preCICE v3.2.0
|
C language bindings to main Application Programming Interface of preCICE. More...
#include <precice/Version.h>
#include <precice/export.h>
Go to the source code of this file.
Functions | |
PRECICE_API const char * | precicec_getVersionInformation () |
Returns information on the version of preCICE. | |
Construction and Configuration | |
PRECICE_API void | precicec_createParticipant_withCommunicator (const char *participantName, const char *configFileName, int solverProcessIndex, int solverProcessSize, void *communicator) |
PRECICE_API void | precicec_createParticipant (const char *participantName, const char *configFileName, int solverProcessIndex, int solverProcessSize) |
Creates the coupling interface and configures it. | |
Steering Methods | |
PRECICE_API void | precicec_initialize () |
Initiates the coupling to the coupling supervisor and initializes coupling data. | |
PRECICE_API void | precicec_advance (double computedTimeStepSize) |
Exchanges data between solver and coupling supervisor. | |
PRECICE_API void | precicec_finalize () |
Finalizes the coupling to the coupling supervisor. | |
Implicit coupling | |
PRECICE_API int | precicec_requiresWritingCheckpoint () |
PRECICE_API int | precicec_requiresReadingCheckpoint () |
Status Queries | |
PRECICE_API int | precicec_getMeshDimensions (const char *meshName) |
Returns the spatial dimensionality of the given mesh. | |
PRECICE_API int | precicec_getDataDimensions (const char *meshName, const char *dataName) |
Returns the spatial dimensionality of the given data on the given mesh. | |
PRECICE_API int | precicec_isCouplingOngoing () |
Returns true (->1), if the coupled simulation is ongoing. | |
PRECICE_API int | precicec_isTimeWindowComplete () |
Returns true (->1), if the coupling time window is completed. | |
PRECICE_API double | precicec_getMaxTimeStepSize () |
Returns maximum allowed time step size. | |
Mesh Access | |
PRECICE_API int | precicec_requiresMeshConnectivityFor (const char *meshName) |
PRECICE_API void | precicec_resetMesh (const char *meshName) |
Removes all vertices and connectivity information from the mesh. | |
PRECICE_API int | precicec_setMeshVertex (const char *meshName, const double *coordinates) |
Creates a mesh vertex. | |
PRECICE_API int | precicec_getMeshVertexSize (const char *meshName) |
Returns the number of vertices of a mesh. | |
PRECICE_API void | precicec_setMeshVertices (const char *meshName, int size, const double *coordinates, int *ids) |
Creates multiple mesh vertices. | |
PRECICE_API void | precicec_setMeshEdge (const char *meshName, int firstVertexID, int secondVertexID) |
Sets mesh edge from vertex IDs. | |
PRECICE_API void | precicec_setMeshEdges (const char *meshName, int size, const int *ids) |
Sets multiple mesh edge from vertex IDs. | |
PRECICE_API void | precicec_setMeshTriangle (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID) |
Sets a triangle from vertex IDs. Creates missing edges. | |
PRECICE_API void | precicec_setMeshTriangles (const char *meshName, int size, const int *ids) |
Sets multiple mesh triangles from vertex IDs. | |
PRECICE_API void | precicec_setMeshQuad (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID) |
Sets surface mesh quadrangle from vertex IDs. | |
PRECICE_API void | precicec_setMeshQuads (const char *meshName, int size, const int *ids) |
Sets multiple mesh quads from vertex IDs. | |
PRECICE_API void | precicec_setMeshTetrahedron (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID) |
Sets mesh tetrahedron from vertex IDs. | |
PRECICE_API void | precicec_setMeshTetrahedra (const char *meshName, int size, const int *ids) |
Sets multiple mesh tetrahedra from vertex IDs. | |
Data Access | |
PRECICE_API int | precicec_requiresInitialData () |
PRECICE_API void | precicec_writeData (const char *meshName, const char *dataName, int size, const int *valueIndices, const double *values) |
Writes vector data values given as block. | |
PRECICE_API void | precicec_readData (const char *meshName, const char *dataName, int size, const int *valueIndices, double relativeReadTime, double *values) |
Reads vector data values given as block. | |
Just-in-time mapping | |
PRECICE_API void | precicec_writeAndMapData (const char *meshName, const char *dataName, int size, const double *coordinates, const double *values) |
Writes data using just-in-time data mapping See. | |
PRECICE_API void | precicec_mapAndReadData (const char *meshName, const char *dataName, int size, const double *coordinates, double relativeReadTime, double *values) |
Reads data using just-in-time data mapping. See. | |
Direct mesh access | |
PRECICE_API void | precicec_setMeshAccessRegion (const char *meshName, const double *boundingBox) |
See precice::Participant::setMeshAccessRegion(). | |
PRECICE_API void | precicec_getMeshVertexIDsAndCoordinates (const char *meshName, const int size, int *ids, double *coordinates) |
See precice::Participant::getMeshVertexIDsAndCoordinates(). | |
Experimental Gradient Data | |
These API functions are experimental and may change in future versions. | |
PRECICE_API int | precicec_requiresGradientDataFor (const char *meshName, const char *dataName) |
Checks if the given data set requires gradient data. We check if the data object has been initialized with the gradient flag. | |
PRECICE_API void | precicec_writeGradientData (const char *meshName, const char *dataName, int size, const int *valueIndices, const double *gradients) |
Writes vector gradient data to a mesh. | |
User-defined profiling | |
PRECICE_API void | precicec_startProfilingSection (const char *sectionName) |
PRECICE_API void | precicec_stopLastProfilingSection () |
C language bindings to main Application Programming Interface of preCICE.
The C bindings are thin wrappers around the C++ API.
Refer to precice::Participant for detailed documentation.
Definition in file preciceC.h.
PRECICE_API void precicec_advance | ( | double | computedTimeStepSize | ) |
Exchanges data between solver and coupling supervisor.
[in] | computedTimeStepSize | Size of time step computed by solver. |
Definition at line 68 of file preciceC.cpp.
PRECICE_API void precicec_createParticipant | ( | const char * | participantName, |
const char * | configFileName, | ||
int | solverProcessIndex, | ||
int | solverProcessSize ) |
Creates the coupling interface and configures it.
Has to be called before any other method of this interface.
[in] | participantName | Name of the participant accessing the interface. Has to match one of the names specified in the configuration xml file. |
[in] | configFileName | (Path and) name of the xml configuration file containing the precice configuration. |
[in] | solverProcessIndex | If the solver code runs with several processes, each process using preCICE has to specify its index, which has to start from 0 and end with solverProcessSize - 1. |
[in] | solverProcessSize | The number of solver processes using preCICE. |
Definition at line 45 of file preciceC.cpp.
PRECICE_API void precicec_createParticipant_withCommunicator | ( | const char * | participantName, |
const char * | configFileName, | ||
int | solverProcessIndex, | ||
int | solverProcessSize, | ||
void * | communicator ) |
[in] | participantName | Name of the participant using the interface. Has to match the name given for a participant in the xml configuration file. |
[in] | configurationFileName | Name (with path) of the xml configuration file. |
[in] | solverProcessIndex | If the solver code runs with several processes, each process using preCICE has to specify its index, which has to start from 0 and end with solverProcessSize - 1. |
[in] | solverProcessSize | The number of solver processes using preCICE. |
[in] | communicator | A pointer to an MPI_Comm to use as communicator. |
Definition at line 28 of file preciceC.cpp.
PRECICE_API void precicec_finalize | ( | ) |
Finalizes the coupling to the coupling supervisor.
Definition at line 76 of file preciceC.cpp.
PRECICE_API int precicec_getDataDimensions | ( | const char * | meshName, |
const char * | dataName ) |
Returns the spatial dimensionality of the given data on the given mesh.
Note that vectorial data dimensionality directly depends on the spatial dimensionality of the mesh.
[in] | meshName | the name of the associated mesh |
[in] | dataName | the name of the data to get the dimensions for |
Definition at line 94 of file preciceC.cpp.
PRECICE_API double precicec_getMaxTimeStepSize | ( | ) |
Returns maximum allowed time step size.
Definition at line 127 of file preciceC.cpp.
PRECICE_API int precicec_getMeshDimensions | ( | const char * | meshName | ) |
Returns the spatial dimensionality of the given mesh.
[in] | meshName | the name of the associated mesh |
Definition at line 85 of file preciceC.cpp.
PRECICE_API void precicec_getMeshVertexIDsAndCoordinates | ( | const char * | meshName, |
const int | size, | ||
int * | ids, | ||
double * | coordinates ) |
See precice::Participant::getMeshVertexIDsAndCoordinates().
Definition at line 418 of file preciceC.cpp.
PRECICE_API int precicec_getMeshVertexSize | ( | const char * | meshName | ) |
Returns the number of vertices of a mesh.
[in] | meshName | the name of the mesh. |
Definition at line 208 of file preciceC.cpp.
PRECICE_API const char * precicec_getVersionInformation | ( | ) |
Returns information on the version of preCICE.
Returns a semicolon-separated C-string containing:
1) the version of preCICE 2) the revision information of preCICE 3) the configuration of preCICE including MPI, PETSC, PYTHON
Definition at line 403 of file preciceC.cpp.
PRECICE_API void precicec_initialize | ( | ) |
Initiates the coupling to the coupling supervisor and initializes coupling data.
Definition at line 60 of file preciceC.cpp.
PRECICE_API int precicec_isCouplingOngoing | ( | ) |
Returns true (->1), if the coupled simulation is ongoing.
Definition at line 103 of file preciceC.cpp.
PRECICE_API int precicec_isTimeWindowComplete | ( | ) |
Returns true (->1), if the coupling time window is completed.
Definition at line 115 of file preciceC.cpp.
PRECICE_API void precicec_mapAndReadData | ( | const char * | meshName, |
const char * | dataName, | ||
int | size, | ||
const double * | coordinates, | ||
double | relativeReadTime, | ||
double * | values ) |
Reads data using just-in-time data mapping. See.
[in] | meshName | Name of the mesh to write and map the data to. Typically a received mesh |
[in] | dataName | Name of the data to field on this mesh. |
[in] | size | Number of vertices to write |
[in] | coordinates | Pointer to the coordinates where we read the data. Needs to have size x precicec_getMeshDimensions( meshName ) entries |
[in] | relativeReadTime | Same as in |
[in/out] | values Pointer to the values to be filled by preCICE. Needs to have size x precicec_getDataDimensions( meshName , dataName ) entries |
Reads data values from a mesh using a just-in-time data mapping. Values correspond to a given point in time relative to the beginning of the current timestep (experimental).
This function reads values at temporary locations from data of a mesh. As opposed to the readData function using VertexIDs, this function allows reading data via coordinates, which don't have to be specified during the initialization. This is particularly useful for meshes, which vary over time. Note that using this function comes at a performance cost, since the specified mapping needs to be computed locally for the given locations, whereas the other variant (readData) can typically exploit the static interface mesh and pre-compute data structures more efficient.
Values are read into a block of continuous memory defined by values in the order specified by vertices.
The 1D/Scalar-format of values is (d0, d1, ..., dn) The 2D-format of values is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format of values is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)
The data is read at relativeReadTime, which indicates the point in time measured from the beginning of the current time step. relativeReadTime = 0 corresponds to data at the beginning of the time step. Assuming that the user will call advance(dt) at the end of the time step, dt indicates the size of the current time step. Then relativeReadTime = dt corresponds to the data at the end of the time step.
[in] | meshName | The name of the mesh that holds the data, needs to be a mesh received from another participant. |
[in] | dataName | The name of the data to read from. |
[in] | coordinates | a span to the coordinates of the vertices The 2D-format is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz) |
[in] | relativeReadTime | Point in time where data is read relative to the beginning of the current time step. |
[out] | values | The destination memory to read the data from. |
values
contain the read data as specified in the above format.relativeReadTime
on each individual rank. As a result, calling the function for different coordinates
while keeping the relativeReadTime
constant is more efficient than calling it for varying relativeReadTime
values at each coordinate
. In practice, this means that iterating over time (i.e., varying relativeReadTime
) in the outer loop and over space (i.e., iterating over coordinates
) in the inner loop gives a significantly better performance than vice versa.Definition at line 359 of file preciceC.cpp.
PRECICE_API void precicec_readData | ( | const char * | meshName, |
const char * | dataName, | ||
int | size, | ||
const int * | valueIndices, | ||
double | relativeReadTime, | ||
double * | values ) |
Reads vector data values given as block.
The block contains the vector values in the following form: values = (d0x, d0y, d0z, d1x, d1y, d1z, ...., dnx, dny, dnz), where n is the number of vector values. In 2D, the z-components are removed.
[in] | meshName | the name of the mesh |
[in] | dataName | the name of the data to be read. |
[in] | size | Number of indices, and number of values * dimensions. |
[in] | valueIndices | Indices (from setReadPosition()) of data values. |
[in] | relativeReadTime | Point in time where data is read relative to the beginning of the current time step. |
[in] | values | Values of the data to be read. |
Definition at line 329 of file preciceC.cpp.
PRECICE_API int precicec_requiresGradientDataFor | ( | const char * | meshName, |
const char * | dataName ) |
Checks if the given data set requires gradient data. We check if the data object has been initialized with the gradient flag.
preCICE may require gradient data information from the solver and ignores any API calls regarding gradient data if it is not required. (When applying a nearest-neighbor-gradient mapping)
[in] | meshName | the name of mesh that hold the data. |
[in] | dataName | the name of the data. |
Definition at line 375 of file preciceC.cpp.
PRECICE_API int precicec_requiresInitialData | ( | ) |
Checks if the participant is required to provide initial data.
If true, then the participant needs to write initial data to defined vertices prior to calling initialize().
Definition at line 135 of file preciceC.cpp.
PRECICE_API int precicec_requiresMeshConnectivityFor | ( | const char * | meshName | ) |
Checks if the given mesh requires connectivity.
preCICE may require connectivity information from the solver and ignores any API calls regarding connectivity if it is not required. Use this function to conditionally generate this connectivity.
[in] | meshName | the name of the mesh |
Definition at line 162 of file preciceC.cpp.
PRECICE_API int precicec_requiresReadingCheckpoint | ( | ) |
Checks if the participant is required to read an iteration checkpoint.
If true, the participant is required to read an iteration checkpoint before calling advance().
Definition at line 153 of file preciceC.cpp.
PRECICE_API int precicec_requiresWritingCheckpoint | ( | ) |
Checks if the participant is required to write an iteration checkpoint.
If true, the participant is required to write an iteration checkpoint before calling advance().
Definition at line 144 of file preciceC.cpp.
PRECICE_API void precicec_resetMesh | ( | const char * | meshName | ) |
Removes all vertices and connectivity information from the mesh.
Allows redefining a mesh during runtime. After the call to resetMesh(), the mesh vertices need to be set with setMeshVertex() and setMeshVertices() again. Connectivity information may be set as well.
Reading data from this mesh using readData() is not possible until the next call to advance().
[in] | meshName | the name of the mesh to reset |
Definition at line 174 of file preciceC.cpp.
PRECICE_API void precicec_setMeshAccessRegion | ( | const char * | meshName, |
const double * | boundingBox ) |
See precice::Participant::setMeshAccessRegion().
Definition at line 408 of file preciceC.cpp.
PRECICE_API void precicec_setMeshEdge | ( | const char * | meshName, |
int | firstVertexID, | ||
int | secondVertexID ) |
Sets mesh edge from vertex IDs.
[in] | meshName | the name of the mesh to add the edge to |
[in] | firstVertexID | ID of the first vertex of the edge |
[in] | secondVertexID | ID of the second vertex of the edge |
meshName
Definition at line 218 of file preciceC.cpp.
PRECICE_API void precicec_setMeshEdges | ( | const char * | meshName, |
int | size, | ||
const int * | ids ) |
Sets multiple mesh edge from vertex IDs.
[in] | meshName | the name of the mesh to add the edges to |
[in] | size | the amount of edges to set |
[in] | ids | an array containing 2*size vertex IDs |
meshName
Definition at line 229 of file preciceC.cpp.
PRECICE_API void precicec_setMeshQuad | ( | const char * | meshName, |
int | firstVertexID, | ||
int | secondVertexID, | ||
int | thirdVertexID, | ||
int | fourthVertexID ) |
Sets surface mesh quadrangle from vertex IDs.
[in] | meshName | the name of the mesh to add the Quad to |
[in] | firstVertexID | ID of the first vertex of the Quad |
[in] | secondVertexID | ID of the second vertex of the Quad |
[in] | thirdVertexID | ID of the third vertex of the Quad |
[in] | fourthVertexID | ID of the fourth vertex of the Quad |
Definition at line 265 of file preciceC.cpp.
PRECICE_API void precicec_setMeshQuads | ( | const char * | meshName, |
int | size, | ||
const int * | ids ) |
Sets multiple mesh quads from vertex IDs.
[in] | meshName | the name of the mesh to add the quad to |
[in] | size | the amount of quads to set |
[in] | ids | an array containing 4*size vertex IDs |
meshName
Definition at line 278 of file preciceC.cpp.
PRECICE_API void precicec_setMeshTetrahedra | ( | const char * | meshName, |
int | size, | ||
const int * | ids ) |
Sets multiple mesh tetrahedra from vertex IDs.
[in] | meshName | the name of the mesh to add the tetrahedra to |
[in] | size | the amount of tetrahedra to set |
[in] | ids | an array containing 4*size vertex IDs |
meshName
Definition at line 303 of file preciceC.cpp.
PRECICE_API void precicec_setMeshTetrahedron | ( | const char * | meshName, |
int | firstVertexID, | ||
int | secondVertexID, | ||
int | thirdVertexID, | ||
int | fourthVertexID ) |
Sets mesh tetrahedron from vertex IDs.
[in] | meshName | the name of the mesh to add the Tetra to |
[in] | firstVertexID | ID of the first vertex of the Tetra |
[in] | secondVertexID | ID of the second vertex of the Tetra |
[in] | thirdVertexID | ID of the third vertex of the Tetra |
[in] | fourthVertexID | ID of the fourth vertex of the Tetra |
Definition at line 290 of file preciceC.cpp.
PRECICE_API void precicec_setMeshTriangle | ( | const char * | meshName, |
int | firstVertexID, | ||
int | secondVertexID, | ||
int | thirdVertexID ) |
Sets a triangle from vertex IDs. Creates missing edges.
Definition at line 241 of file preciceC.cpp.
PRECICE_API void precicec_setMeshTriangles | ( | const char * | meshName, |
int | size, | ||
const int * | ids ) |
Sets multiple mesh triangles from vertex IDs.
[in] | meshName | the name of the mesh to add the triangles to |
[in] | size | the amount of triangles to set |
[in] | ids | an array containing 3*size vertex IDs |
ids
were added to the mesh with the name meshName
Definition at line 253 of file preciceC.cpp.
PRECICE_API int precicec_setMeshVertex | ( | const char * | meshName, |
const double * | coordinates ) |
Creates a mesh vertex.
[in] | meshName | the name of the mesh to add the vertex to. |
[in] | coordinates | a pointer to the coordinates of the vertex. |
Definition at line 182 of file preciceC.cpp.
PRECICE_API void precicec_setMeshVertices | ( | const char * | meshName, |
int | size, | ||
const double * | coordinates, | ||
int * | ids ) |
Creates multiple mesh vertices.
[in] | meshName | the name of the mesh to add the vertices to. |
[in] | size | Number of vertices to create |
[in] | coordinates | a pointer to the coordinates of the vertices The 2D-format is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz) |
[out] | ids | The ids of the created vertices |
Definition at line 194 of file preciceC.cpp.
PRECICE_API void precicec_startProfilingSection | ( | const char * | sectionName | ) |
Start a named user-defined profiling section
Starts a profiling section to record with the given name. This action is active until it is stopped by stopLastProfilingSection().
All active sections must be stopped before calling initialize() or advance().
[in] | sectionName | the name of the profiling section to start. The name may not contain forward slashes /. |
Definition at line 430 of file preciceC.cpp.
PRECICE_API void precicec_stopLastProfilingSection | ( | ) |
Stop the last profiling section
Definition at line 437 of file preciceC.cpp.
PRECICE_API void precicec_writeAndMapData | ( | const char * | meshName, |
const char * | dataName, | ||
int | size, | ||
const double * | coordinates, | ||
const double * | values ) |
Writes data using just-in-time data mapping See.
[in] | meshName | Name of the mesh to write and map the data to. Typically a received mesh |
[in] | dataName | Name of the data to field on this mesh. |
[in] | size | Number of vertices to write |
[in] | coordinates | Pointer to the coordinates where we write the data. Needs to have size x precicec_getMeshDimensions( meshName ) entries |
[in] | values | Pointer to the data values we want to pass to preCICE. Needs to have size x precicec_getDataDimensions( meshName , dataName ) entries |
Writes data values to a mesh using a just-in-time mapping (experimental).
This function writes values at temporary locations to data of a mesh. As opposed to the writeData function using VertexIDs, this function allows to write data via coordinates, which don't have to be specified during the initialization. This is particularly useful for meshes, which vary over time. Note that using this function comes at a performance cost, since the specified mapping needs to be computed locally for the given locations, whereas the other variant (writeData) can typically exploit the static interface mesh and pre-compute data structures more efficiently.
Values are passed via a block of continuous memory defined by values in the order specified by vertices.
The 1D/Scalar-format of values is (d0, d1, ..., dn) The 2D-format of values is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format of values is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)
[in] | meshName | The name of the mesh that holds the data, needs to be a mesh received from another participant. |
[in] | dataName | The name of the data to write. |
[in] | coordinates | A span to the coordinates of the vertices The 2D-format is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz) |
[in] | values | The values containing the write data. |
Definition at line 344 of file preciceC.cpp.
PRECICE_API void precicec_writeData | ( | const char * | meshName, |
const char * | dataName, | ||
int | size, | ||
const int * | valueIndices, | ||
const double * | values ) |
Writes vector data values given as block.
The block must contain the vector values in the following form: values = (d0x, d0y, d0z, d1x, d1y, d1z, ...., dnx, dny, dnz), where n is the number of vector values. In 2D, the z-components are removed.
[in] | meshName | the name of the mesh |
[in] | dataName | the name of the data to be written. |
[in] | size | Number of indices, and number of values * dimensions. |
[in] | values | Values of the data to be written. |
Definition at line 315 of file preciceC.cpp.
PRECICE_API void precicec_writeGradientData | ( | const char * | meshName, |
const char * | dataName, | ||
int | size, | ||
const int * | valueIndices, | ||
const double * | gradients ) |
Writes vector gradient data to a mesh.
This function writes gradient values of specified vertices to data of a mesh. Values are provided as a block of continuous memory defined by gradients. The order of the provided gradient data follows the order specified by vertices.
Each gradient or Jacobian depends on the dimensionality of the mesh and data. Each gradient has a total of getMeshDimensions(meshName) * getDataDimensions(meshName, dataName) components and is stored in a linearised format as follows:
Spatial Dimensions | Scalar Data | Vectorial Data |
---|---|---|
2D | s dx, s dy | x dx, y dx, x dy, y dy |
3D | s dy, s dy, s dz | x dx, y dx, z dx, x dy, y dy, z dy, x dz, y dz, z dz |
The gradients/Jacobian for all vertices are then contiguously saved in memory.
Example for 2D Vectorial:
Index | 0 | 1 | 2 | 3 | ... | 4n | 4n+1 | 4n+2 | 4n+3 |
---|---|---|---|---|---|---|---|---|---|
Component | x0 dx | y0 dx | x0 dy | y0 dy | ... | xn dx | yn dx | xn dy | yn dy |
[in] | meshName | the name of mesh that hold the data. |
[in] | dataName | the name of the data to write to. |
[in] | ids | the vertex ids of the vertices to write gradient data to. |
[in] | gradients | the linearised gradient data to write to preCICE. |
Definition at line 388 of file preciceC.cpp.