Addition of a tally system and [Tallies] block

doc/content/news.md

@@ -5,6 +5,7 @@ significant changes to report.
 
 ### 2024
 
+- [July 2024](news/july2024.md)
 - [March 2024](news/march2024.md)
 
 ### 2023

doc/content/news/july2024.md

@@ -0,0 +1,22 @@
+# July 2022 News
+
+- A new [tally system](/actions/AddTallyAction.md) and an accompanying input syntax
+  block have been added to Cardinal
+- The tally parameters found in [OpenMCCellAverageProblem](/problems/OpenMCCellAverageProblem.md)
+  have been deprecated in favor of this new tally system.
+
+  - Existing input files written with the previous tally syntax will no longer run
+
+The main advantages of the new tally system is the ability to add multiple tallies with different
+spatial binning schemes for different scores. As an example, you can add a [CellTally](/tallies/CellTally.md)
+with a heating score and a [MeshTally](/tallies/MeshTally.md) with a flux score:
+
+!listing actions/multi_tally_example.i
+  block=Problem
+
+Other advantages include:
+
+- Being able to specify tally triggers on a per-tally basis;
+- The option to apply block restrictions to different [CellTally](/tallies/CellTally.md)
+  scores;
+- Additional flexibility when it comes to adding new tally filters in the future.

doc/content/source/actions/AddTallyAction.md

@@ -0,0 +1,36 @@
+# AddTallyAction
+
+!alert note
+`AddTallyAction` can only add tallies to problems which contain a [OpenMCCellAverageProblem](OpenMCCellAverageProblem.md)
+in the `[Problem]` block. Otherwise, attempting to add a tally will result in an error.
+
+## Overview
+
+The `AddTallyAction` action is responsible for adding local tallies to a simulation through the
+`[Tallies]` block in a Cardinal input file.
+
+For all requested tallies other than unstructured mesh tallies, a single tally object is added
+per sub-block in `[Tallies]`. When an unstructured mesh tally is requested `N` tally objects
+will be added, where `N` is the number of positions in `mesh_translations` / the number of positions
+in the file named `mesh_translations_file`. These translated mesh tallies store their scores in the
+same auxvariable(s), and the tally scores are normalized by the sum over all bins in the associated
+[OpenMCCellAverageProblem](OpenMCCellAverageProblem.md). `mesh_translations` and
+`mesh_translations_file` are only applicable to [MeshTally](MeshTally.md) objects.
+
+## Example Input File Syntax
+
+An example where multiple unstructured mesh tallies are added can be found below. `AddTallyAction`adds
+three mesh tallies, where each tally has one of the positions listed in the file named `mesh_translations_file`.
+
+!listing /tutorials/pebbles/openmc_um.i
+  block=Problem
+
+An example of adding non-translated tallies can be found below, where both a [CellTally](CellTally.md)
+and [MeshTally](MeshTally.md) are added to the problem.
+
+!listing /multi_tally_example.i
+  block=Problem
+
+!syntax list /Problem/Tallies actions=false subsystems=false heading=Available Tally Objects
+
+!syntax parameters /Problem/Tallies/AddTallyAction

doc/content/source/actions/multi_tally_example.i

@@ -0,0 +1,43 @@
+[Mesh]
+  [sphere]
+    type = FileMeshGenerator
+    file = mesh_in.e
+  []
+[]
+
+[Problem]
+  type = OpenMCCellAverageProblem
+  particles = 10000
+  inactive_batches = 100
+  batches = 1000
+  initial_properties = xml
+  verbose = true
+  cell_level = 0
+
+  normalize_by_global_tally = true
+  check_tally_sum = true
+
+  power = 100.0
+
+  source_rate_normalization = 'heating_local'
+
+  [Tallies]
+    [Mesh_Tally]
+      type = MeshTally
+      tally_score = 'flux'
+    []
+    [Cell_Tally]
+      type = CellTally
+      tally_score = 'heating_local'
+    []
+  []
+[]
+
+[Executioner]
+  type = Steady
+[]
+
+[Outputs]
+  execute_on = final
+  exodus = true
+[]

doc/content/source/problems/OpenMCCellAverageProblem.md

@@ -7,7 +7,7 @@ The data flow contains two major steps:
 - Temperature and/or density field data on the [MooseMesh](https://mooseframework.inl.gov/source/mesh/MooseMesh.html)
   are volume-averaged and applied to the corresponding OpenMC cells.
 - Tallies are mapped from OpenMC into `CONSTANT MONOMIAL` fields on the
-  [MooseMesh](https://mooseframework.inl.gov/source/mesh/MooseMesh.html).
+  [MooseMesh](https://mooseframework.inl.gov/source/mesh/MooseMesh.html) through the [tally system](AddTallyAction.md).
 
 The smallest possible input file to run OpenMC is shown below.
 This page describes this syntax, plus more advanced settings.
@@ -24,7 +24,7 @@ to communicate OpenMC's solution with MOOSE. These variables will be viewable in
 the MOOSE output files (e.g., via Paraview).
 Depending on the user settings, the following `CONSTANT MONOMIAL` variables will be added:
 
-- Variable(s) representing the OpenMC tally(s)
+- Variable(s) representing the OpenMC tally(s) added by the `[Tallies]` block
 - Variable(s) representing the temperature to read into OpenMC. Temperature will be read
   from the mesh subdomains indicated by `temperature_blocks`.
 - Variable(s) representing the density to read into OpenMC. Density will be read
@@ -34,8 +34,9 @@ Depending on the user settings, the following `CONSTANT MONOMIAL` variables will
 
 !alert tip
 These variables have default names, but you can also control their names using the
-`temperature_variables`, `density_variables`, and `tally_name` parameters. If you want
-to see the names, run with `verbose = true` and tables will print out on initialization
+`temperature_variables`, and `density_variables` parameters. The names of the tally variables
+can be customized with the `tally_name` parameter in each [tally object](AddTallyAction.md).
+If you want to see the names, run with `verbose = true` and tables will print out on initialization
 with this information.
 
 !alert note
@@ -59,8 +60,13 @@ a variable named `nek_temp` in the `helium` block (and so on for density).
   density_variables = 'rho_water; rho_helium'
   density_blocks = 'water; helium'
 
-  tally_score = 'heating flux'
-  tally_name = 'power openmc_flux'
+  [Tallies]
+    [cell_tally]
+      type = CellTally
+      tally_score = 'heating flux'
+      tally_name = 'power openmc_flux'
+    []
+  []
 []
 ```
 
@@ -114,7 +120,13 @@ on defaults; we would set our `[Problem]` block as:
   type = OpenMCCellAverageProblem
   density_blocks = 'water helium'
   temperature_blocks = 'fuel cladding water helium'
-  tally_score = 'heating flux'
+
+  [Tallies]
+    [cell_tally]
+      type = CellTally
+      tally_score = 'heating flux'
+    []
+  []
 []
 ```
 
@@ -284,20 +296,20 @@ regions where there are no cells at that level.
 
 ## Adding Tallies
 
-This class automatically creates tallies with scores specified by the user. There
-are two spatial options, controlled by `tally_type`:
+This class takes the tally objects initialized by the `[Tallies]` block and use them to construct
+tally auxvariables. At the moment there are two options for discretizing tallies spatially in Cardinal:
 
-1. cell tallies
-2. libMesh unstructured mesh tallies
+1. cell tallies ([CellTally](CellTally.md))
+2. libMesh unstructured mesh tallies ([MeshTally](MeshTally.md))
 
-The tally is normalized according to the specified `power` or `source_strength`
-(depending on whether you are running a $k$-eigenvalue or fixed-source problem). By default,
-the normalization is done against a global tally added over the entire
-OpenMC domain. By setting `normalize_by_global_tally` to false, however, the tally is instead
-normalized by the sum of the tally itself.
+If no tallies are specified by the `[Tallies]` block, this class adds no tally auxvariables. Each is normalized
+according to the specified `power` or `source_strength` (depending on whether you are running a
+$k$-eigenvalue or fixed-source problem). By default, the normalization is done against a global
+tally added over the entire OpenMC domain. By setting `normalize_by_global_tally` to false, however,
+the tally is instead normalized by the sum of the tally itself.
 
-You can customize the type of score that OpenMC uses for its tally with the
-`tally_score` parameter. Options include:
+You can customize the type of score that Cardinal uses to normalize tallies to `power` with the `source_rate_normalization`
+parameter. Options include:
 
 - `heating`: total nuclear heating
 - `heating_local`: same as the `heating` score, except that energy from secondary photons
@@ -310,12 +322,12 @@ You can customize the type of score that OpenMC uses for its tally with the
    released is a function of the incident energy by linking to optional fission energy release data.
 - `fission_q_recoverable`: same as the `kappa_fission` score, except that the score depends
    on the incident energy by linking to optional fission energy release data
-- `damage_energy`: damage energy production
 
 For more information on the specific meanings of these various scores,
-please consult the [OpenMC tally documentation](https://docs.openmc.org/en/stable/usersguide/tallies.html). [tally_units] compares the units from OpenMC
-and the units of the AuxVariables created by Cardinal. Note that for all area or
-volume units in [tally_units], that those units match whatever unit is used in the `[Mesh]`.
+please consult the [OpenMC tally documentation](https://docs.openmc.org/en/stable/usersguide/tallies.html). All
+of the tallies added are normalized with the same `source_rate_normalization` score when running in eigenvalue mode.
+[tally_units] compares the units from OpenMC and the units of the AuxVariables created for all tally scores supported
+by Cardinal. Note that for all area or volume units in [tally_units], that those units match whatever unit is used in the `[Mesh]`.
 
 !table id=tally_units caption=Tally units from OpenMC and the conversion in Cardinal.
 | Tally score | OpenMC Units | Cardinal Units |
@@ -366,38 +378,6 @@ already are exactly the same volume, then no special thought is needed for the t
 normalization, and the value will be exactly consistent with the interpretation
 used in OpenMC.
 
-#### Cell Tallies
-
-With cell tallies, `tally_blocks` specifies which blocks
-in the `[Mesh]` should be tallied. Then, any OpenMC cells that map to those blocks
-are added to a cell tally, with one bin for each unique cell ID/instance combination.
-
-#### Unstructured Mesh Tallies
-  id=um
-
-There are two options with unstructured mesh tallies:
-
-- Do nothing, in which case OpenMC will tally on the `[Mesh]`
-- Specify a `mesh_template`, which provides a path to a mesh file
-
-For the `mesh_template` option, it is possible
-to translate the same mesh to multiple locations in the OpenMC geometry
-(while only taking up the memory needed to store a single mesh) using
-the `mesh_translations` or `mesh_translations_file` parameters. This is a useful feature for
-geometries that consist of many repeated geometry units, such as pebble bed and pin fuel
-systems.
-
-!alert note
-At present, unstructured mesh tallies are copied directly to the `[Mesh]` (without
-doing any type of nearest-node lookup).
-Suppose the mesh template consists of a mesh for a pincell with $N$ elements
-that you have translated to 3 different locations, giving a total of $3N$ tally
-bins. Because a direct copy is used to transfer the mesh tally results to the `[Mesh]`,
-the first $3N$ elements in the `[Mesh]` must exactly match the $3N$ elements in
-the mesh tally (except for a possible mesh scaling, as described in [#scaling]).
-This equivalence is required for the direct copy to be accurate - otherwise, the
-mesh tally results would be transferred to incorrect regions of space.
-
 ## Other Features
 
 While this class mainly facilitates data transfers to and from OpenMC, a number of
@@ -512,11 +492,9 @@ once reaching certain criteria in $k$ and/or the tally uncertainties, including:
 - $k$ relative error
 - tally relative error
 
-Set the `k_trigger` parameter to activate a trigger based on $k$, and set
-`tally_trigger` to activate a trigger based on the tally created
-automatically as part of the wrapping setup. Then, the desired convergence
-threshold is specified with the `k_trigger_threshold` and `tally_trigger_threshold`
-parameters, respectively. Both $k$ and tally triggers can be used simultaneously.
+Setting `k_trigger` enables triggers based on $k$, and setting `k_trigger_threshold` sets the required convergence criteria.
+Individual tally triggers can be set in the `tally_trigger` and `tally_trigger_threshold` parameters of the tally classes
+([CellTally](CellTally.md) and [MeshTally](MeshTally.md)). Both $k$ and multiple tally triggers can be used simultaneously.
 
 #### Controlling the OpenMC Settings
 
@@ -531,13 +509,6 @@ settings directly from the Cardinal input file:
 For all of the above, a setting in the Cardinal input file will override
 any settings in the OpenMC XML files.
 
-#### Outputting the OpenMC Solution
-
-Certain aspects of the OpenMC solution can be output as auxiliary variables to the mesh:
-
-- `unrelaxed_tally`: unrelaxed tally; this will append `_raw` to the tally name and output to the mesh mirror
-- `unrelaxed_tally_std_dev`: unrelaxed tally standard deviation; this will append `_std_dev` to the tally and output to the mesh mirror
-
 #### Volume Calculations
 
 It can be helpful for debugging problem setup to compare actual OpenMC cell volumes against

doc/content/source/problems/smallest_openmc_input.i

@@ -10,9 +10,14 @@
   temperature_blocks = '1 2 3'
   density_blocks = '3'
 
-  tally_type = cell
-  tally_blocks = '1'
   cell_level = 0
+
+  [Tallies]
+    [Cell]
+      type = CellTally
+      tally_blocks = '1'
+    []
+  []
 []
 
 [Executioner]

doc/content/source/tallies/CellTally.md

@@ -0,0 +1,33 @@
+# CellTally
+
+!alert note
+`CellTally` can only be added to problems when the input files contains a [OpenMCCellAverageProblem](OpenMCCellAverageProblem.md)
+in the `[Problem]` block. Otherwise, attempting to add this tally will result in an error.
+
+## Description
+
+The `CellTally` class wraps an OpenMC tally with a distributed cell filter to enable data transfer
+from CSG cells to a [MOOSEMesh](https://mooseframework.inl.gov/source/mesh/MooseMesh.html) mirror
+of the OpenMC geometry. The cell to element mapping established by the [OpenMCCellAverageProblem](OpenMCCellAverageProblem.md)
+is used to facilitate this data transfer to the mesh mirror. When using a `CellTally`, `tally_blocks`
+specifies which blocks in the `[Mesh]` should be tallied. Then, any OpenMC cells that map to those
+blocks are added to a cell tally, with one bin for each unique cell ID/instance combination.
+`check_equal_mapped_tally_volumes` is used to confirm whether the elements mapped to a specific cell
+have the same volume (to a tolerance specified in `equal_tally_volume_abs_tol`) as the associated cell.
+
+!include scores_triggers.md
+
+## Example Input File Syntax
+
+As an example, this `CellTally` scores `kappa_fission` (the default tally score) on block `0` and stores
+the result in a variable named `heat_source`. This corresponds to tallying the heating for three different
+fuel pebbles.
+
+!listing /tutorials/pebbles/openmc.i
+  block=Problem
+
+!syntax parameters /Problem/Tallies/CellTally
+
+!syntax inputs /Problem/Tallies/CellTally
+
+!syntax children /Problem/Tallies/CellTally

doc/content/source/tallies/MeshTally.md

@@ -0,0 +1,56 @@
+# MeshTally
+  id=um
+
+!alert note
+`MeshTally` can only be added to problems when the input files contains a [OpenMCCellAverageProblem](OpenMCCellAverageProblem.md)
+in the `[Problem]` block. Otherwise, attempting to add this tally will result in an error.
+
+## Description
+
+The `MeshTally` class wraps an OpenMC tally with an unstructured libMesh filter to directly enable tallying on an unstructured mesh.
+There are two options when using a `MeshTally`:
+
+- Do nothing, in which case OpenMC will tally on the `[Mesh]`
+- Specify a `mesh_template`, which provides a path to a mesh file
+
+For the `mesh_template` option, it is possible
+to translate the same mesh to multiple locations in the OpenMC geometry
+(while only taking up the memory needed to store a single mesh) using
+the `mesh_translations` or `mesh_translations_file` parameters provided by
+the [tallies block](AddTallyAction.md). This is a useful feature for
+geometries that consist of many repeated geometry units, such as pebble bed and pin fuel
+systems.
+
+!alert note
+At present, unstructured mesh tallies are copied directly to the `[Mesh]` (without
+doing any type of nearest-node lookup).
+Suppose the mesh template consists of a mesh for a pincell with $N$ elements
+that you have translated to 3 different locations, giving a total of $3N$ tally
+bins. Because a direct copy is used to transfer the mesh tally results to the `[Mesh]`,
+the first $3N$ elements in the `[Mesh]` must exactly match the $3N$ elements in
+the mesh tally (except for a possible mesh scaling, as described in [OpenMCCellAverageProblem.md#scaling]).
+This equivalence is required for the direct copy to be accurate - otherwise, the
+mesh tally results would be transferred to incorrect regions of space.
+
+!include scores_triggers.md
+
+!alert note
+At present time, libMesh unstructured mesh tallies only support `collision` and `analog` estimators. Attempting to set `tally_estimator`
+to `tracklength` will result in a warning; the `MeshTally` will then manually reset the estimator to `collision` to prevent OpenMC from
+throwing an error.
+
+## Example Input File Syntax
+
+As an example, this `MeshTally` scores `kappa_fission` (the default tally score) on the unstructured mesh
+found in `mesh_in.e` and stores it in a variable called `heat_source`. The `[Tallies]` block adds three
+`MeshTally` classes, each one located at a different point specified in `mesh_translations` which corresponds
+to the centroid of a fuel pebble.
+
+!listing /tutorials/pebbles/openmc_um.i
+  block=Problem
+
+!syntax parameters /Problem/Tallies/MeshTally
+
+!syntax inputs /Problem/Tallies/MeshTally
+
+!syntax children /Problem/Tallies/MeshTally