7. Execution Settings¶
Once you have created the materials and geometry for your simulation, the last
step to have a complete model is to specify execution settings through the
openmc.Settings
class. At a minimum, you need to specify a source
distribution and how many particles to run. Many other execution settings can be set using the
openmc.Settings
object, but they are generally optional.
7.1. Run Modes¶
The Settings.run_mode
attribute controls what run mode is used when
openmc is executed. There are five different run modes that can
be specified:
- ‘eigenvalue’
- Runs a \(k\) eigenvalue simulation. See Eigenvalue Calculations for a
full description of eigenvalue calculations. In this mode, the
Settings.source
specifies a starting source that is only used for the first fission generation. - ‘fixed source’
- Runs a fixed-source calculation with a specified external source, specified in
the
Settings.source
attribute. - ‘volume’
- Runs a stochastic volume calculation.
- ‘plot’
- Generates slice or voxel plots (see Geometry Visualization).
- ‘particle restart’
- Simulate a single source particle using a particle restart file.
So, for example, to specify that OpenMC should be run in fixed source mode, you
would need to instantiate a openmc.Settings
object and assign the
Settings.run_mode
attribute:
settings = openmc.Settings()
settings.run_mode = 'fixed source'
If you don’t specify a run mode, the default run mode is ‘eigenvalue’.
7.2. Number of Particles¶
For a fixed source simulation, the total number of source particle histories
simulated is broken up into a number of batches, each corresponding to a
realization of the tally random variables. Thus, you
need to specify both the number of batches (Settings.batches
) as well as
the number of particles per batch (Settings.particles
).
For a \(k\) eigenvalue simulation, particles are grouped into fission
generations, as described in Eigenvalue Calculations. Successive fission
generations can be combined into a batch for statistical purposes. By default, a
batch will consist of only a single fission generation, but this can be changed
with the Settings.generations_per_batch
attribute. For problems with a
high dominance ratio, using multiple generations per batch can help reduce
underprediction of variance, thereby leading to more accurate confidence
intervals. Tallies should not be scored to until the source distribution
converges, as described in Method of Successive Generations, which may take
many generations. To specify the number of batches that should be discarded
before tallies begin to accumulate, use the Settings.inactive
attribute.
The following example shows how one would simulate 10000 particles per generation, using 10 generations per batch, 150 total batches, and discarding 5 batches. Thus, a total of 145 active batches (or 1450 generations) will be used for accumulating tallies.
settings.particles = 10000
settings.generations_per_batch = 10
settings.batches = 150
settings.inactive = 5
7.3. External Source Distributions¶
External source distributions can be specified through the
Settings.source
attribute. If you have a single external source, you can
create an instance of openmc.Source
and use it to set the
Settings.source
attribute. If you have multiple external sources with
varying source strengths, Settings.source
should be set to a list of
openmc.Source
objects.
The openmc.Source
class has three main attributes that one can set:
Source.space
, which defines the spatial distribution,
Source.angle
, which defines the angular distribution, and
Source.energy
, which defines the energy distribution.
The spatial distribution can be set equal to a sub-class of
openmc.stats.Spatial
; common choices are openmc.stats.Point
or
openmc.stats.Box
. To independently specify distributions in the
\(x\), \(y\), and \(z\) coordinates, you can use
openmc.stats.CartesianIndependent
.
The angular distribution can be set equal to a sub-class of
openmc.stats.UnitSphere
such as openmc.stats.Isotropic
,
openmc.stats.Monodirectional
, or
openmc.stats.PolarAzimuthal
. By default, if no angular distribution is
specified, an isotropic angular distribution is used.
The energy distribution can be set equal to any univariate probability
distribution. This could be a probability mass function
(openmc.stats.Discrete
), a Watt fission spectrum
(openmc.stats.Watt
), or a tabular distribution
(openmc.stats.Tabular
). By default, if no energy distribution is
specified, a Watt fission spectrum with \(a\) = 0.988 MeV and \(b\) =
2.249 MeV -1 is used.
As an example, to create an isotropic, 10 MeV monoenergetic source uniformly distributed over a cube centered at the origin with an edge length of 10 cm, one would run:
source = openmc.Source()
source.space = openmc.stats.Box((-5, -5, -5), (5, 5, 5))
source.angle = openmc.stats.Isotropic()
source.energy = openmc.stats.Discrete([10.0e6], [1.0])
settings.source = source
The openmc.Source
class also has a Source.strength
attribute
that indicates the relative strength of a source distribution if multiple are
used. For example, to create two sources, one that should be sampled 70% of the
time and another that should be sampled 30% of the time:
src1 = openmc.Source()
src1.strength = 0.7
...
src2 = openmc.Source()
src2.strength = 0.3
...
settings.source = [src1, src2]
For a full list of all classes related to statistical distributions, see openmc.stats – Statistics.
7.4. Shannon Entropy¶
To assess convergence of the source distribution, the scalar Shannon entropy
metric is often used in Monte Carlo codes. OpenMC also allows you to calculate
Shannon entropy at each generation over a specified mesh, created using the
openmc.Mesh
class. After instantiating a Mesh
, you need to
specify the lower-left coordinates of the mesh (Mesh.lower_left
), the
number of mesh cells in each direction (Mesh.dimension
) and either the
upper-right coordinates of the mesh (Mesh.upper_right
) or the width of
each mesh cell (Mesh.width
). Once you have a mesh, simply assign it to
the Settings.entropy_mesh
attribute.
entropy_mesh = openmc.Mesh()
entropy_mesh.lower_left = (-50, -50, -25)
entropy_mesh.upper_right = (50, 50, 25)
entropy_mesh.dimension = (8, 8, 8)
settings.entropy_mesh = entropy_mesh
If you’re unsure of what bounds to use for the entropy mesh, you can try getting
a bounding box for the entire geometry using the Geometry.bounding_box
property:
geom = openmc.Geometry()
...
m = openmc.Mesh()
m.lower_left, m.upper_right = geom.bounding_box
m.dimension = (8, 8, 8)
settings.entropy_mesh = m
7.5. Generation of Output Files¶
A number of attributes of the openmc.Settings
class can be used to
control what files are output and how often. First, there is the
Settings.output
attribute which takes a dictionary having keys
‘summary’, ‘tallies’, and ‘path’. The first two keys controls whether a
summary.h5
and tallies.out
file are written, respectively (see
Viewing and Analyzing Results for a description of those files). By default, output files
are written to the current working directory; this can be changed by setting the
‘path’ key. For example, if you want to disable the tallies.out
file and
write the summary.h5
to a directory called ‘results’, you’d specify the
Settings.output
dictionary as:
settings.output = {
'tallies': False,
'path': 'results'
}
Generation of statepoint and source files is handled separately through the
Settings.statepoint
and Settings.sourcepoint
attributes. Both of
those attributes expect dictionaries and have a ‘batches’ key which indicates at
which batches statepoints and source files should be written. Note that by
default, the source is written as part of the statepoint file; this behavior can
be changed by the ‘separate’ and ‘write’ keys of the
Settings.sourcepoint
dictionary, the first of which indicates whether
the source should be written to a separate file and the second of which
indicates whether the source should be written at all.
As an example, to write a statepoint file every five batches:
settings.batches = n
settings.statepoint = {'batches': range(5, n + 5, 5)}