Merge pull request #28438 from joshuahansel/peacock-fix

Fixed Peacock setup doc and added doc for THM plugins

framework/doc/content/templates/sqa/app_sll.md.template

@@ -8,8 +8,8 @@ The [!ac](SLL) provides a list of software libraries utilized by {{app}}.
 ## Dependencies id=dependencies
 
 !template field key=dependencies-intro required=False
-The {{app}} application is developed using MOOSE and is based on various modules, as such
-the [!ac](VVR) for {{app}} is dependent upon the following documents.
+The {{app}} application is developed using MOOSE and is based on various modules. As such,
+the [!ac](SLL) for {{app}} is dependent upon the following documents.
 
 !template! field key=dependencies required=False
 !sqa dependencies suffix=sll category={{category}}
@@ -19,7 +19,7 @@ the [!ac](VVR) for {{app}} is dependent upon the following documents.
 ## MOOSE
 
 {{app}} is a MOOSE-based application, [mooseframework.org](https://mooseframework), which is
-summarized in the following abstract [!cite](permann2020moose).
+summarized in the following abstract [!citep](permann2020moose).
 
 > Harnessing modern parallel computing resources to achieve complex multiphysics simulations is a
 > daunting task. The Multiphysics Object Oriented Simulation Environment (MOOSE) aims to enable such

modules/doc/content/application_usage/input_syntax.md

@@ -129,43 +129,116 @@ Other input files may be included using the following syntax:
 !include path/to/input.i
 ```
 
-This can be used in any arbitrary nested context in an input file and included files
-can include other included files. The only requirement is that the included files
+This can be used in any arbitrary nested context in an input file, and included files
+can include other files. The only requirement is that the included files
 must contain a set of syntactically complete blocks or parameters.
 
-## Parameter override syntax
+Functionally, including a file is equivalent to inserting the
+text of the file at the `!include` location. Therefore,
+for example, if the included file uses a value `${somevar}` defined in the parent file
+via `somevar = somval`, then the `!include` statement must occur *after* the
+`somevar` definition.
 
-It may be useful to include a file containing common parameter defaults and just override specific values.
+!alert! warning title=Beware merge-related include ordering issues
+When an included file contains the same block as the parent file, the blocks get
+*merged*. The merge moves the second instance of the block into the first, not
+the first into the second. For example,
 
-This can be done by using the `param := value` override syntax on the parameter taking precedence.
+`file1.i`:
 
-For example, suppose a file named `default_settings.i` is set up defining these parameter defaults:
+```
+[BlockA]
+  param1 = 4
+[]
 
+!include file2.i
 ```
-[section]
-  field_01 = field_01_default
-  field_02 = field_02_default
-  field_03 = field_03_default
+
+`file2.i`:
+
+```
+val3 = 8
+
+[BlockA]
+  param2 = ${val3}
 []
 ```
 
-A problem specific input may then use those default settings and override just one parameter value with:
+This effectively produces the input
 
 ```
-!include default_settings.i
-[section]
-  field_02 := field_02_problem_specific
+[BlockA]
+  param1 = 4
+[]
+
+val3 = 8
+
+[BlockA]
+  param2 = ${val3}
 []
 ```
 
-This would result in the following specification which uses the default settings and overridden parameter:
+and after the merge operation,
 
 ```
-[section]
-  field_01 = field_01_default
-  field_02 = field_02_problem_specific
-  field_03 = field_03_default
+[BlockA]
+  param1 = 4
+  param2 = ${val3}
 []
+
+val3 = 8
 ```
 
-The `param := value` syntax and verbose `param :override= value` syntax are interchangeable.
+This results in an error, since `${val3}` is now used before it is defined.
+Therefore, files must be partitioned with this behavior in mind.
+!alert-end!
+
+!alert warning title=Included input parameters cannot be overridden by default
+Note that parameters from the parent or included files do not override each other by default,
+as this is just interpreted as providing the input parameter twice, resulting in a parsing error.
+To override parameters, you must either use command-line arguments or the explicit
+override syntax defined below.
+
+## Parameter override syntax
+
+Ordinarily, redefining a parameter results in an input error:
+
+```
+param1 = 3
+param1 = 4   # error due to duplicate parameter
+```
+
+However, there is a syntax for explicitly specifying that you would like to
+allow overriding a previously defined value, using either `:=` or `:override=`
+instead of `=`:
+
+```
+param1 = 3
+param1 := 4           # not an error; now param1 is 4 instead of 3
+param1 :override= 5   # now param1 is 5
+```
+
+Note that `:=` and `:override=` are exactly the same; the latter is provided for
+those wanting to make the syntax more visible to a reader of the input file.
+
+As noted with the `!include` syntax above, redefining a parameter with the
+`=` assignment operator results in an duplicate parameter error; the explicit
+override syntax can be used to fix this:
+
+`myinput.i`:
+
+```
+!include base.i
+
+[BlockA]
+  param1 := new_value   # using "=" would result in an error
+[]
+```
+
+`base.i`:
+
+```
+[BlockA]
+  param1 = original_value
+[]
+```

modules/thermal_hydraulics/doc/content/modules/thermal_hydraulics/index.md

@@ -32,6 +32,7 @@ See [this paper](https://joss.theoj.org/papers/10.21105/joss.06146) for an overv
 - [Examples](modules/thermal_hydraulics/examples/index.md)
 - [Test problems](modules/thermal_hydraulics/test_problems/index.md)
 - [Syntax index](modules/thermal_hydraulics/syntax.md)
+- [Utilities](modules/thermal_hydraulics/utilities.md)
 
 !col-end!
 

modules/thermal_hydraulics/doc/content/modules/thermal_hydraulics/utilities.md

@@ -0,0 +1,21 @@
+# THM Utilities
+
+THM provides the following [Peacock](python/peacock.md optional=True) plugins, located in
+`modules/thermal_hydraulics/python/peacock/`, relative to the root MOOSE directory:
+
+- `FluidPropertyInterrogatorPlugin.py`: Computes various fluid properties from a
+  [FluidProperties](syntax/FluidProperties/index.md) object. Note that currently there
+  is no way to specify non-default input parameter values, and those objects
+  requiring input parameters to be specified cannot be used.
+- `UnitConverterPlugin.py`: Converts between various units of measurement.
+- `ModelBuilder/FlowChannelParametersCalculator.py`: Computes cross-sectional
+  area, hydraulic area, and wetted perimeter for various flow channel geometries.
+
+While these are considered Peacock plugins, you do not actually run these within
+an instance of Peacock but instead, run their source files directly with `python`.
+For example,
+
+```
+cd ~/projects/moose/modules/thermal_hydraulics/python/peacock/
+python FluidPropertyInterrogatorPlugin.py
+```

modules/thermal_hydraulics/doc/content/source/components/HSCoupler2D3D.md

@@ -176,7 +176,7 @@ of the 3D surface. This component uses [automatic differentiation](automatic_dif
 to compute the Jacobian matrix contributions used in Newton's method for solving
 the nonlinear system. For performance flexibility, MOOSE has a maximum AD container size,
 which currently by default is set to 53, which means that if a term like the
-2D boundary heat flux $q_z$ depends on more that 53 degrees of freedom, then
+2D boundary heat flux $q_z$ depends on more than 53 degrees of freedom, then
 an error occurs. This maximum AD container size can be increased by configuring
 MOOSE and recompiling your application. See [automatic_differentiation/index.md#max_container_size]
 for more information.

python/doc/content/python/MooseDocs/extensions/bibtex.md

@@ -1,17 +1,37 @@
 # Bibtex Extension
 
-I did some work [!cite](slaughter2014framework)
+The `bibtex` extension allows you to cite references stored in BibTeX database(s).
 
+## Configuration
 
-[!cite](slaughter2014framework, slaughter2015continuous)
+The `bibtex` extension is enabled by default. The only thing necessary for using
+the citation commands is to provide properly-formatted `.bib` file(s) within the
+included content in your configuration file.
 
+## Usage
 
-[!cite](slaughter2014framework, slaughter2015continuous, gaston2015physics)
+Two commands are provided for citing BibTeX references: `!cite` and `!citep`.
+The latter includes parentheses, while the former does not. To cite multiple
+references, they are separated with a comma.
 
+To generate the list of references cited on a page, the `!bibtex bibliography`
+command is used. If it is not used, then it will automatically be placed at the
+bottom of the page.
 
-[!citep](slaughter2014framework)
+See [citation_examples] for examples.
+
+!devel! example caption=Citation examples. id=citation_examples
+[!cite](slaughter2014framework)
+
+[!cite](slaughter2014framework, slaughter2015continuous)
 
+[!cite](slaughter2014framework, slaughter2015continuous, gaston2015physics)
+
+[!citep](slaughter2014framework)
 
 [!citep](slaughter2014framework, slaughter2015continuous)
 
 !bibtex bibliography
+
+Some text after the references.
+!devel-end!

python/doc/content/python/peacock.md

@@ -1,96 +1,52 @@
 # Peacock
 
 !style! halign=left
-Peacock is a graphical front end for the MOOSE input file syntax. Peacock allows the user to build or modify an input file, execute the application, and view the results all within one package.
+Peacock is a graphical front end for the MOOSE input file syntax. Peacock allows the user to build or modify an input file, execute an application, and view the results, all within one package.
 !style-end!
 
-
-## Conda Packages
-
-!include installation/install_peacock.md
-
 ## Environment
 
-!style! halign=left
-Adding Peacock to your PATH will allow you to launch it from your application or `tests` directory. Peacock will search up through the filesystem directory tree until it finds your application, obviating the need to specify your application as an argument, and simplifying Peacock usage.
-!style-end!
-
-First, we need to discover the absolute path to `peacock` on your machine. Assuming that your MOOSE
-repository sits in the default location of `~/projects/moose`, enter the following directory and run
-`pwd`. Example:
-
-```bash
-cd ~/projects/moose/python/peacock
-pwd
-/home/you/projects/moose/python/peacock
-```
-
-Whatever returns, this is your path to `peacock`.
-
-Next, we need to know what shell you are operating in to determine what profile to modify.
-Run `echo $0` to do so.
-Example:
-
-```bash
-echo $0
--zsh
-```
-
-Where `-zsh` is our example result. The following table describes which profile file one must edit,
-as well as how to assign a value to a variable in that shell:
+To allow the shell to find the Peacock executable, you must add its directory
+to your `PATH` environment variable. Within the MOOSE directory, the Peacock
+executable is located in `python/peacock/`. If for example your MOOSE directory
+is installed at `~/projects/moose`, then you would add `~/projects/moose/python/peacock`
+to your `PATH`. To avoid needing to manually modify `PATH` for each terminal
+session, it is recommended that you do this in your shell profile file.
+The shell profile file name and the syntax to modify environment variables
+differ by shell, so consult shell documentation for proper usage.
+To know which shell you are using, use `echo $SHELL`. The following table
+gives the profile file name and `PATH` modification syntax for each shell:
 
 | Shell | Profile Location | Command |
 | :- | :- | :- |
-| bash | `~/.bash_profile` | `export PATH=pwd:$PATH` |
-| zsh | `~/.zshrc` | `export PATH=pwd:$PATH` |
-| sh | `~/.profile` | `export PATH=pwd:$PATH` |
-| csh | `~/.cshrc` | `setenv PATH pwd:$PATH` |
-| tcsh | `~/.tcshrc` | `setenv PATH pwd:$PATH` |
-
-Replace occurrences of `pwd` in the above table with the result you received in the previous step
-as you apply the following instructions:
-
-!alert! warning title=Dangerous Syntax Below
-Use single quotes: ( `'` ). We *literally* want to write "`$PATH`" in the below example, and not the
-value of `$PATH`.
-
-Use two greater thans: ( `>>` ). Two greater thans append information to a file, while a single
-greater than ( `>` ) overwrites the file entirely.
-
-If you do not trust yourself, create a backup of this file using `cp` (copy) before you begin.
-!alert-end!
-
-`zsh` Example:
-
-```bash
-echo 'export PATH=/home/you/projects/moose/python/peacock:$PATH' >> ~/.zshrc
-```
-
-!alert! tip
-A wealth of information on how shell profiles work is available on the internet. Search for
-"`<your shell> profile`" for more information.
-!alert-end!
+| bash | `~/.bash_profile` | `export PATH=~/projects/moose/python/peacock:$PATH` |
+| zsh | `~/.zshrc` | `export PATH=~/projects/moose/python/peacock:$PATH` |
+| sh | `~/.profile` | `export PATH=~/projects/moose/python/peacock:$PATH` |
+| csh | `~/.cshrc` | `setenv PATH ~/projects/moose/python/peacock:$PATH` |
+| tcsh | `~/.tcshrc` | `setenv PATH ~/projects/moose/python/peacock:$PATH` |
 
 ## Usage
 
-!style! halign=left
-The following examples assume you have added Peacock to your PATH. General usage is as follows:
-!style-end!
+After you have added the Peacock directory to your `PATH` as described above, you
+can invoke Peacock in any directory below the directory containing your application
+executable. For example, if your project is located at `~/projects/myapp`, and you
+built the binary `~/projects/myapp/myapp-opt`, you can run Peacock in the
+directory `~/projects/myapp/test/tests/mytest/`, and Peacock will be able to
+find your application:
 
 ```bash
-cd ~/projects/<your application directory>
+cd ~/projects/myapp/test/tests/mytest/
 peacock
 ```
 
-Peacock will search upwards from the current directory, and attempt to find your application's executable. Syntax is gathered, and you are presented with input syntax specific to your application.
+This will load Peacock without any input file (which you can load afterward);
+alternatively, you can start Peacock with an input file directly from the
+command line:
 
 ```bash
-cd ~/projects/<your application directory>/<your test directory>
 peacock -i your_input_file.i
 ```
 
-Peacock will attempt to find your application's executable, and then the Input file tab will be populated with information from 'your_input_file.i'.
-
 !alert! warning
 Do not use `sudo` when running Peacock.
 !alert-end!