preCICE v3.1.2
Loading...
Searching...
No Matches
Functions | Variables
preciceC.cpp File Reference
#include "precice/preciceC.h"
#include <memory>
#include <string>
#include "logging/LogMacros.hpp"
#include "logging/Logger.hpp"
#include "precice/impl/versions.hpp"
#include "precice/precice.hpp"
#include "utils/assertion.hpp"
Include dependency graph for preciceC.cpp:

Go to the source code of this file.

Functions

void precicec_createParticipant_withCommunicator (const char *participantName, const char *configFileName, int solverProcessIndex, int solverProcessSize, void *communicator)
 
void precicec_createParticipant (const char *participantName, const char *configFileName, int solverProcessIndex, int solverProcessSize)
 Creates the coupling interface and configures it.
 
void precicec_initialize ()
 Initiates the coupling to the coupling supervisor and initializes coupling data.
 
void precicec_advance (double computedTimeStepSize)
 Exchanges data between solver and coupling supervisor.
 
void precicec_finalize ()
 Finalizes the coupling to the coupling supervisor.
 
int precicec_getMeshDimensions (const char *meshName)
 Returns the spatial dimensionality of the given mesh.
 
int precicec_getDataDimensions (const char *meshName, const char *dataName)
 Returns the spatial dimensionality of the given data on the given mesh.
 
int precicec_isCouplingOngoing ()
 Returns true (->1), if the coupled simulation is ongoing.
 
int precicec_isTimeWindowComplete ()
 Returns true (->1), if the coupling time window is completed.
 
double precicec_getMaxTimeStepSize ()
 Returns maximum allowed time step size.
 
int precicec_requiresInitialData ()
 
int precicec_requiresWritingCheckpoint ()
 
int precicec_requiresReadingCheckpoint ()
 
int precicec_requiresMeshConnectivityFor (const char *meshName)
 Checks if the given mesh requires connectivity.
 
int precicec_setMeshVertex (const char *meshName, const double *position)
 Creates a mesh vertex.
 
void precicec_setMeshVertices (const char *meshName, int size, const double *positions, int *ids)
 Creates multiple mesh vertices.
 
int precicec_getMeshVertexSize (const char *meshName)
 Returns the number of vertices of a mesh.
 
void precicec_setMeshEdge (const char *meshName, int firstVertexID, int secondVertexID)
 Sets mesh edge from vertex IDs.
 
void precicec_setMeshEdges (const char *meshName, int size, const int *vertices)
 Sets multiple mesh edge from vertex IDs.
 
void precicec_setMeshTriangle (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID)
 Sets a triangle from vertex IDs. Creates missing edges.
 
void precicec_setMeshTriangles (const char *meshName, int size, const int *vertices)
 Sets multiple mesh triangles from vertex IDs.
 
void precicec_setMeshQuad (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID)
 Sets surface mesh quadrangle from vertex IDs.
 
void precicec_setMeshQuads (const char *meshName, int size, const int *vertices)
 Sets multiple mesh quads from vertex IDs.
 
void precicec_setMeshTetrahedron (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID)
 Sets mesh tetrahedron from vertex IDs.
 
void precicec_setMeshTetrahedra (const char *meshName, int size, const int *vertices)
 Sets multiple mesh tetrahedra from vertex IDs.
 
void precicec_writeData (const char *meshName, const char *dataName, int size, const int *valueIndices, const double *values)
 Writes vector data values given as block.
 
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.
 
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.
 
void precicec_writeGradientData (const char *meshName, const char *dataName, int size, const int *valueIndices, const double *gradients)
 Writes vector gradient data to a mesh.
 
const char * precicec_getVersionInformation ()
 Returns information on the version of preCICE.
 
void precicec_setMeshAccessRegion (const char *meshName, const double *boundingBox)
 See precice::Participant::setMeshAccessRegion().
 
void precicec_getMeshVertexIDsAndCoordinates (const char *meshName, const int size, int *ids, double *coordinates)
 See precice::Participant::getMeshVertexIDsAndCoordinates().
 

Variables

static std::unique_ptr< precice::Participantimpl = nullptr
 
static precice::logging::Logger _log ("precicec")
 
static std::string errormsg = "preCICE has not been created properly. Be sure to call \"precicec_createParticipant\" or \"precicec_createParticipant_withCommunicator\" before any other call to preCICE."
 
static std::string errormsgCreate = "preCICE has been created already! Be sure to call either \"precicec_createParticipant\" or \"precicec_createParticipant_withCommunicator\" exactly once."
 

Function Documentation

◆ precicec_advance()

void precicec_advance ( double computedTimeStepSize)

Exchanges data between solver and coupling supervisor.

Parameters
[in]computedTimeStepSizeSize of time step computed by solver.

Definition at line 62 of file preciceC.cpp.

◆ precicec_createParticipant()

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.

Parameters
[in]participantNameName 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]solverProcessIndexIf 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]solverProcessSizeThe number of solver processes using preCICE.

Definition at line 43 of file preciceC.cpp.

◆ precicec_createParticipant_withCommunicator()

void precicec_createParticipant_withCommunicator ( const char * participantName,
const char * configFileName,
int solverProcessIndex,
int solverProcessSize,
void * communicator )
Parameters
[in]participantNameName of the participant using the interface. Has to match the name given for a participant in the xml configuration file.
[in]configurationFileNameName (with path) of the xml configuration file.
[in]solverProcessIndexIf 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]solverProcessSizeThe number of solver processes using preCICE.
[in]communicatorA pointer to an MPI_Comm to use as communicator.

Definition at line 28 of file preciceC.cpp.

◆ precicec_finalize()

void precicec_finalize ( )

Finalizes the coupling to the coupling supervisor.

Definition at line 68 of file preciceC.cpp.

◆ precicec_getDataDimensions()

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 spacial dimensionality of the mesh.

Parameters
[in]meshNamethe name of the associated mesh
[in]dataNamethe name of the data to get the dimensions for
Returns
the dimensions of the given Data
See also
getMeshDimensions

Definition at line 81 of file preciceC.cpp.

◆ precicec_getMaxTimeStepSize()

double precicec_getMaxTimeStepSize ( )

Returns maximum allowed time step size.

Definition at line 105 of file preciceC.cpp.

◆ precicec_getMeshDimensions()

int precicec_getMeshDimensions ( const char * meshName)

Returns the spatial dimensionality of the given mesh.

Parameters
[in]meshNamethe name of the associated mesh
Returns
the dimensions of the given mesh

Definition at line 75 of file preciceC.cpp.

◆ precicec_getMeshVertexIDsAndCoordinates()

void precicec_getMeshVertexIDsAndCoordinates ( const char * meshName,
const int size,
int * ids,
double * coordinates )

◆ precicec_getMeshVertexSize()

int precicec_getMeshVertexSize ( const char * meshName)

Returns the number of vertices of a mesh.

Parameters
[in]meshNamethe name of the mesh.
Returns
the amount of the vertices of the mesh

Definition at line 158 of file preciceC.cpp.

◆ precicec_getVersionInformation()

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 294 of file preciceC.cpp.

◆ precicec_initialize()

void precicec_initialize ( )

Initiates the coupling to the coupling supervisor and initializes coupling data.

Definition at line 56 of file preciceC.cpp.

◆ precicec_isCouplingOngoing()

int precicec_isCouplingOngoing ( )

Returns true (->1), if the coupled simulation is ongoing.

Definition at line 87 of file preciceC.cpp.

◆ precicec_isTimeWindowComplete()

int precicec_isTimeWindowComplete ( )

Returns true (->1), if the coupling time window is completed.

Definition at line 96 of file preciceC.cpp.

◆ precicec_readData()

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.

Parameters
[in]meshNamethe name of the mesh
[in]dataNamethe name of the data to be read.
[in]sizeNumber of indices, and number of values * dimensions.
[in]valueIndicesIndices (from setReadPosition()) of data values.
[in]relativeReadTimePoint in time where data is read relative to the beginning of the current time step.
[in]valuesValues of the data to be read.
See also
Participant::readData

Definition at line 258 of file preciceC.cpp.

◆ precicec_requiresGradientDataFor()

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.

Attention
This API function is experimental and may change in the future!

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)

Parameters
[in]meshNamethe name of mesh that hold the data.
[in]dataNamethe name of the data.
Returns
whether gradient is required

Definition at line 271 of file preciceC.cpp.

◆ precicec_requiresInitialData()

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().

Note
If initial data is configured, then this function needs to be called.
Precondition
initialize() has not yet been called

Definition at line 110 of file preciceC.cpp.

◆ precicec_requiresMeshConnectivityFor()

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.

Parameters
[in]meshNamethe name of the mesh
Returns
whether connectivity is required

Definition at line 128 of file preciceC.cpp.

◆ precicec_requiresReadingCheckpoint()

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().

Note
If implicit coupling is configured for this Participant, then this function needs to be called.
This function returns false before the first call to advance().
Precondition
initialize() has been called
See also
requiresWritingCheckpoint()

Definition at line 122 of file preciceC.cpp.

◆ precicec_requiresWritingCheckpoint()

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().

Note
If implicit coupling is configured for this Participant, then this function needs to be called.
Precondition
initialize() has been called
See also
requiresReadingCheckpoint()

Definition at line 116 of file preciceC.cpp.

◆ precicec_setMeshAccessRegion()

void precicec_setMeshAccessRegion ( const char * meshName,
const double * boundingBox )

◆ precicec_setMeshEdge()

void precicec_setMeshEdge ( const char * meshName,
int firstVertexID,
int secondVertexID )

Sets mesh edge from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the edge to
[in]firstVertexIDID of the first vertex of the edge
[in]secondVertexIDID of the second vertex of the edge
Precondition
ids were added to the mesh with the name meshName

Definition at line 165 of file preciceC.cpp.

◆ precicec_setMeshEdges()

void precicec_setMeshEdges ( const char * meshName,
int size,
const int * ids )

Sets multiple mesh edge from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the edges to
[in]sizethe amount of edges to set
[in]idsan array containing 2*size vertex IDs
Precondition
ids were added to the mesh with the name meshName

Definition at line 174 of file preciceC.cpp.

◆ precicec_setMeshQuad()

void precicec_setMeshQuad ( const char * meshName,
int firstVertexID,
int secondVertexID,
int thirdVertexID,
int fourthVertexID )

Sets surface mesh quadrangle from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the Quad to
[in]firstVertexIDID of the first vertex of the Quad
[in]secondVertexIDID of the second vertex of the Quad
[in]thirdVertexIDID of the third vertex of the Quad
[in]fourthVertexIDID of the fourth vertex of the Quad

Definition at line 204 of file preciceC.cpp.

◆ precicec_setMeshQuads()

void precicec_setMeshQuads ( const char * meshName,
int size,
const int * ids )

Sets multiple mesh quads from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the quad to
[in]sizethe amount of quads to set
[in]idsan array containing 4*size vertex IDs
Precondition
vertices in \ids were added to the mesh with the name meshName

Definition at line 215 of file preciceC.cpp.

◆ precicec_setMeshTetrahedra()

void precicec_setMeshTetrahedra ( const char * meshName,
int size,
const int * ids )

Sets multiple mesh tetrahedra from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the tetrahedra to
[in]sizethe amount of tetrahedra to set
[in]idsan array containing 4*size vertex IDs
Precondition
vertices in ids were added to the mesh with the name meshName

Definition at line 236 of file preciceC.cpp.

◆ precicec_setMeshTetrahedron()

void precicec_setMeshTetrahedron ( const char * meshName,
int firstVertexID,
int secondVertexID,
int thirdVertexID,
int fourthVertexID )

Sets mesh tetrahedron from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the Tetra to
[in]firstVertexIDID of the first vertex of the Tetra
[in]secondVertexIDID of the second vertex of the Tetra
[in]thirdVertexIDID of the third vertex of the Tetra
[in]fourthVertexIDID of the fourth vertex of the Tetra

Definition at line 225 of file preciceC.cpp.

◆ precicec_setMeshTriangle()

void precicec_setMeshTriangle ( const char * meshName,
int firstVertexID,
int secondVertexID,
int thirdVertexID )

Sets a triangle from vertex IDs. Creates missing edges.

Definition at line 184 of file preciceC.cpp.

◆ precicec_setMeshTriangles()

void precicec_setMeshTriangles ( const char * meshName,
int size,
const int * ids )

Sets multiple mesh triangles from vertex IDs.

Parameters
[in]meshNamethe name of the mesh to add the triangles to
[in]sizethe amount of triangles to set
[in]idsan array containing 3*size vertex IDs
Precondition
vertices in ids were added to the mesh with the name meshName

Definition at line 194 of file preciceC.cpp.

◆ precicec_setMeshVertex()

int precicec_setMeshVertex ( const char * meshName,
const double * coordinates )

Creates a mesh vertex.

Parameters
[in]meshNamethe name of the mesh to add the vertex to.
[in]coordinatesa pointer to the coordinates of the vertex.
Returns
the id of the created vertex

Definition at line 137 of file preciceC.cpp.

◆ precicec_setMeshVertices()

void precicec_setMeshVertices ( const char * meshName,
int size,
const double * coordinates,
int * ids )

Creates multiple mesh vertices.

Parameters
[in]meshNamethe name of the mesh to add the vertices to.
[in]sizeNumber of vertices to create
[in]coordinatesa 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]idsThe ids of the created vertices

Definition at line 146 of file preciceC.cpp.

◆ precicec_writeData()

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.

Parameters
[in]meshNamethe name of the mesh
[in]dataNamethe name of the data to be written.
[in]sizeNumber of indices, and number of values * dimensions.
[in]valuesValues of the data to be written.
See also
Participant::writeData

Definition at line 246 of file preciceC.cpp.

◆ precicec_writeGradientData()

void precicec_writeGradientData ( const char * meshName,
const char * dataName,
int size,
const int * valueIndices,
const double * gradients )

Writes vector gradient data to a mesh.

Attention
This API function is experimental and may change in the future!

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
Parameters
[in]meshNamethe name of mesh that hold the data.
[in]dataNamethe name of the data to write to.
[in]idsthe vertex ids of the vertices to write gradient data to.
[in]gradientsthe linearised gradient data to write to preCICE.
Precondition
Data has attribute hasGradient = true
every VertexID in vertices is a return value of setMeshVertex or setMeshVertices
gradients.size() == ids.size() * getMeshDimensions(meshName) * getDataDimensions(meshName, dataName)
See also
Participant::setMeshVertex()
Participant::setMeshVertices()
Participant::getMeshDimensions()
Participant::getDataDimensions()

Definition at line 281 of file preciceC.cpp.

Variable Documentation

◆ _log

precice::logging::Logger _log("precicec") ( "precicec" )
static

◆ errormsg

std::string errormsg = "preCICE has not been created properly. Be sure to call \"precicec_createParticipant\" or \"precicec_createParticipant_withCommunicator\" before any other call to preCICE."
static

Definition at line 25 of file preciceC.cpp.

◆ errormsgCreate

std::string errormsgCreate = "preCICE has been created already! Be sure to call either \"precicec_createParticipant\" or \"precicec_createParticipant_withCommunicator\" exactly once."
static

Definition at line 26 of file preciceC.cpp.

◆ impl

std::unique_ptr<precice::Participant> impl = nullptr
static

Definition at line 21 of file preciceC.cpp.