# 4. 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 five valid elements in the tallies.xml file are `<tally>`

, `<filter>`

,
`<mesh>`

, `<derivative>`

, and `<assume_separate>`

.

## 4.1. `<tally>`

Element¶

The `<tally>`

element accepts the following sub-elements:

- name
An optional string name to identify the tally in summary output files.

Default: “”- filters
A space-separated list of the IDs of

`filter`

elements.- nuclides
If specified, the scores listed will be for particular nuclides, not the summation of reactions from all nuclides. Nuclides are expressed using the GNDS naming convention, e.g. “U235” or “Am242_m1”. The reaction rate for all nuclides can be obtained with “total”. For example, to obtain the reaction rates for U235, Pu239, and all nuclides in a material, this element should be:

<nuclides>U235 Pu239 total</nuclides>

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. A full list of valid scores can be found in the user’s guide.

- 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 \(\sigma^2\)

- std_dev
Standard deviation of the batch mean \(\sigma\)

- rel_err
Relative error of the batch mean \(\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

## 4.2. `<filter>`

Element¶

Filters can be used to modify 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. The `filter`

element has the following
attributes/sub-elements:

- type
The type of the filter. Accepted options are “cell”, “cellfrom”, “cellborn”, “surface”, “material”, “universe”, “energy”, “energyout”, “mu”, “polar”, “azimuthal”, “mesh”, “distribcell”, “delayedgroup”, “energyfunction”, and “particle”.

- bins
A description of the bins for each type of filter can be found in 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)

### 4.2.1. 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.

- surface
This filter allows the tally to be scored when crossing a surface. A list of surface IDs should be given. By default, net currents are tallied, and to tally a partial current from one cell to another, this should be used in combination with a cell or cell_from filter that defines the other cell. This filter should not be used in combination with a meshfilter.

- cellfrom
This filter allows the tally to be scored when crossing a surface and the particle came from a specified cell. A list of cell IDs should be given. To tally a partial current from a cell to another, this filter should be used in combination with a cell filter, to define the other cell. This filter should not be used in combination with a meshfilter.

- 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 materials 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<filter type="energy" bins="0.0 1.0e6 20.0e6" />

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<filter type="energyout" bins="0.0 1.0e6 20.0e6" />

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., \(\mu = \hat{\Omega} \cdot \hat{\Omega}'\)), which represents a portion of the possible values of \([-1,1]\). For example, spanning all of \([-1,1]\) with five equi-width bins can be specified as:<filter type="mu" bins="-1.0 -0.6 -0.2 0.2 0.6 1.0" />

Alternatively, if only one value is provided as a bin, OpenMC will interpret this to mean the complete range of \([-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 \([-1,1]\) can be instead written as:

<filter type="mu" bins="5" />

- polar
A monotonically increasing list of bounding particle polar angles which represents a portion of the possible values of \([0,\pi]\). For example, spanning all of \([0,\pi]\) with five equi-width bins can be specified as:

<filter type="polar" bins="0.0 0.6283 1.2566 1.8850 2.5132 3.1416"/>

Alternatively, if only one value is provided as a bin, OpenMC will interpret this to mean the complete range of \([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 \([0,\pi]\) can be instead written as:

<filter type="polar" bins="5" />

- azimuthal
A monotonically increasing list of bounding particle azimuthal angles which represents a portion of the possible values of \([-\pi,\pi)\). For example, spanning all of \([-\pi,\pi)\) with two equi-width bins can be specified as:

<filter type="azimuthal" bins="0.0 3.1416 6.2832" />

Alternatively, if only one value is provided as a bin, OpenMC will interpret this to mean the complete range of \([-\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 \([-\pi,\pi)\) can be instead written as:

<filter type="azimuthal" bins="2" />

- mesh
The unique ID of a 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:

<filter type="delayedgroup" bins="1 2 3 4 5 6" />

- energyfunction
`energyfunction`

filters do not use the`bins`

entry. Instead they use`energy`

and`y`

.- particle
A list of integers indicating the type of particles to tally (‘neutron’ = 1, ‘photon’ = 2, ‘electron’ = 3, ‘positron’ = 4).

## 4.3. `<mesh>`

Element¶

If a mesh is desired as a filter for a tally, it must be specified in a separate
element with the tag name `<mesh>`

. This element has the following
attributes/sub-elements:

- type
The type of mesh. This can be either “regular”, “rectilinear”, “cylindrical”, “spherical”, or “unstructured”.

- dimension
The number of mesh cells in each direction. (For regular mesh only.)

- length_multiplier
A multiplicative factor to apply to the mesh coordinates in all directions. (For unstructured mesh only.)

- 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. (For regular mesh only.)

- 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. (For regular mesh only.)

- width
The width of mesh cells in each direction. (For regular mesh only.)

- x_grid
The mesh divisions along the x-axis. (For rectilinear mesh only.)

- y_grid
The mesh divisions along the y-axis. (For rectilinear mesh only.)

- z_grid
The mesh divisions along the z-axis. (For rectilinear and cylindrical meshes only.)

- r_grid
The mesh divisions along the r-axis. (For cylindrical and spherical meshes only.)

- phi_grid
The mesh divisions along the phi-axis. (For cylindrical and spherical meshes only.)

- theta_grid
The mesh divisions along the theta-axis. (For spherical mesh only.)

- library
The mesh library used to represent an unstructured mesh. This can be either “moab” or “libmesh”. (For unstructured mesh only.)

- filename
The name of the mesh file to be loaded at runtime. (For unstructured mesh only.)

Note

One of

`<upper_right>`

or`<width>`

must be specified, but not both (even if they are consistent with one another).

## 4.4. `<derivative>`

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”)

## 4.5. `<assume_separate>`

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