Updating Doc String: Address Issue #258 #263

csdechant · 2024-11-13T18:58:32Z

This PR updates the Zapdos header files to include previously missing Doc String, which will close Issue #258. This PR also includes minor edits that remove previously unused parameters in Zapdos objects.

Updating the docstings in Zapdos is in progress with the following objects completed: - Actions - Auxkernels - bcs - constraits - indicators - interfacekernels - postprocessors - userobjects Also minor edits of head and body files were done, which involved removing out dated parameters

csdechant · 2024-11-13T19:57:28Z

The PR for updating Zapdos Doc Sting is ready for review. @gsgall is the primary reviewer, but I included @cticenhour in case he would like to look at this PR too.

moosebuild · 2024-11-13T20:16:33Z

Job Documentation, step Sync to remote on c4b976a wanted to post the following:

View the site here

This comment will be updated on new commits.

gsgall

Overall looks good, a few typos and some missing documentation, and lack of detail in comments but thank you for doing this @csdechant.

gsgall · 2024-12-12T20:55:07Z

include/actions/AddDriftDiffusionAction.h

+  /*
+   *  Helper function that supplies the Kernels for drift-diffusion for the electrons,
+   *  energy independent charged particles, neutral particles, and
+   *  electron mean energy depending


This sentence seems incomplete. Is this suppose to be mean electron energy dependent particles?

It should read "electron mean energy density". Will edit.

This has been addressed in 4b5a202

gsgall · 2024-12-12T20:57:02Z

include/actions/AddDriftDiffusionAction.h

  virtual void addADKernels(const std::string & name,
                            const std::string & potential_name,
                            const bool & Using_offset,
                            const bool & charged,
                            const bool & energy);
+
+  /// Helper function that supplies the Aux kernels to convert scaled position units


What are the scaled position units in this case referring to? Is this for when the user is using a non-dimensioqnalized spatial domain?

That is correct. For clarity, I can add edit to:
/// Helper function that supplies the Aux kernels to convert scaled position units when parameter position_units is set to non-unity

This has been addressed in 4b5a202

include/actions/AddPeriodicControllers.h

gsgall · 2024-12-12T21:01:54Z

include/actions/AddPeriodicRelativeNodalDifference.h

  Real _period;
+  /// The number of cycles to calculate the difference


This description is unclear to me. Can you add some more detail here?

Sure, a probably better description is "The number of cycles PeriodicRelativeNodalDifference is active"

This has been addressed in 4b5a202

include/auxkernels/AbsValueAux.h

include/materials/GasBase.h

include/userobjects/ProvideMobility.h

gsgall · 2024-12-12T21:57:48Z

src/actions/AddPeriodicRelativeNodalDifference.C

@@ -56,13 +56,12 @@ AddPeriodicRelativeNodalDifference::validParams()
  params.addParam<Real>(
      "starting_cycle", 0.0, "The number of the cycles before starting the difference calculation");
  params.addRequiredParam<Real>("cycle_frequency", "The cycle's frequency in Hz");
-  params.addParam<Real>(
-      "num_cycles", 2000.0, "The number of cycles to calculation the difference for.");
+  params.addParam<Real>("num_cycles", 2000.0, "The number of cycles to calculate the difference.");


This is a bit unclear to me. Does this mean the number of cycles for which the difference between the current and previous cycle is calculated. Or is this something like the number of cycles between cycles that are being compared?

It is the former description. I can edit it to simply say "The number of cycles this object is active".

This has been addressed in 4b5a202

src/interfacekernels/InterfaceAdvection.C

gsgall · 2024-12-12T22:00:47Z

include/actions/AddDriftDiffusionAction.h

+
+  /*
+   *  Helper function that supplies the Kernels for drift-diffusion for the electrons,
+   *  energy independent charged particles, neutral particles, and
+   *  electron mean energy depending
+   */
  virtual void addADKernels(const std::string & name,
                            const std::string & potential_name,
                            const bool & Using_offset,
                            const bool & charged,
                            const bool & energy);
+
+  /// Helper function that supplies the Aux kernels to convert scaled position units
  virtual void addPosition(const std::string & position_name, const int & component);

+  /// Helper function that supplies the Aux kernels to convert densities from log form
  virtual void addDensityLog(const std::string & particle_name);
+
+  /// Helper function that supplies the Aux kernels for current
  virtual void addCurrent(const std::string & particle_name, const std::string & potential_name);
+
+  /// Helper function that supplies the Aux kernels for the electric field
  virtual void addEfield(const std::string & Efield_name,
                         const std::string & potential_name,
                         const int & component);


@cticenhour correct me if I am wrong but I believe the MOOSE standard should be to have a description for each of the parameters of every custom function. In the style of

@param name description

This comment is also applicable for the rest of the actions that do not have the parameter doc strings for their internal functions.

This is true for most MOOSE header files I have seen and should add them regardless for better documentation. This was an oversight and will edit.

This has been addressed in 4b5a202

Co-authored-by: Grayson Gall <[email protected]>

csdechant · 2024-12-20T20:51:54Z

@gsgall everything should be addressed now, and this PR is ready for a re-review.

gsgall · 2025-01-09T14:40:35Z

@gsgall everything should be addressed now, and this PR is ready for a re-review.

@csdechant @cticenhour Is there something weird going on with the civit build. I would like to review the website but when I try to use the most recent link to the site preview I am getting a 404 error.

cticenhour · 2025-01-09T17:01:05Z

@gsgall It's because the website was built almost 3 weeks ago. CIVET regularly cleans out old PR websites on the order of weekly. So @csdechant will need to push again to trigger a new one.

csdechant · 2025-01-09T20:46:39Z

@gsgall just push a no edit commit (using the git commit --amend --no-edit command). After this build, a review version of the website should be available.

csdechant · 2025-01-15T16:23:22Z

@gsgall the git commit --amend --no-edit messed with the commit history (I must have not done a proper git fetch while working between two machines). The problem is fixed and the commit history is restored, so commits like 4b5a202 can be viewed again.

gsgall · 2025-01-16T00:26:08Z

@gsgall the git commit --amend --no-edit messed with the commit history (I must have not done a proper git fetch while working between two machines). The problem is fixed and the commit history is restored, so commits like 4b5a202 can be viewed again.

Thank you @csdechant! I am working on the review now.

gsgall

Thank you @csdechant there are only a few small types and grammar issues I found this time around

include/actions/AddPeriodicControllers.h

include/actions/AddPeriodicRelativeNodalDifference.h

include/postprocessors/MultiPeriodAverager.h

include/postprocessors/PeriodicTimeIntegratedPostprocessor.h

gsgall · 2025-01-16T01:03:16Z

include/userobjects/CurrentDensityShapeSideUserObject.h

+  /**
+   * This is called before execute so you can reset any internal data.
+   */
  virtual void initialize();
+  /**
+   * Called on every "object" (like every element or node).
+   * In this case, it is called at every quadrature point on every element.
+   */
  virtual void execute();
+
+  /**
+   * Implement this function to compute Jacobian terms for this UserObject. The
+   * shape function index _j and its corrsponding global DOF index _j_global
+   * will be provided.
+   */
  virtual void executeJacobian(unsigned int jvar);
+  /**
+   * Called _once_ after execute has been called all all "objects".
+   */
  virtual void finalize();
+  /**
+   * Called when using threading.  You need to combine the data from "y"
+   * into _this_ object.
+   */


These descriptions seem like they are almost the same as the ones for base object. They should probably be more descriptive of this objects behaviour.

@gsgall which base object are you looking at? I looked at ShapeSideUserObject and ShapeUserObject, and I didn't see a description for this functions. If these are already defined somewhere in the hierarchy, and I don't think they need to be redefined here.

The base object I am referencing is the UserObject. These descriptions just seem to echo what a general user object would do with these methods but there are object specific implementations for all of them. I would be my preference that some description which is specific to what this object does are used rather than just describing what the general use of these methods is.

If this is not the standard in other MOOSE applications I am fine with these descriptions.

gsgall · 2025-01-16T01:04:32Z

include/userobjects/ProvideMobility.h

+  /**
+   * This is called before execute so you can reset any internal data.
+   */
  virtual void initialize();
-
+  /**
+   * Called on every "object" (like every element or node).
+   * In this case, it is called at every quadrature point on every element.
+   */
  virtual void execute();
-
+  /**
+   * Called _once_ after execute has been called on all "objects".
+   */
  virtual void finalize();


Similar to my comment on the other user object. This is really generic and doesn't really say anything about this specific object.

I believe these docstring comments will be inherited by UserObject.h, so I can remove them. As for why the comments are generic, it is because these are generic functions and are not custom made for the specific object (i.e. all userobjects need an initialize, execute, and finalize function).

src/interfacekernels/InterfaceAdvection.C

Co-authored-by: Grayson Gall <[email protected]>

moosebuild · 2025-01-16T16:16:59Z

Job Precheck, step Clang format on dab4f0f wanted to post the following:

Your code requires style changes.

A patch was auto generated and copied here
You can directly apply the patch by running, in the top level of your repository:

curl -s https://mooseframework.inl.gov/zapdos/docs/PRs/263/clang_format/style.patch | git apply -v

Alternatively, with your repository up to date and in the top level of your repository:

git clang-format 9720bf2cc323e22d551ac23549cf7f9c2f944b91

csdechant

@gsgall All grammar fixes should be applied now. As for the comments involving docstrings, if a generic function is already defined somewhere in the hierarchy somewhere, I don't believe it needs to be redefined since they are not object specific (e.g. functions such as initialize, execute, finalize). I added those comments because I must of overlooked their inclusion elsewhere. If you have an objection removing those comments, please let me know.

csdechant · 2025-01-16T15:17:51Z

include/materials/GasElectronMoments.h

  MaterialProperty<Real> & _Avogadro;
-  MaterialProperty<Real> & _vthermal_em;
-  MaterialProperty<Real> & _vthermal_ip;
-  MaterialProperty<Real> & _iz_coeff_efield_a;
-  MaterialProperty<Real> & _iz_coeff_efield_b;
-  MaterialProperty<Real> & _iz_coeff_efield_c;
-  MaterialProperty<Real> & _iz_coeff_energy_a;
-  MaterialProperty<Real> & _iz_coeff_energy_b;
-  MaterialProperty<Real> & _iz_coeff_energy_c;
+  /// Avogadro's number (reduced significant figures)
  MaterialProperty<Real> & _N_A;
-  MaterialProperty<Real> & _el_coeff_energy_a;
-  MaterialProperty<Real> & _el_coeff_energy_b;
-  MaterialProperty<Real> & _el_coeff_energy_c;
+
+  /// Charge sign of electrons


I am not sure, to be honest. This object is a more general version of Gas, which also has two different versions of Avagadro's number. I made a comment in the PR #265 that will should make a issues regarding re-examining the material objects. I made this into an issue, Issue #270

csdechant · 2025-01-16T16:01:31Z

include/userobjects/CurrentDensityShapeSideUserObject.h

+  /**
+   * This is called before execute so you can reset any internal data.
+   */
  virtual void initialize();
+  /**
+   * Called on every "object" (like every element or node).
+   * In this case, it is called at every quadrature point on every element.
+   */
  virtual void execute();
+
+  /**
+   * Implement this function to compute Jacobian terms for this UserObject. The
+   * shape function index _j and its corrsponding global DOF index _j_global
+   * will be provided.
+   */
  virtual void executeJacobian(unsigned int jvar);
+  /**
+   * Called _once_ after execute has been called all all "objects".
+   */
  virtual void finalize();
+  /**
+   * Called when using threading.  You need to combine the data from "y"
+   * into _this_ object.
+   */


@gsgall which base object are you looking at? I looked at ShapeSideUserObject and ShapeUserObject, and I didn't see a description for this functions. If these are already defined somewhere in the hierarchy, and I don't think they need to be redefined here.

csdechant · 2025-01-16T16:13:50Z

include/userobjects/ProvideMobility.h

+  /**
+   * This is called before execute so you can reset any internal data.
+   */
  virtual void initialize();
-
+  /**
+   * Called on every "object" (like every element or node).
+   * In this case, it is called at every quadrature point on every element.
+   */
  virtual void execute();
-
+  /**
+   * Called _once_ after execute has been called on all "objects".
+   */
  virtual void finalize();


I believe these docstring comments will be inherited by UserObject.h, so I can remove them. As for why the comments are generic, it is because these are generic functions and are not custom made for the specific object (i.e. all userobjects need an initialize, execute, and finalize function).

csdechant added 4 commits November 12, 2024 17:07

Adding remaining docstrings which closes shannon-lab#258

09f8929

Addressing trailing whitespace

c1357a1

Addressing Clang formatting

52b53b9

csdechant requested review from gsgall and cticenhour November 13, 2024 19:55

csdechant mentioned this pull request Nov 26, 2024

Merging Casey's Thesis Work #265

Open

gsgall requested changes Dec 12, 2024

View reviewed changes

csdechant and others added 4 commits December 20, 2024 09:57

Apply suggestions from code review

6a94f37

Co-authored-by: Grayson Gall <[email protected]>

Apply Clang Format

4f7fc5b

Addressing edits in docstrings

4b5a202

Addressing whitespace

fb79626

csdechant force-pushed the docstring branch from fb79626 to 8092391 Compare January 9, 2025 20:43

csdechant force-pushed the docstring branch from 8092391 to fb79626 Compare January 15, 2025 16:18

gsgall requested changes Jan 16, 2025

View reviewed changes

Apply suggestions from code review

dab4f0f

Co-authored-by: Grayson Gall <[email protected]>

csdechant commented Jan 16, 2025

View reviewed changes

Applying Clang-format

c4b976a

		Real _period;
		/// The number of cycles to calculate the difference

Updating Doc String: Address Issue #258 #263

Are you sure you want to change the base?

Updating Doc String: Address Issue #258 #263

Conversation

csdechant commented Nov 13, 2024

csdechant commented Nov 13, 2024 • edited Loading

moosebuild commented Nov 13, 2024 • edited Loading

gsgall left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csdechant Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csdechant commented Dec 20, 2024

gsgall commented Jan 9, 2025

cticenhour commented Jan 9, 2025 • edited Loading

csdechant commented Jan 9, 2025

csdechant commented Jan 15, 2025

gsgall commented Jan 16, 2025

gsgall left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

moosebuild commented Jan 16, 2025

csdechant left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csdechant commented Nov 13, 2024 •

edited

Loading

moosebuild commented Nov 13, 2024 •

edited

Loading

csdechant Dec 20, 2024 •

edited

Loading

cticenhour commented Jan 9, 2025 •

edited

Loading