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.

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