crp/OpenMC
1
0
Fork 0
mirror of https://github.com/openmc-dev/openmc.git synced 2026-07-26 21:25:36 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

adding back files to be reviewed

Browse source
This commit is contained in:
Paul Romano 2019-10-28 11:55:45 -05:00
parent ae28233110
commit bc09d1ef55
1244 changed files with 301904 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

190
docs/source/usersguide/basics.rst Normal file
View file

@ -0,0 +1,190 @@
.. _usersguide_basics:
======================
Basics of Using OpenMC
======================
----------------
Creating a Model
----------------
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 :ref:`usersguide_geometry`.
: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.
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
<http://www.w3.org/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
<person>
<firstname>John</firstname>
<lastname>Smith</lastname>
<age>27</age>
<occupation>Health Physicist</occupation>
</person>
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 or using :ref:`Emacs nXML mode
<usersguide_nxml>`.
Creating Input Files
--------------------
.. currentmodule:: openmc
The most rudimentary option for creating input files is to simply write them
from scratch using the :ref:`XML format specifications
<io_file_formats_input>`. 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:`Python API <pythonapi>`, which is introduced in the
following section.
----------
Python API
----------
OpenMC's :ref:`Python API <pythonapi>` 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
geometry = openmc.Geometry()
...
geometry.export_to_xml()
# Assign simulation settings
settings = openmc.Settings()
...
settings.export_to_xml()
Once 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.
Identifying Objects
-------------------
In the XML user input files, each object (cell, surface, tally, etc.) has to be
uniquely identified by a positive integer (ID) in the same manner as MCNP and
Serpent. In the Python API, integer IDs can be assigned but it is not strictly
required. When IDs are not explicitly assigned to instances of the OpenMC Python
classes, they will be automatically assigned.
.. _result_files:
-----------------------------
Viewing and Analyzing Results
-----------------------------
After a simulation has been completed by running :ref:`scripts_openmc`, you will
have several output files that were created:
``tallies.out``
An ASCII file showing the mean and standard deviation of the mean for any
user-defined tallies.
``summary.h5``
An HDF5 file with a complete description of the geometry and materials used in
the simulation.
``statepoint.#.h5``
An HDF5 file with the complete results of the simulation, including tallies as
well as the final source distribution. This file can be used both to
view/analyze results as well as restart a simulation if desired.
For a simple simulation with few tallies, looking at the ``tallies.out`` file
might be sufficient. For anything more complicated (plotting results, finding a
subset of results, etc.), you will likely find it easier to work with the
statepoint file directly using the :class:`openmc.StatePoint` class. For more
details on working with statepoints, see :ref:`usersguide_statepoint`.
--------------
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

161
docs/source/usersguide/beginners.rst Normal file
View file

@ -0,0 +1,161 @@
.. _usersguide_beginners:
============================
A Beginner's Guide to OpenMC
============================
--------------------
What does OpenMC do?
--------------------
In a nutshell, OpenMC simulates neutral particles (presently neutrons and
photons) 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 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
deterministic methods:
- **Pro**: Depending on what method is used, solution can be determined very
quickly.
- **Pro**: The solution is a global solution, i.e. we know the average behavior
everywhere.
- **Pro**: Once the problem is converged, the solution is known.
- **Con**: If the model is complex, it is necessary to do sophisticated mesh
generation.
- **Con**: It is necessary to generate multi-group cross sections which requires
knowing the solution *a priori*.
Now let's look at the pros and cons of Monte Carlo methods:
- **Pro**: No mesh generation is required to build geometry. By using
`constructive solid geometry`_, it's possible to build arbitrarily complex
models with curved surfaces.
- **Pro**: Monte Carlo methods can be used with either continuous-energy or
multi-group cross sections.
- **Pro**: Running simulations in parallel is conceptually very simple.
- **Con**: Because they rely on repeated random sampling, they are
computationally very expensive.
- **Con**: A simulation doesn't automatically give you the global solution
everywhere -- you have to specifically ask for those quantities you want.
- **Con**: Even after the problem is converged, it is necessary to simulate
many particles to reduce stochastic uncertainty.
Because fewer approximations are made in solving a problem by the Monte Carlo
method, it is often seen as a "gold standard" which can be used as a benchmark
for a solution of the same problem by deterministic means. However, it comes at
the expense of a potentially longer simulation.
-----------------
How does it work?
-----------------
In order to do anything, the code first needs to have a model of some problem of
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 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. 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, 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
<http://www.ee.surrey.ac.uk/Teaching/Unix/>`_ will help you get acquainted with
commonly-used commands.
To reap the full benefits of OpenMC, you should also have basic proficiency in
the use of `Python <http://www.python.org/>`_, 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
necessarily have to have git installed in order to download and run OpenMC, it
makes it much easier to receive updates if you do have it installed and have a
basic understanding of how it works. There are a list of good `git tutorials`_
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 <https://help.github.com/articles/set-up-git/>`_ 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
Concepts Manual`_. This manual describes the basics of nuclear power for
electricity generation, the fission process, and the overall systems in a
pressurized or boiling water reactor. Another resource that is a bit more
technical than the Reactor Concepts Manual but still at an elementary level is
the DOE Fundamentals Handbook on Nuclear Physics and Reactor Theory `Volume I`_
and `Volume II`_. You may also find it helpful to review the following terms:
- `Neutron cross section`_
- `Effective multiplication factor`_
- `Flux`_
.. _nuclear reactor: https://en.wikipedia.org/wiki/Nuclear_reactor
.. _Monte Carlo: https://en.wikipedia.org/wiki/Monte_Carlo_method
.. _fission: https://en.wikipedia.org/wiki/Nuclear_fission
.. _deterministic: https://en.wikipedia.org/wiki/Deterministic_algorithm
.. _neutron transport: https://en.wikipedia.org/wiki/Neutron_transport
.. _discretization: https://en.wikipedia.org/wiki/Discretization
.. _constructive solid geometry: https://en.wikipedia.org/wiki/Constructive_solid_geometry
.. _git: http://git-scm.com/
.. _git tutorials: http://git-scm.com/documentation
.. _Reactor Concepts Manual: http://www.tayloredge.com/periodic/trivia/ReactorConcepts.pdf
.. _Volume I: https://www.standards.doe.gov/standards-documents/1000/1019-bhdbk-1993-v1
.. _Volume II: https://www.standards.doe.gov/standards-documents/1000/1019-bhdbk-1993-v2
.. _OpenMC source code: https://github.com/openmc-dev/openmc
.. _GitHub: https://github.com/
.. _bug reports: https://github.com/openmc-dev/openmc/issues
.. _Neutron cross section: https://en.wikipedia.org/wiki/Neutron_cross_section
.. _Effective multiplication factor: https://en.wikipedia.org/wiki/Nuclear_chain_reaction#Effective_neutron_multiplication_factor
.. _Flux: https://en.wikipedia.org/wiki/Neutron_flux

267
docs/source/usersguide/cross_sections.rst Normal file
View file

@ -0,0 +1,267 @@
.. _usersguide_cross_sections:
===========================
Cross Section Configuration
===========================
In order to run a simulation with OpenMC, you will need cross section data for
each nuclide or material in your problem. OpenMC can be run in continuous-energy
or multi-group mode.
In continuous-energy mode, OpenMC uses a native `HDF5
<https://support.hdfgroup.org/HDF5/>`_ format (see :ref:`io_nuclear_data`) to
store all nuclear data. Pregenerated HDF5 libraries can be found at
https://openmc.org; unless you have specific data needs, it is highly
recommended to use one of the pregenerated libraries. Alternatively, if you have
ACE format data that was produced with NJOY_, such as that distributed with
MCNP_ or Serpent_, it can be converted to the HDF5 format using the :ref:`using
the Python API <create_xs_library>`. Several sources provide openly available
ACE data including the `ENDF/B`_, JEFF_, and TENDL_ libraries as well as the
`LANL Nuclear Data Team <https://nucleardata.lanl.gov/>`_. In addition to
tabulated cross sections in the HDF5 files, OpenMC relies on :ref:`windowed
multipole <windowed_multipole>` data to perform on-the-fly Doppler broadening.
In multi-group mode, OpenMC utilizes an HDF5-based library format which can be
used to describe nuclide- or material-specific quantities.
---------------------
Environment Variables
---------------------
When :ref:`scripts_openmc` is run, it will look for several environment
variables that indicate where cross sections can be found. While the location of
cross sections can also be indicated through the
:attr:`openmc.Materials.cross_setion` attribute (or in the :ref:`materials.xml
<io_materials>` file), if you always use the same set of cross section data, it
is often easier to just set an environment variable that will be picked up by
default every time OpenMC is run. The following environment variables are used:
:envvar:`OPENMC_CROSS_SECTIONS`
Indicates the path to the :ref:`cross_sections.xml <io_cross_sections>`
summary file that is used to locate HDF5 format cross section libraries if the
user has not specified :attr:`Materials.cross_sections` (equivalently, the
:ref:`cross_sections` in :ref:`materials.xml <io_materials>`).
:envvar:`OPENMC_MG_CROSS_SECTIONS`
Indicates the path to the an :ref:`HDF5 file <io_mgxs_library>` that contains
multi-group cross sections if the user has not specified
:attr:`Materials.cross_sections` (equivalently, the :ref:`cross_sections` in
:ref:`materials.xml <io_materials>`).
To set these environment variables persistently, export them from your shell
profile (``.profile`` or ``.bashrc`` in bash_).
.. _bash: http://www.linuxfromscratch.org/blfs/view/6.3/postlfs/profile.html
--------------------------------
Continuous-Energy Cross Sections
--------------------------------
Using Pregenerated Libraries
----------------------------
Various evaluated nuclear data libraries have been processed into the HDF5
format required by OpenMC and can be found at https://openmc.org. You
can find both libraries generated by the OpenMC development team as well as
libraries based on ACE files distributed elsewhere. To use these libraries,
download the archive file, unpack it, and then set your
:envvar:`OPENMC_CROSS_SECTIONS` environment variable to the absolute path of
the ``cross_sections.xml`` file contained in the unpacked directory.
.. _create_xs_library:
Manually Creating a Library from ACE files
------------------------------------------
.. currentmodule:: openmc.data
The scripts described above use the :mod:`openmc.data` module in the Python API
to convert ACE data and create a :ref:`cross_sections.xml <io_cross_sections>`
file. For those who prefer to use the API directly, the
:class:`openmc.data.IncidentNeutron` and :class:`openmc.data.ThermalScattering`
classes can be used to read ACE data and convert it to HDF5. For
continuous-energy incident neutron data, use the
:meth:`IncidentNeutron.from_ace` class method to read in an existing ACE file
and the :meth:`IncidentNeutron.export_to_hdf5` method to write the data to an
HDF5 file.
::
u235 = openmc.data.IncidentNeutron.from_ace('92235.710nc')
u235.export_to_hdf5('U235.h5')
If you have multiple ACE files for the same nuclide at different temperatures,
you can use the :meth:`IncidentNeutron.add_temperature_from_ace` method to
append cross sections to an existing :class:`IncidentNeutron` instance::
u235 = openmc.data.IncidentNeutron.from_ace('92235.710nc')
for suffix in [711, 712, 713, 714, 715, 716]:
u235.add_temperature_from_ace('92235.{}nc'.format(suffix))
u235.export_to_hdf5('U235.h5')
Similar methods exist for thermal scattering data:
::
light_water = openmc.data.ThermalScattering.from_ace('lwtr.20t')
for suffix in range(21, 28):
light_water.add_temperature_from_ace('lwtr.{}t'.format(suffix))
light_water.export_to_hdf5('lwtr.h5')
Once you have created corresponding HDF5 files for each of your ACE files, you
can create a library and export it to XML using the
:class:`openmc.data.DataLibrary` class::
library = openmc.data.DataLibrary()
library.register_file('U235.h5')
library.register_file('lwtr.h5')
...
library.export_to_xml()
At this point, you will have a ``cross_sections.xml`` file that you can use in
OpenMC.
.. hint:: The :class:`IncidentNeutron` class allows you to view/modify cross
sections, secondary angle/energy distributions, probability tables,
etc. For a more thorough overview of the capabilities of this class,
see the :ref:`notebook_nuclear_data` example notebook.
Manually Creating a Library from ENDF files
-------------------------------------------
If you need to create a nuclear data library and you do not already have
suitable ACE files or you need to further customize the data (for example,
adding more temperatures), the :meth:`IncidentNeutron.from_njoy` and
:meth:`ThermalScattering.from_njoy` methods can be used to create data instances
by directly running NJOY_. Both methods require that you pass the name of ENDF
file(s) that are passed on to NJOY. For example, to generate data for Zr-92::
zr92 = openmc.data.IncidentNeutron.from_njoy('n-040_Zr_092.endf')
By default, data is produced at room temperature, 293.6 K. You can also specify
a list of temperatures that you want data at::
zr92 = openmc.data.IncidentNeutron.from_njoy(
'n-040_Zr_092.endf', temperatures=[300., 600., 1000.])
The :meth:`IncidentNeutron.from_njoy` method assumes you have an executable
named ``njoy`` available on your path. If you want to explicitly name the
executable, the ``njoy_exec`` optional argument can be used. Additionally, the
``stdout`` argument can be used to show the progress of the NJOY run.
To generate a thermal scattering file, you need to specify both an ENDF incident
neutron sub-library file as well as a thermal neutron scattering sub-library
file; for example::
light_water = openmc.data.ThermalScattering.from_njoy(
'neutrons/n-001_H_001.endf', 'thermal_scatt/tsl-HinH2O.endf')
Once you have instances of :class:`IncidentNeutron` and
:class:`ThermalScattering`, a library can be created by using the
``export_to_hdf5()`` methods and the :class:`DataLibrary` class as described in
:ref:`create_xs_library`.
Enabling Resonance Scattering Treatments
----------------------------------------
In order for OpenMC to correctly treat elastic scattering in heavy nuclides
where low-lying resonances might be present (see
:ref:`energy_dependent_xs_model`), the elastic scattering cross section at 0 K
must be present. If the data you are using was generated via
:meth:`IncidentNeutron.from_njoy`, you will already have 0 K elastic scattering
cross sections available. Otherwise, to add 0 K elastic scattering cross
sections to an existing :class:`IncidentNeutron` instance, you can use the
:meth:`IncidentNeutron.add_elastic_0K_from_endf` method which requires an ENDF
file for the nuclide you are modifying::
u238 = openmc.data.IncidentNeutron.from_hdf5('U238.h5')
u238.add_elastic_0K_from_endf('n-092_U_238.endf')
u238.export_to_hdf5('U238_with_0K.h5')
With 0 K elastic scattering data present, you can turn on a resonance scattering
method using :attr:`Settings.resonance_scattering`.
.. note:: The process of reconstructing resonances and generating tabulated 0 K
cross sections can be computationally expensive, especially for
nuclides like U-238 where thousands of resonances are present. Thus,
running the :meth:`IncidentNeutron.add_elastic_0K_from_endf` method
may take several minutes to complete.
Photon Cross Sections
---------------------
Photon interaction data is needed to run OpenMC with photon transport enabled.
Some of this data, namely bremsstrahlung cross sections from `Seltzer and
Berger`_, mean excitation energy from the `NIST ESTAR database`_, and Compton
profiles calculated by `Biggs et al.`_ and available in the Geant4 G4EMLOW data
file, is distributed with OpenMC. The rest is available from the NNDC_, which
provides ENDF data from the photo-atomic and atomic relaxation sublibraries of
the ENDF/B-VII.1 library.
Most of the pregenerated HDF5 libraries available at https://openmc.org
already have photon interaction data included. If you are building a data
library yourself, it is possible to use the Python API directly to convert
photon interaction data from an ENDF or ACE file to an HDF5 file. The
:class:`openmc.data.IncidentPhoton` class contains an
:meth:`IncidentPhoton.from_ace` method that will generate photon data from an
ACE table and an :meth:`IncidentPhoton.export_to_hdf5` method that writes the
data to an HDF5 file:
::
u = openmc.data.IncidentPhoton.from_ace('92000.12p')
u.export_to_hdf5('U.h5')
Similarly, the :meth:`IncidentPhoton.from_endf` method can be used to read
photon data from an ENDF file. In this case, both the photo-atomic and atomic
relaxation sublibrary files are required:
::
u = openmc.data.IncidentPhoton.from_endf('photoat-092_U_000.endf',
'atom-092_U_000.endf')
Once the HDF5 files have been generated, a library can be created using the
:class:`DataLibrary` class as described in :ref:`create_xs_library`.
-----------------------
Windowed Multipole Data
-----------------------
OpenMC is capable of using windowed multipole data for on-the-fly Doppler
broadening. A comprehensive multipole data library containing all nuclides in
ENDF/B-VII.1 is available on `GitHub
<https://github.com/mit-crpg/WMP_Library>`_. To obtain this library, download
and unpack an archive (.zip or .tag.gz) from GitHub. Once unpacked, you can use
the :class:`openmc.data.DataLibrary` class to register the .h5 files as
described in :ref:`create_xs_library`.
The `official ENDF/B-VII.1 HDF5 library
<https://openmc.org/official-data-libraries/>`_ includes the windowed
multipole library, so if you are using this library, the windowed multipole data
will already be available to you.
--------------------------
Multi-Group Cross Sections
--------------------------
Multi-group cross section libraries are generally tailored to the specific
calculation to be performed. Therefore, at this point in time, OpenMC is not
distributed with any pre-existing multi-group cross section libraries.
However, if obtained or generated their own library, the user
should set the :envvar:`OPENMC_MG_CROSS_SECTIONS` environment variable
to the absolute path of the file library expected to used most frequently.
For an example of how to create a multi-group library, see
:ref:`notebook_mg_mode_part_i`.
.. _NJOY: http://www.njoy21.io/
.. _NNDC: https://www.nndc.bnl.gov/endf
.. _MCNP: https://mcnp.lanl.gov
.. _Serpent: http://montecarlo.vtt.fi
.. _ENDF/B: https://www.nndc.bnl.gov/endf/b7.1/acefiles.html
.. _JEFF: http://www.oecd-nea.org/dbdata/jeff/jeff33/
.. _TENDL: https://tendl.web.psi.ch/tendl_2017/tendl2017.html
.. _Seltzer and Berger: https://doi.org/10.1016/0092-640X(86)90014-8
.. _NIST ESTAR database: https://physics.nist.gov/PhysRefData/Star/Text/ESTAR.html
.. _Biggs et al.: https://doi.org/10.1016/0092-640X(75)90030-3

137
docs/source/usersguide/depletion.rst Normal file
View file

@ -0,0 +1,137 @@
.. _usersguide_depletion:
=========
Depletion
=========
OpenMC supports coupled depletion, or burnup, calculations through the
:mod:`openmc.deplete` Python module. OpenMC solves the transport equation to
obtain transmutation reaction rates, and then the reaction rates are used to
solve a set of transmutation equations that determine the evolution of nuclide
densities within a material. The nuclide densities predicted as some future time
are then used to determine updated reaction rates, and the process is repeated
for as many timesteps as are requested.
The depletion module is designed such that the flux/reaction rate solution (the
transport "operator") is completely isolated from the solution of the
transmutation equations and the method used for advancing time. At present, the
:mod:`openmc.deplete` module offers a single transport operator,
:class:`openmc.deplete.Operator` (which uses the OpenMC transport solver), but
in principle additional operator classes based on other transport codes could be
implemented and no changes to the depletion solver itself would be needed. The
operator class requires a :class:`openmc.Geometry` instance and a
:class:`openmc.Settings` instance::
geom = openmc.Geometry()
settings = openmc.Settings()
...
op = openmc.deplete.Operator(geom, settings)
:mod:`openmc.deplete` supports multiple time-integration methods for determining
material compositions over time. Each method appears as a different class.
For example, :class:`openmc.deplete.CECMIntegrator` runs a depletion calculation
using the CE/CM algorithm (deplete over a timestep using the middle-of-step
reaction rates). An instance of :class:`openmc.deplete.Operator` is passed to
one of these functions along with the power level and timesteps::
power = 1200.0e6
days = 24*60*60
timesteps = [10.0*days, 10.0*days, 10.0*days]
openmc.deplete.CECMIntegrator(op, power, timesteps).integrate()
The coupled transport-depletion problem is executed, and once it is done a
``depletion_results.h5`` file is written. The results can be analyzed using the
:class:`openmc.deplete.ResultsList` class. This class has methods that allow for
easy retrieval of k-effective, nuclide concentrations, and reaction rates over
time::
results = openmc.deplete.ResultsList.from_hdf5("depletion_results.h5")
time, keff = results.get_eigenvalue()
Note that the coupling between the transport solver and the transmutation solver
happens in-memory rather than by reading/writing files on disk.
Caveats
=======
Energy Deposition
-----------------
The default energy deposition mode, ``"fission-q"``, instructs the
:class:`openmc.deplete.Operator` to normalize reaction rates using the product
of fission reaction rates and fission Q values taken from the depletion chain.
This approach does not consider indirect contributions to energy deposition,
such as neutron heating and energy from secondary photons. In doing this,
the energy deposited during a transport calculation will be lower than expected.
This causes the reaction rates to be over-adjusted to hit the user-specific power,
or power density, leading to an over-depletion of burnable materials.
There are some remedies. First, the fission Q values can be directly set in a
variety of ways. This requires knowing what the total fission energy release should
be, including indirect components. Some examples are provided below::
# use a dictionary of fission_q values
fission_q = {"U235": 202} # energy in MeV
# create a modified chain and write it to a new file
chain = openmc.deplete.Chain.from_xml("chain.xml", fission_q)
chain.export_to_xml("chain_mod_q.xml")
op = openmc.deplete.Operator(geometry, setting, "chain_mod_q.xml")
# alternatively, pass the modified fission Q directly to the operator
op = openmc.deplete.Operator(geometry, setting, "chain.xml",
fission_q=fission_q)
A more complete way to model the energy deposition is to use the modified heating
reactions described in :ref:`methods_heating`. These values can be used to normalize
reaction rates instead of using the fission reaction rates with::
op = openmc.deplete.Operator(geometry, settings, "chain.xml",
energy_mode="energy-deposition")
These modified heating libraries can be generated by running the latest version
of :meth:`openmc.data.IncidentNeutron.from_njoy`, and will eventually be bundled into
the distributed libraries.
Local Spectra and Repeated Materials
------------------------------------
It is not uncommon to explicitly create a single burnable material across many locations.
From a pure transport perspective, there is nothing wrong with creating a single
3.5 wt.% enriched fuel ``fuel_3``, and placing that fuel in every fuel pin in an assembly
or even full core problem. This certainly expedites the model making process, but can pose
issues with depletion.
Under this setup, :mod:`openmc.deplete` will deplete a single ``fuel_3`` material using
a single set of reaction rates, and produce a single new composition for the next time
step. This can be problematic if the same ``fuel_3`` is used in very different regions
of the problem.
As an example, consider a full-scale power reactor core with vacuum boundary
conditions, and with fuel pins solely composed of the same ``fuel_3`` material.
The fuel pins towards the center of the problem will surely experience a more intense
neutron flux and greater reaction rates than those towards the edge of the domain.
This indicates that the fuel in the center should be at a more depleted state than
periphery pins, at least for the fist depletion step.
However, without any other instructions, OpenMC will deplete ``fuel_3`` as a single
material, and all of the fuel pins will have an identical composition at the next
transport step.
This can be countered by instructing the operator to treat repeated instances
of the same material as a unique material definition with::
op = openmc.deplete.Operator(geometry, settings, chain_file,
diff_burnable_mats=True)
For our example problem, this would deplete fuel on the outer region of the problem
with different reaction rates than those in the center. Materials will be depleted
corresponding to their local neutron spectra, and have unique compositions at each
transport step.
.. note::
This will increase the total memory usage and run time due to an increased
number of tallies and material definitions.

436
docs/source/usersguide/geometry.rst Normal file
View file

@ -0,0 +1,436 @@
.. _usersguide_geometry:
=================
Defining Geometry
=================
.. currentmodule:: openmc
--------------------
Surfaces and Regions
--------------------
The geometry of a model in OpenMC is defined using `constructive solid
geometry`_ (CSG), also sometimes referred to as combinatorial geometry. CSG
allows a user to create complex regions using Boolean operators (intersection,
union, and complement) on simpler regions. In order to define a region that we
can assign to a cell, we must first define surfaces which bound the region. A
surface is a locus of zeros of a function of Cartesian coordinates
:math:`x,y,z`, e.g.
- A plane perpendicular to the :math:`x` axis: :math:`x - x_0 = 0`
- A cylinder parallel to the :math:`z` axis: :math:`(x - x_0)^2 + (y -
y_0)^2 - R^2 = 0`
- A sphere: :math:`(x - x_0)^2 + (y - y_0)^2 + (z - z_0)^2 - R^2 = 0`
Defining a surface alone is not sufficient to specify a volume -- in order to
define an actual volume, one must reference the *half-space* of a surface. A
surface half-space is the region whose points satisfy a positive or negative
inequality of the surface equation. For example, for a sphere of radius one
centered at the origin, the surface equation is :math:`f(x,y,z) = x^2 + y^2 +
z^2 - 1 = 0`. Thus, we say that the negative half-space of the sphere, is
defined as the collection of points satisfying :math:`f(x,y,z) < 0`, which one
can reason is the inside of the sphere. Conversely, the positive half-space of
the sphere would correspond to all points outside of the sphere, satisfying
:math:`f(x,y,z) > 0`.
In the Python API, surfaces are created via subclasses of
:class:`openmc.Surface`. The available surface types and their corresponding
classes are listed in the following table.
.. table:: Surface types available in OpenMC.
+----------------------+------------------------------+---------------------------+
| Surface | Equation | Class |
+======================+==============================+===========================+
| Plane perpendicular | :math:`x - x_0 = 0` | :class:`openmc.XPlane` |
| to :math:`x`-axis | | |
+----------------------+------------------------------+---------------------------+
| Plane perpendicular | :math:`y - y_0 = 0` | :class:`openmc.YPlane` |
| to :math:`y`-axis | | |
+----------------------+------------------------------+---------------------------+
| Plane perpendicular | :math:`z - z_0 = 0` | :class:`openmc.ZPlane` |
| to :math:`z`-axis | | |
+----------------------+------------------------------+---------------------------+
| Arbitrary plane | :math:`Ax + By + Cz = D` | :class:`openmc.Plane` |
+----------------------+------------------------------+---------------------------+
| Infinite cylinder | :math:`(y-y_0)^2 + (z-z_0)^2 | :class:`openmc.XCylinder` |
| parallel to | - R^2 = 0` | |
| :math:`x`-axis | | |
+----------------------+------------------------------+---------------------------+
| Infinite cylinder | :math:`(x-x_0)^2 + (z-z_0)^2 | :class:`openmc.YCylinder` |
| parallel to | - R^2 = 0` | |
| :math:`y`-axis | | |
+----------------------+------------------------------+---------------------------+
| Infinite cylinder | :math:`(x-x_0)^2 + (y-y_0)^2 | :class:`openmc.ZCylinder` |
| parallel to | - R^2 = 0` | |
| :math:`z`-axis | | |
+----------------------+------------------------------+---------------------------+
| Sphere | :math:`(x-x_0)^2 + (y-y_0)^2 | :class:`openmc.Sphere` |
| | + (z-z_0)^2 - R^2 = 0` | |
+----------------------+------------------------------+---------------------------+
| Cone parallel to the | :math:`(y-y_0)^2 + (z-z_0)^2 | :class:`openmc.XCone` |
| :math:`x`-axis | - R^2(x-x_0)^2 = 0` | |
+----------------------+------------------------------+---------------------------+
| Cone parallel to the | :math:`(x-x_0)^2 + (z-z_0)^2 | :class:`openmc.YCone` |
| :math:`y`-axis | - R^2(y-y_0)^2 = 0` | |
+----------------------+------------------------------+---------------------------+
| Cone parallel to the | :math:`(x-x_0)^2 + (y-y_0)^2 | :class:`openmc.ZCone` |
| :math:`z`-axis | - R^2(z-z_0)^2 = 0` | |
+----------------------+------------------------------+---------------------------+
| General quadric | :math:`Ax^2 + By^2 + Cz^2 + | :class:`openmc.Quadric` |
| surface | Dxy + Eyz + Fxz + Gx + Hy + | |
| | Jz + K = 0` | |
+----------------------+------------------------------+---------------------------+
Each surface is characterized by several parameters. As one example, the
parameters for a sphere are the :math:`x,y,z` coordinates of the center of the
sphere and the radius of the sphere. All of these parameters can be set either
as optional keyword arguments to the class constructor or via attributes::
sphere = openmc.Sphere(r=10.0)
# This is equivalent
sphere = openmc.Sphere()
sphere.r = 10.0
Once a surface has been created, half-spaces can be obtained by applying the
unary ``-`` or ``+`` operators, corresponding to the negative and positive
half-spaces, respectively. For example::
>>> sphere = openmc.Sphere(r=10.0)
>>> inside_sphere = -sphere
>>> outside_sphere = +sphere
>>> type(inside_sphere)
<class 'openmc.surface.Halfspace'>
Instances of :class:`openmc.Halfspace` can be combined together using the
Boolean operators ``&`` (intersection), ``|`` (union), and ``~`` (complement)::
>>> inside_sphere = -openmc.Sphere()
>>> above_plane = +openmc.ZPlane()
>>> northern_hemisphere = inside_sphere & above_plane
>>> type(northern_hemisphere)
<class 'openmc.region.Intersection'>
For many regions, a bounding-box can be determined automatically::
>>> northern_hemisphere.bounding_box
(array([-1., -1., 0.]), array([1., 1., 1.]))
While a bounding box can be determined for regions involving half-spaces of
spheres, cylinders, and axis-aligned planes, it generally cannot be determined
if the region involves cones, non-axis-aligned planes, or other exotic
second-order surfaces. For example, the :func:`openmc.model.hexagonal_prism`
function returns the interior region of a hexagonal prism; because it is bounded
by a :class:`openmc.Plane`, trying to get its bounding box won't work::
>>> hex = openmc.model.hexagonal_prism()
>>> hex.bounding_box
(array([-0.8660254, -inf, -inf]),
array([ 0.8660254, inf, inf]))
Boundary Conditions
-------------------
When a surface is created, by default particles that pass through the surface
will consider it to be transmissive, i.e., they pass through the surface
freely. If your model does not extend to infinity in all spatial dimensions, you
may want to specify different behavior for particles passing through a
surface. To specify a vacuum boundary condition, simply change the
:attr:`Surface.boundary_type` attribute to 'vacuum'::
outer_surface = openmc.Sphere(r=100.0, boundary_type='vacuum')
# This is equivalent
outer_surface = openmc.Sphere(r=100.0)
outer_surface.boundary_type = 'vacuum'
Reflective and periodic boundary conditions can be set with the strings
'reflective' and 'periodic'. Vacuum and reflective boundary conditions can be
applied to any type of surface. Periodic boundary conditions can be applied to
pairs of planar surfaces. For axis-aligned planes, matching periodic surfaces
can be determined automatically. For non-axis-aligned planes, it is necessary to
specify pairs explicitly using the :attr:`Surface.periodic_surface` attribute as
in the following example::
p1 = openmc.Plane(a=0.3, b=5.0, d=1.0, boundary_type='periodic')
p2 = openmc.Plane(a=0.3, b=5.0, d=-1.0, boundary_type='periodic')
p1.periodic_surface = p2
Rotationally-periodic boundary conditions can be specified for a pair of
:class:`XPlane` and :class:`YPlane`; in that case, the
:attr:`Surface.periodic_surface` attribute must be specified manually as well.
.. caution:: When using rotationally-periodic boundary conditions, your geometry
must be defined in the first quadrant, i.e., above the y-plane and
to the right of the x-plane.
.. _usersguide_cells:
-----
Cells
-----
Once you have a material created and a region of space defined, you need to
define a *cell* that assigns the material to the region. Cells are created using
the :class:`openmc.Cell` class::
fuel = openmc.Cell(fill=uo2, region=pellet)
# This is equivalent
fuel = openmc.Cell()
fuel.fill = uo2
fuel.region = pellet
In this example, an instance of :class:`openmc.Material` is assigned to the
:attr:`Cell.fill` attribute. One can also fill a cell with a :ref:`universe
<usersguide_universes>` or :ref:`lattice <usersguide_lattices>`.
The classes :class:`Halfspace`, :class:`Intersection`, :class:`Union`, and
:class:`Complement` and all instances of :class:`openmc.Region` and can be
assigned to the :attr:`Cell.region` attribute.
.. _usersguide_universes:
---------
Universes
---------
Similar to MCNP and Serpent, OpenMC is capable of using *universes*, collections
of cells that can be used as repeatable units of geometry. At a minimum, there
must be one "root" universe present in the model. To define a universe, an
instance of :class:`openmc.Universe` is created and then cells can be added
using the :meth:`Universe.add_cells` or :meth:`Universe.add_cell`
methods. Alternatively, a list of cells can be specified in the constructor::
universe = openmc.Universe(cells=[cell1, cell2, cell3])
# This is equivalent
universe = openmc.Universe()
universe.add_cells([cell1, cell2])
universe.add_cell(cell3)
Universes are generally used in three ways:
1. To be assigned to a :class:`Geometry` object (see
:ref:`usersguide_geom_export`),
2. To be assigned as the fill for a cell via the :attr:`Cell.fill` attribute,
and
3. To be used in a regular arrangement of universes in a :ref:`lattice
<usersguide_lattices>`.
Once a universe is constructed, it can actually be used to determine what cell
or material is found at a given location by using the :meth:`Universe.find`
method, which returns a list of universes, cells, and lattices which are
traversed to find a given point. The last element of that list would contain the
lowest-level cell at that location::
>>> universe.find((0., 0., 0.))[-1]
Cell
ID = 10000
Name = cell 1
Fill = Material 10000
Region = -10000
Rotation = None
Temperature = None
Translation = None
As you are building a geometry, it is also possible to display a plot of single
universe using the :meth:`Universe.plot` method. This method requires that you
have `matplotlib <http://matplotlib.org/>`_ installed.
.. _usersguide_lattices:
--------
Lattices
--------
Many particle transport models involve repeated structures that occur in a
regular pattern such as a rectangular or hexagonal lattice. In such a case, it
would be cumbersome to have to define the boundaries of each of the cells to be
filled with a universe. OpenMC provides a means to define lattice structures
through the :class:`openmc.RectLattice` and :class:`openmc.HexLattice` classes.
Rectangular Lattices
--------------------
A rectangular lattice defines a two-dimensional or three-dimensional array of
universes that are filled into rectangular prisms (lattice elements) each of
which has the same width, length, and height. To completely define a rectangular
lattice, one needs to specify
- The coordinates of the lower-left corner of the lattice
(:attr:`RectLattice.lower_left`),
- The pitch of the lattice, i.e., the distance between the center of adjacent
lattice elements (:attr:`RectLattice.pitch`),
- What universes should fill each lattice element
(:attr:`RectLattice.universes`), and
- A universe that is used to fill any lattice position outside the well-defined
portion of the lattice (:attr:`RectLattice.outer`).
For example, to create a 3x3 lattice centered at the origin in which each
lattice element is 5cm by 5cm and is filled by a universe ``u``, one could run::
lattice = openmc.RectLattice()
lattice.lower_left = (-7.5, -7.5)
lattice.pitch = (5.0, 5.0)
lattice.universes = [[u, u, u],
[u, u, u],
[u, u, u]]
Note that because this is a two-dimensional lattice, the lower-left coordinates
and pitch only need to specify the :math:`x,y` values. The order that the
universes appear is such that the first row corresponds to lattice elements with
the highest :math:`y` -value. Note that the :attr:`RectLattice.universes`
attribute expects a doubly-nested iterable of type :class:`openmc.Universe` ---
this can be normal Python lists, as shown above, or a NumPy array can be used as
well::
lattice.universes = np.tile(u, (3, 3))
For a three-dimensional lattice, the :math:`x,y,z` coordinates of the lower-left
coordinate need to be given and the pitch should also give dimensions for all
three axes. For example, to make a 3x3x3 lattice where the bottom layer is
universe ``u``, the middle layer is universe ``q`` and the top layer is universe
``z`` would look like::
lat3d = openmc.RectLattice()
lat3d.lower_left = (-7.5, -7.5, -7.5)
lat3d.pitch = (5.0, 5.0, 5.0)
lat3d.universes = [
[[u, u, u],
[u, u, u],
[u, u, u]],
[[q, q, q],
[q, q, q],
[q, q, q]],
[[z, z, z],
[z, z, z]
[z, z, z]]]
Again, using NumPy can make things easier::
lat3d.universes = np.empty((3, 3, 3), dtype=openmc.Universe)
lat3d.universes[0, ...] = u
lat3d.universes[1, ...] = q
lat3d.universes[2, ...] = z
Finally, it's possible to specify that lattice positions that aren't normally
without the bounds of the lattice be filled with an "outer" universe. This
allows one to create a truly infinite lattice if desired. An outer universe is
set with the :attr:`RectLattice.outer` attribute.
Hexagonal Lattices
------------------
OpenMC also allows creation of 2D and 3D hexagonal lattices. Creating a
hexagonal lattice is similar to creating a rectangular lattice with a few
differences:
- The center of the lattice must be specified (:attr:`HexLattice.center`).
- For a 2D hexagonal lattice, a single value for the pitch should be specified,
although it still needs to appear in a list. For a 3D hexagonal lattice, the
pitch in the radial and axial directions should be given.
- For a hexagonal lattice, the :attr:`HexLattice.universes` attribute cannot be
given as a NumPy array for reasons explained below.
- As with rectangular lattices, the :attr:`HexLattice.outer` attribute will
specify an outer universe.
For a 2D hexagonal lattice, the :attr:`HexLattice.universes` attribute should be
set to a two-dimensional list of universes filling each lattice element. Each
sub-list corresponds to one ring of universes and is ordered from the outermost
ring to the innermost ring. The universes within each sub-list are ordered from
the "top" (position with greatest y value) and proceed in a clockwise fashion
around the ring. The :meth:`HexLattice.show_indices` static method can be used
to help figure out how to place universes::
>>> print(openmc.HexLattice.show_indices(3))
(0, 0)
(0,11) (0, 1)
(0,10) (1, 0) (0, 2)
(1, 5) (1, 1)
(0, 9) (2, 0) (0, 3)
(1, 4) (1, 2)
(0, 8) (1, 3) (0, 4)
(0, 7) (0, 5)
(0, 6)
Note that by default, hexagonal lattices are positioned such that each lattice
element has two faces that are parallel to the :math:`y` axis. As one example,
to create a three-ring lattice centered at the origin with a pitch of 10 cm
where all the lattice elements centered along the :math:`y` axis are filled with
universe ``u`` and the remainder are filled with universe ``q``, the following
code would work::
hexlat = openmc.HexLattice()
hexlat.center = (0, 0)
hexlat.pitch = [10]
outer_ring = [u, q, q, q, q, q, u, q, q, q, q, q]
middle_ring = [u, q, q, u, q, q]
inner_ring = [u]
hexlat.universes = [outer_ring, middle_ring, inner_ring]
If you need to create a hexagonal boundary (composed of six planar surfaces) for
a hexagonal lattice, :func:`openmc.model.hexagonal_prism` can be used.
.. _usersguide_geom_export:
--------------------------
Exporting a Geometry Model
--------------------------
Once you have finished building your geometry by creating surfaces, cell, and,
if needed, lattices, the last step is to create an instance of
:class:`openmc.Geometry` and export it to an XML file that the
:ref:`scripts_openmc` executable can read using the
:meth:`Geometry.export_to_xml` method. This can be done as follows::
geom = openmc.Geometry(root_univ)
geom.export_to_xml()
# This is equivalent
geom = openmc.Geometry()
geom.root_universe = root_univ
geom.export_to_xml()
Note that it's not strictly required to manually create a root universe. You can
also pass a list of cells to the :class:`openmc.Geometry` constructor and it
will handle creating the unverse::
geom = openmc.Geometry([cell1, cell2, cell3])
geom.export_to_xml()
.. _constructive solid geometry: https://en.wikipedia.org/wiki/Constructive_solid_geometry
.. _quadratic surfaces: https://en.wikipedia.org/wiki/Quadric
--------------------------
Using CAD-based Geometry
--------------------------
OpenMC relies on the Direct Accelerated Geometry Monte Carlo toolkit (`DAGMC
<https://svalinn.github.io/DAGMC/>`_) to represent CAD-based geometry in a
surface mesh format. A DAGMC run can be enabled in OpenMC by setting the
``dagmc`` property to ``True`` in the model Settings either via the Python
:class:`openmc.settings` Python class::
settings = openmc.Settings()
settings.dagmc = True
or in the :ref:`settings.xml <io_settings>` file::
<dagmc>true</dagmc>
With ``dagmc`` set to true, OpenMC will load the DAGMC model (from a local file
named ``dagmc.h5m``) when initializing a simulation. If a `geometry.xml
<../io_formats/geometry.html>`_ is present as well, it will be ignored.
**Note:** DAGMC geometries used in OpenMC are currently required to be clean,
meaning that all surfaces have been `imprinted and merged
<https://svalinn.github.io/DAGMC/usersguide/trelis_workflow.html>`_
successfully and that the model is `watertight
<https://svalinn.github.io/DAGMC/usersguide/tools.html#make-watertight>`_. Future
implementations of DAGMC geometry will support small volume overlaps and
un-merged surfaces.

28
docs/source/usersguide/index.rst Normal file
View file

@ -0,0 +1,28 @@
.. _usersguide:
============
User's Guide
============
Welcome to the OpenMC User's Guide! This tutorial will guide you through the
essential aspects of using OpenMC to perform simulations.
.. toctree::
:numbered:
:maxdepth: 1
beginners
install
cross_sections
basics
materials
geometry
settings
tallies
plots
depletion
scripts
processing
parallel
volume
troubleshoot

492
docs/source/usersguide/install.rst Normal file
View file

@ -0,0 +1,492 @@
.. _usersguide_install:
==============================
Installation and Configuration
==============================
.. currentmodule:: openmc
.. _install_conda:
----------------------------------------
Installing on Linux/Mac with conda-forge
----------------------------------------
Conda_ is an open source package management system and environment management
system for installing multiple versions of software packages and their
dependencies and switching easily between them. `conda-forge
<https://conda-forge.github.io/>`_ is a community-led conda channel of
installable packages. For instructions on installing conda, please consult their
`documentation
<https://docs.conda.io/projects/conda/en/latest/user-guide/install/>`_.
Once you have `conda` installed on your system, add the `conda-forge` channel to
your configuration with:
.. code-block:: sh
conda config --add channels conda-forge
Once the `conda-forge` channel has been enabled, OpenMC can then be installed
with:
.. code-block:: sh
conda install openmc
It is possible to list all of the versions of OpenMC available on your platform with:
.. code-block:: sh
conda search openmc --channel conda-forge
.. _install_ppa:
-----------------------------
Installing on Ubuntu with PPA
-----------------------------
For users with Ubuntu 15.04 or later, a binary package for OpenMC is available
through a `Personal Package Archive`_ (PPA) and can be installed through the
`APT package manager`_. First, add the following PPA to the repository sources:
.. code-block:: sh
sudo apt-add-repository ppa:paulromano/staging
Next, resynchronize the package index files:
.. code-block:: sh
sudo apt update
Now OpenMC should be recognized within the repository and can be installed:
.. code-block:: sh
sudo apt install openmc
Binary packages from this PPA may exist for earlier versions of Ubuntu, but they
are no longer supported.
.. _Personal Package Archive: https://launchpad.net/~paulromano/+archive/staging
.. _APT package manager: https://help.ubuntu.com/community/AptGet/Howto
.. _install_source:
----------------------
Installing from Source
----------------------
.. _prerequisites:
Prerequisites
-------------
.. admonition:: Required
:class: error
* A C/C++ compiler such as gcc_
OpenMC's core codebase is written in C++. The source files have been
tested to work with a wide variety of compilers. If you are using a
Debian-based distribution, you can install the g++ compiler using the
following command::
sudo apt install g++
* CMake_ cross-platform build system
The compiling and linking of source files is handled by CMake in a
platform-independent manner. If you are using Debian or a Debian
derivative such as Ubuntu, you can install CMake using the following
command::
sudo apt install cmake
* HDF5_ Library for portable binary output format
OpenMC uses HDF5 for many input/output files. As such, you will need to
have HDF5 installed on your computer. The installed version will need to
have been compiled with the same compiler you intend to compile OpenMC
with. If compiling with gcc from the APT repositories, users of Debian
derivatives can install HDF5 and/or parallel HDF5 through the package
manager::
sudo apt install libhdf5-dev
Parallel versions of the HDF5 library called `libhdf5-mpich-dev` and
`libhdf5-openmpi-dev` exist which are built against MPICH and OpenMPI,
respectively. To link against a parallel HDF5 library, make sure to set
the HDF5_PREFER_PARALLEL CMake option, e.g.::
CXX=mpicxx.mpich cmake -DHDF5_PREFER_PARALLEL=on ..
Note that the exact package names may vary depending on your particular
distribution and version.
If you are using building HDF5 from source in conjunction with MPI, we
recommend that your HDF5 installation be built with parallel I/O
features. An example of configuring HDF5_ is listed below::
CC=mpicc ./configure --enable-parallel
You may omit ``--enable-parallel`` if you want to compile HDF5_ in serial.
.. admonition:: Optional
:class: note
* An MPI implementation for distributed-memory parallel runs
To compile with support for parallel runs on a distributed-memory
architecture, you will need to have a valid implementation of MPI
installed on your machine. The code has been tested and is known to work
with the latest versions of both OpenMPI_ and MPICH_. OpenMPI and/or MPICH
can be installed on Debian derivatives with::
sudo apt install mpich libmpich-dev
sudo apt install openmpi-bin libopenmpi-dev
* DAGMC_ toolkit for simulation using CAD-based geometries
OpenMC supports particle tracking in CAD-based geometries via the Direct
Accelerated Geometry Monte Carlo (DAGMC) toolkit (`installation
instructions
<https://svalinn.github.io/DAGMC/install/dag_multiple.html>`_). For use in
OpenMC, only the ``MOAB_DIR`` and ``BUILD_TALLY`` variables need to be
specified in the CMake configuration step.
* git_ version control software for obtaining source code
.. _gcc: https://gcc.gnu.org/
.. _CMake: http://www.cmake.org
.. _OpenMPI: http://www.open-mpi.org
.. _MPICH: http://www.mpich.org
.. _HDF5: https://www.hdfgroup.org/solutions/hdf5/
.. _DAGMC: https://svalinn.github.io/DAGMC/index.html
Obtaining the Source
--------------------
All OpenMC source code is hosted on GitHub_. You can download the source code
directly from GitHub or, if you have the git_ version control software installed
on your computer, you can use git to obtain the source code. The latter method
has the benefit that it is easy to receive updates directly from the GitHub
repository. GitHub has a good set of `instructions
<http://help.github.com/set-up-git-redirect>`_ for how to set up git to work
with GitHub since this involves setting up ssh_ keys. With git installed and
setup, the following command will download the full source code from the GitHub
repository::
git clone https://github.com/openmc-dev/openmc.git
By default, the cloned repository will be set to the development branch. To
switch to the source of the latest stable release, run the following commands::
cd openmc
git checkout master
.. _GitHub: https://github.com/openmc-dev/openmc
.. _git: https://git-scm.com
.. _ssh: https://en.wikipedia.org/wiki/Secure_Shell
.. _usersguide_build:
Build Configuration
-------------------
Compiling OpenMC with CMake is carried out in two steps. First, ``cmake`` is run
to determine the compiler, whether optional packages (MPI, HDF5) are available,
to generate a list of dependencies between source files so that they may be
compiled in the correct order, and to generate a normal Makefile. The Makefile
is then used by ``make`` to actually carry out the compile and linking
commands. A typical out-of-source build would thus look something like the
following
.. code-block:: sh
mkdir build && cd build
cmake ..
make
Note that first a build directory is created as a subdirectory of the source
directory. The Makefile in the top-level directory will automatically perform an
out-of-source build with default options.
CMakeLists.txt Options
++++++++++++++++++++++
The following options are available in the CMakeLists.txt file:
debug
Enables debugging when compiling. The flags added are dependent on which
compiler is used.
profile
Enables profiling using the GNU profiler, gprof.
optimize
Enables high-optimization using compiler-dependent flags. For gcc and
Intel C++, this compiles with -O3.
openmp
Enables shared-memory parallelism using the OpenMP API. The C++ compiler
being used must support OpenMP. (Default: on)
dagmc
Enables use of CAD-based DAGMC_ geometries. Please see the note about DAGMC in
the optional dependencies list for more information on this feature. The
installation directory for DAGMC should also be defined as `DAGMC_ROOT` in the
CMake configuration command. (Default: off)
coverage
Compile and link code instrumented for coverage analysis. This is typically
used in conjunction with gcov_.
To set any of these options (e.g. turning on debug mode), the following form
should be used:
.. code-block:: sh
cmake -Ddebug=on /path/to/openmc
.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _usersguide_compile_mpi:
Compiling with MPI
++++++++++++++++++
To compile with MPI, set the :envvar:`CXX` environment variable to the path to
the MPI C++ wrapper. For example, in a bash shell:
.. code-block:: sh
export CXX=mpicxx
cmake /path/to/openmc
Note that in many shells, environment variables can be set for a single command,
i.e.
.. code-block:: sh
CXX=mpicxx cmake /path/to/openmc
Selecting HDF5 Installation
+++++++++++++++++++++++++++
CMakeLists.txt searches for the ``h5cc`` or ``h5pcc`` HDF5 C wrapper on
your PATH environment variable and subsequently uses it to determine library
locations and compile flags. If you have multiple installations of HDF5 or one
that does not appear on your PATH, you can set the HDF5_ROOT environment
variable to the root directory of the HDF5 installation, e.g.
.. code-block:: sh
export HDF5_ROOT=/opt/hdf5/1.8.15
cmake /path/to/openmc
This will cause CMake to search first in /opt/hdf5/1.8.15/bin for ``h5cc`` /
``h5pcc`` before it searches elsewhere. As noted above, an environment variable
can typically be set for a single command, i.e.
.. code-block:: sh
HDF5_ROOT=/opt/hdf5/1.8.15 cmake /path/to/openmc
.. _compile_linux:
Compiling on Linux and Mac OS X
-------------------------------
To compile OpenMC on Linux or Max OS X, run the following commands from within
the root directory of the source code:
.. code-block:: sh
mkdir build && cd build
cmake ..
make
make install
This will build an executable named ``openmc`` and install it (by default in
/usr/local/bin). If you do not have administrative privileges, you can install
OpenMC locally by specifying an install prefix when running cmake:
.. code-block:: sh
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
The ``CMAKE_INSTALL_PREFIX`` variable can be changed to any path for which you
have write-access.
Compiling on Windows 10
-----------------------
Recent versions of Windows 10 include a subsystem for Linux that allows one to
run Bash within Ubuntu running in Windows. First, follow the installation guide
`here <https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`_ to get
Bash on Ubuntu on Windows setup. Once you are within bash, obtain the necessary
:ref:`prerequisites <prerequisites>` via ``apt``. Finally, follow the
:ref:`instructions for compiling on linux <compile_linux>`.
Compiling for the Intel Xeon Phi
--------------------------------
For the second generation Knights Landing architecture, nothing special is
required to compile OpenMC. You may wish to experiment with compiler flags that
control generation of vector instructions to see what configuration gives
optimal performance for your target problem.
For the first generation Knights Corner architecture, it is necessary to
cross-compile OpenMC. If you are using the Intel compiler, it is necessary to
specify that all objects be compiled with the ``-mmic`` flag as follows:
.. code-block:: sh
mkdir build && cd build
CXX=icpc CXXFLAGS=-mmic cmake -Dopenmp=on ..
make
Note that unless an HDF5 build for the Intel Xeon Phi (Knights Corner) is
already on your target machine, you will need to cross-compile HDF5 for the Xeon
Phi. An `example script`_ to build zlib and HDF5 provides several necessary
workarounds.
.. _example script: https://github.com/paulromano/install-scripts/blob/master/install-hdf5-mic
Testing Build
-------------
To run the test suite, you will first need to download a pre-generated cross
section library along with windowed multipole data. Please refer to our
:ref:`devguide_tests` documentation for further details.
---------------------
Installing Python API
---------------------
If you installed OpenMC using :ref:`Conda <install_conda>` or :ref:`PPA
<install_ppa>`, no further steps are necessary in order to use OpenMC's
:ref:`Python API <pythonapi>`. However, if you are :ref:`installing from source
<install_source>`, the Python API is not installed by default when ``make
install`` is run because in many situations it doesn't make sense to install a
Python package in the same location as the ``openmc`` executable (for example,
if you are installing the package into a `virtual environment
<https://docs.python.org/3/tutorial/venv.html>`_). The easiest way to install
the :mod:`openmc` Python package is to use pip_, which is included by default in
Python 3.4+. From the root directory of the OpenMC distribution/repository, run:
.. code-block:: sh
pip install .
pip will first check that all :ref:`required third-party packages
<usersguide_python_prereqs>` have been installed, and if they are not present,
they will be installed by downloading the appropriate packages from the Python
Package Index (`PyPI <https://pypi.org/>`_). However, do note that since pip
runs the ``setup.py`` script which requires NumPy, you will have to first
install NumPy:
.. code-block:: sh
pip install numpy
Installing in "Development" Mode
--------------------------------
If you are primarily doing development with OpenMC, it is strongly recommended
to install the Python package in :ref:`"editable" mode <devguide_editable>`.
.. _usersguide_python_prereqs:
Prerequisites
-------------
The Python API works with Python 3.4+. In addition to Python itself, the API
relies on a number of third-party packages. All prerequisites can be installed
using Conda_ (recommended), pip_, or through the package manager in most Linux
distributions. To run simulations in parallel using MPI, it is recommended to
build mpi4py, HDF5, h5py from source, in that order, using the same compilers
as for OpenMC.
.. admonition:: Required
:class: error
`NumPy <http://www.numpy.org/>`_
NumPy is used extensively within the Python API for its powerful
N-dimensional array.
`SciPy <https://www.scipy.org/>`_
SciPy's special functions, sparse matrices, and spatial data structures
are used for several optional features in the API.
`pandas <http://pandas.pydata.org/>`_
Pandas is used to generate tally DataFrames as demonstrated in
:ref:`examples_pandas` example notebook.
`h5py <http://www.h5py.org/>`_
h5py provides Python bindings to the HDF5 library. Since OpenMC outputs
various HDF5 files, h5py is needed to provide access to data within these
files from Python.
`Matplotlib <http://matplotlib.org/>`_
Matplotlib is used to providing plotting functionality in the API like the
:meth:`Universe.plot` method and the :func:`openmc.plot_xs` function.
`uncertainties <https://pythonhosted.org/uncertainties/>`_
Uncertainties are used for decay data in the :mod:`openmc.data` module.
`lxml <http://lxml.de/>`_
lxml is used for the :ref:`scripts_validate` script and various other
parts of the Python API.
.. admonition:: Optional
:class: note
`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_
mpi4py provides Python bindings to MPI for running distributed-memory
parallel runs. This package is needed if you plan on running depletion
simulations in parallel using MPI.
`Cython <http://cython.org/>`_
Cython is used for resonance reconstruction for ENDF data converted to
:class:`openmc.data.IncidentNeutron`.
`vtk <http://www.vtk.org/>`_
The Python VTK bindings are needed to convert voxel and track files to VTK
format.
`pytest <https://docs.pytest.org>`_
The pytest framework is used for unit testing the Python API.
.. _usersguide_nxml:
-----------------------------------------------------
Configuring Input Validation with GNU Emacs nXML mode
-----------------------------------------------------
The `GNU Emacs`_ text editor has a built-in mode that extends functionality for
editing XML files. One of the features in nXML mode is the ability to perform
real-time `validation`_ of XML files against a `RELAX NG`_ schema. The OpenMC
source contains RELAX NG schemas for each type of user input file. In order for
nXML mode to know about these schemas, you need to tell emacs where to find a
"locating files" description. Adding the following lines to your ``~/.emacs``
file will enable real-time validation of XML input files:
.. code-block:: common-lisp
(require 'rng-loc)
(add-to-list 'rng-schema-locating-files "~/openmc/schemas.xml")
Make sure to replace the last string on the second line with the path to the
schemas.xml file in your own OpenMC source directory.
.. _GNU Emacs: http://www.gnu.org/software/emacs/
.. _validation: https://en.wikipedia.org/wiki/XML_validation
.. _RELAX NG: http://relaxng.org/
.. _NNDC: http://www.nndc.bnl.gov/endf/b7.1/acefiles.html
.. _ctest: http://www.cmake.org/cmake/help/v2.8.12/ctest.html
.. _Conda: https://docs.conda.io/en/latest/
.. _pip: https://pip.pypa.io/en/stable/

177
docs/source/usersguide/materials.rst Normal file
View file

@ -0,0 +1,177 @@
.. _usersguide_materials:
.. currentmodule:: openmc
=====================
Material Compositions
=====================
Materials in OpenMC are defined as a set of nuclides/elements at specified
densities and are created using the :class:`openmc.Material` class. Once a
material has been instantiated, nuclides can be added with
:meth:`Material.add_nuclide` and elements can be added with
:meth:`Material.add_element`. Densities can be specified using atom fractions or
weight fractions. For example, to create a material and add Gd152 at 0.5 atom
percent, you'd run::
mat = openmc.Material()
mat.add_nuclide('Gd152', 0.5, 'ao')
The third argument to :meth:`Material.add_nuclide` can also be 'wo' for weight
percent. The densities specified for each nuclide/element are relative and are
renormalized based on the total density of the material. The total density is
set using the :meth:`Material.set_density` method. The density can be specified
in gram per cubic centimeter ('g/cm3'), atom per barn-cm ('atom/b-cm'), or
kilogram per cubic meter ('kg/m3'), e.g.,
::
mat.set_density('g/cm3', 4.5)
----------------
Natural Elements
----------------
The :meth:`Material.add_element` method works exactly the same as
:meth:`Material.add_nuclide`, except that instead of specifying a single isotope
of an element, you specify the element itself. For example,
::
mat.add_element('C', 1.0)
Internally, OpenMC stores data on the atomic masses and natural abundances of
all known isotopes and then uses this data to determine what isotopes should be
added to the material. When the material is later exported to XML for use by the
:ref:`scripts_openmc` executable, you'll see that any natural elements were
expanded to the naturally-occurring isotopes.
The :meth:`Material.add_element` method can also be used to add uranium at a
specified enrichment through the `enrichment` argument. For example, the
following would add 3.2% enriched uranium to a material::
mat.add_element('U', 1.0, enrichment=3.2)
In addition to U235 and U238, concentrations of U234 and U236 will be present
and are determined through a correlation based on measured data.
Often, cross section libraries don't actually have all naturally-occurring
isotopes for a given element. For example, in ENDF/B-VII.1, cross section
evaluations are given for O16 and O17 but not for O18. If OpenMC is aware of
what cross sections you will be using (through the
:envvar:`OPENMC_CROSS_SECTIONS` environment variable), it will attempt to only
put isotopes in your model for which you have cross section data. In the case of
oxygen in ENDF/B-VII.1, the abundance of O18 would end up being lumped with O16.
-----------------------
Thermal Scattering Data
-----------------------
If you have a moderating material in your model like water or graphite, you
should assign thermal scattering data (so-called :math:`S(\alpha,\beta)`) using
the :meth:`Material.add_s_alpha_beta` method. For example, to model light water,
you would need to add hydrogen and oxygen to a material and then assign the
``c_H_in_H2O`` thermal scattering data::
water = openmc.Material()
water.add_nuclide('H1', 2.0)
water.add_nuclide('O16', 1.0)
water.add_s_alpha_beta('c_H_in_H2O')
water.set_density('g/cm3', 1.0)
.. _usersguide_naming:
------------------
Naming Conventions
------------------
OpenMC uses the GND_ naming convention for nuclides, metastable states, and
compounds:
:Nuclides: ``SymA`` where "A" is the mass number (e.g., ``Fe56``)
:Elements: ``Sym0`` (e.g., ``Fe0`` or ``C0``)
:Excited states: ``SymA_eN`` (e.g., ``V51_e1`` for the first excited state of
Vanadium-51.) This is only used in decay data.
:Metastable states: ``SymA_mN`` (e.g., ``Am242_m1`` for the first excited state
of Americium-242).
:Compounds: ``c_String_Describing_Material`` (e.g., ``c_H_in_H2O``). Used for
thermal scattering data.
.. important:: The element syntax, e.g., ``C0``, is only used when the cross
section evaluation is an elemental evaluation, like carbon in
ENDF/B-VII.1! If you are adding an element via
:meth:`Material.add_element`, just use ``Sym``.
.. _GND: https://www.oecd-nea.org/science/wpec/sg38/Meetings/2016_May/tlh4gnd-main.pdf
-----------
Temperature
-----------
Some Monte Carlo codes define temperature implicitly through the cross section
data, which is itself given only at a particular temperature. In OpenMC, the
material definition is decoupled from the specification of temperature. Instead,
temperatures are assigned to :ref:`cells <usersguide_cells>`
directly. Alternatively, a default temperature can be assigned to a material
that is to be applied to any cell where the material is used. In the absence of
any cell or material temperature specification, a global default temperature can
be set that is applied to all cells and materials. Anytime a material
temperature is specified, it will override the global default
temperature. Similarly, anytime a cell temperatures is specified, it will
override the material or global default temperature. All temperatures should be
given in units of Kelvin.
To assign a default material temperature, one should use the ``temperature``
attribute, e.g.,
::
hot_fuel = openmc.Material()
hot_fuel.temperature = 1200.0 # temperature in Kelvin
.. warning:: MCNP_ users should be aware that OpenMC does not use the concept of
cross section suffixes like "71c" or "80c". Temperatures in Kelvin
should be assigned directly per material or per cell using the
:attr:`Material.temperature` or :attr:`Cell.temperature`
attributes, respectively.
--------------------
Material Collections
--------------------
The :ref:`scripts_openmc` executable expects to find a ``materials.xml`` file
when it is run. To create this file, one needs to instantiate the
:class:`openmc.Materials` class and add materials to it. The :class:`Materials`
class acts like a list (in fact, it is a subclass of Python's built-in
:class:`list` class), so materials can be added by passing a list to the
constructor, using methods like ``append()``, or through the operator
``+=``. Once materials have been added to the collection, it can be exported
using the :meth:`Materials.export_to_xml` method.
::
materials = openmc.Materials()
materials.append(water)
materials += [uo2, zircaloy]
materials.export_to_xml()
# This is equivalent
materials = openmc.Materials([water, uo2, zircaloy])
materials.export_to_xml()
Cross Sections
--------------
OpenMC uses a file called :ref:`cross_sections.xml <io_cross_sections>` to
indicate where cross section data can be found on the filesystem. This file
serves the same role that ``xsdir`` does for MCNP_ or ``xsdata`` does for
Serpent. Information on how to generate a cross section listing file can be
found in :ref:`create_xs_library`. Once you have a cross sections file that has
been generated, you can tell OpenMC to use this file either by setting
:attr:`Materials.cross_sections` or by setting the
:envvar:`OPENMC_CROSS_SECTIONS` environment variable to the path of the
``cross_sections.xml`` file. The former approach would look like::
materials.cross_sections = '/path/to/cross_sections.xml'
.. _MCNP: https://mcnp.lanl.gov/

105
docs/source/usersguide/parallel.rst Normal file
View file

@ -0,0 +1,105 @@
.. _usersguide_parallel:
===================
Running in Parallel
===================
If you are running a simulation on a computer with multiple cores, multiple
sockets, or multiple nodes (i.e., a cluster), you can benefit from the fact that
OpenMC is able to use all available hardware resources if configured
correctly. OpenMC is capable of using both distributed-memory (`MPI
<http://mpi-forum.org/>`_) and shared-memory (`OpenMP
<http://www.openmp.org/>`_) parallelism. If you are on a single-socket
workstation or a laptop, using shared-memory parallelism is likely
sufficient. On a multi-socket node, cluster, or supercomputer, chances are you
will need to use both distributed-memory (across nodes) and shared-memory
(within a single node) parallelism.
----------------------------------
Shared-Memory Parallelism (OpenMP)
----------------------------------
When using OpenMP, multiple threads will be launched and each is capable of
simulating a particle independently of all other threads. The primary benefit of
using OpenMP within a node is that it requires very little extra memory per
thread. OpenMP can be turned on or off at configure-time; by default it is
turned on. The only requirement is that the C++ compiler you use must support
the OpenMP 3.1 or higher standard. Most recent compilers do support the use of
OpenMP.
To specify the number of threads at run-time, you can use the ``threads``
argument to :func:`openmc.run`::
openmc.run(threads=8)
If you're running :ref:`scripts_openmc` directly from the command line, you can
use the ``-s`` or ``--threads`` command-line argument. Alternatively, you can
use the :envvar:`OMP_NUM_THREADS` environment variable. If you do not specify
the number of threads, the OpenMP library will try to determine how many
hardware threads are available on your system and use that many threads.
In general, it is recommended to use as many OpenMP threads as you have hardware
threads on your system. Notably, on a system with Intel hyperthreading, the
hyperthreads should be used and can be expected to provide a 10--30% performance
improvement over not using hyperthreads.
------------------------------------
Distributed-Memory Parallelism (MPI)
------------------------------------
MPI defines a library specification for message-passing between processes. There
are two major implementations of MPI, `OpenMPI <https://www.open-mpi.org/>`_ and
`MPICH <http://www.mpich.org/>`_. Both implementations are known to work with
OpenMC; there is no obvious reason to prefer one over the other. Building OpenMC
with support for MPI requires that you have one of these implementations
installed on your system. For instructions on obtaining MPI, see
:ref:`prerequisites`. Once you have an MPI implementation installed, compile
OpenMC following :ref:`usersguide_compile_mpi`.
To run a simulation using MPI, :ref:`scripts_openmc` needs to be called using
the `mpiexec <https://www.mpich.org/static/docs/v3.1/www1/mpiexec.html>`_
wrapper. For example, to run OpenMC using 32 processes:
.. code-block:: sh
mpiexec -n 32 openmc
The same thing can be achieved from the Python API by supplying the ``mpi_args``
argument to :func:`openmc.run`::
openmc.run(mpi_args=['mpiexec', '-n', '32'])
----------------------
Maximizing Performance
----------------------
There are a number of things you can do to ensure that you obtain optimal
performance on a machine when running in parallel:
- **Use OpenMP within each NUMA node**. Some large server processors have so
many cores that the last level cache is split to reduce memory latency. For
example, the Intel Xeon Haswell-EP_ architecture uses a snoop mode called
*cluster on die* where the L3 cache is split in half. Thus, in general, you
should use one MPI process per socket (and OpenMP within each socket), but for
these large processors, you will want to go one step further and use one
process per NUMA node. The Xeon Phi Knights Landing architecture uses a
similar concept called `sub NUMA clustering
<https://colfaxresearch.com/knl-numa/>`_.
- **Use a sufficiently large number of particles per generation**. Between
fission generations, a number of synchronization tasks take place. If the
number of particles per generation is too low and you are using many
processes/threads, the synchronization time may become non-negligible.
- **Use hardware threading if available**.
- **Use process binding**. When running with MPI, you should ensure that
processes are bound_ to a specific hardware region. This can be set using the
``-bind-to`` (MPICH) or ``--bind-to`` (OpenMPI) option to ``mpiexec``.
- **Turn off generation of tallies.out**. For large simulations with millions of
tally bins or more, generating this ASCII file might consume considerable
time. You can turn off generation of ``tallies.out`` via the
:attr:`Settings.output` attribute::
settings = openmc.Settings()
settings.output = {'tallies': False}
.. _Haswell-EP: http://www.anandtech.com/show/8423/intel-xeon-e5-version-3-up-to-18-haswell-ep-cores-/4
.. _bound: https://wiki.mpich.org/mpich/index.php/Using_the_Hydra_Process_Manager#Process-core_Binding

136
docs/source/usersguide/plots.rst Normal file
View file

@ -0,0 +1,136 @@
.. _usersguide_plots:
======================
Geometry Visualization
======================
.. currentmodule:: openmc
OpenMC is capable of producing two-dimensional slice plots of a geometry as well
as three-dimensional voxel plots using the geometry plotting :ref:`run mode
<usersguide_run_modes>`. The geometry plotting mode relies on the presence of a
:ref:`plots.xml <io_plots>` file that indicates what plots should be created. To
create this file, one needs to create one or more :class:`openmc.Plot`
instances, add them to a :class:`openmc.Plots` collection, and then use the
:class:`Plots.export_to_xml` method to write the ``plots.xml`` file.
-----------
Slice Plots
-----------
.. image:: ../_images/atr.png
:width: 300px
By default, when an instance of :class:`openmc.Plot` is created, it indicates
that a 2D slice plot should be made. You can specify the origin of the plot
(:attr:`Plot.origin`), the width of the plot in each direction
(:attr:`Plot.width`), the number of pixels to use in each direction
(:attr:`Plot.pixels`), and the basis directions for the plot. For example, to
create a :math:`x` - :math:`z` plot centered at (5.0, 2.0, 3.0) with a width of
(50., 50.) and 400x400 pixels::
plot = openmc.Plot()
plot.basis = 'xz'
plot.origin = (5.0, 2.0, 3.0)
plot.width = (50., 50.)
plot.pixels = (400, 400)
The color of each pixel is determined by placing a particle at the center of
that pixel and using OpenMC's internal ``find_cell`` routine (the same one used
for particle tracking during simulation) to determine the cell and material at
that location.
.. note:: In this example, pixels are 50/400=0.125 cm wide. Thus, this plot may
miss any features smaller than 0.125 cm, since they could exist
between pixel centers. More pixels can be used to resolve finer
features but will result in larger files.
By default, a unique color will be assigned to each cell in the geometry. If you
want your plot to be colored by material instead, change the
:attr:`Plot.color_by` attribute::
plot.color_by = 'material'
If you don't like the random colors assigned, you can also indicate that
particular cells/materials should be given colors of your choosing::
plot.colors = {
water: 'blue',
clad: 'black'
}
# This is equivalent
plot.colors = {
water: (0, 0, 255),
clad: (0, 0, 0)
}
Note that colors can be given as RGB tuples or by a string indicating a valid
`SVG color <https://www.w3.org/TR/SVG11/types.html#ColorKeywords>`_.
When you're done creating your :class:`openmc.Plot` instances, you need to then
assign them to a :class:`openmc.Plots` collection and export it to XML::
plots = openmc.Plots([plot1, plot2, plot3])
plots.export_to_xml()
# This is equivalent
plots = openmc.Plots()
plots.append(plot1)
plots += [plot2, plot3]
plots.export_to_xml()
To actually generate the plots, run the :func:`openmc.plot_geometry`
function. Alternatively, run the :ref:`scripts_openmc` executable with the
``--plot`` command-line flag. When that has finished, you will have one or more
``.ppm`` files, i.e., `portable pixmap
<http://netpbm.sourceforge.net/doc/ppm.html>`_ files. On some Linux
distributions, these ``.ppm`` files are natively viewable. If you find that
you're unable to open them on your system (or you don't like the fact that they
are not compressed), you may want to consider converting them to another format.
This is easily accomplished with the ``convert`` command available on most Linux
distributions as part of the `ImageMagick
<http://www.imagemagick.org/script/convert.php>`_ package. (On Debian
derivatives: ``sudo apt install imagemagick``). Images are then converted like:
.. code-block:: sh
convert myplot.ppm myplot.png
Alternatively, if you're working within a `Jupyter <http://jupyter.org/>`_
Notebook or QtConsole, you can use the :func:`openmc.plot_inline` to run OpenMC
in plotting mode and display the resulting plot within the notebook.
.. _usersguide_voxel:
-----------
Voxel Plots
-----------
.. image:: ../_images/3dba.png
:width: 200px
The :class:`openmc.Plot` class can also be told to generate a 3D voxel plot
instead of a 2D slice plot. Simply change the :attr:`Plot.type` attribute to
'voxel'. In this case, the :attr:`Plot.width` and :attr:`Plot.pixels` attributes
should be three items long, e.g.::
vox_plot = openmc.Plot()
vox_plot.type = 'voxel'
vox_plot.width = (100., 100., 50.)
vox_plot.pixels = (400, 400, 200)
The voxel plot data is written to an :ref:`HDF5 file <io_voxel>`. The voxel file
can subsequently be converted into a standard mesh format that can be viewed in
`ParaView <http://www.paraview.org/>`_, `VisIt
<https://wci.llnl.gov/simulation/computer-codes/visit>`_, etc. This typically
will compress the size of the file significantly. The provided
:ref:`scripts_voxel` script can convert the HDF5 voxel file to VTK formats. Once
processed into a standard 3D file format, colors and masks can be defined using
the stored ID numbers to better explore the geometry. The process for doing this
will depend on the 3D viewer, but should be straightforward.
.. note:: 3D voxel plotting can be very computer intensive for the viewing
program (Visit, ParaView, etc.) if the number of voxels is large (>10
million or so). Thus if you want an accurate picture that renders
smoothly, consider using only one voxel in a certain direction.

105
docs/source/usersguide/processing.rst Normal file
View file

@ -0,0 +1,105 @@
.. _usersguide_processing:
=================================
Data Processing and Visualization
=================================
.. currentmodule:: openmc
This section is intended to explain procedures for carrying out common
post-processing tasks with OpenMC. While several utilities of varying complexity
are provided to help automate the process, the most powerful capabilities for
post-processing derive from use of the :ref:`Python API <pythonapi>`.
.. _usersguide_statepoint:
-------------------------
Working with State Points
-------------------------
Tally results are saved in both a text file (tallies.out) as well as an HDF5
statepoint file. While the tallies.out file may be fine for simple tallies, in
many cases the user requires more information about the tally or the run, or has
to deal with a large number of result values (e.g. for mesh tallies). In these
cases, extracting data from the statepoint file via the :ref:`pythonapi` is the
preferred method of data analysis and visualization.
Data Extraction
---------------
A great deal of information is available in statepoint files (See
:ref:`io_statepoint`), all of which is accessible through the Python
API. The :class:`openmc.StatePoint` class can load statepoints and access data
as requested; it is used in many of the provided plotting utilities, OpenMC's
regression test suite, and can be used in user-created scripts to carry out
manipulations of the data.
An :ref:`example IPython notebook <notebook_post_processing>` demonstrates how
to extract data from a statepoint using the Python API.
Plotting in 2D
--------------
The :ref:`IPython notebook example <notebook_post_processing>` also demonstrates
how to plot a mesh tally in two dimensions using the Python API. One can also
use the :ref:`scripts_plot` script which provides an interactive GUI to explore
and plot mesh tallies for any scores and filter bins.
.. image:: ../_images/plotmeshtally.png
:width: 400px
Getting Data into MATLAB
------------------------
There is currently no front-end utility to dump tally data to MATLAB files, but
the process is straightforward. First extract the data using the Python API via
``openmc.statepoint`` and then use the `Scipy MATLAB IO routines
<http://docs.scipy.org/doc/scipy/reference/tutorial/io.html>`_ to save to a MAT
file. Note that all arrays that are accessible in a statepoint are already in
NumPy arrays that can be reshaped and dumped to MATLAB in one step.
.. _usersguide_track:
----------------------------
Particle Track Visualization
----------------------------
.. image:: ../_images/Tracks.png
:width: 400px
OpenMC can dump particle tracks—the position of particles as they are
transported through the geometry. There are two ways to make OpenMC output
tracks: all particle tracks through a command line argument or specific particle
tracks through settings.xml.
Running :ref:`scripts_openmc` with the argument ``-t`` or ``--track`` will cause
a track file to be created for every particle transported in the code. Be
careful as this will produce as many files as there are source particles in your
simulation. To identify a specific particle for which a track should be created,
set the :attr:`Settings.track` attribute to a tuple containing the batch,
generation, and particle number of the desired particle. For example, to create
a track file for particle 4 of batch 1 and generation 2::
settings = openmc.Settings()
settings.track = (1, 2, 4)
To specify multiple particles, the length of the iterable should be a multiple
of three, e.g., if we wanted particles 3 and 4 from batch 1 and generation 2::
settings.track = (1, 2, 3, 1, 2, 4)
After running OpenMC, the working directory will contain a file of the form
"track_(batch #)_(generation #)_(particle #).h5" for each particle tracked.
These track files can be converted into VTK poly data files with the
:ref:`scripts_track` script.
----------------------
Source Site Processing
----------------------
For eigenvalue problems, OpenMC will store information on the fission source
sites in the statepoint file by default. For each source site, the weight,
position, sampled direction, and sampled energy are stored. To extract this data
from a statepoint file, the ``openmc.statepoint`` module can be used. An
:ref:`example IPython notebook <notebook_post_processing>` demontrates how to
analyze and plot source information.

257
docs/source/usersguide/scripts.rst Normal file
View file

@ -0,0 +1,257 @@
.. _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``. ``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
.. note:: If you're using the Python API, :func:`openmc.run` is equivalent to
running ``openmc`` from the command line.
.. _scripts_ace:
----------------------
``openmc-ace-to-hdf5``
----------------------
This script can be used to create HDF5 nuclear data libraries used by OpenMC if
you have existing ACE files. There are four different ways you can specify ACE
libraries that are to be converted:
1. List each ACE library as a positional argument. This is very useful in
conjunction with the usual shell utilities (``ls``, ``find``, etc.).
2. Use the ``--xml`` option to specify a pre-v0.9 cross_sections.xml file.
3. Use the ``--xsdir`` option to specify a MCNP xsdir file.
4. Use the ``--xsdata`` option to specify a Serpent xsdata file.
The script does not use any extra information from cross_sections.xml/ xsdir/
xsdata files to determine whether the nuclide is metastable. Instead, the
``--metastable`` argument can be used to specify whether the ZAID naming convention
follows the NNDC data convention (1000*Z + A + 300 + 100*m), or the MCNP data
convention (essentially the same as NNDC, except that the first metastable state
of Am242 is 95242 and the ground state is 95642).
The optional ``--fission_energy_release`` argument will accept an HDF5 file
containing a library of fission energy release (ENDF MF=1 MT=458) data. A
library built from ENDF/B-VII.1 data is released with OpenMC and can be found at
openmc/data/fission_Q_data_endb71.h5. This data is necessary for
'fission-q-prompt' and 'fission-q-recoverable' tallies, but is not needed
otherwise.
-h, --help show help message and exit
-d DESTINATION, --destination DESTINATION
Directory to create new library in
-m META, --metastable META
How to interpret ZAIDs for metastable nuclides. META
can be either 'nndc' or 'mcnp'. (default: nndc)
--xml XML Old-style cross_sections.xml that lists ACE libraries
--xsdir XSDIR MCNP xsdir file that lists ACE libraries
--xsdata XSDATA Serpent xsdata file that lists ACE libraries
--fission_energy_release FISSION_ENERGY_RELEASE
HDF5 file containing fission energy release data
.. _scripts_compton:
-----------------------
``openmc-make-compton``
-----------------------
This script generates an HDF5 file called ``compton_profiles.h5`` that contains
Compton profile data using an existing data library from `Geant4
<http://geant4.cern.ch/>`_. Note that OpenMC includes this data file by default
so it should not be necessary in practice to generate it yourself.
.. _scripts_depletion_chain:
-------------------------------
``openmc-make-depletion-chain``
-------------------------------
This script generates a depletion chain file called ``chain_endfb71.xml``
using ENDF/B-VII.1 nuclear data. If the :envvar:`OPENMC_ENDF_DATA` variable
is not set, and ``"neutron"``, ``"decay"``, ``"nfy"`` directories
do not exist, then ENDF/B-VII.1 data will be downloaded.
.. _scripts_depletion_chain_casl:
------------------------------------
``openmc-make-depletion-chain-casl``
------------------------------------
This script generates a depletion chain called ``chain_casl.xml``
using ENDF/B-VII.1 nuclear data for a simplified chain.
The nuclides were chosen by CASL-ORIGEN, which can be found in
Appendix A of Kang Seog Kim, `"Specification for the VERA Depletion
Benchmark Suite" <https://doi.org/10.2172/1256820>`_,
CASL-U-2015-1014-000, Rev. 0, ORNL/TM-2016/53, 2016.
``Te129`` has been added into this chain due to its link to
``I129`` production.
If the :envvar:`OPENMC_ENDF_DATA` variable is not set,
and ``"neutron"``, ``"decay"``, ``"nfy"`` directories
to not exist, then ENDF/B-VII.1 data will be downloaded.
.. _scripts_stopping:
-------------------------------
``openmc-make-stopping-powers``
-------------------------------
This script generates an HDF5 file called ``stopping_power.h5`` that contains
radiative and collision stopping powers and mean excitation energy pulled from
the `NIST ESTAR database
<https://physics.nist.gov/PhysRefData/Star/Text/ESTAR.html>`_. Note that OpenMC
includes this data file by default so it should not be necessary in practice to
generate it yourself.
.. _scripts_plot:
--------------------------
``openmc-plot-mesh-tally``
--------------------------
``openmc-plot-mesh-tally`` provides a graphical user interface for plotting mesh
tallies. The path to the statepoint file can be provided as an optional arugment
(if omitted, a file dialog will be presented).
.. _scripts_track:
-----------------------
``openmc-track-to-vtk``
-----------------------
This script converts HDF5 :ref:`particle track files <usersguide_track>` to VTK
poly data that can be viewed with ParaView or VisIt. The filenames of the
particle track files should be given as posititional arguments. The output
filename can also be changed with the ``-o`` flag:
-o OUT, --out OUT Output VTK poly filename
------------------------
``openmc-update-inputs``
------------------------
If you have existing XML files that worked in a previous version of OpenMC that
no longer work with the current version, you can try to update these files using
``openmc-update-inputs``. If any of the given files do not match the most
up-to-date formatting, then they will be automatically rewritten. The old
out-of-date files will not be deleted; they will be moved to a new file with
'.original' appended to their name.
Formatting changes that will be made:
geometry.xml
Lattices containing 'outside' attributes/tags will be replaced with lattices
containing 'outer' attributes, and the appropriate cells/universes will be
added. Any 'surfaces' attributes/elements on a cell will be renamed 'region'.
materials.xml
Nuclide names will be changed from ACE aliases (e.g., Am-242m) to HDF5/GND
names (e.g., Am242_m1). Thermal scattering table names will be changed from
ACE aliases (e.g., HH2O) to HDF5/GND names (e.g., c_H_in_H2O).
----------------------
``openmc-update-mgxs``
----------------------
This script updates OpenMC's deprecated multi-group cross section XML files to
the latest HDF5-based format.
-i IN, --input IN Input XML file
-o OUT, --output OUT Output file in HDF5 format
.. _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.
-r, --relaxng-path Location of OpenMC RelaxNG files
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.
======================== ===================================
.. _scripts_voxel:
---------------------------
``openmc-voxel-to-vtk``
---------------------------
When OpenMC generates :ref:`voxel plots <usersguide_voxel>`, they are in an
:ref:`HDF5 format <io_voxel>` that is not terribly useful by itself. The
``openmc-voxel-to-vtk`` script converts a voxel HDF5 file to a `VTK
<http://www.vtk.org/>`_ file. To run this script, you will need to have the VTK
Python bindings installed. To convert a voxel file, simply provide the path to
the file:
.. code-block:: sh
openmc-voxel-to-vtk voxel_1.h5
The ``openmc-voxel-to-vtk`` script also takes the following optional
command-line arguments:
-o, --output Path to output VTK file

268
docs/source/usersguide/settings.rst Normal file
View file

@ -0,0 +1,268 @@
.. _usersguide_settings:
==================
Execution Settings
==================
.. currentmodule:: openmc
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
:class:`openmc.Settings` class. At a minimum, you need to specify a :ref:`source
distribution <usersguide_source>` and :ref:`how many particles to run
<usersguide_particles>`. Many other execution settings can be set using the
:class:`openmc.Settings` object, but they are generally optional.
.. _usersguide_run_modes:
---------
Run Modes
---------
The :attr:`Settings.run_mode` attribute controls what run mode is used when
:ref:`scripts_openmc` is executed. There are five different run modes that can
be specified:
'eigenvalue'
Runs a :math:`k` eigenvalue simulation. See :ref:`methods_eigenvalue` for a
full description of eigenvalue calculations. In this mode, the
:attr:`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 :attr:`Settings.source` attribute.
'volume'
Runs a stochastic volume calculation.
'plot'
Generates slice or voxel plots (see :ref:`usersguide_plots`).
'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 :class:`openmc.Settings` object and assign the
:attr:`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'.
.. _usersguide_particles:
-------------------
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
:ref:`realization <methods_tallies>` of the tally random variables. Thus, you
need to specify both the number of batches (:attr:`Settings.batches`) as well as
the number of particles per batch (:attr:`Settings.particles`).
For a :math:`k` eigenvalue simulation, particles are grouped into *fission
generations*, as described in :ref:`methods_eigenvalue`. 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 :attr:`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 :ref:`method-successive-generations`, which may take
many generations. To specify the number of batches that should be discarded
before tallies begin to accumulate, use the :attr:`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
.. _usersguide_source:
-----------------------------
External Source Distributions
-----------------------------
External source distributions can be specified through the
:attr:`Settings.source` attribute. If you have a single external source, you can
create an instance of :class:`openmc.Source` and use it to set the
:attr:`Settings.source` attribute. If you have multiple external sources with
varying source strengths, :attr:`Settings.source` should be set to a list of
:class:`openmc.Source` objects.
The :class:`openmc.Source` class has three main attributes that one can set:
:attr:`Source.space`, which defines the spatial distribution,
:attr:`Source.angle`, which defines the angular distribution, and
:attr:`Source.energy`, which defines the energy distribution.
The spatial distribution can be set equal to a sub-class of
:class:`openmc.stats.Spatial`; common choices are :class:`openmc.stats.Point` or
:class:`openmc.stats.Box`. To independently specify distributions in the
:math:`x`, :math:`y`, and :math:`z` coordinates, you can use
:class:`openmc.stats.CartesianIndependent`.
The angular distribution can be set equal to a sub-class of
:class:`openmc.stats.UnitSphere` such as :class:`openmc.stats.Isotropic`,
:class:`openmc.stats.Monodirectional`, or
:class:`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
(:class:`openmc.stats.Discrete`), a Watt fission spectrum
(:class:`openmc.stats.Watt`), or a tabular distribution
(:class:`openmc.stats.Tabular`). By default, if no energy distribution is
specified, a Watt fission spectrum with :math:`a` = 0.988 MeV and :math:`b` =
2.249 MeV :sup:`-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 :class:`openmc.Source` class also has a :attr:`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]
Finally, the :attr:`Source.particle` attribute can be used to indicate the
source should be composed of particles other than neutrons. For example, the
following would generate a photon source::
source = openmc.Source()
source.particle = 'photon'
...
settings.source = source
For a full list of all classes related to statistical distributions, see
:ref:`pythonapi_stats`.
---------------
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
:class:`openmc.Mesh` class. After instantiating a :class:`Mesh`, you need to
specify the lower-left coordinates of the mesh (:attr:`Mesh.lower_left`), the
number of mesh cells in each direction (:attr:`Mesh.dimension`) and either the
upper-right coordinates of the mesh (:attr:`Mesh.upper_right`) or the width of
each mesh cell (:attr:`Mesh.width`). Once you have a mesh, simply assign it to
the :attr:`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 :attr:`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
----------------
Photon Transport
----------------
In addition to neutrons, OpenMC is also capable of simulating the passage of
photons through matter. This allows the modeling of photon production from
neutrons as well as pure photon calculations. The
:attr:`Settings.photon_transport` attribute can be used to enable photon
transport::
settings.photon_transport = True
The way in which OpenMC handles secondary charged particles can be specified
with the :attr:`Settings.electron_treatment` attribute. By default, the
:ref:`thick-target bremsstrahlung <ttb>` (TTB) approximation is used to generate
bremsstrahlung radiation emitted by electrons and positrons created in photon
interactions. To neglect secondary bremsstrahlung photons and instead deposit
all energy from electrons locally, the local energy deposition option can be
selected::
settings.electron_treatment = 'led'
.. note::
Some features related to photon transport are not currently implemented,
including:
* Tallying photon energy deposition.
* Generating a photon source from a neutron calculation that can be used
for a later fixed source photon calculation.
* Photoneutron reactions.
--------------------------
Generation of Output Files
--------------------------
A number of attributes of the :class:`openmc.Settings` class can be used to
control what files are output and how often. First, there is the
:attr:`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
:ref:`result_files` 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
:attr:`Settings.output` dictionary as::
settings.output = {
'tallies': False,
'path': 'results'
}
Generation of statepoint and source files is handled separately through the
:attr:`Settings.statepoint` and :attr:`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
:attr:`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)}
.. _NIST ESTAR database: https://physics.nist.gov/PhysRefData/Star/Text/ESTAR.html

310
docs/source/usersguide/tallies.rst Normal file
View file

@ -0,0 +1,310 @@
.. _usersguide_tallies:
==================
Specifying Tallies
==================
.. currentmodule:: openmc
In order to obtain estimates of physical quantities in your simulation, you need
to create one or more tallies using the :class:`openmc.Tally` class. As
explained in detail in the :ref:`theory manual <methods_tallies>`, tallies
provide estimates of a scoring function times the flux integrated over some
region of phase space, as in:
.. math::
X = \underbrace{\int d\mathbf{r} \int d\mathbf{\Omega} \int
dE}_{\text{filters}} \underbrace{f(\mathbf{r}, \mathbf{\Omega},
E)}_{\text{scores}} \psi (\mathbf{r}, \mathbf{\Omega}, E)
Thus, to specify a tally, we need to specify what regions of phase space should
be included when deciding whether to score an event as well as what the scoring
function (:math:`f` in the above equation) should be used. The regions of phase
space are generally called *filters* and the scoring functions are simply
called *scores*.
The only cases when filters do not correspond directly with the regions of
phase space are when expansion functions are applied in the integrand, such as
for Legendre expansions of the scattering kernel.
-------
Filters
-------
To specify the regions of phase space, one must create a
:class:`openmc.Filter`. Since :class:`openmc.Filter` is an abstract class, you
actually need to instantiate one of its sub-classes (for a full listing, see
:ref:`pythonapi_tallies`). For example, to indicate that events that occur in a
given cell should score to the tally, we would create a
:class:`openmc.CellFilter`::
cell_filter = openmc.CellFilter([fuel.id, moderator.id, reflector.id])
Another commonly used filter is :class:`openmc.EnergyFilter`, which specifies
multiple energy bins over which events should be scored. Thus, if we wanted to
tally events where the incident particle has an energy in the ranges [0 eV, 4
eV] and [4 eV, 1 MeV], we would do the following::
energy_filter = openmc.EnergyFilter([0.0, 4.0, 1.0e6])
Energies are specified in eV and need to be monotonically increasing.
.. caution:: An energy bin between zero and the lowest energy specified is not
included by default as it is in MCNP.
Once you have created a filter, it should be assigned to a :class:`openmc.Tally`
instance through the :attr:`Tally.filters` attribute::
tally.filters.append(cell_filter)
tally.filters.append(energy_filter)
# This is equivalent
tally.filters = [cell_filter, energy_filter]
.. note:: You are actually not required to assign any filters to a tally. If you
create a tally with no filters, all events will score to the
tally. This can be useful if you want to know, for example, a reaction
rate over your entire model.
.. _usersguide_scores:
------
Scores
------
To specify the scoring functions, a list of strings needs to be given to the
:attr:`Tally.scores` attribute. You can score the flux ('flux'), or a reaction
rate ('total', 'fission', etc.). For example, to tally the elastic scattering
rate and the fission neutron production, you'd assign::
tally.scores = ['elastic', 'nu-fission']
With no further specification, you will get the total elastic scattering rate
and the total fission neutron production. If you want reaction rates for a
particular nuclide or set of nuclides, you can set the :attr:`Tally.nuclides`
attribute to a list of strings indicating which nuclides. The nuclide names
should follow the same :ref:`naming convention <usersguide_naming>` as that used
for material specification. If we wanted the reaction rates only for U235 and
U238 (separately), we'd set::
tally.nuclides = ['U235', 'U238']
You can also list 'all' as a nuclide which will give you a separate reaction
rate for every nuclide in the model.
The following tables show all valid scores:
.. table:: **Flux scores: units are particle-cm per source particle.**
+----------------------+---------------------------------------------------+
|Score | Description |
+======================+===================================================+
|flux |Total flux. |
+----------------------+---------------------------------------------------+
.. 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. |
+----------------------+---------------------------------------------------+
|total |Total reaction rate. |
+----------------------+---------------------------------------------------+
|(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 |This score is similar in functionality to the |
| |``scatter`` score except the total production of |
| |neutrons due to scattering is scored vice simply |
| |the scattering rate. This accounts for |
| |multiplicity from (n,2n), (n,3n), and (n,4n) |
| |reactions. |
+----------------------+---------------------------------------------------+
|H1-production |Total production of H1. |
+----------------------+---------------------------------------------------+
|H2-production |Total production of H2 (deuterium). |
+----------------------+---------------------------------------------------+
|H3-production |Total production of H3 (tritium). |
+----------------------+---------------------------------------------------+
|He3-production |Total production of He3. |
+----------------------+---------------------------------------------------+
|He4-production |Total production of He4 (alpha particles). |
+----------------------+---------------------------------------------------+
.. table:: **Miscellaneous scores: units are indicated for each.**
+----------------------+---------------------------------------------------+
|Score | Description |
+======================+===================================================+
|current |Used in combination with a meshsurface filter: |
| |Partial currents on the boundaries of each cell in |
| |a mesh. It may not be used in conjunction with any |
| |other score. Only energy and mesh filters may be |
| |used. |
| |Used in combination with a surface filter: |
| |Net currents on any surface previously defined in |
| |the geometry. It may be used along with any other |
| |filter, except meshsurface filters. |
| |Surfaces can alternatively be defined with cell |
| |from and cell filters thereby resulting in tallying|
| |partial currents. |
| |Units are particles per source particle. |
+----------------------+---------------------------------------------------+
|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. |
+----------------------+---------------------------------------------------+
|heating |Total nuclear heating in units of eV per source |
| |particle. For neutrons, this corresponds to MT=301 |
| |produced by NJOY's HEATR module while for photons, |
| |this is tallied from either direct photon energy |
| |deposition (analog estimator) or pre-generated |
| |photon heating number. See :ref:`methods_heating` |
+----------------------+---------------------------------------------------+
|heating-local |Total nuclear heating in units of eV per source |
| |particle assuming energy from secondary photons is |
| |deposited locally. Note that this score should only|
| |be used for incident neutrons. See |
| |:ref:`methods_heating`. |
+----------------------+---------------------------------------------------+
|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. |
+----------------------+---------------------------------------------------+
|damage-energy |Damage energy production in units of eV per source |
| |particle. This corresponds to MT=444 produced by |
| |NJOY's HEATR module. |
+----------------------+---------------------------------------------------+

104
docs/source/usersguide/troubleshoot.rst Normal file
View file

@ -0,0 +1,104 @@
.. _usersguide_troubleshoot:
===============
Troubleshooting
===============
-------------------------
Problems with Compilation
-------------------------
If you are experiencing problems trying to compile OpenMC, first check if the
error you are receiving is among the following options.
-------------------------
Problems with Simulations
-------------------------
Segmentation Fault
******************
A segmentation fault occurs when the program tries to access a variable in
memory that was outside the memory allocated for the program. The best way to
debug a segmentation fault is to re-compile OpenMC with debug options turned
on. Create a new build directory and type the following commands:
.. code-block:: sh
mkdir build-debug && cd build-debug
cmake -Ddebug=on /path/to/openmc
make
Now when you re-run your problem, it should report exactly where the program
failed. If after reading the debug output, you are still unsure why the program
failed, send an email to the OpenMC User's Group `mailing list`_.
ERROR: No cross_sections.xml file was specified in settings.xml or in the OPENMC_CROSS_SECTIONS environment variable.
*********************************************************************************************************************
OpenMC needs to know where to find cross section data for each nuclide.
Information on what data is available and in what files is summarized in a
cross_sections.xml file. You need to tell OpenMC where to find the
cross_sections.xml file either with the :ref:`cross_sections` in settings.xml or
with the :envvar:`OPENMC_CROSS_SECTIONS` environment variable. It is recommended
to add a line in your ``.profile`` or ``.bash_profile`` setting the
:envvar:`OPENMC_CROSS_SECTIONS` environment variable.
Geometry Debugging
******************
Overlapping Cells
^^^^^^^^^^^^^^^^^
For fast run times, normal simulations do not check if the geometry is
incorrectly defined to have overlapping cells. This can lead to incorrect
results that may or may not be obvious when there are errors in the geometry
input file. The built-in 2D and 3D plotters will check for cell overlaps at
the center of every pixel or voxel position they process, however this might
not be a sufficient check to ensure correctly defined geometry. For instance,
if an overlap is of small aspect ratio, the plotting resolution might not be
high enough to produce any pixels in the overlapping area.
To reliably validate a geometry input, it is best to run the problem in
geometry debugging mode with the ``-g``, ``-geometry-debug``, or
``--geometry-debug`` command-line options. This will enable checks for
overlapping cells at every move of esch simulated particle. Depending on the
complexity of the geometry input file, this could add considerable overhead to
the run (these runs can still be done in parallel). As a result, for this run
mode the user will probably want to run fewer particles than a normal
simulation run. In this case it is important to be aware of how much coverage
each area of the geometry is getting. For instance, if certain regions do not
have many particles travelling through them there will not be many locations
where overlaps are checked for in that region. The user should refer to the
output after a geometry debug run to see how many checks were performed in each
cell, and then adjust the number of starting particles or starting source
distributions accordingly to achieve good coverage.
ERROR: After particle __ crossed surface __ it could not be located in any cell and it did not leak.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This error can arise either if a problem is specified with no boundary
conditions or if there is an error in the geometry itself. First check to ensure
that all of the outer surfaces of your geometry have been given vacuum or
reflective boundary conditions. If proper boundary conditions have been applied
and you still receive this error, it means that a surface/cell/lattice in your
geometry has been specified incorrectly or is missing.
The best way to debug this error is to turn on a trace for the particle getting
lost. After the error message, the code will display what batch, generation, and
particle number caused the error. In your settings.xml, add a :ref:`trace`
followed by the batch, generation, and particle number. This will give you
detailed output every time that particle enters a cell, crosses a boundary, or
has a collision. For example, if you received this error at cycle 5, generation
1, particle 4032, you would enter:
.. code-block:: xml
<trace>5 1 4032</trace>
For large runs it is often advantageous to run only the offending particle by
using particle restart mode with the ``-s``, ``-particle``, or ``--particle``
command-line options in conjunction with the particle restart files that are
created when particles are lost with this error.
.. _mailing list: https://groups.google.com/forum/?fromgroups=#!forum/openmc-users

69
docs/source/usersguide/volume.rst Normal file
View file

@ -0,0 +1,69 @@
.. _usersguide_volume:
==============================
Stochastic Volume Calculations
==============================
.. currentmodule:: openmc
OpenMC has a capability to stochastically determine volumes of cells, materials,
and universes. The method works by overlaying a bounding box, sampling points
from within the box, and seeing what fraction of points were found in a desired
domain. The benefit of doing this stochastically (as opposed to equally-spaced
points), is that it is possible to give reliable error estimates on each
stochastic quantity.
To specify that a volume calculation be run, you first need to create an
instance of :class:`openmc.VolumeCalculation`. The constructor takes a list of
cells, materials, or universes; the number of samples to be used; and the
lower-left and upper-right Cartesian coordinates of a bounding box that encloses
the specified domains::
lower_left = (-0.62, -0.62, -50.)
upper_right = (0.62, 0.62, 50.)
vol_calc = openmc.VolumeCalculation([fuel, clad, moderator], 1000000,
lower_left, upper_right)
For domains contained within regions that have simple definitions, OpenMC can
sometimes automatically determine a bounding box. In this case, the last two
arguments are not necessary. For example,
::
sphere = openmc.Sphere(r=10.0)
cell = openm.Cell(region=-sphere)
vol_calc = openmc.VolumeCalculation([cell], 1000000)
Of course, the volumes that you *need* this capability for are often the ones
with complex definitions.
Once you have one or more :class:`openmc.VolumeCalculation` objects created, you
can then assign then to :attr:`Settings.volume_calculations`::
settings = openmc.Settings()
settings.volume_calculations = [cell_vol_calc, mat_vol_calc]
To execute the volume calculations, one can either set :attr:`Settings.run_mode`
to 'volume' and run :func:`openmc.run`, or alternatively run
:func:`openmc.calculate_volumes` which doesn't require that
:attr:`Settings.run_mode` be set.
When your volume calculations have finished, you can load the results using the
:meth:`VolumeCalculation.load_results` method on an existing object. If you
don't have an existing :class:`VolumeCalculation` object, you can create one and
load results simultaneously using the :meth:`VolumeCalculation.from_hdf5` class
method::
vol_calc = openmc.VolumeCalculation(...)
...
openmc.calculate_volumes()
vol_calc.load_results('volume_1.h5')
# ..or we can create a new object
vol_calc = openmc.VolumeCalculation.from_hdf5('volume_1.h5')
After the results are loaded, volume estimates will be stored in
:attr:`VolumeCalculation.volumes`. There is also a
:attr:`VolumeCalculation.atoms_dataframe` attribute that shows stochastic
estimates of the number of atoms of each type of nuclide within the specified
domains along with their uncertainties.