Merge branch 'develop' into photon-new

docs/source/capi/index.rst

@@ -4,21 +4,32 @@
 C API
 =====
 
-.. c:function:: void openmc_calculate_voumes()
+.. c:function:: void openmc_calculate_volumes()
 
    Run a stochastic volume calculation
 
-.. c:function:: int openmc_cell_set_temperature(int id, double T, int* instance)
+.. c:function:: int openmc_cell_get_id(int32_t index, int32_t* id)
+
+   Get the ID of a cell
+
+   :param index: Index in the cells array
+   :type index: int32_t
+   :param id: ID of the cell
+   :type id: int32_t*
+   :return: Return status (negative if an error occurred)
+   :rtype: int
+
+.. c:function:: int openmc_cell_set_temperature(index index, double T, int32_t* instance)
 
    Set the temperature of a cell.
 
-   :param id: ID of the cell
-   :type id: int
+   :param index: Index in the cells array
+   :type index: int32_t
    :param T: Temperature in Kelvin
    :type T: double
    :param instance: Which instance of the cell. To set the temperature for all
                     instances, pass a null pointer.
-   :type instance: int*
+   :type instance: int32_t*
    :return: Return status (negative if an error occurred)
    :rtype: int
 
@@ -26,7 +37,7 @@ C API
 
    Finalize a simulation
 
-.. c:function:: void openmc_find(double* xyz, int rtype, int* id, int* instance)
+.. c:function:: void openmc_find(double* xyz, int rtype, int32_t* id, int32_t* instance)
 
    Determine the ID of the cell/material containing a given point
 
@@ -36,10 +47,65 @@ C API
    :type rtype: int
    :param id: ID of the cell/material found. If a material is requested and the
               point is in a void, the ID is 0. If an error occurs, the ID is -1.
-   :type id: int
+   :type id: int32_t*
    :param instance: If a cell is repetaed in the geometry, the instance of the
                     cell that was found and zero otherwise.
-   :type instance: int
+   :type instance: int32_t*
+
+.. c:function:: int openmc_get_cell_index(int32_t id, int32_t* index)
+
+   Get the index in the cells array for a cell with a given ID
+
+   :param id: ID of the cell
+   :type id: int32_t
+   :param index: Index in the cells array
+   :type index: int32_t*
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
+.. c:function:: int openmc_get_keff(double k_combined[])
+
+   :param k_combined: Combined estimate of k-effective
+   :type k_combined: double[2]
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
+.. c:function:: int openmc_get_nuclide_index(char name[], int* index)
+
+   Get the index in the nuclides array for a nuclide with a given name
+
+   :param name: Name of the nuclide
+   :type name: char[]
+   :param index: Index in the nuclides array
+   :type index: int*
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
+.. c:function:: int openmc_get_tally_index(int32_t id, int32_t* index)
+
+   Get the index in the tallies array for a tally with a given ID
+
+   :param id: ID of the tally
+   :type id: int32_t
+   :param index: Index in the tallies array
+   :type index: int32_t*
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
+.. c:function:: int openmc_get_material_index(int32_t id, int32_t* index)
+
+   Get the index in the materials array for a material with a given ID
+
+   :param id: ID of the material
+   :type id: int32_t
+   :param index: Index in the materials array
+   :type index: int32_t*
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
+.. c:function:: void openmc_hard_reset()
+
+   Reset tallies, timers, and pseudo-random number generator state
 
 .. c:function:: void openmc_init(int intracomm)
 
@@ -57,13 +123,13 @@ C API
    :return: Return status (negative if an error occurs)
    :rtype: int
 
-.. c:function:: int openmc_material_add_nuclide(int id, char name[], double density)
+.. c:function:: int openmc_material_add_nuclide(int32_t index, char name[], double density)
 
    Add a nuclide to an existing material. If the nuclide already exists, the
    density is overwritten.
 
-   :param id: ID of the material
-   :type id: int
+   :param index: Index in the materials array
+   :type index: int32_t
    :param name: Name of the nuclide
    :type name: char[]
    :param density: Density in atom/b-cm
@@ -71,28 +137,67 @@ C API
    :return: Return status (negative if an error occurs)
    :rtype: int
 
-.. c:function:: int openmc_material_get_densities(int id, double* ptr)
+.. c:function:: int openmc_material_get_densities(int32_t index, int* nuclides[], double* densities[])
 
-   Get an array of nuclide densities for a material.
+   Get density for each nuclide in a material.
 
-   :param id: ID of the material
-   :type id: int
-   :param ptr: Pointer to the array of densities
-   :type ptr: double*
-   :return: Length of the array
+   :param index: Index in the materials array
+   :type index: int32_t
+   :param nuclides: Pointer to array of nuclide indices
+   :type nuclides: int**
+   :param densities: Pointer to the array of densities
+   :type densities: double**
+   :param n: Length of the array
+   :type n: int
+   :return: Return status (negative if an error occurs)
    :rtype: int
 
-.. c:function:: int openmc_material_set_density(int id, double density)
+.. c:function:: int openmc_material_get_id(int32_t index, int32_t* id)
+
+   Get the ID of a material
+
+   :param index: Index in the materials array
+   :type index: int32_t
+   :param id: ID of the material
+   :type id: int32_t*
+   :return: Return status (negative if an error occurred)
+   :rtype: int
+
+.. c:function:: int openmc_material_set_density(int32_t index, double density)
 
    Set the density of a material.
 
-   :param id: ID of the material
-   :type id: int
+   :param index: Index in the materials array
+   :type index: int32_t
    :param density: Density of the material in atom/b-cm
    :type density: double
    :return: Return status (negative if an error occurs)
    :rtype: int
 
+.. c:function:: int openmc_material_set_densities(int32_t, n, char* name[], double density[])
+
+   :param index: Index in the materials array
+   :type index: int32_t
+   :param n: Length of name/density
+   :type n: int
+   :param name: Array of nuclide names
+   :type name: char**
+   :param density: Array of densities
+   :type density: double[]
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
+.. c:function:: int openmc_nuclide_name(int index, char* name[])
+
+   Get name of a nuclide
+
+   :param index: Index in the nuclides array
+   :type index: int
+   :param name: Name of the nuclide
+   :type name: char**
+   :return: Return status (negative if an error occurs)
+   :rtype: int
+
 .. c:function:: void openmc_plot_geometry()
 
    Run plotting mode.
@@ -105,13 +210,52 @@ C API
 
    Run a simulation
 
-.. c:function:: void openmc_tally_results(int id, double** ptr, int shape_[3])
+.. c:function:: int openmc_tally_get_id(int32_t index, int32_t* id)
+
+   Get the ID of a tally
+
+   :param index: Index in the tallies array
+   :type index: int32_t
+   :param id: ID of the tally
+   :type id: int32_t*
+   :return: Return status (negative if an error occurred)
+   :rtype: int
+
+.. c:function:: int openmc_tally_get_nuclides(int32_t index, int* nuclides[], int* n)
+
+   Get nuclides specified in a tally
+
+   :param index: Index in the tallies array
+   :type index: int32_t
+   :param nuclides: Array of nuclide indices
+   :type nuclides: int**
+   :param n: Number of nuclides
+   :type n: int*
+   :return: Return status (negative if an error occurred)
+   :rtype: int
+
+.. c:function:: int openmc_tally_results(int32_t index, double** ptr, int shape_[3])
 
    Get a pointer to tally results array.
 
-   :param id: ID of the tally
-   :type id: int
+   :param index: Index in the tallies array
+   :type index: int32_t
    :param ptr: Pointer to the results array
    :type ptr: double**
    :param shape_: Shape of the results array
    :type shape_: int[3]
+   :return: Return status (negative if an error occurred)
+   :rtype: int
+
+.. c:function:: int openmc_tally_set_nuclides(int32_t index, int n, char* nuclides[])
+
+   Set the nuclides for a tally
+
+   :param index: Index in the tallies array
+   :type index: int32_t
+   :param n: Number of nuclides
+   :type n: int
+   :param nuclides: Array of nuclide names
+   :type nuclides: char**
+   :return: Return status (negative if an error occurred)
+   :rtype: int

docs/source/io_formats/tallies.rst

@@ -123,9 +123,9 @@ to the scored values. 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
+    The type of the filter. Accepted options are "cell", "cellfrom", 
+    "cellborn", "surface", "material", "universe", "energy", "energyout", "mu", 
+    "polar", "azimuthal", "mesh", "distribcell", "delayedgroup", and
     "energyfunction".
 
   :bins:
@@ -154,14 +154,31 @@ 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.
+  A list of unique IDs for cells in which the tally should be 
+  accumulated.
+
+:surface:
+  This filter allows the tally to be scored when crossing a surface. A list of 
+  surface IDs should be given. By default, net currents are tallied, and to 
+  tally a partial current from one cell to another, this should be used in 
+  combination with a cell or cell_from filter that defines the other cell.
+  This filter should not be used in combination with a meshfilter.
+
+:cellfrom:
+  This filter allows the tally to be scored when crossing a surface and the 
+  particle came from a specified cell. A list of cell IDs should be 
+  given.
+  To tally a partial current from a cell to another, this filter should be 
+  used in combination with a cell filter, to define the other cell.
+  This filter should not be used in combination with a meshfilter.
 
 :cellborn:
   This filter allows the tally to be scored to only when particles were
-  originally born in a specified cell. A list of cell IDs should be given.
+  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.
+  A list of unique IDs for materials in which the tally should be accumulated.
 
 :universe:
   A list of unique IDs for universes in which the tally should be accumulated.

docs/source/pythonapi/base.rst

@@ -117,6 +117,7 @@ Constructing Tallies
    openmc.UniverseFilter
    openmc.MaterialFilter
    openmc.CellFilter
+   openmc.CellFromFilter
    openmc.CellbornFilter
    openmc.SurfaceFilter
    openmc.MeshFilter

docs/source/pythonapi/capi.rst

@@ -2,16 +2,40 @@
 :data:`openmc.capi` -- Python bindings to the C API
 ---------------------------------------------------
 
+.. automodule:: openmc.capi
+
+Functions
+---------
+
 .. autosummary::
    :toctree: generated
    :nosignatures:
    :template: myfunction.rst
 
-   openmc.capi.lib_context
+   openmc.capi.calculate_volumes
+   openmc.capi.finalize
+   openmc.capi.find_cell
+   openmc.capi.find_material
+   openmc.capi.hard_reset
+   openmc.capi.init
+   openmc.capi.keff
+   openmc.capi.load_nuclide
+   openmc.capi.plot_geometry
+   openmc.capi.reset
+   openmc.capi.run
+   openmc.capi.run_in_memory
+
+Classes
+-------
 
 .. autosummary::
    :toctree: generated
    :nosignatures:
    :template: myclass.rst
 
-   openmc.capi.OpenMCLibrary
+   openmc.capi.Cell
+   openmc.capi.EnergyFilter
+   openmc.capi.MaterialFilter
+   openmc.capi.Material
+   openmc.capi.Nuclide
+   openmc.capi.Tally

docs/source/usersguide/install.rst

@@ -414,16 +414,19 @@ distributions.
       various HDF5 files, h5py is needed to provide access to data within these
       files from Python.
 
-.. admonition:: Optional
-   :class: note
-
    `Matplotlib <http://matplotlib.org/>`_
       Matplotlib is used to providing plotting functionality in the API like the
       :meth:`Universe.plot` method and the :func:`openmc.plot_xs` function.
 
    `uncertainties <https://pythonhosted.org/uncertainties/>`_
-      Uncertainties are optionally used for decay data in the :mod:`openmc.data`
-      module.
+      Uncertainties are used for decay data in the :mod:`openmc.data` module.
+
+   `lxml <http://lxml.de/>`_
+      lxml is used for the :ref:`scripts_validate` script and various other
+      parts of the Python API.
+
+.. admonition:: Optional
+   :class: note
 
    `Cython <http://cython.org/>`_
       Cython is used for resonance reconstruction for ENDF data converted to
@@ -437,8 +440,8 @@ distributions.
       The silomesh package is needed to convert voxel and track files to SILO
       format.
 
-   `lxml <http://lxml.de/>`_
-      lxml is used for the :ref:`scripts_validate` script.
+   `pytest <https://docs.pytest.org>`_
+      The pytest framework is used for unit testing the Python API.
 
 .. _usersguide_nxml:
 

docs/source/usersguide/tallies.rst

@@ -261,12 +261,19 @@ The following tables show all valid scores:
     +----------------------+---------------------------------------------------+
     |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.                                             |
+    |current               |Used in combination with a mesh filter:            |
+    |                      |Partial currents on the boundaries of each cell in |
+    |                      |a mesh. It may not be used in conjunction with any |
+    |                      |other score. Only energy and mesh filters may be   |
+    |                      |used.                                              |
+    |                      |Used in combination with a surface filter:         |
+    |                      |Net currents on any surface previously defined in  |
+    |                      |the geometry. It may be used along with any other  |
+    |                      |filter, except mesh filters.                       |
+    |                      |Surfaces can alternatively be defined with cell    |
+    |                      |from and cell filters thereby resulting in tallying|
+    |                      |partial currents.                                  |
+    |                      |Units are particles per source particle.           |
     +----------------------+---------------------------------------------------+
     |events                |Number of scoring events. Units are events per     |
     |                      |source particle.                                   |