diff --git a/docs/source/capi/index.rst b/docs/source/capi/index.rst index 9bb1b2c66..1e30eacf1 100644 --- a/docs/source/capi/index.rst +++ b/docs/source/capi/index.rst @@ -8,17 +8,28 @@ C API 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(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(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(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(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 diff --git a/docs/source/pythonapi/capi.rst b/docs/source/pythonapi/capi.rst index af00363cc..a586cb4ad 100644 --- a/docs/source/pythonapi/capi.rst +++ b/docs/source/pythonapi/capi.rst @@ -2,16 +2,37 @@ :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 + 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.CellView + openmc.capi.MaterialView + openmc.capi.NuclideView + openmc.capi.TallyView diff --git a/openmc/capi/__init__.py b/openmc/capi/__init__.py index 6ae49c4ff..a4f16ab71 100644 --- a/openmc/capi/__init__.py +++ b/openmc/capi/__init__.py @@ -1,5 +1,5 @@ -"""Provides bindings to C functions defined by OpenMC shared library. - +""" +This module provides bindings to C functions defined by OpenMC shared library. When the :mod:`openmc` package is imported, the OpenMC shared library is automatically loaded. Calls to the OpenMC library can then be via functions or objects in the :mod:`openmc.capi` subpackage, for example: @@ -136,6 +136,7 @@ def find(xyz, rtype='cell'): def hard_reset(): + """Reset tallies, timers, and pseudo-random number generator state.""" _dll.openmc_hard_reset() @@ -180,7 +181,7 @@ def plot_geometry(): def reset(): - """Reset tallies""" + """Reset tallies and timers.""" _dll.openmc_reset() diff --git a/openmc/capi/cell.py b/openmc/capi/cell.py index 1dbe50d51..9abada00c 100644 --- a/openmc/capi/cell.py +++ b/openmc/capi/cell.py @@ -22,6 +22,23 @@ _dll.openmc_get_cell.errcheck = _error_handler class CellView(object): + """View of a cell. + + This class exposes a cell that is stored internally in the OpenMC solver. To + obtain a view of a cell with a given ID, use the + :data:`openmc.capi.nuclides` mapping. + + Parameters + ---------- + index : int + Index in the `cells` array. + + Attributes + ---------- + id : int + ID of the cell + + """ __instances = WeakValueDictionary() def __new__(cls, *args): if args not in cls.__instances: diff --git a/openmc/capi/material.py b/openmc/capi/material.py index c917d3331..564ecaa05 100644 --- a/openmc/capi/material.py +++ b/openmc/capi/material.py @@ -7,8 +7,8 @@ from numpy.ctypeslib import as_array from openmc.capi import _dll, _error_handler, NuclideView -__all__ = ['MaterialView', 'materials'] +__all__ = ['MaterialView', 'materials'] # Material functions _dll.openmc_get_material.argtypes = [c_int32, POINTER(c_int32)] @@ -36,6 +36,27 @@ _dll.openmc_material_set_densities.errcheck = _error_handler class MaterialView(object): + """View of a material. + + This class exposes a material that is stored internally in the OpenMC + solver. To obtain a view of a material with a given ID, use the + :data:`openmc.capi.materials` mapping. + + Parameters + ---------- + index : int + Index in the `materials` array. + + Attributes + ---------- + id : int + ID of the material + nuclides : list of str + List of nuclides in the material + densities : numpy.ndarray + Array of densities in atom/b-cm + + """ __instances = WeakValueDictionary() def __new__(cls, *args): if args not in cls.__instances: diff --git a/openmc/capi/nuclide.py b/openmc/capi/nuclide.py index 7a2f7a37b..384d0ae91 100644 --- a/openmc/capi/nuclide.py +++ b/openmc/capi/nuclide.py @@ -28,13 +28,30 @@ def load_nuclide(name): Parameters ---------- name : str - Name of nuclide, e.g. 'U235' + Name of the nuclide, e.g. 'U235' """ _dll.openmc_load_nuclide(name.encode()) class NuclideView(object): + """View of a nuclide. + + This class exposes a nuclide that is stored internally in the OpenMC + solver. To obtain a view of a nuclide with a given name, use the + :data:`openmc.capi.nuclides` mapping. + + Parameters + ---------- + index : int + Index in the `nuclides` array. + + Attributes + ---------- + name : str + Name of the nuclide, e.g. 'U235' + + """ __instances = WeakValueDictionary() def __new__(cls, *args): if args not in cls.__instances: @@ -47,19 +64,6 @@ class NuclideView(object): @property def name(self): - """Name of nuclide with given index - - Parameter - --------- - index : int - Index in internal nuclides array - - Returns - ------- - str - Name of nuclide - - """ name = c_char_p() _dll.openmc_nuclide_name(self._index, name) @@ -71,6 +75,7 @@ class NuclideView(object): class _NuclideMapping(Mapping): + """Provide mapping from nuclide name to index in nuclides array.""" def __getitem__(self, key): index = c_int() _dll.openmc_get_nuclide(key.encode(), index) diff --git a/openmc/capi/tally.py b/openmc/capi/tally.py index b1fc49d04..cc8c13a5a 100644 --- a/openmc/capi/tally.py +++ b/openmc/capi/tally.py @@ -30,6 +30,27 @@ _dll.openmc_tally_set_nuclides.errcheck = _error_handler class TallyView(object): + """View of a tally. + + This class exposes a tally that is stored internally in the OpenMC + solver. To obtain a view of a tally with a given ID, use the + :data:`openmc.capi.tallies` mapping. + + Parameters + ---------- + index : int + Index in the `tallys` array. + + Attributes + ---------- + id : int + ID of the tally + nuclides : list of str + List of nuclides to score results for + results : numpy.ndarray + Array of tally results + + """ __instances = WeakValueDictionary() def __new__(cls, *args): if args not in cls.__instances: @@ -56,14 +77,6 @@ class TallyView(object): @property def results(self): - """Get tally results array - - Returns - ------- - numpy.ndarray - Array that exposes the internal tally results array - - """ data = POINTER(c_double)() shape = (c_int*3)() _dll.openmc_tally_results(self._index, data, shape) diff --git a/openmc/nuclide.py b/openmc/nuclide.py index 03062ee0e..fc0d7ef07 100644 --- a/openmc/nuclide.py +++ b/openmc/nuclide.py @@ -11,12 +11,12 @@ class Nuclide(object): Parameters ---------- name : str - Name of the nuclide, e.g. U235 + Name of the nuclide, e.g. 'U235' Attributes ---------- name : str - Name of the nuclide, e.g. U235 + Name of the nuclide, e.g. 'U235' scattering : 'data' or 'iso-in-lab' or None The type of angular scattering distribution to use diff --git a/src/api.F90 b/src/api.F90 index b767d1ab4..40ac0f01f 100644 --- a/src/api.F90 +++ b/src/api.F90 @@ -66,7 +66,7 @@ module openmc_api contains !=============================================================================== -! OPENMC_CELL_ID returns the ID of a cell +! OPENMC_CELL_GET_ID returns the ID of a cell !=============================================================================== function openmc_cell_get_id(index, id) result(err) bind(C) @@ -695,9 +695,9 @@ contains ! OPENMC_TALLY_NUCLIDES returns the list of nuclides assigned to a tally !=============================================================================== - function openmc_tally_get_nuclides(index, ptr, n) result(err) bind(C) + function openmc_tally_get_nuclides(index, nuclides, n) result(err) bind(C) integer(C_INT32_T), value :: index - type(C_PTR), intent(out) :: ptr + type(C_PTR), intent(out) :: nuclides integer(C_INT), intent(out) :: n integer(C_INT) :: err @@ -705,7 +705,7 @@ contains if (index >= 1 .and. index <= size(tallies)) then associate (t => tallies(index)) if (allocated(t % nuclide_bins)) then - ptr = C_LOC(t % nuclide_bins(1)) + nuclides = C_LOC(t % nuclide_bins(1)) n = size(t % nuclide_bins) err = 0 end if @@ -739,6 +739,11 @@ contains end if end function openmc_tally_results +!=============================================================================== +! OPENMC_TALLY_SET_NUCLIDES sets the nuclides in the tally which results should +! be scored for +!=============================================================================== + function openmc_tally_set_nuclides(index, n, nuclides) result(err) bind(C) integer(C_INT32_T), value :: index integer(C_INT), value :: n