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 API as documented
here for coupling, most advanced users will find it easier to work with the
Python bindings in the openmc.capi
module.
Warning
The 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¶
-
void
openmc_calculate_volumes
()¶ Run a stochastic volume calculation
-
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_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)¶ 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.
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
-
void
openmc_finalize
()¶ Finalize a simulation
-
void
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.
-
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_nuclide_index
(char name[], int* index)¶ Get the index in the nuclides array for a nuclide with a given name
Parameters: - name (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
-
void
openmc_hard_reset
()¶ Reset tallies, timers, and pseudo-random number generator state
-
void
openmc_init
(const int* intracomm)¶ Initialize OpenMC
Parameters: - intracomm (const int*) – MPI intracommunicator. If MPI is not being used, a null pointer should be passed.
-
int
openmc_load_nuclide
(char name[])¶ Load data for a nuclide from the HDF5 data library.
Parameters: - name (char[]) – Name of the nuclide.
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_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)¶ Set the density of a material.
Parameters: - index (int32_t) – Index in the materials array
- density (double) – Density of the material in atom/b-cm
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
-
void
openmc_plot_geometry
()¶ Run plotting mode.
-
void
openmc_reset
()¶ Resets all tally scores
-
void
openmc_run
()¶ Run a simulation
-
void
openmc_simulation_finalize
()¶ Finalize a simulation.
-
void
openmc_simulation_init
()¶ Initialize a simulation. Must be called after openmc_init().
-
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
-
void
openmc_statepoint_write
(const char filename[])¶ Write a statepoint file
Parameters: - filename (const char[]) – Name of file to create. If a null pointer is passed, a filename is assigned automatically.
-
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