diff --git a/docs/source/io_formats/cmfd.rst b/docs/source/io_formats/cmfd.rst new file mode 100644 index 0000000000..80e8365c79 --- /dev/null +++ b/docs/source/io_formats/cmfd.rst @@ -0,0 +1,221 @@ +.. _io_cmfd: + +============================== +CMFD Specification -- cmfd.xml +============================== + +Coarse mesh finite difference acceleration method has been implemented in +OpenMC. Currently, it allows users to accelerate fission source convergence +during inactive neutron batches. To run CMFD, the ```` element in +``settings.xml`` should be set to "true". + +------------------- +```` Element +------------------- + +The ```` element controls what batch CMFD calculations should begin. + + *Default*: 1 + +------------------------ +```` Element +------------------------ + +The ```` element controls whether :math:`\widehat{D}` nonlinear +CMFD parameters should be reset to zero before solving CMFD eigenproblem. +It can be turned on with "true" and off with "false". + + *Default*: false + +--------------------- +```` Element +--------------------- + +The ```` element sets one additional CMFD output column. Options are: + +* "balance" - prints the RMS [%] of the resdiual from the neutron balance + equation on CMFD tallies. +* "dominance" - prints the estimated dominance ratio from the CMFD iterations. + **This will only work for power iteration eigensolver**. +* "entropy" - prints the *entropy* of the CMFD predicted fission source. + **Can only be used if OpenMC entropy is active as well**. +* "source" - prints the RMS [%] between the OpenMC fission source and CMFD + fission source. + + *Default*: balance + +------------------------- +```` Element +------------------------- + +The ```` element controls whether an effective downscatter cross +section should be used when using 2-group CMFD. It can be turned on with "true" +and off with "false". + + *Default*: false + +---------------------- +```` Element +---------------------- + +The ```` element controls whether or not the CMFD diffusion result is +used to adjust the weight of fission source neutrons on the next OpenMC batch. +It can be turned on with "true" and off with "false". + + *Default*: false + +------------------------------------ +```` Element +------------------------------------ + +The ```` element specifies two parameters. The first is +the absolute inner tolerance for Gauss-Seidel iterations when performing CMFD +and the second is the relative inner tolerance for Gauss-Seidel iterations +for CMFD calculations. + + *Default*: 1.e-10 1.e-5 + +-------------------- +```` Element +-------------------- + +The ```` element specifies the tolerance on the eigenvalue when performing +CMFD power iteration. + + *Default*: 1.e-8 + +------------------ +```` Element +------------------ + +The CMFD mesh is a structured Cartesian mesh. This element has the following +attributes/sub-elements: + + :lower_left: + The lower-left corner of the structured mesh. If only two coordinates are + given, it is assumed that the mesh is an x-y mesh. + + :upper_right: + The upper-right corner of the structrued mesh. If only two coordinates are + given, it is assumed that the mesh is an x-y mesh. + + :dimension: + The number of mesh cells in each direction. + + :width: + The width of mesh cells in each direction. + + :energy: + Energy bins [in eV], listed in ascending order (e.g. 0.0 0.625 20.0e6) + for CMFD tallies and acceleration. If no energy bins are listed, OpenMC + automatically assumes a one energy group calculation over the entire + energy range. + + :albedo: + Surface ratio of incoming to outgoing partial currents on global boundary + conditions. They are listed in the following order: -x +x -y +y -z +z. + + *Default*: 1.0 1.0 1.0 1.0 1.0 1.0 + + :map: + An optional acceleration map can be specified to overlay on the coarse + mesh spatial grid. If this option is used, a ``1`` is used for a + non-accelerated region and a ``2`` is used for an accelerated region. + For a simple 4x4 coarse mesh with a 2x2 fuel lattice surrounded by + reflector, the map is: + + ``1 1 1 1`` + + ``1 2 2 1`` + + ``1 2 2 1`` + + ``1 1 1 1`` + + Therefore a 2x2 system of equations is solved rather than a 4x4. This + is extremely important to use in reflectors as neutrons will not + contribute to any tallies far away from fission source neutron regions. + A ``2`` must be used to identify any fission source region. + + .. note:: Only two of the following three sub-elements are needed: + ``lower_left``, ``upper_right`` and ``width``. Any combination + of two of these will yield the third. + +------------------ +```` Element +------------------ + +The ```` element is used to normalize the CMFD fission source distribution +to a particular value. For example, if a fission source is calculated for a +17 x 17 lattice of pins, the fission source may be normalized to the number of +fission source regions, in this case 289. This is useful when visualizing this +distribution as the average peaking factor will be unity. This parameter will +not impact the calculation. + + *Default*: 1.0 + +--------------------------- +```` Element +--------------------------- + +The ```` element is used to view the convergence of power +iteration. This option can be turned on with "true" and turned off with "false". + + *Default*: false + +------------------------- +```` Element +------------------------- + +The ```` element can be turned on with "true" to have an adjoint +calculation be performed on the last batch when CMFD is active. + + *Default*: false + +-------------------- +```` Element +-------------------- + +The ```` element specifies an optional Wielandt shift parameter for +accelerating power iterations. It is by default very large so the impact of the +shift is effectively zero. + + *Default*: 1e6 + +---------------------- +```` Element +---------------------- + +The ```` element specifies an optional spectral radius that can be set to +accelerate the convergence of Gauss-Seidel iterations during CMFD power iteration +solve. + + *Default*: 0.0 + +------------------ +```` Element +------------------ + +The ```` element specifies the tolerance on the fission source when performing +CMFD power iteration. + + *Default*: 1.e-8 + +------------------------- +```` Element +------------------------- + +The ```` element contains a list of batch numbers in which CMFD tallies +should be reset. + + *Default*: None + +---------------------------- +```` Element +---------------------------- + +The ```` element is used to write the sparse matrices created +when solving CMFD equations. This option can be turned on with "true" and off +with "false". + + *Default*: false diff --git a/docs/source/io_formats/cross_sections.rst b/docs/source/io_formats/cross_sections.rst new file mode 100644 index 0000000000..6998d3615b --- /dev/null +++ b/docs/source/io_formats/cross_sections.rst @@ -0,0 +1,5 @@ +.. _io_cross_sections: + +============================================ +Cross Sections Locator -- cross_sections.xml +============================================ diff --git a/docs/source/io_formats/geometry.rst b/docs/source/io_formats/geometry.rst new file mode 100644 index 0000000000..d3da787bd5 --- /dev/null +++ b/docs/source/io_formats/geometry.rst @@ -0,0 +1,418 @@ +.. _io_geometry: + +====================================== +Geometry Specification -- geometry.xml +====================================== + +The geometry in OpenMC is described using `constructive solid geometry`_ (CSG), +also sometimes referred to as combinatorial geometry. CSG allows a user to +create complex objects using Boolean operators on a set of simpler surfaces. In +the geometry model, each unique volume is defined by its bounding surfaces. In +OpenMC, most `quadratic surfaces`_ can be modeled and used as bounding surfaces. + +Every geometry.xml must have an XML declaration at the beginning of the file and +a root element named geometry. Within the root element the user can define any +number of cells, surfaces, and lattices. Let us look at the following example: + +.. code-block:: xml + + + + + + + 1 + sphere + 0.0 0.0 0.0 5.0 + vacuum + + + + 1 + 0 + 1 + -1 + + + +At the beginning of this file is a comment, denoted by a tag starting with +````. Comments, as well as any other type of input, +may span multiple lines. One convenient feature of the XML input format is that +sub-elements of the ``cell`` and ``surface`` elements can also be equivalently +expressed of attributes of the original element, e.g. the geometry file above +could be written as: + +.. code-block:: xml + + + + + + + + + + +.. _surface_element: + +--------------------- +```` Element +--------------------- + +Each ```` element can have the following attributes or sub-elements: + + :id: + A unique integer that can be used to identify the surface. + + *Default*: None + + :name: + An optional string name to identify the surface in summary output + files. This string is limited to 52 characters for formatting purposes. + + *Default*: "" + + :type: + The type of the surfaces. This can be "x-plane", "y-plane", "z-plane", + "plane", "x-cylinder", "y-cylinder", "z-cylinder", "sphere", "x-cone", + "y-cone", "z-cone", or "quadric". + + *Default*: None + + :coeffs: + The corresponding coefficients for the given type of surface. See below for + a list a what coefficients to specify for a given surface + + *Default*: None + + :boundary: + The boundary condition for the surface. This can be "transmission", + "vacuum", "reflective", or "periodic". Periodic boundary conditions can + only be applied to x-, y-, and z-planes. Only axis-aligned periodicity is + supported, i.e., x-planes can only be paired with x-planes. Specify which + planes are periodic and the code will automatically identify which planes + are paired together. + + *Default*: "transmission" + + :periodic_surface_id: + If a periodic boundary condition is applied, this attribute identifies the + ``id`` of the corresponding periodic sufrace. + +The following quadratic surfaces can be modeled: + + :x-plane: + A plane perpendicular to the x axis, i.e. a surface of the form :math:`x - + x_0 = 0`. The coefficients specified are ":math:`x_0`". + + :y-plane: + A plane perpendicular to the y axis, i.e. a surface of the form :math:`y - + y_0 = 0`. The coefficients specified are ":math:`y_0`". + + :z-plane: + A plane perpendicular to the z axis, i.e. a surface of the form :math:`z - + z_0 = 0`. The coefficients specified are ":math:`z_0`". + + :plane: + An arbitrary plane of the form :math:`Ax + By + Cz = D`. The coefficients + specified are ":math:`A \: B \: C \: D`". + + :x-cylinder: + An infinite cylinder whose length is parallel to the x-axis. This is a + quadratic surface of the form :math:`(y - y_0)^2 + (z - z_0)^2 = R^2`. The + coefficients specified are ":math:`y_0 \: z_0 \: R`". + + :y-cylinder: + An infinite cylinder whose length is parallel to the y-axis. This is a + quadratic surface of the form :math:`(x - x_0)^2 + (z - z_0)^2 = R^2`. The + coefficients specified are ":math:`x_0 \: z_0 \: R`". + + :z-cylinder: + An infinite cylinder whose length is parallel to the z-axis. This is a + quadratic surface of the form :math:`(x - x_0)^2 + (y - y_0)^2 = R^2`. The + coefficients specified are ":math:`x_0 \: y_0 \: R`". + + :sphere: + A sphere of the form :math:`(x - x_0)^2 + (y - y_0)^2 + (z - z_0)^2 = + R^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 \: R`". + + :x-cone: + A cone parallel to the x-axis of the form :math:`(y - y_0)^2 + (z - z_0)^2 = + R^2 (x - x_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 + \: R^2`". + + :y-cone: + A cone parallel to the y-axis of the form :math:`(x - x_0)^2 + (z - z_0)^2 = + R^2 (y - y_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 + \: R^2`". + + :z-cone: + A cone parallel to the x-axis of the form :math:`(x - x_0)^2 + (y - y_0)^2 = + R^2 (z - z_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 + \: R^2`". + + :quadric: + A general quadric surface of the form :math:`Ax^2 + By^2 + Cz^2 + Dxy + + Eyz + Fxz + Gx + Hy + Jz + K = 0` The coefficients specified are ":math:`A + \: B \: C \: D \: E \: F \: G \: H \: J \: K`". + +.. _cell_element: + +------------------ +```` Element +------------------ + +Each ```` element can have the following attributes or sub-elements: + + :id: + A unique integer that can be used to identify the cell. + + *Default*: None + + :name: + An optional string name to identify the cell in summary output files. + This string is limmited to 52 characters for formatting purposes. + + *Default*: "" + + :universe: + The ``id`` of the universe that this cell is contained in. + + *Default*: 0 + + :fill: + The ``id`` of the universe that fills this cell. + + .. note:: If a fill is specified, no material should be given. + + *Default*: None + + :material: + The ``id`` of the material that this cell contains. If the cell should + contain no material, this can also be set to "void". A list of materials + can be specified for the "distributed material" feature. This will give each + unique instance of the cell its own material. + + .. note:: If a material is specified, no fill should be given. + + *Default*: None + + :region: + A Boolean expression of half-spaces that defines the spatial region which + the cell occupies. Each half-space is identified by the unique ID of the + surface prefixed by `-` or `+` to indicate that it is the negative or + positive half-space, respectively. The `+` sign for a positive half-space + can be omitted. Valid Boolean operators are parentheses, union `|`, + complement `~`, and intersection. Intersection is implicit and indicated by + the presence of whitespace. The order of operator precedence is parentheses, + complement, intersection, and then union. + + As an example, the following code gives a cell that is the union of the + negative half-space of surface 3 and the complement of the intersection of + the positive half-space of surface 5 and the negative half-space of surface + 2: + + .. code-block:: xml + + + + .. note:: The ``region`` attribute/element can be omitted to make a cell + fill its entire universe. + + *Default*: A region filling all space. + + :temperature: + The temperature of the cell in Kelvin. If windowed-multipole data is + avalable, this temperature will be used to Doppler broaden some cross + sections in the resolved resonance region. A list of temperatures can be + specified for the "distributed temperature" feature. This will give each + unique instance of the cell its own temperature. + + *Default*: If a material default temperature is supplied, it is used. In the + absence of a material default temperature, the :ref:`global default + temperature ` is used. + + :rotation: + If the cell is filled with a universe, this element specifies the angles in + degrees about the x, y, and z axes that the filled universe should be + rotated. Should be given as three real numbers. For example, if you wanted + to rotate the filled universe by 90 degrees about the z-axis, the cell + element would look something like: + + .. code-block:: xml + + + + The rotation applied is an intrinsic rotation whose Tait-Bryan angles are + given as those specified about the x, y, and z axes respectively. That is to + say, if the angles are :math:`(\phi, \theta, \psi)`, then the rotation + matrix applied is :math:`R_z(\psi) R_y(\theta) R_x(\phi)` or + + .. math:: + + \left [ \begin{array}{ccc} \cos\theta \cos\psi & -\cos\theta \sin\psi + + \sin\phi \sin\theta \cos\psi & \sin\phi \sin\psi + \cos\phi \sin\theta + \cos\psi \\ \cos\theta \sin\psi & \cos\phi \cos\psi + \sin\phi \sin\theta + \sin\psi & -\sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\ + -\sin\theta & \sin\phi \cos\theta & \cos\phi \cos\theta \end{array} + \right ] + + *Default*: None + + :translation: + If the cell is filled with a universe, this element specifies a vector that + is used to translate (shift) the universe. Should be given as three real + numbers. + + .. note:: Any translation operation is applied after a rotation, if also + specified. + + *Default*: None + + +--------------------- +```` Element +--------------------- + +The ```` can be used to represent repeating structures (e.g. fuel pins +in an assembly) or other geometry which fits onto a rectilinear grid. Each cell +within the lattice is filled with a specified universe. A ```` accepts +the following attributes or sub-elements: + + :id: + A unique integer that can be used to identify the lattice. + + :name: + An optional string name to identify the lattice in summary output + files. This string is limited to 52 characters for formatting purposes. + + *Default*: "" + + :dimension: + Two or three integers representing the number of lattice cells in the x- and + y- (and z-) directions, respectively. + + *Default*: None + + :lower_left: + The coordinates of the lower-left corner of the lattice. If the lattice is + two-dimensional, only the x- and y-coordinates are specified. + + *Default*: None + + :pitch: + If the lattice is 3D, then three real numbers that express the distance + between the centers of lattice cells in the x-, y-, and z- directions. If + the lattice is 2D, then omit the third value. + + *Default*: None + + :outer: + The unique integer identifier of a universe that will be used to fill all + space outside of the lattice. The universe will be tiled repeatedly as if + it were placed in a lattice of infinite size. This element is optional. + + *Default*: An error will be raised if a particle leaves a lattice with no + outer universe. + + :universes: + A list of the universe numbers that fill each cell of the lattice. + + *Default*: None + +Here is an example of a properly defined 2d rectangular lattice: + +.. code-block:: xml + + + -1.5 -1.5 + 1.0 1.0 + + 2 2 2 + 2 1 2 + 2 2 2 + + + +------------------------- +```` Element +------------------------- + +The ```` can be used to represent repeating structures (e.g. fuel +pins in an assembly) or other geometry which naturally fits onto a hexagonal +grid or hexagonal prism grid. Each cell within the lattice is filled with a +specified universe. This lattice uses the "flat-topped hexagon" scheme where two +of the six edges are perpendicular to the y-axis. A ```` accepts +the following attributes or sub-elements: + + :id: + A unique integer that can be used to identify the lattice. + + :name: + An optional string name to identify the hex_lattice in summary output + files. This string is limited to 52 characters for formatting purposes. + + *Default*: "" + + :n_rings: + An integer representing the number of radial ring positions in the xy-plane. + Note that this number includes the degenerate center ring which only has one + element. + + *Default*: None + + :n_axial: + An integer representing the number of positions along the z-axis. This + element is optional. + + *Default*: None + + :center: + The coordinates of the center of the lattice. If the lattice does not have + axial sections then only the x- and y-coordinates are specified. + + *Default*: None + + :pitch: + If the lattice is 3D, then two real numbers that express the distance + between the centers of lattice cells in the xy-plane and along the z-axis, + respectively. If the lattice is 2D, then omit the second value. + + *Default*: None + + :outer: + The unique integer identifier of a universe that will be used to fill all + space outside of the lattice. The universe will be tiled repeatedly as if + it were placed in a lattice of infinite size. This element is optional. + + *Default*: An error will be raised if a particle leaves a lattice with no + outer universe. + + :universes: + A list of the universe numbers that fill each cell of the lattice. + + *Default*: None + +Here is an example of a properly defined 2d hexagonal lattice: + +.. code-block:: xml + + +
0.0 0.0
+ 1.0 + + 202 + 202 202 + 202 202 202 + 202 202 + 202 101 202 + 202 202 + 202 202 202 + 202 202 + 202 + + + +.. _constructive solid geometry: http://en.wikipedia.org/wiki/Constructive_solid_geometry + +.. _quadratic surfaces: http://en.wikipedia.org/wiki/Quadric diff --git a/docs/source/io_formats/index.rst b/docs/source/io_formats/index.rst index 6de9f199c8..f3eea21def 100644 --- a/docs/source/io_formats/index.rst +++ b/docs/source/io_formats/index.rst @@ -4,6 +4,23 @@ File Format Specifications ========================== +.. _io_file_formats_input: + +----------- +Input Files +----------- + +.. toctree:: + :numbered: + :maxdepth: 2 + + geometry + materials + settings + tallies + plots + cmfd + ---------- Data Files ---------- @@ -12,6 +29,7 @@ Data Files :numbered: :maxdepth: 2 + cross_sections nuclear_data mgxs_library data_wmp diff --git a/docs/source/io_formats/materials.rst b/docs/source/io_formats/materials.rst new file mode 100644 index 0000000000..fc57280f8b --- /dev/null +++ b/docs/source/io_formats/materials.rst @@ -0,0 +1,133 @@ +.. _io_materials: + +======================================== +Materials Specification -- materials.xml +======================================== + +.. _cross_sections: + +---------------------------- +```` Element +---------------------------- + +The ```` element has no attributes and simply indicates the path +to an XML cross section listing file (usually named cross_sections.xml). If this +element is absent from the settings.xml file, the +:envvar:`OPENMC_CROSS_SECTIONS` environment variable will be used to find the +path to the XML cross section listing when in continuous-energy mode, and the +:envvar:`OPENMC_MG_CROSS_SECTIONS` environment variable will be used in +multi-group mode. + +.. _multipole_library: + +------------------------------- +```` Element +------------------------------- + +The ```` element indicates the directory containing a +windowed multipole library. If a windowed multipole library is available, +OpenMC can use it for on-the-fly Doppler-broadening of resolved resonance range +cross sections. If this element is absent from the settings.xml file, the +:envvar:`OPENMC_MULTIPOLE_LIBRARY` environment variable will be used. + + .. note:: The element must also be set to "true" for + windowed multipole functionality. + +.. _material: + +---------------------- +```` Element +---------------------- + +Each ``material`` element can have the following attributes or sub-elements: + + :id: + A unique integer that can be used to identify the material. + + :name: + An optional string name to identify the material in summary output + files. This string is limited to 52 characters for formatting purposes. + + *Default*: "" + + :temperature: + An element with no attributes which is used to set the default temperature + of the material in Kelvin. + + *Default*: If a material default temperature is not given and a cell + temperature is not specified, the :ref:`global default temperature + ` 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`` + 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 ```` + and ```` sub-elements are to be interpreted as absolute nuclide/element + densities in atom/b-cm or g/cm3, and the total density of the material is + taken as the sum of all nuclides/elements. The "macro" unit is used with + 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. + + *Default*: None + + .. note:: A ``macroscopic`` quantity can not be used in conjunction with a + ``nuclide``, ``element``, or ``sab`` quantity. + + :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 + desired nuclide. Finally, the ``ao`` and ``wo`` attributes specify the atom or + weight percent of that nuclide within the material, respectively. One + example would be as follows: + + .. code-block:: xml + + + + + .. note:: If one nuclide is specified in atom percent, all others must also + be given in atom percent. The same applies for weight percentages. + + An optional attribute/sub-element for each nuclide is ``scattering``. This + attribute may be set to "data" to use the scattering laws specified by the + cross section library (default). Alternatively, when set to "iso-in-lab", + the scattering laws are used to sample the outgoing energy but an + isotropic-in-lab distribution is used to sample the outgoing angle at each + scattering interaction. The ``scattering`` attribute may be most useful + when using OpenMC to compute multi-group cross-sections for deterministic + transport codes and to quantify the effects of anisotropic scattering. + + *Default*: None + + .. note:: The ``scattering`` attribute/sub-element is not used in the + multi-group :ref:`energy_mode`. + + :sab: + Associates an S(a,b) table with the material. This element has one + attribute/sub-element called ``name``. The ``name`` attribute + is the name of the S(a,b) table that should be associated with the material. + + *Default*: None + + .. note:: This element is not used in the multi-group :ref:`energy_mode`. + + :macroscopic: + The ``macroscopic`` element is similar to the ``nuclide`` element, but, + recognizes that some multi-group libraries may be providing material + specific macroscopic cross sections instead of always providing nuclide + specific data like in the continuous-energy case. To that end, the + macroscopic element has one attribute/sub-element called ``name``. + The ``name`` attribute is the name of the cross-section for a + desired nuclide. One example would be as follows: + + .. code-block:: xml + + + + .. note:: This element is only used in the multi-group :ref:`energy_mode`. + + *Default*: None diff --git a/docs/source/io_formats/plots.rst b/docs/source/io_formats/plots.rst new file mode 100644 index 0000000000..4bfdaa8d53 --- /dev/null +++ b/docs/source/io_formats/plots.rst @@ -0,0 +1,192 @@ +.. _io_plots: + +============================================ +Geometry Plotting Specification -- plots.xml +============================================ + +Basic plotting capabilities are available in OpenMC by creating a plots.xml +file and subsequently running with the command-line flag ``-plot``. The root +element of the plots.xml is simply ```` and any number output plots can +be defined with ```` sub-elements. Two plot types are currently +implemented in openMC: + +* ``slice`` 2D pixel plot along one of the major axes. Produces a PPM image + file. +* ``voxel`` 3D voxel data dump. Produces a binary file containing voxel xyz + position and cell or material id. + + +------------------ +```` Element +------------------ + +Each plot is specified by a combination of the following attributes or +sub-elements: + + :id: + The unique ``id`` of the plot. + + *Default*: None - Required entry + + :filename: + Filename for the output plot file. + + *Default*: "plot" + + :color_by: + Keyword for plot coloring. This can be either "cell" or "material", which + colors regions by cells and materials, respectively. For voxel plots, this + determines which id (cell or material) is associated with each position. + + *Default*: "cell" + + :level: + Universe depth to plot at (optional). This parameter controls how many + universe levels deep to pull cell and material ids from when setting plot + colors. If a given location does not have as many levels as specified, + colors will be taken from the lowest level at that location. For example, if + ``level`` is set to zero colors will be taken from top-level (universe zero) + cells only. However, if ``level`` is set to 1 colors will be taken from + cells in universes that fill top-level fill-cells, and from top-level cells + that contain materials. + + *Default*: Whatever the deepest universe is in the model + + :origin: + Specifies the (x,y,z) coordinate of the center of the plot. Should be three + floats separated by spaces. + + *Default*: None - Required entry + + :width: + Specifies the width of the plot along each of the basis directions. Should + be two or three floats separated by spaces for 2D plots and 3D plots, + respectively. + + *Default*: None - Required entry + + :type: + Keyword for type of plot to be produced. Currently only "slice" and "voxel" + plots are implemented. The "slice" plot type creates 2D pixel maps saved in + the PPM file format. PPM files can be displayed in most viewers (e.g. the + default Gnome viewer, IrfanView, etc.). The "voxel" plot type produces a + binary datafile containing voxel grid positioning and the cell or material + (specified by the ``color`` tag) at the center of each voxel. These + datafiles can be processed into 3D SILO files using the + ``openmc-voxel-to-silovtk`` utility provided with the OpenMC source, and + subsequently viewed with a 3D viewer such as VISIT or Paraview. See the + :ref:`io_voxel` for information about the datafile structure. + + .. note:: Since the PPM format is saved without any kind of compression, + the resulting file sizes can be quite large. Saving the image in + the PNG format can often times reduce the file size by orders of + magnitude without any loss of image quality. Likewise, + high-resolution voxel files produced by OpenMC can be quite large, + but the equivalent SILO files will be significantly smaller. + + *Default*: "slice" + +```` elements of ``type`` "slice" and "voxel" must contain the ``pixels`` +attribute or sub-element: + + :pixels: + Specifies the number of pixels or voxels to be used along each of the basis + directions for "slice" and "voxel" plots, respectively. Should be two or + three integers separated by spaces. + + .. warning:: The ``pixels`` input determines the output file size. For the + PPM format, 10 million pixels will result in a file just under + 30 MB in size. A 10 million voxel binary file will be around + 40 MB. + + .. warning:: If the aspect ratio defined in ``pixels`` does not match the + aspect ratio defined in ``width`` the plot may appear stretched + or squeezed. + + .. warning:: Geometry features along a basis direction smaller than + ``width``/``pixels`` along that basis direction may not appear + in the plot. + + *Default*: None - Required entry for "slice" and "voxel" plots + +```` elements of ``type`` "slice" can also contain the following +attributes or sub-elements. These are not used in "voxel" plots: + + :basis: + Keyword specifying the plane of the plot for "slice" type plots. Can be + one of: "xy", "xz", "yz". + + *Default*: "xy" + + :background: + Specifies the RGB color of the regions where no OpenMC cell can be found. + Should be three integers separated by spaces. + + *Default*: 0 0 0 (black) + + :color: + Any number of this optional tag may be included in each ```` element, + which can override the default random colors for cells or materials. Each + ``color`` element must contain ``id`` and ``rgb`` sub-elements. + + :id: + Specifies the cell or material unique id for the color specification. + + :rgb: + Specifies the custom color for the cell or material. Should be 3 integers + separated by spaces. + + As an example, if your plot is colored by material and you want material 23 + to be blue, the corresponding ``color`` element would look like: + + .. code-block:: xml + + + + *Default*: None + + :mask: + The special ``mask`` sub-element allows for the selective plotting of *only* + user-specified cells or materials. Only one ``mask`` element is allowed per + ``plot`` element, and it must contain as attributes or sub-elements a + background masking color and a list of cells or materials to plot: + + :components: + List of unique ``id`` numbers of the cells or materials to plot. Should be + any number of integers separated by spaces. + + :background: + Color to apply to all cells or materials not in the ``components`` list of + cells or materials to plot. This overrides any ``color`` color + specifications. + + *Default*: 255 255 255 (white) + + :meshlines: + The ``meshlines`` sub-element allows for plotting the boundaries of a + regular mesh on top of a plot. Only one ``meshlines`` element is allowed per + ``plot`` element, and it must contain as attributes or sub-elements a mesh + type and a linewidth. Optionally, a color may be specified for the overlay: + + :meshtype: + The type of the mesh to be plotted. Valid options are "tally", "entropy", + "ufs", and "cmfd". If plotting "tally" meshes, the id of the mesh to plot + must be specified with the ``id`` sub-element. + + :id: + A single integer id number for the mesh specified on ``tallies.xml`` that + should be plotted. This element is only required for ``meshtype="tally"``. + + :linewidth: + A single integer number of pixels of linewidth to specify for the mesh + boundaries. Specifying this as 0 indicates that lines will be 1 pixel + thick, specifying 1 indicates 3 pixels thick, specifying 2 indicates + 5 pixels thick, etc. + + :color: + Specifies the custom color for the meshlines boundaries. Should be 3 + integers separated by whitespace. This element is optional. + + *Default*: 0 0 0 (black) + + *Default*: None diff --git a/docs/source/io_formats/settings.rst b/docs/source/io_formats/settings.rst new file mode 100644 index 0000000000..3b26eb84b8 --- /dev/null +++ b/docs/source/io_formats/settings.rst @@ -0,0 +1,856 @@ +.. _io_settings: + +====================================== +Settings Specification -- settings.xml +====================================== + +All simulation parameters and miscellaneous options are specified in the +settings.xml file. + +--------------------- +```` Element +--------------------- + +The ```` element indicates the total number of batches to execute, +where each batch corresponds to a tally realization. In a fixed source +calculation, each batch consists of a number of source particles. In an +eigenvalue calculation, each batch consists of one or many fission source +iterations (generations), where each generation itself consists of a number of +source neutrons. + + *Default*: None + +---------------------------------- +```` Element +---------------------------------- + +The ```` element has no attributes and has an accepted +value of "true" or "false". If set to "true", uncertainties on tally results +will be reported as the half-width of the 95% two-sided confidence interval. If +set to "false", uncertainties on tally results will be reported as the sample +standard deviation. + + *Default*: false + +-------------------- +```` Element +-------------------- + +The ```` element indicates two kinds of cutoffs. The first is the weight +cutoff used below which particles undergo Russian roulette. Surviving particles +are assigned a user-determined weight. Note that weight cutoffs and Russian +rouletting are not turned on by default. The second is the energy cutoff which +is used to kill particles under certain energy. The energy cutoff should not be +used unless you know particles under the energy are of no importance to results +you care. This element has the following attributes/sub-elements: + + :weight: + The weight below which particles undergo Russian roulette. + + *Default*: 0.25 + + :weight_avg: + The weight that is assigned to particles that are not killed after Russian + roulette. + + *Default*: 1.0 + + :energy: + The energy under which particles will be killed. + + *Default*: 0.0 + +------------------------- +```` Element +------------------------- + +The ```` element determines the treatment of the energy grid during +a simulation. The valid options are "nuclide", "logarithm", and +"material-union". Setting this element to "nuclide" will cause OpenMC to use a +nuclide's energy grid when determining what points to interpolate between for +determining cross sections (i.e. non-unionized energy grid). Setting this +element to "logarithm" causes OpenMC to use a logarithmic mapping technique +described in LA-UR-14-24530_. Setting this element to "material-union" will +cause OpenMC to create energy grids that are unionized material-by-material and +use these grids when determining the energy-cross section pairs to interpolate +cross section values between. + + *Default*: logarithm + + .. note:: This element is not used in the multi-group :ref:`energy_mode`. + +.. _LA-UR-14-24530: https://laws.lanl.gov/vhosts/mcnp.lanl.gov/pdf_files/la-ur-14-24530.pdf + +.. _energy_mode: + +------------------------- +```` Element +------------------------- + +The ```` element tells OpenMC if the run-mode should be +continuous-energy or multi-group. Options for entry are: ``continuous-energy`` +or ``multi-group``. + + *Default*: continuous-energy + +--------------------- +```` Element +--------------------- + +The ```` element describes a mesh that is used for calculating Shannon +entropy. This mesh should cover all possible fissionable materials in the +problem. It has the following attributes/sub-elements: + + :dimension: + The number of mesh cells in the x, y, and z directions, respectively. + + *Default*: If this tag is not present, the number of mesh cells is + automatically determined by the code. + + :lower_left: + The Cartesian coordinates of the lower-left corner of the mesh. + + *Default*: None + + :upper_right: + The Cartesian coordinates of the upper-right corner of the mesh. + + *Default*: None + +----------------------------------- +```` Element +----------------------------------- + +The ```` element indicates the number of total fission +source iterations per batch for an eigenvalue calculation. This element is +ignored for all run modes other than "eigenvalue". + + *Default*: 1 + +---------------------- +```` Element +---------------------- + +The ```` element indicates the number of inactive batches used in a +k-eigenvalue calculation. In general, the starting fission source iterations in +an eigenvalue calculation can not be used to contribute to tallies since the +fission source distribution and eigenvalue are generally not converged +immediately. This element is ignored for all run modes other than "eigenvalue". + + *Default*: 0 + +-------------------------- +```` Element +-------------------------- + +The ```` element (ignored for all run modes other than +"eigenvalue".) specifies a precision trigger on the combined +:math:`k_{eff}`. The trigger is a convergence criterion on the uncertainty of +the estimated eigenvalue. It has the following attributes/sub-elements: + + :type: + The type of precision trigger. Accepted options are "variance", "std_dev", + and "rel_err". + + :variance: + Variance of the batch mean :math:`\sigma^2` + + :std_dev: + Standard deviation of the batch mean :math:`\sigma` + + :rel_err: + Relative error of the batch mean :math:`\frac{\sigma}{\mu}` + + *Default*: None + + :threshold: + The precision trigger's convergence criterion for the + combined :math:`k_{eff}`. + + *Default*: None + +.. note:: See section on the :ref:`trigger` for more information. + + +--------------------------- +```` Element +--------------------------- + +The ```` element indicates the number of bins to use for the +logarithmic-mapped energy grid. Using more bins will result in energy grid +searches over a smaller range at the expense of more memory. The default is +based on the recommended value in LA-UR-14-24530_. + + *Default*: 8000 + + .. note:: This element is not used in the multi-group :ref:`energy_mode`. + +--------------------------- +```` Element +--------------------------- + +The ```` element allows the user to set a maximum scattering order +to apply to every nuclide/material in the problem. That is, if the data +library has :math:`P_3` data available, but ```` was set to ``1``, +then, OpenMC will only use up to the :math:`P_1` data. + + *Default*: Use the maximum order in the data library + + .. note:: This element is not used in the continuous-energy + :ref:`energy_mode`. + +----------------------- +```` Element +----------------------- + +The ```` element has no attributes and has an accepted value of +"true" or "false". If set to "true", all user-defined tallies and global tallies +will not be reduced across processors in a parallel calculation. This means that +the accumulate score in one batch on a single processor is considered as an +independent realization for the tally random variable. For a problem with large +tally data, this option can significantly improve the parallel efficiency. + + *Default*: false + +-------------------- +```` Element +-------------------- + +The ```` element determines what output files should be written to disk +during the run. The sub-elements are described below, where "true" will write +out the file and "false" will not. + + :cross_sections: + Writes out an ASCII summary file of the cross sections that were read in. + + *Default*: false + + :summary: + Writes out an HDF5 summary file describing all of the user input files that + were read in. + + *Default*: true + + :tallies: + Write out an ASCII file of tally results. + + *Default*: true + + .. note:: The tally results will always be written to a binary/HDF5 state + point file. + +------------------------- +```` Element +------------------------- + +The ```` element specifies an absolute or relative path where all +output files should be written to. The specified path must exist or else OpenMC +will abort. + + *Default*: Current working directory + +----------------------- +```` Element +----------------------- + +This element indicates the number of neutrons to simulate per fission source +iteration when a k-eigenvalue calculation is performed or the number of neutrons +per batch for a fixed source simulation. + + *Default*: None + +--------------------- +```` Element +--------------------- + +The ```` element determines whether probability tables should be used +in the unresolved resonance range if available. This element has no attributes +or sub-elements and can be set to either "false" or "true". + + *Default*: true + + .. note:: This element is not used in the multi-group :ref:`energy_mode`. + +---------------------------------- +```` Element +---------------------------------- + +The ``resonance_scattering`` element indicates to OpenMC that a method be used +to properly account for resonance elastic scattering (typically for nuclides +with Z > 40). This element can contain one or more of the following attributes +or sub-elements: + + :enable: + Indicates whether a resonance elastic scattering method should be turned + on. Accepts values of "true" or "false". + + *Default*: If the ```` element is present, "true". + + :method: + + Which resonance elastic scattering method is to be applied: "ares" + (accelerated resonance elastic scattering), "dbrc" (Doppler broadening + rejection correction), or "wcm" (weight correction method). Descriptions of + each of these methods are documented here_. + + .. _here: http://dx.doi.org/10.1016/j.anucene.2014.01.017 + + *Default*: "ares" + + :energy_min: + The energy in eV above which the resonance elastic scattering method should + be applied. + + *Default*: 0.01 eV + + :energy_max: + The energy in eV below which the resonance elastic scattering method should + be applied. + + *Default*: 1000.0 eV + + :nuclides: + + A list of nuclides to which the resonance elastic scattering method should + be applied. + + *Default*: If ```` is present but the ```` + sub-element is not given, the method is applied to all nuclides with 0 K + elastic scattering data present. + + .. note:: If the ``resonance_scattering`` element is not given, the free gas, + constant cross section scattering model, which has historically been + used by Monte Carlo codes to sample target velocities, is used to + treat the target motion of all nuclides. If + ``resonance_scattering`` is present, the constant cross section + method is applied below ``energy_min`` and the target-at-rest + (asymptotic) kernel is used above ``energy_max``. + + .. note:: This element is not used in the multi-group :ref:`energy_mode`. + +---------------------- +```` Element +---------------------- + +The ```` element indicates whether or not CMFD acceleration should be +turned on or off. This element has no attributes or sub-elements and can be set +to either "false" or "true". + + *Default*: false + +---------------------- +```` Element +---------------------- + +The ```` element indicates which run mode should be used when OpenMC +is executed. This element has no attributes or sub-elements and can be set to +"eigenvalue", "fixed source", "plot", "volume", or "particle restart". + + *Default*: None + +------------------ +```` Element +------------------ + +The ``seed`` element is used to set the seed used for the linear congruential +pseudo-random number generator. + + *Default*: 1 + +-------------------- +```` Element +-------------------- + +The ``source`` element gives information on an external source distribution to +be used either as the source for a fixed source calculation or the initial +source guess for criticality calculations. Multiple ```` elements may be +specified to define different source distributions. Each one takes the following +attributes/sub-elements: + + :strength: + The strength of the source. If multiple sources are present, the source + strength indicates the relative probability of choosing one source over the + other. + + *Default*: 1.0 + + :file: + If this attribute is given, it indicates that the source is to be read from + a binary source file whose path is given by the value of this element. Note, + the number of source sites needs to be the same as the number of particles + simulated in a fission source generation. + + *Default*: None + + :space: + An element specifying the spatial distribution of source sites. This element + has the following attributes: + + :type: + The type of spatial distribution. Valid options are "box", "fission", + "point", and "cartesian". A "box" spatial distribution has coordinates + sampled uniformly in a parallelepiped. A "fission" spatial distribution + samples locations from a "box" distribution but only locations in + fissionable materials are accepted. A "point" spatial distribution has + coordinates specified by a triplet. An "cartesian" spatial distribution + specifies independent distributions of x-, y-, and z-coordinates. + + *Default*: None + + :parameters: + For a "box" or "fission" spatial distribution, ``parameters`` should be + given as six real numbers, the first three of which specify the lower-left + corner of a parallelepiped and the last three of which specify the + upper-right corner. Source sites are sampled uniformly through that + parallelepiped. + + For a "point" spatial distribution, ``parameters`` should be given as + three real numbers which specify the (x,y,z) location of an isotropic + point source. + + For an "cartesian" distribution, no parameters are specified. Instead, + the ``x``, ``y``, and ``z`` elements must be specified. + + *Default*: None + + :x: + For an "cartesian" distribution, this element specifies the distribution + of x-coordinates. The necessary sub-elements/attributes are those of a + univariate probability distribution (see the description in + :ref:`univariate`). + + :y: + For an "cartesian" distribution, this element specifies the distribution + of y-coordinates. The necessary sub-elements/attributes are those of a + univariate probability distribution (see the description in + :ref:`univariate`). + + :z: + For an "cartesian" distribution, this element specifies the distribution + of z-coordinates. The necessary sub-elements/attributes are those of a + univariate probability distribution (see the description in + :ref:`univariate`). + + :angle: + An element specifying the angular distribution of source sites. This element + has the following attributes: + + :type: + The type of angular distribution. Valid options are "isotropic", + "monodirectional", and "mu-phi". The angle of the particle emitted from a + source site is isotropic if the "isotropic" option is given. The angle of + the particle emitted from a source site is the direction specified in the + ``reference_uvw`` element/attribute if "monodirectional" option is + given. The "mu-phi" option produces directions with the cosine of the + polar angle and the azimuthal angle explicitly specified. + + *Default*: isotropic + + :reference_uvw: + The direction from which the polar angle is measured. Represented by the + x-, y-, and z-components of a unit vector. For a monodirectional + distribution, this defines the direction of all sampled particles. + + :mu: + An element specifying the distribution of the cosine of the polar + angle. Only relevant when the type is "mu-phi". The necessary + sub-elements/attributes are those of a univariate probability distribution + (see the description in :ref:`univariate`). + + :phi: + An element specifying the distribution of the azimuthal angle. Only + relevant when the type is "mu-phi". The necessary sub-elements/attributes + are those of a univariate probability distribution (see the description in + :ref:`univariate`). + + :energy: + An element specifying the energy distribution of source sites. The necessary + sub-elements/attributes are those of a univariate probability distribution + (see the description in :ref:`univariate`). + + *Default*: Watt spectrum with :math:`a` = 0.988 MeV and :math:`b` = + 2.249 MeV :sup:`-1` + + :write_initial: + An element specifying whether to write out the initial source bank used at + the beginning of the first batch. The output file is named + "initial_source.h5" + + *Default*: false + +.. _univariate: + +Univariate Probability Distributions +++++++++++++++++++++++++++++++++++++ + +Various components of a source distribution involve probability distributions of +a single random variable, e.g. the distribution of the energy, the distribution +of the polar angle, and the distribution of x-coordinates. Each of these +components supports the same syntax with an element whose tag signifies the +variable and whose sub-elements/attributes are as follows: + +:type: + The type of the distribution. Valid options are "uniform", "discrete", + "tabular", "maxwell", and "watt". The "uniform" option produces variates + sampled from a uniform distribution over a finite interval. The "discrete" + option produces random variates that can assume a finite number of values + (i.e., a distribution characterized by a probability mass function). The + "tabular" option produces random variates sampled from a tabulated + distribution where the density function is either a histogram or + linearly-interpolated between tabulated points. The "watt" option produces + random variates is sampled from a Watt fission spectrum (only used for + energies). The "maxwell" option produce variates sampled from a Maxwell + fission spectrum (only used for energies). + + *Default*: None + +:parameters: + For a "uniform" distribution, ``parameters`` should be given as two real + numbers :math:`a` and :math:`b` that define the interval :math:`[a,b]` over + which random variates are sampled. + + For a "discrete" or "tabular" distribution, ``parameters`` provides the + :math:`(x,p)` pairs defining the discrete/tabular distribution. All :math:`x` + points are given first followed by corresponding :math:`p` points. + + For a "watt" distribution, ``parameters`` should be given as two real numbers + :math:`a` and :math:`b` that parameterize the distribution :math:`p(x) dx = c + e^{-x/a} \sinh \sqrt{b \, x} dx`. + + For a "maxwell" distribution, ``parameters`` should be given as one real + number :math:`a` that parameterizes the distribution :math:`p(x) dx = c x + e^{-x/a} dx`. + + .. note:: The above format should be used even when using the multi-group + :ref:`energy_mode`. +:interpolation: + For a "tabular" distribution, ``interpolation`` can be set to "histogram" or + "linear-linear" thereby specifying how tabular points are to be interpolated. + + *Default*: histogram + +------------------------- +```` Element +------------------------- + +The ```` element indicates at what batches a state point file +should be written. A state point file can be used to restart a run or to get +tally results at any batch. The default behavior when using this tag is to +write out the source bank in the state_point file. This behavior can be +customized by using the ```` element. This element has the +following attributes/sub-elements: + + :batches: + A list of integers separated by spaces indicating at what batches a state + point file should be written. + + *Default*: Last batch only + +-------------------------- +```` Element +-------------------------- + +The ```` element indicates at what batches the source bank +should be written. The source bank can be either written out within a state +point file or separately in a source point file. This element has the following +attributes/sub-elements: + + :batches: + A list of integers separated by spaces indicating at what batches a state + point file should be written. It should be noted that if the ``separate`` + attribute is not set to "true", this list must be a subset of state point + batches. + + *Default*: Last batch only + + :separate: + If this element is set to "true", a separate binary source point file will + be written. Otherwise, the source sites will be written in the state point + directly. + + *Default*: false + + :write: + If this element is set to "false", source sites are not written + to the state point or source point file. This can substantially reduce the + size of state points if large numbers of particles per batch are used. + + *Default*: true + + :overwrite_latest: + If this element is set to "true", a source point file containing + the source bank will be written out to a separate file named + ``source.binary`` or ``source.h5`` depending on if HDF5 is enabled. + This file will be overwritten at every single batch so that the latest + source bank will be available. It should be noted that a user can set both + this element to "true" and specify batches to write a permanent source bank. + + *Default*: false + +------------------------------ +```` Element +------------------------------ + +The ```` element has no attributes and has an accepted value +of "true" or "false". If set to "true", this option will enable the use of +survival biasing, otherwise known as implicit capture or absorption. + + *Default*: false + +.. _tabular_legendre: + +--------------------------------- +```` Element +--------------------------------- + +The optional ```` element specifies how the multi-group +Legendre scattering kernel is represented if encountered in a multi-group +problem. Specifically, the options are to either convert the Legendre +expansion to a tabular representation or leave it as a set of Legendre +coefficients. Converting to a tabular representation will cost memory but can +allow for a decrease in runtime compared to leaving as a set of Legendre +coefficients. This element has the following attributes/sub-elements: + + :enable: + This attribute/sub-element denotes whether or not the conversion of a + Legendre scattering expansion to the tabular format should be performed or + not. A value of “true” means the conversion should be performed, “false” + means it will not. + + *Default*: true + + :num_points: + If the conversion is to take place the number of tabular points is + required. This attribute/sub-element allows the user to set the desired + number of points. + + *Default*: 33 + + .. note:: This element is only used in the multi-group :ref:`energy_mode`. + +.. _temperature_default: + +--------------------------------- +```` Element +--------------------------------- + +The ```` element specifies a default temperature in Kelvin +that is to be applied to cells in the absence of an explicit cell temperature or +a material default temperature. + + *Default*: 293.6 K + +.. _temperature_method: + +-------------------------------- +```` Element +-------------------------------- + +The ```` element has an accepted value of "nearest" or +"interpolation". A value of "nearest" indicates that for each +cell, the nearest temperature at which cross sections are given is to be +applied, within a given tolerance (see :ref:`temperature_tolerance`). A value of +"interpolation" indicates that cross sections are to be linear-linear +interpolated between temperatures at which nuclear data are present (see +:ref:`temperature_treatment`). + + *Default*: "nearest" + +.. _temperature_multipole: + +----------------------------------- +```` Element +----------------------------------- + +The ```` element toggles the windowed multipole +capability on or off. If this element is set to "True" and the relevant data is +available, OpenMC will use the windowed multipole method to evaluate and Doppler +broaden cross sections in the resolved resonance range. This override other +methods like "nearest" and "interpolation" in the resolved resonance range. + + *Default*: False + +.. _temperature_tolerance: + +----------------------------------- +```` Element +----------------------------------- + +The ```` element specifies a tolerance in Kelvin that is +to be applied when the "nearest" temperature method is used. For example, if a +cell temperature is 340 K and the tolerance is 15 K, then the closest +temperature in the range of 325 K to 355 K will be used to evaluate cross +sections. + + *Default*: 10 K + +--------------------- +```` Element +--------------------- + +The ```` element indicates the number of OpenMP threads to be used for +a simulation. It has no attributes and accepts a positive integer value. + + *Default*: None (Determined by environment variable :envvar:`OMP_NUM_THREADS`) + +.. _trace: + +------------------- +```` Element +------------------- + +The ```` element can be used to print out detailed information about a +single particle during a simulation. This element should be followed by three +integers: the batch number, generation number, and particle number. + + *Default*: None + +.. _track: + +------------------- +```` Element +------------------- + +The ```` element specifies particles for which OpenMC will output binary +files describing particle position at every step of its transport. This element +should be followed by triplets of integers. Each triplet describes one +particle. The integers in each triplet specify the batch number, generation +number, and particle number, respectively. + + *Default*: None + +.. _trigger: + +------------------------- +```` Element +------------------------- + +OpenMC includes tally precision triggers which allow the user to define +uncertainty thresholds on :math:`k_{eff}` in the ```` subelement +of ``settings.xml``, and/or tallies in ``tallies.xml``. When using triggers, +OpenMC will run until it completes as many batches as defined by ````. +At this point, the uncertainties on all tallied values are computed and compared +with their corresponding trigger thresholds. If any triggers have not been met, +OpenMC will continue until either all trigger thresholds have been satisfied or +```` has been reached. + +The ```` element provides an active "toggle switch" for tally +precision trigger(s), the maximum number of batches and the batch interval. It +has the following attributes/sub-elements: + + :active: + This determines whether or not to use trigger(s). Trigger(s) are used when + this tag is set to "true". + + :max_batches: + This describes the maximum number of batches allowed when using trigger(s). + + .. note:: When max_batches is set, the number of ``batches`` shown in the + ```` element represents minimum number of batches to + simulate when using the trigger(s). + + :batch_interval: + This tag describes the number of batches in between convergence checks. + OpenMC will check if the trigger has been reached at each batch defined + by ``batch_interval`` after the minimum number of batches is reached. + + .. note:: If this tag is not present, the ``batch_interval`` is predicted + dynamically by OpenMC for each convergence check. The predictive + model assumes no correlation between fission sources + distributions from batch-to-batch. This assumption is reasonable + for fixed source and small criticality calculations, but is very + optimistic for highly coupled full-core reactor problems. + + +------------------------ +```` Element +------------------------ + +The ```` element describes a mesh that is used for re-weighting +source sites at every generation based on the uniform fission site methodology +described in Kelly et al., "MC21 Analysis of the Nuclear Energy Agency Monte +Carlo Performance Benchmark Problem," Proceedings of *Physor 2012*, Knoxville, +TN (2012). This mesh should cover all possible fissionable materials in the +problem. It has the following attributes/sub-elements: + + :dimension: + The number of mesh cells in the x, y, and z directions, respectively. + + *Default*: None + + :lower_left: + The Cartesian coordinates of the lower-left corner of the mesh. + + *Default*: None + + :upper_right: + The Cartesian coordinates of the upper-right corner of the mesh. + + *Default*: None + +.. _verbosity: + +----------------------- +```` Element +----------------------- + +The ```` element tells the code how much information to display to +the standard output. A higher verbosity corresponds to more information being +displayed. The text of this element should be an integer between between 1 +and 10. The verbosity levels are defined as follows: + + :1: don't display any output + :2: only show OpenMC logo + :3: all of the above + headers + :4: all of the above + results + :5: all of the above + file I/O + :6: all of the above + timing statistics and initialization messages + :7: all of the above + :math:`k` by generation + :9: all of the above + indicate when each particle starts + :10: all of the above + event information + + *Default*: 7 + +------------------------------------- +```` Element +------------------------------------- + +The ```` element indicates whether fission neutrons +should be created or not. If this element is set to "true", fission neutrons +will be created; otherwise the fission is treated as capture and no fission +neutron will be created. Note that this option is only applied to fixed source +calculation. For eigenvalue calculation, fission will always be treated as real +fission. + + *Default*: true + + +------------------------- +```` Element +------------------------- + +The ```` element indicates that a stochastic volume calculation +should be run at the beginning of the simulation. This element has the following +sub-elements/attributes: + + :cells: + The unique IDs of cells for which the volume should be estimated. + + *Default*: None + + :samples: + The number of samples used to estimate volumes. + + *Default*: None + + :lower_left: + The lower-left Cartesian coordinates of a bounding box that is used to + sample points within. + + *Default*: None + + :upper_right: + The upper-right Cartesian coordinates of a bounding box that is used to + sample points within. + + *Default*: None diff --git a/docs/source/io_formats/tallies.rst b/docs/source/io_formats/tallies.rst new file mode 100644 index 0000000000..b64b5a7761 --- /dev/null +++ b/docs/source/io_formats/tallies.rst @@ -0,0 +1,583 @@ +.. _io_tallies: + +==================================== +Tallies Specification -- tallies.xml +==================================== + +The tallies.xml file allows the user to tell the code what results he/she is +interested in, e.g. the fission rate in a given cell or the current across a +given surface. There are two pieces of information that determine what +quantities should be scored. First, one needs to specify what region of phase +space should count towards the tally and secondly, the actual quantity to be +scored also needs to be specified. The first set of parameters we call *filters* +since they effectively serve to filter events, allowing some to score and +preventing others from scoring to the tally. + +The structure of tallies in OpenMC is flexible in that any combination of +filters can be used for a tally. The following types of filter are available: +cell, universe, material, surface, birth region, pre-collision energy, +post-collision energy, and an arbitrary structured mesh. + +The three valid elements in the tallies.xml file are ````, ````, +and ````. + +.. _tally: + +------------------- +```` Element +------------------- + +The ```` element accepts the following sub-elements: + + :name: + An optional string name to identify the tally in summary output + files. This string is limited to 52 characters for formatting purposes. + + *Default*: "" + + :filter: + Specify a filter that modifies tally behavior. Most tallies (e.g. ``cell``, + ``energy``, and ``material``) restrict the tally so that only particles + within certain regions of phase space contribute to the tally. Others + (e.g. ``delayedgroup`` and ``energyfunction``) can apply some other function + to the scored values. This element and its attributes/sub-elements are + described below. + + .. note:: + You may specify zero, one, or multiple filters to apply to the tally. To + specify multiple filters, you must use multiple ```` elements. + + The ``filter`` element has the following attributes/sub-elements: + + :type: + The type of the filter. Accepted options are "cell", "cellborn", + "material", "universe", "energy", "energyout", "mu", "polar", + "azimuthal", "mesh", "distribcell", "delayedgroup", and + "energyfunction". + + :bins: + A description of the bins for each type of filter can be found in + :ref:`filter_types`. + + :energy: + ``energyfunction`` filters multiply tally scores by an arbitrary + function. The function is described by a piecewise linear-linear set of + (energy, y) values. This entry specifies the energy values. The function + will be evaluated as zero outside of the bounds of this energy grid. + (Only used for ``energyfunction`` filters) + + :y: + ``energyfunction`` filters multiply tally scores by an arbitrary + function. The function is described by a piecewise linear-linear set of + (energy, y) values. This entry specifies the y values. (Only used + for ``energyfunction`` filters) + + :nuclides: + If specified, the scores listed will be for particular nuclides, not the + summation of reactions from all nuclides. The format for nuclides should be + [Atomic symbol]-[Mass number], e.g. "U-235". The reaction rate for all + nuclides can be obtained with "total". For example, to obtain the reaction + rates for U-235, Pu-239, and all nuclides in a material, this element should + be: + + .. code-block:: xml + + U-235 Pu-239 total + + *Default*: total + + :estimator: + The estimator element is used to force the use of either ``analog``, + ``collision``, or ``tracklength`` tally estimation. ``analog`` is generally + the least efficient though it can be used with every score type. + ``tracklength`` is generally the most efficient, but neither ``tracklength`` + nor ``collision`` can be used to score a tally that requires post-collision + information. For example, a scattering tally with outgoing energy filters + cannot be used with ``tracklength`` or ``collision`` because the code will + not know the outgoing energy distribution. + + *Default*: ``tracklength`` but will revert to ``analog`` if necessary. + + :scores: + A space-separated list of the desired responses to be accumulated. The accepted + options are listed in the following tables: + + .. table:: **Flux scores: units are particle-cm per source particle.** + + +----------------------+---------------------------------------------------+ + |Score | Description | + +======================+===================================================+ + |flux |Total flux. | + +----------------------+---------------------------------------------------+ + |flux-YN |Spherical harmonic expansion of the direction of | + | |motion :math:`\left(\Omega\right)` of the total | + | |flux. This score will tally all of the harmonic | + | |moments of order 0 to N. N must be between 0 and | + | |10. | + +----------------------+---------------------------------------------------+ + + .. table:: **Reaction scores: units are reactions per source particle.** + + +----------------------+---------------------------------------------------+ + |Score | Description | + +======================+===================================================+ + |absorption |Total absorption rate. This accounts for all | + | |reactions which do not produce secondary neutrons | + | |as well as fission. | + +----------------------+---------------------------------------------------+ + |elastic |Elastic scattering reaction rate. | + +----------------------+---------------------------------------------------+ + |fission |Total fission reaction rate. | + +----------------------+---------------------------------------------------+ + |scatter |Total scattering rate. Can also be identified with | + | |the "scatter-0" response type. | + +----------------------+---------------------------------------------------+ + |scatter-N |Tally the N\ :sup:`th` \ scattering moment, where N| + | |is the Legendre expansion order of the change in | + | |particle angle :math:`\left(\mu\right)`. N must be | + | |between 0 and 10. As an example, tallying the 2\ | + | |:sup:`nd` \ scattering moment would be specified as| + | |``scatter-2``. | + +----------------------+---------------------------------------------------+ + |scatter-PN |Tally all of the scattering moments from order 0 to| + | |N, where N is the Legendre expansion order of the | + | |change in particle angle | + | |:math:`\left(\mu\right)`. That is, "scatter-P1" is | + | |equivalent to requesting tallies of "scatter-0" and| + | |"scatter-1". Like for "scatter-N", N must be | + | |between 0 and 10. As an example, tallying up to the| + | |2\ :sup:`nd` \ scattering moment would be specified| + | |as `` scatter-P2 ``. | + +----------------------+---------------------------------------------------+ + |scatter-YN |"scatter-YN" is similar to "scatter-PN" except an | + | |additional expansion is performed for the incoming | + | |particle direction :math:`\left(\Omega\right)` | + | |using the real spherical harmonics. This is useful| + | |for performing angular flux moment weighting of the| + | |scattering moments. Like "scatter-PN", "scatter-YN"| + | |will tally all of the moments from order 0 to N; N | + | |again must be between 0 and 10. | + +----------------------+---------------------------------------------------+ + |total |Total reaction rate. | + +----------------------+---------------------------------------------------+ + |total-YN |The total reaction rate expanded via spherical | + | |harmonics about the direction of motion of the | + | |neutron, :math:`\Omega`. This score will tally all | + | |of the harmonic moments of order 0 to N. N must be| + | |between 0 and 10. | + +----------------------+---------------------------------------------------+ + |(n,2nd) |(n,2nd) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,2n) |(n,2n) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,3n) |(n,3n) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,na) |(n,n\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,n3a) |(n,n3\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,2na) |(n,2n\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,3na) |(n,3n\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,np) |(n,np) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,n2a) |(n,n2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,2n2a) |(n,2n2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,nd) |(n,nd) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,nt) |(n,nt) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,nHe-3) |(n,n\ :sup:`3`\ He) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,nd2a) |(n,nd2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,nt2a) |(n,nt2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,4n) |(n,4n) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,2np) |(n,2np) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,3np) |(n,3np) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,n2p) |(n,n2p) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,n*X*) |Level inelastic scattering reaction rate. The *X* | + | |indicates what which inelastic level, e.g., (n,n3) | + | |is third-level inelastic scattering. | + +----------------------+---------------------------------------------------+ + |(n,nc) |Continuum level inelastic scattering reaction rate.| + +----------------------+---------------------------------------------------+ + |(n,gamma) |Radiative capture reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,p) |(n,p) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,d) |(n,d) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,t) |(n,t) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,3He) |(n,\ :sup:`3`\ He) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,a) |(n,\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,2a) |(n,2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,3a) |(n,3\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,2p) |(n,2p) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,pa) |(n,p\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,t2a) |(n,t2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,d2a) |(n,d2\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,pd) |(n,pd) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,pt) |(n,pt) reaction rate. | + +----------------------+---------------------------------------------------+ + |(n,da) |(n,d\ :math:`\alpha`\ ) reaction rate. | + +----------------------+---------------------------------------------------+ + |*Arbitrary integer* |An arbitrary integer is interpreted to mean the | + | |reaction rate for a reaction with a given ENDF MT | + | |number. | + +----------------------+---------------------------------------------------+ + + .. table:: **Particle production scores: units are particles produced per + source particles.** + + +----------------------+---------------------------------------------------+ + |Score | Description | + +======================+===================================================+ + |delayed-nu-fission |Total production of delayed neutrons due to | + | |fission. | + +----------------------+---------------------------------------------------+ + |prompt-nu-fission |Total production of prompt neutrons due to | + | |fission. | + +----------------------+---------------------------------------------------+ + |nu-fission |Total production of neutrons due to fission. | + +----------------------+---------------------------------------------------+ + |nu-scatter, |These scores are similar in functionality to their | + |nu-scatter-N, |``scatter*`` equivalents except the total | + |nu-scatter-PN, |production of neutrons due to scattering is scored | + |nu-scatter-YN |vice simply the scattering rate. This accounts for | + | |multiplicity from (n,2n), (n,3n), and (n,4n) | + | |reactions. | + +----------------------+---------------------------------------------------+ + + .. table:: **Miscellaneous scores: units are indicated for each.** + + +----------------------+---------------------------------------------------+ + |Score | Description | + +======================+===================================================+ + |current |Partial currents on the boundaries of each cell in | + | |a mesh. Units are particles per source | + | |particle. Note that this score can only be used if | + | |a mesh filter has been specified. Furthermore, it | + | |may not be used in conjunction with any other | + | |score. | + +----------------------+---------------------------------------------------+ + |events |Number of scoring events. Units are events per | + | |source particle. | + +----------------------+---------------------------------------------------+ + |inverse-velocity |The flux-weighted inverse velocity where the | + | |velocity is in units of centimeters per second. | + +----------------------+---------------------------------------------------+ + |kappa-fission |The recoverable energy production rate due to | + | |fission. The recoverable energy is defined as the | + | |fission product kinetic energy, prompt and delayed | + | |neutron kinetic energies, prompt and delayed | + | |:math:`\gamma`-ray total energies, and the total | + | |energy released by the delayed :math:`\beta` | + | |particles. The neutrino energy does not contribute | + | |to this response. The prompt and delayed | + | |:math:`\gamma`-rays are assumed to deposit their | + | |energy locally. Units are eV per source particle. | + +----------------------+---------------------------------------------------+ + |fission-q-prompt |The prompt fission energy production rate. This | + | |energy comes in the form of fission fragment | + | |nuclei, prompt neutrons, and prompt | + | |:math:`\gamma`-rays. This value depends on the | + | |incident energy and it requires that the nuclear | + | |data library contains the optional fission energy | + | |release data. Energy is assumed to be deposited | + | |locally. Units are eV per source particle. | + +----------------------+---------------------------------------------------+ + |fission-q-recoverable |The recoverable fission energy production rate. | + | |This energy comes in the form of fission fragment | + | |nuclei, prompt and delayed neutrons, prompt and | + | |delayed :math:`\gamma`-rays, and delayed | + | |:math:`\beta`-rays. This tally differs from the | + | |kappa-fission tally in that it is dependent on | + | |incident neutron energy and it requires that the | + | |nuclear data library contains the optional fission | + | |energy release data. Energy is assumed to be | + | |deposited locally. Units are eV per source | + | |paticle. | + +----------------------+---------------------------------------------------+ + |decay-rate |The delayed-nu-fission-weighted decay rate where | + | |the decay rate is in units of inverse seconds. | + +----------------------+---------------------------------------------------+ + + .. note:: + The ``analog`` estimator is actually identical to the ``collision`` + estimator for the flux and inverse-velocity scores. + + :trigger: + Precision trigger applied to all filter bins and nuclides for this tally. + It must specify the trigger's type, threshold and scores to which it will + be applied. It has the following attributes/sub-elements: + + :type: + The type of the trigger. Accepted options are "variance", "std_dev", + and "rel_err". + + :variance: + Variance of the batch mean :math:`\sigma^2` + + :std_dev: + Standard deviation of the batch mean :math:`\sigma` + + :rel_err: + Relative error of the batch mean :math:`\frac{\sigma}{\mu}` + + *Default*: None + + :threshold: + The precision trigger's convergence criterion for tallied values. + + *Default*: None + + :scores: + The score(s) in this tally to which the trigger should be applied. + + .. note:: The ``scores`` in ``trigger`` must have been defined in + ``scores`` in ``tally``. An optional "all" may be used to + select all scores in this tally. + + *Default*: "all" + + :derivative: + The id of a ``derivative`` element. This derivative will be applied to all + scores in the tally. Differential tallies are currently only implemented + for collision and analog estimators. + + *Default*: None + +.. _filter_types: + +Filter Types +++++++++++++ + +For each filter type, the following table describes what the ``bins`` attribute +should be set to: + +:cell: + A list of unique IDs for cells in which the tally should be accumulated. + +:cellborn: + This filter allows the tally to be scored to only when particles were + originally born in a specified cell. A list of cell IDs should be given. + +:material: + A list of unique IDs for matreials in which the tally should be accumulated. + +:universe: + A list of unique IDs for universes in which the tally should be accumulated. + +:energy: + In continuous-energy mode, this filter should be provided as a + monotonically increasing list of bounding **pre-collision** energies + for a number of groups. For example, if this filter is specified as + + .. code-block:: xml + + + + then two energy bins will be created, one with energies between 0 and + 1 MeV and the other with energies between 1 and 20 MeV. + + In multi-group mode the bins provided must match group edges + defined in the multi-group library. + +:energyout: + In continuous-energy mode, this filter should be provided as a + monotonically increasing list of bounding **post-collision** energies + for a number of groups. For example, if this filter is specified as + + .. code-block:: xml + + + + then two post-collision energy bins will be created, one with + energies between 0 and 1 MeV and the other with energies between + 1 and 20 MeV. + + In multi-group mode the bins provided must match group edges + defined in the multi-group library. + +:mu: + A monotonically increasing list of bounding **post-collision** cosines + of the change in a particle's angle (i.e., :math:`\mu = \hat{\Omega} + \cdot \hat{\Omega}'`), which represents a portion of the possible + values of :math:`[-1,1]`. For example, spanning all of :math:`[-1,1]` + with five equi-width bins can be specified as: + + .. code-block:: xml + + + + Alternatively, if only one value is provided as a bin, OpenMC will + interpret this to mean the complete range of :math:`[-1,1]` should + be automatically subdivided in to the provided value for the bin. + That is, the above example of five equi-width bins spanning + :math:`[-1,1]` can be instead written as: + + .. code-block:: xml + + + +:polar: + A monotonically increasing list of bounding particle polar angles + which represents a portion of the possible values of :math:`[0,\pi]`. + For example, spanning all of :math:`[0,\pi]` with five equi-width + bins can be specified as: + + .. code-block:: xml + + + + Alternatively, if only one value is provided as a bin, OpenMC will + interpret this to mean the complete range of :math:`[0,\pi]` should + be automatically subdivided in to the provided value for the bin. + That is, the above example of five equi-width bins spanning + :math:`[0,\pi]` can be instead written as: + + .. code-block:: xml + + + +:azimuthal: + A monotonically increasing list of bounding particle azimuthal angles + which represents a portion of the possible values of :math:`[-\pi,\pi)`. + For example, spanning all of :math:`[-\pi,\pi)` with two equi-width + bins can be specified as: + + .. code-block:: xml + + + + Alternatively, if only one value is provided as a bin, OpenMC will + interpret this to mean the complete range of :math:`[-\pi,\pi)` should + be automatically subdivided in to the provided value for the bin. + That is, the above example of five equi-width bins spanning + :math:`[-\pi,\pi)` can be instead written as: + + .. code-block:: xml + + + +:mesh: + The unique ID of a structured mesh to be tallied over. + +:distribcell: + The single cell which should be tallied uniquely for all instances. + + .. note:: The distribcell filter will take a single cell ID and will tally + each unique occurrence of that cell separately. This filter will not + accept more than one cell ID. It is not recommended to combine this + filter with a cell or mesh filter. + +:delayedgroup: + A list of delayed neutron precursor groups for which the tally should + be accumulated. For instance, to tally to all 6 delayed groups in the + ENDF/B-VII.1 library the filter is specified as: + + .. code-block:: xml + + + +:energyfunction: + ``energyfunction`` filters do not use the ``bins`` entry. Instead + they use ``energy`` and ``y``. + + +------------------ +```` Element +------------------ + +If a structured mesh is desired as a filter for a tally, it must be specified in +a separate element with the tag name ````. This element has the following +attributes/sub-elements: + + :type: + The type of structured mesh. The only valid option is "regular". + + :dimension: + The number of mesh cells in each direction. + + :lower_left: + The lower-left corner of the structured mesh. If only two coordinates are + given, it is assumed that the mesh is an x-y mesh. + + :upper_right: + The upper-right corner of the structured mesh. If only two coordinates are + given, it is assumed that the mesh is an x-y mesh. + + :width: + The width of mesh cells in each direction. + + .. note:: + One of ```` or ```` must be specified, but not both + (even if they are consistent with one another). + +------------------------ +```` Element +------------------------ + +OpenMC can take the first-order derivative of many tallies with respect to +material perturbations. It works by propagating a derivative through the +transport equation. Essentially, OpenMC keeps track of how each particle's +weight would change as materials are perturbed, and then accounts for that +weight change in the tallies. Note that this assumes material perturbations are +small enough not to change the distribution of fission sites. This element has +the following attributes/sub-elements: + + :id: + A unique integer that can be used to identify the derivative. + + :variable: + The independent variable of the derivative. Accepted options are "density", + "nuclide_density", and "temperature". A "density" derivative will give the + derivative with respect to the density of the material in [g / cm^3]. A + "nuclide_density" derivative will give the derivative with respect to the + density of a particular nuclide in units of [atom / b / cm]. A + "temperature" derivative is with respect to a material temperature in units + of [K]. The temperature derivative requires windowed multipole to be + turned on. Note also that the temperature derivative only accounts for + resolved resonance Doppler broadening. It does not account for thermal + expansion, S(a, b) scattering, resonance scattering, or unresolved Doppler + broadening. + + :material: + The perturbed material. (Necessary for all derivative types) + + :nuclide: + The perturbed nuclide. (Necessary only for "nuclide_density") + +----------------------------- +```` Element +----------------------------- + +In cases where the user needs to specify many different tallies each of which +are spatially separate, this tag can be used to cut down on some of the tally +overhead. The effect of assuming all tallies are spatially separate is that once +one tally is scored to, the same event is assumed not to score to any other +tallies. This element should be followed by "true" or "false". + + .. warning:: If used incorrectly, the assumption that all tallies are + spatially separate can lead to incorrect results. + + *Default*: false diff --git a/docs/source/methods/cmfd.rst b/docs/source/methods/cmfd.rst index 9403933fd6..a1dcc4847c 100644 --- a/docs/source/methods/cmfd.rst +++ b/docs/source/methods/cmfd.rst @@ -402,7 +402,7 @@ information: It should be noted that for more difficult simulations (e.g., light water reactors), there are other options available to users such as tally resetting parameters, effective down-scatter usage, tally estimator, etc. For more -information please see :ref:`usersguide_cmfd`. +information please see :ref:`io_cmfd`. Of the options described above, the optional acceleration subset region is an uncommon feature. Because OpenMC only has a structured Cartesian mesh, mesh diff --git a/docs/source/usersguide/basics.rst b/docs/source/usersguide/basics.rst new file mode 100644 index 0000000000..0633212df5 --- /dev/null +++ b/docs/source/usersguide/basics.rst @@ -0,0 +1,154 @@ +.. _usersguide_basics: + +====================== +Basics of Using OpenMC +====================== + +----------- +Input Files +----------- + +When you build and install OpenMC, you will have an :ref:`scripts_openmc` +executable on your system. When you run ``openmc``, the first thing it will do +is look for a set of XML_ files that describe the model you want to +simulation. Three of these files are required and another three are optional, as +described below. + +.. admonition:: Required + :class: error + + :ref:`io_materials` + This file describes what materials are present in the problem and what they + are composed of. Additionally, it indicates where OpenMC should look for a + cross section library. + + :ref:`io_geometry` + This file describes how the materials defined in ``materials.xml`` occupy + regions of space. Physical volumes are defined using constructive solid + geometry, described in detail in FIXME. + + :ref:`io_settings` + This file indicates what mode OpenMC should be run in, how many particles + to simulate, the source definition, and a whole host of miscellaneous + options. + +.. admonition:: Optional + :class: note + + :ref:`io_tallies` + This file describes what physical quantities should be tallied during the + simulation (fluxes, reaction rates, currents, etc.). + + :ref:`io_plots` + This file gives specifications for producing slice or voxel plots of the + geometry. + + :ref:`io_cmfd` + This file specifies execution parameters for coarse mesh finite difference + (CMFD) acceleration. + +eXtensible Markup Language (XML) +-------------------------------- + +Unlike many other Monte Carlo codes which use an arbitrary-format ASCII file +with "cards" to specify a particular geometry, materials, and associated run +settings, the input files for OpenMC are structured in a set of XML_ files. XML, +which stands for eXtensible Markup Language, is a simple format that allows data +to be exchanged efficiently between different programs and interfaces. + +Anyone who has ever seen webpages written in HTML will be familiar with the +structure of XML whereby "tags" enclosed in angle brackets denote that a +particular piece of data will follow. Let us examine the follow example: + +.. code-block:: xml + + + John + Smith + 27 + Health Physicist + + +Here we see that the first tag indicates that the following data will describe a +person. The nested tags *firstname*, *lastname*, *age*, and *occupation* +indicate characteristics about the person being described. + +In much the same way, OpenMC input uses XML tags to describe the geometry, the +materials, and settings for a Monte Carlo simulation. Note that because the XML +files have a well-defined structure, they can be validated using the +:ref:`scripts_validate` script. + +.. _XML: http://www.w3.org/XML/ + +Creating Input Files +-------------------- + +.. currentmodule:: openmc + +The simplest option to create input files is to simply write them from scratch +using the :ref:`XML format specifications `. This +approach will feel familiar to users of other Monte Carlo codes such as MCNP and +Serpent, with the added bonus that the XML formats feel much more "readable". + +Alternatively, input files can be generated using OpenMC's :ref:`pythonapi`. The +Python API defines a set of functions and classes that roughly correspond to +elements in the XML files. For example, the :class:`openmc.Cell` Python class +directly corresponds to the :ref:`cell_element` in XML. Each XML file itself +also has a corresponding class: :class:`openmc.Geometry` for ``geometry.xml``, +:class:`openmc.Materials` for ``materials.xml``, :class:`openmc.Settings` for +``settings.xml``, and so on. To create a model then, one creates instances of +these classes and then uses the ``export_to_xml()`` method, +e.g. :meth:`Geometry.export_to_xml`. Most scripts that generate a full model +will look something like the following: + +.. code-block:: Python + + # Create materials + materials = openmc.Materials() + ... + materials.export_to_xml() + + # Create geometry + geom = openmc.Geometry() + ... + geom.export_to_xml() + + # Assign simulation settings + settings = openmc.Settings() + ... + settings.export_to_xml() + +One a model has been created and exported to XML, a simulation can be run either +by calling :ref:`scripts_openmc` directly from a shell or by using the +:func:`openmc.run()` function from Python. + +.. tip:: Users are strongly encouraged to use the Python API to generate input + files and analyze results. + +-------------- +Physical Units +-------------- + +Unless specified otherwise, all length quantities are assumed to be in units of +centimeters, all energy quantities are assumed to be in electronvolts, and all +time quantities are assumed to be in seconds. + +======= ============ ====== +Measure Default unit Symbol +======= ============ ====== +length centimeter cm +energy electronvolt eV +time second s +======= ============ ====== + +------------------------------------ +ERSN-OpenMC Graphical User Interface +------------------------------------ + +A third-party Java-based user-friendly graphical user interface for creating XML +input files called ERSN-OpenMC_ is developed and maintained by members of the +Radiation and Nuclear Systems Group at the Faculty of Sciences Tetouan, Morocco. +The GUI also allows one to automatically download prerequisites for installing and +running OpenMC. + +.. _ERSN-OpenMC: https://github.com/EL-Bakkali-Jaafar/ERSN-OpenMC diff --git a/docs/source/usersguide/beginners.rst b/docs/source/usersguide/beginners.rst index 2487e9c416..22b09a24d3 100644 --- a/docs/source/usersguide/beginners.rst +++ b/docs/source/usersguide/beginners.rst @@ -8,33 +8,35 @@ A Beginner's Guide to OpenMC What does OpenMC do? -------------------- -In a nutshell, OpenMC simulates neutrons moving around randomly in a `nuclear -reactor`_ (or other fissile system). This is what's known as `Monte Carlo`_ -simulation. Neutrons are important in nuclear reactors because they are the -particles that induce `fission`_ in uranium and other nuclides. Knowing the -behavior of neutrons allows you to determine how often and where fission -occurs. The amount of energy released is then directly proportional to the -fission reaction rate since most heat is produced by fission. By simulating many -neutrons (millions or billions), it is possible to determine the average -behavior of these neutrons (or the behavior of the energy produced or any other -quantity one is interested in) very accurately. +In a nutshell, OpenMC simulates neutral particles (presently only neutrons) +moving stochastically through an arbitrarily defined model that represents an +real-world experimental setup. The experiment could be as simple as a sphere of +metal or as complicated as a full-scale `nuclear reactor`_. This is what's known +as `Monte Carlo`_ simulation. In the case of a nuclear reactor model, neutrons +are especially important because they are the particles that induce `fission`_ +in isotopes of uranium and other elements. Knowing the behavior of neutrons +allows one to determine how often and where fission occurs. The amount of energy +released is then directly proportional to the fission reaction rate since most +heat is produced by fission. By simulating many neutrons (millions or billions), +it is possible to determine the average behavior of these neutrons (or the +behavior of the energy produced, or any other quantity one is interested in) +very accurately. Using Monte Carlo methods to determine the average behavior of various physical -quantities in a nuclear reactor is quite different from other means of solving -the same problem. The other class of methods for determining the behavior of -neutrons and reactions rates in a reactor is so-called `deterministic`_ -methods. In these methods, the starting point is not randomly simulating -particles but rather writing an equation that describes the average behavior of -the particles. The equation that describes the average behavior of neutrons is -called the `neutron transport`_ equation. This equation is a seven-dimensional -equation (three for space, three for velocity, and one for time) and is very -difficult to solve directly. For all but the simplest problems, it is necessary -to make some sort of `discretization`_. As an example, we can divide up all -space into small sections which are homogeneous and then solve the equation on -those small sections. After these discretizations and various approximations, -one can arrive at forms that are suitable for solution on a computer. Among -these are discrete ordinates, method of characteristics, finite-difference -diffusion, and nodal methods. +quantities in a system is quite different from other means of solving the same +problem. The other class of methods for determining the behavior of neutrons and +reactions rates is so-called `deterministic`_ methods. In these methods, the +starting point is not randomly simulating particles but rather writing an +equation that describes the average behavior of the particles. The equation that +describes the average behavior of neutrons is called the `neutron transport`_ +equation. This equation is a seven-dimensional equation (three for space, three +for velocity, and one for time) and is very difficult to solve directly. For all +but the simplest problems, it is necessary to make some sort of +`discretization`_. As an example, we can divide up all space into small sections +which are homogeneous and then solve the equation on those small sections. After +these discretizations and various approximations, one can arrive at forms that +are suitable for solution on a computer. Among these are discrete ordinates, +method of characteristics, finite-difference diffusion, and nodal methods. So why choose Monte Carlo over deterministic methods? Each method has its pros and cons. Let us first take a look at few of the salient pros and cons of @@ -88,30 +90,32 @@ interest. This could be a nuclear reactor or any other physical system with fissioning material. You, as the code user, will need to describe the model so that the code can do something with it. A basic model consists of a few things: -- A description of the geometry -- the problem should be split up into regions - of homogeneous material. +- A description of the geometry -- the problem must be split up into regions of + homogeneous material composition. - For each different material in the problem, a description of what nuclides are in the material and at what density. - Various parameters telling the code how many particles to simulate and what options to use. - A list of different physical quantities that the code should return at the end - of the simulation. Remember, in a Monte Carlo simulation, if you don't ask for - anything, it will not give you any answers (other than a few default - quantities). + of the simulation. In a Monte Carlo simulation, if you don't ask for anything, + it will not give you any answers (other than a few default quantities). ----------------------- What do I need to know? ----------------------- If you are starting to work with OpenMC, there are a few things you should be -familiar with. Whether you plan on working in Linux, Mac OS X, or Windows, you +familiar with. Whether you plan on working in Linux, macOS, or Windows, you should be comfortable working in a command line environment. There are many resources online for learning command line environments. If you are using Linux or Mac OS X (also Unix-derived), `this tutorial `_ will help you get acquainted with -commonly-used commands. It is also helpful to be familiar with `Python -`_, as most of the post-processing utilities provided -with OpenMC rely on it for data manipulation and results visualization. +commonly-used commands. + +To reap the full benefits of OpenMC, you should also have basic proficiency in +the use of `Python `_, as OpenMC includes a rich Python +API that offers many usability improvements over dealing with raw XML input +files. OpenMC uses a version control software called `git`_ to keep track of changes to the code, document bugs and issues, and other development tasks. While you don't @@ -122,7 +126,7 @@ at the git documentation website. The `OpenMC source code`_ and documentation are hosted at `GitHub`_. In order to receive updates to the code directly, submit `bug reports`_, and perform other development tasks, you may want to sign up for a free account on GitHub. Once you have an account, you can follow `these -instructions `_ on how to set up +instructions `_ on how to set up your computer for using GitHub. If you are new to nuclear engineering, you may want to review the NRC's `Reactor @@ -153,5 +157,5 @@ and `Volume II`_. You may also find it helpful to review the following terms: .. _GitHub: https://github.com/ .. _bug reports: https://github.com/mit-crpg/openmc/issues .. _Neutron cross section: http://en.wikipedia.org/wiki/Neutron_cross_section -.. _Effective multiplication factor: http://en.wikipedia.org/wiki/Effective_multiplication_factor +.. _Effective multiplication factor: https://en.wikipedia.org/wiki/Nuclear_chain_reaction#Effective_neutron_multiplication_factor .. _Flux: http://en.wikipedia.org/wiki/Neutron_flux diff --git a/docs/source/usersguide/index.rst b/docs/source/usersguide/index.rst index cbdb608060..d3fa0f4cf8 100644 --- a/docs/source/usersguide/index.rst +++ b/docs/source/usersguide/index.rst @@ -9,10 +9,11 @@ essential aspects of using OpenMC to perform simulations. .. toctree:: :numbered: - :maxdepth: 2 + :maxdepth: 1 beginners install - input + basics + scripts processing troubleshoot diff --git a/docs/source/usersguide/input.rst b/docs/source/usersguide/input.rst deleted file mode 100644 index b4ba5350b1..0000000000 --- a/docs/source/usersguide/input.rst +++ /dev/null @@ -1,2451 +0,0 @@ -.. _usersguide_input: - -======================= -Writing XML Input Files -======================= - -Unlike many other Monte Carlo codes which use an arbitrary-format ASCII file -with "cards" to specify a particular geometry, materials, and associated run -settings, the input files for OpenMC are structured in a set of XML_ files. XML, -which stands for eXtensible Markup Language, is a simple format that allows data -to be exchanged efficiently between different programs and interfaces. - -Anyone who has ever seen webpages written in HTML will be familiar with the -structure of XML whereby "tags" enclosed in angle brackets denote that a -particular piece of data will follow. Let us examine the follow example: - -.. code-block:: xml - - - John - Smith - 27 - Health Physicist - - -Here we see that the first tag indicates that the following data will describe a -person. The nested tags *firstname*, *lastname*, *age*, and *occupation* -indicate characteristics about the person being described. - -In much the same way, OpenMC input uses XML tags to describe the geometry, the -materials, and settings for a Monte Carlo simulation. - -.. _XML: http://www.w3.org/XML/ - ------------------ -Overview of Files ------------------ - -To assemble a complete model for OpenMC, one needs to create separate XML files -for the geometry, materials, and settings. Additionally, there are three optional -input files. The first is a tallies XML file that specifies physical quantities -to be tallied. The second is a plots XML file that specifies regions of geometry -which should be plotted. The third is a CMFD XML file that specifies coarse mesh -acceleration geometry and execution parameters. OpenMC expects that these -files are called: - -* ``geometry.xml`` -* ``materials.xml`` -* ``settings.xml`` -* ``tallies.xml`` -* ``plots.xml`` -* ``cmfd.xml`` - --------------------- -Validating XML Files --------------------- - -Input files can be checked before executing OpenMC using the -``openmc-validate-xml`` script which is installed alongside the Python API. Two -command line arguments can be set when running ``openmc-validate-xml``: - -* ``-i``, ``--input-path`` - Location of OpenMC input files. - *Default*: current working directory -* ``-r``, ``--relaxng-path`` - Location of OpenMC RelaxNG files. - *Default*: None - -If the RelaxNG path is not set, the script will search for these files because -it expects that the user is either running the script located in the install -directory ``bin`` folder or in ``src/utils``. Once executed, it will match -OpenMC XML files with their RelaxNG schema and check if they are valid. Below -is a table of the messages that will be printed after each file is checked. - -======================== =================================== -Message Description -======================== =================================== -[XML ERROR] Cannot parse XML file. -[NO RELAXNG FOUND] No RelaxNG file found for XML file. -[NOT VALID] XML file does not match RelaxNG. -[VALID] XML file matches RelaxNG. -======================== =================================== - -As an example, if OpenMC is installed in the directory ``/opt/openmc/`` and the -current working directory is where OpenMC XML input files are located, they can -be validated using the following command: - -.. code-block:: bash - - /opt/openmc/bin/openmc-validate-xml - --------------- -Physical Units --------------- - -Unless specified otherwise, all length quantities are assumed to be in units of -centimeters, all energy quantities are assumed to be in electronvolts, and all -time quantities are assumed to be in seconds. - -======= ============ ====== -Measure Default unit Symbol -======= ============ ====== -length centimeter cm -energy electronvolt eV -time second s -======= ============ ====== - --------------------------------------- -Settings Specification -- settings.xml --------------------------------------- - -All simulation parameters and miscellaneous options are specified in the -settings.xml file. - -```` Element ---------------------- - -The ```` element indicates the total number of batches to execute, -where each batch corresponds to a tally realization. In a fixed source -calculation, each batch consists of a number of source particles. In an -eigenvalue calculation, each batch consists of one or many fission source -iterations (generations), where each generation itself consists of a number of -source neutrons. - - *Default*: None - -```` Element ----------------------------------- - -The ```` element has no attributes and has an accepted -value of "true" or "false". If set to "true", uncertainties on tally results -will be reported as the half-width of the 95% two-sided confidence interval. If -set to "false", uncertainties on tally results will be reported as the sample -standard deviation. - - *Default*: false - -```` Element --------------------- - -The ```` element indicates two kinds of cutoffs. The first is the weight -cutoff used below which particles undergo Russian roulette. Surviving particles -are assigned a user-determined weight. Note that weight cutoffs and Russian -rouletting are not turned on by default. The second is the energy cutoff which -is used to kill particles under certain energy. The energy cutoff should not be -used unless you know particles under the energy are of no importance to results -you care. This element has the following attributes/sub-elements: - - :weight: - The weight below which particles undergo Russian roulette. - - *Default*: 0.25 - - :weight_avg: - The weight that is assigned to particles that are not killed after Russian - roulette. - - *Default*: 1.0 - - :energy: - The energy under which particles will be killed. - - *Default*: 0.0 - -```` Element -------------------------- - -The ```` element determines the treatment of the energy grid during -a simulation. The valid options are "nuclide", "logarithm", and -"material-union". Setting this element to "nuclide" will cause OpenMC to use a -nuclide's energy grid when determining what points to interpolate between for -determining cross sections (i.e. non-unionized energy grid). Setting this -element to "logarithm" causes OpenMC to use a logarithmic mapping technique -described in LA-UR-14-24530_. Setting this element to "material-union" will -cause OpenMC to create energy grids that are unionized material-by-material and -use these grids when determining the energy-cross section pairs to interpolate -cross section values between. - - *Default*: logarithm - - .. note:: This element is not used in the multi-group :ref:`energy_mode`. - -.. _LA-UR-14-24530: https://laws.lanl.gov/vhosts/mcnp.lanl.gov/pdf_files/la-ur-14-24530.pdf - -.. _energy_mode: - -```` Element -------------------------- - -The ```` element tells OpenMC if the run-mode should be -continuous-energy or multi-group. Options for entry are: ``continuous-energy`` -or ``multi-group``. - - *Default*: continuous-energy - -```` Element ---------------------- - -The ```` element describes a mesh that is used for calculating Shannon -entropy. This mesh should cover all possible fissionable materials in the -problem. It has the following attributes/sub-elements: - - :dimension: - The number of mesh cells in the x, y, and z directions, respectively. - - *Default*: If this tag is not present, the number of mesh cells is - automatically determined by the code. - - :lower_left: - The Cartesian coordinates of the lower-left corner of the mesh. - - *Default*: None - - :upper_right: - The Cartesian coordinates of the upper-right corner of the mesh. - - *Default*: None - -```` Element ------------------------------------ - -The ```` element indicates the number of total fission -source iterations per batch for an eigenvalue calculation. This element is -ignored for all run modes other than "eigenvalue". - - *Default*: 1 - -```` Element ----------------------- - -The ```` element indicates the number of inactive batches used in a -k-eigenvalue calculation. In general, the starting fission source iterations in -an eigenvalue calculation can not be used to contribute to tallies since the -fission source distribution and eigenvalue are generally not converged -immediately. This element is ignored for all run modes other than "eigenvalue". - - *Default*: 0 - -```` Element --------------------------- - -The ```` element (ignored for all run modes other than -"eigenvalue".) specifies a precision trigger on the combined -:math:`k_{eff}`. The trigger is a convergence criterion on the uncertainty of -the estimated eigenvalue. It has the following attributes/sub-elements: - - :type: - The type of precision trigger. Accepted options are "variance", "std_dev", - and "rel_err". - - :variance: - Variance of the batch mean :math:`\sigma^2` - - :std_dev: - Standard deviation of the batch mean :math:`\sigma` - - :rel_err: - Relative error of the batch mean :math:`\frac{\sigma}{\mu}` - - *Default*: None - - :threshold: - The precision trigger's convergence criterion for the - combined :math:`k_{eff}`. - - *Default*: None - -.. note:: See section on the :ref:`trigger` for more information. - - -```` Element ---------------------------- - -The ```` element indicates the number of bins to use for the -logarithmic-mapped energy grid. Using more bins will result in energy grid -searches over a smaller range at the expense of more memory. The default is -based on the recommended value in LA-UR-14-24530_. - - *Default*: 8000 - - .. note:: This element is not used in the multi-group :ref:`energy_mode`. - -```` Element ---------------------------- - -The ```` element allows the user to set a maximum scattering order -to apply to every nuclide/material in the problem. That is, if the data -library has :math:`P_3` data available, but ```` was set to ``1``, -then, OpenMC will only use up to the :math:`P_1` data. - - *Default*: Use the maximum order in the data library - - .. note:: This element is not used in the continuous-energy - :ref:`energy_mode`. - -```` Element ------------------------ - -The ```` element has no attributes and has an accepted value of -"true" or "false". If set to "true", all user-defined tallies and global tallies -will not be reduced across processors in a parallel calculation. This means that -the accumulate score in one batch on a single processor is considered as an -independent realization for the tally random variable. For a problem with large -tally data, this option can significantly improve the parallel efficiency. - - *Default*: false - -```` Element --------------------- - -The ```` element determines what output files should be written to disk -during the run. The sub-elements are described below, where "true" will write -out the file and "false" will not. - - :cross_sections: - Writes out an ASCII summary file of the cross sections that were read in. - - *Default*: false - - :summary: - Writes out an HDF5 summary file describing all of the user input files that - were read in. - - *Default*: true - - :tallies: - Write out an ASCII file of tally results. - - *Default*: true - - .. note:: The tally results will always be written to a binary/HDF5 state - point file. - -```` Element -------------------------- - -The ```` element specifies an absolute or relative path where all -output files should be written to. The specified path must exist or else OpenMC -will abort. - - *Default*: Current working directory - -```` Element ------------------------ - -This element indicates the number of neutrons to simulate per fission source -iteration when a k-eigenvalue calculation is performed or the number of neutrons -per batch for a fixed source simulation. - - *Default*: None - -```` Element ---------------------- - -The ```` element determines whether probability tables should be used -in the unresolved resonance range if available. This element has no attributes -or sub-elements and can be set to either "false" or "true". - - *Default*: true - - .. note:: This element is not used in the multi-group :ref:`energy_mode`. - -```` Element ----------------------------------- - -The ``resonance_scattering`` element indicates to OpenMC that a method be used -to properly account for resonance elastic scattering (typically for nuclides -with Z > 40). This element can contain one or more of the following attributes -or sub-elements: - - :enable: - Indicates whether a resonance elastic scattering method should be turned - on. Accepts values of "true" or "false". - - *Default*: If the ```` element is present, "true". - - :method: - - Which resonance elastic scattering method is to be applied: "ares" - (accelerated resonance elastic scattering), "dbrc" (Doppler broadening - rejection correction), or "wcm" (weight correction method). Descriptions of - each of these methods are documented here_. - - .. _here: http://dx.doi.org/10.1016/j.anucene.2014.01.017 - - *Default*: "ares" - - :energy_min: - The energy in eV above which the resonance elastic scattering method should - be applied. - - *Default*: 0.01 eV - - :energy_max: - The energy in eV below which the resonance elastic scattering method should - be applied. - - *Default*: 1000.0 eV - - :nuclides: - - A list of nuclides to which the resonance elastic scattering method should - be applied. - - *Default*: If ```` is present but the ```` - sub-element is not given, the method is applied to all nuclides with 0 K - elastic scattering data present. - - .. note:: If the ``resonance_scattering`` element is not given, the free gas, - constant cross section scattering model, which has historically been - used by Monte Carlo codes to sample target velocities, is used to - treat the target motion of all nuclides. If - ``resonance_scattering`` is present, the constant cross section - method is applied below ``energy_min`` and the target-at-rest - (asymptotic) kernel is used above ``energy_max``. - - .. note:: This element is not used in the multi-group :ref:`energy_mode`. - -```` Element ----------------------- - -The ```` element indicates whether or not CMFD acceleration should be -turned on or off. This element has no attributes or sub-elements and can be set -to either "false" or "true". - - *Default*: false - -```` Element ----------------------- - -The ```` element indicates which run mode should be used when OpenMC -is executed. This element has no attributes or sub-elements and can be set to -"eigenvalue", "fixed source", "plot", "volume", or "particle restart". - - *Default*: None - -```` Element ------------------- - -The ``seed`` element is used to set the seed used for the linear congruential -pseudo-random number generator. - - *Default*: 1 - -```` Element --------------------- - -The ``source`` element gives information on an external source distribution to -be used either as the source for a fixed source calculation or the initial -source guess for criticality calculations. Multiple ```` elements may be -specified to define different source distributions. Each one takes the following -attributes/sub-elements: - - :strength: - The strength of the source. If multiple sources are present, the source - strength indicates the relative probability of choosing one source over the - other. - - *Default*: 1.0 - - :file: - If this attribute is given, it indicates that the source is to be read from - a binary source file whose path is given by the value of this element. Note, - the number of source sites needs to be the same as the number of particles - simulated in a fission source generation. - - *Default*: None - - :space: - An element specifying the spatial distribution of source sites. This element - has the following attributes: - - :type: - The type of spatial distribution. Valid options are "box", "fission", - "point", and "cartesian". A "box" spatial distribution has coordinates - sampled uniformly in a parallelepiped. A "fission" spatial distribution - samples locations from a "box" distribution but only locations in - fissionable materials are accepted. A "point" spatial distribution has - coordinates specified by a triplet. An "cartesian" spatial distribution - specifies independent distributions of x-, y-, and z-coordinates. - - *Default*: None - - :parameters: - For a "box" or "fission" spatial distribution, ``parameters`` should be - given as six real numbers, the first three of which specify the lower-left - corner of a parallelepiped and the last three of which specify the - upper-right corner. Source sites are sampled uniformly through that - parallelepiped. - - For a "point" spatial distribution, ``parameters`` should be given as - three real numbers which specify the (x,y,z) location of an isotropic - point source. - - For an "cartesian" distribution, no parameters are specified. Instead, - the ``x``, ``y``, and ``z`` elements must be specified. - - *Default*: None - - :x: - For an "cartesian" distribution, this element specifies the distribution - of x-coordinates. The necessary sub-elements/attributes are those of a - univariate probability distribution (see the description in - :ref:`univariate`). - - :y: - For an "cartesian" distribution, this element specifies the distribution - of y-coordinates. The necessary sub-elements/attributes are those of a - univariate probability distribution (see the description in - :ref:`univariate`). - - :z: - For an "cartesian" distribution, this element specifies the distribution - of z-coordinates. The necessary sub-elements/attributes are those of a - univariate probability distribution (see the description in - :ref:`univariate`). - - :angle: - An element specifying the angular distribution of source sites. This element - has the following attributes: - - :type: - The type of angular distribution. Valid options are "isotropic", - "monodirectional", and "mu-phi". The angle of the particle emitted from a - source site is isotropic if the "isotropic" option is given. The angle of - the particle emitted from a source site is the direction specified in the - ``reference_uvw`` element/attribute if "monodirectional" option is - given. The "mu-phi" option produces directions with the cosine of the - polar angle and the azimuthal angle explicitly specified. - - *Default*: isotropic - - :reference_uvw: - The direction from which the polar angle is measured. Represented by the - x-, y-, and z-components of a unit vector. For a monodirectional - distribution, this defines the direction of all sampled particles. - - :mu: - An element specifying the distribution of the cosine of the polar - angle. Only relevant when the type is "mu-phi". The necessary - sub-elements/attributes are those of a univariate probability distribution - (see the description in :ref:`univariate`). - - :phi: - An element specifying the distribution of the azimuthal angle. Only - relevant when the type is "mu-phi". The necessary sub-elements/attributes - are those of a univariate probability distribution (see the description in - :ref:`univariate`). - - :energy: - An element specifying the energy distribution of source sites. The necessary - sub-elements/attributes are those of a univariate probability distribution - (see the description in :ref:`univariate`). - - *Default*: Watt spectrum with :math:`a` = 0.988 MeV and :math:`b` = - 2.249 MeV :sup:`-1` - - :write_initial: - An element specifying whether to write out the initial source bank used at - the beginning of the first batch. The output file is named - "initial_source.h5" - - *Default*: false - -.. _univariate: - -Univariate Probability Distributions -++++++++++++++++++++++++++++++++++++ - -Various components of a source distribution involve probability distributions of -a single random variable, e.g. the distribution of the energy, the distribution -of the polar angle, and the distribution of x-coordinates. Each of these -components supports the same syntax with an element whose tag signifies the -variable and whose sub-elements/attributes are as follows: - -:type: - The type of the distribution. Valid options are "uniform", "discrete", - "tabular", "maxwell", and "watt". The "uniform" option produces variates - sampled from a uniform distribution over a finite interval. The "discrete" - option produces random variates that can assume a finite number of values - (i.e., a distribution characterized by a probability mass function). The - "tabular" option produces random variates sampled from a tabulated - distribution where the density function is either a histogram or - linearly-interpolated between tabulated points. The "watt" option produces - random variates is sampled from a Watt fission spectrum (only used for - energies). The "maxwell" option produce variates sampled from a Maxwell - fission spectrum (only used for energies). - - *Default*: None - -:parameters: - For a "uniform" distribution, ``parameters`` should be given as two real - numbers :math:`a` and :math:`b` that define the interval :math:`[a,b]` over - which random variates are sampled. - - For a "discrete" or "tabular" distribution, ``parameters`` provides the - :math:`(x,p)` pairs defining the discrete/tabular distribution. All :math:`x` - points are given first followed by corresponding :math:`p` points. - - For a "watt" distribution, ``parameters`` should be given as two real numbers - :math:`a` and :math:`b` that parameterize the distribution :math:`p(x) dx = c - e^{-x/a} \sinh \sqrt{b \, x} dx`. - - For a "maxwell" distribution, ``parameters`` should be given as one real - number :math:`a` that parameterizes the distribution :math:`p(x) dx = c x - e^{-x/a} dx`. - - .. note:: The above format should be used even when using the multi-group - :ref:`energy_mode`. -:interpolation: - For a "tabular" distribution, ``interpolation`` can be set to "histogram" or - "linear-linear" thereby specifying how tabular points are to be interpolated. - - *Default*: histogram - -```` Element -------------------------- - -The ```` element indicates at what batches a state point file -should be written. A state point file can be used to restart a run or to get -tally results at any batch. The default behavior when using this tag is to -write out the source bank in the state_point file. This behavior can be -customized by using the ```` element. This element has the -following attributes/sub-elements: - - :batches: - A list of integers separated by spaces indicating at what batches a state - point file should be written. - - *Default*: Last batch only - -```` Element --------------------------- - -The ```` element indicates at what batches the source bank -should be written. The source bank can be either written out within a state -point file or separately in a source point file. This element has the following -attributes/sub-elements: - - :batches: - A list of integers separated by spaces indicating at what batches a state - point file should be written. It should be noted that if the ``separate`` - attribute is not set to "true", this list must be a subset of state point - batches. - - *Default*: Last batch only - - :separate: - If this element is set to "true", a separate binary source point file will - be written. Otherwise, the source sites will be written in the state point - directly. - - *Default*: false - - :write: - If this element is set to "false", source sites are not written - to the state point or source point file. This can substantially reduce the - size of state points if large numbers of particles per batch are used. - - *Default*: true - - :overwrite_latest: - If this element is set to "true", a source point file containing - the source bank will be written out to a separate file named - ``source.binary`` or ``source.h5`` depending on if HDF5 is enabled. - This file will be overwritten at every single batch so that the latest - source bank will be available. It should be noted that a user can set both - this element to "true" and specify batches to write a permanent source bank. - - *Default*: false - -```` Element ------------------------------- - -The ```` element has no attributes and has an accepted value -of "true" or "false". If set to "true", this option will enable the use of -survival biasing, otherwise known as implicit capture or absorption. - - *Default*: false - -.. _tabular_legendre: - -```` Element ---------------------------------- - -The optional ```` element specifies how the multi-group -Legendre scattering kernel is represented if encountered in a multi-group -problem. Specifically, the options are to either convert the Legendre -expansion to a tabular representation or leave it as a set of Legendre -coefficients. Converting to a tabular representation will cost memory but can -allow for a decrease in runtime compared to leaving as a set of Legendre -coefficients. This element has the following attributes/sub-elements: - - :enable: - This attribute/sub-element denotes whether or not the conversion of a - Legendre scattering expansion to the tabular format should be performed or - not. A value of “true” means the conversion should be performed, “false” - means it will not. - - *Default*: true - - :num_points: - If the conversion is to take place the number of tabular points is - required. This attribute/sub-element allows the user to set the desired - number of points. - - *Default*: 33 - - .. note:: This element is only used in the multi-group :ref:`energy_mode`. - -.. _temperature_default: - -```` Element ---------------------------------- - -The ```` element specifies a default temperature in Kelvin -that is to be applied to cells in the absence of an explicit cell temperature or -a material default temperature. - - *Default*: 293.6 K - -.. _temperature_method: - -```` Element --------------------------------- - -The ```` element has an accepted value of "nearest" or -"interpolation". A value of "nearest" indicates that for each -cell, the nearest temperature at which cross sections are given is to be -applied, within a given tolerance (see :ref:`temperature_tolerance`). A value of -"interpolation" indicates that cross sections are to be linear-linear -interpolated between temperatures at which nuclear data are present (see -:ref:`temperature_treatment`). - - *Default*: "nearest" - -.. _temperature_multipole: - -```` Element ------------------------------------ - -The ```` element toggles the windowed multipole -capability on or off. If this element is set to "True" and the relevant data is -available, OpenMC will use the windowed multipole method to evaluate and Doppler -broaden cross sections in the resolved resonance range. This override other -methods like "nearest" and "interpolation" in the resolved resonance range. - - *Default*: False - -.. _temperature_tolerance: - -```` Element ------------------------------------ - -The ```` element specifies a tolerance in Kelvin that is -to be applied when the "nearest" temperature method is used. For example, if a -cell temperature is 340 K and the tolerance is 15 K, then the closest -temperature in the range of 325 K to 355 K will be used to evaluate cross -sections. - - *Default*: 10 K - -```` Element ---------------------- - -The ```` element indicates the number of OpenMP threads to be used for -a simulation. It has no attributes and accepts a positive integer value. - - *Default*: None (Determined by environment variable :envvar:`OMP_NUM_THREADS`) - -.. _trace: - -```` Element -------------------- - -The ```` element can be used to print out detailed information about a -single particle during a simulation. This element should be followed by three -integers: the batch number, generation number, and particle number. - - *Default*: None - -.. _track: - -```` Element -------------------- - -The ```` element specifies particles for which OpenMC will output binary -files describing particle position at every step of its transport. This element -should be followed by triplets of integers. Each triplet describes one -particle. The integers in each triplet specify the batch number, generation -number, and particle number, respectively. - - *Default*: None - -.. _trigger: - -```` Element -------------------------- - -OpenMC includes tally precision triggers which allow the user to define -uncertainty thresholds on :math:`k_{eff}` in the ```` subelement -of ``settings.xml``, and/or tallies in ``tallies.xml``. When using triggers, -OpenMC will run until it completes as many batches as defined by ````. -At this point, the uncertainties on all tallied values are computed and compared -with their corresponding trigger thresholds. If any triggers have not been met, -OpenMC will continue until either all trigger thresholds have been satisfied or -```` has been reached. - -The ```` element provides an active "toggle switch" for tally -precision trigger(s), the maximum number of batches and the batch interval. It -has the following attributes/sub-elements: - - :active: - This determines whether or not to use trigger(s). Trigger(s) are used when - this tag is set to "true". - - :max_batches: - This describes the maximum number of batches allowed when using trigger(s). - - .. note:: When max_batches is set, the number of ``batches`` shown in the - ```` element represents minimum number of batches to - simulate when using the trigger(s). - - :batch_interval: - This tag describes the number of batches in between convergence checks. - OpenMC will check if the trigger has been reached at each batch defined - by ``batch_interval`` after the minimum number of batches is reached. - - .. note:: If this tag is not present, the ``batch_interval`` is predicted - dynamically by OpenMC for each convergence check. The predictive - model assumes no correlation between fission sources - distributions from batch-to-batch. This assumption is reasonable - for fixed source and small criticality calculations, but is very - optimistic for highly coupled full-core reactor problems. - - -```` Element ------------------------- - -The ```` element describes a mesh that is used for re-weighting -source sites at every generation based on the uniform fission site methodology -described in Kelly et al., "MC21 Analysis of the Nuclear Energy Agency Monte -Carlo Performance Benchmark Problem," Proceedings of *Physor 2012*, Knoxville, -TN (2012). This mesh should cover all possible fissionable materials in the -problem. It has the following attributes/sub-elements: - - :dimension: - The number of mesh cells in the x, y, and z directions, respectively. - - *Default*: None - - :lower_left: - The Cartesian coordinates of the lower-left corner of the mesh. - - *Default*: None - - :upper_right: - The Cartesian coordinates of the upper-right corner of the mesh. - - *Default*: None - -.. _verbosity: - -```` Element ------------------------ - -The ```` element tells the code how much information to display to -the standard output. A higher verbosity corresponds to more information being -displayed. The text of this element should be an integer between between 1 -and 10. The verbosity levels are defined as follows: - - :1: don't display any output - :2: only show OpenMC logo - :3: all of the above + headers - :4: all of the above + results - :5: all of the above + file I/O - :6: all of the above + timing statistics and initialization messages - :7: all of the above + :math:`k` by generation - :9: all of the above + indicate when each particle starts - :10: all of the above + event information - - *Default*: 7 - -```` Element -------------------------------------- - -The ```` element indicates whether fission neutrons -should be created or not. If this element is set to "true", fission neutrons -will be created; otherwise the fission is treated as capture and no fission -neutron will be created. Note that this option is only applied to fixed source -calculation. For eigenvalue calculation, fission will always be treated as real -fission. - - *Default*: true - - -```` Element -------------------------- - -The ```` element indicates that a stochastic volume calculation -should be run at the beginning of the simulation. This element has the following -sub-elements/attributes: - - :cells: - The unique IDs of cells for which the volume should be estimated. - - *Default*: None - - :samples: - The number of samples used to estimate volumes. - - *Default*: None - - :lower_left: - The lower-left Cartesian coordinates of a bounding box that is used to - sample points within. - - *Default*: None - - :upper_right: - The upper-right Cartesian coordinates of a bounding box that is used to - sample points within. - - *Default*: None - --------------------------------------- -Geometry Specification -- geometry.xml --------------------------------------- - -The geometry in OpenMC is described using `constructive solid geometry`_ (CSG), -also sometimes referred to as combinatorial geometry. CSG allows a user to -create complex objects using Boolean operators on a set of simpler surfaces. In -the geometry model, each unique volume is defined by its bounding surfaces. In -OpenMC, most `quadratic surfaces`_ can be modeled and used as bounding surfaces. - -Every geometry.xml must have an XML declaration at the beginning of the file and -a root element named geometry. Within the root element the user can define any -number of cells, surfaces, and lattices. Let us look at the following example: - -.. code-block:: xml - - - - - - - 1 - sphere - 0.0 0.0 0.0 5.0 - vacuum - - - - 1 - 0 - 1 - -1 - - - -At the beginning of this file is a comment, denoted by a tag starting with -````. Comments, as well as any other type of input, -may span multiple lines. One convenient feature of the XML input format is that -sub-elements of the ``cell`` and ``surface`` elements can also be equivalently -expressed of attributes of the original element, e.g. the geometry file above -could be written as: - -.. code-block:: xml - - - - - - - - - - -.. _surface_element: - -```` Element ---------------------- - -Each ```` element can have the following attributes or sub-elements: - - :id: - A unique integer that can be used to identify the surface. - - *Default*: None - - :name: - An optional string name to identify the surface in summary output - files. This string is limited to 52 characters for formatting purposes. - - *Default*: "" - - :type: - The type of the surfaces. This can be "x-plane", "y-plane", "z-plane", - "plane", "x-cylinder", "y-cylinder", "z-cylinder", "sphere", "x-cone", - "y-cone", "z-cone", or "quadric". - - *Default*: None - - :coeffs: - The corresponding coefficients for the given type of surface. See below for - a list a what coefficients to specify for a given surface - - *Default*: None - - :boundary: - The boundary condition for the surface. This can be "transmission", - "vacuum", "reflective", or "periodic". Periodic boundary conditions can - only be applied to x-, y-, and z-planes. Only axis-aligned periodicity is - supported, i.e., x-planes can only be paired with x-planes. Specify which - planes are periodic and the code will automatically identify which planes - are paired together. - - *Default*: "transmission" - - :periodic_surface_id: - If a periodic boundary condition is applied, this attribute identifies the - ``id`` of the corresponding periodic sufrace. - -The following quadratic surfaces can be modeled: - - :x-plane: - A plane perpendicular to the x axis, i.e. a surface of the form :math:`x - - x_0 = 0`. The coefficients specified are ":math:`x_0`". - - :y-plane: - A plane perpendicular to the y axis, i.e. a surface of the form :math:`y - - y_0 = 0`. The coefficients specified are ":math:`y_0`". - - :z-plane: - A plane perpendicular to the z axis, i.e. a surface of the form :math:`z - - z_0 = 0`. The coefficients specified are ":math:`z_0`". - - :plane: - An arbitrary plane of the form :math:`Ax + By + Cz = D`. The coefficients - specified are ":math:`A \: B \: C \: D`". - - :x-cylinder: - An infinite cylinder whose length is parallel to the x-axis. This is a - quadratic surface of the form :math:`(y - y_0)^2 + (z - z_0)^2 = R^2`. The - coefficients specified are ":math:`y_0 \: z_0 \: R`". - - :y-cylinder: - An infinite cylinder whose length is parallel to the y-axis. This is a - quadratic surface of the form :math:`(x - x_0)^2 + (z - z_0)^2 = R^2`. The - coefficients specified are ":math:`x_0 \: z_0 \: R`". - - :z-cylinder: - An infinite cylinder whose length is parallel to the z-axis. This is a - quadratic surface of the form :math:`(x - x_0)^2 + (y - y_0)^2 = R^2`. The - coefficients specified are ":math:`x_0 \: y_0 \: R`". - - :sphere: - A sphere of the form :math:`(x - x_0)^2 + (y - y_0)^2 + (z - z_0)^2 = - R^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 \: R`". - - :x-cone: - A cone parallel to the x-axis of the form :math:`(y - y_0)^2 + (z - z_0)^2 = - R^2 (x - x_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 - \: R^2`". - - :y-cone: - A cone parallel to the y-axis of the form :math:`(x - x_0)^2 + (z - z_0)^2 = - R^2 (y - y_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 - \: R^2`". - - :z-cone: - A cone parallel to the x-axis of the form :math:`(x - x_0)^2 + (y - y_0)^2 = - R^2 (z - z_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 - \: R^2`". - - :quadric: - A general quadric surface of the form :math:`Ax^2 + By^2 + Cz^2 + Dxy + - Eyz + Fxz + Gx + Hy + Jz + K = 0` The coefficients specified are ":math:`A - \: B \: C \: D \: E \: F \: G \: H \: J \: K`". - - -```` Element ------------------- - -Each ```` element can have the following attributes or sub-elements: - - :id: - A unique integer that can be used to identify the cell. - - *Default*: None - - :name: - An optional string name to identify the cell in summary output files. - This string is limmited to 52 characters for formatting purposes. - - *Default*: "" - - :universe: - The ``id`` of the universe that this cell is contained in. - - *Default*: 0 - - :fill: - The ``id`` of the universe that fills this cell. - - .. note:: If a fill is specified, no material should be given. - - *Default*: None - - :material: - The ``id`` of the material that this cell contains. If the cell should - contain no material, this can also be set to "void". A list of materials - can be specified for the "distributed material" feature. This will give each - unique instance of the cell its own material. - - .. note:: If a material is specified, no fill should be given. - - *Default*: None - - :region: - A Boolean expression of half-spaces that defines the spatial region which - the cell occupies. Each half-space is identified by the unique ID of the - surface prefixed by `-` or `+` to indicate that it is the negative or - positive half-space, respectively. The `+` sign for a positive half-space - can be omitted. Valid Boolean operators are parentheses, union `|`, - complement `~`, and intersection. Intersection is implicit and indicated by - the presence of whitespace. The order of operator precedence is parentheses, - complement, intersection, and then union. - - As an example, the following code gives a cell that is the union of the - negative half-space of surface 3 and the complement of the intersection of - the positive half-space of surface 5 and the negative half-space of surface - 2: - - .. code-block:: xml - - - - .. note:: The ``region`` attribute/element can be omitted to make a cell - fill its entire universe. - - *Default*: A region filling all space. - - :temperature: - The temperature of the cell in Kelvin. If windowed-multipole data is - avalable, this temperature will be used to Doppler broaden some cross - sections in the resolved resonance region. A list of temperatures can be - specified for the "distributed temperature" feature. This will give each - unique instance of the cell its own temperature. - - *Default*: If a material default temperature is supplied, it is used. In the - absence of a material default temperature, the :ref:`global default - temperature ` is used. - - :rotation: - If the cell is filled with a universe, this element specifies the angles in - degrees about the x, y, and z axes that the filled universe should be - rotated. Should be given as three real numbers. For example, if you wanted - to rotate the filled universe by 90 degrees about the z-axis, the cell - element would look something like: - - .. code-block:: xml - - - - The rotation applied is an intrinsic rotation whose Tait-Bryan angles are - given as those specified about the x, y, and z axes respectively. That is to - say, if the angles are :math:`(\phi, \theta, \psi)`, then the rotation - matrix applied is :math:`R_z(\psi) R_y(\theta) R_x(\phi)` or - - .. math:: - - \left [ \begin{array}{ccc} \cos\theta \cos\psi & -\cos\theta \sin\psi + - \sin\phi \sin\theta \cos\psi & \sin\phi \sin\psi + \cos\phi \sin\theta - \cos\psi \\ \cos\theta \sin\psi & \cos\phi \cos\psi + \sin\phi \sin\theta - \sin\psi & -\sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\ - -\sin\theta & \sin\phi \cos\theta & \cos\phi \cos\theta \end{array} - \right ] - - *Default*: None - - :translation: - If the cell is filled with a universe, this element specifies a vector that - is used to translate (shift) the universe. Should be given as three real - numbers. - - .. note:: Any translation operation is applied after a rotation, if also - specified. - - *Default*: None - - -```` Element ---------------------- - -The ```` can be used to represent repeating structures (e.g. fuel pins -in an assembly) or other geometry which fits onto a rectilinear grid. Each cell -within the lattice is filled with a specified universe. A ```` accepts -the following attributes or sub-elements: - - :id: - A unique integer that can be used to identify the lattice. - - :name: - An optional string name to identify the lattice in summary output - files. This string is limited to 52 characters for formatting purposes. - - *Default*: "" - - :dimension: - Two or three integers representing the number of lattice cells in the x- and - y- (and z-) directions, respectively. - - *Default*: None - - :lower_left: - The coordinates of the lower-left corner of the lattice. If the lattice is - two-dimensional, only the x- and y-coordinates are specified. - - *Default*: None - - :pitch: - If the lattice is 3D, then three real numbers that express the distance - between the centers of lattice cells in the x-, y-, and z- directions. If - the lattice is 2D, then omit the third value. - - *Default*: None - - :outer: - The unique integer identifier of a universe that will be used to fill all - space outside of the lattice. The universe will be tiled repeatedly as if - it were placed in a lattice of infinite size. This element is optional. - - *Default*: An error will be raised if a particle leaves a lattice with no - outer universe. - - :universes: - A list of the universe numbers that fill each cell of the lattice. - - *Default*: None - -Here is an example of a properly defined 2d rectangular lattice: - -.. code-block:: xml - - - -1.5 -1.5 - 1.0 1.0 - - 2 2 2 - 2 1 2 - 2 2 2 - - - -```` Element -------------------------- - -The ```` can be used to represent repeating structures (e.g. fuel -pins in an assembly) or other geometry which naturally fits onto a hexagonal -grid or hexagonal prism grid. Each cell within the lattice is filled with a -specified universe. This lattice uses the "flat-topped hexagon" scheme where two -of the six edges are perpendicular to the y-axis. A ```` accepts -the following attributes or sub-elements: - - :id: - A unique integer that can be used to identify the lattice. - - :name: - An optional string name to identify the hex_lattice in summary output - files. This string is limited to 52 characters for formatting purposes. - - *Default*: "" - - :n_rings: - An integer representing the number of radial ring positions in the xy-plane. - Note that this number includes the degenerate center ring which only has one - element. - - *Default*: None - - :n_axial: - An integer representing the number of positions along the z-axis. This - element is optional. - - *Default*: None - - :center: - The coordinates of the center of the lattice. If the lattice does not have - axial sections then only the x- and y-coordinates are specified. - - *Default*: None - - :pitch: - If the lattice is 3D, then two real numbers that express the distance - between the centers of lattice cells in the xy-plane and along the z-axis, - respectively. If the lattice is 2D, then omit the second value. - - *Default*: None - - :outer: - The unique integer identifier of a universe that will be used to fill all - space outside of the lattice. The universe will be tiled repeatedly as if - it were placed in a lattice of infinite size. This element is optional. - - *Default*: An error will be raised if a particle leaves a lattice with no - outer universe. - - :universes: - A list of the universe numbers that fill each cell of the lattice. - - *Default*: None - -Here is an example of a properly defined 2d hexagonal lattice: - -.. code-block:: xml - - -
0.0 0.0
- 1.0 - - 202 - 202 202 - 202 202 202 - 202 202 - 202 101 202 - 202 202 - 202 202 202 - 202 202 - 202 - - - -.. _constructive solid geometry: http://en.wikipedia.org/wiki/Constructive_solid_geometry - -.. _quadratic surfaces: http://en.wikipedia.org/wiki/Quadric - ----------------------------------------- -Materials Specification -- materials.xml ----------------------------------------- - -.. _cross_sections: - -```` Element ----------------------------- - -The ```` element has no attributes and simply indicates the path -to an XML cross section listing file (usually named cross_sections.xml). If this -element is absent from the settings.xml file, the -:envvar:`OPENMC_CROSS_SECTIONS` environment variable will be used to find the -path to the XML cross section listing when in continuous-energy mode, and the -:envvar:`OPENMC_MG_CROSS_SECTIONS` environment variable will be used in -multi-group mode. - -.. _multipole_library: - -```` Element -------------------------------- - -The ```` element indicates the directory containing a -windowed multipole library. If a windowed multipole library is available, -OpenMC can use it for on-the-fly Doppler-broadening of resolved resonance range -cross sections. If this element is absent from the settings.xml file, the -:envvar:`OPENMC_MULTIPOLE_LIBRARY` environment variable will be used. - - .. note:: The element must also be set to "true" for - windowed multipole functionality. - -.. _material: - -```` Element ----------------------- - -Each ``material`` element can have the following attributes or sub-elements: - - :id: - A unique integer that can be used to identify the material. - - :name: - An optional string name to identify the material in summary output - files. This string is limited to 52 characters for formatting purposes. - - *Default*: "" - - :temperature: - An element with no attributes which is used to set the default temperature - of the material in Kelvin. - - *Default*: If a material default temperature is not given and a cell - temperature is not specified, the :ref:`global default temperature - ` 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`` - 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 ```` - and ```` sub-elements are to be interpreted as absolute nuclide/element - densities in atom/b-cm or g/cm3, and the total density of the material is - taken as the sum of all nuclides/elements. The "macro" unit is used with - 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. - - *Default*: None - - .. note:: A ``macroscopic`` quantity can not be used in conjunction with a - ``nuclide``, ``element``, or ``sab`` quantity. - - :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 - desired nuclide. Finally, the ``ao`` and ``wo`` attributes specify the atom or - weight percent of that nuclide within the material, respectively. One - example would be as follows: - - .. code-block:: xml - - - - - .. note:: If one nuclide is specified in atom percent, all others must also - be given in atom percent. The same applies for weight percentages. - - An optional attribute/sub-element for each nuclide is ``scattering``. This - attribute may be set to "data" to use the scattering laws specified by the - cross section library (default). Alternatively, when set to "iso-in-lab", - the scattering laws are used to sample the outgoing energy but an - isotropic-in-lab distribution is used to sample the outgoing angle at each - scattering interaction. The ``scattering`` attribute may be most useful - when using OpenMC to compute multi-group cross-sections for deterministic - transport codes and to quantify the effects of anisotropic scattering. - - *Default*: None - - .. note:: The ``scattering`` attribute/sub-element is not used in the - multi-group :ref:`energy_mode`. - - :sab: - Associates an S(a,b) table with the material. This element has one - attribute/sub-element called ``name``. The ``name`` attribute - is the name of the S(a,b) table that should be associated with the material. - - *Default*: None - - .. note:: This element is not used in the multi-group :ref:`energy_mode`. - - :macroscopic: - The ``macroscopic`` element is similar to the ``nuclide`` element, but, - recognizes that some multi-group libraries may be providing material - specific macroscopic cross sections instead of always providing nuclide - specific data like in the continuous-energy case. To that end, the - macroscopic element has one attribute/sub-element called ``name``. - The ``name`` attribute is the name of the cross-section for a - desired nuclide. One example would be as follows: - - .. code-block:: xml - - - - .. note:: This element is only used in the multi-group :ref:`energy_mode`. - - *Default*: None - ------------------------------------- -Tallies Specification -- tallies.xml ------------------------------------- - -The tallies.xml file allows the user to tell the code what results he/she is -interested in, e.g. the fission rate in a given cell or the current across a -given surface. There are two pieces of information that determine what -quantities should be scored. First, one needs to specify what region of phase -space should count towards the tally and secondly, the actual quantity to be -scored also needs to be specified. The first set of parameters we call *filters* -since they effectively serve to filter events, allowing some to score and -preventing others from scoring to the tally. - -The structure of tallies in OpenMC is flexible in that any combination of -filters can be used for a tally. The following types of filter are available: -cell, universe, material, surface, birth region, pre-collision energy, -post-collision energy, and an arbitrary structured mesh. - -The three valid elements in the tallies.xml file are ````, ````, -and ````. - -.. _tally: - -```` Element -------------------- - -The ```` element accepts the following sub-elements: - - :name: - An optional string name to identify the tally in summary output - files. This string is limited to 52 characters for formatting purposes. - - *Default*: "" - - :filter: - Specify a filter that modifies tally behavior. Most tallies (e.g. ``cell``, - ``energy``, and ``material``) restrict the tally so that only particles - within certain regions of phase space contribute to the tally. Others - (e.g. ``delayedgroup`` and ``energyfunction``) can apply some other function - to the scored values. This element and its attributes/sub-elements are - described below. - - .. note:: - You may specify zero, one, or multiple filters to apply to the tally. To - specify multiple filters, you must use multiple ```` elements. - - The ``filter`` element has the following attributes/sub-elements: - - :type: - The type of the filter. Accepted options are "cell", "cellborn", - "material", "universe", "energy", "energyout", "mu", "polar", - "azimuthal", "mesh", "distribcell", "delayedgroup", and - "energyfunction". - - :bins: - A description of the bins for each type of filter can be found in - :ref:`filter_types`. - - :energy: - ``energyfunction`` filters multiply tally scores by an arbitrary - function. The function is described by a piecewise linear-linear set of - (energy, y) values. This entry specifies the energy values. The function - will be evaluated as zero outside of the bounds of this energy grid. - (Only used for ``energyfunction`` filters) - - :y: - ``energyfunction`` filters multiply tally scores by an arbitrary - function. The function is described by a piecewise linear-linear set of - (energy, y) values. This entry specifies the y values. (Only used - for ``energyfunction`` filters) - - :nuclides: - If specified, the scores listed will be for particular nuclides, not the - summation of reactions from all nuclides. The format for nuclides should be - [Atomic symbol]-[Mass number], e.g. "U-235". The reaction rate for all - nuclides can be obtained with "total". For example, to obtain the reaction - rates for U-235, Pu-239, and all nuclides in a material, this element should - be: - - .. code-block:: xml - - U-235 Pu-239 total - - *Default*: total - - :estimator: - The estimator element is used to force the use of either ``analog``, - ``collision``, or ``tracklength`` tally estimation. ``analog`` is generally - the least efficient though it can be used with every score type. - ``tracklength`` is generally the most efficient, but neither ``tracklength`` - nor ``collision`` can be used to score a tally that requires post-collision - information. For example, a scattering tally with outgoing energy filters - cannot be used with ``tracklength`` or ``collision`` because the code will - not know the outgoing energy distribution. - - *Default*: ``tracklength`` but will revert to ``analog`` if necessary. - - :scores: - A space-separated list of the desired responses to be accumulated. The accepted - options are listed in the following tables: - - .. table:: **Flux scores: units are particle-cm per source particle.** - - +----------------------+---------------------------------------------------+ - |Score | Description | - +======================+===================================================+ - |flux |Total flux. | - +----------------------+---------------------------------------------------+ - |flux-YN |Spherical harmonic expansion of the direction of | - | |motion :math:`\left(\Omega\right)` of the total | - | |flux. This score will tally all of the harmonic | - | |moments of order 0 to N. N must be between 0 and | - | |10. | - +----------------------+---------------------------------------------------+ - - .. table:: **Reaction scores: units are reactions per source particle.** - - +----------------------+---------------------------------------------------+ - |Score | Description | - +======================+===================================================+ - |absorption |Total absorption rate. This accounts for all | - | |reactions which do not produce secondary neutrons | - | |as well as fission. | - +----------------------+---------------------------------------------------+ - |elastic |Elastic scattering reaction rate. | - +----------------------+---------------------------------------------------+ - |fission |Total fission reaction rate. | - +----------------------+---------------------------------------------------+ - |scatter |Total scattering rate. Can also be identified with | - | |the "scatter-0" response type. | - +----------------------+---------------------------------------------------+ - |scatter-N |Tally the N\ :sup:`th` \ scattering moment, where N| - | |is the Legendre expansion order of the change in | - | |particle angle :math:`\left(\mu\right)`. N must be | - | |between 0 and 10. As an example, tallying the 2\ | - | |:sup:`nd` \ scattering moment would be specified as| - | |``scatter-2``. | - +----------------------+---------------------------------------------------+ - |scatter-PN |Tally all of the scattering moments from order 0 to| - | |N, where N is the Legendre expansion order of the | - | |change in particle angle | - | |:math:`\left(\mu\right)`. That is, "scatter-P1" is | - | |equivalent to requesting tallies of "scatter-0" and| - | |"scatter-1". Like for "scatter-N", N must be | - | |between 0 and 10. As an example, tallying up to the| - | |2\ :sup:`nd` \ scattering moment would be specified| - | |as `` scatter-P2 ``. | - +----------------------+---------------------------------------------------+ - |scatter-YN |"scatter-YN" is similar to "scatter-PN" except an | - | |additional expansion is performed for the incoming | - | |particle direction :math:`\left(\Omega\right)` | - | |using the real spherical harmonics. This is useful| - | |for performing angular flux moment weighting of the| - | |scattering moments. Like "scatter-PN", "scatter-YN"| - | |will tally all of the moments from order 0 to N; N | - | |again must be between 0 and 10. | - +----------------------+---------------------------------------------------+ - |total |Total reaction rate. | - +----------------------+---------------------------------------------------+ - |total-YN |The total reaction rate expanded via spherical | - | |harmonics about the direction of motion of the | - | |neutron, :math:`\Omega`. This score will tally all | - | |of the harmonic moments of order 0 to N. N must be| - | |between 0 and 10. | - +----------------------+---------------------------------------------------+ - |(n,2nd) |(n,2nd) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,2n) |(n,2n) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,3n) |(n,3n) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,na) |(n,n\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,n3a) |(n,n3\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,2na) |(n,2n\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,3na) |(n,3n\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,np) |(n,np) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,n2a) |(n,n2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,2n2a) |(n,2n2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,nd) |(n,nd) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,nt) |(n,nt) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,nHe-3) |(n,n\ :sup:`3`\ He) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,nd2a) |(n,nd2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,nt2a) |(n,nt2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,4n) |(n,4n) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,2np) |(n,2np) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,3np) |(n,3np) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,n2p) |(n,n2p) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,n*X*) |Level inelastic scattering reaction rate. The *X* | - | |indicates what which inelastic level, e.g., (n,n3) | - | |is third-level inelastic scattering. | - +----------------------+---------------------------------------------------+ - |(n,nc) |Continuum level inelastic scattering reaction rate.| - +----------------------+---------------------------------------------------+ - |(n,gamma) |Radiative capture reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,p) |(n,p) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,d) |(n,d) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,t) |(n,t) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,3He) |(n,\ :sup:`3`\ He) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,a) |(n,\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,2a) |(n,2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,3a) |(n,3\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,2p) |(n,2p) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,pa) |(n,p\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,t2a) |(n,t2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,d2a) |(n,d2\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,pd) |(n,pd) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,pt) |(n,pt) reaction rate. | - +----------------------+---------------------------------------------------+ - |(n,da) |(n,d\ :math:`\alpha`\ ) reaction rate. | - +----------------------+---------------------------------------------------+ - |*Arbitrary integer* |An arbitrary integer is interpreted to mean the | - | |reaction rate for a reaction with a given ENDF MT | - | |number. | - +----------------------+---------------------------------------------------+ - - .. table:: **Particle production scores: units are particles produced per - source particles.** - - +----------------------+---------------------------------------------------+ - |Score | Description | - +======================+===================================================+ - |delayed-nu-fission |Total production of delayed neutrons due to | - | |fission. | - +----------------------+---------------------------------------------------+ - |prompt-nu-fission |Total production of prompt neutrons due to | - | |fission. | - +----------------------+---------------------------------------------------+ - |nu-fission |Total production of neutrons due to fission. | - +----------------------+---------------------------------------------------+ - |nu-scatter, |These scores are similar in functionality to their | - |nu-scatter-N, |``scatter*`` equivalents except the total | - |nu-scatter-PN, |production of neutrons due to scattering is scored | - |nu-scatter-YN |vice simply the scattering rate. This accounts for | - | |multiplicity from (n,2n), (n,3n), and (n,4n) | - | |reactions. | - +----------------------+---------------------------------------------------+ - - .. table:: **Miscellaneous scores: units are indicated for each.** - - +----------------------+---------------------------------------------------+ - |Score | Description | - +======================+===================================================+ - |current |Partial currents on the boundaries of each cell in | - | |a mesh. Units are particles per source | - | |particle. Note that this score can only be used if | - | |a mesh filter has been specified. Furthermore, it | - | |may not be used in conjunction with any other | - | |score. | - +----------------------+---------------------------------------------------+ - |events |Number of scoring events. Units are events per | - | |source particle. | - +----------------------+---------------------------------------------------+ - |inverse-velocity |The flux-weighted inverse velocity where the | - | |velocity is in units of centimeters per second. | - +----------------------+---------------------------------------------------+ - |kappa-fission |The recoverable energy production rate due to | - | |fission. The recoverable energy is defined as the | - | |fission product kinetic energy, prompt and delayed | - | |neutron kinetic energies, prompt and delayed | - | |:math:`\gamma`-ray total energies, and the total | - | |energy released by the delayed :math:`\beta` | - | |particles. The neutrino energy does not contribute | - | |to this response. The prompt and delayed | - | |:math:`\gamma`-rays are assumed to deposit their | - | |energy locally. Units are eV per source particle. | - +----------------------+---------------------------------------------------+ - |fission-q-prompt |The prompt fission energy production rate. This | - | |energy comes in the form of fission fragment | - | |nuclei, prompt neutrons, and prompt | - | |:math:`\gamma`-rays. This value depends on the | - | |incident energy and it requires that the nuclear | - | |data library contains the optional fission energy | - | |release data. Energy is assumed to be deposited | - | |locally. Units are eV per source particle. | - +----------------------+---------------------------------------------------+ - |fission-q-recoverable |The recoverable fission energy production rate. | - | |This energy comes in the form of fission fragment | - | |nuclei, prompt and delayed neutrons, prompt and | - | |delayed :math:`\gamma`-rays, and delayed | - | |:math:`\beta`-rays. This tally differs from the | - | |kappa-fission tally in that it is dependent on | - | |incident neutron energy and it requires that the | - | |nuclear data library contains the optional fission | - | |energy release data. Energy is assumed to be | - | |deposited locally. Units are eV per source | - | |paticle. | - +----------------------+---------------------------------------------------+ - |decay-rate |The delayed-nu-fission-weighted decay rate where | - | |the decay rate is in units of inverse seconds. | - +----------------------+---------------------------------------------------+ - - .. note:: - The ``analog`` estimator is actually identical to the ``collision`` - estimator for the flux and inverse-velocity scores. - - :trigger: - Precision trigger applied to all filter bins and nuclides for this tally. - It must specify the trigger's type, threshold and scores to which it will - be applied. It has the following attributes/sub-elements: - - :type: - The type of the trigger. Accepted options are "variance", "std_dev", - and "rel_err". - - :variance: - Variance of the batch mean :math:`\sigma^2` - - :std_dev: - Standard deviation of the batch mean :math:`\sigma` - - :rel_err: - Relative error of the batch mean :math:`\frac{\sigma}{\mu}` - - *Default*: None - - :threshold: - The precision trigger's convergence criterion for tallied values. - - *Default*: None - - :scores: - The score(s) in this tally to which the trigger should be applied. - - .. note:: The ``scores`` in ``trigger`` must have been defined in - ``scores`` in ``tally``. An optional "all" may be used to - select all scores in this tally. - - *Default*: "all" - - :derivative: - The id of a ``derivative`` element. This derivative will be applied to all - scores in the tally. Differential tallies are currently only implemented - for collision and analog estimators. - - *Default*: None - -.. _filter_types: - -Filter Types -++++++++++++ - -For each filter type, the following table describes what the ``bins`` attribute -should be set to: - -:cell: - A list of unique IDs for cells in which the tally should be accumulated. - -:cellborn: - This filter allows the tally to be scored to only when particles were - originally born in a specified cell. A list of cell IDs should be given. - -:material: - A list of unique IDs for matreials in which the tally should be accumulated. - -:universe: - A list of unique IDs for universes in which the tally should be accumulated. - -:energy: - In continuous-energy mode, this filter should be provided as a - monotonically increasing list of bounding **pre-collision** energies - for a number of groups. For example, if this filter is specified as - - .. code-block:: xml - - - - then two energy bins will be created, one with energies between 0 and - 1 MeV and the other with energies between 1 and 20 MeV. - - In multi-group mode the bins provided must match group edges - defined in the multi-group library. - -:energyout: - In continuous-energy mode, this filter should be provided as a - monotonically increasing list of bounding **post-collision** energies - for a number of groups. For example, if this filter is specified as - - .. code-block:: xml - - - - then two post-collision energy bins will be created, one with - energies between 0 and 1 MeV and the other with energies between - 1 and 20 MeV. - - In multi-group mode the bins provided must match group edges - defined in the multi-group library. - -:mu: - A monotonically increasing list of bounding **post-collision** cosines - of the change in a particle's angle (i.e., :math:`\mu = \hat{\Omega} - \cdot \hat{\Omega}'`), which represents a portion of the possible - values of :math:`[-1,1]`. For example, spanning all of :math:`[-1,1]` - with five equi-width bins can be specified as: - - .. code-block:: xml - - - - Alternatively, if only one value is provided as a bin, OpenMC will - interpret this to mean the complete range of :math:`[-1,1]` should - be automatically subdivided in to the provided value for the bin. - That is, the above example of five equi-width bins spanning - :math:`[-1,1]` can be instead written as: - - .. code-block:: xml - - - -:polar: - A monotonically increasing list of bounding particle polar angles - which represents a portion of the possible values of :math:`[0,\pi]`. - For example, spanning all of :math:`[0,\pi]` with five equi-width - bins can be specified as: - - .. code-block:: xml - - - - Alternatively, if only one value is provided as a bin, OpenMC will - interpret this to mean the complete range of :math:`[0,\pi]` should - be automatically subdivided in to the provided value for the bin. - That is, the above example of five equi-width bins spanning - :math:`[0,\pi]` can be instead written as: - - .. code-block:: xml - - - -:azimuthal: - A monotonically increasing list of bounding particle azimuthal angles - which represents a portion of the possible values of :math:`[-\pi,\pi)`. - For example, spanning all of :math:`[-\pi,\pi)` with two equi-width - bins can be specified as: - - .. code-block:: xml - - - - Alternatively, if only one value is provided as a bin, OpenMC will - interpret this to mean the complete range of :math:`[-\pi,\pi)` should - be automatically subdivided in to the provided value for the bin. - That is, the above example of five equi-width bins spanning - :math:`[-\pi,\pi)` can be instead written as: - - .. code-block:: xml - - - -:mesh: - The unique ID of a structured mesh to be tallied over. - -:distribcell: - The single cell which should be tallied uniquely for all instances. - - .. note:: The distribcell filter will take a single cell ID and will tally - each unique occurrence of that cell separately. This filter will not - accept more than one cell ID. It is not recommended to combine this - filter with a cell or mesh filter. - -:delayedgroup: - A list of delayed neutron precursor groups for which the tally should - be accumulated. For instance, to tally to all 6 delayed groups in the - ENDF/B-VII.1 library the filter is specified as: - - .. code-block:: xml - - - -:energyfunction: - ``energyfunction`` filters do not use the ``bins`` entry. Instead - they use ``energy`` and ``y``. - - -```` Element ------------------- - -If a structured mesh is desired as a filter for a tally, it must be specified in -a separate element with the tag name ````. This element has the following -attributes/sub-elements: - - :type: - The type of structured mesh. The only valid option is "regular". - - :dimension: - The number of mesh cells in each direction. - - :lower_left: - The lower-left corner of the structured mesh. If only two coordinates are - given, it is assumed that the mesh is an x-y mesh. - - :upper_right: - The upper-right corner of the structured mesh. If only two coordinates are - given, it is assumed that the mesh is an x-y mesh. - - :width: - The width of mesh cells in each direction. - - .. note:: - One of ```` or ```` must be specified, but not both - (even if they are consistent with one another). - -```` Element ------------------------- - -OpenMC can take the first-order derivative of many tallies with respect to -material perturbations. It works by propagating a derivative through the -transport equation. Essentially, OpenMC keeps track of how each particle's -weight would change as materials are perturbed, and then accounts for that -weight change in the tallies. Note that this assumes material perturbations are -small enough not to change the distribution of fission sites. This element has -the following attributes/sub-elements: - - :id: - A unique integer that can be used to identify the derivative. - - :variable: - The independent variable of the derivative. Accepted options are "density", - "nuclide_density", and "temperature". A "density" derivative will give the - derivative with respect to the density of the material in [g / cm^3]. A - "nuclide_density" derivative will give the derivative with respect to the - density of a particular nuclide in units of [atom / b / cm]. A - "temperature" derivative is with respect to a material temperature in units - of [K]. The temperature derivative requires windowed multipole to be - turned on. Note also that the temperature derivative only accounts for - resolved resonance Doppler broadening. It does not account for thermal - expansion, S(a, b) scattering, resonance scattering, or unresolved Doppler - broadening. - - :material: - The perturbed material. (Necessary for all derivative types) - - :nuclide: - The perturbed nuclide. (Necessary only for "nuclide_density") - -```` Element ------------------------------ - -In cases where the user needs to specify many different tallies each of which -are spatially separate, this tag can be used to cut down on some of the tally -overhead. The effect of assuming all tallies are spatially separate is that once -one tally is scored to, the same event is assumed not to score to any other -tallies. This element should be followed by "true" or "false". - - .. warning:: If used incorrectly, the assumption that all tallies are - spatially separate can lead to incorrect results. - - *Default*: false - -.. _usersguide_plotting: - --------------------------------------------- -Geometry Plotting Specification -- plots.xml --------------------------------------------- - -Basic plotting capabilities are available in OpenMC by creating a plots.xml -file and subsequently running with the command-line flag ``-plot``. The root -element of the plots.xml is simply ```` and any number output plots can -be defined with ```` sub-elements. Two plot types are currently -implemented in openMC: - -* ``slice`` 2D pixel plot along one of the major axes. Produces a PPM image - file. -* ``voxel`` 3D voxel data dump. Produces a binary file containing voxel xyz - position and cell or material id. - - -```` Element ------------------- - -Each plot is specified by a combination of the following attributes or -sub-elements: - - :id: - The unique ``id`` of the plot. - - *Default*: None - Required entry - - :filename: - Filename for the output plot file. - - *Default*: "plot" - - :color_by: - Keyword for plot coloring. This can be either "cell" or "material", which - colors regions by cells and materials, respectively. For voxel plots, this - determines which id (cell or material) is associated with each position. - - *Default*: "cell" - - :level: - Universe depth to plot at (optional). This parameter controls how many - universe levels deep to pull cell and material ids from when setting plot - colors. If a given location does not have as many levels as specified, - colors will be taken from the lowest level at that location. For example, if - ``level`` is set to zero colors will be taken from top-level (universe zero) - cells only. However, if ``level`` is set to 1 colors will be taken from - cells in universes that fill top-level fill-cells, and from top-level cells - that contain materials. - - *Default*: Whatever the deepest universe is in the model - - :origin: - Specifies the (x,y,z) coordinate of the center of the plot. Should be three - floats separated by spaces. - - *Default*: None - Required entry - - :width: - Specifies the width of the plot along each of the basis directions. Should - be two or three floats separated by spaces for 2D plots and 3D plots, - respectively. - - *Default*: None - Required entry - - :type: - Keyword for type of plot to be produced. Currently only "slice" and "voxel" - plots are implemented. The "slice" plot type creates 2D pixel maps saved in - the PPM file format. PPM files can be displayed in most viewers (e.g. the - default Gnome viewer, IrfanView, etc.). The "voxel" plot type produces a - binary datafile containing voxel grid positioning and the cell or material - (specified by the ``color`` tag) at the center of each voxel. These - datafiles can be processed into 3D SILO files using the - ``openmc-voxel-to-silovtk`` utility provided with the OpenMC source, and - subsequently viewed with a 3D viewer such as VISIT or Paraview. See the - :ref:`io_voxel` for information about the datafile structure. - - .. note:: Since the PPM format is saved without any kind of compression, - the resulting file sizes can be quite large. Saving the image in - the PNG format can often times reduce the file size by orders of - magnitude without any loss of image quality. Likewise, - high-resolution voxel files produced by OpenMC can be quite large, - but the equivalent SILO files will be significantly smaller. - - *Default*: "slice" - -```` elements of ``type`` "slice" and "voxel" must contain the ``pixels`` -attribute or sub-element: - - :pixels: - Specifies the number of pixels or voxels to be used along each of the basis - directions for "slice" and "voxel" plots, respectively. Should be two or - three integers separated by spaces. - - .. warning:: The ``pixels`` input determines the output file size. For the - PPM format, 10 million pixels will result in a file just under - 30 MB in size. A 10 million voxel binary file will be around - 40 MB. - - .. warning:: If the aspect ratio defined in ``pixels`` does not match the - aspect ratio defined in ``width`` the plot may appear stretched - or squeezed. - - .. warning:: Geometry features along a basis direction smaller than - ``width``/``pixels`` along that basis direction may not appear - in the plot. - - *Default*: None - Required entry for "slice" and "voxel" plots - -```` elements of ``type`` "slice" can also contain the following -attributes or sub-elements. These are not used in "voxel" plots: - - :basis: - Keyword specifying the plane of the plot for "slice" type plots. Can be - one of: "xy", "xz", "yz". - - *Default*: "xy" - - :background: - Specifies the RGB color of the regions where no OpenMC cell can be found. - Should be three integers separated by spaces. - - *Default*: 0 0 0 (black) - - :color: - Any number of this optional tag may be included in each ```` element, - which can override the default random colors for cells or materials. Each - ``color`` element must contain ``id`` and ``rgb`` sub-elements. - - :id: - Specifies the cell or material unique id for the color specification. - - :rgb: - Specifies the custom color for the cell or material. Should be 3 integers - separated by spaces. - - As an example, if your plot is colored by material and you want material 23 - to be blue, the corresponding ``color`` element would look like: - - .. code-block:: xml - - - - *Default*: None - - :mask: - The special ``mask`` sub-element allows for the selective plotting of *only* - user-specified cells or materials. Only one ``mask`` element is allowed per - ``plot`` element, and it must contain as attributes or sub-elements a - background masking color and a list of cells or materials to plot: - - :components: - List of unique ``id`` numbers of the cells or materials to plot. Should be - any number of integers separated by spaces. - - :background: - Color to apply to all cells or materials not in the ``components`` list of - cells or materials to plot. This overrides any ``color`` color - specifications. - - *Default*: 255 255 255 (white) - - :meshlines: - The ``meshlines`` sub-element allows for plotting the boundaries of a - regular mesh on top of a plot. Only one ``meshlines`` element is allowed per - ``plot`` element, and it must contain as attributes or sub-elements a mesh - type and a linewidth. Optionally, a color may be specified for the overlay: - - :meshtype: - The type of the mesh to be plotted. Valid options are "tally", "entropy", - "ufs", and "cmfd". If plotting "tally" meshes, the id of the mesh to plot - must be specified with the ``id`` sub-element. - - :id: - A single integer id number for the mesh specified on ``tallies.xml`` that - should be plotted. This element is only required for ``meshtype="tally"``. - - :linewidth: - A single integer number of pixels of linewidth to specify for the mesh - boundaries. Specifying this as 0 indicates that lines will be 1 pixel - thick, specifying 1 indicates 3 pixels thick, specifying 2 indicates - 5 pixels thick, etc. - - :color: - Specifies the custom color for the meshlines boundaries. Should be 3 - integers separated by whitespace. This element is optional. - - *Default*: 0 0 0 (black) - - *Default*: None - -.. _usersguide_cmfd: - ------------------------------- -CMFD Specification -- cmfd.xml ------------------------------- - -Coarse mesh finite difference acceleration method has been implemented in -OpenMC. Currently, it allows users to accelerate fission source convergence -during inactive neutron batches. To run CMFD, the ```` element in -``settings.xml`` should be set to "true". - -```` Element -------------------- - -The ```` element controls what batch CMFD calculations should begin. - - *Default*: 1 - -```` Element ------------------------- - -The ```` element controls whether :math:`\widehat{D}` nonlinear -CMFD parameters should be reset to zero before solving CMFD eigenproblem. -It can be turned on with "true" and off with "false". - - *Default*: false - -```` Element ---------------------- - -The ```` element sets one additional CMFD output column. Options are: - -* "balance" - prints the RMS [%] of the resdiual from the neutron balance - equation on CMFD tallies. -* "dominance" - prints the estimated dominance ratio from the CMFD iterations. - **This will only work for power iteration eigensolver**. -* "entropy" - prints the *entropy* of the CMFD predicted fission source. - **Can only be used if OpenMC entropy is active as well**. -* "source" - prints the RMS [%] between the OpenMC fission source and CMFD - fission source. - - *Default*: balance - -```` Element -------------------------- - -The ```` element controls whether an effective downscatter cross -section should be used when using 2-group CMFD. It can be turned on with "true" -and off with "false". - - *Default*: false - -```` Element ----------------------- - -The ```` element controls whether or not the CMFD diffusion result is -used to adjust the weight of fission source neutrons on the next OpenMC batch. -It can be turned on with "true" and off with "false". - - *Default*: false - -```` Element ------------------------------------- - -The ```` element specifies two parameters. The first is -the absolute inner tolerance for Gauss-Seidel iterations when performing CMFD -and the second is the relative inner tolerance for Gauss-Seidel iterations -for CMFD calculations. - - *Default*: 1.e-10 1.e-5 - -```` Element --------------------- - -The ```` element specifies the tolerance on the eigenvalue when performing -CMFD power iteration. - - *Default*: 1.e-8 - -```` Element ------------------- - -The CMFD mesh is a structured Cartesian mesh. This element has the following -attributes/sub-elements: - - :lower_left: - The lower-left corner of the structured mesh. If only two coordinates are - given, it is assumed that the mesh is an x-y mesh. - - :upper_right: - The upper-right corner of the structrued mesh. If only two coordinates are - given, it is assumed that the mesh is an x-y mesh. - - :dimension: - The number of mesh cells in each direction. - - :width: - The width of mesh cells in each direction. - - :energy: - Energy bins [in eV], listed in ascending order (e.g. 0.0 0.625 20.0e6) - for CMFD tallies and acceleration. If no energy bins are listed, OpenMC - automatically assumes a one energy group calculation over the entire - energy range. - - :albedo: - Surface ratio of incoming to outgoing partial currents on global boundary - conditions. They are listed in the following order: -x +x -y +y -z +z. - - *Default*: 1.0 1.0 1.0 1.0 1.0 1.0 - - :map: - An optional acceleration map can be specified to overlay on the coarse - mesh spatial grid. If this option is used, a ``1`` is used for a - non-accelerated region and a ``2`` is used for an accelerated region. - For a simple 4x4 coarse mesh with a 2x2 fuel lattice surrounded by - reflector, the map is: - - ``1 1 1 1`` - - ``1 2 2 1`` - - ``1 2 2 1`` - - ``1 1 1 1`` - - Therefore a 2x2 system of equations is solved rather than a 4x4. This - is extremely important to use in reflectors as neutrons will not - contribute to any tallies far away from fission source neutron regions. - A ``2`` must be used to identify any fission source region. - - .. note:: Only two of the following three sub-elements are needed: - ``lower_left``, ``upper_right`` and ``width``. Any combination - of two of these will yield the third. - -```` Element ------------------- - -The ```` element is used to normalize the CMFD fission source distribution -to a particular value. For example, if a fission source is calculated for a -17 x 17 lattice of pins, the fission source may be normalized to the number of -fission source regions, in this case 289. This is useful when visualizing this -distribution as the average peaking factor will be unity. This parameter will -not impact the calculation. - - *Default*: 1.0 - -```` Element ---------------------------- - -The ```` element is used to view the convergence of power -iteration. This option can be turned on with "true" and turned off with "false". - - *Default*: false - -```` Element -------------------------- - -The ```` element can be turned on with "true" to have an adjoint -calculation be performed on the last batch when CMFD is active. - - *Default*: false - -```` Element --------------------- - -The ```` element specifies an optional Wielandt shift parameter for -accelerating power iterations. It is by default very large so the impact of the -shift is effectively zero. - - *Default*: 1e6 - -```` Element ----------------------- - -The ```` element specifies an optional spectral radius that can be set to -accelerate the convergence of Gauss-Seidel iterations during CMFD power iteration -solve. - - *Default*: 0.0 - -```` Element ------------------- - -The ```` element specifies the tolerance on the fission source when performing -CMFD power iteration. - - *Default*: 1.e-8 - -```` Element -------------------------- - -The ```` element contains a list of batch numbers in which CMFD tallies -should be reset. - - *Default*: None - -```` Element ----------------------------- - -The ```` element is used to write the sparse matrices created -when solving CMFD equations. This option can be turned on with "true" and off -with "false". - - *Default*: false - ------------------------------------- -ERSN-OpenMC Graphical User Interface ------------------------------------- - -A third-party Java-based user-friendly graphical user interface for creating XML -input files called ERSN-OpenMC_ is developed and maintained by members of the -Radiation and Nuclear Systems Group at the Faculty of Sciences Tetouan, Morocco. -The GUI also allows one to automatically download prerequisites for installing and -running OpenMC. - -.. _ERSN-OpenMC: https://github.com/EL-Bakkali-Jaafar/ERSN-OpenMC diff --git a/docs/source/usersguide/install.rst b/docs/source/usersguide/install.rst index e980407084..4d9a0849ec 100644 --- a/docs/source/usersguide/install.rst +++ b/docs/source/usersguide/install.rst @@ -76,6 +76,7 @@ Prerequisites ------------- .. admonition:: Required + :class: error * A Fortran compiler such as gfortran_ @@ -140,6 +141,7 @@ Prerequisites distribution and version. .. admonition:: Optional + :class: note * An MPI implementation for distributed-memory parallel runs @@ -511,45 +513,6 @@ to the absolute path of the file library expected to used most frequently. .. _Serpent: http://montecarlo.vtt.fi .. _TENDL: https://tendl.web.psi.ch/tendl_2015/tendl2015.html --------------- -Running OpenMC --------------- - -Once you have a model built (see :ref:`usersguide_input`), you can either run -the openmc executable directly from the directory containing your XML input -files, or you can specify as a command-line argument the directory containing -the XML input files. For example, if your XML input files are in the directory -``/home/username/somemodel/``, one way to run the simulation would be: - -.. code-block:: sh - - cd /home/username/somemodel - openmc - -Alternatively, you could run from any directory: - -.. code-block:: sh - - openmc /home/username/somemodel - -Note that in the latter case, any output files will be placed in the present -working directory which may be different from ``/home/username/somemodel``. - -Command-Line Flags ------------------- - -OpenMC accepts the following command line flags: - --g, --geometry-debug Run in geometry debugging mode, where cell overlaps are - checked for after each move of a particle --n, --particles N Use *N* particles per generation or batch --p, --plot Run in plotting mode --r, --restart file Restart a previous run from a state point or a particle - restart file --s, --threads N Run with *N* OpenMP threads --t, --track Write tracks for all particles --v, --version Show version information - ----------------------------------------------------- Configuring Input Validation with GNU Emacs nXML mode ----------------------------------------------------- diff --git a/docs/source/usersguide/scripts.rst b/docs/source/usersguide/scripts.rst new file mode 100644 index 0000000000..f99ddbc91f --- /dev/null +++ b/docs/source/usersguide/scripts.rst @@ -0,0 +1,120 @@ +.. _usersguide_scripts: + +======================= +Executables and Scripts +======================= + +.. _scripts_openmc: + +---------- +``openmc`` +---------- + +Once you have a model built (see :ref:`usersguide_basics`), you can either run +the openmc executable directly from the directory containing your XML input +files, or you can specify as a command-line argument the directory containing +the XML input files. For example, if your XML input files are in the directory +``/home/username/somemodel/``, one way to run the simulation would be: + +.. code-block:: sh + + cd /home/username/somemodel + openmc + +Alternatively, you could run from any directory: + +.. code-block:: sh + + openmc /home/username/somemodel + +Note that in the latter case, any output files will be placed in the present +working directory which may be different from ``/home/username/somemodel``. If +you're using the Python API, :func:`openmc.run` is equivalent to running +``openmc`` from the command line. OpenMC accepts the following command line +flags: + +-c, --volume Run in stochastic volume calculation mode +-g, --geometry-debug Run in geometry debugging mode, where cell overlaps are + checked for after each move of a particle +-n, --particles N Use *N* particles per generation or batch +-p, --plot Run in plotting mode +-r, --restart file Restart a previous run from a state point or a particle + restart file +-s, --threads N Run with *N* OpenMP threads +-t, --track Write tracks for all particles +-v, --version Show version information +-h, --help Show help message + +---------------------- +``openmc-ace-to-hdf5`` +---------------------- + +------------------------------ +``openmc-convert-mcnp70-data`` +------------------------------ + +------------------------------ +``openmc-convert-mcnp71-data`` +------------------------------ + +------------------------ +``openmc-get-jeff-data`` +------------------------ + +----------------------------- +``openmc-get-multipole-data`` +----------------------------- + +------------------------ +``openmc-get-nndc-data`` +------------------------ + +-------------------------- +``openmc-plot-mesh-tally`` +-------------------------- + +----------------------- +``openmc-track-to-vtk`` +----------------------- + +------------------------ +``openmc-update-inputs`` +------------------------ + +---------------------- +``openmc-update-mgxs`` +---------------------- + +.. _scripts_validate: + +----------------------- +``openmc-validate-xml`` +----------------------- + +Input files can be checked before executing OpenMC using the +``openmc-validate-xml`` script which is installed alongside the Python API. Two +command line arguments can be set when running ``openmc-validate-xml``: + +* ``-i``, ``--input-path`` - Location of OpenMC input files. + *Default*: current working directory +* ``-r``, ``--relaxng-path`` - Location of OpenMC RelaxNG files. + *Default*: None + +If the RelaxNG path is not set, the script will search for these files because +it expects that the user is either running the script located in the install +directory ``bin`` folder or in ``src/utils``. Once executed, it will match +OpenMC XML files with their RelaxNG schema and check if they are valid. Below +is a table of the messages that will be printed after each file is checked. + +======================== =================================== +Message Description +======================== =================================== +[XML ERROR] Cannot parse XML file. +[NO RELAXNG FOUND] No RelaxNG file found for XML file. +[NOT VALID] XML file does not match RelaxNG. +[VALID] XML file matches RelaxNG. +======================== =================================== + +--------------------------- +``openmc-voxel-to-silovtk`` +--------------------------- diff --git a/scripts/openmc-memory-usage b/scripts/openmc-memory-usage deleted file mode 100755 index 32655c62c7..0000000000 --- a/scripts/openmc-memory-usage +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python - -""" -This script reads a cross_sections.out file, adds up the memory usage for each -nuclide and S(a,b) table, and displays the total memory usage. - -""" - -from __future__ import print_function - -import sys -import os - -if len(sys.argv) > 1: - # Get path to cross_sections.out file from command line argument - filename = sys.argv[-1] -else: - # Set default path for cross_sections.out - filename = 'cross_sections.out' - if not os.path.exists(filename): - raise OSError('Could not find cross_sections.out file!') - -# Open file handle for cross_sections.out file -f = open(filename, 'r') - -# Initialize memory size arrays -memory_xs = [] -memory_angle = [] -memory_energy = [] -memory_urr = [] -memory_total = [] -memory_sab = [] - -while True: - # Read next line in file - line = f.readline() - - # Check for EOF - if line == '': - break - - # Look for block listing memory usage for a nuclide - words = line.split() - if len(words) == 2 and words[0] == 'Memory': - memory_xs.append(int(f.readline().split()[-2])) - memory_angle.append(int(f.readline().split()[-2])) - memory_energy.append(int(f.readline().split()[-2])) - memory_urr.append(int(f.readline().split()[-2])) - memory_total.append(int(f.readline().split()[-2])) - - # Look for memory usage for S(a,b) table - if len(words) == 5 and words[1] == 'Used': - memory_sab.append(int(words[-2])) - -# Write out summary memory usage -print('Memory Requirements') -print(' Reaction Cross Sections = ' + str(sum(memory_xs))) -print(' Secondary Angle Distributions = ' + str(sum(memory_angle))) -print(' Secondary Energy Distributions = ' + str(sum(memory_energy))) -print(' Probability Tables = ' + str(sum(memory_urr))) -print(' S(a,b) Tables = ' + str(sum(memory_sab))) -print(' Total = ' + str(sum(memory_total))) diff --git a/scripts/openmc-statepoint-3d b/scripts/openmc-statepoint-3d deleted file mode 100755 index e667ad0bbd..0000000000 --- a/scripts/openmc-statepoint-3d +++ /dev/null @@ -1,393 +0,0 @@ -#!/usr/bin/env python2 - -from __future__ import division, print_function - -import sys -import itertools -import re -import warnings - -from openmc.statepoint import StatePoint - -alphanum = re.compile(r"[\W_]+") - -err = False - -################################################################################ -def parse_options(): - """Process command line arguments""" - - - - def tallies_callback(option, opt, value, parser): - """Option parser function for list of tallies""" - global err - try: - setattr(parser.values, option.dest, [int(v) for v in value.split(',')]) - except: - p.print_help() - err = True - - def scores_callback(option, opt, value, parser): - """Option parser function for list of scores""" - global err - try: - scores = {} - entries = value.split(',') - for e in entries: - tally,score = [int(i) for i in e.split('.')] - if not tally in scores: scores[tally] = [] - scores[tally].append(score) - setattr(parser.values, option.dest, scores) - except: - p.print_help() - err = True - - def filters_callback(option, opt, value, parser): - """Option parser function for list of filters""" - global err - try: - filters = {} - entries = value.split(',') - for e in entries: - tally,filter_,bin = [i for i in e.split('.')] - tally,bin = int(tally),int(bin) - if not tally in filters: filters[tally] = {} - if not filter_ in filters[tally]: filters[tally][filter_] = [] - filters[tally][filter_].append(bin) - setattr(parser.values, option.dest, filters) - except: - p.print_help() - err = True - - from optparse import OptionParser - usage = r"""%prog [options] - -The default is to process all tallies and all scores into one file. Subsets -can be chosen using the options. For example, to only process tallies 2 and 4 -with all scores on tally 2 and only scores 1 and 3 on tally 4: - -%prog -t 2,4 -s 4.1,4.3 - -Likewise if you have additional filters on a tally you can specify a subset of -bins for each filter for that tally. For example to process all tallies and -scores, but only energyin bin #1 in tally 2: - -%prog -f 2.energyin.1 - -You can list the available tallies, scores, and filters with the -l option: - -%prog -l """ - p = OptionParser(usage=usage) - p.add_option('-t', '--tallies', dest='tallies', type='string', default=None, - action='callback', callback=tallies_callback, - help='List of tally indices to process, separated by commas.' \ - ' Default is to process all tallies.') - p.add_option('-s', '--scores', dest='scores', type='string', default=None, - action='callback', callback=scores_callback, - help='List of score indices to process, separated by commas, ' \ - 'specified as {tallyid}.{scoreid}.' \ - ' Default is to process all scores in each tally.') - p.add_option('-f', '--filters', dest='filters', type='string', default=None, - action='callback', callback=filters_callback, - help='List of filter bins to process, separated by commas, ' \ - 'specified as {tallyid}.{filter}.{binid}. ' \ - 'Default is to process all filter combinaiton for each score.') - p.add_option('-l', '--list', dest='list', action='store_true', - help='List the tally and score indices available in the file.') - p.add_option('-o', '--output', action='store', dest='output', - default='tally', help='path to output SILO file.') - p.add_option('-e', '--error', dest='valerr', default=False, - action='store_true', - help='Flag to extract errors instead of values.') - p.add_option('-v', '--vtk', action='store_true', dest='vtk', - default=False, help='Flag to convert to VTK instead of SILO.') - parsed = p.parse_args() - - if not parsed[1]: - p.print_help() - return parsed, err - - if parsed[0].valerr: - parsed[0].valerr = 1 - else: - parsed[0].valerr = 0 - - return parsed, err - -################################################################################ -def main(file_, o): - """Main program""" - - sp = StatePoint(file_) - sp.read_results() - - validate_options(sp, o) - - if o.list: - print_available(sp) - return - - if o.vtk: - if not o.output[-4:] == ".vtm": o.output += ".vtm" - else: - if not o.output[-5:] == ".silo": o.output += ".silo" - - if o.vtk: - try: - import vtk - except: - print('The vtk python bindings do not appear to be installed properly.\n' - 'On Ubuntu: sudo apt-get install python-vtk\n' - 'See: http://www.vtk.org/') - return - else: - try: - import silomesh - except: - print('The silomesh package does not appear to be installed properly.\n' - 'See: https://github.com/nhorelik/silomesh/') - return - - if o.vtk: - blocks = vtk.vtkMultiBlockDataSet() - blocks.SetNumberOfBlocks(5) - block_idx = 0 - else: - silomesh.init_silo(o.output) - - # Tally loop ################################################################# - for tally in sp.tallies: - - # skip non-mesh tallies or non-user-specified tallies - if o.tallies and not tally.id in o.tallies: continue - if not 'mesh' in tally.filters: continue - - print("Processing Tally {}...".format(tally.id)) - - # extract filter options and mesh parameters for this tally - filtercombos = get_filter_combos(tally) - meshparms = get_mesh_parms(sp, tally) - nx,ny,nz = meshparms[:3] - ll = meshparms[3:6] - ur = meshparms[6:9] - - if o.vtk: - ww = [(u-l)/n for u,l,n in zip(ur,ll,(nx,ny,nz))] - grid = grid = vtk.vtkImageData() - grid.SetDimensions(nx+1,ny+1,nz+1) - grid.SetOrigin(*ll) - grid.SetSpacing(*ww) - else: - silomesh.init_mesh('Tally_{}'.format(tally.id), *meshparms) - - # Score loop ############################################################### - for sid,score in enumerate(tally.scores): - - # skip non-user-specified scrores for this tally - if o.scores and tally.id in o.scores and not sid in o.scores[tally.id]: - continue - - # Filter loop ############################################################ - for filterspec in filtercombos: - - # skip non-user-specified filter bins - skip = False - if o.filters and tally.id in o.filters: - for filter_,bin in filterspec[1:]: - if filter_ in o.filters[tally.id] and \ - not bin in o.filters[tally.id][filter_]: - skip = True - break - if skip: continue - - # find and sanitize the variable name for this score - varname = get_sanitized_filterspec_name(tally, score, filterspec) - if o.vtk: - vtkdata = vtk.vtkDoubleArray() - vtkdata.SetName(varname) - dataforvtk = {} - else: - silomesh.init_var(varname) - - lbl = "\t Score {}.{} {}:\t\t{}".format(tally.id, sid+1, score, varname) - - # Mesh fill loop ####################################################### - for x in range(1,nx+1): - sys.stdout.write(lbl+" {0}%\r".format(int(x/nx*100))) - sys.stdout.flush() - for y in range(1,ny+1): - for z in range(1,nz+1): - filterspec[0][1] = (x,y,z) - val = sp.get_values(tally.id-1, filterspec, sid)[o.valerr] - if o.vtk: - # vtk cells go z, y, x, so we store it now and enter it later - i = (z-1)*nx*ny + (y-1)*nx + x-1 - dataforvtk[i] = float(val) - else: - silomesh.set_value(float(val), x, y, z) - - # end mesh fill loop - print() - if o.vtk: - for i in range(nx*ny*nz): - vtkdata.InsertNextValue(dataforvtk[i]) - grid.GetCellData().AddArray(vtkdata) - del vtkdata - - else: - silomesh.finalize_var() - - # end filter loop - - # end score loop - if o.vtk: - blocks.SetBlock(block_idx, grid) - block_idx += 1 - else: - silomesh.finalize_mesh() - - # end tally loop - if o.vtk: - writer = vtk.vtkXMLMultiBlockDataWriter() - writer.SetFileName(o.output) - writer.SetInput(blocks) - writer.Write() - else: - silomesh.finalize_silo() - -################################################################################ -def get_sanitized_filterspec_name(tally, score, filterspec): - """Returns a name fit for silo vars for a given filterspec, tally and score""" - - comboname = "_"+" ".join(["{}_{}".format(filter_, bin) - for filter_, bin in filterspec[1:]]) - if len(filterspec[1:]) == 0: comboname = '' - varname = 'Tally_{}_{}{}'.format(tally.id, score, comboname) - varname = alphanum.sub('_', varname) - return varname - -################################################################################ -def get_filter_combos(tally): - """Returns a list of all filter spec combinations, excluding meshes - - Each combo has the mesh spec as the first element, to be set later. - These filter specs correspond with the second argument to StatePoint.get_value - """ - - specs = [] - - if len(tally.filters) == 1: - return [[['mesh', [1, 1, 1]]]] - - filters = list(tally.filters.keys()) - filters.pop(filters.index('mesh')) - nbins = [tally.filters[f].length for f in filters] - - combos = [ [b] for b in range(nbins[0])] - for i,b in enumerate(nbins[1:]): - prod = list(itertools.product(combos, range(b))) - if i == 0: - combos = prod - else: - combos = [[v for v in p[0]] + [p[1]] for p in prod] - - for c in combos: - spec = [['mesh', [1, 1, 1]]] - for i,bin in enumerate(c): - spec.append((filters[i], bin)) - specs.append(spec) - - return specs - -################################################################################ -def get_mesh_parms(sp, tally): - meshid = tally.filters['mesh'].bins[0] - for i,m in enumerate(sp.meshes): - if m.id == meshid: - mesh = m - return mesh.dimension + mesh.lower_left + mesh.upper_right - -################################################################################ -def print_available(sp): - """Prints available tallies/scores in a statepoint""" - - print("Available tally and score indices:") - for tally in sp.tallies: - mesh = "" - if not 'mesh' in tally.filters: mesh = "(no mesh)" - print("\tTally {} {}".format(tally.id, mesh)) - scores = ["{}.{}: {}".format(tally.id, sid, score) - for sid, score in enumerate(tally.scores)] - for score in scores: - print("\t\tScore {}".format(score)) - for filter_ in tally.filters: - if filter_ == 'mesh': continue - for bin in range(tally.filters[filter_].length): - print("\t\t\tFilters: {}.{}.{}".format(tally.id, filter_, bin)) - -################################################################################ -def validate_options(sp,o): - """Validates specified tally/score options for the current statepoint""" - - available_tallies = [t.id for t in sp.tallies] - if o.tallies: - for otally in o.tallies: - if not otally in available_tallies: - warnings.warn('Tally {} not in statepoint file'.format(otally)) - continue - else: - for tally in sp.tallies: - if tally.id == otally: break - if not 'mesh' in tally.filters: - warnings.warn('Tally {} contains no mesh'.format(otally)) - if o.scores and otally in o.scores.keys(): - for oscore in o.scores[otally]: - if oscore > len(tally.scores): - warnings.warn('No score {} in tally {}'.format(oscore, otally)) - - if o.scores: - for otally in o.scores.keys(): - if not otally in available_tallies: - warnings.warn('Tally {} not in statepoint file'.format(otally)) - continue - if o.tallies and not otally in o.tallies: - warnings.warn( - 'Skipping scores for tally {}, excluded by tally list'.format(otally)) - continue - - if o.filters: - for otally in o.filters.keys(): - if not otally in available_tallies: - warnings.warn('Tally {} not in statepoint file'.format(otally)) - continue - if o.tallies and not otally in o.tallies: - warnings.warn( - 'Skipping filters for tally {}, excluded by tally list'.format(otally)) - continue - for tally in sp.tallies: - if tally.id == otally: break - for filter_ in o.filters[otally]: - if filter_ == 'mesh': - warnings.warn('Cannot specify mesh filter bins') - continue - if not filter_ in tally.filters.keys(): - warnings.warn( - 'Tally {} does not contain filter {}'.format(otally, filter_)) - continue - for bin in o.filters[otally][filter_]: - if bin >= tally.filters[filter_].length: - warnings.warn( - 'No bin {} in tally {} filter {}'.format(bin, otally, filter_)) - -################################################################################ -# monkeypatch to suppress the source echo produced by warnings -def formatwarning(message, category, filename, lineno, line): - return "{}:{}: {}: {}\n".format(filename, lineno, category.__name__, message) -warnings.formatwarning = formatwarning - -################################################################################ -if __name__ == '__main__': - (options, args), err = parse_options() - if args and not err: - main(args[0],options)