.. _userguide_input:
ENRICO Runtime Settings
=======================
Parameters and settings for each individual physics code are set normally in
their respective input files. Parameters related to the coupled simulation are
listed in a special ``enrico.xml`` file. This file accepts the following
elements:
````
~~~~~~~~~~~~~~~~~
Base element for heat/fluids driver parameters
````
------------
The physics driver for solving fluid and heat transfer equations. Valid options
are "nek5000", "nekrs", and "surrogate".
````
-----------------
The pressure of the outlet boundary condition in units of [MPa].
Nek5000- and nekRS-specific Parameters
--------------------------------------
Under the ```` element, these sub-elements are available Nek5000 and nekRS
* ````: Required. The casename for the problem (i.e, the basename for .par or .rea files).
* ````: Optional. Can be ``true`` or ``false`` (default ``false``). If true, output the heat
source to a Nek field file in units of [W/cm^3]. In an ENRICO simulation, the field file ``#.f#####`` always
contains temperature. The heat source is additionally output as follows:
- For Nek5000 runs, the heat source is output as the first passive scalar in ``#.f######``.
- For nekRS runs, the heat source is output as the temperature field in a second field file, ``qsc#.f#####``.
Surrogate-specific Parameters
-----------------------------
Under the ```` element, these surrogate-specific sub-elements are available:
* ````: The cladding inner radius in units of [cm].
* ````: The cladding outer radius in units of [cm].
* ````: The fuel pellet radius in units of [cm].
* ````: The number of rings the fuel pellet should be subdivided
into when solving the heat equation.
* ````: The number of rings in the cladding should be subdivided
into when solving the heat equation.
* ````: Number of pins in the assembly in the x-direction.
* ````: Number of pins in the assembly in the y-direction.
* ````: Pitch, or distance between centers along the x- and y-axes,
between pins. The pitch must be greater than the outer diameter of the pins,
which would correspond to touching pins. This pitch is used to determine the
pin-pin spacing and the pin- to assembly-edge spacing, which is taken to be
half a pitch.
* ``n_assem_x``: Number of assemblies in the x direction, each column of
assemblies is assumed to be centered at y=0.
* ``n_assem_y``: Number of assemblies in the y direction, each row of
assemblies is assumed to be centered at x=0.
* ``assembly_width_x``: Width of assembly in x direction in units of [cm].
* ``assembly_width_y``: Width of assembly in y direction in units of [cm].
* ``skip_assemblies``: Indices of assemblies in the rectangular grid that
should be skipped (if any) when solving the heat/fluids equatioons (ie, if an
assembly is not a fuel/core region with a pin lattice, it should be skipped).
Indices start at 0 in upper left corner of the core and work left to right,
then top to bottom.
* ````: Values along the z-axis that subdivide the fuel region in units of [cm].
* ````: Fluid inlet temperature in [K].
* ````: Fluid mass flowrate in [kg/s].
* ```` * Maximum number of iterations to perform in the
solution of the subchannel equations. Convergence is based on the relative
change measured in the 1-norm in enthalpy and pressure between two
successive iterations. This defaults to 100.
* ````: Convergence tolerance to use for enthalpy between
two successive iterations of the subchannel solver. This defaults to a
value of 1e-2.
* ````: Convergence tolerance to use for pressure between
two successive iterations of the subchannel solver. This defaults to a value
of 1e-2.
* ````: Tolerance on the heat equation solver. This defaults to a value of 1e-4.
* ````: Degree of output printing for diagnostic checking. This
defaults to `none`, but may be set to `low` and `high`. Both `low` and `high`
perform error checks such as ensuring conservation of mass and energy, while
`high` prints some subchannel solution metrics for each channel.
* ````: This element indicates visualization settings for the heat solver.
- ``filename`` (attribute): File prefix for output VTK files
- ````: what iterations to write output at
- ````: resolution of the VTK objects. When fluid regions are
included, the resolution must be divisible by the number of channels per rod
(typically 4)
- ````: what data to write. Either "all", "source", "temperature", or "density".
- ````: what regions to write output for. Either "all", "solid", or "fluid".
````
~~~~~~~~~~~~~~~~
Base element for neutron transport driver parameters
````
------------
The physics driver for solving particle transport. Valid options are "openmc",
"shift", and "surrogate".
````
------------------
A boolean (“true” or “false”, default “false”). If true, then a boron search to
the ``target_keff`` value will be performed. If false, no boron search will be
performed. This boron search yields the boron parts per million (ppm) on a
number density basis in the fluid-bearing regions of the model.
Shift-specific Parameters
-------------------------
Under the ```` element, these Shift-specific sub-elements are available:
* ````: Path to the Shift XML input file
Boron search-specific Parameters
--------------------------------
Under the ```` element, these boron search-specific sub-elements are
available:
* ````: The first guess of the fluid's boron concentration
in units of ppm to use when performing the critical search. If not provided,
this defaults to the average boron ppm across all fluid-bearing cells of the
initial the neutron transport model.
* ````: The k-eigenvalue to search for by varing the boron ppm.
This defaults to a value of 1.0.
* ````: The tolerance on the k-eigenvalue, to a 95%
confidence interval based on the stochastic variation of k-eff, that will be
used to evaluate convergence of the boron search. This defaults to a value of
1.0e-3.
* ````: The enrichment of B-10 in the boron in terms of an atom
fraction. This defaults to a value of 0.1982.
* ````: The target boron search convergence criterion. If
:math:`ppm_i` and :math:`ppm_{i+1}` are the set of total boron number
density concentrations (on a number density basis) at iterations :math:`i`
and :math:`i+1`, convergence is reached if both of the following conditions
are achieved:
.. math::
\lvert ppm_{i+1} - ppm_i \rvert < \epsilon_{boron}
.. math::
\lvert k_{eff,i+1} - k_{eff,i} \rvert < \epsilon_{keff}
This defaults to a value of 1.0e-3.
.. note:: In ENRICO, the boron parts-per-million (ppm) is defined as the ppm
boron on a number-density basis.
.. note:: ENRICO assumes that the reactivity effect of the hydrogen and oxygen
in boric acid is small and on the order of their number density
variations in water. Therefore, the ENRICO's boron search only
modifies the boron concentrations and not the hydrogen and oxygen as
the boron ppm varies.
````
~~~~~~~~~~~~~~
Base node for coupling parameters
````
-------------
A boolean ("true" or "false", default "false"). If true, print detailed info, including
MPI communicator layouts for each rank and volume comparisons for each cell (summarized
volume statistics are always printed).
````
-----------
The power of the reactor in units of [W].
````
-------------------
The maximum number of timesteps.
````
---------------------
The maximum number of Picard iterations within a timestep.
.. _epsilon:
````
-------------
Convergence criterion, :math:`\epsilon`. If :math:`T_i` and :math:`T_{i+1}` are
the set of temperatures at iterations :math:`i` and :math:`i+1`, convergence is
reached if
.. math::
\lvert T_{i+1} - T_i \rvert < \epsilon
*Default*: 1.0e-3
````
-----------
Underrelaxation parameter used on a heat source update. Let :math:`q_i` be the
heat source at iteration :math:`i` and :math:`\tilde{q}_{i+1}` be the next
estimate of the heat source as determined by the neutronics solver. Then, the
heat source for iteration :math:`i + 1` is:
.. math::
q_{i+1} = (1 - \alpha) q_i + \alpha \tilde{q}_{i+1}
Choosing :math:`\alpha = 1` corresponds to no underrelaxation. A special value
of "robbins-monro" indicates that Robbins-Monro relaxation is to be used:
.. math::
q_{i+1} = \frac{1}{i} q_i + \left (1 - \frac{1}{i} \right) \tilde{q}_{i+1}
*Default*: 1.0
````
-------------
Underrelaxation parameter used on a temperature update. Let :math:`T_i` be the
temperature at iteration :math:`i` and :math:`\tilde{T}_{i+1}` be the next
estimate of the temperature as determined by the thermal-fluids solver. Then,
the temperature for iteration :math:`i + 1` is:
.. math::
T_{i+1} = (1 - \alpha_T) T_i + \alpha_T \tilde{T}_{i+1}
Choosing :math:`\alpha_T = 1` corresponds to no underrelaxation. A special value
of "robbins-monro" indicates that Robbins-Monro relaxation is to be used:
.. math::
T_{i+1} = \frac{1}{i} T_i + \left (1 - \frac{1}{i} \right) \tilde{T}_{i+1}
*Default*: 1.0
````
---------------
Underrelaxation parameter used on a density update update. Let :math:`\rho_i` be
the density at iteration :math:`i` and :math:`\tilde{\rho}_{i+1}` be the next
estimate of the density as determined by the thermal-fluids solver. Then, the
density for iteration :math:`i + 1` is:
.. math::
\rho_{i+1} = (1 - \alpha_\rho) \rho_i + \alpha_\rho \tilde{\rho}_{i+1}
Choosing :math:`\alpha_\rho = 1` corresponds to no underrelaxation. A special
value of "robbins-monro" indicates that Robbins-Monro relaxation is to be used:
.. math::
\rho_{i+1} = \frac{1}{i} \rho_i + \left (1 - \frac{1}{i} \right) \tilde{\rho}_{i+1}
*Default*: 1.0
````
--------------------
The initial temperature distribution can be determined either from the
neutronics solver or the heat-fluids solver. A value of "neutronics" will use
the temperatures specified in the model for the neutronics solver whereas a
value of "heat_fluids" will use the temperatures specified in the model for the
heat-fluids solver.
*Default*: neutronics
````
----------------
The initial density distribution can be determined either from the
neutronics solver or the heat-fluids solver. A value of "neutronics" will use
the densities specified in the model for the neutronics solver whereas a
value of "heat_fluids" will use the densities specified in the model for the
heat-fluids solver. Note that this density initial condition strictly refers
to the fluid density - the solid density is constant throughout the simulation,
and is unchanged from the value used in the neutronics input.
*Default*: neutronics
````
----------------------
This element indicates the type of norm to use for convergence checks. At each
Picard iteration, the norm of the difference between the temperature at the
previous and current iterations is compared to the value of :ref:`epsilon` in
order to determine convergence. Valid values for this element are "L1", "L2",
and "Linf".
*Default*: Linf