diff --git a/docs/source/capi/index.rst b/docs/source/capi/index.rst index ff19758bb3..d63ed1f3ae 100644 --- a/docs/source/capi/index.rst +++ b/docs/source/capi/index.rst @@ -4,6 +4,48 @@ 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 :py:mod:`openmc.capi` module. + +.. warning:: The C API is still experimental and may undergo substantial changes + in future releases. + +---------------- +Type Definitions +---------------- + +.. c:type:: Bank + + Attributes of a source particle. + + .. c:member:: double wgt + + Weight of the particle + + .. c:member:: double xyz[3] + + Position of the particle (units of cm) + + .. c:member:: double uvw[3] + + Unit vector indicating direction of the particle + + .. c:member:: double E + + Energy of the particle in eV + + .. c:member:: 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 +--------- + .. c:function:: void openmc_calculate_volumes() Run a stochastic volume calculation @@ -15,7 +57,7 @@ C API :param int32_t index: Index in the cells array :param int* type: Type of the fill :param int32_t** indices: Array of material indices for cell - :param int32_t n: Length of indices array + :param int32_t* n: Length of indices array :return: Return status (negative if an error occurred) :rtype: int @@ -28,14 +70,15 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_cell_set_fill(int32_t index, int type, int32_t n, int32_t* indices) +.. c:function:: int openmc_cell_set_fill(int32_t index, int type, int32_t n, const int32_t* indices) Set the fill for a cell :param int32_t index: Index in the cells array :param int type: Type of the fill :param int32_t n: Length of indices array - :param int32_t* indices: Array of material indices for cell + :param indices: Array of material indices for cell + :type indices: const int32_t* :return: Return status (negative if an error occurred) :rtype: int @@ -48,14 +91,15 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_cell_set_temperature(index index, double T, int32_t* instance) +.. c:function:: int openmc_cell_set_temperature(index index, double T, const int32_t* instance) Set the temperature of a cell. :param int32_t index: Index in the cells array :param double T: Temperature in Kelvin - :param int32_t* instance: Which instance of the cell. To set the temperature - for all instances, pass a null pointer. + :param instance: Which instance of the cell. To set the temperature for all + instances, pass a null pointer. + :type instance: const int32_t* :return: Return status (negative if an error occurred) :rtype: int @@ -69,13 +113,14 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_energy_filter_set_bins(int32_t index, int32_t n, double* energies) +.. c:function:: int openmc_energy_filter_set_bins(int32_t index, int32_t n, const double* energies) Set the bounding energies for an energy filter :param int32_t index: Index in the filters array :param int32_t n: Number of energies specified - :param double* energies: Bounding energies of the bins for the energy filter + :param energies: Bounding energies of the bins for the energy filter + :type energies: const double* :return: Return status (negative if an error occurred) :rtype: int @@ -109,6 +154,16 @@ C API :return: Return status (negative if an error occurred) :rtype: int +.. c:function:: int openmc_extend_sources(int32_t n, int32_t* index_start, int32_t* index_end) + + Extend the external sources array by n elements + + :param int32_t n: Number of sources to create + :param int32_t* index_start: Index of first new source + :param int32_t* index_end: Index of last new source + :return: Return status (negative if an error occurred) + :rtype: int + .. c:function:: int openmc_extend_tallies(int32_t n, int32_t* index_start, int32_t* index_end) Extend the tallies array by n elements @@ -150,7 +205,7 @@ C API :param int32_t* 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. - :param int32_t* instance: If a cell is repetaed in the geometry, the instance + :param int32_t* instance: If a cell is repeated in the geometry, the instance of the cell that was found and zero otherwise. .. c:function:: int openmc_get_cell_index(int32_t id, int32_t* index) @@ -177,7 +232,7 @@ C API :param int32_t* id: Unused integer ID -.. c:function:: int openmc_get_keff(double k_combined[]) +.. c:function:: int openmc_get_keff(double k_combined[2]) :param double[2] k_combined: Combined estimate of k-effective :return: Return status (negative if an error occurs) @@ -214,11 +269,13 @@ C API Reset tallies, timers, and pseudo-random number generator state -.. c:function:: void openmc_init(int intracomm) +.. c:function:: void openmc_init(const int* intracomm) Initialize OpenMC - :param int intracomm: MPI intracommunicator + :param intracomm: MPI intracommunicator. If MPI is not being used, a null + pointer should be passed. + :type intracomm: const int* .. c:function:: int openmc_load_nuclide(char name[]) @@ -228,18 +285,19 @@ C API :return: Return status (negative if an error occurs) :rtype: int -.. c:function:: int openmc_material_add_nuclide(int32_t index, char name[], double density) +.. c:function:: 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. :param int32_t index: Index in the materials array - :param char[] name: Name of the nuclide + :param name: Name of the nuclide + :type name: const char[] :param double density: Density in atom/b-cm :return: Return status (negative if an error occurs) :rtype: int -.. c:function:: int openmc_material_get_densities(int32_t index, int* nuclides[], double* densities[], int* n) +.. c:function:: int openmc_material_get_densities(int32_t index, int** nuclides, double** densities, int* n) Get density for each nuclide in a material. @@ -268,12 +326,14 @@ C API :return: Return status (negative if an error occurs) :rtype: int -.. c:function:: int openmc_material_set_densities(int32_t index, int n, char* name[], double density[]) +.. c:function:: int openmc_material_set_densities(int32_t index, int n, const char** name, const double density*) :param int32_t index: Index in the materials array :param int n: Length of name/density - :param char** name: Array of nuclide names - :param double[] density: Array of densities + :param name: Array of nuclide names + :type name: const char** + :param density: Array of densities + :type density: const double* :return: Return status (negative if an error occurs) :rtype: int @@ -296,13 +356,14 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_material_filter_set_bins(int32_t index, int32_t n, int32_t* bins) +.. c:function:: int openmc_material_filter_set_bins(int32_t index, int32_t n, const int32_t* bins) Set the bins for a material filter :param int32_t index: Index in the filters array :param int32_t n: Number of bins - :param int32_t* bins: Index in the materials array for each bin + :param bins: Index in the materials array for each bin + :type bins: const int32_t* :return: Return status (negative if an error occurred) :rtype: int @@ -323,7 +384,7 @@ C API finished (zero). :rtype: int -.. c:function:: int openmc_nuclide_name(int index, char* name[]) +.. c:function:: int openmc_nuclide_name(int index, char** name) Get name of a nuclide @@ -352,6 +413,33 @@ C API Initialize a simulation. Must be called after openmc_init(). +.. c:function:: int openmc_source_bank(struct Bank** ptr, int64_t* n) + + Return a pointer to the source bank array. + + :param ptr: Pointer to the source bank array + :type ptr: struct Bank** + :param int64_t* n: Length of the source bank array + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_source_set_strength(int32_t index, double strength) + + Set the strength of an external source + + :param int32_t index: Index in the external source array + :param double strength: Source strength + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: void openmc_statepoint_write(const char filename[]) + + Write a statepoint file + + :param filename: Name of file to create. If a null pointer is passed, a + filename is assigned automatically. + :type filename: const char[] + .. c:function:: int openmc_tally_get_id(int32_t index, int32_t* id) Get the ID of a tally @@ -378,7 +466,7 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_tally_get_nuclides(int32_t index, int* nuclides[], int* n) +.. c:function:: int openmc_tally_get_nuclides(int32_t index, int** nuclides, int* n) Get nuclides specified in a tally @@ -408,13 +496,14 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_tally_set_filters(int32_t index, int n, int32_t* indices) +.. c:function:: int openmc_tally_set_filters(int32_t index, int n, const int32_t* indices) Set filters for a tally :param int32_t index: Index in the tallies array :param int n: Number of filters - :param int32_t* indices: Array of filter indices + :param indices: Array of filter indices + :type indices: const int32_t* :return: Return status (negative if an error occurred) :rtype: int @@ -427,22 +516,24 @@ C API :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_tally_set_nuclides(int32_t index, int n, char* nuclides[]) +.. c:function:: int openmc_tally_set_nuclides(int32_t index, int n, const char** nuclides) Set the nuclides for a tally :param int32_t index: Index in the tallies array :param int n: Number of nuclides - :param char** nuclides: Array of nuclide names + :param nuclides: Array of nuclide names + :type nuclides: const char** :return: Return status (negative if an error occurred) :rtype: int -.. c:function:: int openmc_tally_set_scores(int32_t index, int n, int* scores) +.. c:function:: int openmc_tally_set_scores(int32_t index, int n, const int* scores) Set scores for a tally :param int32_t index: Index in the tallies array :param int n: Number of scores - :param int* scores: Array of scores + :param scores: Array of scores + :type scores: const int* :return: Return status (negative if an error occurred) :rtype: int diff --git a/include/openmc.h b/include/openmc.h index 5f72e99ed2..bb04907a52 100644 --- a/include/openmc.h +++ b/include/openmc.h @@ -8,29 +8,30 @@ extern "C" { #endif - void openmc_calculate_voumes(); - void openmc_finalize(); - void openmc_hard_reset(); - int openmc_next_batch(); - void openmc_plot_geometry(); - void openmc_reset(); - void openmc_run(); - void openmc_simulation_finalize(); - void openmc_simulation_init(); + struct Bank { + double wgt; + double xyz[3]; + double uvw[3]; + double E; + int delayed_group; + }; + void openmc_calculate_voumes(); int openmc_cell_get_fill(int32_t index, int* type, int32_t** indices, int32_t* n); int openmc_cell_get_id(int32_t index, int32_t* id); - int openmc_cell_set_fill(int32_t index, int type, int32_t n, int32_t* indices); + int openmc_cell_set_fill(int32_t index, int type, int32_t n, const int32_t* indices); int openmc_cell_set_id(int32_t index, int32_t id); - int openmc_cell_set_temperature(int32_t index, double T, int32_t* instance); + int openmc_cell_set_temperature(int32_t index, double T, const int32_t* instance); int openmc_energy_filter_get_bins(int32_t index, double** energies, int32_t* n); - int openmc_energy_filter_set_bins(int32_t index, int32_t n, double* energies); + int openmc_energy_filter_set_bins(int32_t index, int32_t n, const double* energies); int openmc_extend_cells(int32_t n, int32_t* index_start, int32_t* index_end); int openmc_extend_filters(int32_t n, int32_t* index_start, int32_t* index_end); int openmc_extend_materials(int32_t n, int32_t* index_start, int32_t* index_end); + int openmc_extend_sources(int32_t n, int32_t* index_start, int32_t* index_end); int openmc_extend_tallies(int32_t n, int32_t* index_start, int32_t* index_end); int openmc_filter_get_id(int32_t index, int32_t* id); int openmc_filter_set_id(int32_t index, int32_t id); + void openmc_finalize(); int openmc_find(double* xyz, int rtype, int32_t* id, int32_t* instance); int openmc_get_cell_index(int32_t id, int32_t* index); int openmc_get_filter_index(int32_t id, int32_t* index); @@ -38,28 +39,39 @@ extern "C" { int openmc_get_keff(double k_combined[]); int openmc_get_material_index(int32_t id, int32_t* index); int openmc_get_nuclide_index(char name[], int* index); - int openmc_get_tally_tally(int32_t id, int32_t* index); + int openmc_get_tally_index(int32_t id, int32_t* index); + void openmc_hard_reset(); + void openmc_init(const int* intracomm); int openmc_load_nuclide(char name[]); - int openmc_material_add_nuclide(int32_t index, char name[], double density); - int openmc_material_get_densities(int32_t index, int* nuclides[], double* densities[], int* n); + int openmc_material_add_nuclide(int32_t index, const char name[], double density); + int openmc_material_get_densities(int32_t index, int** nuclides, double** densities, int* n); int openmc_material_get_id(int32_t index, int32_t* id); int openmc_material_set_density(int32_t index, double density); - int openmc_material_set_densities(int32_t index, int n, char* name[], double density[]); + int openmc_material_set_densities(int32_t index, int n, const char** name, const double* density); int openmc_material_set_id(int32_t index, int32_t id); int openmc_material_filter_get_bins(int32_t index, int32_t** bins, int32_t* n); - int openmc_material_filter_set_bins(int32_t index, int32_t n, int32_t* bins); + int openmc_material_filter_set_bins(int32_t index, int32_t n, const int32_t* bins); int openmc_mesh_filter_set_mesh(int32_t index, int32_t index_mesh); - int openmc_nuclide_name(int index, char* name[]); + int openmc_next_batch(); + int openmc_nuclide_name(int index, char** name); + void openmc_plot_geometry(); + void openmc_reset(); + void openmc_run(); + void openmc_simulation_finalize(); + void openmc_simulation_init(); + int openmc_source_bank(struct Bank** ptr, int64_t* n); + int openmc_source_set_strength(int32_t index, double strength); + void openmc_statepoint_write(const char filename[]); int openmc_tally_get_id(int32_t index, int32_t* id); int openmc_tally_get_filters(int32_t index, int32_t** indices, int* n); int openmc_tally_get_n_realizations(int32_t index, int32_t* n); - int openmc_tally_get_nuclides(int32_t index, int* nuclides[], int* n); + int openmc_tally_get_nuclides(int32_t index, int** nuclides, int* n); int openmc_tally_get_scores(int32_t index, int** scores, int* n); int openmc_tally_results(int32_t index, double** ptr, int shape_[3]); - int openmc_tally_set_filters(int32_t index, int n, int32_t* indices); + int openmc_tally_set_filters(int32_t index, int n, const int32_t* indices); int openmc_tally_set_id(int32_t index, int32_t id); - int openmc_tally_set_nuclides(int32_t index, int n, char* nuclides[]); - int openmc_tally_set_scores(int32_t index, int n, int* scores); + int openmc_tally_set_nuclides(int32_t index, int n, const char** nuclides); + int openmc_tally_set_scores(int32_t index, int n, const int* scores); // Error codes extern int E_UNASSIGNED; diff --git a/src/api.F90 b/src/api.F90 index 9db06ac205..eb9a996950 100644 --- a/src/api.F90 +++ b/src/api.F90 @@ -4,6 +4,7 @@ module openmc_api use hdf5, only: HID_T, h5tclose_f, h5close_f + use bank_header, only: openmc_source_bank use constants, only: K_BOLTZMANN use eigenvalue, only: k_sum, openmc_get_keff use error @@ -20,6 +21,8 @@ module openmc_api use random_lcg, only: seed, openmc_set_seed use settings use simulation_header + use source_header, only: openmc_extend_sources, openmc_source_set_strength + use state_point, only: openmc_statepoint_write use tally_header use tally_filter_header use tally_filter @@ -43,6 +46,7 @@ module openmc_api public :: openmc_extend_filters public :: openmc_extend_cells public :: openmc_extend_materials + public :: openmc_extend_sources public :: openmc_extend_tallies public :: openmc_filter_get_id public :: openmc_filter_get_type @@ -77,6 +81,8 @@ module openmc_api public :: openmc_run public :: openmc_simulation_finalize public :: openmc_simulation_init + public :: openmc_source_bank + public :: openmc_source_set_strength public :: openmc_tally_get_id public :: openmc_tally_get_filters public :: openmc_tally_get_n_realizations diff --git a/src/source_header.F90 b/src/source_header.F90 index fca05d8167..da15046ab8 100644 --- a/src/source_header.F90 +++ b/src/source_header.F90 @@ -17,6 +17,8 @@ module source_header implicit none private public :: free_memory_source + public :: openmc_extend_sources + public :: openmc_source_set_strength integer :: n_accept = 0 ! Number of samples accepted integer :: n_reject = 0 ! Number of samples rejected