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

type 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

• density (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_remove_tally(int32_t index);

Given an index of a tally, remove it from the tallies array :param int index: Index in tallies array :return: Return status (negative if an error occurs) :rtype: 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