Merge pull request #850 from paulromano/usersguide

Big documentation update

.gitignore

@@ -59,16 +59,17 @@ src/cmake_install.cmake
 src/install_manifest.txt
 
 # Nuclear data
-data/nndc
-data/nndc_hdf5
-data/wmp
-data/multipole_lib.tar.gz
-data/ENDF-B-VII.1-*.tar.gz
-data/JEFF32-ACE-*.tar.gz
-data/JEFF32-ACE-*.zip
-data/TSLs.tar.gz
-data/jeff-3.2
-data/jeff-3.2-hdf5
+scripts/nndc
+scripts/nndc_hdf5
+scripts/wmp
+scripts/multipole_lib.tar.gz
+scripts/ENDF-B-VII.1-*.tar.gz
+scripts/JEFF32-ACE-*.tar.gz
+scripts/JEFF32-ACE-*.zip
+scripts/TSLs.tar.gz
+scripts/jeff-3.2
+scripts/jeff-3.2-hdf5
+scripts/*.tar.xz
 
 # Images
 *.ppm
@@ -81,14 +82,16 @@ data/jeff-3.2-hdf5
 # IPython notebook checkpoints
 .ipynb_checkpoints
 
-# Multi-group cross section IPython Notebook
-docs/source/pythonapi/examples/*.xml
-docs/source/pythonapi/examples/*.png
-docs/source/pythonapi/examples/*.xls
-docs/source/pythonapi/examples/mgxs
-docs/source/pythonapi/examples/tracks
-docs/source/pythonapi/examples/fission-rates
-docs/source/pythonapi/examples/plots
+# Jupyter notebooks
+examples/jupyter/*.xml
+examples/jupyter/*.png
+examples/jupyter/*.xls
+examples/jupyter/*.ace
+examples/jupyter/*.endf
+examples/jupyter/mgxs
+examples/jupyter/tracks
+examples/jupyter/fission-rates
+examples/jupyter/plots
 
 # Cython files
 *.c

docs/source/examples/candu.rst

@@ -0,0 +1,13 @@
+.. _notebook_candu:
+
+=======================
+Modeling a CANDU Bundle
+=======================
+
+.. only:: html
+
+    .. notebook:: ../../../examples/jupyter/candu.ipynb
+
+.. only:: latex
+
+    IPython notebooks must be viewed in the online HTML documentation.

docs/source/examples/index.rst

@@ -9,19 +9,42 @@ features via the :ref:`pythonapi`.
 
 .. _Jupyter: https://jupyter.org/
 
+-----------
+Basic Usage
+-----------
+
 .. toctree::
     :maxdepth: 1
 
+    pincell
     post-processing
     pandas-dataframes
     tally-arithmetic
+    search
+    triso
+    candu
+    nuclear-data
+
+------------------------------------
+Multi-Group Cross Section Generation
+------------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
     mgxs-part-i
     mgxs-part-ii
     mgxs-part-iii
+    mdgxs-part-i
+    mdgxs-part-ii
+
+----------------
+Multi-Group Mode
+----------------
+
+.. toctree::
+    :maxdepth: 1
+
     mg-mode-part-i
     mg-mode-part-ii
     mg-mode-part-iii
-    mdgxs-part-i
-    mdgxs-part-ii
-    search
-    nuclear-data

docs/source/examples/mdgxs-part-i.rst

@@ -6,7 +6,7 @@ Multi-Group (Delayed) Cross Section Generation Part I: Introduction
 
 .. only:: html
 
-    .. notebook:: mdgxs-part-i.ipynb
+    .. notebook:: ../../../examples/jupyter/mdgxs-part-i.ipynb
 
 .. only:: latex
 

docs/source/examples/mdgxs-part-ii.rst

@@ -6,7 +6,7 @@ Multi-Group (Delayed) Cross Section Generation Part II: Advanced Features
 
 .. only:: html
 
-    .. notebook:: mdgxs-part-ii.ipynb
+    .. notebook:: ../../../examples/jupyter/mdgxs-part-ii.ipynb
 
 .. only:: latex
 

docs/source/examples/mg-mode-part-i.rst

@@ -6,7 +6,7 @@ Multi-Group Mode Part I: Introduction
 
 .. only:: html
 
-    .. notebook:: mg-mode-part-i.ipynb
+    .. notebook:: ../../../examples/jupyter/mg-mode-part-i.ipynb
 
 .. only:: latex
 

docs/source/examples/mg-mode-part-ii.rst

@@ -6,7 +6,7 @@ Multi-Group Mode Part II: MGXS Library Generation With OpenMC
 
 .. only:: html
 
-    .. notebook:: mg-mode-part-ii.ipynb
+    .. notebook:: ../../../examples/jupyter/mg-mode-part-ii.ipynb
 
 .. only:: latex
 

docs/source/examples/mg-mode-part-iii.rst

@@ -6,7 +6,7 @@ Multi-Group Mode Part III: Advanced Feature Showcase
 
 .. only:: html
 
-    .. notebook:: mg-mode-part-iii.ipynb
+    .. notebook:: ../../../examples/jupyter/mg-mode-part-iii.ipynb
 
 .. only:: latex
 

docs/source/examples/mgxs-part-i.rst

@@ -6,7 +6,7 @@ MGXS Part I: Introduction
 
 .. only:: html
 
-    .. notebook:: mgxs-part-i.ipynb
+    .. notebook:: ../../../examples/jupyter/mgxs-part-i.ipynb
 
 .. only:: latex
 

docs/source/examples/mgxs-part-ii.rst

@@ -6,7 +6,7 @@ MGXS Part II: Advanced Features
 
 .. only:: html
 
-    .. notebook:: mgxs-part-ii.ipynb
+    .. notebook:: ../../../examples/jupyter/mgxs-part-ii.ipynb
 
 .. only:: latex
 

docs/source/examples/mgxs-part-iii.rst

@@ -6,7 +6,7 @@ MGXS Part III: Libraries
 
 .. only:: html
 
-    .. notebook:: mgxs-part-iii.ipynb
+    .. notebook:: ../../../examples/jupyter/mgxs-part-iii.ipynb
 
 .. only:: latex
 

docs/source/examples/nuclear-data.rst

@@ -6,7 +6,7 @@ Nuclear Data
 
 .. only:: html
 
-    .. notebook:: nuclear-data.ipynb
+    .. notebook:: ../../../examples/jupyter/nuclear-data.ipynb
 
 .. only:: latex
 

docs/source/examples/pandas-dataframes.rst

@@ -1,10 +1,12 @@
+.. _examples_pandas:
+
 =================
 Pandas Dataframes
 =================
 
 .. only:: html
 
-    .. notebook:: pandas-dataframes.ipynb
+    .. notebook:: ../../../examples/jupyter/pandas-dataframes.ipynb
 
 .. only:: latex
 

docs/source/examples/pincell.rst

@@ -0,0 +1,13 @@
+.. _notebook_pincell:
+
+===================
+Modeling a Pin-Cell
+===================
+
+.. only:: html
+
+    .. notebook:: ../../../examples/jupyter/pincell.ipynb
+
+.. only:: latex
+
+    IPython notebooks must be viewed in the online HTML documentation.

docs/source/examples/post-processing.rst

@@ -6,7 +6,7 @@ Post Processing
 
 .. only:: html
 
-    .. notebook:: post-processing.ipynb
+    .. notebook:: ../../../examples/jupyter/post-processing.ipynb
 
 .. only:: latex
 

docs/source/examples/search.rst

@@ -6,7 +6,7 @@ Criticality Search
 
 .. only:: html
 
-    .. notebook:: search.ipynb
+    .. notebook:: ../../../examples/jupyter/search.ipynb
 
 .. only:: latex
 

docs/source/examples/tally-arithmetic.rst

@@ -4,7 +4,7 @@ Tally Arithmetic
 
 .. only:: html
 
-    .. notebook:: tally-arithmetic.ipynb
+    .. notebook:: ../../../examples/jupyter/tally-arithmetic.ipynb
 
 .. only:: latex
 

docs/source/examples/triso.rst

@@ -0,0 +1,13 @@
+.. _notebook_triso:
+
+========================
+Modeling TRISO Particles
+========================
+
+.. only:: html
+
+    .. notebook:: ../../../examples/jupyter/triso.ipynb
+
+.. only:: latex
+
+    IPython notebooks must be viewed in the online HTML documentation.

docs/source/index.rst

@@ -13,9 +13,7 @@ OpenMC was originally developed by members of the `Computational Reactor Physics
 Group`_ at the `Massachusetts Institute of Technology`_ starting
 in 2011. Various universities, laboratories, and other organizations now
 contribute to the development of OpenMC. For more information on OpenMC, feel
-free to send a message to the User's Group `mailing list`_. Documentation for
-the latest developmental version of the develop branch can be found on
-`Read the Docs`_.
+free to send a message to the User's Group `mailing list`_.
 
 .. _Computational Reactor Physics Group: http://crpg.mit.edu
 .. _Massachusetts Institute of Technology: http://web.mit.edu

docs/source/io_formats/cmfd.rst

@@ -0,0 +1,221 @@
+.. _io_cmfd:
+
+==============================
+CMFD Specification -- cmfd.xml
+==============================
+
+Coarse mesh finite difference acceleration method has been implemented in
+OpenMC. Currently, it allows users to accelerate fission source convergence
+during inactive neutron batches. To run CMFD, the ``<run_cmfd>`` element in
+``settings.xml`` should be set to "true".
+
+-------------------
+``<begin>`` Element
+-------------------
+
+The ``<begin>`` element controls what batch CMFD calculations should begin.
+
+  *Default*: 1
+
+------------------------
+``<dhat_reset>`` Element
+------------------------
+
+The ``<dhat_reset>`` element controls whether :math:`\widehat{D}` nonlinear
+CMFD parameters should be reset to zero before solving CMFD eigenproblem.
+It can be turned on with "true" and off with "false".
+
+  *Default*: false
+
+---------------------
+``<display>`` Element
+---------------------
+
+The ``<display>`` element sets one additional CMFD output column. Options are:
+
+* "balance" - prints the RMS [%] of the resdiual from the neutron balance
+  equation on CMFD tallies.
+* "dominance" - prints the estimated dominance ratio from the CMFD iterations.
+  **This will only work for power iteration eigensolver**.
+* "entropy" - prints the *entropy* of the CMFD predicted fission source.
+  **Can only be used if OpenMC entropy is active as well**.
+* "source" - prints the RMS [%] between the OpenMC fission source and CMFD
+  fission source.
+
+  *Default*: balance
+
+-------------------------
+``<downscatter>`` Element
+-------------------------
+
+The ``<downscatter>`` element controls whether an effective downscatter cross
+section should be used when using 2-group CMFD. It can be turned on with "true"
+and off with "false".
+
+  *Default*: false
+
+----------------------
+``<feedback>`` Element
+----------------------
+
+The ``<feedback>`` element controls whether or not the CMFD diffusion result is
+used to adjust the weight of fission source neutrons on the next OpenMC batch.
+It can be turned on with "true" and off with "false".
+
+  *Default*: false
+
+------------------------------------
+``<gauss_seidel_tolerance>`` Element
+------------------------------------
+
+The ``<gauss_seidel_tolerance>`` element specifies two parameters. The first is
+the absolute inner tolerance for Gauss-Seidel iterations when performing CMFD
+and the second is the relative inner tolerance for Gauss-Seidel iterations
+for CMFD calculations.
+
+  *Default*: 1.e-10 1.e-5
+
+--------------------
+``<ktol>`` Element
+--------------------
+
+The ``<ktol>`` element specifies the tolerance on the eigenvalue when performing
+CMFD power iteration.
+
+  *Default*: 1.e-8
+
+------------------
+``<mesh>`` Element
+------------------
+
+The CMFD mesh is a structured Cartesian mesh. This element has the following
+attributes/sub-elements:
+
+  :lower_left:
+    The lower-left corner of the structured mesh. If only two coordinates are
+    given, it is assumed that the mesh is an x-y mesh.
+
+  :upper_right:
+    The upper-right corner of the structrued mesh. If only two coordinates are
+    given, it is assumed that the mesh is an x-y mesh.
+
+  :dimension:
+    The number of mesh cells in each direction.
+
+  :width:
+    The width of mesh cells in each direction.
+
+  :energy:
+    Energy bins [in eV], listed in ascending order (e.g. 0.0 0.625 20.0e6)
+    for CMFD tallies and acceleration. If no energy bins are listed, OpenMC
+    automatically assumes a one energy group calculation over the entire
+    energy range.
+
+  :albedo:
+    Surface ratio of incoming to outgoing partial currents on global boundary
+    conditions. They are listed in the following order: -x +x -y +y -z +z.
+
+    *Default*: 1.0 1.0 1.0 1.0 1.0 1.0
+
+  :map:
+    An optional acceleration map can be specified to overlay on the coarse
+    mesh spatial grid. If this option is used, a ``1`` is used for a
+    non-accelerated region and a ``2`` is used for an accelerated region.
+    For a simple 4x4 coarse mesh with a 2x2 fuel lattice surrounded by
+    reflector, the map is:
+
+      ``1 1 1 1``
+
+      ``1 2 2 1``
+
+      ``1 2 2 1``
+
+      ``1 1 1 1``
+
+    Therefore a 2x2 system of equations is solved rather than a 4x4. This
+    is extremely important to use in reflectors as neutrons will not
+    contribute to any tallies far away from fission source neutron regions.
+    A ``2`` must be used to identify any fission source region.
+
+    .. note:: Only two of the following three sub-elements are needed:
+              ``lower_left``, ``upper_right`` and ``width``. Any combination
+              of two of these will yield the third.
+
+------------------
+``<norm>`` Element
+------------------
+
+The ``<norm>`` element is used to normalize the CMFD fission source distribution
+to a particular value. For example, if a fission source is calculated for a
+17 x 17 lattice of pins, the fission source may be normalized to the number of
+fission source regions, in this case 289. This is useful when visualizing this
+distribution as the average peaking factor will be unity. This parameter will
+not impact the calculation.
+
+  *Default*: 1.0
+
+---------------------------
+``<power_monitor>`` Element
+---------------------------
+
+The ``<power_monitor>`` element is used to view the convergence of power
+iteration. This option can be turned on with "true" and turned off with "false".
+
+  *Default*: false
+
+-------------------------
+``<run_adjoint>`` Element
+-------------------------
+
+The ``<run_adjoint>`` element can be turned on with "true" to have an adjoint
+calculation be performed on the last batch when CMFD is active.
+
+  *Default*: false
+
+--------------------
+``<shift>`` Element
+--------------------
+
+The ``<shift>`` element specifies an optional Wielandt shift parameter for
+accelerating power iterations. It is by default very large so the impact of the
+shift is effectively zero.
+
+  *Default*: 1e6
+
+----------------------
+``<spectral>`` Element
+----------------------
+
+The ``<spectral>`` element specifies an optional spectral radius that can be set to
+accelerate the convergence of Gauss-Seidel iterations during CMFD power iteration
+solve.
+
+  *Default*: 0.0
+
+------------------
+``<stol>`` Element
+------------------
+
+The ``<stol>`` element specifies the tolerance on the fission source when performing
+CMFD power iteration.
+
+  *Default*: 1.e-8
+
+-------------------------
+``<tally_reset>`` Element
+-------------------------
+
+The ``<tally_reset>`` element contains a list of batch numbers in which CMFD tallies
+should be reset.
+
+  *Default*: None
+
+----------------------------
+``<write_matrices>`` Element
+----------------------------
+
+The ``<write_matrices>`` element is used to write the sparse matrices created
+when solving CMFD equations. This option can be turned on with "true" and off
+with "false".
+
+  *Default*: false

docs/source/io_formats/cross_sections.rst

@@ -0,0 +1,51 @@
+.. _io_cross_sections:
+
+============================================
+Cross Sections Listing -- cross_sections.xml
+============================================
+
+.. _directory_element:
+
+-----------------------
+``<directory>`` Element
+-----------------------
+
+The ``<directory>`` element specifies a root directory to which the path for all
+files listed in a :ref:`library_element` are given relative to. This element has
+no attributes or sub-elements; the directory should be given within the text
+node. For example,
+
+.. code-block:: xml
+
+   <directory>/opt/data/cross_sections/</directory>
+
+.. _library_element:
+
+---------------------
+``<library>`` Element
+---------------------
+
+The ``<library>`` element indicates where an HDF5 cross section file is located,
+whether it contains incident neutron or thermal scattering data, and what
+materials are listed within. It has the following attributes:
+
+  :materials:
+
+    A space-separated list of nuclides or thermal scattering tables. For
+    example,
+
+    .. code-block:: xml
+
+       <library materials="U234 U235 U238" />
+       <library materials="c_H_in_H2O c_D_in_G2O" />
+
+    Often, just a single nuclide or thermal scattering table is contained in a
+    given file.
+
+  :path:
+    Path to the HDF5 file. If the :ref:`directory_element` is specified, the
+    path is relative to the directory given. Otherwise, it is relative to the
+    directory containing the ``cross_sections.xml`` file.
+
+  :type:
+    The type of data contained in the file, either 'neutron' or 'thermal'.

docs/source/io_formats/geometry.rst

@@ -0,0 +1,365 @@
+.. _io_geometry:
+
+======================================
+Geometry Specification -- geometry.xml
+======================================
+
+.. _surface_element:
+
+---------------------
+``<surface>`` Element
+---------------------
+
+Each ``<surface>`` element can have the following attributes or sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the surface.
+
+    *Default*: None
+
+  :name:
+    An optional string name to identify the surface in summary output
+    files. This string is limited to 52 characters for formatting purposes.
+
+    *Default*: ""
+
+  :type:
+    The type of the surfaces. This can be "x-plane", "y-plane", "z-plane",
+    "plane", "x-cylinder", "y-cylinder", "z-cylinder", "sphere", "x-cone",
+    "y-cone", "z-cone", or "quadric".
+
+    *Default*: None
+
+  :coeffs:
+    The corresponding coefficients for the given type of surface. See below for
+    a list a what coefficients to specify for a given surface
+
+    *Default*: None
+
+  :boundary:
+     The boundary condition for the surface. This can be "transmission",
+     "vacuum", "reflective", or "periodic". Periodic boundary conditions can
+     only be applied to x-, y-, and z-planes. Only axis-aligned periodicity is
+     supported, i.e., x-planes can only be paired with x-planes. Specify which
+     planes are periodic and the code will automatically identify which planes
+     are paired together.
+
+    *Default*: "transmission"
+
+  :periodic_surface_id:
+     If a periodic boundary condition is applied, this attribute identifies the
+     ``id`` of the corresponding periodic sufrace.
+
+The following quadratic surfaces can be modeled:
+
+  :x-plane:
+    A plane perpendicular to the x axis, i.e. a surface of the form :math:`x -
+    x_0 = 0`. The coefficients specified are ":math:`x_0`".
+
+  :y-plane:
+    A plane perpendicular to the y axis, i.e. a surface of the form :math:`y -
+    y_0 = 0`. The coefficients specified are ":math:`y_0`".
+
+  :z-plane:
+    A plane perpendicular to the z axis, i.e. a surface of the form :math:`z -
+    z_0 = 0`. The coefficients specified are ":math:`z_0`".
+
+  :plane:
+    An arbitrary plane of the form :math:`Ax + By + Cz = D`. The coefficients
+    specified are ":math:`A \: B \: C \: D`".
+
+  :x-cylinder:
+    An infinite cylinder whose length is parallel to the x-axis. This is a
+    quadratic surface of the form :math:`(y - y_0)^2 + (z - z_0)^2 = R^2`. The
+    coefficients specified are ":math:`y_0 \: z_0 \: R`".
+
+  :y-cylinder:
+    An infinite cylinder whose length is parallel to the y-axis. This is a
+    quadratic surface of the form :math:`(x - x_0)^2 + (z - z_0)^2 = R^2`. The
+    coefficients specified are ":math:`x_0 \: z_0 \: R`".
+
+  :z-cylinder:
+    An infinite cylinder whose length is parallel to the z-axis. This is a
+    quadratic surface of the form :math:`(x - x_0)^2 + (y - y_0)^2 = R^2`. The
+    coefficients specified are ":math:`x_0 \: y_0 \: R`".
+
+  :sphere:
+    A sphere of the form :math:`(x - x_0)^2 + (y - y_0)^2 + (z - z_0)^2 =
+    R^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0 \: R`".
+
+  :x-cone:
+    A cone parallel to the x-axis of the form :math:`(y - y_0)^2 + (z - z_0)^2 =
+    R^2 (x - x_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0
+    \: R^2`".
+
+  :y-cone:
+    A cone parallel to the y-axis of the form :math:`(x - x_0)^2 + (z - z_0)^2 =
+    R^2 (y - y_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0
+    \: R^2`".
+
+  :z-cone:
+    A cone parallel to the x-axis of the form :math:`(x - x_0)^2 + (y - y_0)^2 =
+    R^2 (z - z_0)^2`. The coefficients specified are ":math:`x_0 \: y_0 \: z_0
+    \: R^2`".
+
+  :quadric:
+     A general quadric surface of the form :math:`Ax^2 + By^2 + Cz^2 + Dxy +
+     Eyz + Fxz + Gx + Hy + Jz + K = 0` The coefficients specified are ":math:`A
+     \: B \: C \: D \: E \: F \: G \: H \: J \: K`".
+
+.. _cell_element:
+
+------------------
+``<cell>`` Element
+------------------
+
+Each ``<cell>`` element can have the following attributes or sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the cell.
+
+    *Default*: None
+
+  :name:
+    An optional string name to identify the cell in summary output files.
+    This string is limmited to 52 characters for formatting purposes.
+
+    *Default*: ""
+
+  :universe:
+    The ``id`` of the universe that this cell is contained in.
+
+    *Default*: 0
+
+  :fill:
+    The ``id`` of the universe that fills this cell.
+
+    .. note:: If a fill is specified, no material should be given.
+
+    *Default*: None
+
+  :material:
+    The ``id`` of the material that this cell contains. If the cell should
+    contain no material, this can also be set to "void". A list of materials
+    can be specified for the "distributed material" feature. This will give each
+    unique instance of the cell its own material.
+
+    .. note:: If a material is specified, no fill should be given.
+
+    *Default*: None
+
+  :region:
+    A Boolean expression of half-spaces that defines the spatial region which
+    the cell occupies. Each half-space is identified by the unique ID of the
+    surface prefixed by `-` or `+` to indicate that it is the negative or
+    positive half-space, respectively. The `+` sign for a positive half-space
+    can be omitted. Valid Boolean operators are parentheses, union `|`,
+    complement `~`, and intersection. Intersection is implicit and indicated by
+    the presence of whitespace. The order of operator precedence is parentheses,
+    complement, intersection, and then union.
+
+    As an example, the following code gives a cell that is the union of the
+    negative half-space of surface 3 and the complement of the intersection of
+    the positive half-space of surface 5 and the negative half-space of surface
+    2:
+
+    .. code-block:: xml
+
+        <cell id="1" material="1" region="-3 | ~(5 -2)" />
+
+    .. note:: The ``region`` attribute/element can be omitted to make a cell
+              fill its entire universe.
+
+    *Default*: A region filling all space.
+
+  :temperature:
+    The temperature of the cell in Kelvin. If windowed-multipole data is
+    avalable, this temperature will be used to Doppler broaden some cross
+    sections in the resolved resonance region. A list of temperatures can be
+    specified for the "distributed temperature" feature. This will give each
+    unique instance of the cell its own temperature.
+
+    *Default*: If a material default temperature is supplied, it is used. In the
+    absence of a material default temperature, the :ref:`global default
+    temperature <temperature_default>` is used.
+
+  :rotation:
+    If the cell is filled with a universe, this element specifies the angles in
+    degrees about the x, y, and z axes that the filled universe should be
+    rotated. Should be given as three real numbers. For example, if you wanted
+    to rotate the filled universe by 90 degrees about the z-axis, the cell
+    element would look something like:
+
+    .. code-block:: xml
+
+        <cell fill="..." rotation="0 0 90" />
+
+    The rotation applied is an intrinsic rotation whose Tait-Bryan angles are
+    given as those specified about the x, y, and z axes respectively. That is to
+    say, if the angles are :math:`(\phi, \theta, \psi)`, then the rotation
+    matrix applied is :math:`R_z(\psi) R_y(\theta) R_x(\phi)` or
+
+    .. math::
+
+       \left [ \begin{array}{ccc} \cos\theta \cos\psi & -\cos\theta \sin\psi +
+       \sin\phi \sin\theta \cos\psi & \sin\phi \sin\psi + \cos\phi \sin\theta
+       \cos\psi \\ \cos\theta \sin\psi & \cos\phi \cos\psi + \sin\phi \sin\theta
+       \sin\psi & -\sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\
+       -\sin\theta & \sin\phi \cos\theta & \cos\phi \cos\theta \end{array}
+       \right ]
+
+    *Default*: None
+
+  :translation:
+    If the cell is filled with a universe, this element specifies a vector that
+    is used to translate (shift) the universe. Should be given as three real
+    numbers.
+
+    .. note:: Any translation operation is applied after a rotation, if also
+              specified.
+
+    *Default*: None
+
+
+---------------------
+``<lattice>`` Element
+---------------------
+
+The ``<lattice>`` can be used to represent repeating structures (e.g. fuel pins
+in an assembly) or other geometry which fits onto a rectilinear grid. Each cell
+within the lattice is filled with a specified universe. A ``<lattice>`` accepts
+the following attributes or sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the lattice.
+
+  :name:
+    An optional string name to identify the lattice in summary output
+    files. This string is limited to 52 characters for formatting purposes.
+
+    *Default*: ""
+
+  :dimension:
+    Two or three integers representing the number of lattice cells in the x- and
+    y- (and z-) directions, respectively.
+
+    *Default*: None
+
+  :lower_left:
+    The coordinates of the lower-left corner of the lattice. If the lattice is
+    two-dimensional, only the x- and y-coordinates are specified.
+
+    *Default*: None
+
+  :pitch:
+    If the lattice is 3D, then three real numbers that express the distance
+    between the centers of lattice cells in the x-, y-, and z- directions.  If
+    the lattice is 2D, then omit the third value.
+
+    *Default*: None
+
+  :outer:
+    The unique integer identifier of a universe that will be used to fill all
+    space outside of the lattice.  The universe will be tiled repeatedly as if
+    it were placed in a lattice of infinite size.  This element is optional.
+
+    *Default*: An error will be raised if a particle leaves a lattice with no
+    outer universe.
+
+  :universes:
+    A list of the universe numbers that fill each cell of the lattice.
+
+    *Default*: None
+
+Here is an example of a properly defined 2d rectangular lattice:
+
+.. code-block:: xml
+
+    <lattice id="10" dimension="3 3" outer="1">
+        <lower_left> -1.5 -1.5 </lower_left>
+        <pitch> 1.0 1.0 </pitch>
+        <universes>
+          2 2 2
+          2 1 2
+          2 2 2
+        </universes>
+    </lattice>
+
+-------------------------
+``<hex_lattice>`` Element
+-------------------------
+
+The ``<hex_lattice>`` can be used to represent repeating structures (e.g. fuel
+pins in an assembly) or other geometry which naturally fits onto a hexagonal
+grid or hexagonal prism grid. Each cell within the lattice is filled with a
+specified universe. This lattice uses the "flat-topped hexagon" scheme where two
+of the six edges are perpendicular to the y-axis.  A ``<hex_lattice>`` accepts
+the following attributes or sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the lattice.
+
+  :name:
+    An optional string name to identify the hex_lattice in summary output
+    files. This string is limited to 52 characters for formatting purposes.
+
+    *Default*: ""
+
+  :n_rings:
+    An integer representing the number of radial ring positions in the xy-plane.
+    Note that this number includes the degenerate center ring which only has one
+    element.
+
+    *Default*: None
+
+  :n_axial:
+    An integer representing the number of positions along the z-axis.  This
+    element is optional.
+
+    *Default*: None
+
+  :center:
+    The coordinates of the center of the lattice. If the lattice does not have
+    axial sections then only the x- and y-coordinates are specified.
+
+    *Default*: None
+
+  :pitch:
+    If the lattice is 3D, then two real numbers that express the distance
+    between the centers of lattice cells in the xy-plane and along the z-axis,
+    respectively.  If the lattice is 2D, then omit the second value.
+
+    *Default*: None
+
+  :outer:
+    The unique integer identifier of a universe that will be used to fill all
+    space outside of the lattice.  The universe will be tiled repeatedly as if
+    it were placed in a lattice of infinite size.  This element is optional.
+
+    *Default*: An error will be raised if a particle leaves a lattice with no
+    outer universe.
+
+  :universes:
+    A list of the universe numbers that fill each cell of the lattice.
+
+    *Default*: None
+
+Here is an example of a properly defined 2d hexagonal lattice:
+
+.. code-block:: xml
+
+    <hex_lattice id="10" n_rings="3" outer="1">
+        <center> 0.0 0.0 </center>
+        <pitch> 1.0 </pitch>
+        <universes>
+                  202
+               202   202
+            202   202   202
+               202   202
+            202   101   202
+               202   202
+            202   202   202
+               202   202
+                  202
+        </universes>
+    </hex_lattice>

docs/source/io_formats/index.rst

@@ -4,6 +4,23 @@
 File Format Specifications
 ==========================
 
+.. _io_file_formats_input:
+
+-----------
+Input Files
+-----------
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   geometry
+   materials
+   settings
+   tallies
+   plots
+   cmfd
+
 ----------
 Data Files
 ----------
@@ -12,6 +29,7 @@ Data Files
    :numbered:
    :maxdepth: 2
 
+   cross_sections
    nuclear_data
    mgxs_library
    data_wmp

docs/source/io_formats/materials.rst

@@ -0,0 +1,133 @@
+.. _io_materials:
+
+========================================
+Materials Specification -- materials.xml
+========================================
+
+.. _cross_sections:
+
+----------------------------
+``<cross_sections>`` Element
+----------------------------
+
+The ``<cross_sections>`` element has no attributes and simply indicates the path
+to an XML cross section listing file (usually named cross_sections.xml). If this
+element is absent from the settings.xml file, the
+:envvar:`OPENMC_CROSS_SECTIONS` environment variable will be used to find the
+path to the XML cross section listing when in continuous-energy mode, and the
+:envvar:`OPENMC_MG_CROSS_SECTIONS` environment variable will be used in
+multi-group mode.
+
+.. _multipole_library:
+
+-------------------------------
+``<multipole_library>`` Element
+-------------------------------
+
+The ``<multipole_library>`` element indicates the directory containing a
+windowed multipole library. If a windowed multipole library is available,
+OpenMC can use it for on-the-fly Doppler-broadening of resolved resonance range
+cross sections. If this element is absent from the settings.xml file, the
+:envvar:`OPENMC_MULTIPOLE_LIBRARY` environment variable will be used.
+
+  .. note:: The <temperature_multipole> element must also be set to "true" for
+    windowed multipole functionality.
+
+.. _material:
+
+----------------------
+``<material>`` Element
+----------------------
+
+Each ``material`` element can have the following attributes or sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the material.
+
+  :name:
+    An optional string name to identify the material in summary output
+    files. This string is limited to 52 characters for formatting purposes.
+
+    *Default*: ""
+
+  :temperature:
+    An element with no attributes which is used to set the default temperature
+    of the material in Kelvin.
+
+    *Default*: If a material default temperature is not given and a cell
+    temperature is not specified, the :ref:`global default temperature
+    <temperature_default>` is used.
+
+  :density:
+    An element with attributes/sub-elements called ``value`` and ``units``. The
+    ``value`` attribute is the numeric value of the density while the ``units``
+    can be "g/cm3", "kg/m3", "atom/b-cm", "atom/cm3", or "sum". The "sum" unit
+    indicates that values appearing in ``ao`` or ``wo`` attributes for ``<nuclide>``
+    and ``<element>`` sub-elements are to be interpreted as absolute nuclide/element
+    densities in atom/b-cm or g/cm3, and the total density of the material is
+    taken as the sum of all nuclides/elements. The "macro" unit is used with
+    a ``macroscopic`` quantity to indicate that the density is already included
+    in the library and thus not needed here.  However, if a value is provided
+    for the ``value``, then this is treated as a number density multiplier on
+    the macroscopic cross sections in the multi-group data.  This can be used,
+    for example, when perturbing the density slightly.
+
+    *Default*: None
+
+    .. note:: A ``macroscopic`` quantity can not be used in conjunction with a
+              ``nuclide``, ``element``, or ``sab`` quantity.
+
+  :nuclide:
+    An element with attributes/sub-elements called ``name``, and ``ao``
+    or ``wo``. The ``name`` attribute is the name of the cross-section for a
+    desired nuclide. Finally, the ``ao`` and ``wo`` attributes specify the atom or
+    weight percent of that nuclide within the material, respectively. One
+    example would be as follows:
+
+    .. code-block:: xml
+
+        <nuclide name="H1" ao="2.0" />
+        <nuclide name="O16" ao="1.0" />
+
+    .. note:: If one nuclide is specified in atom percent, all others must also
+              be given in atom percent. The same applies for weight percentages.
+
+    An optional attribute/sub-element for each nuclide is ``scattering``. This
+    attribute may be set to "data" to use the scattering laws specified by the
+    cross section library (default). Alternatively, when set to "iso-in-lab",
+    the scattering laws are used to sample the outgoing energy but an
+    isotropic-in-lab  distribution is used to sample the outgoing angle at each
+    scattering interaction. The ``scattering`` attribute may be most useful
+    when using OpenMC to compute multi-group cross-sections for deterministic
+    transport codes and to quantify the effects of anisotropic scattering.
+
+    *Default*: None
+
+    .. note:: The ``scattering`` attribute/sub-element is not used in the
+              multi-group :ref:`energy_mode`.
+
+  :sab:
+    Associates an S(a,b) table with the material. This element has one
+    attribute/sub-element called ``name``. The ``name`` attribute
+    is the name of the S(a,b) table that should be associated with the material.
+
+    *Default*: None
+
+    .. note:: This element is not used in the multi-group :ref:`energy_mode`.
+
+  :macroscopic:
+    The ``macroscopic`` element is similar to the ``nuclide`` element, but,
+    recognizes that some multi-group libraries may be providing material
+    specific macroscopic cross sections instead of always providing nuclide
+    specific data like in the continuous-energy case.  To that end, the
+    macroscopic element has one attribute/sub-element called ``name``.
+    The ``name`` attribute is the name of the cross-section for a
+    desired nuclide. One example would be as follows:
+
+    .. code-block:: xml
+
+        <macroscopic name="UO2" />
+
+    .. note:: This element is only used in the multi-group :ref:`energy_mode`.
+
+    *Default*: None

docs/source/io_formats/plots.rst

@@ -0,0 +1,192 @@
+.. _io_plots:
+
+============================================
+Geometry Plotting Specification -- plots.xml
+============================================
+
+Basic plotting capabilities are available in OpenMC by creating a plots.xml file
+and subsequently running with the ``--plot`` command-line flag. The root element
+of the plots.xml is simply ``<plots>`` and any number output plots can be
+defined with ``<plot>`` sub-elements.  Two plot types are currently implemented
+in openMC:
+
+* ``slice``  2D pixel plot along one of the major axes. Produces a PPM image
+  file.
+* ``voxel``  3D voxel data dump. Produces a binary file containing voxel xyz
+  position and cell or material id.
+
+
+------------------
+``<plot>`` Element
+------------------
+
+Each plot is specified by a combination of the following attributes or
+sub-elements:
+
+  :id:
+    The unique ``id`` of the plot.
+
+    *Default*: None - Required entry
+
+  :filename:
+    Filename for the output plot file.
+
+    *Default*: "plot"
+
+  :color_by:
+    Keyword for plot coloring.  This can be either "cell" or "material", which
+    colors regions by cells and materials, respectively. For voxel plots, this
+    determines which id (cell or material) is associated with each position.
+
+    *Default*: "cell"
+
+  :level:
+    Universe depth to plot at (optional).  This parameter controls how many
+    universe levels deep to pull cell and material ids from when setting plot
+    colors.  If a given location does not have as many levels as specified,
+    colors will be taken from the lowest level at that location. For example, if
+    ``level`` is set to zero colors will be taken from top-level (universe zero)
+    cells only.  However, if ``level`` is set to 1 colors will be taken from
+    cells in universes that fill top-level fill-cells, and from top-level cells
+    that contain materials.
+
+    *Default*: Whatever the deepest universe is in the model
+
+  :origin:
+    Specifies the (x,y,z) coordinate of the center of the plot.  Should be three
+    floats separated by spaces.
+
+    *Default*: None - Required entry
+
+  :width:
+    Specifies the width of the plot along each of the basis directions.  Should
+    be two or three floats separated by spaces for 2D plots and 3D plots,
+    respectively.
+
+    *Default*: None - Required entry
+
+  :type:
+    Keyword for type of plot to be produced. Currently only "slice" and "voxel"
+    plots are implemented. The "slice" plot type creates 2D pixel maps saved in
+    the PPM file format. PPM files can be displayed in most viewers (e.g. the
+    default Gnome viewer, IrfanView, etc.).  The "voxel" plot type produces a
+    binary datafile containing voxel grid positioning and the cell or material
+    (specified by the ``color`` tag) at the center of each voxel. These
+    datafiles can be processed into 3D SILO files using the :ref:`scripts_voxel`
+    script provided with OpenMC, and subsequently viewed with a 3D viewer such
+    as VISIT or Paraview. See the :ref:`io_voxel` for information about the
+    datafile structure.
+
+    .. note:: Since the PPM format is saved without any kind of compression,
+              the resulting file sizes can be quite large.  Saving the image in
+              the PNG format can often times reduce the file size by orders of
+              magnitude without any loss of image quality. Likewise,
+              high-resolution voxel files produced by OpenMC can be quite large,
+              but the equivalent SILO files will be significantly smaller.
+
+    *Default*: "slice"
+
+``<plot>`` elements of ``type`` "slice" and "voxel" must contain the ``pixels``
+attribute or sub-element:
+
+  :pixels:
+    Specifies the number of pixels or voxels to be used along each of the basis
+    directions for "slice" and "voxel" plots, respectively. Should be two or
+    three integers separated by spaces.
+
+    .. warning:: The ``pixels`` input determines the output file size.  For the
+                 PPM format, 10 million pixels will result in a file just under
+                 30 MB in size. A 10 million voxel binary file will be around
+                 40 MB.
+
+    .. warning:: If the aspect ratio defined in ``pixels`` does not match the
+                 aspect ratio defined in ``width`` the plot may appear stretched
+                 or squeezed.
+
+    .. warning:: Geometry features along a basis direction smaller than
+                 ``width``/``pixels`` along that basis direction may not appear
+                 in the plot.
+
+    *Default*: None - Required entry for "slice" and "voxel" plots
+
+``<plot>`` elements of ``type`` "slice" can also contain the following
+attributes or sub-elements.  These are not used in "voxel" plots:
+
+  :basis:
+    Keyword specifying the plane of the plot for "slice" type plots.  Can be
+    one of: "xy", "xz", "yz".
+
+    *Default*: "xy"
+
+  :background:
+    Specifies the RGB color of the regions where no OpenMC cell can be found.
+    Should be three integers separated by spaces.
+
+    *Default*: 0 0 0 (black)
+
+  :color:
+    Any number of this optional tag may be included in each ``<plot>`` element,
+    which can override the default random colors for cells or materials. Each
+    ``color`` element must contain ``id`` and ``rgb`` sub-elements.
+
+    :id:
+      Specifies the cell or material unique id for the color specification.
+
+    :rgb:
+      Specifies the custom color for the cell or material. Should be 3 integers
+      separated by spaces.
+
+    As an example, if your plot is colored by material and you want material 23
+    to be blue, the corresponding ``color`` element would look like:
+
+    .. code-block:: xml
+
+        <color id="23" rgb="0 0 255" />
+
+    *Default*: None
+
+  :mask:
+    The special ``mask`` sub-element allows for the selective plotting of *only*
+    user-specified cells or materials. Only one ``mask`` element is allowed per
+    ``plot`` element, and it must contain as attributes or sub-elements a
+    background masking color and a list of cells or materials to plot:
+
+    :components:
+      List of unique ``id`` numbers of the cells or materials to plot. Should be
+      any number of integers separated by spaces.
+
+    :background:
+      Color to apply to all cells or materials not in the ``components`` list of
+      cells or materials to plot. This overrides any ``color`` color
+      specifications.
+
+    *Default*: 255 255 255 (white)
+
+  :meshlines:
+    The ``meshlines`` sub-element allows for plotting the boundaries of a
+    regular mesh on top of a plot. Only one ``meshlines`` element is allowed per
+    ``plot`` element, and it must contain as attributes or sub-elements a mesh
+    type and a linewidth.  Optionally, a color may be specified for the overlay:
+
+    :meshtype:
+      The type of the mesh to be plotted. Valid options are "tally", "entropy",
+      "ufs", and "cmfd".  If plotting "tally" meshes, the id of the mesh to plot
+      must be specified with the ``id`` sub-element.
+
+    :id:
+      A single integer id number for the mesh specified on ``tallies.xml`` that
+      should be plotted. This element is only required for ``meshtype="tally"``.
+
+    :linewidth:
+      A single integer number of pixels of linewidth to specify for the mesh
+      boundaries. Specifying this as 0 indicates that lines will be 1 pixel
+      thick, specifying 1 indicates 3 pixels thick, specifying 2 indicates
+      5 pixels thick, etc.
+
+    :color:
+      Specifies the custom color for the meshlines boundaries. Should be 3
+      integers separated by whitespace.  This element is optional.
+
+      *Default*: 0 0 0 (black)
+
+    *Default*: None

docs/source/io_formats/settings.rst

@@ -0,0 +1,847 @@
+.. _io_settings:
+
+======================================
+Settings Specification -- settings.xml
+======================================
+
+All simulation parameters and miscellaneous options are specified in the
+settings.xml file.
+
+---------------------
+``<batches>`` Element
+---------------------
+
+The ``<batches>`` element indicates the total number of batches to execute,
+where each batch corresponds to a tally realization. In a fixed source
+calculation, each batch consists of a number of source particles. In an
+eigenvalue calculation, each batch consists of one or many fission source
+iterations (generations), where each generation itself consists of a number of
+source neutrons.
+
+  *Default*: None
+
+----------------------------------
+``<confidence_intervals>`` Element
+----------------------------------
+
+The ``<confidence_intervals>`` element has no attributes and has an accepted
+value of "true" or "false". If set to "true", uncertainties on tally results
+will be reported as the half-width of the 95% two-sided confidence interval. If
+set to "false", uncertainties on tally results will be reported as the sample
+standard deviation.
+
+  *Default*: false
+
+--------------------
+``<cutoff>`` Element
+--------------------
+
+The ``<cutoff>`` element indicates two kinds of cutoffs. The first is the weight
+cutoff used below which particles undergo Russian roulette. Surviving particles
+are assigned a user-determined weight. Note that weight cutoffs and Russian
+rouletting are not turned on by default. The second is the energy cutoff which
+is used to kill particles under certain energy. The energy cutoff should not be
+used unless you know particles under the energy are of no importance to results
+you care. This element has the following attributes/sub-elements:
+
+  :weight:
+    The weight below which particles undergo Russian roulette.
+
+    *Default*: 0.25
+
+  :weight_avg:
+    The weight that is assigned to particles that are not killed after Russian
+    roulette.
+
+    *Default*: 1.0
+
+  :energy:
+    The energy under which particles will be killed.
+
+    *Default*: 0.0
+
+-------------------------
+``<energy_grid>`` Element
+-------------------------
+
+The ``<energy_grid>`` element determines the treatment of the energy grid during
+a simulation. The valid options are "nuclide", "logarithm", and
+"material-union". Setting this element to "nuclide" will cause OpenMC to use a
+nuclide's energy grid when determining what points to interpolate between for
+determining cross sections (i.e. non-unionized energy grid). Setting this
+element to "logarithm" causes OpenMC to use a logarithmic mapping technique
+described in LA-UR-14-24530_. Setting this element to "material-union" will
+cause OpenMC to create energy grids that are unionized material-by-material and
+use these grids when determining the energy-cross section pairs to interpolate
+cross section values between.
+
+  *Default*: logarithm
+
+  .. note:: This element is not used in the multi-group :ref:`energy_mode`.
+
+.. _LA-UR-14-24530: https://laws.lanl.gov/vhosts/mcnp.lanl.gov/pdf_files/la-ur-14-24530.pdf
+
+.. _energy_mode:
+
+-------------------------
+``<energy_mode>`` Element
+-------------------------
+
+The ``<energy_mode>`` element tells OpenMC if the run-mode should be
+continuous-energy or multi-group.  Options for entry are: ``continuous-energy``
+or ``multi-group``.
+
+  *Default*: continuous-energy
+
+---------------------
+``<entropy>`` Element
+---------------------
+
+The ``<entropy>`` element describes a mesh that is used for calculating Shannon
+entropy. This mesh should cover all possible fissionable materials in the
+problem. It has the following attributes/sub-elements:
+
+  :dimension:
+    The number of mesh cells in the x, y, and z directions, respectively.
+
+    *Default*: If this tag is not present, the number of mesh cells is
+     automatically determined by the code.
+
+  :lower_left:
+    The Cartesian coordinates of the lower-left corner of the mesh.
+
+    *Default*: None
+
+  :upper_right:
+    The Cartesian coordinates of the upper-right corner of the mesh.
+
+    *Default*: None
+
+-----------------------------------
+``<generations_per_batch>`` Element
+-----------------------------------
+
+The ``<generations_per_batch>`` element indicates the number of total fission
+source iterations per batch for an eigenvalue calculation. This element is
+ignored for all run modes other than "eigenvalue".
+
+  *Default*: 1
+
+----------------------
+``<inactive>`` Element
+----------------------
+
+The ``<inactive>`` element indicates the number of inactive batches used in a
+k-eigenvalue calculation. In general, the starting fission source iterations in
+an eigenvalue calculation can not be used to contribute to tallies since the
+fission source distribution and eigenvalue are generally not converged
+immediately. This element is ignored for all run modes other than "eigenvalue".
+
+  *Default*: 0
+
+--------------------------
+``<keff_trigger>`` Element
+--------------------------
+
+The ``<keff_trigger>`` element (ignored for all run modes other than
+"eigenvalue".) specifies a precision trigger on the combined
+:math:`k_{eff}`. The trigger is a convergence criterion on the uncertainty of
+the estimated eigenvalue. It has the following attributes/sub-elements:
+
+  :type:
+    The type of precision trigger. Accepted options are "variance", "std_dev",
+    and "rel_err".
+
+    :variance:
+      Variance of the batch mean :math:`\sigma^2`
+
+    :std_dev:
+      Standard deviation of the batch mean :math:`\sigma`
+
+    :rel_err:
+      Relative error of the batch mean :math:`\frac{\sigma}{\mu}`
+
+    *Default*: None
+
+  :threshold:
+    The precision trigger's convergence criterion for the
+    combined :math:`k_{eff}`.
+
+    *Default*: None
+
+.. note:: See section on the :ref:`trigger` for more information.
+
+
+---------------------------
+``<log_grid_bins>`` Element
+---------------------------
+
+The ``<log_grid_bins>`` element indicates the number of bins to use for the
+logarithmic-mapped energy grid. Using more bins will result in energy grid
+searches over a smaller range at the expense of more memory. The default is
+based on the recommended value in LA-UR-14-24530_.
+
+  *Default*: 8000
+
+  .. note:: This element is not used in the multi-group :ref:`energy_mode`.
+
+---------------------------
+``<max_order>`` Element
+---------------------------
+
+The ``<max_order>`` element allows the user to set a maximum scattering order
+to apply to every nuclide/material in the problem.  That is, if the data
+library has :math:`P_3` data available, but ``<max_order>`` was set to ``1``,
+then, OpenMC will only use up to the :math:`P_1` data.
+
+  *Default*: Use the maximum order in the data library
+
+  .. note:: This element is not used in the continuous-energy
+    :ref:`energy_mode`.
+
+-----------------------
+``<no_reduce>`` Element
+-----------------------
+
+The ``<no_reduce>`` element has no attributes and has an accepted value of
+"true" or "false". If set to "true", all user-defined tallies and global tallies
+will not be reduced across processors in a parallel calculation. This means that
+the accumulate score in one batch on a single processor is considered as an
+independent realization for the tally random variable. For a problem with large
+tally data, this option can significantly improve the parallel efficiency.
+
+  *Default*: false
+
+--------------------
+``<output>`` Element
+--------------------
+
+The ``<output>`` element determines what output files should be written to disk
+during the run. The sub-elements are described below, where "true" will write
+out the file and "false" will not.
+
+  :summary:
+    Writes out an HDF5 summary file describing all of the user input files that
+    were read in.
+
+    *Default*: true
+
+  :tallies:
+    Write out an ASCII file of tally results.
+
+    *Default*: true
+
+  .. note:: The tally results will always be written to a binary/HDF5 state
+            point file.
+
+  :path:
+    Absolute or relative path where all output files should be written to. The
+    specified path must exist or else OpenMC will abort.
+
+    *Default*: Current working directory
+
+-----------------------
+``<particles>`` Element
+-----------------------
+
+This element indicates the number of neutrons to simulate per fission source
+iteration when a k-eigenvalue calculation is performed or the number of neutrons
+per batch for a fixed source simulation.
+
+  *Default*: None
+
+---------------------
+``<ptables>`` Element
+---------------------
+
+The ``<ptables>`` element determines whether probability tables should be used
+in the unresolved resonance range if available. This element has no attributes
+or sub-elements and can be set to either "false" or "true".
+
+  *Default*: true
+
+  .. note:: This element is not used in the multi-group :ref:`energy_mode`.
+
+----------------------------------
+``<resonance_scattering>`` Element
+----------------------------------
+
+The ``resonance_scattering`` element indicates to OpenMC that a method be used
+to properly account for resonance elastic scattering (typically for nuclides
+with Z > 40). This element can contain one or more of the following attributes
+or sub-elements:
+
+  :enable:
+    Indicates whether a resonance elastic scattering method should be turned
+    on. Accepts values of "true" or "false".
+
+    *Default*: If the ``<resonance_scattering>`` element is present, "true".
+
+  :method:
+
+    Which resonance elastic scattering method is to be applied: "ares"
+    (accelerated resonance elastic scattering), "dbrc" (Doppler broadening
+    rejection correction), or "wcm" (weight correction method). Descriptions of
+    each of these methods are documented here_.
+
+    .. _here: http://dx.doi.org/10.1016/j.anucene.2014.01.017
+
+    *Default*: "ares"
+
+  :energy_min:
+    The energy in eV above which the resonance elastic scattering method should
+    be applied.
+
+    *Default*: 0.01 eV
+
+  :energy_max:
+    The energy in eV below which the resonance elastic scattering method should
+    be applied.
+
+    *Default*: 1000.0 eV
+
+  :nuclides:
+
+    A list of nuclides to which the resonance elastic scattering method should
+    be applied.
+
+    *Default*: If ``<resonance_scattering>`` is present but the ``<nuclides>``
+    sub-element is not given, the method is applied to all nuclides with 0 K
+    elastic scattering data present.
+
+  .. note:: If the ``resonance_scattering`` element is not given, the free gas,
+            constant cross section scattering model, which has historically been
+            used by Monte Carlo codes to sample target velocities, is used to
+            treat the target motion of all nuclides.  If
+            ``resonance_scattering`` is present, the constant cross section
+            method is applied below ``energy_min`` and the target-at-rest
+            (asymptotic) kernel is used above ``energy_max``.
+
+  .. note:: This element is not used in the multi-group :ref:`energy_mode`.
+
+----------------------
+``<run_cmfd>`` Element
+----------------------
+
+The ``<run_cmfd>`` element indicates whether or not CMFD acceleration should be
+turned on or off. This element has no attributes or sub-elements and can be set
+to either "false" or "true".
+
+  *Default*: false
+
+----------------------
+``<run_mode>`` Element
+----------------------
+
+The ``<run_mode>`` element indicates which run mode should be used when OpenMC
+is executed. This element has no attributes or sub-elements and can be set to
+"eigenvalue", "fixed source", "plot", "volume", or "particle restart".
+
+  *Default*: None
+
+------------------
+``<seed>`` Element
+------------------
+
+The ``seed`` element is used to set the seed used for the linear congruential
+pseudo-random number generator.
+
+  *Default*: 1
+
+--------------------
+``<source>`` Element
+--------------------
+
+The ``source`` element gives information on an external source distribution to
+be used either as the source for a fixed source calculation or the initial
+source guess for criticality calculations. Multiple ``<source>`` elements may be
+specified to define different source distributions. Each one takes the following
+attributes/sub-elements:
+
+  :strength:
+    The strength of the source. If multiple sources are present, the source
+    strength indicates the relative probability of choosing one source over the
+    other.
+
+    *Default*: 1.0
+
+  :file:
+    If this attribute is given, it indicates that the source is to be read from
+    a binary source file whose path is given by the value of this element. Note,
+    the number of source sites needs to be the same as the number of particles
+    simulated in a fission source generation.
+
+    *Default*: None
+
+  :space:
+    An element specifying the spatial distribution of source sites. This element
+    has the following attributes:
+
+    :type:
+      The type of spatial distribution. Valid options are "box", "fission",
+      "point", and "cartesian". A "box" spatial distribution has coordinates
+      sampled uniformly in a parallelepiped. A "fission" spatial distribution
+      samples locations from a "box" distribution but only locations in
+      fissionable materials are accepted. A "point" spatial distribution has
+      coordinates specified by a triplet. An "cartesian" spatial distribution
+      specifies independent distributions of x-, y-, and z-coordinates.
+
+      *Default*: None
+
+    :parameters:
+      For a "box" or "fission" spatial distribution, ``parameters`` should be
+      given as six real numbers, the first three of which specify the lower-left
+      corner of a parallelepiped and the last three of which specify the
+      upper-right corner. Source sites are sampled uniformly through that
+      parallelepiped.
+
+      For a "point" spatial distribution, ``parameters`` should be given as
+      three real numbers which specify the (x,y,z) location of an isotropic
+      point source.
+
+      For an "cartesian" distribution, no parameters are specified. Instead,
+      the ``x``, ``y``, and ``z`` elements must be specified.
+
+      *Default*: None
+
+    :x:
+      For an "cartesian" distribution, this element specifies the distribution
+      of x-coordinates. The necessary sub-elements/attributes are those of a
+      univariate probability distribution (see the description in
+      :ref:`univariate`).
+
+    :y:
+      For an "cartesian" distribution, this element specifies the distribution
+      of y-coordinates. The necessary sub-elements/attributes are those of a
+      univariate probability distribution (see the description in
+      :ref:`univariate`).
+
+    :z:
+      For an "cartesian" distribution, this element specifies the distribution
+      of z-coordinates. The necessary sub-elements/attributes are those of a
+      univariate probability distribution (see the description in
+      :ref:`univariate`).
+
+  :angle:
+    An element specifying the angular distribution of source sites. This element
+    has the following attributes:
+
+    :type:
+      The type of angular distribution. Valid options are "isotropic",
+      "monodirectional", and "mu-phi". The angle of the particle emitted from a
+      source site is isotropic if the "isotropic" option is given. The angle of
+      the particle emitted from a source site is the direction specified in the
+      ``reference_uvw`` element/attribute if "monodirectional" option is
+      given. The "mu-phi" option produces directions with the cosine of the
+      polar angle and the azimuthal angle explicitly specified.
+
+      *Default*: isotropic
+
+    :reference_uvw:
+      The direction from which the polar angle is measured. Represented by the
+      x-, y-, and z-components of a unit vector. For a monodirectional
+      distribution, this defines the direction of all sampled particles.
+
+    :mu:
+      An element specifying the distribution of the cosine of the polar
+      angle. Only relevant when the type is "mu-phi". The necessary
+      sub-elements/attributes are those of a univariate probability distribution
+      (see the description in :ref:`univariate`).
+
+    :phi:
+      An element specifying the distribution of the azimuthal angle. Only
+      relevant when the type is "mu-phi". The necessary sub-elements/attributes
+      are those of a univariate probability distribution (see the description in
+      :ref:`univariate`).
+
+  :energy:
+    An element specifying the energy distribution of source sites. The necessary
+    sub-elements/attributes are those of a univariate probability distribution
+    (see the description in :ref:`univariate`).
+
+    *Default*: Watt spectrum with :math:`a` = 0.988 MeV and :math:`b` =
+    2.249 MeV :sup:`-1`
+
+  :write_initial:
+    An element specifying whether to write out the initial source bank used at
+    the beginning of the first batch. The output file is named
+    "initial_source.h5"
+
+    *Default*: false
+
+.. _univariate:
+
+Univariate Probability Distributions
+++++++++++++++++++++++++++++++++++++
+
+Various components of a source distribution involve probability distributions of
+a single random variable, e.g. the distribution of the energy, the distribution
+of the polar angle, and the distribution of x-coordinates. Each of these
+components supports the same syntax with an element whose tag signifies the
+variable and whose sub-elements/attributes are as follows:
+
+:type:
+  The type of the distribution. Valid options are "uniform", "discrete",
+  "tabular", "maxwell", and "watt". The "uniform" option produces variates
+  sampled from a uniform distribution over a finite interval. The "discrete"
+  option produces random variates that can assume a finite number of values
+  (i.e., a distribution characterized by a probability mass function). The
+  "tabular" option produces random variates sampled from a tabulated
+  distribution where the density function is either a histogram or
+  linearly-interpolated between tabulated points. The "watt" option produces
+  random variates is sampled from a Watt fission spectrum (only used for
+  energies). The "maxwell" option produce variates sampled from a Maxwell
+  fission spectrum (only used for energies).
+
+  *Default*: None
+
+:parameters:
+  For a "uniform" distribution, ``parameters`` should be given as two real
+  numbers :math:`a` and :math:`b` that define the interval :math:`[a,b]` over
+  which random variates are sampled.
+
+  For a "discrete" or "tabular" distribution, ``parameters`` provides the
+  :math:`(x,p)` pairs defining the discrete/tabular distribution. All :math:`x`
+  points are given first followed by corresponding :math:`p` points.
+
+  For a "watt" distribution, ``parameters`` should be given as two real numbers
+  :math:`a` and :math:`b` that parameterize the distribution :math:`p(x) dx = c
+  e^{-x/a} \sinh \sqrt{b \, x} dx`.
+
+  For a "maxwell" distribution, ``parameters`` should be given as one real
+  number :math:`a` that parameterizes the distribution :math:`p(x) dx = c x
+  e^{-x/a} dx`.
+
+  .. note:: The above format should be used even when using the multi-group
+            :ref:`energy_mode`.
+:interpolation:
+  For a "tabular" distribution, ``interpolation`` can be set to "histogram" or
+  "linear-linear" thereby specifying how tabular points are to be interpolated.
+
+  *Default*: histogram
+
+-------------------------
+``<state_point>`` Element
+-------------------------
+
+The ``<state_point>`` element indicates at what batches a state point file
+should be written. A state point file can be used to restart a run or to get
+tally results at any batch. The default behavior when using this tag is to
+write out the source bank in the state_point file. This behavior can be
+customized by using the ``<source_point>`` element. This element has the
+following attributes/sub-elements:
+
+  :batches:
+    A list of integers separated by spaces indicating at what batches a state
+    point file should be written.
+
+    *Default*: Last batch only
+
+--------------------------
+``<source_point>`` Element
+--------------------------
+
+The ``<source_point>`` element indicates at what batches the source bank
+should be written. The source bank can be either written out within a state
+point file or separately in a source point file. This element has the following
+attributes/sub-elements:
+
+  :batches:
+    A list of integers separated by spaces indicating at what batches a state
+    point file should be written. It should be noted that if the ``separate``
+    attribute is not set to "true", this list must be a subset of state point
+    batches.
+
+    *Default*: Last batch only
+
+  :separate:
+    If this element is set to "true", a separate binary source point file will
+    be written. Otherwise, the source sites will be written in the state point
+    directly.
+
+    *Default*: false
+
+  :write:
+    If this element is set to "false", source sites are not written
+    to the state point or source point file. This can substantially reduce the
+    size of state points if large numbers of particles per batch are used.
+
+    *Default*: true
+
+  :overwrite_latest:
+    If this element is set to "true", a source point file containing
+    the source bank will be written out to a separate file named
+    ``source.binary`` or ``source.h5`` depending on if HDF5 is enabled.
+    This file will be overwritten at every single batch so that the latest
+    source bank will be available. It should be noted that a user can set both
+    this element to "true" and specify batches to write a permanent source bank.
+
+    *Default*: false
+
+------------------------------
+``<survival_biasing>`` Element
+------------------------------
+
+The ``<survival_biasing>`` element has no attributes and has an accepted value
+of "true" or "false". If set to "true", this option will enable the use of
+survival biasing, otherwise known as implicit capture or absorption.
+
+  *Default*: false
+
+.. _tabular_legendre:
+
+---------------------------------
+``<tabular_legendre>`` Element
+---------------------------------
+
+The optional ``<tabular_legendre>`` element specifies how the multi-group
+Legendre scattering kernel is represented if encountered in a multi-group
+problem.  Specifically, the options are to either convert the Legendre
+expansion to a tabular representation or leave it as a set of Legendre
+coefficients. Converting to a tabular representation will cost memory but can
+allow for a decrease in runtime compared to leaving as a set of Legendre
+coefficients. This element has the following attributes/sub-elements:
+
+  :enable:
+    This attribute/sub-element denotes whether or not the conversion of a
+    Legendre scattering expansion to the tabular format should be performed or
+    not. A value of “true” means the conversion should be performed, “false”
+    means it will not.
+
+    *Default*: true
+
+  :num_points:
+    If the conversion is to take place the number of tabular points is
+    required. This attribute/sub-element allows the user to set the desired
+    number of points.
+
+    *Default*: 33
+
+  .. note:: This element is only used in the multi-group :ref:`energy_mode`.
+
+.. _temperature_default:
+
+---------------------------------
+``<temperature_default>`` Element
+---------------------------------
+
+The ``<temperature_default>`` element specifies a default temperature in Kelvin
+that is to be applied to cells in the absence of an explicit cell temperature or
+a material default temperature.
+
+  *Default*: 293.6 K
+
+.. _temperature_method:
+
+--------------------------------
+``<temperature_method>`` Element
+--------------------------------
+
+The ``<temperature_method>`` element has an accepted value of "nearest" or
+"interpolation". A value of "nearest" indicates that for each
+cell, the nearest temperature at which cross sections are given is to be
+applied, within a given tolerance (see :ref:`temperature_tolerance`). A value of
+"interpolation" indicates that cross sections are to be linear-linear
+interpolated between temperatures at which nuclear data are present (see
+:ref:`temperature_treatment`).
+
+  *Default*: "nearest"
+
+.. _temperature_multipole:
+
+-----------------------------------
+``<temperature_multipole>`` Element
+-----------------------------------
+
+The ``<temperature_multipole>`` element toggles the windowed multipole
+capability on or off. If this element is set to "True" and the relevant data is
+available, OpenMC will use the windowed multipole method to evaluate and Doppler
+broaden cross sections in the resolved resonance range.  This override other
+methods like "nearest" and "interpolation" in the resolved resonance range.
+
+  *Default*: False
+
+.. _temperature_tolerance:
+
+-----------------------------------
+``<temperature_tolerance>`` Element
+-----------------------------------
+
+The ``<temperature_tolerance>`` element specifies a tolerance in Kelvin that is
+to be applied when the "nearest" temperature method is used. For example, if a
+cell temperature is 340 K and the tolerance is 15 K, then the closest
+temperature in the range of 325 K to 355 K will be used to evaluate cross
+sections.
+
+  *Default*: 10 K
+
+---------------------
+``<threads>`` Element
+---------------------
+
+The ``<threads>`` element indicates the number of OpenMP threads to be used for
+a simulation. It has no attributes and accepts a positive integer value.
+
+  *Default*: None (Determined by environment variable :envvar:`OMP_NUM_THREADS`)
+
+.. _trace:
+
+-------------------
+``<trace>`` Element
+-------------------
+
+The ``<trace>`` element can be used to print out detailed information about a
+single particle during a simulation. This element should be followed by three
+integers: the batch number, generation number, and particle number.
+
+  *Default*: None
+
+.. _track:
+
+-------------------
+``<track>`` Element
+-------------------
+
+The ``<track>`` element specifies particles for which OpenMC will output binary
+files describing particle position at every step of its transport. This element
+should be followed by triplets of integers.  Each triplet describes one
+particle. The integers in each triplet specify the batch number, generation
+number, and particle number, respectively.
+
+  *Default*: None
+
+.. _trigger:
+
+-------------------------
+``<trigger>`` Element
+-------------------------
+
+OpenMC includes tally precision triggers which allow the user to define
+uncertainty thresholds on :math:`k_{eff}` in the ``<keff_trigger>`` subelement
+of ``settings.xml``, and/or tallies in ``tallies.xml``. When using triggers,
+OpenMC will run until it completes as many batches as defined by ``<batches>``.
+At this point, the uncertainties on all tallied values are computed and compared
+with their corresponding trigger thresholds. If any triggers have not been met,
+OpenMC will continue until either all trigger thresholds have been satisfied or
+``<max_batches>`` has been reached.
+
+The ``<trigger>`` element provides an active "toggle switch" for tally
+precision trigger(s), the maximum number of batches and the batch interval. It
+has the following attributes/sub-elements:
+
+  :active:
+    This determines whether or not to use trigger(s). Trigger(s) are used when
+    this tag is set to "true".
+
+  :max_batches:
+    This describes the maximum number of batches allowed when using trigger(s).
+
+    .. note:: When max_batches is set, the number of ``batches`` shown in the
+              ``<batches>`` element represents minimum number of batches to
+              simulate when using the trigger(s).
+
+  :batch_interval:
+    This tag describes the number of  batches in between convergence checks.
+    OpenMC will check if the trigger has been reached at each batch defined
+    by ``batch_interval`` after the minimum number of batches is reached.
+
+    .. note:: If this tag is not present, the ``batch_interval`` is predicted
+              dynamically by OpenMC for each convergence check. The predictive
+              model assumes no correlation between fission sources
+              distributions from batch-to-batch. This assumption is reasonable
+              for fixed source and small criticality calculations, but is very
+              optimistic for highly coupled full-core reactor problems.
+
+
+------------------------
+``<uniform_fs>`` Element
+------------------------
+
+The ``<uniform_fs>`` element describes a mesh that is used for re-weighting
+source sites at every generation based on the uniform fission site methodology
+described in Kelly et al., "MC21 Analysis of the Nuclear Energy Agency Monte
+Carlo Performance Benchmark Problem," Proceedings of *Physor 2012*, Knoxville,
+TN (2012). This mesh should cover all possible fissionable materials in the
+problem. It has the following attributes/sub-elements:
+
+  :dimension:
+    The number of mesh cells in the x, y, and z directions, respectively.
+
+    *Default*: None
+
+  :lower_left:
+    The Cartesian coordinates of the lower-left corner of the mesh.
+
+    *Default*: None
+
+  :upper_right:
+    The Cartesian coordinates of the upper-right corner of the mesh.
+
+    *Default*: None
+
+.. _verbosity:
+
+-----------------------
+``<verbosity>`` Element
+-----------------------
+
+The ``<verbosity>`` element tells the code how much information to display to
+the standard output. A higher verbosity corresponds to more information being
+displayed. The text of this element should be an integer between between 1
+and 10. The verbosity levels are defined as follows:
+
+  :1: don't display any output
+  :2: only show OpenMC logo
+  :3: all of the above + headers
+  :4: all of the above + results
+  :5: all of the above + file I/O
+  :6: all of the above + timing statistics and initialization messages
+  :7: all of the above + :math:`k` by generation
+  :9: all of the above + indicate when each particle starts
+  :10: all of the above + event information
+
+  *Default*: 7
+
+-------------------------------------
+``<create_fission_neutrons>`` Element
+-------------------------------------
+
+The ``<create_fission_neutrons>`` element indicates whether fission neutrons
+should be created or not.  If this element is set to "true", fission neutrons
+will be created; otherwise the fission is treated as capture and no fission
+neutron will be created. Note that this option is only applied to fixed source
+calculation. For eigenvalue calculation, fission will always be treated as real
+fission.
+
+  *Default*: true
+
+
+-------------------------
+``<volume_calc>`` Element
+-------------------------
+
+The ``<volume_calc>`` element indicates that a stochastic volume calculation
+should be run at the beginning of the simulation. This element has the following
+sub-elements/attributes:
+
+  :cells:
+    The unique IDs of cells for which the volume should be estimated.
+
+    *Default*: None
+
+  :samples:
+    The number of samples used to estimate volumes.
+
+    *Default*: None
+
+  :lower_left:
+     The lower-left Cartesian coordinates of a bounding box that is used to
+     sample points within.
+
+     *Default*: None
+
+  :upper_right:
+     The upper-right Cartesian coordinates of a bounding box that is used to
+     sample points within.
+
+     *Default*: None

docs/source/io_formats/tallies.rst

@@ -0,0 +1,361 @@
+.. _io_tallies:
+
+====================================
+Tallies Specification -- tallies.xml
+====================================
+
+The tallies.xml file allows the user to tell the code what results he/she is
+interested in, e.g. the fission rate in a given cell or the current across a
+given surface. There are two pieces of information that determine what
+quantities should be scored. First, one needs to specify what region of phase
+space should count towards the tally and secondly, the actual quantity to be
+scored also needs to be specified. The first set of parameters we call *filters*
+since they effectively serve to filter events, allowing some to score and
+preventing others from scoring to the tally.
+
+The structure of tallies in OpenMC is flexible in that any combination of
+filters can be used for a tally. The following types of filter are available:
+cell, universe, material, surface, birth region, pre-collision energy,
+post-collision energy, and an arbitrary structured mesh.
+
+The three valid elements in the tallies.xml file are ``<tally>``, ``<mesh>``,
+and ``<assume_separate>``.
+
+.. _tally:
+
+-------------------
+``<tally>`` Element
+-------------------
+
+The ``<tally>`` element accepts the following sub-elements:
+
+  :name:
+    An optional string name to identify the tally in summary output
+    files. This string is limited to 52 characters for formatting purposes.
+
+    *Default*: ""
+
+  :filter:
+    Specify a filter that modifies tally behavior. Most tallies (e.g. ``cell``,
+    ``energy``, and ``material``) restrict the tally so that only particles
+    within certain regions of phase space contribute to the tally.  Others
+    (e.g. ``delayedgroup`` and ``energyfunction``) can apply some other function
+    to the scored values. This element and its attributes/sub-elements are
+    described below.
+
+    .. note::
+        You may specify zero, one, or multiple filters to apply to the tally. To
+        specify multiple filters, you must use multiple ``<filter>`` elements.
+
+    The ``filter`` element has the following attributes/sub-elements:
+
+      :type:
+        The type of the filter. Accepted options are "cell", "cellborn",
+        "material", "universe", "energy", "energyout", "mu", "polar",
+        "azimuthal", "mesh", "distribcell", "delayedgroup", and
+        "energyfunction".
+
+      :bins:
+         A description of the bins for each type of filter can be found in
+         :ref:`filter_types`.
+
+      :energy:
+        ``energyfunction`` filters multiply tally scores by an arbitrary
+        function. The function is described by a piecewise linear-linear set of
+        (energy, y) values. This entry specifies the energy values. The function
+        will be evaluated as zero outside of the bounds of this energy grid.
+        (Only used for ``energyfunction`` filters)
+
+      :y:
+        ``energyfunction`` filters multiply tally scores by an arbitrary
+        function. The function is described by a piecewise linear-linear set of
+        (energy, y) values. This entry specifies the y values. (Only used
+        for ``energyfunction`` filters)
+
+  :nuclides:
+    If specified, the scores listed will be for particular nuclides, not the
+    summation of reactions from all nuclides. The format for nuclides should be
+    [Atomic symbol]-[Mass number], e.g. "U-235". The reaction rate for all
+    nuclides can be obtained with "total". For example, to obtain the reaction
+    rates for U-235, Pu-239, and all nuclides in a material, this element should
+    be:
+
+    .. code-block:: xml
+
+        <nuclides>U-235 Pu-239 total</nuclides>
+
+    *Default*: total
+
+  :estimator:
+    The estimator element is used to force the use of either ``analog``,
+    ``collision``, or ``tracklength`` tally estimation.  ``analog`` is generally
+    the least efficient though it can be used with every score type.
+    ``tracklength`` is generally the most efficient, but neither ``tracklength``
+    nor ``collision`` can be used to score a tally that requires post-collision
+    information.  For example, a scattering tally with outgoing energy filters
+    cannot be used with ``tracklength`` or ``collision`` because the code will
+    not know the outgoing energy distribution.
+
+    *Default*: ``tracklength`` but will revert to ``analog`` if necessary.
+
+  :scores:
+    A space-separated list of the desired responses to be accumulated. A full
+    list of valid scores can be found in the :ref:`user's guide
+    <usersguide_scores>`.
+
+  :trigger:
+    Precision trigger applied to all filter bins and nuclides for this tally.
+    It must specify the trigger's type, threshold and scores to which it will
+    be applied. It has the following attributes/sub-elements:
+
+   :type:
+     The type of the trigger. Accepted options are "variance", "std_dev",
+     and "rel_err".
+
+     :variance:
+       Variance of the batch mean :math:`\sigma^2`
+
+     :std_dev:
+       Standard deviation of the batch mean :math:`\sigma`
+
+     :rel_err:
+       Relative error of the batch mean :math:`\frac{\sigma}{\mu}`
+
+     *Default*: None
+
+   :threshold:
+     The precision trigger's convergence criterion for tallied values.
+
+     *Default*: None
+
+   :scores:
+     The score(s) in this tally to which the trigger should be applied.
+
+     .. note:: The ``scores`` in ``trigger`` must have been defined in
+               ``scores`` in ``tally``. An optional "all" may be used to
+               select all scores in this tally.
+
+     *Default*: "all"
+
+  :derivative:
+    The id of a ``derivative`` element. This derivative will be applied to all
+    scores in the tally. Differential tallies are currently only implemented
+    for collision and analog estimators.
+
+     *Default*: None
+
+.. _filter_types:
+
+Filter Types
+++++++++++++
+
+For each filter type, the following table describes what the ``bins`` attribute
+should be set to:
+
+:cell:
+  A list of unique IDs for cells in which the tally should be accumulated.
+
+:cellborn:
+  This filter allows the tally to be scored to only when particles were
+  originally born in a specified cell. A list of cell IDs should be given.
+
+:material:
+  A list of unique IDs for matreials in which the tally should be accumulated.
+
+:universe:
+  A list of unique IDs for universes in which the tally should be accumulated.
+
+:energy:
+  In continuous-energy mode, this filter should be provided as a
+  monotonically increasing list of bounding **pre-collision** energies
+  for a number of groups. For example, if this filter is specified as
+
+  .. code-block:: xml
+
+      <filter type="energy" bins="0.0 1.0e6 20.0e6" />
+
+  then two energy bins will be created, one with energies between 0 and
+  1 MeV and the other with energies between 1 and 20 MeV.
+
+  In multi-group mode the bins provided must match group edges
+  defined in the multi-group library.
+
+:energyout:
+  In continuous-energy mode, this filter should be provided as a
+  monotonically increasing list of bounding **post-collision** energies
+  for a number of groups. For example, if this filter is specified as
+
+  .. code-block:: xml
+
+      <filter type="energyout" bins="0.0 1.0e6 20.0e6" />
+
+  then two post-collision energy bins will be created, one with
+  energies between 0 and 1 MeV and the other with energies between
+  1 and 20 MeV.
+
+  In multi-group mode the bins provided must match group edges
+  defined in the multi-group library.
+
+:mu:
+  A monotonically increasing list of bounding **post-collision** cosines
+  of the change in a particle's angle (i.e., :math:`\mu = \hat{\Omega}
+  \cdot \hat{\Omega}'`), which represents a portion of the possible
+  values of :math:`[-1,1]`.  For example, spanning all of :math:`[-1,1]`
+  with five equi-width bins can be specified as:
+
+  .. code-block:: xml
+
+      <filter type="mu" bins="-1.0 -0.6 -0.2 0.2 0.6 1.0" />
+
+  Alternatively, if only one value is provided as a bin, OpenMC will
+  interpret this to mean the complete range of :math:`[-1,1]` should
+  be automatically subdivided in to the provided value for the bin.
+  That is, the above example of five equi-width bins spanning
+  :math:`[-1,1]` can be instead written as:
+
+  .. code-block:: xml
+
+      <filter type="mu" bins="5" />
+
+:polar:
+  A monotonically increasing list of bounding particle polar angles
+  which represents a portion of the possible values of :math:`[0,\pi]`.
+  For example, spanning all of :math:`[0,\pi]` with five equi-width
+  bins can be specified as:
+
+  .. code-block:: xml
+
+      <filter type="polar" bins="0.0 0.6283 1.2566 1.8850 2.5132 3.1416"/>
+
+  Alternatively, if only one value is provided as a bin, OpenMC will
+  interpret this to mean the complete range of :math:`[0,\pi]` should
+  be automatically subdivided in to the provided value for the bin.
+  That is, the above example of five equi-width bins spanning
+  :math:`[0,\pi]` can be instead written as:
+
+  .. code-block:: xml
+
+      <filter type="polar" bins="5" />
+
+:azimuthal:
+  A monotonically increasing list of bounding particle azimuthal angles
+  which represents a portion of the possible values of :math:`[-\pi,\pi)`.
+  For example, spanning all of :math:`[-\pi,\pi)` with two equi-width
+  bins can be specified as:
+
+  .. code-block:: xml
+
+      <filter type="azimuthal" bins="0.0 3.1416 6.2832" />
+
+  Alternatively, if only one value is provided as a bin, OpenMC will
+  interpret this to mean the complete range of :math:`[-\pi,\pi)` should
+  be automatically subdivided in to the provided value for the bin.
+  That is, the above example of five equi-width bins spanning
+  :math:`[-\pi,\pi)` can be instead written as:
+
+  .. code-block:: xml
+
+      <filter type="azimuthal" bins="2" />
+
+:mesh:
+  The unique ID of a structured mesh to be tallied over.
+
+:distribcell:
+  The single cell which should be tallied uniquely for all instances.
+
+  .. note:: The distribcell filter will take a single cell ID and will tally
+            each unique occurrence of that cell separately. This filter will not
+            accept more than one cell ID. It is not recommended to combine this
+            filter with a cell or mesh filter.
+
+:delayedgroup:
+  A list of delayed neutron precursor groups for which the tally should
+  be accumulated. For instance, to tally to all 6 delayed groups in the
+  ENDF/B-VII.1 library the filter is specified as:
+
+  .. code-block:: xml
+
+      <filter type="delayedgroup" bins="1 2 3 4 5 6" />
+
+:energyfunction:
+  ``energyfunction`` filters do not use the ``bins`` entry.  Instead
+  they use ``energy`` and ``y``.
+
+
+------------------
+``<mesh>`` Element
+------------------
+
+If a structured mesh is desired as a filter for a tally, it must be specified in
+a separate element with the tag name ``<mesh>``. This element has the following
+attributes/sub-elements:
+
+  :type:
+    The type of structured mesh. The only valid option is "regular".
+
+  :dimension:
+    The number of mesh cells in each direction.
+
+  :lower_left:
+    The lower-left corner of the structured mesh. If only two coordinates are
+    given, it is assumed that the mesh is an x-y mesh.
+
+  :upper_right:
+    The upper-right corner of the structured mesh. If only two coordinates are
+    given, it is assumed that the mesh is an x-y mesh.
+
+  :width:
+    The width of mesh cells in each direction.
+
+  .. note::
+      One of ``<upper_right>`` or ``<width>`` must be specified, but not both
+      (even if they are consistent with one another).
+
+------------------------
+``<derivative>`` Element
+------------------------
+
+OpenMC can take the first-order derivative of many tallies with respect to
+material perturbations. It works by propagating a derivative through the
+transport equation. Essentially, OpenMC keeps track of how each particle's
+weight would change as materials are perturbed, and then accounts for that
+weight change in the tallies. Note that this assumes material perturbations are
+small enough not to change the distribution of fission sites. This element has
+the following attributes/sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the derivative.
+
+  :variable:
+    The independent variable of the derivative. Accepted options are "density",
+    "nuclide_density", and "temperature". A "density" derivative will give the
+    derivative with respect to the density of the material in [g / cm^3]. A
+    "nuclide_density" derivative will give the derivative with respect to the
+    density of a particular nuclide in units of [atom / b / cm].  A
+    "temperature" derivative is with respect to a material temperature in units
+    of [K].  The temperature derivative requires windowed multipole to be
+    turned on.  Note also that the temperature derivative only accounts for
+    resolved resonance Doppler broadening.  It does not account for thermal
+    expansion, S(a, b) scattering, resonance scattering, or unresolved Doppler
+    broadening.
+
+  :material:
+    The perturbed material. (Necessary for all derivative types)
+
+  :nuclide:
+    The perturbed nuclide. (Necessary only for "nuclide_density")
+
+-----------------------------
+``<assume_separate>`` Element
+-----------------------------
+
+In cases where the user needs to specify many different tallies each of which
+are spatially separate, this tag can be used to cut down on some of the tally
+overhead. The effect of assuming all tallies are spatially separate is that once
+one tally is scored to, the same event is assumed not to score to any other
+tallies. This element should be followed by "true" or "false".
+
+  .. warning:: If used incorrectly, the assumption that all tallies are
+               spatially separate can lead to incorrect results.
+
+  *Default*: false

docs/source/methods/cmfd.rst

@@ -402,7 +402,7 @@ information:
 It should be noted that for more difficult simulations (e.g., light water
 reactors), there are other options available to users such as tally resetting
 parameters, effective down-scatter usage, tally estimator, etc. For more
-information please see :ref:`usersguide_cmfd`.
+information please see :ref:`io_cmfd`.
 
 Of the options described above, the optional acceleration subset region is an
 uncommon feature. Because OpenMC only has a structured Cartesian mesh, mesh

docs/source/methods/physics.rst

@@ -1657,7 +1657,7 @@ another.
 
 .. _OECD: http://www.oecd-nea.org/dbprog/MMRW-BOOKS.html
 
-.. _NJOY: http://t2.lanl.gov/codes.shtml
+.. _NJOY: https://njoy.github.io/NJOY2016/
 
 .. _PREPRO: http://www-nds.iaea.org/ndspub/endf/prepro/
 

docs/source/pythonapi/base.rst

@@ -0,0 +1,197 @@
+------------------------------------
+:mod:`openmc` -- Basic Functionality
+------------------------------------
+
+Handling nuclear data
+---------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.XSdata
+   openmc.MGXSLibrary
+
+Simulation Settings
+-------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Source
+   openmc.VolumeCalculation
+   openmc.Settings
+
+Material Specification
+----------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Nuclide
+   openmc.Element
+   openmc.Macroscopic
+   openmc.Material
+   openmc.Materials
+
+Cross sections for nuclides, elements, and materials can be plotted using the
+following function:
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myfunction.rst
+
+   openmc.plot_xs
+
+Building geometry
+-----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Plane
+   openmc.XPlane
+   openmc.YPlane
+   openmc.ZPlane
+   openmc.XCylinder
+   openmc.YCylinder
+   openmc.ZCylinder
+   openmc.Sphere
+   openmc.Cone
+   openmc.XCone
+   openmc.YCone
+   openmc.ZCone
+   openmc.Quadric
+   openmc.Halfspace
+   openmc.Intersection
+   openmc.Union
+   openmc.Complement
+   openmc.Cell
+   openmc.Universe
+   openmc.RectLattice
+   openmc.HexLattice
+   openmc.Geometry
+
+Many of the above classes are derived from several abstract classes:
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Surface
+   openmc.Region
+   openmc.Lattice
+
+Two helper function are also available to create rectangular and hexagonal
+prisms defined by the intersection of four and six surface half-spaces,
+respectively.
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myfunction.rst
+
+   openmc.get_hexagonal_prism
+   openmc.get_rectangular_prism
+
+.. _pythonapi_tallies:
+
+Constructing Tallies
+--------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Filter
+   openmc.UniverseFilter
+   openmc.MaterialFilter
+   openmc.CellFilter
+   openmc.CellbornFilter
+   openmc.SurfaceFilter
+   openmc.MeshFilter
+   openmc.EnergyFilter
+   openmc.EnergyoutFilter
+   openmc.MuFilter
+   openmc.PolarFilter
+   openmc.AzimuthalFilter
+   openmc.DistribcellFilter
+   openmc.DelayedGroupFilter
+   openmc.EnergyFunctionFilter
+   openmc.Mesh
+   openmc.Trigger
+   openmc.TallyDerivative
+   openmc.Tally
+   openmc.Tallies
+
+Coarse Mesh Finite Difference Acceleration
+------------------------------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.CMFDMesh
+   openmc.CMFD
+
+Geometry Plotting
+-----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Plot
+   openmc.Plots
+
+Running OpenMC
+--------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myfunction.rst
+
+   openmc.run
+   openmc.calculate_volumes
+   openmc.plot_geometry
+   openmc.plot_inline
+   openmc.search_for_keff
+
+Post-processing
+---------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.Particle
+   openmc.StatePoint
+   openmc.Summary
+
+Various classes may be created when performing tally slicing and/or arithmetic:
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.arithmetic.CrossScore
+   openmc.arithmetic.CrossNuclide
+   openmc.arithmetic.CrossFilter
+   openmc.arithmetic.AggregateScore
+   openmc.arithmetic.AggregateNuclide
+   openmc.arithmetic.AggregateFilter

docs/source/pythonapi/data.rst

@@ -0,0 +1,134 @@
+--------------------------------------------
+:mod:`openmc.data` -- Nuclear Data Interface
+--------------------------------------------
+
+Core Classes
+------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.data.IncidentNeutron
+    openmc.data.Reaction
+    openmc.data.Product
+    openmc.data.Tabulated1D
+    openmc.data.FissionEnergyRelease
+    openmc.data.ThermalScattering
+    openmc.data.CoherentElastic
+    openmc.data.FissionEnergyRelease
+    openmc.data.DataLibrary
+    openmc.data.Decay
+    openmc.data.FissionProductYields
+    openmc.data.WindowedMultipole
+
+Core Functions
+--------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myfunction.rst
+
+    openmc.data.atomic_mass
+    openmc.data.linearize
+    openmc.data.thin
+    openmc.data.write_compact_458_library
+
+Angle-Energy Distributions
+--------------------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.data.AngleEnergy
+    openmc.data.KalbachMann
+    openmc.data.CorrelatedAngleEnergy
+    openmc.data.UncorrelatedAngleEnergy
+    openmc.data.NBodyPhaseSpace
+    openmc.data.LaboratoryAngleEnergy
+    openmc.data.AngleDistribution
+    openmc.data.EnergyDistribution
+    openmc.data.ArbitraryTabulated
+    openmc.data.GeneralEvaporation
+    openmc.data.MaxwellEnergy
+    openmc.data.Evaporation
+    openmc.data.WattEnergy
+    openmc.data.MadlandNix
+    openmc.data.DiscretePhoton
+    openmc.data.LevelInelastic
+    openmc.data.ContinuousTabular
+
+Resonance Data
+--------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.data.Resonances
+    openmc.data.ResonanceRange
+    openmc.data.SingleLevelBreitWigner
+    openmc.data.MultiLevelBreitWigner
+    openmc.data.ReichMoore
+    openmc.data.RMatrixLimited
+    openmc.data.ParticlePair
+    openmc.data.SpinGroup
+    openmc.data.Unresolved
+
+ACE Format
+----------
+
+Classes
++++++++
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.data.ace.Library
+    openmc.data.ace.Table
+
+Functions
++++++++++
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myfunction.rst
+
+    openmc.data.ace.ascii_to_binary
+
+ENDF Format
+-----------
+
+Classes
++++++++
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.data.endf.Evaluation
+
+Functions
++++++++++
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myfunction.rst
+
+    openmc.data.endf.float_endf
+    openmc.data.endf.get_cont_record
+    openmc.data.endf.get_evaluations
+    openmc.data.endf.get_head_record
+    openmc.data.endf.get_tab1_record
+    openmc.data.endf.get_tab2_record
+    openmc.data.endf.get_text_record

docs/source/pythonapi/index.rst

@@ -6,508 +6,45 @@ Python API
 
 OpenMC includes a rich Python API that enables programmatic pre- and
 post-processing. The easiest way to begin using the API is to take a look at the
-example Jupyter_ notebooks provided in the :ref:`examples` section of the
-documentation. However, this assumes that you are already familiar with Python
-and common third-party packages such as NumPy_. If you have never programmed in
-Python before, there are many good tutorials available online. We recommend
-going through the modules from Codecademy_ and/or the `Scipy lectures`_. The
-full API documentation serves to provide more information on a given module or
-class.
-
-------------------------------------
-:mod:`openmc` -- Basic Functionality
-------------------------------------
-
-Handling nuclear data
----------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.XSdata
-   openmc.MGXSLibrary
-
-
-Simulation Settings
--------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.Source
-   openmc.VolumeCalculation
-   openmc.Settings
-
-Material Specification
-----------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.Nuclide
-   openmc.Element
-   openmc.Macroscopic
-   openmc.Material
-   openmc.Materials
-
-Building geometry
------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.Plane
-   openmc.XPlane
-   openmc.YPlane
-   openmc.ZPlane
-   openmc.XCylinder
-   openmc.YCylinder
-   openmc.ZCylinder
-   openmc.Sphere
-   openmc.Cone
-   openmc.XCone
-   openmc.YCone
-   openmc.ZCone
-   openmc.Quadric
-   openmc.Halfspace
-   openmc.Intersection
-   openmc.Union
-   openmc.Complement
-   openmc.Cell
-   openmc.Universe
-   openmc.RectLattice
-   openmc.HexLattice
-   openmc.Geometry
-
-Many of the above classes are derived from several abstract classes:
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.Surface
-   openmc.Region
-   openmc.Lattice
-
-Two helper function are also available to create rectangular and hexagonal
-prisms defined by the intersection of four and six surface half-spaces,
-respectively.
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myfunction.rst
-
-   openmc.get_hexagonal_prism
-   openmc.get_rectangular_prism
-
-Constructing Tallies
---------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.UniverseFilter
-   openmc.MaterialFilter
-   openmc.CellFilter
-   openmc.CellbornFilter
-   openmc.SurfaceFilter
-   openmc.MeshFilter
-   openmc.EnergyFilter
-   openmc.EnergyoutFilter
-   openmc.MuFilter
-   openmc.PolarFilter
-   openmc.AzimuthalFilter
-   openmc.DistribcellFilter
-   openmc.DelayedGroupFilter
-   openmc.EnergyFunctionFilter
-   openmc.Mesh
-   openmc.Trigger
-   openmc.TallyDerivative
-   openmc.Tally
-   openmc.Tallies
-
-Coarse Mesh Finite Difference Acceleration
-------------------------------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.CMFDMesh
-   openmc.CMFD
-
-Plotting
---------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.Plot
-   openmc.Plots
-
-Running OpenMC
---------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myfunction.rst
-
-   openmc.run
-   openmc.calculate_volumes
-   openmc.plot_geometry
-   openmc.plot_inline
-   openmc.search_for_keff
-
-Post-processing
----------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.Particle
-   openmc.StatePoint
-   openmc.Summary
-
-Various classes may be created when performing tally slicing and/or arithmetic:
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.arithmetic.CrossScore
-   openmc.arithmetic.CrossNuclide
-   openmc.arithmetic.CrossFilter
-   openmc.arithmetic.AggregateScore
-   openmc.arithmetic.AggregateNuclide
-   openmc.arithmetic.AggregateFilter
-
----------------------------------
-:mod:`openmc.stats` -- Statistics
----------------------------------
-
-Univariate Probability Distributions
-------------------------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.stats.Univariate
-   openmc.stats.Discrete
-   openmc.stats.Uniform
-   openmc.stats.Maxwell
-   openmc.stats.Watt
-   openmc.stats.Tabular
-   openmc.stats.Legendre
-   openmc.stats.Mixture
-
-Angular Distributions
----------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.stats.UnitSphere
-   openmc.stats.PolarAzimuthal
-   openmc.stats.Isotropic
-   openmc.stats.Monodirectional
-
-Spatial Distributions
----------------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.stats.Spatial
-   openmc.stats.CartesianIndependent
-   openmc.stats.Box
-   openmc.stats.Point
-
-----------------------------------------------------------
-:mod:`openmc.mgxs` -- Multi-Group Cross Section Generation
-----------------------------------------------------------
-
-Energy Groups
--------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.mgxs.EnergyGroups
-
-Multi-group Cross Sections
---------------------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclassinherit.rst
-
-    openmc.mgxs.MGXS
-    openmc.mgxs.AbsorptionXS
-    openmc.mgxs.CaptureXS
-    openmc.mgxs.Chi
-    openmc.mgxs.FissionXS
-    openmc.mgxs.InverseVelocity
-    openmc.mgxs.KappaFissionXS
-    openmc.mgxs.MultiplicityMatrixXS
-    openmc.mgxs.NuFissionMatrixXS
-    openmc.mgxs.ScatterXS
-    openmc.mgxs.ScatterMatrixXS
-    openmc.mgxs.ScatterProbabilityMatrix
-    openmc.mgxs.TotalXS
-    openmc.mgxs.TransportXS
-
-Multi-delayed-group Cross Sections
-----------------------------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclassinherit.rst
-
-    openmc.mgxs.MDGXS
-    openmc.mgxs.ChiDelayed
-    openmc.mgxs.DelayedNuFissionXS
-    openmc.mgxs.DelayedNuFissionMatrixXS
-    openmc.mgxs.Beta
-    openmc.mgxs.DecayRate
-
-Multi-group Cross Section Libraries
------------------------------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.mgxs.Library
-
--------------------------------------
-:mod:`openmc.model` -- Model Building
--------------------------------------
-
-TRISO Fuel Modeling
--------------------
-
-Classes
-+++++++
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.model.TRISO
-
-Functions
-+++++++++
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myfunction.rst
-
-   openmc.model.create_triso_lattice
-   openmc.model.pack_trisos
-
-Model Container
----------------
-
-Classes
-+++++++
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.model.Model
-
---------------------------------------------
-:mod:`openmc.data` -- Nuclear Data Interface
---------------------------------------------
-
-Core Classes
-------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.data.IncidentNeutron
-    openmc.data.Reaction
-    openmc.data.Product
-    openmc.data.Tabulated1D
-    openmc.data.FissionEnergyRelease
-    openmc.data.ThermalScattering
-    openmc.data.CoherentElastic
-    openmc.data.FissionEnergyRelease
-    openmc.data.DataLibrary
-    openmc.data.Decay
-    openmc.data.FissionProductYields
-    openmc.data.WindowedMultipole
-
-Core Functions
---------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myfunction.rst
-
-    openmc.data.atomic_mass
-    openmc.data.linearize
-    openmc.data.thin
-    openmc.data.write_compact_458_library
-
-Angle-Energy Distributions
---------------------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.data.AngleEnergy
-    openmc.data.KalbachMann
-    openmc.data.CorrelatedAngleEnergy
-    openmc.data.UncorrelatedAngleEnergy
-    openmc.data.NBodyPhaseSpace
-    openmc.data.LaboratoryAngleEnergy
-    openmc.data.AngleDistribution
-    openmc.data.EnergyDistribution
-    openmc.data.ArbitraryTabulated
-    openmc.data.GeneralEvaporation
-    openmc.data.MaxwellEnergy
-    openmc.data.Evaporation
-    openmc.data.WattEnergy
-    openmc.data.MadlandNix
-    openmc.data.DiscretePhoton
-    openmc.data.LevelInelastic
-    openmc.data.ContinuousTabular
-
-Resonance Data
---------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.data.Resonances
-    openmc.data.ResonanceRange
-    openmc.data.SingleLevelBreitWigner
-    openmc.data.MultiLevelBreitWigner
-    openmc.data.ReichMoore
-    openmc.data.RMatrixLimited
-    openmc.data.ParticlePair
-    openmc.data.SpinGroup
-    openmc.data.Unresolved
-
-ACE Format
-----------
-
-Classes
-+++++++
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.data.ace.Library
-    openmc.data.ace.Table
-
-Functions
-+++++++++
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myfunction.rst
-
-    openmc.data.ace.ascii_to_binary
-
-ENDF Format
------------
-
-Classes
-+++++++
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myclass.rst
-
-    openmc.data.endf.Evaluation
-
-Functions
-+++++++++
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myfunction.rst
-
-    openmc.data.endf.float_endf
-    openmc.data.endf.get_cont_record
-    openmc.data.endf.get_evaluations
-    openmc.data.endf.get_head_record
-    openmc.data.endf.get_tab1_record
-    openmc.data.endf.get_tab2_record
-    openmc.data.endf.get_text_record
-
----------------------------------------------------------
-:mod:`openmc.openmoc_compatible` -- OpenMOC Compatibility
----------------------------------------------------------
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-    :template: myfunction.rst
-
-    openmc.openmoc_compatible.get_openmoc_material
-    openmc.openmoc_compatible.get_openmc_material
-    openmc.openmoc_compatible.get_openmoc_surface
-    openmc.openmoc_compatible.get_openmc_surface
-    openmc.openmoc_compatible.get_openmoc_cell
-    openmc.openmoc_compatible.get_openmc_cell
-    openmc.openmoc_compatible.get_openmoc_universe
-    openmc.openmoc_compatible.get_openmc_universe
-    openmc.openmoc_compatible.get_openmoc_lattice
-    openmc.openmoc_compatible.get_openmc_lattice
-    openmc.openmoc_compatible.get_openmoc_geometry
-    openmc.openmoc_compatible.get_openmc_geometry
-
-.. _Jupyter: https://jupyter.org/
-.. _NumPy: http://www.numpy.org/
-.. _Codecademy: https://www.codecademy.com/tracks/python
-.. _Scipy lectures: https://scipy-lectures.github.io/
+:ref:`examples`. This assumes that you are already familiar with Python and
+common third-party packages such as `NumPy <http://www.numpy.org/>`_. If you
+have never used Python before, the prospect of learning a new code *and* a
+programming language might sound daunting. However, you should keep in mind that
+there are many substantial benefits to using the Python API, including:
+
+- The ability to define dimensions using variables.
+- Availability of standard-library modules for working with files.
+- An entire ecosystem of third-party packages for scientific computing.
+- Ability to create materials based on natural elements or uranium enrichment
+- Automated multi-group cross section generation (:mod:`openmc.mgxs`)
+- Convenience functions (e.g., a function returning a hexagonal region)
+- Ability to plot individual universes as geometry is being created
+- A :math:`k_\text{eff}` search function (:func:`openmc.search_for_keff`)
+- Random sphere packing for generating TRISO particle locations
+  (:func:`openmc.model.pack_trisos`)
+- A fully-featured nuclear data interface (:mod:`openmc.data`)
+
+For those new to Python, there are many good tutorials available online. We
+recommend going through the modules from `Codecademy
+<https://www.codecademy.com/tracks/python>`_ and/or the `Scipy lectures
+<https://scipy-lectures.github.io/>`_.
+
+The full API documentation serves to provide more information on a given module
+or class.
+
+.. tip:: Users are strongly encouraged to use the Python API to generate input
+         files and analyze results.
+
+-------
+Modules
+-------
+
+.. toctree::
+   :maxdepth: 2
+
+   base
+   stats
+   mgxs
+   model
+   data
+   openmoc

docs/source/pythonapi/mgxs.rst

@@ -0,0 +1,61 @@
+----------------------------------------------------------
+:mod:`openmc.mgxs` -- Multi-Group Cross Section Generation
+----------------------------------------------------------
+
+Energy Groups
+-------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.mgxs.EnergyGroups
+
+Multi-group Cross Sections
+--------------------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclassinherit.rst
+
+    openmc.mgxs.MGXS
+    openmc.mgxs.AbsorptionXS
+    openmc.mgxs.CaptureXS
+    openmc.mgxs.Chi
+    openmc.mgxs.FissionXS
+    openmc.mgxs.InverseVelocity
+    openmc.mgxs.KappaFissionXS
+    openmc.mgxs.MultiplicityMatrixXS
+    openmc.mgxs.NuFissionMatrixXS
+    openmc.mgxs.ScatterXS
+    openmc.mgxs.ScatterMatrixXS
+    openmc.mgxs.ScatterProbabilityMatrix
+    openmc.mgxs.TotalXS
+    openmc.mgxs.TransportXS
+
+Multi-delayed-group Cross Sections
+----------------------------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclassinherit.rst
+
+    openmc.mgxs.MDGXS
+    openmc.mgxs.ChiDelayed
+    openmc.mgxs.DelayedNuFissionXS
+    openmc.mgxs.DelayedNuFissionMatrixXS
+    openmc.mgxs.Beta
+    openmc.mgxs.DecayRate
+
+Multi-group Cross Section Libraries
+-----------------------------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
+
+    openmc.mgxs.Library

docs/source/pythonapi/model.rst

@@ -0,0 +1,40 @@
+-------------------------------------
+:mod:`openmc.model` -- Model Building
+-------------------------------------
+
+TRISO Fuel Modeling
+-------------------
+
+Classes
++++++++
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.model.TRISO
+
+Functions
++++++++++
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myfunction.rst
+
+   openmc.model.create_triso_lattice
+   openmc.model.pack_trisos
+
+Model Container
+---------------
+
+Classes
++++++++
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.model.Model

docs/source/pythonapi/openmoc.rst

@@ -0,0 +1,24 @@
+---------------------------------------------------------
+:mod:`openmc.openmoc_compatible` -- OpenMOC Compatibility
+---------------------------------------------------------
+
+Core Classes
+------------
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: myfunction.rst
+
+    openmc.openmoc_compatible.get_openmoc_material
+    openmc.openmoc_compatible.get_openmc_material
+    openmc.openmoc_compatible.get_openmoc_surface
+    openmc.openmoc_compatible.get_openmc_surface
+    openmc.openmoc_compatible.get_openmoc_cell
+    openmc.openmoc_compatible.get_openmc_cell
+    openmc.openmoc_compatible.get_openmoc_universe
+    openmc.openmoc_compatible.get_openmc_universe
+    openmc.openmoc_compatible.get_openmoc_lattice
+    openmc.openmoc_compatible.get_openmc_lattice
+    openmc.openmoc_compatible.get_openmoc_geometry
+    openmc.openmoc_compatible.get_openmc_geometry

docs/source/pythonapi/stats.rst

@@ -0,0 +1,48 @@
+.. _pythonapi_stats:
+
+---------------------------------
+:mod:`openmc.stats` -- Statistics
+---------------------------------
+
+Univariate Probability Distributions
+------------------------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.stats.Univariate
+   openmc.stats.Discrete
+   openmc.stats.Uniform
+   openmc.stats.Maxwell
+   openmc.stats.Watt
+   openmc.stats.Tabular
+   openmc.stats.Legendre
+   openmc.stats.Mixture
+
+Angular Distributions
+---------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.stats.UnitSphere
+   openmc.stats.PolarAzimuthal
+   openmc.stats.Isotropic
+   openmc.stats.Monodirectional
+
+Spatial Distributions
+---------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   openmc.stats.Spatial
+   openmc.stats.CartesianIndependent
+   openmc.stats.Box
+   openmc.stats.Point

docs/source/quickinstall.rst

@@ -106,6 +106,10 @@ should specify an installation directory where you have write access, e.g.
 
     cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
 
+If you want to build a parallel version of OpenMC (using OpenMP or MPI),
+directions can be found in the :ref:`detailed installation instructions
+<usersguide_build>`.
+
 .. _GitHub: https://github.com/mit-crpg/openmc
 .. _git: http://git-scm.com
 .. _gfortran: http://gcc.gnu.org/wiki/GFortran

docs/source/usersguide/basics.rst

@@ -0,0 +1,194 @@
+.. _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.
+
+   :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
+<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()
+
+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.
+
+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

docs/source/usersguide/beginners.rst

@@ -8,33 +8,35 @@ A Beginner's Guide to OpenMC
 What does OpenMC do?
 --------------------
 
-In a nutshell, OpenMC simulates neutrons moving around randomly in a `nuclear
-reactor`_ (or other fissile system). This is what's known as `Monte Carlo`_
-simulation. Neutrons are important in nuclear reactors because they are the
-particles that induce `fission`_ in uranium and other nuclides. Knowing the
-behavior of neutrons allows you to determine how often and where fission
-occurs. The amount of energy released is then directly proportional to the
-fission reaction rate since most heat is produced by fission. By simulating many
-neutrons (millions or billions), it is possible to determine the average
-behavior of these neutrons (or the behavior of the energy produced or any other
-quantity one is interested in) very accurately.
+In a nutshell, OpenMC simulates neutral particles (presently only neutrons)
+moving stochastically through an arbitrarily defined model that represents an
+real-world experimental setup. The experiment could be as simple as a sphere of
+metal or as complicated as a full-scale `nuclear reactor`_. This is what's known
+as `Monte Carlo`_ simulation. In the case of a nuclear reactor model, neutrons
+are especially important because they are the particles that induce `fission`_
+in isotopes of uranium and other elements. Knowing the behavior of neutrons
+allows one to determine how often and where fission occurs. The amount of energy
+released is then directly proportional to the fission reaction rate since most
+heat is produced by fission. By simulating many neutrons (millions or billions),
+it is possible to determine the average behavior of these neutrons (or the
+behavior of the energy produced, or any other quantity one is interested in)
+very accurately.
 
 Using Monte Carlo methods to determine the average behavior of various physical
-quantities in a nuclear reactor is quite different from other means of solving
-the same problem. The other class of methods for determining the behavior of
-neutrons and reactions rates in a reactor is so-called `deterministic`_
-methods. In these methods, the starting point is not randomly simulating
-particles but rather writing an equation that describes the average behavior of
-the particles. The equation that describes the average behavior of neutrons is
-called the `neutron transport`_ equation. This equation is a seven-dimensional
-equation (three for space, three for velocity, and one for time) and is very
-difficult to solve directly. For all but the simplest problems, it is necessary
-to make some sort of `discretization`_. As an example, we can divide up all
-space into small sections which are homogeneous and then solve the equation on
-those small sections. After these discretizations and various approximations,
-one can arrive at forms that are suitable for solution on a computer. Among
-these are discrete ordinates, method of characteristics, finite-difference
-diffusion, and nodal methods.
+quantities in a system is quite different from other means of solving the same
+problem. The other class of methods for determining the behavior of neutrons and
+reactions rates is so-called `deterministic`_ methods. In these methods, the
+starting point is not randomly simulating particles but rather writing an
+equation that describes the average behavior of the particles. The equation that
+describes the average behavior of neutrons is called the `neutron transport`_
+equation. This equation is a seven-dimensional equation (three for space, three
+for velocity, and one for time) and is very difficult to solve directly. For all
+but the simplest problems, it is necessary to make some sort of
+`discretization`_. As an example, we can divide up all space into small sections
+which are homogeneous and then solve the equation on those small sections. After
+these discretizations and various approximations, one can arrive at forms that
+are suitable for solution on a computer. Among these are discrete ordinates,
+method of characteristics, finite-difference diffusion, and nodal methods.
 
 So why choose Monte Carlo over deterministic methods? Each method has its pros
 and cons. Let us first take a look at few of the salient pros and cons of
@@ -88,30 +90,32 @@ interest. This could be a nuclear reactor or any other physical system with
 fissioning material. You, as the code user, will need to describe the model so
 that the code can do something with it. A basic model consists of a few things:
 
-- A description of the geometry -- the problem should be split up into regions
-  of homogeneous material.
+- A description of the geometry -- the problem must be split up into regions of
+  homogeneous material composition.
 - For each different material in the problem, a description of what nuclides are
   in the material and at what density.
 - Various parameters telling the code how many particles to simulate and what
   options to use.
 - A list of different physical quantities that the code should return at the end
-  of the simulation. Remember, in a Monte Carlo simulation, if you don't ask for
-  anything, it will not give you any answers (other than a few default
-  quantities).
+  of the simulation. In a Monte Carlo simulation, if you don't ask for anything,
+  it will not give you any answers (other than a few default quantities).
 
 -----------------------
 What do I need to know?
 -----------------------
 
 If you are starting to work with OpenMC, there are a few things you should be
-familiar with. Whether you plan on working in Linux, Mac OS X, or Windows, you
+familiar with. Whether you plan on working in Linux, macOS, or Windows, you
 should be comfortable working in a command line environment. There are many
 resources online for learning command line environments. If you are using Linux
 or Mac OS X (also Unix-derived), `this tutorial
 <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

docs/source/usersguide/cross_sections.rst

@@ -0,0 +1,234 @@
+.. _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. 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:`scripts_ace` script (or :ref:`using the Python
+API <create_xs_library>`).  Several sources provide openly available ACE data as
+described below and can be easily converted using the provided scripts. The
+TALYS-based evaluated nuclear data library, TENDL_, is also available in ACE
+format. 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 :class:`openmc.Materials` class
+(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_MULTIPOLE_LIBRARY`
+  Indicates the path to a directory containing windowed multipole data if the
+  user has not specified :attr:`Materials.multipole_library` (equivalently, the
+  :ref:`multipole_library` 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 ENDF/B-VII.1 Cross Sections from NNDC
+-------------------------------------------
+
+The NNDC_ provides ACE data from the ENDF/B-VII.1 neutron and thermal scattering
+sublibraries at room temperature processed using NJOY_. To use this data with
+OpenMC, the :ref:`scripts_nndc` script can be used to automatically download and
+extract the ACE data, fix any deficiencies, and create an HDF5 library:
+
+.. code-block:: sh
+
+    openmc-get-nndc-data
+
+At this point, you should set the :envvar:`OPENMC_CROSS_SECTIONS` environment
+variable to the absolute path of the file ``nndc_hdf5/cross_sections.xml``. This
+cross section set is used by the test suite.
+
+Using JEFF Cross Sections from OECD/NEA
+---------------------------------------
+
+The NEA_ provides processed ACE data from the JEFF_ library. To use this data
+with OpenMC, the :ref:`scripts_jeff` script can be used to automatically
+download and extract the ACE data, fix any deficiencies, and create an HDF5
+library.
+
+.. code-block:: sh
+
+    openmc-get-jeff-data
+
+At this point, you should set the :envvar:`OPENMC_CROSS_SECTIONS` environment
+variable to the absolute path of the file ``jeff-3.2-hdf5/cross_sections.xml``.
+
+Using Cross Sections from MCNP
+------------------------------
+
+OpenMC provides two scripts (:ref:`scripts_mcnp70` and :ref:`scripts_mcnp71`)
+that will automatically convert ENDF/B-VII.0 and ENDF/B-VII.1 ACE data that is
+provided with MCNP5 or MCNP6. To convert the ENDF/B-VII.0 ACE files
+(``endf70[a-k]`` and ``endf70sab``) into the native HDF5 format, run the
+following:
+
+.. code-block:: sh
+
+    openmc-convert-mcnp70-data /path/to/mcnpdata/
+
+where ``/path/to/mcnpdata`` is the directory containing the ``endf70[a-k]``
+files.
+
+To convert the ENDF/B-VII.1 ACE files (the endf71x and ENDF71SaB libraries), use
+the following script:
+
+.. code-block:: sh
+
+    openmc-convert-mcnp71-data /path/to/mcnpdata
+
+where ``/path/to/mcnpdata`` is the directory containing the ``endf71x`` and
+``ENDF71SaB`` directories.
+
+.. _other_cross_sections:
+
+Using Other Cross Sections
+--------------------------
+
+If you have a library of ACE format cross sections other than those listed above
+that you need to convert to OpenMC's HDF5 format, the :ref:`scripts_ace` script
+can be used. 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).
+
+.. _create_xs_library:
+
+Manually Creating a Library
+---------------------------
+
+.. 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.
+
+-----------------------
+Windowed Multipole Data
+-----------------------
+
+OpenMC is capable of using windowed multipole data for on-the-fly Doppler
+broadening. While such data is not yet available for all nuclides, an
+experimental multipole library is available that contains data for 70
+nuclides. To obtain this library, you can run :ref:`scripts_multipole` which
+will download and extract it into a ``wmp`` directory. Once the library has been
+downloaded, set the :envvar:`OPENMC_MULTIPOLE_LIBRARY` environment variable (or
+the :attr:`Materials.multipole_library` attribute) to the ``wmp`` directory.
+
+--------------------------
+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: https://njoy.github.io/NJOY2016/
+.. _NNDC: http://www.nndc.bnl.gov/endf/b7.1/acefiles.html
+.. _NEA: http://www.oecd-nea.org
+.. _JEFF: https://www.oecd-nea.org/dbforms/data/eva/evatapes/jeff_32/
+.. _MCNP: http://mcnp.lanl.gov
+.. _Serpent: http://montecarlo.vtt.fi
+.. _TENDL: https://tendl.web.psi.ch/tendl_2015/tendl2015.html

docs/source/usersguide/geometry.rst

@@ -0,0 +1,385 @@
+.. _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 perpendicular 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 of 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.get_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.get_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 only be applied
+to pairs of axis-aligned planar surfaces.
+
+.. _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.get_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()
+
+.. _constructive solid geometry: http://en.wikipedia.org/wiki/Constructive_solid_geometry
+.. _quadratic surfaces: http://en.wikipedia.org/wiki/Quadric

docs/source/usersguide/index.rst

@@ -9,10 +9,19 @@ essential aspects of using OpenMC to perform simulations.
 
 .. toctree::
     :numbered:
-    :maxdepth: 2
+    :maxdepth: 1
 
     beginners
     install
-    input
+    cross_sections
+    basics
+    materials
+    geometry
+    settings
+    tallies
+    plots
+    scripts
     processing
+    parallel
+    volume
     troubleshoot

docs/source/usersguide/install.rst

@@ -4,6 +4,8 @@
 Installation and Configuration
 ==============================
 
+.. currentmodule:: openmc
+
 ----------------------------------------
 Installing on Linux/Mac with conda-forge
 ----------------------------------------
@@ -52,7 +54,7 @@ Next, resynchronize the package index files:
 
 .. code-block:: sh
 
-    sudo apt-get update
+    sudo apt update
 
 Now OpenMC should be recognized within the repository and can be installed:
 
@@ -76,6 +78,7 @@ Prerequisites
 -------------
 
 .. admonition:: Required
+   :class: error
 
     * A Fortran compiler such as gfortran_
 
@@ -140,6 +143,7 @@ Prerequisites
       distribution and version.
 
 .. admonition:: Optional
+   :class: note
 
     * An MPI implementation for distributed-memory parallel runs
 
@@ -186,6 +190,8 @@ switch to the source of the latest stable release, run the following commands::
 .. _git: http://git-scm.com
 .. _ssh: http://en.wikipedia.org/wiki/Secure_Shell
 
+.. _usersguide_build:
+
 Build Configuration
 -------------------
 
@@ -243,6 +249,8 @@ should be used:
 
 .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
 
+.. _usersguide_compile_mpi:
+
 Compiling with MPI
 ++++++++++++++++++
 
@@ -318,7 +326,7 @@ 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-get``. Finally, follow the
+:ref:`prerequisites <prerequisites>` via ``apt``. Finally, follow the
 :ref:`instructions for compiling on linux <compile_linux>`.
 
 Compiling for the Intel Xeon Phi
@@ -371,184 +379,68 @@ if we wanted to run only the plot tests with 4 processors, we run:
 If you want to run the full test suite with different build options please
 refer to our :ref:`test suite` documentation.
 
----------------------------
-Cross Section Configuration
----------------------------
+--------------------
+Python Prerequisites
+--------------------
 
-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.
+OpenMC's :ref:`Python API <pythonapi>` works with either Python 2.7 or Python
+3.2+. In addition to Python itself, the API relies on a number of third-party
+packages. All prerequisites can be installed using `conda
+<http://conda.pydata.org/docs/>`_ (recommended), `pip
+<https://pip.pypa.io/en/stable/>`_, or through the package manager in most Linux
+distributions.
 
-In continuous-energy mode, OpenMC uses a native HDF5 format to store all nuclear
-data. 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:`openmc-ace-to-hdf5 <other_cross_sections>` script distributed with
-OpenMC.  Several sources provide openly available ACE data as described
-below. The TALYS-based evaluated nuclear data library, TENDL_, is also available
-in ACE format.
+.. admonition:: Required
+   :class: error
 
-In multi-group mode, OpenMC utilizes an XML-based library format which can be
-used to describe nuclide- or material-specific quantities.
+   `six <https://pythonhosted.org/six/>`_
+      The Python API works with both Python 2.7+ and 3.2+. To do so, the six
+      compatibility library is used.
 
-Using ENDF/B-VII.1 Cross Sections from NNDC
--------------------------------------------
+   `NumPy <http://www.numpy.org/>`_
+      NumPy is used extensively within the Python API for its powerful
+      N-dimensional array.
 
-The NNDC_ provides ACE data from the ENDF/B-VII.1 neutron and thermal scattering
-sublibraries at four temperatures processed using NJOY_. To use this data with
-OpenMC, a script is provided with OpenMC that will automatically download and
-extract the ACE data, fix any deficiencies, and create an HDF5 library:
+   `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.
 
-.. code-block:: sh
+.. admonition:: Optional
+   :class: note
 
-    openmc-get-nndc-data
+   `SciPy <https://www.scipy.org/>`_
+      SciPy's special functions, sparse matrices, and spatial data structures
+      are used for several optional features in the API.
 
-At this point, you should set the :envvar:`OPENMC_CROSS_SECTIONS` environment
-variable to the absolute path of the file ``nndc_hdf5/cross_sections.xml``. This
-cross section set is used by the test suite.
+   `pandas <http://pandas.pydata.org/>`_
+      Pandas is used to generate tally DataFrames as demonstrated in
+      :ref:`examples_pandas` example notebook.
 
-Using JEFF Cross Sections from OECD/NEA
----------------------------------------
+   `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.
 
-The NEA_ provides processed ACE data from the JEFF_ library. To use this data
-with OpenMC, a script is provided with OpenMC that will automatically download
-and extract the ACE data, fix any deficiencies, and create an HDF5 library.
+   `uncertainties <https://pythonhosted.org/uncertainties/>`_
+      Uncertainties are optionally used for decay data in the :mod:`openmc.data`
+      module.
 
-.. code-block:: sh
+   `Cython <http://cython.org/>`_
+      Cython is used for resonance reconstruction for ENDF data converted to
+      :class:`openmc.data.IncidentNeutron`.
 
-    openmc-get-jeff-data
+   `vtk <http://www.vtk.org/>`_
+      The Python VTK bindings are needed to convert voxel and track files to VTK
+      format.
 
-At this point, you should set the :envvar:`OPENMC_CROSS_SECTIONS` environment
-variable to the absolute path of the file ``jeff-3.2-hdf5/cross_sections.xml``.
+   `silomesh <https://github.com/nhorelik/silomesh>`_
+      The silomesh package is needed to convert voxel and track files to SILO
+      format.
 
-Using Cross Sections from MCNP
-------------------------------
+   `lxml <http://lxml.de/>`_
+      lxml is used for the :ref:`scripts_validate` script.
 
-OpenMC is provided with a script that will automatically convert ENDF/B-VII.0
-and ENDF/B-VII.1 ACE data that is provided with MCNP5 or MCNP6. To convert the
-ENDF/B-VII.0 ACE files (``endf70[a-k]`` and ``endf70sab``) into the native HDF5
-format, run the following:
-
-.. code-block:: sh
-
-    openmc-convert-mcnp70-data /path/to/mcnpdata/
-
-where ``/path/to/mcnpdata`` is the directory containing the ``endf70[a-k]``
-files.
-
-To convert the ENDF/B-VII.1 ACE files (the endf71x and ENDF71SaB libraries), use
-the following script:
-
-.. code-block:: sh
-
-    openmc-convert-mcnp71-data /path/to/mcnpdata
-
-where ``/path/to/mcnpdata`` is the directory containing the ``endf71x`` and
-``ENDF71SaB`` directories.
-
-.. _other_cross_sections:
-
-Using Other Cross Sections
---------------------------
-
-If you have a library of ACE format cross sections other than those listed above
-that you need to convert to OpenMC's HDF5 format, the ``openmc-ace-to-hdf5``
-script can be used. 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 ``openmc-ace-to-hdf5`` script has the following command-line flags:
-
--h, --help            show this help message and exit
-
--d DESTINATION, --destination DESTINATION
-                      Directory to create new library in (default: .)
-
--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
-                      (default: None)
-
---xsdir XSDIR         MCNP xsdir file that lists ACE libraries (default:
-                      None)
-
---xsdata XSDATA       Serpent xsdata file that lists ACE libraries (default:
-                      None)
-
---fission_energy_release FISSION_ENERGY_RELEASE
-                      HDF5 file containing fission energy release data
-                      (default: None)
-
-
-Using 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 the user has 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.
-
-.. _NJOY: http://t2.lanl.gov/nis/codes/NJOY12/
-.. _NNDC: http://www.nndc.bnl.gov/endf/b7.1/acefiles.html
-.. _NEA: http://www.oecd-nea.org
-.. _JEFF: https://www.oecd-nea.org/dbforms/data/eva/evatapes/jeff_32/
-.. _MCNP: http://mcnp.lanl.gov
-.. _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
+.. _usersguide_nxml:
 
 -----------------------------------------------------
 Configuring Input Validation with GNU Emacs nXML mode
@@ -573,4 +465,5 @@ schemas.xml file in your own OpenMC source directory.
 .. _GNU Emacs: http://www.gnu.org/software/emacs/
 .. _validation: http://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

docs/source/usersguide/materials.rst

@@ -0,0 +1,169 @@
+.. _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 are
+expanded to the naturally-occurring isotopes.
+
+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 (either through the
+:attr:`Materials.cross_sections` attribute or 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/

docs/source/usersguide/parallel.rst

@@ -0,0 +1,112 @@
+.. _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. To use OpenMP, you need to pass the ``-Dopenmp=on`` flag when running
+``CMake``:
+
+.. code-block:: sh
+
+    cmake -Dopenmp=on /path/to/openmc/root
+    make
+
+The only requirement is that the Fortran 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

docs/source/usersguide/plots.rst

@@ -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/SVG/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 or SILO
+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.

docs/source/usersguide/processing.rst

@@ -4,185 +4,18 @@
 Data Processing and Visualization
 =================================
 
-This section is intended to explain in detail the recommended 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>`. Both the provided scripts and the Python API rely on a number
-third-party Python packages, including:
+.. currentmodule:: openmc
 
-* [1]_ `NumPy <http://www.numpy.org/>`_
-* [2]_ `h5py <http://www.h5py.org>`_
-* [3]_ `pandas <http://pandas.pydata.org>`_
-* [4]_ `matplotlib <http://matplotlib.org/>`_
-* [4]_ `Silomesh <https://github.com/nhorelik/silomesh>`_
-* [4]_ `VTK <http://www.vtk.org/>`_
-* [4]_ `lxml <http://lxml.de>`_
+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>`.
 
-Most of these are can easily be installed with `pip <https://pip.pypa.io>`_
-or alternatively obtaining through a package manager.
+.. _usersguide_statepoint:
 
-.. [1] Required for most post-processing tasks
-.. [2] Required for reading HDF5 output files
-.. [3] Optional dependency for advanced features in Python API
-.. [4] Not used directly by the Python API, but are optional dependencies for a
-       number of scripts.
-
-----------------------
-Geometry Visualization
-----------------------
-
-Geometry plotting is carried out by creating a plots.xml, specifying plots, and
-running OpenMC with the --plot or -p command-line option (See
-:ref:`usersguide_plotting`).
-
-Plotting in 2D
---------------
-
-.. image:: ../_images/atr.png
-   :height: 200px
-
-See below for a simple example of a plots xml file that demonstrates the
-capabilities of 2D slice plots. Here we assume that there is a ``geometry.xml``
-file containing 7 cells.
-
-.. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8"?>
-        <plots>
-
-          <plot id="1" type="slice" color="cell" basis="xy">
-              <filename> myplot </filename>
-              <origin> 0 0 </origin>
-              <width> 10 10 </width>
-              <pixels> 2000 2000 </pixels>
-              <background> 0 0 0 </background>
-              <col_spec id="1" rgb="198 226 255"/>
-              <col_spec id="2" rgb="255 218 185"/>
-              <col_spec id="3" rgb="255 255 255"/>
-              <col_spec id="4" rgb="101 101 101"/>
-              <col_spec id="7" rgb="123 123 231"/>
-              <mask background="255 255 255">
-                <components> 1 3 4 5 6 </components>
-              </mask>
-          </plot>
-
-        </plots>
-
-
-In this example, OpenMC will produce a plot named ``myplot.ppm`` when run in
-plotting mode. The picture will be on the xy-plane, depicting the rectangle
-between points (-5,-5) and (5,5) with 2000 pixels along each dimension. 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. In this example, pixels are 10/2000=0.005 cm wide, so points will be
-at (-4.9975,-4.9975), (-4.9950,-4.9975), (-4.9925,-4.9975), etc. This is pointed
-out to demonstrate that this plot may miss any features smaller than 0.005 cm,
-since they could exist between pixel centers. More pixels can be used to resolve
-finer features, but could result in larger files.
-
-The ``background``, ``col_spec``, and ``mask`` elements define how to set pixel
-colors based on the cell ids at each pixel center. In this example, RGB colors
-are specified for cells 1,2,3,4, and 7, a random color will be assigned to cells
-5 and 6, and a black background color (``rgb="0 0 0"``) will be applied to
-locations where no cell is defined. However, the ``mask`` element here says that
-only cells 1,3,4,5, and 6 should be displayed, with other cells taking a white
-color (``rgb="255 255 255"``), which overrides the ``col_spec`` for cell 2 and
-the random color assigned to cell 7.
-
-After running OpenMC to obtain PPM files, images should be saved to another
-format before using them elsewhere. This cuts down the size of the file by
-orders of magnitude.  Most image viewers and editors that can view PPM images
-can also save to other formats (e.g. `Gimp <http://www.gimp.org/>`_, `IrfanView
-<http://www.irfanview.com/>`_, etc.).  However, more likely the user will want to
-convert to another format on the command line.  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
-Ubuntu: ``sudo apt-get install imagemagick``).  Images are then converted like:
-
-.. code-block:: sh
-
-    convert myplot.ppm myplot.png
-
-Plotting in 3D
---------------
-
-.. image:: ../_images/3dgeomplot.png
-   :height: 200px
-
-See below for a simple example of a plots xml file that demonstrates the
-capabilities of 3D voxel plots.
-
-.. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8"?>
-        <plots>
-
-          <plot id="1" type="voxel" color="mat">
-              <filename> myplot </filename>
-              <origin> 0 0 0 </origin>
-              <width> 10 10 10 </width>
-              <pixels> 500 500 500 </pixels>
-          </plot>
-
-        </plots>
-
-Voxel plots are built the same way 2D slice plots are, by determining the cell
-or material id of a particle at the center of each voxel. In this example, the
-space covered is the cube between the points (-5,-5,-5) and (5,5,5), with voxel
-centers 10/500 = 0.02 cm apart. The HDF5 voxel files that are produced do not
-specify any color - instead containing only material or cell ids (material id
-in this example) - and thus the ``background``, ``col_spec``, and ``mask``
-elements are not used. If no cell is found at a voxel center, an id of -1 is
-stored.
-
-The voxel plot data is written to an HDF5 file. The voxel file can subsequently
-be converted into a standard mesh format that can be viewed in ParaView, Visit,
-etc. This typically will compress the size of the file significantly. The
-provided utility openmc-voxel-to-silovtk accomplishes this for SILO:
-
-.. code-block:: sh
-
-    openmc-voxel-to-silovtk myplot.voxel -o output.silo
-
-and VTK file formats:
-
-.. code-block:: sh
-
-    openmc-voxel-to-silovtk myplot.voxel --vtk -o output.vti
-
-To use this utility you need either
-
-* `Silomesh <https://github.com/nhorelik/silomesh>`_
-
-or
-
-* `VTK <http://www.vtk.org/>`_ with python bindings. On debian derivatives,
-  these are easily obtained with ``sudo apt-get install python-vtk``
-
-For the HDF5 file structure, see :ref:`io_voxel`.
-
-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.
-
-.. image:: ../_images/3dba.png
-   :height: 200px
-
-.. 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. For
-          instance, the 3D pin lattice figure at the beginning of this section
-          was generated with a 500x500x1 voxel mesh, which allows for resolution
-          of the cylinders without wasting too many voxels on the axial
-          dimension.
-
-
--------------------
-Tally Visualization
--------------------
+-------------------------
+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
@@ -208,109 +41,12 @@ 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. Note, however,
-that there is also a script distributed with OpenMC, ``openmc-plot-mesh-tally``,
-that provides an interactive GUI to explore and plot mesh tallies for any scores
-and filter bins.
+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
-   :height: 200px
-
-Plotting in 3D
---------------
-
-.. image:: ../_images/3dcore.png
-   :height: 200px
-
-As with 3D plots of the geometry, meshtally data needs to be put into a standard
-format for viewing. The utility ``openmc-statepoint-3d`` is provided to
-accomplish this for both VTK and SILO. By default ``openmc-statepoint-3d``
-processes a statepoint into a 3D file with all mesh tallies and filter/score
-combinations,
-
-.. code-block:: sh
-
-    openmc-statepoint-3d <statepoint_file> -o output.silo
-    openmc-statepoint-3d <statepoint_file> --vtk -o output.vtm
-
-but it also provides several command-line options to selectively process only
-certain data arrays in order to keep file sizes down.
-
-.. code-block:: sh
-
-    openmc-statepoint-3d <statepoint_file> --tallies 2,4 --scores 4.1,4.3 -o output.silo
-    openmc-statepoint-3d <statepoint_file> --filters 2.energyin.1 --vtk -o output.vtm
-
-All available options for specifying a subset of tallies, scores, and filters
-can be listed with the ``--list`` or ``-l`` command line options.
-
-.. note:: Note that while SILO files can contain multiple meshes in one file,
-          VTK needs to use a multi-block dataset, which stores each mesh piece
-          in a different file in a subfolder.  All meshes can be loaded at once
-          with the main VTM file, or each VTI file in the subfolder can be
-          loaded individually.
-
-Alternatively, the user can write their own Python script to manipulate the data
-appropriately before insertion into a SILO or VTK file.  For instance, if the
-data has been extracted as was done in the 2D plotting example script above, a
-SILO file can be created with:
-
-.. code-block:: python
-
-    import silomesh as sm
-    sm.init_silo("fluxtally.silo")
-    sm.init_mesh('tally_mesh', *mesh.dimension, *mesh.lower_left, *mesh.upper_right)
-    sm.init_var('flux_tally_thermal')
-    for x in range(1,nx+1):
-      for y in range(1,ny+1):
-          for z in range(1,nz+1):
-            sm.set_value(float(thermal[(x,y,z)]),x,y,z)
-    sm.finalize_var()
-    sm.init_var('flux_tally_fast')
-    for x in range(1,nx+1):
-      for y in range(1,ny+1):
-          for z in range(1,nz+1):
-              sm.set_value(float(fast[(x,y,z)]),x,y,z)
-    sm.finalize_var()
-    sm.finalize_mesh()
-    sm.finalize_silo()
-
-and the equivalent VTK file with:
-
-.. code-block:: python
-
-    import vtk
-
-    grid = vtk.vtkImageData()
-    grid.SetDimensions(nx+1,ny+1,nz+1)
-    grid.SetOrigin(*mesh.lower_left)
-    grid.SetSpacing(*mesh.width)
-
-    # vtk cell arrays have x on the inners, so we need to reorder the data
-    idata = {}
-    for x in range(nx):
-      for y in range(ny):
-        for z in range(nz):
-          i = z*nx*ny + y*nx + x
-          idata[i] = (x,y,z)
-
-    vtkfastdata = vtk.vtkDoubleArray()
-    vtkfastdata.SetName("fast")
-    for i in range(nx*ny*nz):
-      vtkfastdata.InsertNextValue(fast[idata[i]])
-
-    vtkthermaldata = vtk.vtkDoubleArray()
-    vtkthermaldata.SetName("thermal")
-    for i in range(nx*ny*nz):
-      vtkthermaldata.InsertNextValue(thermal[idata[i]])
-
-    grid.GetCellData().AddArray(vtkfastdata)
-    grid.GetCellData().AddArray(vtkthermaldata)
-
-    writer = vtk.vtkXMLImageDataWriter()
-    writer.SetInput(grid)
-    writer.SetFileName('tally.vti')
-    writer.Write()
+   :width: 400px
 
 Getting Data into MATLAB
 ------------------------
@@ -322,44 +58,40 @@ the process is straightforward. First extract the data using the Python API via
 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
-   :height: 200px
+   :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
+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 OpenMC with the argument "-t", "-track", or "--track" will cause a track
-file to be created for every particle transported in the code.
+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::
 
-The settings.xml file can dictate that specific particle tracks are output.
-These particles are specified within a ''track'' element.  The ''track'' element
-should contain triplets of integers specifying the batch, generation, and
-particle numbers, respectively.  For example, to output the tracks for particles
-3 and 4 of batch 1 and generation 2 the settings.xml file should contain:
+  settings = openmc.Settings()
+  settings.track = (1, 2, 4)
 
-.. code-block:: xml
+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::
 
-      <track>
-        1 2 3
-        1 2 4
-      </track>
+  settings.track = (1, 2, 3, 1, 2, 4)
 
-After running OpenMC, the directory should contain a file of the form
+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
-``openmc-track-to-vtk`` utility.  The usage of ``openmc-track-to-vtk`` is of the
-form "openmc-track-to-vtk [-o OUT] IN" where OUT is the optional output filename
-and IN is one or more filenames describing track files.  The default output name
-is "track.pvtp".  A common usage of track.py is "openmc-track-to-vtk track*.h5"
-which will use the data from all binary track files in the directory to write a
-"track.pvtp" VTK output file.  The .pvtp file can then be read and plotted by 3d
-visualization programs such as ParaView.
+:ref:`scripts_track` script.
 
 ----------------------
 Source Site Processing

docs/source/usersguide/scripts.rst

@@ -0,0 +1,283 @@
+.. _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_mcnp70:
+
+------------------------------
+``openmc-convert-mcnp70-data``
+------------------------------
+
+This script converts ENDF/B-VII.0 ACE data from the MCNP5/6 distribution into an
+HDF5 library that can be used by OpenMC. This assumes that you have a directory
+containing files named endf70a, endf70b, ..., endf70k, and endf70sab. The path
+to the directory containing these files should be given as a positional
+argument. The following optional arguments are available:
+
+-d DESTINATION, --destination DESTINATION
+    Directory to create new library in (Default: mcnp_endfb70)
+
+.. _scripts_mcnp71:
+
+------------------------------
+``openmc-convert-mcnp71-data``
+------------------------------
+
+This script converts ENDF/B-VII.1 ACE data from the MCNP6 distribution into an
+HDF5 library that can be used by OpenMC. This assumes that you have a directory
+containing subdirectories 'endf71x' and 'ENDF71SaB'. The path to the directory
+containing these subdirectories should be given as a positional argument. The
+following optional arguments are available:
+
+-d DESTINATION, --destination DESTINATION
+     Directory to create new library in (Default: mcnp_endfb71)
+
+-f FER, --fission_energy_release FER
+     HDF5 file containing fission energy release data
+
+.. _scripts_jeff:
+
+------------------------
+``openmc-get-jeff-data``
+------------------------
+
+This script downloads `JEFF 3.2 ACE data
+<https://www.oecd-nea.org/dbforms/data/eva/evatapes/jeff_32/>`_ from OECD/NEA
+and converts it to a multi-temperature HDF5 library for use with OpenMC. It has
+the following optional arguments:
+
+-b, --batch
+    Suppress standard in
+
+-d DESTINATION, --destination DESTINATION
+    Directory to create new library in (default: jeff-3.2-hdf5)
+
+.. warning:: This script will download approximately 9 GB of data. Extracting
+             and processing the data may require as much as 40 GB of additional
+             free disk space.
+
+.. _scripts_multipole:
+
+-----------------------------
+``openmc-get-multipole-data``
+-----------------------------
+
+This script downloads and extracts windowed multipole data based on
+ENDF/B-VII.1. It has the following optional arguments:
+
+-b, --batch     Suppress standard in
+
+.. _scripts_nndc:
+
+------------------------
+``openmc-get-nndc-data``
+------------------------
+
+This script downloads `ENDF/B-VII.1 ACE data
+<http://www.nndc.bnl.gov/endf/b7.1/acefiles.html>`_ from NNDC and converts it to
+an HDF5 library for use with OpenMC. This data is used for OpenMC's regression
+test suite. This script has the following optional arguments:
+
+-b, --batch     Suppress standard in
+
+.. _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-silovtk``
+---------------------------
+
+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-silovtk`` script converts a voxel HDF5 file to `VTK
+<http://www.vtk.org/>`_ or `SILO
+<https://wci.llnl.gov/simulation/computer-codes/silo>`_ file. For VTK, you need
+to have the VTK Python bindings installed. For SILO, you need to have `silomesh
+<https://github.com/nhorelik/silomesh>`_ installed. To convert a voxel file,
+simply provide the path to the file:
+
+.. code-block:: sh
+
+   openmc-voxel-to-silovtk voxel_1.h5
+
+The ``openmc-voxel-to-silovtk`` script also takes the following optional
+command-line arguments:
+
+-o, --output   Path to output VTK or SILO file
+-s, --silo     Flag to convert to SILO instead of VTK

docs/source/usersguide/settings.rst

@@ -0,0 +1,226 @@
+.. _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]
+
+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
+
+--------------------------
+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)}

docs/source/usersguide/tallies.rst

@@ -0,0 +1,311 @@
+.. _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 called *filters* and the scoring functions are simply called *scores*.
+
+-------
+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'), a reaction rate
+('total', 'fission', etc.), or even scattering moments (e.g., 'scatter-P3'). 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.                                        |
+    +----------------------+---------------------------------------------------+
+    |flux-YN               |Spherical harmonic expansion of the direction of   |
+    |                      |motion :math:`\left(\Omega\right)` of the total    |
+    |                      |flux. This score will tally all of the harmonic    |
+    |                      |moments of order 0 to N.  N must be between 0 and  |
+    |                      |10.                                                |
+    +----------------------+---------------------------------------------------+
+
+.. table:: **Reaction scores: units are reactions per source particle.**
+
+    +----------------------+---------------------------------------------------+
+    |Score                 | Description                                       |
+    +======================+===================================================+
+    |absorption            |Total absorption rate. This accounts for all       |
+    |                      |reactions which do not produce secondary neutrons  |
+    |                      |as well as fission.                                |
+    +----------------------+---------------------------------------------------+
+    |elastic               |Elastic scattering reaction rate.                  |
+    +----------------------+---------------------------------------------------+
+    |fission               |Total fission reaction rate.                       |
+    +----------------------+---------------------------------------------------+
+    |scatter               |Total scattering rate. Can also be identified with |
+    |                      |the "scatter-0" response type.                     |
+    +----------------------+---------------------------------------------------+
+    |scatter-N             |Tally the N\ :sup:`th` \ scattering moment, where N|
+    |                      |is the Legendre expansion order of the change in   |
+    |                      |particle angle :math:`\left(\mu\right)`. N must be |
+    |                      |between 0 and 10. As an example, tallying the 2\   |
+    |                      |:sup:`nd` \ scattering moment would be specified as|
+    |                      |``<scores>scatter-2</scores>``.                    |
+    +----------------------+---------------------------------------------------+
+    |scatter-PN            |Tally all of the scattering moments from order 0 to|
+    |                      |N, where N is the Legendre expansion order of the  |
+    |                      |change in particle angle                           |
+    |                      |:math:`\left(\mu\right)`. That is, "scatter-P1" is |
+    |                      |equivalent to requesting tallies of "scatter-0" and|
+    |                      |"scatter-1".  Like for "scatter-N", N must be      |
+    |                      |between 0 and 10. As an example, tallying up to the|
+    |                      |2\ :sup:`nd` \ scattering moment would be specified|
+    |                      |as ``<scores> scatter-P2 </scores>``.              |
+    +----------------------+---------------------------------------------------+
+    |scatter-YN            |"scatter-YN" is similar to "scatter-PN" except an  |
+    |                      |additional expansion is performed for the incoming |
+    |                      |particle direction :math:`\left(\Omega\right)`     |
+    |                      |using the real spherical harmonics.  This is useful|
+    |                      |for performing angular flux moment weighting of the|
+    |                      |scattering moments. Like "scatter-PN", "scatter-YN"|
+    |                      |will tally all of the moments from order 0 to N; N |
+    |                      |again must be between 0 and 10.                    |
+    +----------------------+---------------------------------------------------+
+    |total                 |Total reaction rate.                               |
+    +----------------------+---------------------------------------------------+
+    |total-YN              |The total reaction rate expanded via spherical     |
+    |                      |harmonics about the direction of motion of the     |
+    |                      |neutron, :math:`\Omega`. This score will tally all |
+    |                      |of the harmonic moments of order 0 to N.  N must be|
+    |                      |between 0 and 10.                                  |
+    +----------------------+---------------------------------------------------+
+    |(n,2nd)               |(n,2nd) reaction rate.                             |
+    +----------------------+---------------------------------------------------+
+    |(n,2n)                |(n,2n) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,3n)                |(n,3n) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,na)                |(n,n\ :math:`\alpha`\ ) reaction rate.             |
+    +----------------------+---------------------------------------------------+
+    |(n,n3a)               |(n,n3\ :math:`\alpha`\ ) reaction rate.            |
+    +----------------------+---------------------------------------------------+
+    |(n,2na)               |(n,2n\ :math:`\alpha`\ ) reaction rate.            |
+    +----------------------+---------------------------------------------------+
+    |(n,3na)               |(n,3n\ :math:`\alpha`\ ) reaction rate.            |
+    +----------------------+---------------------------------------------------+
+    |(n,np)                |(n,np) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,n2a)               |(n,n2\ :math:`\alpha`\ ) reaction rate.            |
+    +----------------------+---------------------------------------------------+
+    |(n,2n2a)              |(n,2n2\ :math:`\alpha`\ ) reaction rate.           |
+    +----------------------+---------------------------------------------------+
+    |(n,nd)                |(n,nd) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,nt)                |(n,nt) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,nHe-3)             |(n,n\ :sup:`3`\ He) reaction rate.                 |
+    +----------------------+---------------------------------------------------+
+    |(n,nd2a)              |(n,nd2\ :math:`\alpha`\ ) reaction rate.           |
+    +----------------------+---------------------------------------------------+
+    |(n,nt2a)              |(n,nt2\ :math:`\alpha`\ ) reaction rate.           |
+    +----------------------+---------------------------------------------------+
+    |(n,4n)                |(n,4n) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,2np)               |(n,2np) reaction rate.                             |
+    +----------------------+---------------------------------------------------+
+    |(n,3np)               |(n,3np) reaction rate.                             |
+    +----------------------+---------------------------------------------------+
+    |(n,n2p)               |(n,n2p) reaction rate.                             |
+    +----------------------+---------------------------------------------------+
+    |(n,n*X*)              |Level inelastic scattering reaction rate. The *X*  |
+    |                      |indicates what which inelastic level, e.g., (n,n3) |
+    |                      |is third-level inelastic scattering.               |
+    +----------------------+---------------------------------------------------+
+    |(n,nc)                |Continuum level inelastic scattering reaction rate.|
+    +----------------------+---------------------------------------------------+
+    |(n,gamma)             |Radiative capture reaction rate.                   |
+    +----------------------+---------------------------------------------------+
+    |(n,p)                 |(n,p) reaction rate.                               |
+    +----------------------+---------------------------------------------------+
+    |(n,d)                 |(n,d) reaction rate.                               |
+    +----------------------+---------------------------------------------------+
+    |(n,t)                 |(n,t) reaction rate.                               |
+    +----------------------+---------------------------------------------------+
+    |(n,3He)               |(n,\ :sup:`3`\ He) reaction rate.                  |
+    +----------------------+---------------------------------------------------+
+    |(n,a)                 |(n,\ :math:`\alpha`\ ) reaction rate.              |
+    +----------------------+---------------------------------------------------+
+    |(n,2a)                |(n,2\ :math:`\alpha`\ ) reaction rate.             |
+    +----------------------+---------------------------------------------------+
+    |(n,3a)                |(n,3\ :math:`\alpha`\ ) reaction rate.             |
+    +----------------------+---------------------------------------------------+
+    |(n,2p)                |(n,2p) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,pa)                |(n,p\ :math:`\alpha`\ ) reaction rate.             |
+    +----------------------+---------------------------------------------------+
+    |(n,t2a)               |(n,t2\ :math:`\alpha`\ ) reaction rate.            |
+    +----------------------+---------------------------------------------------+
+    |(n,d2a)               |(n,d2\ :math:`\alpha`\ ) reaction rate.            |
+    +----------------------+---------------------------------------------------+
+    |(n,pd)                |(n,pd) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,pt)                |(n,pt) reaction rate.                              |
+    +----------------------+---------------------------------------------------+
+    |(n,da)                |(n,d\ :math:`\alpha`\ ) reaction rate.             |
+    +----------------------+---------------------------------------------------+
+    |*Arbitrary integer*   |An arbitrary integer is interpreted to mean the    |
+    |                      |reaction rate for a reaction with a given ENDF MT  |
+    |                      |number.                                            |
+    +----------------------+---------------------------------------------------+
+
+.. table:: **Particle production scores: units are particles produced per
+           source particles.**
+
+    +----------------------+---------------------------------------------------+
+    |Score                 | Description                                       |
+    +======================+===================================================+
+    |delayed-nu-fission    |Total production of delayed neutrons due to        |
+    |                      |fission.                                           |
+    +----------------------+---------------------------------------------------+
+    |prompt-nu-fission     |Total production of prompt neutrons due to         |
+    |                      |fission.                                           |
+    +----------------------+---------------------------------------------------+
+    |nu-fission            |Total production of neutrons due to fission.       |
+    +----------------------+---------------------------------------------------+
+    |nu-scatter,           |These scores are similar in functionality to their |
+    |nu-scatter-N,         |``scatter*`` equivalents except the total          |
+    |nu-scatter-PN,        |production of neutrons due to scattering is scored |
+    |nu-scatter-YN         |vice simply the scattering rate. This accounts for |
+    |                      |multiplicity from (n,2n), (n,3n), and (n,4n)       |
+    |                      |reactions.                                         |
+    +----------------------+---------------------------------------------------+
+
+.. table:: **Miscellaneous scores: units are indicated for each.**
+
+    +----------------------+---------------------------------------------------+
+    |Score                 | Description                                       |
+    +======================+===================================================+
+    |current               |Partial currents on the boundaries of each cell in |
+    |                      |a mesh. Units are particles per source             |
+    |                      |particle. Note that this score can only be used if |
+    |                      |a mesh filter has been specified. Furthermore, it  |
+    |                      |may not be used in conjunction with any other      |
+    |                      |score.                                             |
+    +----------------------+---------------------------------------------------+
+    |events                |Number of scoring events. Units are events per     |
+    |                      |source particle.                                   |
+    +----------------------+---------------------------------------------------+
+    |inverse-velocity      |The flux-weighted inverse velocity where the       |
+    |                      |velocity is in units of centimeters per second.    |
+    +----------------------+---------------------------------------------------+
+    |kappa-fission         |The recoverable energy production rate due to      |
+    |                      |fission. The recoverable energy is defined as the  |
+    |                      |fission product kinetic energy, prompt and delayed |
+    |                      |neutron kinetic energies, prompt and delayed       |
+    |                      |:math:`\gamma`-ray total energies, and the total   |
+    |                      |energy released by the delayed :math:`\beta`       |
+    |                      |particles. The neutrino energy does not contribute |
+    |                      |to this response. The prompt and delayed           |
+    |                      |:math:`\gamma`-rays are assumed to deposit their   |
+    |                      |energy locally. Units are eV per source particle.  |
+    +----------------------+---------------------------------------------------+
+    |fission-q-prompt      |The prompt fission energy production rate. This    |
+    |                      |energy comes in the form of fission fragment       |
+    |                      |nuclei, prompt neutrons, and prompt                |
+    |                      |:math:`\gamma`-rays. This value depends on the     |
+    |                      |incident energy and it requires that the nuclear   |
+    |                      |data library contains the optional fission energy  |
+    |                      |release data. Energy is assumed to be deposited    |
+    |                      |locally. Units are eV per source particle.         |
+    +----------------------+---------------------------------------------------+
+    |fission-q-recoverable |The recoverable fission energy production rate.    |
+    |                      |This energy comes in the form of fission fragment  |
+    |                      |nuclei, prompt and delayed neutrons, prompt and    |
+    |                      |delayed :math:`\gamma`-rays, and delayed           |
+    |                      |:math:`\beta`-rays. This tally differs from the    |
+    |                      |kappa-fission tally in that it is dependent on     |
+    |                      |incident neutron energy and it requires that the   |
+    |                      |nuclear data library contains the optional fission |
+    |                      |energy release data. Energy is assumed to be       |
+    |                      |deposited locally. Units are eV per source         |
+    |                      |paticle.                                           |
+    +----------------------+---------------------------------------------------+
+    |decay-rate            |The delayed-nu-fission-weighted decay rate where   |
+    |                      |the decay rate is in units of inverse seconds.     |
+    +----------------------+---------------------------------------------------+

docs/source/usersguide/volume.rst

@@ -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.

man/man1/openmc.1

@@ -47,17 +47,17 @@ is affected by the following environment variables.
 Indicates the default path to the cross_sections.xml summary file that is used
 to locate HDF5 format cross section libraries if the user has not specified the
 <cross_sections> tag in
-.I settings.xml\fP.
+.I materials.xml\fP.
 .TP
 .B OPENMC_MG_CROSS_SECTIONS
-Indicates the default path to the mgxs.xml file that contains multi-group cross
+Indicates the default path to an HDF5 file that contains multi-group cross
 section libraries if the user has not specified the <cross_sections> tag in
-.I settings.xml\fP.
+.I materials.xml\fP.
 .TP
 .B OPENMC_MULTIPOLE_LIBRARY
 Indicates the default path to a directory containing windowed multipole data if
 the user has not specified the <multipole_library> tag in
-.I settings.xml\fP.
+.I materials.xml\fP.
 .SH LICENSE
 Copyright \(co 2011-2017 Massachusetts Institute of Technology.
 .PP

openmc/lattice.py

@@ -367,7 +367,7 @@ class Lattice(object):
         return all_universes
 
     def get_universe(self, idx):
-        """Return universe corresponding to a lattice element index
+        r"""Return universe corresponding to a lattice element index
 
         Parameters
         ----------

openmc/material.py

@@ -29,8 +29,13 @@ DENSITY_UNITS = ['g/cm3', 'g/cc', 'kg/cm3', 'atom/b-cm', 'atom/cm3', 'sum',
 
 
 class Material(object):
-    """A material composed of a collection of nuclides/elements that can be
-    assigned to a region of space.
+    """A material composed of a collection of nuclides/elements.
+
+    To create a material, one should create an instance of this class, add
+    nuclides or elements with :meth:`Material.add_nuclide` or
+    `Material.add_element`, respectively, and set the total material density
+    with `Material.export_to_xml()`. The material can then be assigned to a cell
+    using the :attr:`Cell.fill` attribute.
 
     Parameters
     ----------

openmc/settings.py

@@ -71,11 +71,12 @@ class Settings(object):
         Indicate that all user-defined and global tallies should not be reduced
         across processes in a parallel calculation.
     output : dict
-        Dictionary indicating what files to output. Valid keys are 'summary',
-        'cross_sections', 'tallies', and 'distribmats'. Values corresponding to
-        each key should be given as a boolean value.
-    output_path : str
-        Path to write output to
+        Dictionary indicating what files to output. Acceptable keys are:
+
+        :path: String indicating a directory where output files should be
+               written
+        :summary: Whether the 'summary.h5' file should be written (bool)
+        :tallies: Whether the 'tallies.out' file should be written (bool)
     particles : int
         Number of particles per generation
     ptables : bool
@@ -193,7 +194,6 @@ class Settings(object):
         self._trigger_batch_interval = None
 
         self._output = None
-        self._output_path = None
 
         # Output options
         self._statepoint = {}
@@ -315,10 +315,6 @@ class Settings(object):
     def output(self):
         return self._output
 
-    @property
-    def output_path(self):
-        return self._output_path
-
     @property
     def sourcepoint(self):
         return self._sourcepoint
@@ -479,30 +475,15 @@ class Settings(object):
 
     @output.setter
     def output(self, output):
-        if not isinstance(output, dict):
-            msg = 'Unable to set output to "{0}" which is not a Python ' \
-                  'dictionary of string keys and boolean values'.format(output)
-            raise ValueError(msg)
-
-        for element in output:
-            keys = ['summary', 'cross_sections', 'tallies', 'distribmats']
-            if element not in keys:
-                msg = 'Unable to set output to "{0}" which is unsupported by ' \
-                      'OpenMC'.format(element)
-                raise ValueError(msg)
-
-            if not isinstance(output[element], (bool, np.bool)):
-                msg = 'Unable to set output for "{0}" to a non-boolean ' \
-                      'value "{1}"'.format(element, output[element])
-                raise ValueError(msg)
-
+        cv.check_type('output', output, Mapping)
+        for key, value in output.items():
+            cv.check_value('output key', key, ('summary', 'tallies', 'path'))
+            if key in ('summary', 'tallies'):
+                cv.check_type("output['{}']".format(key), value, bool)
+            else:
+                cv.check_type("output['path']", value, string_types)
         self._output = output
 
-    @output_path.setter
-    def output_path(self, output_path):
-        cv.check_type('output path', output_path, string_types)
-        self._output_path = output_path
-
     @verbosity.setter
     def verbosity(self, verbosity):
         cv.check_type('verbosity', verbosity, Integral)
@@ -876,13 +857,12 @@ class Settings(object):
         if self._output is not None:
             element = ET.SubElement(root, "output")
 
-            for key in self._output:
+            for key, value in self._output.items():
                 subelement = ET.SubElement(element, key)
-                subelement.text = str(self._output[key]).lower()
-
-            if self._output_path is not None:
-                element = ET.SubElement(root, "output_path")
-                element.text = self._output_path
+                if key in ('summary', 'tallies'):
+                    subelement.text = str(value).lower()
+                else:
+                    subelement.text = value
 
     def _create_verbosity_subelement(self, root):
         if self._verbosity is not None:

openmc/surface.py

@@ -1177,7 +1177,7 @@ class Sphere(Surface):
         y-coordinate of the center of the sphere
     z0 : float
         z-coordinate of the center of the sphere
-    R : float
+    r : float
         Radius of the sphere
     boundary_type : {'transmission, 'vacuum', 'reflective'}
         Boundary condition that defines the behavior for particles hitting the
@@ -1325,7 +1325,7 @@ class Cone(Surface):
         y-coordinate of the apex
     z0 : float
         z-coordinate of the apex
-    R2 : float
+    r2 : float
         Parameter related to the aperature
     boundary_type : {'transmission, 'vacuum', 'reflective'}
         Boundary condition that defines the behavior for particles hitting the
@@ -2033,4 +2033,4 @@ def get_hexagonal_prism(edge_length=1., orientation='y',
         # y = sqrt(3)*(x + a)
         upper_left = Plane(A=-c, B=1., D=c*l, boundary_type=boundary_type)
         return Intersection(-top, +bottom, -upper_right, +lower_right,
-                            +lower_left, -upper_left)
+                            +lower_left, -upper_left)

readme.rst

@@ -10,10 +10,10 @@ transport code based on modern methods. It is a constructive solid geometry,
 continuous-energy transport code that uses HDF5 format cross sections. The
 project started under the Computational Reactor Physics Group at MIT.
 
-Complete documentation on the usage of OpenMC is hosted on Read the Docs at
-http://openmc.readthedocs.io. If you are interested in the project or would like
-to help and contribute, please send a message to the OpenMC User's Group
-`mailing list`_.
+Complete documentation on the usage of OpenMC is hosted on Read the Docs (both
+for the `latest release`_ and developmental_ version). If you are interested in
+the project or would like to help and contribute, please send a message to the
+OpenMC User's Group `mailing list`_.
 
 ------------
 Installation
@@ -48,8 +48,10 @@ License
 
 OpenMC is distributed under the MIT/X license_.
 
+.. _latest release: http://openmc.readthedocs.io/en/stable/
+.. _developmental: http://openmc.readthedocs.io/en/latest/
 .. _mailing list: https://groups.google.com/forum/?fromgroups=#!forum/openmc-users
-.. _installation instructions: http://openmc.readthedocs.io/en/latest/usersguide/install.html
-.. _Troubleshooting section: http://openmc.readthedocs.io/en/latest/usersguide/troubleshoot.html
+.. _installation instructions: http://openmc.readthedocs.io/en/stable/usersguide/install.html
+.. _Troubleshooting section: http://openmc.readthedocs.io/en/stable/usersguide/troubleshoot.html
 .. _Issues: https://github.com/mit-crpg/openmc/issues
-.. _license: http://openmc.readthedocs.io/en/latest/license.html
+.. _license: http://openmc.readthedocs.io/en/stable/license.html

scripts/openmc-get-nndc-data

@@ -18,7 +18,7 @@ import openmc.data
 
 description = """
 Download ENDF/B-VII.1 ACE data from NNDC and convert it to an HDF5 library for
-use with OpenMC.
+use with OpenMC. This data is used for OpenMC's regression test suite.
 
 """
 

scripts/openmc-memory-usage

@@ -1,62 +0,0 @@
-#!/usr/bin/env python
-
-"""
-This script reads a cross_sections.out file, adds up the memory usage for each
-nuclide and S(a,b) table, and displays the total memory usage.
-
-"""
-
-from __future__ import print_function
-
-import sys
-import os
-
-if len(sys.argv) > 1:
-    # Get path to cross_sections.out file from command line argument
-    filename = sys.argv[-1]
-else:
-    # Set default path for cross_sections.out
-    filename = 'cross_sections.out'
-    if not os.path.exists(filename):
-        raise OSError('Could not find cross_sections.out file!')
-
-# Open file handle for cross_sections.out file
-f = open(filename, 'r')
-
-# Initialize memory size arrays
-memory_xs = []
-memory_angle = []
-memory_energy = []
-memory_urr = []
-memory_total = []
-memory_sab = []
-
-while True:
-    # Read next line in file
-    line = f.readline()
-
-    # Check for EOF
-    if line == '':
-        break
-
-    # Look for block listing memory usage for a nuclide
-    words = line.split()
-    if len(words) == 2 and words[0] == 'Memory':
-        memory_xs.append(int(f.readline().split()[-2]))
-        memory_angle.append(int(f.readline().split()[-2]))
-        memory_energy.append(int(f.readline().split()[-2]))
-        memory_urr.append(int(f.readline().split()[-2]))
-        memory_total.append(int(f.readline().split()[-2]))
-
-    # Look for memory usage for S(a,b) table
-    if len(words) == 5 and words[1] == 'Used':
-        memory_sab.append(int(words[-2]))
-
-# Write out summary memory usage
-print('Memory Requirements')
-print('  Reaction Cross Sections        = ' + str(sum(memory_xs)))
-print('  Secondary Angle Distributions  = ' + str(sum(memory_angle)))
-print('  Secondary Energy Distributions = ' + str(sum(memory_energy)))
-print('  Probability Tables             = ' + str(sum(memory_urr)))
-print('  S(a,b) Tables                  = ' + str(sum(memory_sab)))
-print('  Total                          = ' + str(sum(memory_total)))

scripts/openmc-plot-mesh-tally

@@ -4,6 +4,7 @@
 
 import os
 import sys
+import argparse
 
 import six.moves.tkinter as tk
 import six.moves.tkinter_filedialog as filedialog
@@ -16,17 +17,17 @@ from matplotlib.figure import Figure
 import matplotlib.pyplot as plt
 import numpy as np
 
-from openmc.statepoint import StatePoint
+from openmc import StatePoint, MeshFilter
 
 
 class MeshPlotter(tk.Frame):
     def __init__(self, parent, filename):
         tk.Frame.__init__(self, parent)
 
-        self.labels = {'cell': 'Cell:', 'cellborn': 'Cell born:',
-                       'surface': 'Surface:', 'material': 'Material:',
-                       'universe': 'Universe:', 'energy': 'Energy in:',
-                       'energyout': 'Energy out:'}
+        self.labels = {'Cell': 'Cell:', 'Cellborn': 'Cell born:',
+                       'Surface': 'Surface:', 'Material': 'Material:',
+                       'Universe': 'Universe:', 'Energy': 'Energy in:',
+                       'Energyout': 'Energy out:'}
 
         self.filterBoxes = {}
 
@@ -122,7 +123,7 @@ class MeshPlotter(tk.Frame):
         selectedTally = self.datafile.tallies[tally_id]
 
         # Get mesh for selected tally
-        self.mesh = selectedTally.filters_by_name['mesh'].mesh
+        self.mesh = selectedTally.find_filter(MeshFilter).mesh
 
         # Get mesh dimensions
         if len(self.mesh.dimension) == 2:
@@ -160,8 +161,8 @@ class MeshPlotter(tk.Frame):
         # create a label/combobox for each filter in selected tally
         count = 0
         for f in selectedTally.filters:
-            filterType = f.type
-            if filterType == 'mesh':
+            filterType = f.short_name
+            if filterType == 'Mesh':
                 continue
             count += 1
 
@@ -172,7 +173,7 @@ class MeshPlotter(tk.Frame):
             self.filterBoxes[filterType] = combobox
 
             # Set combobox items
-            if filterType in ['energy', 'energyout']:
+            if filterType in ['Energy', 'Energyout']:
                 combobox['values'] = ['{0} to {1}'.format(*f.bins[i:i+2])
                                       for i in range(len(f.bins) - 1)]
             else:
@@ -202,16 +203,16 @@ class MeshPlotter(tk.Frame):
         # Create spec_list
         spec_list = []
         for f in selectedTally.filters:
-            if f.type == 'mesh':
+            if f.short_name == 'Mesh':
                 mesh_filter = f
                 continue
-            elif f.type in ['energy', 'energyout']:
-                index = self.filterBoxes[f.type].current()
+            elif f.short_name in ['Energy', 'Energyout']:
+                index = self.filterBoxes[f.short_name].current()
                 ebin = (f.bins[index], f.bins[index + 1])
-                spec_list.append((f.type, (ebin,)))
+                spec_list.append((type(f), (ebin,)))
             else:
-                index = self.filterBoxes[f.type].current()
-                spec_list.append((f.type, (index,)))
+                index = self.filterBoxes[f.short_name].current()
+                spec_list.append((type(f), (index,)))
 
         text = self.basisBox.get()
         if text == 'xy':
@@ -230,7 +231,7 @@ class MeshPlotter(tk.Frame):
                 else:
                     meshtuple = (i + 1, axial_level, j + 1)
                 filters, filter_bins = zip(*spec_list + [
-                    (mesh_filter.type, (meshtuple,))])
+                    (type(mesh_filter), (meshtuple,))])
                 mean = selectedTally.get_values(
                     [self.scoreBox.get()], filters, filter_bins)
                 stdev = selectedTally.get_values(
@@ -268,10 +269,9 @@ class MeshPlotter(tk.Frame):
 
         # Find which tallies are mesh tallies
         self.meshTallies = []
-        for itally, tally in self.datafile.tallies.iteritems():
-            if any([f.type == 'mesh' for f in tally.filters]):
+        for itally, tally in self.datafile.tallies.items():
+            if any([isinstance(f, MeshFilter) for f in tally.filters]):
                 self.meshTallies.append(itally)
-                tally.filters_by_name = {f.type: f for f in tally.filters}
 
         if not self.meshTallies:
             messagebox.showerror("Invalid StatePoint File",
@@ -280,16 +280,20 @@ class MeshPlotter(tk.Frame):
 
 
 if __name__ == '__main__':
+    parser = argparse.ArgumentParser()
+    parser.add_argument('statepoint', nargs='?', help='Statepoint file')
+    args = parser.parse_args()
+
     # Hide root window
     root = tk.Tk()
     root.withdraw()
 
     # If no filename given as command-line argument, open file dialog
-    if len(sys.argv) < 2:
+    if args.statepoint is None:
         filename = filedialog.askopenfilename(title='Select statepoint file',
                                               initialdir='.')
     else:
-        filename = sys.argv[1]
+        filename = args.statepoint
 
     if filename:
         # Check to make sure file exists

scripts/openmc-statepoint-3d

@@ -1,393 +0,0 @@
-#!/usr/bin/env python2
-
-from __future__ import division, print_function
-
-import sys
-import itertools
-import re
-import warnings
-
-from openmc.statepoint import StatePoint
-
-alphanum = re.compile(r"[\W_]+")
-
-err = False
-
-################################################################################
-def parse_options():
-  """Process command line arguments"""
-
-
-
-  def tallies_callback(option, opt, value, parser):
-    """Option parser function for list of tallies"""
-    global err
-    try:
-      setattr(parser.values, option.dest, [int(v) for v in value.split(',')])
-    except:
-      p.print_help()
-      err = True
-
-  def scores_callback(option, opt, value, parser):
-    """Option parser function for list of scores"""
-    global err
-    try:
-      scores = {}
-      entries = value.split(',')
-      for e in entries:
-        tally,score = [int(i) for i in e.split('.')]
-        if not tally in scores: scores[tally] = []
-        scores[tally].append(score)
-      setattr(parser.values, option.dest, scores)
-    except:
-      p.print_help()
-      err = True
-
-  def filters_callback(option, opt, value, parser):
-    """Option parser function for list of filters"""
-    global err
-    try:
-      filters = {}
-      entries = value.split(',')
-      for e in entries:
-        tally,filter_,bin = [i for i in e.split('.')]
-        tally,bin = int(tally),int(bin)
-        if not tally in filters: filters[tally] = {}
-        if not filter_ in filters[tally]: filters[tally][filter_] = []
-        filters[tally][filter_].append(bin)
-      setattr(parser.values, option.dest, filters)
-    except:
-      p.print_help()
-      err = True
-
-  from optparse import OptionParser
-  usage = r"""%prog [options] <statepoint_file>
-
-The default is to process all tallies and all scores into one file. Subsets
-can be chosen using the options.  For example, to only process tallies 2 and 4
-with all scores on tally 2 and only scores 1 and 3 on tally 4:
-
-%prog -t 2,4 -s 4.1,4.3 <statepoint_file>
-
-Likewise if you have additional filters on a tally you can specify a subset of
-bins for each filter for that tally. For example to process all tallies and
-scores, but only energyin bin #1 in tally 2:
-
-%prog -f 2.energyin.1 <statepoint_file>
-
-You can list the available tallies, scores, and filters with the -l option:
-
-%prog -l <statepoint_file>"""
-  p = OptionParser(usage=usage)
-  p.add_option('-t', '--tallies', dest='tallies', type='string', default=None,
-                action='callback', callback=tallies_callback,
-                help='List of tally indices to process, separated by commas.' \
-                     ' Default is to process all tallies.')
-  p.add_option('-s', '--scores', dest='scores', type='string', default=None,
-               action='callback', callback=scores_callback,
-               help='List of score indices to process, separated by commas, ' \
-                 'specified as {tallyid}.{scoreid}.' \
-                 ' Default is to process all scores in each tally.')
-  p.add_option('-f', '--filters', dest='filters', type='string', default=None,
-               action='callback', callback=filters_callback,
-               help='List of filter bins to process, separated by commas, ' \
-                 'specified as {tallyid}.{filter}.{binid}. ' \
-                 'Default is to process all filter combinaiton for each score.')
-  p.add_option('-l', '--list', dest='list', action='store_true',
-               help='List the tally and score indices available in the file.')
-  p.add_option('-o', '--output', action='store', dest='output',
-               default='tally', help='path to output SILO file.')
-  p.add_option('-e', '--error', dest='valerr', default=False,
-               action='store_true',
-               help='Flag to extract errors instead of values.')
-  p.add_option('-v', '--vtk', action='store_true', dest='vtk',
-               default=False, help='Flag to convert to VTK instead of SILO.')
-  parsed = p.parse_args()
-
-  if not parsed[1]:
-    p.print_help()
-    return parsed, err
-
-  if parsed[0].valerr:
-    parsed[0].valerr = 1
-  else:
-    parsed[0].valerr = 0
-
-  return parsed, err
-
-################################################################################
-def main(file_, o):
-  """Main program"""
-
-  sp = StatePoint(file_)
-  sp.read_results()
-
-  validate_options(sp, o)
-
-  if o.list:
-    print_available(sp)
-    return
-
-  if o.vtk:
-    if not o.output[-4:] == ".vtm": o.output += ".vtm"
-  else:
-    if not o.output[-5:] == ".silo": o.output += ".silo"
-
-  if o.vtk:
-    try:
-      import vtk
-    except:
-      print('The vtk python bindings do not appear to be installed properly.\n'
-            'On Ubuntu: sudo apt-get install python-vtk\n'
-            'See: http://www.vtk.org/')
-      return
-  else:
-    try:
-      import silomesh
-    except:
-      print('The silomesh package does not appear to be installed properly.\n'
-            'See: https://github.com/nhorelik/silomesh/')
-      return
-
-  if o.vtk:
-    blocks = vtk.vtkMultiBlockDataSet()
-    blocks.SetNumberOfBlocks(5)
-    block_idx = 0
-  else:
-    silomesh.init_silo(o.output)
-
-  # Tally loop #################################################################
-  for tally in sp.tallies:
-
-    # skip non-mesh tallies or non-user-specified tallies
-    if o.tallies and not tally.id in o.tallies: continue
-    if not 'mesh' in tally.filters: continue
-
-    print("Processing Tally {}...".format(tally.id))
-
-    # extract filter options and mesh parameters for this tally
-    filtercombos = get_filter_combos(tally)
-    meshparms = get_mesh_parms(sp, tally)
-    nx,ny,nz = meshparms[:3]
-    ll = meshparms[3:6]
-    ur = meshparms[6:9]
-
-    if o.vtk:
-      ww = [(u-l)/n for u,l,n in zip(ur,ll,(nx,ny,nz))]
-      grid = grid = vtk.vtkImageData()
-      grid.SetDimensions(nx+1,ny+1,nz+1)
-      grid.SetOrigin(*ll)
-      grid.SetSpacing(*ww)
-    else:
-      silomesh.init_mesh('Tally_{}'.format(tally.id), *meshparms)
-
-    # Score loop ###############################################################
-    for sid,score in enumerate(tally.scores):
-
-      # skip non-user-specified scrores for this tally
-      if o.scores and tally.id in o.scores and not sid in o.scores[tally.id]:
-        continue
-
-      # Filter loop ############################################################
-      for filterspec in filtercombos:
-
-        # skip non-user-specified filter bins
-        skip = False
-        if o.filters and tally.id in o.filters:
-          for filter_,bin in filterspec[1:]:
-            if filter_ in o.filters[tally.id] and \
-               not bin in o.filters[tally.id][filter_]:
-              skip = True
-              break
-        if skip: continue
-
-        # find and sanitize the variable name for this score
-        varname = get_sanitized_filterspec_name(tally, score, filterspec)
-        if o.vtk:
-          vtkdata = vtk.vtkDoubleArray()
-          vtkdata.SetName(varname)
-          dataforvtk = {}
-        else:
-          silomesh.init_var(varname)
-
-        lbl = "\t Score {}.{} {}:\t\t{}".format(tally.id, sid+1, score, varname)
-
-        # Mesh fill loop #######################################################
-        for x in range(1,nx+1):
-          sys.stdout.write(lbl+" {0}%\r".format(int(x/nx*100)))
-          sys.stdout.flush()
-          for y in range(1,ny+1):
-            for z in range(1,nz+1):
-              filterspec[0][1] = (x,y,z)
-              val = sp.get_values(tally.id-1, filterspec, sid)[o.valerr]
-              if o.vtk:
-                # vtk cells go z, y, x, so we store it now and enter it later
-                i = (z-1)*nx*ny + (y-1)*nx + x-1
-                dataforvtk[i] = float(val)
-              else:
-                silomesh.set_value(float(val), x, y, z)
-
-        # end mesh fill loop
-        print()
-        if o.vtk:
-          for i in range(nx*ny*nz):
-            vtkdata.InsertNextValue(dataforvtk[i])
-          grid.GetCellData().AddArray(vtkdata)
-          del vtkdata
-
-        else:
-          silomesh.finalize_var()
-
-      # end filter loop
-
-    # end score loop
-    if o.vtk:
-      blocks.SetBlock(block_idx, grid)
-      block_idx += 1
-    else:
-      silomesh.finalize_mesh()
-
-  # end tally loop
-  if o.vtk:
-    writer = vtk.vtkXMLMultiBlockDataWriter()
-    writer.SetFileName(o.output)
-    writer.SetInput(blocks)
-    writer.Write()
-  else:
-    silomesh.finalize_silo()
-
-################################################################################
-def get_sanitized_filterspec_name(tally, score, filterspec):
-  """Returns a name fit for silo vars for a given filterspec, tally and score"""
-
-  comboname = "_"+" ".join(["{}_{}".format(filter_, bin)
-                        for filter_, bin in filterspec[1:]])
-  if len(filterspec[1:]) == 0: comboname = ''
-  varname = 'Tally_{}_{}{}'.format(tally.id, score, comboname)
-  varname = alphanum.sub('_', varname)
-  return varname
-
-################################################################################
-def get_filter_combos(tally):
-  """Returns a list of all filter spec combinations, excluding meshes
-
-  Each combo has the mesh spec as the first element, to be set later.
-  These filter specs correspond with the second argument to StatePoint.get_value
-  """
-
-  specs = []
-
-  if len(tally.filters) == 1:
-    return [[['mesh', [1, 1, 1]]]]
-
-  filters = list(tally.filters.keys())
-  filters.pop(filters.index('mesh'))
-  nbins = [tally.filters[f].length for f in filters]
-
-  combos = [ [b] for b in range(nbins[0])]
-  for i,b in enumerate(nbins[1:]):
-    prod = list(itertools.product(combos, range(b)))
-    if i == 0:
-      combos = prod
-    else:
-      combos = [[v for v in p[0]] + [p[1]] for p in prod]
-
-  for c in combos:
-    spec = [['mesh', [1, 1, 1]]]
-    for i,bin in enumerate(c):
-      spec.append((filters[i], bin))
-    specs.append(spec)
-
-  return specs
-
-################################################################################
-def get_mesh_parms(sp, tally):
-  meshid = tally.filters['mesh'].bins[0]
-  for i,m in enumerate(sp.meshes):
-    if m.id == meshid:
-      mesh = m
-  return mesh.dimension + mesh.lower_left + mesh.upper_right
-
-################################################################################
-def print_available(sp):
-  """Prints available tallies/scores in a statepoint"""
-
-  print("Available tally and score indices:")
-  for tally in sp.tallies:
-    mesh = ""
-    if not 'mesh' in tally.filters: mesh = "(no mesh)"
-    print("\tTally {} {}".format(tally.id, mesh))
-    scores = ["{}.{}: {}".format(tally.id, sid, score)
-              for sid, score in enumerate(tally.scores)]
-    for score in scores:
-      print("\t\tScore {}".format(score))
-      for filter_ in tally.filters:
-        if filter_ == 'mesh': continue
-        for bin in range(tally.filters[filter_].length):
-          print("\t\t\tFilters: {}.{}.{}".format(tally.id, filter_, bin))
-
-################################################################################
-def validate_options(sp,o):
-  """Validates specified tally/score options for the current statepoint"""
-
-  available_tallies = [t.id for t in sp.tallies]
-  if o.tallies:
-    for otally in o.tallies:
-      if not otally in available_tallies:
-        warnings.warn('Tally {} not in statepoint file'.format(otally))
-        continue
-      else:
-        for tally in sp.tallies:
-          if tally.id == otally: break
-      if not 'mesh' in tally.filters:
-        warnings.warn('Tally {} contains no mesh'.format(otally))
-      if o.scores and otally in o.scores.keys():
-        for oscore in o.scores[otally]:
-          if oscore > len(tally.scores):
-            warnings.warn('No score {} in tally {}'.format(oscore, otally))
-
-  if o.scores:
-    for otally in o.scores.keys():
-      if not otally in available_tallies:
-        warnings.warn('Tally {} not in statepoint file'.format(otally))
-        continue
-      if o.tallies and not otally in o.tallies:
-        warnings.warn(
-          'Skipping scores for tally {}, excluded by tally list'.format(otally))
-        continue
-
-  if o.filters:
-    for otally in o.filters.keys():
-      if not otally in available_tallies:
-        warnings.warn('Tally {} not in statepoint file'.format(otally))
-        continue
-      if o.tallies and not otally in o.tallies:
-        warnings.warn(
-          'Skipping filters for tally {}, excluded by tally list'.format(otally))
-        continue
-      for tally in sp.tallies:
-        if tally.id == otally: break
-      for filter_ in o.filters[otally]:
-        if filter_ == 'mesh':
-          warnings.warn('Cannot specify mesh filter bins')
-          continue
-        if not filter_ in tally.filters.keys():
-          warnings.warn(
-                  'Tally {} does not contain filter {}'.format(otally, filter_))
-          continue
-        for bin in o.filters[otally][filter_]:
-          if bin >= tally.filters[filter_].length:
-            warnings.warn(
-                 'No bin {} in tally {} filter {}'.format(bin, otally, filter_))
-
-################################################################################
-# monkeypatch to suppress the source echo produced by warnings
-def formatwarning(message, category, filename, lineno, line):
-  return "{}:{}: {}: {}\n".format(filename, lineno, category.__name__, message)
-warnings.formatwarning = formatwarning
-
-################################################################################
-if __name__ == '__main__':
-    (options, args), err = parse_options()
-    if args and not err:
-      main(args[0],options)

scripts/openmc-track-to-vtk

@@ -1,25 +1,14 @@
 #!/usr/bin/env python
-"""Convert binary particle track to VTK poly data.
 
-Usage information can be obtained by running 'track.py --help':
-
-    usage: track.py [-h] [-o OUT] IN [IN ...]
-
-    Convert particle track file to a .pvtp file.
-
-    positional arguments:
-      IN                 Input particle track data filename(s).
-
-    optional arguments:
-      -h, --help         show this help message and exit
-      -o OUT, --out OUT  Output VTK poly data filename.
+"""Convert HDF5 particle track to VTK poly data.
 
 """
 
 import os
 import argparse
-import h5py
 import struct
+
+import h5py
 import vtk
 
 

scripts/openmc-update-inputs

@@ -1,22 +1,6 @@
 #!/usr/bin/env python
 """Update OpenMC's input XML files to the latest format.
 
-Usage information can be obtained by running 'openmc-update-inputs --help':
-
-usage: openmc-update-inputs [-h] IN [IN ...]
-
-Update geometry.xml files to the latest format. This will remove 'outside'
-attributes/elements from lattices and replace them with 'outer' attributes. For
-'cell' elements, any 'surfaces' attributes/elements will be renamed
-'region'. Note that this script will not delete the given files; it will append
-'.original' to the given files and write new ones.
-
-positional arguments:
-  IN          Input geometry.xml file(s).
-
-optional arguments:
-  -h, --help  show this help message and exit
-
 """
 
 from __future__ import print_function
@@ -59,7 +43,7 @@ def parse_args():
          epilog=epilog,
          formatter_class=argparse.RawTextHelpFormatter)
     parser.add_argument('input', metavar='IN', type=str, nargs='+',
-                        help='Input geometry.xml file(s).')
+                        help='Input XML file(s).')
 
     # Parse and return commandline arguments.
     return parser.parse_args()
@@ -68,20 +52,21 @@ def parse_args():
 def get_universe_ids(geometry_root):
     """Return a set of universe id numbers."""
     root = geometry_root
-    out = {0}
+    out = set()
 
     # Get the ids of universes defined by cells.
     for cell in root.iter('cell'):
-        # Get universe attributes.
+        # Get universe attributes/elements
         if 'universe' in cell.attrib:
             uid = cell.attrib['universe']
             out.add(int(uid))
-
-        # Get universe elements.
         elif cell.find('universe') is not None:
             elem = cell.find('universe')
             uid = elem.text
             out.add(int(uid))
+        else:
+            # Default to universe 0
+            out.add(0)
 
     # Get the ids of universes defined by lattices.
     for lat in root.iter('lattice'):

scripts/openmc-update-mgxs

@@ -2,23 +2,6 @@
 """Update OpenMC's deprecated multi-group cross section XML files to the latest
 HDF5-based format.
 
-Usage information can be obtained by running 'openmc-update-mgxs --help':
-
-usage: openmc-update-mgxs [-h] in out
-
-Update mgxs.xml files to the latest format. This will remove 'outside'
-attributes/elements from lattices and replace them with 'outer' attributes. For
-'cell' elements, any 'surfaces' attributes/elements will be renamed
-'region'. Note that this script will not delete the given files; it will append
-'.original' to the given files and write new ones.
-
-positional arguments:
-  in          Input mgxs xml file
-  out         Output mgxs hdf5 file
-
-optional arguments:
-  -h, --help  show this help message and exit
-
 """
 
 from __future__ import print_function

setup.py

@@ -39,12 +39,13 @@ kwargs = {'name': 'openmc',
 if have_setuptools:
     kwargs.update({
         # Required dependencies
-        'install_requires': ['six', 'numpy>=1.9', 'h5py', 'matplotlib'],
+        'install_requires': ['six', 'numpy>=1.9', 'h5py'],
 
         # Optional dependencies
         'extras_require': {
             'decay': ['uncertainties'],
             'pandas': ['pandas>=0.17.0'],
+            'plot': ['matplotlib', 'ipython'],
             'sparse' : ['scipy'],
             'vtk': ['vtk', 'silomesh'],
             'validate': ['lxml']

src/input_xml.F90

@@ -183,14 +183,6 @@ contains
       max_order = 0
     end if
 
-    ! Set output directory if a path has been specified on the <output_path>
-    ! element
-    if (check_for_node(root, "output_path")) then
-      call get_node_value(root, "output_path", path_output)
-      if (.not. ends_with(path_output, "/")) &
-           path_output = trim(path_output) // "/"
-    end if
-
     ! Check for a trigger node and get trigger information
     if (check_for_node(root, "trigger")) then
       node_trigger = root % child("trigger")
@@ -308,12 +300,30 @@ contains
     call get_node_list(root, "source", node_source_list)
     n = size(node_source_list)
 
-    if (run_mode == MODE_EIGENVALUE .or. run_mode == MODE_FIXEDSOURCE) then
-      if (n == 0) call fatal_error("No source specified in settings XML file.")
-    end if
+    if (n == 0) then
+      ! Default source is isotropic point source at origin with Watt spectrum
+      allocate(external_source(1))
+      external_source % strength = ONE
 
-    ! Allocate array for sources
-    allocate(external_source(n))
+      allocate(SpatialPoint :: external_source(1) % space)
+      select type (space => external_source(1) % space)
+      type is (SpatialPoint)
+        space % xyz(:) = [ZERO, ZERO, ZERO]
+      end select
+
+      allocate(Isotropic :: external_source(1) % angle)
+      external_source(1) % angle % reference_uvw(:) = [ZERO, ZERO, ONE]
+
+      allocate(Watt :: external_source(1) % energy)
+      select type(energy => external_source(1) % energy)
+      type is (Watt)
+        energy % a = 0.988e6_8
+        energy % b = 2.249e-6_8
+      end select
+    else
+      ! Allocate array for sources
+      allocate(external_source(n))
+    end if
 
     ! Read each source
     do i = 1, n
@@ -451,8 +461,12 @@ contains
           end select
 
         else
-          call fatal_error("No spatial distribution specified for external &
-               &source.")
+          ! If no spatial distribution specified, make it a point source
+          allocate(SpatialPoint :: external_source(i) % space)
+          select type (space => external_source(i) % space)
+          type is (SpatialPoint)
+            space % xyz(:) = [ZERO, ZERO, ZERO]
+          end select
         end if
 
         ! Determine external source angular distribution
@@ -839,6 +853,13 @@ contains
       if (check_for_node(node_output, "tallies")) then
         call get_node_value(node_output, "tallies", output_tallies)
       end if
+
+      ! Set output directory if a path has been specified
+      if (check_for_node(node_output, "path")) then
+        call get_node_value(node_output, "path", path_output)
+        if (.not. ends_with(path_output, "/")) &
+             path_output = trim(path_output) // "/"
+      end if
     end if
 
     ! Check for cmfd run

src/relaxng/settings.rnc

@@ -38,13 +38,10 @@ element settings {
 
   element output {
     (element summary { xsd:boolean } | attribute summary { xsd:boolean })? &
-    (element cross_sections { xsd:boolean } |
-      attribute cross_sections { xsd:boolean })? &
-    (element tallies { xsd:boolean } | attribute tallies { xsd:boolean })?
+    (element tallies { xsd:boolean } | attribute tallies { xsd:boolean })? &
+    (element path { xsd:string } | attribute path { xsd:string })?
   }? &
 
-  element output_path { xsd:string { maxLength = "255" } }? &
-
   element particles { xsd:positiveInteger }? &
 
   element ptables { xsd:boolean }? &

src/relaxng/settings.rng

@@ -177,16 +177,6 @@
               </attribute>
             </choice>
           </optional>
-          <optional>
-            <choice>
-              <element name="cross_sections">
-                <data type="boolean"/>
-              </element>
-              <attribute name="cross_sections">
-                <data type="boolean"/>
-              </attribute>
-            </choice>
-          </optional>
           <optional>
             <choice>
               <element name="tallies">
@@ -197,16 +187,19 @@
               </attribute>
             </choice>
           </optional>
+          <optional>
+            <choice>
+              <element name="path">
+                <data type="string"/>
+              </element>
+              <attribute name="path">
+                <data type="string"/>
+              </attribute>
+            </choice>
+          </optional>
         </interleave>
       </element>
     </optional>
-    <optional>
-      <element name="output_path">
-        <data type="string">
-          <param name="maxLength">255</param>
-        </data>
-      </element>
-    </optional>
     <optional>
       <element name="particles">
         <data type="positiveInteger"/>