Merge remote-tracking branch 'upstream/devel' into devel

doc/content/getting_started/eigenvalue.md

@@ -2,9 +2,9 @@
 
 The input files associated with this tutorial are
 [moltres/tutorial/eigenvalue/nts.i](https://github.com/arfc/moltres/blob/devel/tutorial/eigenvalue/nts.i) and
-[moltres/tutorial/eigenvalue/nts-action.i](https://github.com/arfc/moltres/blob/devel/tutorial/eigenvalue/nts-action.i)
+[moltres/tutorial/eigenvalue/nts-action.i](https://github.com/arfc/moltres/blob/devel/tutorial/eigenvalue/nts-action.i).
 Refer to [Tutorial 2a](getting_started/input_syntax.md) for an introduction on the input file
-syntax and an in-depth description of every input parameter.
+syntax and in-depth descriptions of every input parameter.
 
 As mentioned in Tutorial 2a, this example involves a simple 2-D axisymmetric core model of the
 Molten Salt Reactor Experiment (MSRE) that was developed at Oak Ridge National Laboratory. The

doc/content/getting_started/moltres_xs.md

@@ -1,3 +1,106 @@
 # Group Constant File Generation With `moltres_xs.py`
 
-TODO: Add content
+## Example problem: Godiva Sphere
+
+In this tutorial, we demonstrate how to use OpenMC to generate group constants for Moltres using
+`moltres_xs.py`.
+
+The relevant files for this tutorial may be found in the
+[`godiva`](https://github.com/arfc/moltres/tree/devel/tutorial/) tutorial directory.
+To run these input files and subsequent group constant generation scripts, the user must install
+[OpenMC](https://github.com/openmc-dev/openmc/) version 0.13.2 or later.
+
+### Step 1: Generating Group Constants with OpenMC
+
+In this directory, there are 2 OpenMC input files for 900K and 1200K simulations:
+`godiva_openmc_900.py` and `godiva_openmc_1200.py`. Unlike Scale or Serpent, OpenMC does not have
+a notion of branches to generate group constants for different temperatures and burnups. Thus,
+separate input files for different temperatures is required.
+
+The user must include the `openmc_xs.generate_openmc_tallies_xml()` function in the OpenMC input
+file to generate a `domain_dict`. The function sets up the OpenMC tallies required for the group
+constant generation. This is necessary because unlike Serpent, OpenMC does not generate all the
+group constant data with any simulation, the user must specify what they want. The user may define
+domains as either openmc.Material or openmc.Cell.
+
+For this tutorial, we also provide the OpenMC output files obtained after running the input files:
+`statepoint_900_openmc.100.h5`, `statepoint_1200_openmc.100.h5`, `summary_900.h5`, and
+`summary_1200.h5`. Each OpenMC simulation generates a statepoint and summary file. Both output
+files are required for the group constant generation.
+
+### Step 2: Parsing OpenMC Output Files with moltres_xs.py
+
+`godiva_openmc.inp` is the input file that informs `moltres_xs.py` how to parse the various OpenMC
+output files to generate Moltres group constants. The structure of the input file is as follows:
+
+```
+[TITLE]
+  *name of output json file*
+
+[MAT]
+  *number of materials*
+  *names of materials listed*
+
+[BRANCH]
+  *number of branches*
+  *material name* *temperature* *file index* *burnup index* *universe index* *branch index*
+  
+[FILES]
+  *number of files*
+  *statepoint file name* *openmc* *openmc input file* *summary file*
+```
+
+For OpenMC, since we do not utilize the burnup and branch indexes, users must indicate both index
+values as "1" so that `moltres_xs.py` correctly parses the input file. For OpenMC, we also add
+additional openmc input files and summary files. The universe index must correspond to the material
+or cell id defined in the OpenMC input file.
+
+To generate the Moltres group constants, the user runs:
+```
+python ../../python/moltres_xs.py godiva_openmc.inp
+```
+This will output `godiva_openmc.json` containing the Moltres group constants. An example of this
+output file can be found in `../../python/test/gold/godiva.json`.
+
+## OpenMC Group Constant Generation 
+
+This table outlines the OpenMC methods used by `moltres_xs.py` to calculate the group constants for Moltres.
+
+| Group Constant | Description | OpenMC Tally Used | Units |
+| --- | --- | --- | --- |
+| BETA_EFF | Delayed neutron fraction | mgxs.Beta() | - |
+| CHI_T | Fission spectrum (total) | mgxs.Chi() | - |
+| CHI_P | Fission spectrum (prompt neutrons) | mgxs.Chi(prompt=True) | - |
+| CHI_D | Fission spectrum (delayed neutrons) | mgxs.ChiDelayed() | - |
+| DECAY_CONSTANT | Decay rate for delayed neutron precursors | mgxs.DecayRate() | 1/s |
+| DIFFCOEF | Diffusion coefficient multi-group cross section | mgxs.DiffusionCoefficient() | cm |
+| FISSE | Average deposited fission energy | mgxs.KappaFissionXS() / mgxs.FissionXS() | MeV |
+| FISSXS | Fission cross section | mgxs.FissionXS() | 1/cm |
+| GTRANSFXS | Scattering production XS Matrix | mgxs.ScatterProbabilityMatrix() * mgxs.ScatterXS() | 1/cm |
+| NSF | Fission neutron production cross section |  nu-fission / flux | 1/cm |
+| RECIPVEL | Inverse neutron speed |  mgxs.InverseVelocity() | s/cm |
+| REMXS | Removal cross section (out scatter + absorption) | mgxs.ScatterProbabilityMatrix() *  mgxs.ScatterXS() + mgxs.AbsorptionXS() | 1/cm |
+
+## Serpent Comparison
+
+We cross verified the group constants generated by OpenMC with group constants generated by
+Serpent. `godiva_serpent` and `godiva_serpent_res.m` are the Serpent input and output files for the
+Godiva sphere. `godiva_serpent.inp` generates the group constants with `moltres_xs.py`. Note the
+minor differences between `godiva_openmc.inp` and `godiva_serpent.inp` arising from the use of
+`branch` and `coef` cards to set up various reactor states at various temperatures in
+[Serpent](https://serpent.vtt.fi/mediawiki/index.php/Input_syntax_manual). Serpent condenses
+multi-temperature group constant data from the various branches into one `*_res.m` output file.
+
+The only difference in syntax format for Serpent-based `*.inp` files lies in the `[FILES]` section
+as follows:
+
+```
+[FILES]
+  *number of files*
+  *serpent _res.m file name* *serpent*
+```
+
+The group constant values generated by both Serpent and OpenMC are similar in values and orders
+of magnitude. The only notable difference is in the FISSE group constant value. Serpent outputs
+FISSE values of ~193 MeV, while OpenMC outputs FISSE values of ~202 MeV. A possible reason for this
+discrepancy is that Serpent includes neutrino energies while OpenMC does not.

doc/content/getting_started/sss2_gc.md

@@ -1,3 +1,55 @@
 # Group Constant File Generation With `extractSerpent2GCs.py`
 
-TODO: Add content
+## Example problem: Two-region MSRE model
+
+Here, group constants are taken from an example Serpent output using PyNE. These will be used to
+generate text-based group constant files using `extractSerpent2GCs.py`. The relevant files for this
+tutorial may be found in the
+[`MSRE_group_constants`](https://github.com/arfc/moltres/tree/devel/tutorial) tutorial directory.
+
+Moltres is *not* a spatially homogenized diffusion code. MOOSE is made for running +big+, +intense+
+problems, using modern HPC. Because there is no desire to homogenize spatially here, the materials
+that the user would like used in Moltres should each fill their own infinite universe. Then, this
+universe should have its group constants generated using the `set gcu <material universe numbers>`
+option in Serpent 2.
+
+It's important that universe 0, the main universe, is not included. Serpent takes tallies for group
+constants in the first universe it identifies, so including 0 means that no further universes will
+be included in GC generation. (please double check this on the
+[serpent forum](https://ttuki.vtt.fi/serpent)).
+
+### Step 1: Generating Group Constants with Serpent 2
+
+In this directory, we provide a Serpent input file for simulating ORNL's Molten Salt Reactor
+Experiment, documented largely on websites like [this](http://www.energyfromthorium.com/pdf/).
+
+For group constant generation, Cole Gentry found that a 4 group structure with three thermal groups
+and one fast group works well in the graphite moderated FHR. There is also an available recommended
+13-group structure commented out in the `gentryGroups.serp` file 
+The PDF of these findings can be found [here](http://trace.tennessee.edu/utk_graddiss/3695/).
+
+The "fuel" file contains "cards" (a relic term referring to the fortran-dominated reactor physics
+ages of yore) that will generate group constants at a few temperatures, and likewise for the
+"moder" file. Like a cooking show, we have prepared the important results for you in the
+`fuel.coe` and `moder.coe` files, which get parsed by `serpentTools` in the `extractSerpent2GCs`
+script. `serpentTools` is a suite of parsers designed by GATech for parsing `SERPENT` output files.
+More information can be found at [here](http://serpent-tools.readthedocs.io/en/latest/).
+
+### Step 2: Parsing Serpent 2 Output Files with extractSerpent2GCs.py
+
+The command to run in order to generate the Moltres-compatible group constants is:
+
+```
+$MOLTRES/python/extractSerpent2GCs.py MSREProperties msre_gentry_4g tempMapping.txt secBranch.txt universeMapping.txt
+```
+
+where $MOLTRES is an environment variable leading to the install location of Moltres. An
+alternative would be to just add the $MOLTRES/python directory to your path.
+
+The input syntax requires a directory name you'd like to create, a file base name that Moltres
+will look at, a file that maps primary branch names to temperatures, a file that lists the
+secondary branch names, and lastly a file that maps universe numbers from Serpent to material
+names. Group constants will be extracted for all materials listed in the last file.
+
+The ```secBranch.txt``` file should be blank if no secondary branches were used, i.e. there is only
+one branch variation per burnup step.

doc/content/getting_started/transient.md

@@ -1,3 +1,3 @@
-# Transient Simulation with Temperature Coupling and Precursor Drift
+# Time-Dependent Simulation with Thermal-Hydraulic Coupling and Precursor Looping
 
-TODO: Add content
+Tutorial to come at a later date.

doc/content/getting_started/tutorials.md

@@ -3,20 +3,20 @@
 The *two-step procedure* is a common approach for multiphysics full-core nuclear reactor analysis.
 These steps are:
 
-+Step 1:+ Generate group constant data with a lattice or full-core reactor model on a
-high-fidelity, continuous-/fine-energy neutronics software at various reactor states.
++Step 1:+ Generate neutron group constant data with a lattice or full-core reactor model on a
+high-fidelity, continuous/fine-energy neutronics software at various reactor states.
 
 +Step 2:+ Use an intermediate-fidelity, computationally cheaper neutronics software with the
-group constant data to perform multiphysics reactor analysis.
+neutron group constant data to perform multiphysics reactor analysis.
 
-Moltres falls under the second step of the two-step procedure. The following sections cover
+Moltres falls under Step 2 of the two-step procedure. The following sections cover
 various tutorials for group constant file generation and running various types of reactor
 simulations with Moltres. The tutorials assume that readers have a basic understanding of reactor
-analysis and molten salt reactors.
+analysis, molten salt reactors, and the [MOOSE framework](https://mooseframework.inl.gov/).
 
 ## 1. Group Constant File Generation
 
-Moltres requires group constants in a compatible text- or JSON-based files to run reactor
+Moltres requires group constants in compatible text- or JSON-based format to run reactor
 simulations. The Moltres GitHub repository provides Python scripts that can automatically parse
 output files from OpenMC, Serpent 2 and NEWT (in SCALE) and generate the requisite .txt or .json
 files. The newer [`moltres_xs.py`](https://github.com/arfc/moltres/blob/devel/python/moltres_xs.py)
@@ -46,9 +46,8 @@ the existing tutorials below.
 
 +2c.+ [Time-dependent Simulation with Thermal-Hydraulic Coupling and Precursor Looping](getting_started/transient.md)
 
-[Recommended Executioner and Preconditioning Settings](getting_started/recommended.md)
++Tip:+ [Recommended Executioner and Preconditioning Settings](getting_started/recommended.md)
 
 ## 3. Data Postprocessing and Analysis
 
-TODO: Add tutorials for this section
-
+Tutorials to come at a later date.

tutorial/eigenvalue/tests

@@ -0,0 +1,14 @@
+[Tests]
+  [nts]
+    type = RunApp
+    input = nts.i
+    check_input = True
+    method = opt
+  []
+  [nts_action]
+    type = RunApp
+    input = 'nts-action.i'
+    check_input = True
+    method = opt
+  []
+[]

tutorial/godiva/godiva_serpent.inp

@@ -12,4 +12,4 @@
 
 [FILES]
   1
-  godiva_serpent_res.m   serpent 1
+  godiva_serpent_res.m   serpent

tutorial/transient/tests

@@ -0,0 +1,8 @@
+[Tests]
+  [transient]
+    type = RunApp
+    input = transient.i
+    check_input = True
+    method = opt
+  []
+[]