mirror of
https://github.com/openmc-dev/openmc.git
synced 2026-07-28 06:05:58 -04:00
Start restructuring user's guide
This commit is contained in:
Paul Romano
parent
47deaa8c60
commit
8a2035a191
17 changed files with 2746 additions and 2984 deletions
154
docs/source/usersguide/basics.rst
Normal file
154
docs/source/usersguide/basics.rst
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
.. _usersguide_basics:
|
||||
|
||||
======================
|
||||
Basics of Using OpenMC
|
||||
======================
|
||||
|
||||
-----------
|
||||
Input Files
|
||||
-----------
|
||||
|
||||
When you build and install OpenMC, you will have an :ref:`scripts_openmc`
|
||||
executable on your system. When you run ``openmc``, the first thing it will do
|
||||
is look for a set of XML_ files that describe the model you want to
|
||||
simulation. Three of these files are required and another three are optional, as
|
||||
described below.
|
||||
|
||||
.. admonition:: Required
|
||||
:class: error
|
||||
|
||||
:ref:`io_materials`
|
||||
This file describes what materials are present in the problem and what they
|
||||
are composed of. Additionally, it indicates where OpenMC should look for a
|
||||
cross section library.
|
||||
|
||||
:ref:`io_geometry`
|
||||
This file describes how the materials defined in ``materials.xml`` occupy
|
||||
regions of space. Physical volumes are defined using constructive solid
|
||||
geometry, described in detail in FIXME.
|
||||
|
||||
:ref:`io_settings`
|
||||
This file indicates what mode OpenMC should be run in, how many particles
|
||||
to simulate, the source definition, and a whole host of miscellaneous
|
||||
options.
|
||||
|
||||
.. admonition:: Optional
|
||||
:class: note
|
||||
|
||||
:ref:`io_tallies`
|
||||
This file describes what physical quantities should be tallied during the
|
||||
simulation (fluxes, reaction rates, currents, etc.).
|
||||
|
||||
:ref:`io_plots`
|
||||
This file gives specifications for producing slice or voxel plots of the
|
||||
geometry.
|
||||
|
||||
:ref:`io_cmfd`
|
||||
This file specifies execution parameters for coarse mesh finite difference
|
||||
(CMFD) acceleration.
|
||||
|
||||
eXtensible Markup Language (XML)
|
||||
--------------------------------
|
||||
|
||||
Unlike many other Monte Carlo codes which use an arbitrary-format ASCII file
|
||||
with "cards" to specify a particular geometry, materials, and associated run
|
||||
settings, the input files for OpenMC are structured in a set of XML_ files. XML,
|
||||
which stands for eXtensible Markup Language, is a simple format that allows data
|
||||
to be exchanged efficiently between different programs and interfaces.
|
||||
|
||||
Anyone who has ever seen webpages written in HTML will be familiar with the
|
||||
structure of XML whereby "tags" enclosed in angle brackets denote that a
|
||||
particular piece of data will follow. Let us examine the follow example:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<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.
|
||||
|
||||
.. _XML: http://www.w3.org/XML/
|
||||
|
||||
Creating Input Files
|
||||
--------------------
|
||||
|
||||
.. currentmodule:: openmc
|
||||
|
||||
The simplest option to create input files is to simply write them from scratch
|
||||
using the :ref:`XML format specifications <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:`pythonapi`. The
|
||||
Python API defines a set of functions and classes that roughly correspond to
|
||||
elements in the XML files. For example, the :class:`openmc.Cell` Python class
|
||||
directly corresponds to the :ref:`cell_element` in XML. Each XML file itself
|
||||
also has a corresponding class: :class:`openmc.Geometry` for ``geometry.xml``,
|
||||
:class:`openmc.Materials` for ``materials.xml``, :class:`openmc.Settings` for
|
||||
``settings.xml``, and so on. To create a model then, one creates instances of
|
||||
these classes and then uses the ``export_to_xml()`` method,
|
||||
e.g. :meth:`Geometry.export_to_xml`. Most scripts that generate a full model
|
||||
will look something like the following:
|
||||
|
||||
.. code-block:: Python
|
||||
|
||||
# Create materials
|
||||
materials = openmc.Materials()
|
||||
...
|
||||
materials.export_to_xml()
|
||||
|
||||
# Create geometry
|
||||
geom = openmc.Geometry()
|
||||
...
|
||||
geom.export_to_xml()
|
||||
|
||||
# Assign simulation settings
|
||||
settings = openmc.Settings()
|
||||
...
|
||||
settings.export_to_xml()
|
||||
|
||||
One a model has been created and exported to XML, a simulation can be run either
|
||||
by calling :ref:`scripts_openmc` directly from a shell or by using the
|
||||
:func:`openmc.run()` function from Python.
|
||||
|
||||
.. tip:: Users are strongly encouraged to use the Python API to generate input
|
||||
files and analyze results.
|
||||
|
||||
--------------
|
||||
Physical Units
|
||||
--------------
|
||||
|
||||
Unless specified otherwise, all length quantities are assumed to be in units of
|
||||
centimeters, all energy quantities are assumed to be in electronvolts, and all
|
||||
time quantities are assumed to be in seconds.
|
||||
|
||||
======= ============ ======
|
||||
Measure Default unit Symbol
|
||||
======= ============ ======
|
||||
length centimeter cm
|
||||
energy electronvolt eV
|
||||
time second s
|
||||
======= ============ ======
|
||||
|
||||
------------------------------------
|
||||
ERSN-OpenMC Graphical User Interface
|
||||
------------------------------------
|
||||
|
||||
A third-party Java-based user-friendly graphical user interface for creating XML
|
||||
input files called ERSN-OpenMC_ is developed and maintained by members of the
|
||||
Radiation and Nuclear Systems Group at the Faculty of Sciences Tetouan, Morocco.
|
||||
The GUI also allows one to automatically download prerequisites for installing and
|
||||
running OpenMC.
|
||||
|
||||
.. _ERSN-OpenMC: https://github.com/EL-Bakkali-Jaafar/ERSN-OpenMC
|
||||
|
|
@ -8,33 +8,35 @@ A Beginner's Guide to OpenMC
|
|||
What does OpenMC do?
|
||||
--------------------
|
||||
|
||||
In a nutshell, OpenMC simulates neutrons moving around randomly in a `nuclear
|
||||
reactor`_ (or other fissile system). This is what's known as `Monte Carlo`_
|
||||
simulation. Neutrons are important in nuclear reactors because they are the
|
||||
particles that induce `fission`_ in uranium and other nuclides. Knowing the
|
||||
behavior of neutrons allows you to determine how often and where fission
|
||||
occurs. The amount of energy released is then directly proportional to the
|
||||
fission reaction rate since most heat is produced by fission. By simulating many
|
||||
neutrons (millions or billions), it is possible to determine the average
|
||||
behavior of these neutrons (or the behavior of the energy produced or any other
|
||||
quantity one is interested in) very accurately.
|
||||
In a nutshell, OpenMC simulates neutral particles (presently only neutrons)
|
||||
moving stochastically through an arbitrarily defined model that represents an
|
||||
real-world experimental setup. The experiment could be as simple as a sphere of
|
||||
metal or as complicated as a full-scale `nuclear reactor`_. This is what's known
|
||||
as `Monte Carlo`_ simulation. In the case of a nuclear reactor model, neutrons
|
||||
are especially important because they are the particles that induce `fission`_
|
||||
in isotopes of uranium and other elements. Knowing the behavior of neutrons
|
||||
allows one to determine how often and where fission occurs. The amount of energy
|
||||
released is then directly proportional to the fission reaction rate since most
|
||||
heat is produced by fission. By simulating many neutrons (millions or billions),
|
||||
it is possible to determine the average behavior of these neutrons (or the
|
||||
behavior of the energy produced, or any other quantity one is interested in)
|
||||
very accurately.
|
||||
|
||||
Using Monte Carlo methods to determine the average behavior of various physical
|
||||
quantities in a nuclear reactor is quite different from other means of solving
|
||||
the same problem. The other class of methods for determining the behavior of
|
||||
neutrons and reactions rates in a reactor is so-called `deterministic`_
|
||||
methods. In these methods, the starting point is not randomly simulating
|
||||
particles but rather writing an equation that describes the average behavior of
|
||||
the particles. The equation that describes the average behavior of neutrons is
|
||||
called the `neutron transport`_ equation. This equation is a seven-dimensional
|
||||
equation (three for space, three for velocity, and one for time) and is very
|
||||
difficult to solve directly. For all but the simplest problems, it is necessary
|
||||
to make some sort of `discretization`_. As an example, we can divide up all
|
||||
space into small sections which are homogeneous and then solve the equation on
|
||||
those small sections. After these discretizations and various approximations,
|
||||
one can arrive at forms that are suitable for solution on a computer. Among
|
||||
these are discrete ordinates, method of characteristics, finite-difference
|
||||
diffusion, and nodal methods.
|
||||
quantities in a system is quite different from other means of solving the same
|
||||
problem. The other class of methods for determining the behavior of neutrons and
|
||||
reactions rates is so-called `deterministic`_ methods. In these methods, the
|
||||
starting point is not randomly simulating particles but rather writing an
|
||||
equation that describes the average behavior of the particles. The equation that
|
||||
describes the average behavior of neutrons is called the `neutron transport`_
|
||||
equation. This equation is a seven-dimensional equation (three for space, three
|
||||
for velocity, and one for time) and is very difficult to solve directly. For all
|
||||
but the simplest problems, it is necessary to make some sort of
|
||||
`discretization`_. As an example, we can divide up all space into small sections
|
||||
which are homogeneous and then solve the equation on those small sections. After
|
||||
these discretizations and various approximations, one can arrive at forms that
|
||||
are suitable for solution on a computer. Among these are discrete ordinates,
|
||||
method of characteristics, finite-difference diffusion, and nodal methods.
|
||||
|
||||
So why choose Monte Carlo over deterministic methods? Each method has its pros
|
||||
and cons. Let us first take a look at few of the salient pros and cons of
|
||||
|
|
@ -88,30 +90,32 @@ interest. This could be a nuclear reactor or any other physical system with
|
|||
fissioning material. You, as the code user, will need to describe the model so
|
||||
that the code can do something with it. A basic model consists of a few things:
|
||||
|
||||
- A description of the geometry -- the problem should be split up into regions
|
||||
of homogeneous material.
|
||||
- A description of the geometry -- the problem must be split up into regions of
|
||||
homogeneous material composition.
|
||||
- For each different material in the problem, a description of what nuclides are
|
||||
in the material and at what density.
|
||||
- Various parameters telling the code how many particles to simulate and what
|
||||
options to use.
|
||||
- A list of different physical quantities that the code should return at the end
|
||||
of the simulation. Remember, in a Monte Carlo simulation, if you don't ask for
|
||||
anything, it will not give you any answers (other than a few default
|
||||
quantities).
|
||||
of the simulation. In a Monte Carlo simulation, if you don't ask for anything,
|
||||
it will not give you any answers (other than a few default quantities).
|
||||
|
||||
-----------------------
|
||||
What do I need to know?
|
||||
-----------------------
|
||||
|
||||
If you are starting to work with OpenMC, there are a few things you should be
|
||||
familiar with. Whether you plan on working in Linux, Mac OS X, or Windows, you
|
||||
familiar with. Whether you plan on working in Linux, macOS, or Windows, you
|
||||
should be comfortable working in a command line environment. There are many
|
||||
resources online for learning command line environments. If you are using Linux
|
||||
or Mac OS X (also Unix-derived), `this tutorial
|
||||
<http://www.ee.surrey.ac.uk/Teaching/Unix/>`_ will help you get acquainted with
|
||||
commonly-used commands. It is also helpful to be familiar with `Python
|
||||
<http://www.python.org/>`_, as most of the post-processing utilities provided
|
||||
with OpenMC rely on it for data manipulation and results visualization.
|
||||
commonly-used commands.
|
||||
|
||||
To reap the full benefits of OpenMC, you should also have basic proficiency in
|
||||
the use of `Python <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
|
||||
|
|
@ -122,7 +126,7 @@ at the git documentation website. The `OpenMC source code`_ and documentation
|
|||
are hosted at `GitHub`_. In order to receive updates to the code directly,
|
||||
submit `bug reports`_, and perform other development tasks, you may want to sign
|
||||
up for a free account on GitHub. Once you have an account, you can follow `these
|
||||
instructions <http://help.github.com/set-up-git-redirect>`_ on how to set up
|
||||
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
|
||||
|
|
@ -153,5 +157,5 @@ and `Volume II`_. You may also find it helpful to review the following terms:
|
|||
.. _GitHub: https://github.com/
|
||||
.. _bug reports: https://github.com/mit-crpg/openmc/issues
|
||||
.. _Neutron cross section: http://en.wikipedia.org/wiki/Neutron_cross_section
|
||||
.. _Effective multiplication factor: http://en.wikipedia.org/wiki/Effective_multiplication_factor
|
||||
.. _Effective multiplication factor: https://en.wikipedia.org/wiki/Nuclear_chain_reaction#Effective_neutron_multiplication_factor
|
||||
.. _Flux: http://en.wikipedia.org/wiki/Neutron_flux
|
||||
|
|
|
|||
|
|
@ -9,10 +9,11 @@ essential aspects of using OpenMC to perform simulations.
|
|||
|
||||
.. toctree::
|
||||
:numbered:
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
beginners
|
||||
install
|
||||
input
|
||||
basics
|
||||
scripts
|
||||
processing
|
||||
troubleshoot
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -76,6 +76,7 @@ Prerequisites
|
|||
-------------
|
||||
|
||||
.. admonition:: Required
|
||||
:class: error
|
||||
|
||||
* A Fortran compiler such as gfortran_
|
||||
|
||||
|
|
@ -140,6 +141,7 @@ Prerequisites
|
|||
distribution and version.
|
||||
|
||||
.. admonition:: Optional
|
||||
:class: note
|
||||
|
||||
* An MPI implementation for distributed-memory parallel runs
|
||||
|
||||
|
|
@ -511,45 +513,6 @@ to the absolute path of the file library expected to used most frequently.
|
|||
.. _Serpent: http://montecarlo.vtt.fi
|
||||
.. _TENDL: https://tendl.web.psi.ch/tendl_2015/tendl2015.html
|
||||
|
||||
--------------
|
||||
Running OpenMC
|
||||
--------------
|
||||
|
||||
Once you have a model built (see :ref:`usersguide_input`), you can either run
|
||||
the openmc executable directly from the directory containing your XML input
|
||||
files, or you can specify as a command-line argument the directory containing
|
||||
the XML input files. For example, if your XML input files are in the directory
|
||||
``/home/username/somemodel/``, one way to run the simulation would be:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
cd /home/username/somemodel
|
||||
openmc
|
||||
|
||||
Alternatively, you could run from any directory:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
openmc /home/username/somemodel
|
||||
|
||||
Note that in the latter case, any output files will be placed in the present
|
||||
working directory which may be different from ``/home/username/somemodel``.
|
||||
|
||||
Command-Line Flags
|
||||
------------------
|
||||
|
||||
OpenMC accepts the following command line flags:
|
||||
|
||||
-g, --geometry-debug Run in geometry debugging mode, where cell overlaps are
|
||||
checked for after each move of a particle
|
||||
-n, --particles N Use *N* particles per generation or batch
|
||||
-p, --plot Run in plotting mode
|
||||
-r, --restart file Restart a previous run from a state point or a particle
|
||||
restart file
|
||||
-s, --threads N Run with *N* OpenMP threads
|
||||
-t, --track Write tracks for all particles
|
||||
-v, --version Show version information
|
||||
|
||||
-----------------------------------------------------
|
||||
Configuring Input Validation with GNU Emacs nXML mode
|
||||
-----------------------------------------------------
|
||||
|
|
|
|||
120
docs/source/usersguide/scripts.rst
Normal file
120
docs/source/usersguide/scripts.rst
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
.. _usersguide_scripts:
|
||||
|
||||
=======================
|
||||
Executables and Scripts
|
||||
=======================
|
||||
|
||||
.. _scripts_openmc:
|
||||
|
||||
----------
|
||||
``openmc``
|
||||
----------
|
||||
|
||||
Once you have a model built (see :ref:`usersguide_basics`), you can either run
|
||||
the openmc executable directly from the directory containing your XML input
|
||||
files, or you can specify as a command-line argument the directory containing
|
||||
the XML input files. For example, if your XML input files are in the directory
|
||||
``/home/username/somemodel/``, one way to run the simulation would be:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
cd /home/username/somemodel
|
||||
openmc
|
||||
|
||||
Alternatively, you could run from any directory:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
openmc /home/username/somemodel
|
||||
|
||||
Note that in the latter case, any output files will be placed in the present
|
||||
working directory which may be different from ``/home/username/somemodel``. If
|
||||
you're using the Python API, :func:`openmc.run` is equivalent to running
|
||||
``openmc`` from the command line. OpenMC accepts the following command line
|
||||
flags:
|
||||
|
||||
-c, --volume Run in stochastic volume calculation mode
|
||||
-g, --geometry-debug Run in geometry debugging mode, where cell overlaps are
|
||||
checked for after each move of a particle
|
||||
-n, --particles N Use *N* particles per generation or batch
|
||||
-p, --plot Run in plotting mode
|
||||
-r, --restart file Restart a previous run from a state point or a particle
|
||||
restart file
|
||||
-s, --threads N Run with *N* OpenMP threads
|
||||
-t, --track Write tracks for all particles
|
||||
-v, --version Show version information
|
||||
-h, --help Show help message
|
||||
|
||||
----------------------
|
||||
``openmc-ace-to-hdf5``
|
||||
----------------------
|
||||
|
||||
------------------------------
|
||||
``openmc-convert-mcnp70-data``
|
||||
------------------------------
|
||||
|
||||
------------------------------
|
||||
``openmc-convert-mcnp71-data``
|
||||
------------------------------
|
||||
|
||||
------------------------
|
||||
``openmc-get-jeff-data``
|
||||
------------------------
|
||||
|
||||
-----------------------------
|
||||
``openmc-get-multipole-data``
|
||||
-----------------------------
|
||||
|
||||
------------------------
|
||||
``openmc-get-nndc-data``
|
||||
------------------------
|
||||
|
||||
--------------------------
|
||||
``openmc-plot-mesh-tally``
|
||||
--------------------------
|
||||
|
||||
-----------------------
|
||||
``openmc-track-to-vtk``
|
||||
-----------------------
|
||||
|
||||
------------------------
|
||||
``openmc-update-inputs``
|
||||
------------------------
|
||||
|
||||
----------------------
|
||||
``openmc-update-mgxs``
|
||||
----------------------
|
||||
|
||||
.. _scripts_validate:
|
||||
|
||||
-----------------------
|
||||
``openmc-validate-xml``
|
||||
-----------------------
|
||||
|
||||
Input files can be checked before executing OpenMC using the
|
||||
``openmc-validate-xml`` script which is installed alongside the Python API. Two
|
||||
command line arguments can be set when running ``openmc-validate-xml``:
|
||||
|
||||
* ``-i``, ``--input-path`` - Location of OpenMC input files.
|
||||
*Default*: current working directory
|
||||
* ``-r``, ``--relaxng-path`` - Location of OpenMC RelaxNG files.
|
||||
*Default*: None
|
||||
|
||||
If the RelaxNG path is not set, the script will search for these files because
|
||||
it expects that the user is either running the script located in the install
|
||||
directory ``bin`` folder or in ``src/utils``. Once executed, it will match
|
||||
OpenMC XML files with their RelaxNG schema and check if they are valid. Below
|
||||
is a table of the messages that will be printed after each file is checked.
|
||||
|
||||
======================== ===================================
|
||||
Message Description
|
||||
======================== ===================================
|
||||
[XML ERROR] Cannot parse XML file.
|
||||
[NO RELAXNG FOUND] No RelaxNG file found for XML file.
|
||||
[NOT VALID] XML file does not match RelaxNG.
|
||||
[VALID] XML file matches RelaxNG.
|
||||
======================== ===================================
|
||||
|
||||
---------------------------
|
||||
``openmc-voxel-to-silovtk``
|
||||
---------------------------
|
||||
Loading…
Add table
Add a link
Reference in a new issue