C/C++ API¶
The libopenmc shared library that is built when installing OpenMC exports a
number of C interoperable functions and global variables that can be used for
in-memory coupling. While it is possible to directly use the C/C++ API as
documented here for coupling, most advanced users will find it easier to work
with the Python bindings in the openmc.lib
module.
Warning
The C/C++ API is still experimental and may undergo substantial changes in future releases.
Type Definitions¶
-
Bank
¶ Attributes of a source particle.
-
double
wgt
¶ Weight of the particle
-
double xyz[3]
Position of the particle (units of cm)
-
double uvw[3]
Unit vector indicating direction of the particle
-
double
E
¶ Energy of the particle in eV
-
int
delayed_group
¶ If the particle is a delayed neutron, indicates which delayed precursor group it was born from. If not a delayed neutron, this member is zero.
-
double
Functions¶
-
int
openmc_calculate_volumes
()¶ Run a stochastic volume calculation
Returns: Return status (negative if an error occurred) Return type: int
-
int
openmc_cell_get_fill
(int32_t index, int* type, int32_t** indices, int32_t* n)¶ Get the fill for a cell
Parameters: - index (int32_t) – Index in the cells array
- type (int*) – Type of the fill
- indices (int32_t**) – Array of material indices for cell
- n (int32_t*) – Length of indices array
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_cell_get_id
(int32_t index, int32_t* id)¶ Get the ID of a cell
Parameters: - index (int32_t) – Index in the cells array
- id (int32_t*) – ID of the cell
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_cell_get_temperature
(int32_t index, const int32_t* instance, double* T)¶ Get the temperature of a cell
Parameters: - index (int32_t) – Index in the cells array
- instance (int32_t*) – Which instance of the cell. If a null pointer is passed, the temperature of the first instance is returned.
- T (double*) – temperature of the cell
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_cell_set_fill
(int32_t index, int type, int32_t n, const int32_t* indices)¶ Set the fill for a cell
Parameters: - index (int32_t) – Index in the cells array
- type (int) – Type of the fill
- n (int32_t) – Length of indices array
- indices (const int32_t*) – Array of material indices for cell
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_cell_set_id
(int32_t index, int32_t id)¶ Set the ID of a cell
Parameters: - index (int32_t) – Index in the cells array
- id (int32_t) – ID of the cell
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_cell_set_temperature
(index index, double T, const int32_t* instance, bool set_contained)¶ Set the temperature of a cell.
Parameters: - index (int32_t) – Index in the cells array
- T (double) – Temperature in Kelvin
- instance (const int32_t*) – Which instance of the cell. To set the temperature for all instances, pass a null pointer.
- set_contained – If the cell is not filled by a material, whether to set the temperatures of all filled cells
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_energy_filter_get_bins
(int32_t index, double** energies, int32_t* n)¶ Return the bounding energies for an energy filter
Parameters: - index (int32_t) – Index in the filters array
- energies (double**) – Bounding energies of the bins for the energy filter
- n (int32_t*) – Number of energies specified
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_energy_filter_set_bins
(int32_t index, int32_t n, const double* energies)¶ Set the bounding energies for an energy filter
Parameters: - index (int32_t) – Index in the filters array
- n (int32_t) – Number of energies specified
- energies (const double*) – Bounding energies of the bins for the energy filter
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_extend_cells
(int32_t n, int32_t* index_start, int32_t* index_end)¶ Extend the cells array by n elements
Parameters: - n (int32_t) – Number of cells to create
- index_start (int32_t*) – Index of first new cell
- index_end (int32_t*) – Index of last new cell
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_extend_filters
(int32_t n, int32_t* index_start, int32_t* index_end)¶ Extend the filters array by n elements
Parameters: - n (int32_t) – Number of filters to create
- index_start (int32_t*) – Index of first new filter
- index_end (int32_t*) – Index of last new filter
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_extend_materials
(int32_t n, int32_t* index_start, int32_t* index_end)¶ Extend the materials array by n elements
Parameters: - n (int32_t) – Number of materials to create
- index_start (int32_t*) – Index of first new material
- index_end (int32_t*) – Index of last new material
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_extend_sources
(int32_t n, int32_t* index_start, int32_t* index_end)¶ Extend the external sources array by n elements
Parameters: - n (int32_t) – Number of sources to create
- index_start (int32_t*) – Index of first new source
- index_end (int32_t*) – Index of last new source
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_extend_tallies
(int32_t n, int32_t* index_start, int32_t* index_end)¶ Extend the tallies array by n elements
Parameters: - n (int32_t) – Number of tallies to create
- index_start (int32_t*) – Index of first new tally
- index_end (int32_t*) – Index of last new tally
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_filter_get_id
(int32_t index, int32_t* id)¶ Get the ID of a filter
Parameters: - index (int32_t) – Index in the filters array
- id (int32_t*) – ID of the filter
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_filter_set_id
(int32_t index, int32_t id)¶ Set the ID of a filter
Parameters: - index (int32_t) – Index in the filters array
- id (int32_t) – ID of the filter
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_finalize
()¶ Finalize a simulation
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_find
(double* xyz, int rtype, int32_t* id, int32_t* instance)¶ Determine the ID of the cell/material containing a given point
Parameters: - xyz (double[3]) – Cartesian coordinates
- rtype (int) – Which ID to return (1=cell, 2=material)
- id (int32_t*) – 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.
- instance (int32_t*) – If a cell is repeated in the geometry, the instance of the cell that was found and zero otherwise.
Returns: Return status (negative if an error occurs)
Return type: int
-
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
Parameters: - id (int32_t) – ID of the cell
- index (int32_t*) – Index in the cells array
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_get_filter_index
(int32_t id, int32_t* index)¶ Get the index in the filters array for a filter with a given ID
Parameters: - id (int32_t) – ID of the filter
- index (int32_t*) – Index in the filters array
Returns: Return status (negative if an error occurs)
Return type: int
-
void
openmc_get_filter_next_id
(int32_t* id)¶ Get an integer ID that has not been used by any filters.
Parameters: - id (int32_t*) – Unused integer ID
-
int
openmc_get_keff
(double k_combined[2])¶ Parameters: - k_combined (double[2]) – Combined estimate of k-effective
Returns: Return status (negative if an error occurs)
Return type: int
-
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
Parameters: - id (int32_t) – ID of the material
- index (int32_t*) – Index in the materials array
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_get_n_batches
(int* n_batches, bool get_max_batches)¶ Get number of batches to simulate
Parameters: - n_batches (int*) – Number of batches to simulate
- get_max_batches (bool) – Whether to return n_batches or n_max_batches (only relevant when triggers are used)
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_get_nuclide_index
(const char name[], int* index)¶ Get the index in the nuclides array for a nuclide with a given name
Parameters: - name (const char[]) – Name of the nuclide
- index (int*) – Index in the nuclides array
Returns: Return status (negative if an error occurs)
Return type: int
-
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
Parameters: - id (int32_t) – ID of the tally
- index (int32_t*) – Index in the tallies array
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_hard_reset
()¶ Reset tallies, timers, and pseudo-random number generator state
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_init
(int argc, char** argv, const void* intracomm)¶ Initialize OpenMC
Parameters: - argc (int) – Number of command-line arguments (including command)
- argv (char**) – Command-line arguments
- intracomm (const void*) – MPI intracommunicator. If MPI is not being used, a null pointer should be passed.
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_load_nuclide
(const char* name, const double* temps, int n)¶ Load data for a nuclide from the HDF5 data library.
Parameters: - name (const char*) – Name of the nuclide.
- temps (const double*) – Temperatures in [K] to load data at
- n (int) – Number of temperatures
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_material_add_nuclide
(int32_t index, const char name[], double density)¶ Add a nuclide to an existing material. If the nuclide already exists, the density is overwritten.
Parameters: - index (int32_t) – Index in the materials array
- name (const char[]) – Name of the nuclide
- density (double) – Density in atom/b-cm
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_material_get_densities
(int32_t index, int** nuclides, double** densities, int* n)¶ Get density for each nuclide in a material.
Parameters: - index (int32_t) – Index in the materials array
- nuclides (int**) – Pointer to array of nuclide indices
- densities (double**) – Pointer to the array of densities
- n (int*) – Length of the array
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_material_get_density
(int32_t index, double* density)¶ Get density of a material.
Parameters: - index (int32_t) – Index in the materials array
- denity (double*) – Pointer to a density
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_material_get_id
(int32_t index, int32_t* id)¶ Get the ID of a material
Parameters: - index (int32_t) – Index in the materials array
- id (int32_t*) – ID of the material
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_material_set_density
(int32_t index, double density, const char* units)¶ Set the density of a material.
Parameters: - index (int32_t) – Index in the materials array
- density (double) – Density of the material
- units (const char*) – Units for density
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_material_set_densities
(int32_t index, int n, const char** name, const double* density)¶ Parameters: - index (int32_t) – Index in the materials array
- n (int) – Length of name/density
- name (const char**) – Array of nuclide names
- density (const double*) – Array of densities
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_material_set_id
(int32_t index, int32_t id)¶ Set the ID of a material
Parameters: - index (int32_t) – Index in the materials array
- id (int32_t) – ID of the material
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_material_filter_get_bins
(int32_t index, int32_t** bins, int32_t* n)¶ Get the bins for a material filter
Parameters: - index (int32_t) – Index in the filters array
- bins (int32_t**) – Index in the materials array for each bin
- n (int32_t*) – Number of bins
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_material_filter_set_bins
(int32_t index, int32_t n, const int32_t* bins)¶ Set the bins for a material filter
Parameters: - index (int32_t) – Index in the filters array
- n (int32_t) – Number of bins
- bins (const int32_t*) – Index in the materials array for each bin
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_mesh_filter_set_mesh
(int32_t index, int32_t index_mesh)¶ Set the mesh for a mesh filter
Parameters: - index (int32_t) – Index in the filters array
- index_mesh (int32_t) – Index in the meshes array
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_next_batch
()¶ Simulate next batch of particles. Must be called after openmc_simulation_init().
Returns: Integer indicating whether simulation has finished (negative) or not finished (zero). Return type: int
-
int
openmc_nuclide_name
(int index, char** name)¶ Get name of a nuclide
Parameters: - index (int) – Index in the nuclides array
- name (char**) – Name of the nuclide
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_plot_geometry
()¶ Run plotting mode.
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_reset
()¶ Resets all tally scores
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_run
()¶ Run a simulation
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_set_n_batches
(int32_t n_batches, bool set_max_batches, bool add_statepoint_batch)¶ Set number of batches and number of max batches
Parameters: - n_batches (int32_t) – Number of batches to simulate
- set_max_batches (bool) – Whether to set settings::n_max_batches or settings::n_batches (only relevant when triggers are used)
- add_statepoint_batch (bool) – Whether to add n_batches to settings::statepoint_batch
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_simulation_finalize
()¶ Finalize a simulation.
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_simulation_init
()¶ Initialize a simulation. Must be called after openmc_init().
Returns: Return status (negative if an error occurs) Return type: int
-
int
openmc_source_bank
(struct Bank** ptr, int64_t* n)¶ Return a pointer to the source bank array.
Parameters: - ptr (struct Bank**) – Pointer to the source bank array
- n (int64_t*) – Length of the source bank array
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_source_set_strength
(int32_t index, double strength)¶ Set the strength of an external source
Parameters: - index (int32_t) – Index in the external source array
- strength (double) – Source strength
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_statepoint_write
(const char filename[], const bool* write_source)¶ Write a statepoint file
Parameters: - filename (const char[]) – Name of file to create. If a null pointer is passed, a filename is assigned automatically.
- write_source (const bool*) – Whether to include the source bank
Returns: Return status (negative if an error occurs)
Return type: int
-
int
openmc_tally_get_id
(int32_t index, int32_t* id)¶ Get the ID of a tally
Parameters: - index (int32_t) – Index in the tallies array
- id (int32_t*) – ID of the tally
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_get_filters
(int32_t index, int32_t** indices, int* n)¶ Get filters specified in a tally
Parameters: - index (int32_t) – Index in the tallies array
- indices (int32_t**) – Array of filter indices
- n (int*) – Number of filters
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_get_n_realizations
(int32_t index, int32_t* n)¶ Parameters: - index (int32_t) – Index in the tallies array
- n (int32_t*) – Number of realizations
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_get_nuclides
(int32_t index, int** nuclides, int* n)¶ Get nuclides specified in a tally
Parameters: - index (int32_t) – Index in the tallies array
- nuclides (int**) – Array of nuclide indices
- n (int*) – Number of nuclides
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_get_scores
(int32_t index, int** scores, int* n)¶ Get scores specified for a tally
Parameters: - index (int32_t) – Index in the tallies array
- scores (int**) – Array of scores
- n (int*) – Number of scores
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_results
(int32_t index, double** ptr, int shape_[3])¶ Get a pointer to tally results array.
Parameters: - index (int32_t) – Index in the tallies array
- ptr (double**) – Pointer to the results array
- shape (int[3]) – Shape of the results array
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_set_filters
(int32_t index, int n, const int32_t* indices)¶ Set filters for a tally
Parameters: - index (int32_t) – Index in the tallies array
- n (int) – Number of filters
- indices (const int32_t*) – Array of filter indices
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_set_id
(int32_t index, int32_t id)¶ Set the ID of a tally
Parameters: - index (int32_t) – Index in the tallies array
- id (int32_t) – ID of the tally
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_set_nuclides
(int32_t index, int n, const char** nuclides)¶ Set the nuclides for a tally
Parameters: - index (int32_t) – Index in the tallies array
- n (int) – Number of nuclides
- nuclides (const char**) – Array of nuclide names
Returns: Return status (negative if an error occurred)
Return type: int
-
int
openmc_tally_set_scores
(int32_t index, int n, const int* scores)¶ Set scores for a tally
Parameters: - index (int32_t) – Index in the tallies array
- n (int) – Number of scores
- scores (const int*) – Array of scores
Returns: Return status (negative if an error occurred)
Return type: int