Addressed reviewers comments

Author: zhieejhia93

doc/source/dev/workbench.rst

@@ -0,0 +1,103 @@
+.. devguide_workbench:
+
+Adding Application to Workbench
+-------------------------------
+
+If you wish to use WATTS on the NEAMS Workbench with a code
+that is not already available, adding the code can be done quite easily.
+
+First, you have to develop a plugin for the code and add it to WATTS following
+the steps described previously. Once the plugin is available, you can then add it
+to `watts_ui.py`.
+
+In the `run_direct()` function, you will need to add an `elif` statement as follows,
+
+.. code-block::
+
+    elif plugin['code'].upper() == '<name_of_new_code>':
+        app_plugin = watts.name_of_new_plugin(
+            template_file=plugin['template'],
+            executable=exec,
+            extra_inputs=plugin['extra_inputs'],
+            extra_template_inputs=plugin['extra_template_inputs'],
+            show_stdout=plugin['show_stdout'],
+            show_stderr=plugin['show_stderr'])
+
+Note tha additional steps might be necessary here depending on the code that
+is being added.
+
+If the plugin is developed to be similar to the other plugins on WATTS,
+no other changes are necessary to `watts_ui.py`. Otherwise, the developer
+is responsible for making sure that `watt_ui.py` can read the results
+produced by the plugin. Within `run_direct()`, the results from the plugin
+should be extracted and saved to `watts_params` as individual entries. This
+is required for the coupling and data-transfer between different codes.
+
+Next, the `watts.sch` file needs to be updated. The name of the new code needs
+to be added to the `code` block as follows::
+
+    watts{
+        plugins{
+            plugin{
+                code{
+                    Description = "[Required] All - Name of application"
+                    ...
+                    ValEnums=[PyARC RELAP5 ... <name_of_new_code>]
+                }
+            }
+        }
+    }
+
+Note that the name used for the new code used here must match that used in
+`watts_ui.py`.
+
+Adding new plugin options
++++++++++++++++++++++++++
+
+Any additional options needed by the plugin can be added under the `plugin`
+block as follows::
+
+     watts{
+        plugins{
+            plugin{
+               additional_plugin_option{
+                    Description = "[optional] New_code - Description of the new option"
+                    MinOccurs=0
+                    MaxOccurs=1
+                    ValType=String
+                    InputTmpl="plugin.additional_plugin_option"
+                }
+            }
+        }
+    }
+
+Note that `MinOccurs` and `MaxOccurs` represent the minimum and maximum occurences of
+this option, `ValType` is the input type of the new option, and `InputTmpl` is the
+template file for the new option located in the `etc/templates` directory. Template
+file is optional but highly recommended as it provides a template or example to other users.
+
+If new plugin options are added, the `create_plugins()` function in `watts_ui.py` must
+be updated. The function essentially creates a nested Python dictionary that contains one
+or more individual dictionaries where each individual dictionary stores the information
+of each plugin. The function utilizes a series of `if` statements to decide what information
+should be stored for each plugin.
+
+If the input of the new option is a string, the new option can be added as follows ::
+
+    if plg.new_option_name is not None:
+            nested_plugins['new_option_name'] = str(
+                plg.new_option_name.value).strip('\"')
+
+If the input is a list ::
+
+    if plg.new_option_name is not None:
+        nested_plugins['new_option_name'] = convert_to_list(plg.new_option_name)
+
+If the input is a bool ::
+
+    nested_plugins['new_option_name'] = False
+
+    if plg.new_option_name is not None and str(plg.new_option_name.value).capitalize() == 'True':
+        nested_plugins['new_option_name'] = True
+
+Similar approach can be used for plugin options of different input types.

doc/source/user/workbench.rst

@@ -10,16 +10,16 @@ and visualization for integrated codes. Instructions on how to download and inst
 Workbench can be found on the Workbench
 `Gitlab repository <https://code.ornl.gov/neams-workbench/downloads>`.
 
-To set up WATTS in the Workbench environment, user needs to first provide the path to
-where Workbench is installed in `workbench.sh` under the `scripts` directory. User can
+To set up WATTS in the Workbench environment, you first need to first provide the path to
+where Workbench is installed in `workbench.sh` under the `scripts` directory. You can
 then run `setup_conda_wb.sh` under the same directory to set up WATTS within
 the Workbench environment.
 
 Optional: To install OpenMC in the Workbench environemnt, run `setup_openmc.sh`.
 
 To finish setting up WATTS, open Workbench and go to the `File` tab at the top-left corner
 then select `Configurations` from the drop menu. In the `Application configurations`
-window, click `Add` on the top most row then select `WATTS` from the pop-up window.
+window, click `Add` on the top most row then select `Watts` from the pop-up window.
 In the list of `Application Options`, input the path of `watts_ui.py` to `Executable`.
 The file should exist by default in `/watts/src/watt_ui/`. Next, click `Load Grammar`.
 Click `OK` to complete the setup.
@@ -35,9 +35,7 @@ file can also be dragged and dropped to the Workbench window.
 
 The WATTS input file utilizes a hierarchical block-based system where a block
 is defined with opening and closing curly braces `{ }`. A `watts` block is first
-created within which other blocks and variables can be defined. Within the `watts`
-block, `workflow_dir` needs to be defined as the path to the working directory
-(where all templates and extra files are located).
+created within which other blocks and variables can be defined.
 
 Plugins
 ~~~~~~~
@@ -53,7 +51,7 @@ The `plugins` block is required. Within the `plugins` blocks are
             exec_dir = SAM_DIR
             exec_name = "sam-opt"
             extra_inputs=["file1", "file2", "file3"]
-            extra_templat_inputs=["template1", "template2", "template3"]
+            extra_template_inputs=["template1", "template2", "template3"]
             show_stderr = False
             show_stdout = False
         }
@@ -77,7 +75,7 @@ in the snippet above. For each sub-block the basic inputs are::
      `show_stdout` : Option to display output
      `exec_dir` : Environment variable that points to the directory in which the application's executable is stored
      `extra_inputs` : Additional non-templated input files
-     `extra_templateinputs` : Additional tempalted input files
+     `extra_template_inputs` : Additional tempalted input files
      `exec_name` : Name of the executable
      `executable` : Path to the executable
 
@@ -86,13 +84,30 @@ ONLY `executable`. Additionally, there are  application-specific inputs
 that can be provided to the plugins such as::
 
     `extra_args` (multiple apps) : Extra arguments to applications
+    'transfer_params' (multiple apps) : Output to transfer between applications for multi-apps run
     `plotfl_to_csv` (RELAP5) : Option to convert `plotfl` file to `csv` file
     `conv_channel` (SAS) : Path to `CHANNELtoCSV.x`
     `conv_primar4` (SAS) : Path to `PRIMAR4toCSV.x`
     `auto_link_files` (Dakota) : List of files for Dakota to link automatically
     `scores` (OpenMC) : List of filters for tallies
     `score_names` (OpenMC) : List of user-given names for tally filters
 
+Currently all applications/codes already integrated to WATTS can be run on Workbench, these include
+PyARC, OpenMC, SERPENT, ABCE, MCNP, MOOSE, SAS, Dakota, Serpent, and RELAP5.
+
+For OpenMC, multiple `scores` can be provided at once. If provided, the number of `score_names` must be the
+same as the number of `scores`. For instance, ::
+
+    scores = ["elastic", "nu-fission"]
+    score_names = ["total_elastic_scatter_rate", "total_fission_neutron_prod"]
+
+and there are N tallies where N > 1, then the outputs of the run will be named as::
+
+    total_elastic_scatter_rate_1, total_elastic_scatter_rate_2, ..., total_elastic_scatter_rate_N
+    total_fission_neutron_prod_1, total_fission_neutron_prod_2, ..., total_fission_neutron_prod_N
+
+If `score_names` is not provided, `scores` will be used as the base name for the outputs.
+
 Workflow level
 ~~~~~~~~~~~~~~
 
@@ -101,8 +116,21 @@ by the `plugin` keyword::
 
     plugin = ID1
 
-where 'ID1' is the ID of the plugin provided in the `plugins` block. The
-`variable` sub-block is where the values of the templated variables are
+where 'ID1' is the ID of the plugin provided in the `plugins` block. When performing
+a multi-app run where more than one plugins are used, the sequence of the run is
+determined by the order of plugins. For example, when the order of the plugins is::
+
+    plugin = ID1
+    plugin = ID2
+
+Workbench will run ID1 first then ID2. On the other than, when the order is ::
+
+    plugin = ID2
+    plugin = ID1
+
+Workbench will instead run ID1 first then ID2.
+
+The`variable` sub-block is where the values of the templated variables are
 specified, as shown below::
 
     variables{
@@ -146,9 +174,17 @@ Parametric study
 To perform parametric study, a `parametric` block needs to be added to
 the `workflow_level1` block as follows::
 
-    parametric{
+    workflow_level1{
+        plugin = ID1
+        variables{
+            param(He_inlet_temp) {value = 873.15}
+            param(He_outlet_temp) {value = 1023.15}
+            ...
+        }
+        parametric{
         changing_params = "heat_source"
         changing_values = [0, 1e5, 2e5, 3e5]
+        }
     }
 
 where `changing_params` is the parameter whose values are varied and
@@ -160,22 +196,32 @@ Picard iteration
 To perform Picard iteration, the `iteration` block needs to be added
 to the `workflow_level1` block::
 
-    iteration{
-        plugin_main = ID1
-        plugin_sub = ID2
-        nmax = 10
-        convergence_params = "keff"
-        convergence_criteria = 0.0001
-        to_sub_params = ["avg_Tf_1" "avg_Tf_2" "avg_Tf_3" "avg_Tf_4" "avg_Tf_5"]
-        to_main_params = ["Init_P_1" "Init_P_2" "Init_P_3" "Init_P_4" "Init_P_5"]
+    workflow_level1{
+        plugin = ID1
+        variables{
+            param(He_inlet_temp) {value = 873.15}
+            param(He_outlet_temp) {value = 1023.15}
+            ...
+        }
+        iteration{
+            plugin = ID2
+            nmax = 10
+            convergence_params = "keff"
+            convergence_criteria = 0.0001
+            to_sub_params = ["avg_Tf_1" "avg_Tf_2" "avg_Tf_3" "avg_Tf_4" "avg_Tf_5"]
+            to_main_params = ["Init_P_1" "Init_P_2" "Init_P_3" "Init_P_4" "Init_P_5"]
+        }
     }
 
-where `plugin_main` and `plugin_sub` are the plugin IDs of the two applications,
-`nmax` is the maximum number of iterations, `convergence_params` is the parameter
-used for evaluating convergence, `convergence_criteria` is the tolerance for
+`plugin` in the `iteration` block is the plugin ID (ID2 in this example) of the
+application that will be used along with the the first plugin (ID1 in this example)
+to perform iteration. `nmax` is the maximum number of iterations,
+`convergence_params` is the parameter used for evaluating convergence,
+`convergence_criteria` is the tolerance for
 convergence, `to_sub_params` and `to_main_params` are lists of parameters whose
 values are iterated between the two applications where they each must have at least
 one parameter. Note that the parameter supplied to `convergence_params` must be
 an output from the second plugin. For instance, in the above example, "keff" is
-an output produced by the plugin of "ID2". The same also applies for `to_sub_params`
-and `to_main_params`.
+an output produced by the plugin of "ID2". Note that the choice of "keff" in
+this example is arbitrary and `convergence_params` should be chosen according to
+the applications used and the objective of iteration runs.

examples/1App_OpenMC_VHTR/README.md

@@ -18,4 +18,4 @@ This example provides a demonstration on how to use WATTS to perform a single SA
 
 - [__watts_exec.py__](watts_exec.py): WATTS workflow for this example. This is the file to execute to run the problem described above.
 - [__openmc_template__](openmc_template.py): OpenMC templated model.
-- [__watts_comprehensive.son__](watts_comprehensive.son): Workbench input file for this example.
+- [__watts_wb.son__](watts_wb.son): Workbench input file for this example.

…1App_OpenMC_VHTR/watts_comprehensive.son examples/1App_OpenMC_VHTR/watts_wb.sonexamples/1App_OpenMC_VHTR/watts_comprehensive.son renamed to examples/1App_OpenMC_VHTR/watts_wb.son examples/1App_OpenMC_VHTR/watts_comprehensive.son renamed to examples/1App_OpenMC_VHTR/watts_wb.son

@@ -10,7 +10,7 @@ watts{
     }
 
     workflow_level1{
-        plugin = ID1
+        plugin = ID1  
         variables{
             param(ax_ref) {value = 2.0}
             param(num_cool_pins) {value = 24}

examples/1App_PyARC_UnitCell/README.md

@@ -18,4 +18,4 @@ This example provides a demonstration on how to use WATTS to perform a single Py
 - [__watts_exec.py__](watts_exec.py): WATTS workflow for this example. This is the file to execute to run the problem described above.
 - [__pyarc_template__](pyarc_template): PyARC templated input file.
 - [__lumped.son__](lumped.son): SON file referenced in PyARC input with description of lumped fission products.
-- [__watts_comprehensive.son__](watts_comprehensive.son): Workbench input file for this example.
+- [__watts_wb.son__](watts_wb.son): Workbench input file for this example.

…p_PyARC_UnitCell/watts_comprehensive.son examples/1App_PyARC_UnitCell/watts_wb.sonexamples/1App_PyARC_UnitCell/watts_comprehensive.son renamed to examples/1App_PyARC_UnitCell/watts_wb.son examples/1App_PyARC_UnitCell/watts_comprehensive.son renamed to examples/1App_PyARC_UnitCell/watts_wb.son

@@ -17,4 +17,4 @@ This example provides a demonstration on how to use WATTS to run RELAP5-3D.
 
 - [__watts_exec.py__](watts_exec.py): This is the file to execute to run the problem described above.
 - [__relap5_template__](relap5_template): Templated RELAP5-3D input.
-- [__watts_comprehensive.son__](watts_comprehensive.son): Workbench input file for this example.
+- [__watts_wb.son__](watts_wb.son): Workbench input file for this example.

examples/1App_RELAP5_SingleChannel/README.md

@@ -18,4 +18,4 @@ This example provides a demonstration on how to use WATTS to perform a single SA
 
 - [__watts_exec.py__](watts_exec.py): WATTS workflow for this example. This is the file to execute to run the problem described above.
 - [__sam_template__](sam_template): SAM templated input file.
-- [__watts_comprehensive.son__](watts_comprehensive.son): Workbench input file for this example.
+- [__watts_wb__.son__](watts_wb.son): Workbench input file for this example.