From 7e19b82f9388b5beb8079fbb6a3f056a0e7f748a Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Fri, 29 Dec 2017 17:20:02 -0600 Subject: [PATCH] Update C API documentation --- docs/source/capi/index.rst | 417 +++++++++++++++++++++++++---------- include/openmc.h | 104 +++++++++ openmc/capi/cell.py | 2 + src/api.F90 | 7 +- src/geometry_header.F90 | 2 +- src/simulation.F90 | 1 + src/tallies/tally_header.F90 | 1 + 7 files changed, 417 insertions(+), 117 deletions(-) create mode 100644 include/openmc.h diff --git a/docs/source/capi/index.rst b/docs/source/capi/index.rst index 581f358d4f..ff19758bb3 100644 --- a/docs/source/capi/index.rst +++ b/docs/source/capi/index.rst @@ -8,14 +8,43 @@ C API Run a stochastic volume calculation +.. c:function:: int openmc_cell_get_fill(int32_t index, int* type, int32_t** indices, int32_t* n) + + Get the fill for a cell + + :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 + :return: Return status (negative if an error occurred) + :rtype: int + .. c:function:: int openmc_cell_get_id(int32_t index, int32_t* id) Get the ID of a cell - :param index: Index in the cells array - :type index: int32_t - :param id: ID of the cell - :type id: int32_t* + :param int32_t index: Index in the cells array + :param int32_t* id: ID of the cell + :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) + + 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 + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_cell_set_id(int32_t index, int32_t id) + + Set the ID of a cell + + :param int32_t index: Index in the cells array + :param int32_t id: ID of the cell :return: Return status (negative if an error occurred) :rtype: int @@ -23,13 +52,88 @@ C API Set the temperature of a cell. - :param index: Index in the cells array - :type index: int32_t - :param T: Temperature in Kelvin - :type T: double - :param instance: Which instance of the cell. To set the temperature for all - instances, pass a null pointer. - :type instance: int32_t* + :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. + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_energy_filter_get_bins(int32_t index, double** energies, int32_t* n) + + Return the bounding energies for an energy filter + + :param int32_t index: Index in the filters array + :param double** energies: Bounding energies of the bins for the energy filter + :param int32_t* n: Number of energies specified + :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) + + 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 + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_extend_cells(int32_t n, int32_t* index_start, int32_t* index_end) + + Extend the cells array by n elements + + :param int32_t n: Number of cells to create + :param int32_t* index_start: Index of first new cell + :param int32_t* index_end: Index of last new cell + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_extend_filters(int32_t n, int32_t* index_start, int32_t* index_end) + + Extend the filters array by n elements + + :param int32_t n: Number of filters to create + :param int32_t* index_start: Index of first new filter + :param int32_t* index_end: Index of last new filter + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_extend_materials(int32_t n, int32_t* index_start, int32_t* index_end) + + Extend the materials array by n elements + + :param int32_t n: Number of materials to create + :param int32_t* index_start: Index of first new material + :param int32_t* index_end: Index of last new material + :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 + + :param int32_t n: Number of tallies to create + :param int32_t* index_start: Index of first new tally + :param int32_t* index_end: Index of last new tally + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_filter_get_id(int32_t index, int32_t* id) + + Get the ID of a filter + + :param int32_t index: Index in the filters array + :param int32_t* id: ID of the filter + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_filter_set_id(int32_t index, int32_t id) + + Set the ID of a filter + + :param int32_t index: Index in the filters array + :param int32_t id: ID of the filter :return: Return status (negative if an error occurred) :rtype: int @@ -41,54 +145,41 @@ C API Determine the ID of the cell/material containing a given point - :param xyz: Cartesian coordinates - :type xyz: double[3] - :param rtype: Which ID to return (1=cell, 2=material) - :type rtype: int - :param 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. - :type id: int32_t* - :param instance: If a cell is repetaed in the geometry, the instance of the - cell that was found and zero otherwise. - :type instance: int32_t* + :param double[3] xyz: Cartesian coordinates + :param int rtype: Which ID to return (1=cell, 2=material) + :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 + of the cell that was found and zero otherwise. .. c:function:: 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 - :param id: ID of the cell - :type id: int32_t - :param index: Index in the cells array - :type index: int32_t* + :param int32_t id: ID of the cell + :param int32_t* index: Index in the cells array :return: Return status (negative if an error occurs) :rtype: int +.. c:function:: 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 + + :param int32_t id: ID of the filter + :param int32_t* index: Index in the filters array + :return: Return status (negative if an error occurs) + :rtype: int + +.. c:function:: void openmc_get_filter_next_id(int32_t* id) + + Get an integer ID that has not been used by any filters. + + :param int32_t* id: Unused integer ID + .. c:function:: int openmc_get_keff(double k_combined[]) - :param k_combined: Combined estimate of k-effective - :type k_combined: double[2] - :return: Return status (negative if an error occurs) - :rtype: int - -.. c:function:: int openmc_get_nuclide_index(char name[], int* index) - - Get the index in the nuclides array for a nuclide with a given name - - :param name: Name of the nuclide - :type name: char[] - :param index: Index in the nuclides array - :type index: int* - :return: Return status (negative if an error occurs) - :rtype: int - -.. c:function:: 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 - - :param id: ID of the tally - :type id: int32_t - :param index: Index in the tallies array - :type index: int32_t* + :param double[2] k_combined: Combined estimate of k-effective :return: Return status (negative if an error occurs) :rtype: int @@ -96,10 +187,26 @@ C API Get the index in the materials array for a material with a given ID - :param id: ID of the material - :type id: int32_t - :param index: Index in the materials array - :type index: int32_t* + :param int32_t id: ID of the material + :param int32_t* index: Index in the materials array + :return: Return status (negative if an error occurs) + :rtype: int + +.. c:function:: int openmc_get_nuclide_index(char name[], int* index) + + Get the index in the nuclides array for a nuclide with a given name + + :param char[] name: Name of the nuclide + :param int* index: Index in the nuclides array + :return: Return status (negative if an error occurs) + :rtype: int + +.. c:function:: 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 + + :param int32_t id: ID of the tally + :param int32_t* index: Index in the tallies array :return: Return status (negative if an error occurs) :rtype: int @@ -111,15 +218,13 @@ C API Initialize OpenMC - :param intracomm: MPI intracommunicator - :type intracomm: int + :param int intracomm: MPI intracommunicator .. c:function:: int openmc_load_nuclide(char name[]) Load data for a nuclide from the HDF5 data library. - :param name: Name of the nuclide. - :type name: char[] + :param char[] name: Name of the nuclide. :return: Return status (negative if an error occurs) :rtype: int @@ -128,27 +233,20 @@ C API Add a nuclide to an existing material. If the nuclide already exists, the density is overwritten. - :param index: Index in the materials array - :type index: int32_t - :param name: Name of the nuclide - :type name: char[] - :param density: Density in atom/b-cm - :type density: double + :param int32_t index: Index in the materials array + :param char[] name: Name of the nuclide + :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[]) +.. c:function:: int openmc_material_get_densities(int32_t index, int* nuclides[], double* densities[], int* n) Get density for each nuclide in a material. - :param index: Index in the materials array - :type index: int32_t - :param nuclides: Pointer to array of nuclide indices - :type nuclides: int** - :param densities: Pointer to the array of densities - :type densities: double** - :param n: Length of the array - :type n: int + :param int32_t index: Index in the materials array + :param int** nuclides: Pointer to array of nuclide indices + :param double** densities: Pointer to the array of densities + :param int* n: Length of the array :return: Return status (negative if an error occurs) :rtype: int @@ -156,10 +254,8 @@ C API Get the ID of a material - :param index: Index in the materials array - :type index: int32_t - :param id: ID of the material - :type id: int32_t* + :param int32_t index: Index in the materials array + :param int32_t* id: ID of the material :return: Return status (negative if an error occurred) :rtype: int @@ -167,34 +263,72 @@ C API Set the density of a material. - :param index: Index in the materials array - :type index: int32_t - :param density: Density of the material in atom/b-cm - :type density: double + :param int32_t index: Index in the materials array + :param double density: Density of the material in atom/b-cm :return: Return status (negative if an error occurs) :rtype: int -.. c:function:: int openmc_material_set_densities(int32_t, n, char* name[], double density[]) +.. c:function:: int openmc_material_set_densities(int32_t index, int n, char* name[], double density[]) - :param index: Index in the materials array - :type index: int32_t - :param n: Length of name/density - :type n: int - :param name: Array of nuclide names - :type name: char** - :param density: Array of densities - :type density: double[] + :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 :return: Return status (negative if an error occurs) :rtype: int +.. c:function:: int openmc_material_set_id(int32_t index, int32_t id) + + Set the ID of a material + + :param int32_t index: Index in the materials array + :param int32_t id: ID of the material + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_material_filter_get_bins(int32_t index, int32_t** bins, int32_t* n) + + Get the bins for a material filter + + :param int32_t index: Index in the filters array + :param int32_t** bins: Index in the materials array for each bin + :param int32_t* n: Number of bins + :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) + + 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 + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_mesh_filter_set_mesh(int32_t index, int32_t index_mesh) + + Set the mesh for a mesh filter + + :param int32_t index: Index in the filters array + :param int32_t index_mesh: Index in the meshes array + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_next_batch() + + Simulate next batch of particles. Must be called after openmc_simulation_init(). + + :return: Integer indicating whether simulation has finished (negative) or not + finished (zero). + :rtype: int + .. c:function:: int openmc_nuclide_name(int index, char* name[]) Get name of a nuclide - :param index: Index in the nuclides array - :type index: int - :param name: Name of the nuclide - :type name: char** + :param int index: Index in the nuclides array + :param char** name: Name of the nuclide :return: Return status (negative if an error occurs) :rtype: int @@ -210,14 +344,37 @@ C API Run a simulation +.. c:function:: void openmc_simulation_finalize() + + Finalize a simulation. + +.. c:function:: void openmc_simulation_init() + + Initialize a simulation. Must be called after openmc_init(). + .. c:function:: int openmc_tally_get_id(int32_t index, int32_t* id) Get the ID of a tally - :param index: Index in the tallies array - :type index: int32_t - :param id: ID of the tally - :type id: int32_t* + :param int32_t index: Index in the tallies array + :param int32_t* id: ID of the tally + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_tally_get_filters(int32_t index, int32_t** indices, int* n) + + Get filters specified in a tally + + :param int32_t index: Index in the tallies array + :param int32_t** indices: Array of filter indices + :param int* n: Number of filters + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_tally_get_n_realizations(int32_t index, int32_t* n) + + :param int32_t index: Index in the tallies array + :param int32_t* n: Number of realizations :return: Return status (negative if an error occurred) :rtype: int @@ -225,12 +382,19 @@ C API Get nuclides specified in a tally - :param index: Index in the tallies array - :type index: int32_t - :param nuclides: Array of nuclide indices - :type nuclides: int** - :param n: Number of nuclides - :type n: int* + :param int32_t index: Index in the tallies array + :param int** nuclides: Array of nuclide indices + :param int* n: Number of nuclides + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_tally_get_scores(int32_t index, int** scores, int* n) + + Get scores specified for a tally + + :param int32_t index: Index in the tallies array + :param int** scores: Array of scores + :param int* n: Number of scores :return: Return status (negative if an error occurred) :rtype: int @@ -238,12 +402,28 @@ C API Get a pointer to tally results array. - :param index: Index in the tallies array - :type index: int32_t - :param ptr: Pointer to the results array - :type ptr: double** - :param shape_: Shape of the results array - :type shape_: int[3] + :param int32_t index: Index in the tallies array + :param double** ptr: Pointer to the results array + :param int[3] shape_: Shape of the results array + :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) + + 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 + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_tally_set_id(int32_t index, int32_t id) + + Set the ID of a tally + + :param int32_t index: Index in the tallies array + :param int32_t id: ID of the tally :return: Return status (negative if an error occurred) :rtype: int @@ -251,11 +431,18 @@ C API Set the nuclides for a tally - :param index: Index in the tallies array - :type index: int32_t - :param n: Number of nuclides - :type n: int - :param nuclides: Array of nuclide names - :type nuclides: char** + :param int32_t index: Index in the tallies array + :param int n: Number of nuclides + :param char** nuclides: Array of nuclide names + :return: Return status (negative if an error occurred) + :rtype: int + +.. c:function:: int openmc_tally_set_scores(int32_t index, int n, 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 :return: Return status (negative if an error occurred) :rtype: int diff --git a/include/openmc.h b/include/openmc.h new file mode 100644 index 0000000000..5f72e99ed2 --- /dev/null +++ b/include/openmc.h @@ -0,0 +1,104 @@ +#ifndef OPENMC_H +#define OPENMC_H + +#include +#include + +#ifdef __cplusplus +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(); + + 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_id(int32_t index, int32_t id); + int openmc_cell_set_temperature(int32_t index, double T, 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_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_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); + 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); + void openmc_get_filter_next_id(int32_t* id); + 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_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_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_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_mesh_filter_set_mesh(int32_t index, int32_t index_mesh); + int openmc_nuclide_name(int index, char* name[]); + 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_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_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); + + // Error codes + extern int E_UNASSIGNED; + extern int E_ALLOCATE; + extern int E_OUT_OF_BOUNDS; + extern int E_INVALID_SIZE; + extern int E_INVALID_ARGUMENT; + extern int E_INVALID_TYPE; + extern int E_INVALID_ID; + extern int E_GEOMETRY; + extern int E_DATA; + extern int E_PHYSICS; + extern int E_WARNING; + + // Global variables + extern char openmc_err_msg[256]; + extern double keff; + extern double keff_std; + extern int32_t n_batches; + extern int32_t n_cells; + extern int32_t n_filters; + extern int32_t n_inactive; + extern int32_t n_lattices; + extern int32_t n_materials; + extern int32_t n_meshes; + extern int64_t n_particles; + extern int32_t n_plots; + extern int32_t n_realizations; + extern int32_t n_sab_tables; + extern int32_t n_sources; + extern int32_t n_surfaces; + extern int32_t n_tallies; + extern int32_t n_universes; + extern int run_mode; + extern bool simulation_initialized; + extern int verbosity; + +#ifdef __cplusplus +} +#endif + +#endif // OPENMC_H diff --git a/openmc/capi/cell.py b/openmc/capi/cell.py index f13f64a045..0c4b72c749 100644 --- a/openmc/capi/cell.py +++ b/openmc/capi/cell.py @@ -21,6 +21,8 @@ _dll.openmc_cell_get_id.restype = c_int _dll.openmc_cell_get_id.errcheck = _error_handler _dll.openmc_cell_get_fill.argtypes = [ c_int32, POINTER(c_int), POINTER(POINTER(c_int32)), POINTER(c_int32)] +_dll.openmc_cell_get_fill.restype = c_int +_dll.openmc_cell_get_fill.errcheck = _error_handler _dll.openmc_cell_set_fill.argtypes = [ c_int32, c_int, c_int32, POINTER(c_int32)] _dll.openmc_cell_set_fill.restype = c_int diff --git a/src/api.F90 b/src/api.F90 index 326b755b6a..9db06ac205 100644 --- a/src/api.F90 +++ b/src/api.F90 @@ -24,7 +24,7 @@ module openmc_api use tally_filter_header use tally_filter use tally, only: openmc_tally_set_type - use simulation, only: openmc_run + use simulation use string, only: to_f_string use timer_header use volume_calc, only: openmc_calculate_volumes @@ -57,6 +57,7 @@ module openmc_api public :: openmc_get_material_index public :: openmc_get_nuclide_index public :: openmc_get_tally_index + public :: openmc_global_tallies public :: openmc_hard_reset public :: openmc_init public :: openmc_load_nuclide @@ -69,12 +70,16 @@ module openmc_api public :: openmc_material_filter_get_bins public :: openmc_material_filter_set_bins public :: openmc_mesh_filter_set_mesh + public :: openmc_next_batch public :: openmc_nuclide_name public :: openmc_plot_geometry public :: openmc_reset public :: openmc_run + public :: openmc_simulation_finalize + public :: openmc_simulation_init public :: openmc_tally_get_id public :: openmc_tally_get_filters + public :: openmc_tally_get_n_realizations public :: openmc_tally_get_nuclides public :: openmc_tally_get_scores public :: openmc_tally_results diff --git a/src/geometry_header.F90 b/src/geometry_header.F90 index b827c055c1..e71916d096 100644 --- a/src/geometry_header.F90 +++ b/src/geometry_header.F90 @@ -524,7 +524,7 @@ contains function openmc_cell_set_fill(index, type, n, indices) result(err) bind(C) - ! Set the fill for a fill + ! Set the fill for a cell integer(C_INT32_T), value, intent(in) :: index ! index in cells integer(C_INT), value, intent(in) :: type integer(c_INT32_T), value, intent(in) :: n diff --git a/src/simulation.F90 b/src/simulation.F90 index e8997fc9b8..026c9c61e7 100644 --- a/src/simulation.F90 +++ b/src/simulation.F90 @@ -43,6 +43,7 @@ module simulation implicit none private + public :: openmc_next_batch public :: openmc_run public :: openmc_simulation_init public :: openmc_simulation_finalize diff --git a/src/tallies/tally_header.F90 b/src/tallies/tally_header.F90 index fa397632f7..474e77d1ce 100644 --- a/src/tallies/tally_header.F90 +++ b/src/tallies/tally_header.F90 @@ -26,6 +26,7 @@ module tally_header public :: openmc_global_tallies public :: openmc_tally_get_id public :: openmc_tally_get_filters + public :: openmc_tally_get_n_realizations public :: openmc_tally_get_nuclides public :: openmc_tally_get_scores public :: openmc_tally_results