add kinetic simulation information to the user guide

Author: yardasol

docs/source/io_formats/materials.rst

@@ -49,8 +49,9 @@ Each ``material`` element can have the following attributes or sub-elements:
     <temperature_default>` is used.
 
   :density:
-    An element with attributes/sub-elements called ``value`` and ``units``. The
-    ``value`` attribute is the numeric value of the density while the ``units``
+    An element with attributes/sub-elements called ``value``, ``units``, and
+    (optionally) ``value_timeseries``. The ``value`` attribute is the numeric
+    value of the density while the ``units``
     can be "g/cm3", "kg/m3", "atom/b-cm", "atom/cm3", or "sum". The "sum" unit
     indicates that values appearing in ``ao`` or ``wo`` attributes for ``<nuclide>``
     and ``<element>`` sub-elements are to be interpreted as absolute nuclide/element
@@ -59,14 +60,21 @@ Each ``material`` element can have the following attributes or sub-elements:
     a ``macroscopic`` quantity to indicate that the density is already included
     in the library and thus not needed here.  However, if a value is provided
     for the ``value``, then this is treated as a number density multiplier on
-    the macroscopic cross sections in the multi-group data.  This can be used,
-    for example, when perturbing the density slightly.
+    the macroscopic cross sections in the multi-group data. This can be used,
+    for example, when perturbing the density slightly. The ``value_timeseries``
+    element indicates a material density changing in time. This can be used to
+    simulate various benchmark problems in kinetic simulations. The
+    ``value_timeseries`` attribute is assumed to use the same units specified
+    in the ``units`` attribute.
 
     *Default*: None
 
     .. note:: A ``macroscopic`` quantity can not be used in conjunction with a
               ``nuclide``, ``element``, or ``sab`` quantity.
 
+    .. note:: The ``value_timeseries`` attribute cannot be used with ``sum``
+              densities.
+
   :nuclide:
     An element with attributes/sub-elements called ``name``, and ``ao``
     or ``wo``. The ``name`` attribute is the name of the cross-section for a

docs/source/io_formats/settings.rst

@@ -321,6 +321,18 @@ the estimated eigenvalue. It has the following attributes/sub-elements:
 
   .. note:: See section on the :ref:`trigger` for more information.
 
+-------------------------------------
+``<kinetic_simulation>`` Element
+-------------------------------------
+
+The ``<kinetic_simulation>`` element indicates whether to run a static or
+time-dependent simulation (with no feedbacks). If this element is set to
+"true", a kinetic simulation will be run; otherwise a static simulation is run.
+
+  *Default*: false
+
+.. _kinetic_simulation:
+
 ---------------------------
 ``<log_grid_bins>`` Element
 ---------------------------
@@ -585,6 +597,25 @@ found in the :ref:`random ray user guide <random_ray>`.
 
     *Default*: 1.0
 
+If a kinetic simulation is active, two additional settings are available:
+
+  :bd_order:
+    Order for backwards difference approximation used in numerically estimating
+    time derivatives. The backwards difference approximation is stable for
+    orders less than or equal to 6, and is relatively straightforward to
+    implement. The default value of 3 balances higher precision with speed.
+
+    *Default*: 3
+
+  :time_derivative_method:
+    The method used to resolve the angular flux time-derivative in the time-dependent
+    characteristic equation. The ``isotropic`` method utilizes an isotropic approximation
+    to resolve the angular flux time derivative. The ``propagation`` method
+    uses a technique called Time Derivative Propagation to resolve the angular
+    flux time derivative.
+
+    *Default*: ``isotropic``
+
 ----------------------------------
 ``<resonance_scattering>`` Element
 ----------------------------------
@@ -1286,6 +1317,32 @@ despite not being bounded on both sides.
 
 .. _trace:
 
+---------------------------------
+``<timestep_parameters>`` Element
+---------------------------------
+
+The ``<timestep_parameters>`` element can be used specify for how long and
+at what resolution to run a kinetic simulation. This element has the
+following attributes/sub-elements:
+
+  :n_timesteps:
+    The number of timesteps. Must be specified by the user.
+
+  :dt:
+    Time step size. Must be specified by the user.
+
+  :timestep_units:
+    Time step units. Available options are  ``ms`` for milliseconds, ``s`` for seconds,
+    and ``min`` for minutes.
+
+    *Default*: ``s``
+
+  .. note:: This element is required if the :ref:`kinetic_simulation` is ``true``.
+
+  *Default*: None
+
+.. _timestep_parameters:
+
 -------------------
 ``<trace>`` Element
 -------------------

docs/source/io_formats/statepoint.rst

@@ -28,6 +28,10 @@ The current version of the statepoint file format is 18.1.
              'continuous-energy' or 'multi-group'.
            - **run_mode** (*char[]*) -- Run mode used, either 'eigenvalue' or
              'fixed source'.
+           - **solver_type** (*char[]*) -- Solver used, either 'monte carlo' or
+             'random ray'.
+           - **kinetic_simulation** (*int*) -- Flag indicating whether a kinetic (1)
+             or static (0) simulation was run.
            - **n_particles** (*int8_t*) -- Number of particles used per generation.
            - **n_batches** (*int*) -- Number of batches to simulate.
            - **current_batch** (*int*) -- The number of batches already simulated.
@@ -49,6 +53,10 @@ The current version of the statepoint file format is 18.1.
              combined estimate of k-effective.
            - **n_realizations** (*int*) -- Number of realizations for global
              tallies.
+           - **n_energy_groups** (*int*) -- Number of energy groups used if
+              **energy_mode** is 'multi-group'.
+           - **n_delay_groups** (*int*) -- Number of delay groups used if
+              **energy_mode** is 'multi-group'.
            - **global_tallies** (*double[][2]*) -- Accumulated sum and
              sum-of-squares for each global tally.
            - **source_bank** (Compound type) -- Source bank information for each
@@ -197,3 +205,16 @@ All values are given in seconds and are measured on the master process.
              tally results and evaluating their statistics.
            - **writing statepoints** (*double*) -- Time spent writing statepoint
              files
+
+           If random ray mode is used, the following times are also recorded:
+           - **source_update** (*double*) -- Time spent updating the neutron source. 
+           - **precursor_update** (*double*) -- Time spent updating the precursors
+             (only written for kinetic simulations).
+
+**/timestep_data/**
+
+Time step information for kinetic simulation. All values are given in seconds.
+
+:Datasets: - **dt** (*double*) -- Length of the time step.
+           - **current_timestep** (*int*) -- Numbered time step.
+           - **current_time** (*double*) -- Simulated elapsed time.