preCICE
Public Member Functions | Private Attributes | Friends | List of all members
precice::SolverInterface Class Reference

Main Application Programming Interface of preCICE. More...

#include <SolverInterface.hpp>

Collaboration diagram for precice::SolverInterface:
[legend]

Public Member Functions

 SolverInterface (const SolverInterface &copy)=delete
 Disable copy construction. More...
 
SolverInterfaceoperator= (const SolverInterface &assign)=delete
 Disable assignment construction. More...
 
Construction and Configuration
 SolverInterface (const std::string &participantName, const std::string &configurationFileName, int solverProcessIndex, int solverProcessSize)
 
 SolverInterface (const std::string &participantName, const std::string &configurationFileName, int solverProcessIndex, int solverProcessSize, void *communicator)
 
 ~SolverInterface ()
 
Steering Methods
double initialize ()
 Fully initializes preCICE. More...
 
void initializeData ()
 Initializes coupling data. More...
 
double advance (double computedTimestepLength)
 Advances preCICE after the solver has computed one timestep. More...
 
void finalize ()
 Finalizes preCICE. More...
 
Status Queries
int getDimensions () const
 Returns the number of spatial dimensions configured. More...
 
bool isCouplingOngoing () const
 Checks if the coupled simulation is still ongoing. More...
 
bool isReadDataAvailable () const
 Checks if new data to be read is available. More...
 
bool isWriteDataRequired (double computedTimestepLength) const
 Checks if new data has to be written before calling advance(). More...
 
bool isTimeWindowComplete () const
 Checks if the current coupling window is completed. More...
 
bool hasToEvaluateSurrogateModel () const
 Returns whether the solver has to evaluate the surrogate model representation. More...
 
bool hasToEvaluateFineModel () const
 Checks if the solver has to evaluate the fine model representation. More...
 
Action Methods
bool isActionRequired (const std::string &action) const
 Checks if the provided action is required. More...
 
void markActionFulfilled (const std::string &action)
 Indicates preCICE that a required action has been fulfilled by a solver. More...
 
Mesh Access

bool hasMesh (const std::string &meshName) const
 Checks if the mesh with given name is used by a solver. More...
 
int getMeshID (const std::string &meshName) const
 Returns the ID belonging to the mesh with given name. More...
 
std::set< int > getMeshIDs () const
 Returns a id-set of all used meshes by this participant. More...
 
bool isMeshConnectivityRequired (int meshID) const
 Checks if the given mesh requires connectivity. More...
 
int setMeshVertex (int meshID, const double *position)
 Creates a mesh vertex. More...
 
int getMeshVertexSize (int meshID) const
 Returns the number of vertices of a mesh. More...
 
void setMeshVertices (int meshID, int size, const double *positions, int *ids)
 Creates multiple mesh vertices. More...
 
void getMeshVertices (int meshID, int size, const int *ids, double *positions) const
 Get vertex positions for multiple vertex ids from a given mesh. More...
 
void getMeshVertexIDsFromPositions (int meshID, int size, const double *positions, int *ids) const
 Gets mesh vertex IDs from positions. More...
 
int setMeshEdge (int meshID, int firstVertexID, int secondVertexID)
 Sets mesh edge from vertex IDs, returns edge ID. More...
 
void setMeshTriangle (int meshID, int firstEdgeID, int secondEdgeID, int thirdEdgeID)
 Sets mesh triangle from edge IDs. More...
 
void setMeshTriangleWithEdges (int meshID, int firstVertexID, int secondVertexID, int thirdVertexID)
 Sets mesh triangle from vertex IDs. More...
 
void setMeshQuad (int meshID, int firstEdgeID, int secondEdgeID, int thirdEdgeID, int fourthEdgeID)
 Sets mesh Quad from edge IDs. More...
 
void setMeshQuadWithEdges (int meshID, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID)
 Sets surface mesh quadrangle from vertex IDs. More...
 
Data Access
bool hasData (const std::string &dataName, int meshID) const
 Checks if the data with given name is used by a solver and mesh. More...
 
int getDataID (const std::string &dataName, int meshID) const
 Returns the ID of the data associated with the given name and mesh. More...
 
void mapReadDataTo (int toMeshID)
 Computes and maps all read data mapped to the mesh with given ID. More...
 
void mapWriteDataFrom (int fromMeshID)
 Computes and maps all write data mapped from the mesh with given ID. More...
 
void writeBlockVectorData (int dataID, int size, const int *valueIndices, const double *values)
 Writes vector data given as block. More...
 
void writeVectorData (int dataID, int valueIndex, const double *value)
 Writes vector data to a vertex. More...
 
void writeBlockScalarData (int dataID, int size, const int *valueIndices, const double *values)
 Writes scalar data given as block. More...
 
void writeScalarData (int dataID, int valueIndex, double value)
 Writes scalar data to a vertex. More...
 
void readBlockVectorData (int dataID, int size, const int *valueIndices, double *values) const
 Reads vector data into a provided block. More...
 
void readVectorData (int dataID, int valueIndex, double *value) const
 Reads vector data form a vertex. More...
 
void readBlockScalarData (int dataID, int size, const int *valueIndices, double *values) const
 Reads scalar data as a block. More...
 
void readScalarData (int dataID, int valueIndex, double &value) const
 Reads scalar data of a vertex. More...
 
Experimental Data Access

These API functions are experimental and may change in future versions.

void setMeshAccessRegion (const int meshID, const double *boundingBox) const
 setMeshAccessRegion Define a region of interest on a received mesh (<use-mesh ... from="otherParticipant />") in order to receive only a certain mesh region. Have a look at the website under https://precice.org/couple-your-code-direct-access.html or navigate manually to the page Docs->Couple your code -> Advanced topics -> Accessing received meshes directly for a comprehensive documentation More...
 
void getMeshVerticesAndIDs (const int meshID, const int size, int *ids, double *coordinates) const
 getMeshVerticesAndIDs Iterates over the region of interest defined by bounding boxes and reads the corresponding coordinates omitting the mapping. More...
 

Private Attributes

std::unique_ptr< impl::SolverInterfaceImpl_impl
 Pointer to implementation of SolverInterface. More...
 

Friends

struct testing::WhiteboxAccessor
 

Detailed Description

Main Application Programming Interface of preCICE.

To adapt a solver to preCICE, follow the following main structure:

  1. Create an object of SolverInterface with SolverInterface()
  2. Initialize preCICE with SolverInterface::initialize()
  3. Advance to the next (time)step with SolverInterface::advance()
  4. Finalize preCICE with SolverInterface::finalize()

    Note
    We use solver, simulation code, and participant as synonyms. The preferred name in the documentation is participant.

Definition at line 38 of file SolverInterface.hpp.

Constructor & Destructor Documentation

◆ SolverInterface() [1/3]

precice::SolverInterface::SolverInterface ( const std::string &  participantName,
const std::string &  configurationFileName,
int  solverProcessIndex,
int  solverProcessSize 
)
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.

Definition at line 8 of file SolverInterface.cpp.

◆ SolverInterface() [2/3]

precice::SolverInterface::SolverInterface ( const std::string &  participantName,
const std::string &  configurationFileName,
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 17 of file SolverInterface.cpp.

Here is the call graph for this function:

◆ ~SolverInterface()

precice::SolverInterface::~SolverInterface ( )
default

◆ SolverInterface() [3/3]

precice::SolverInterface::SolverInterface ( const SolverInterface copy)
delete

Disable copy construction.

Member Function Documentation

◆ advance()

double precice::SolverInterface::advance ( double  computedTimestepLength)

Advances preCICE after the solver has computed one timestep.

Parameters
[in]computedTimestepLengthLength of timestep used by the solver.
Precondition
initialize() has been called successfully.
initializeData() has been called, if required by configuration.
The solver has computed one timestep.
The solver has written all coupling data.
isCouplngOngoing() returns true.
finalize() has not yet been called.
Postcondition
Coupling data values specified in the configuration are exchanged.
Coupling scheme state (computed time, computed timesteps, ...) is updated.
The coupling state is logged.
Configured data mapping schemes are applied.
[Second Participant] Configured acceleration schemes are applied.
Meshes with data are exported to files if configured.
Returns
Maximum length of next timestep to be computed by solver.

Definition at line 39 of file SolverInterface.cpp.

◆ finalize()

void precice::SolverInterface::finalize ( )

Finalizes preCICE.

Precondition
finalize() has not been called.
Postcondition
Communication channels are closed.
Meshes and data are deallocated
See also
isCouplingOngoing()

Definition at line 45 of file SolverInterface.cpp.

◆ getDataID()

int precice::SolverInterface::getDataID ( const std::string &  dataName,
int  meshID 
) const

Returns the ID of the data associated with the given name and mesh.

Parameters
[in]dataNamethe name of the data
[in]meshIDthe id of the associated mesh
Returns
the id of the corresponding data

Definition at line 116 of file SolverInterface.cpp.

◆ getDimensions()

int precice::SolverInterface::getDimensions ( ) const

Returns the number of spatial dimensions configured.

Returns
the configured dimension

Currently, two and three dimensional problems can be solved using preCICE. The dimension is specified in the XML configuration.

Definition at line 50 of file SolverInterface.cpp.

◆ getMeshID()

int precice::SolverInterface::getMeshID ( const std::string &  meshName) const

Returns the ID belonging to the mesh with given name.

Parameters
[in]meshNamethe name of the mesh
Returns
the id of the corresponding mesh

Definition at line 94 of file SolverInterface.cpp.

◆ getMeshIDs()

std::set< int > precice::SolverInterface::getMeshIDs ( ) const

Returns a id-set of all used meshes by this participant.

Deprecated:
Unclear use case and difficult to port to other languages. Prefer calling getMeshID for specific mesh names.
Returns
the set of ids.

Definition at line 100 of file SolverInterface.cpp.

◆ getMeshVertexIDsFromPositions()

void precice::SolverInterface::getMeshVertexIDsFromPositions ( int  meshID,
int  size,
const double *  positions,
int *  ids 
) const

Gets mesh vertex IDs from positions.

Parameters
[in]meshIDID of the mesh to retrieve positions from
[in]sizeNumber of vertices to lookup.
[in]positionsPositions to find ids for. The 2D-format is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)
[out]idsIDs corresponding to positions.
Precondition
count of available elements at positions matches the configured dimension * size
count of available elements at ids matches size
Note
prefer to reuse the IDs returned from calls to setMeshVertex() and setMeshVertices().

Definition at line 170 of file SolverInterface.cpp.

◆ getMeshVertexSize()

int precice::SolverInterface::getMeshVertexSize ( int  meshID) const

Returns the number of vertices of a mesh.

Parameters
[in]meshIDthe id of the mesh
Returns
the amount of the vertices of the mesh
Precondition
This function can be called on received meshes as well as provided meshes. However, you need to call this function after initialize(), if the meshID corresponds to a received mesh, since the relevant mesh data is exchanged during the initialize() call.

Definition at line 146 of file SolverInterface.cpp.

◆ getMeshVertices()

void precice::SolverInterface::getMeshVertices ( int  meshID,
int  size,
const int *  ids,
double *  positions 
) const

Get vertex positions for multiple vertex ids from a given mesh.

Parameters
[in]meshIDthe id of the mesh to read the vertices from.
[in]sizeNumber of vertices to lookup
[in]idsThe ids of the vertices to lookup
[out]positionsa pointer to memory to write the coordinates to The 2D-format is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)
Precondition
count of available elements at positions matches the configured dimension * size
count of available elements at ids matches size
See also
getDimensions()

Definition at line 161 of file SolverInterface.cpp.

◆ getMeshVerticesAndIDs()

void precice::SolverInterface::getMeshVerticesAndIDs ( const int  meshID,
const int  size,
int *  ids,
double *  coordinates 
) const

getMeshVerticesAndIDs Iterates over the region of interest defined by bounding boxes and reads the corresponding coordinates omitting the mapping.

Parameters
[in]meshIDcorresponding mesh ID
[in]sizereturn value of getMeshVertexSize()
[out]idsids corresponding to the coordinates
[out]coordinatesthe coordinates associated to the ids and corresponding data values (dim * size)
Precondition
IDs and coordinates need to have the correct size, which can be queried by getMeshVertexSize()
This function can be called on received meshes as well as provided meshes. However, you need to call this function after initialize(), if the meshID corresponds to a received mesh, since the relevant mesh data is exchanged during the initialize() call.

Definition at line 312 of file SolverInterface.cpp.

◆ hasData()

bool precice::SolverInterface::hasData ( const std::string &  dataName,
int  meshID 
) const

Checks if the data with given name is used by a solver and mesh.

Parameters
[in]dataNamethe name of the data
[in]meshIDthe id of the associated mesh
Returns
whether the mesh is used.

Definition at line 110 of file SolverInterface.cpp.

◆ hasMesh()

bool precice::SolverInterface::hasMesh ( const std::string &  meshName) const

Checks if the mesh with given name is used by a solver.

Parameters
[in]meshNamethe name of the mesh
Returns
whether the mesh is used.

Definition at line 88 of file SolverInterface.cpp.

◆ hasToEvaluateFineModel()

bool precice::SolverInterface::hasToEvaluateFineModel ( ) const

Checks if the solver has to evaluate the fine model representation.

Deprecated:
Was necessary for deprecated manifold mapping. Always returns true.
Returns
whether the fine model has to be evaluated.
Note
The solver may still have to evaluate the surrogate model representation.
See also
hasToEvaluateSurrogateModel()

Definition at line 127 of file SolverInterface.cpp.

◆ hasToEvaluateSurrogateModel()

bool precice::SolverInterface::hasToEvaluateSurrogateModel ( ) const

Returns whether the solver has to evaluate the surrogate model representation.

Deprecated:
Was necessary for deleted manifold mapping. Always returns false.
Returns
whether the surrogate model has to be evaluated.
Note
The solver may still have to evaluate the fine model representation.
See also
hasToEvaluateFineModel()

Definition at line 122 of file SolverInterface.cpp.

◆ initialize()

double precice::SolverInterface::initialize ( )

Fully initializes preCICE.

Precondition
initialize() has not yet bee called.
Postcondition
Parallel communication to the coupling partner/s is setup.
Meshes are exchanged between coupling partners and the parallel partitions are created.
[Serial Coupling Scheme] If the solver is not starting the simulation, coupling data is received from the coupling partner's first computation.
Returns
Maximum length of first timestep to be computed by the solver.

Definition at line 29 of file SolverInterface.cpp.

◆ initializeData()

void precice::SolverInterface::initializeData ( )

Initializes coupling data.

The starting values for coupling data are zero by default.

To provide custom values, first set the data using the Data Access methods and call this method to finally exchange the data.

Serial Coupling Scheme
Only the first participant has to call this method, the second participant receives the values on calling initialize().
Parallel Coupling Scheme
Values in both directions are exchanged. Both participants need to call initializeData().
Precondition
initialize() has been called successfully.
The action WriteInitialData is required
advance() has not yet been called.
finalize() has not yet been called.
Postcondition
Initial coupling data was exchanged.
See also
isActionRequired
precice::constants::actionWriteInitialData

Definition at line 34 of file SolverInterface.cpp.

◆ isActionRequired()

bool precice::SolverInterface::isActionRequired ( const std::string &  action) const

Checks if the provided action is required.

Parameters
[in]actionthe name of the action
Returns
whether the action is required

Some features of preCICE require a solver to perform specific actions, in order to be in valid state for a coupled simulation. A solver is made eligible to use those features, by querying for the required actions, performing them on demand, and calling markActionFulfilled() to signalize preCICE the correct behavior of the solver.

See also
markActionFulfilled()
cplscheme::constants

Definition at line 76 of file SolverInterface.cpp.

◆ isCouplingOngoing()

bool precice::SolverInterface::isCouplingOngoing ( ) const

Checks if the coupled simulation is still ongoing.

Returns
whether the coupling is ongoing.

A coupling is ongoing as long as

  • the maximum number of time windows has not been reached, and
  • the final time has not been reached.
Precondition
initialize() has been called successfully.
See also
advance()
Note
The user should call finalize() after this function returns false.

Definition at line 55 of file SolverInterface.cpp.

◆ isMeshConnectivityRequired()

bool precice::SolverInterface::isMeshConnectivityRequired ( int  meshID) const

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]meshIDthe id of the mesh
Returns
whether connectivity is required

Definition at line 105 of file SolverInterface.cpp.

◆ isReadDataAvailable()

bool precice::SolverInterface::isReadDataAvailable ( ) const

Checks if new data to be read is available.

Returns
whether new data is available to be read.

Data is classified to be new, if it has been received while calling initialize() and before calling advance(), or in the last call of advance(). This is always true, if a participant does not make use of subcycling, i.e. choosing smaller timesteps than the limits returned in intitialize() and advance().

Precondition
initialize() has been called successfully.
Note
It is allowed to read data even if this function returns false. This is not recommended due to performance reasons. Use this function to prevent unnecessary reads.

Definition at line 60 of file SolverInterface.cpp.

◆ isTimeWindowComplete()

bool precice::SolverInterface::isTimeWindowComplete ( ) const

Checks if the current coupling window is completed.

Returns
whether the current coupling window is complete.

The following reasons require several solver time steps per time window step:

  • A solver chooses to perform subcycling, i.e. using a smaller timestep than the time window..
  • An implicit coupling iteration is not yet converged.
Precondition
initialize() has been called successfully.

Definition at line 71 of file SolverInterface.cpp.

◆ isWriteDataRequired()

bool precice::SolverInterface::isWriteDataRequired ( double  computedTimestepLength) const

Checks if new data has to be written before calling advance().

Parameters
[in]computedTimestepLengthLength of timestep used by the solver.
Returns
whether new data has to be written.

This is always true, if a participant does not make use of subcycling, i.e. choosing smaller timesteps than the limits returned in intitialize() and advance().

Precondition
initialize() has been called successfully.
Note
It is allowed to write data even if this function returns false. This is not recommended due to performance reasons. Use this function to prevent unnecessary writes.

Definition at line 65 of file SolverInterface.cpp.

◆ mapReadDataTo()

void precice::SolverInterface::mapReadDataTo ( int  toMeshID)

Computes and maps all read data mapped to the mesh with given ID.

This is an explicit request to map read data to the Mesh associated with toMeshID. It also computes the mapping if necessary.

Precondition
A mapping to toMeshID was configured.

Definition at line 226 of file SolverInterface.cpp.

◆ mapWriteDataFrom()

void precice::SolverInterface::mapWriteDataFrom ( int  fromMeshID)

Computes and maps all write data mapped from the mesh with given ID.

This is an explicit request to map write data from the Mesh associated with fromMeshID. It also computes the mapping if necessary.

Precondition
A mapping from fromMeshID was configured.

Definition at line 232 of file SolverInterface.cpp.

◆ markActionFulfilled()

void precice::SolverInterface::markActionFulfilled ( const std::string &  action)

Indicates preCICE that a required action has been fulfilled by a solver.

Precondition
The solver fulfilled the specified action.
Parameters
[in]actionthe name of the action
See also
requireAction()
cplscheme::constants

Definition at line 82 of file SolverInterface.cpp.

◆ operator=()

SolverInterface& precice::SolverInterface::operator= ( const SolverInterface assign)
delete

Disable assignment construction.

◆ readBlockScalarData()

void precice::SolverInterface::readBlockScalarData ( int  dataID,
int  size,
const int *  valueIndices,
double *  values 
) const

Reads scalar data as a block.

This function reads values of specified vertices from a dataID. Values are provided as a block of continuous memory. valueIndices contains the indices of the vertices.

Parameters
[in]dataIDID to read from.
[in]sizeNumber n of vertices.
[in]valueIndicesIndices of the vertices.
[out]valuespointer to the read destination.
Precondition
count of available elements at values matches the given size
count of available elements at valueIndices matches the given size
initialize() has been called
Postcondition
values contains the read data.
See also
SolverInterface::setMeshVertex()

Definition at line 289 of file SolverInterface.cpp.

◆ readBlockVectorData()

void precice::SolverInterface::readBlockVectorData ( int  dataID,
int  size,
const int *  valueIndices,
double *  values 
) const

Reads vector data into a provided block.

This function reads values of specified vertices from a dataID. Values are read into a block of continuous memory. valueIndices contains the indices of the vertices.

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)

Parameters
[in]dataIDID to read from.
[in]sizeNumber n of vertices.
[in]valueIndicesIndices of the vertices.
[out]valuespointer to read destination.
Precondition
count of available elements at values matches the configured dimension * size
count of available elements at valueIndices matches the given size
initialize() has been called
Postcondition
values contain the read data as specified in the above format.
See also
SolverInterface::setMeshVertex()

Definition at line 272 of file SolverInterface.cpp.

◆ readScalarData()

void precice::SolverInterface::readScalarData ( int  dataID,
int  valueIndex,
double &  value 
) const

Reads scalar data of a vertex.

This function reads a value of a specified vertex from a dataID.

Parameters
[in]dataIDID to read from.
[in]valueIndexIndex of the vertex.
[out]valueread destination of the value.
Precondition
initialize() has been called
Postcondition
value contains the read data.
See also
SolverInterface::setMeshVertex()

Definition at line 298 of file SolverInterface.cpp.

◆ readVectorData()

void precice::SolverInterface::readVectorData ( int  dataID,
int  valueIndex,
double *  value 
) const

Reads vector data form a vertex.

This function reads a value of a specified vertex from a dataID. Values are provided as a block of continuous memory.

The 2D-format of value is (x, y) The 3D-format of value is (x, y, z)

Parameters
[in]dataIDID to read from.
[in]valueIndexIndex of the vertex.
[out]valuepointer to the vector value.
Precondition
count of available elements at value matches the configured dimension
initialize() has been called
Postcondition
value contains the read data as specified in the above format.
See also
SolverInterface::setMeshVertex()

Definition at line 281 of file SolverInterface.cpp.

◆ setMeshAccessRegion()

void precice::SolverInterface::setMeshAccessRegion ( const int  meshID,
const double *  boundingBox 
) const

setMeshAccessRegion Define a region of interest on a received mesh (<use-mesh ... from="otherParticipant />") in order to receive only a certain mesh region. Have a look at the website under https://precice.org/couple-your-code-direct-access.html or navigate manually to the page Docs->Couple your code -> Advanced topics -> Accessing received meshes directly for a comprehensive documentation

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

This function is required if you don't want to use the mapping schemes in preCICE, but rather want to use your own solver for data mapping. As opposed to the usual preCICE mapping, only a single mesh (from the other participant) is now involved in this situation since an 'own' mesh defined by the participant itself is not required any more. In order to re-partition the received mesh, the participant needs to define the mesh region it wants read data from and write data to. The mesh region is specified through an axis-aligned bounding box given by the lower and upper [min and max] bounding-box limits in each space dimension [x, y, z].

Note
Defining a bounding box for serial runs of the solver (not to be confused with serial coupling mode) is valid. However, a warning is raised in case vertices are filtered out completely on the receiving side, since the associated data values of the filtered vertices are filled with zero data.
This function can only be called once per participant and rank and trying to call it more than once results in an error.
If you combine the direct access with a mpping (say you want to read data from a defined mesh, as usual, but you want to directly access and write data on a received mesh without a mapping) you may not need this function at all since the region of interest is already defined through the defined mesh used for data reading. This is the case if you define any mapping involving the directly accessed mesh on the receiving participant. (In parallel, only the cases read-consistent and write-conservative are relevant, as usual).
The safety factor scaling (see safety-factor in the configuration file) is not applied to the defined access region and a specified safety will be ignored in case there is no additional mapping involved. However, in case a mapping is in addition to the direct access involved, you will receive (and gain access to) vertices inside the defined access region plus vertices inside the safety factor region resulting from the mapping. The default value of the safety factor is 0.5,i.e., the defined access region as computed through the involved provided mesh is by 50% enlarged.
Parameters
[in]meshIDID of the mesh you want to access through the bounding box
[in]boundingBoxAxis aligned bounding boxes which has in 3D the format [x_min, x_max, y_min, y_max, z_min, z_max]
Precondition
initialize() has not yet been called.

Definition at line 306 of file SolverInterface.cpp.

◆ setMeshEdge()

int precice::SolverInterface::setMeshEdge ( int  meshID,
int  firstVertexID,
int  secondVertexID 
)

Sets mesh edge from vertex IDs, returns edge ID.

Parameters
[in]meshIDID 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
Returns
the ID of the edge
Precondition
vertices with firstVertexID and secondVertexID were added to the mesh with the ID meshID

Definition at line 179 of file SolverInterface.cpp.

◆ setMeshQuad()

void precice::SolverInterface::setMeshQuad ( int  meshID,
int  firstEdgeID,
int  secondEdgeID,
int  thirdEdgeID,
int  fourthEdgeID 
)

Sets mesh Quad from edge IDs.

Parameters
[in]meshIDID of the mesh to add the Quad to
[in]firstEdgeIDID of the first edge of the Quad
[in]secondEdgeIDID of the second edge of the Quad
[in]thirdEdgeIDID of the third edge of the Quad
[in]fourthEdgeIDID of the forth edge of the Quad
Precondition
edges with firstEdgeID, secondEdgeID, thirdEdgeID and fourthEdgeID were added to the mesh with the ID meshID.

Definition at line 205 of file SolverInterface.cpp.

◆ setMeshQuadWithEdges()

void precice::SolverInterface::setMeshQuadWithEdges ( int  meshID,
int  firstVertexID,
int  secondVertexID,
int  thirdVertexID,
int  fourthVertexID 
)

Sets surface mesh quadrangle from vertex IDs.

Warning
This routine is supposed to be used, when no edge information is available per se. Edges are created on the fly within preCICE. This routine is significantly slower than the one using edge IDs, since it needs to check, whether an edge is created already or not.
Parameters
[in]meshIDID 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
Precondition
vertices with firstVertexID, secondVertexID, thirdVertexID, and fourthVertexID were added to the mesh with the ID meshID

Definition at line 215 of file SolverInterface.cpp.

◆ setMeshTriangle()

void precice::SolverInterface::setMeshTriangle ( int  meshID,
int  firstEdgeID,
int  secondEdgeID,
int  thirdEdgeID 
)

Sets mesh triangle from edge IDs.

Parameters
[in]meshIDID of the mesh to add the triangle to
[in]firstEdgeIDID of the first edge of the triangle
[in]secondEdgeIDID of the second edge of the triangle
[in]thirdEdgeIDID of the third edge of the triangle
Precondition
edges with firstEdgeID, secondEdgeID, and thirdEdgeID were added to the mesh with the ID meshID

Definition at line 187 of file SolverInterface.cpp.

◆ setMeshTriangleWithEdges()

void precice::SolverInterface::setMeshTriangleWithEdges ( int  meshID,
int  firstVertexID,
int  secondVertexID,
int  thirdVertexID 
)

Sets mesh triangle from vertex IDs.

Warning
This routine is supposed to be used, when no edge information is available per se. Edges are created on the fly within preCICE. This routine is significantly slower than the one using edge IDs, since it needs to check, whether an edge is created already or not.
Parameters
[in]meshIDID of the mesh to add the triangle to
[in]firstVertexIDID of the first vertex of the triangle
[in]secondVertexIDID of the second vertex of the triangle
[in]thirdVertexIDID of the third vertex of the triangle
Precondition
edges with firstVertexID, secondVertexID, and thirdVertexID were added to the mesh with the ID meshID

Definition at line 196 of file SolverInterface.cpp.

◆ setMeshVertex()

int precice::SolverInterface::setMeshVertex ( int  meshID,
const double *  position 
)

Creates a mesh vertex.

Parameters
[in]meshIDthe id of the mesh to add the vertex to.
[in]positiona pointer to the coordinates of the vertex.
Returns
the id of the created vertex
Precondition
initialize() has not yet been called
count of available elements at position matches the configured dimension
See also
getDimensions()

Definition at line 139 of file SolverInterface.cpp.

◆ setMeshVertices()

void precice::SolverInterface::setMeshVertices ( int  meshID,
int  size,
const double *  positions,
int *  ids 
)

Creates multiple mesh vertices.

Parameters
[in]meshIDthe id of the mesh to add the vertices to.
[in]sizeNumber of vertices to create
[in]positionsa 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
Precondition
initialize() has not yet been called
count of available elements at positions matches the configured dimension * size
count of available elements at ids matches size
See also
getDimensions()

Definition at line 152 of file SolverInterface.cpp.

◆ writeBlockScalarData()

void precice::SolverInterface::writeBlockScalarData ( int  dataID,
int  size,
const int *  valueIndices,
const double *  values 
)

Writes scalar data given as block.

This function writes values of specified vertices to a dataID. Values are provided as a block of continuous memory. valueIndices contains the indices of the vertices

Parameters
[in]dataIDID to write to.
[in]sizeNumber n of vertices.
[in]valueIndicesIndices of the vertices.
[in]valuespointer to the values.
Precondition
count of available elements at values matches the given size
count of available elements at valueIndices matches the given size
initialize() has been called
See also
SolverInterface::setMeshVertex()

Definition at line 255 of file SolverInterface.cpp.

◆ writeBlockVectorData()

void precice::SolverInterface::writeBlockVectorData ( int  dataID,
int  size,
const int *  valueIndices,
const double *  values 
)

Writes vector data given as block.

This function writes values of specified vertices to a dataID. Values are provided as a block of continuous memory. valueIndices contains the indices of the vertices

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)

Parameters
[in]dataIDID to write to.
[in]sizeNumber n of vertices.
[in]valueIndicesIndices of the vertices.
[in]valuespointer to the vector values.
Precondition
count of available elements at values matches the configured dimension * size
count of available elements at valueIndices matches the given size
initialize() has been called
See also
SolverInterface::setMeshVertex()

Definition at line 238 of file SolverInterface.cpp.

◆ writeScalarData()

void precice::SolverInterface::writeScalarData ( int  dataID,
int  valueIndex,
double  value 
)

Writes scalar data to a vertex.

This function writes a value of a specified vertex to a dataID.

Parameters
[in]dataIDID to write to.
[in]valueIndexIndex of the vertex.
[in]valuethe value to write.
Precondition
initialize() has been called
See also
SolverInterface::setMeshVertex()

Definition at line 264 of file SolverInterface.cpp.

◆ writeVectorData()

void precice::SolverInterface::writeVectorData ( int  dataID,
int  valueIndex,
const double *  value 
)

Writes vector data to a vertex.

This function writes a value of a specified vertex to a dataID. Values are provided as a block of continuous memory.

The 2D-format of value is (x, y) The 3D-format of value is (x, y, z)

Parameters
[in]dataIDID to write to.
[in]valueIndexIndex of the vertex.
[in]valuepointer to the vector value.
Precondition
count of available elements at value matches the configured dimension
initialize() has been called
See also
SolverInterface::setMeshVertex()

Definition at line 247 of file SolverInterface.cpp.

Friends And Related Function Documentation

◆ testing::WhiteboxAccessor

friend struct testing::WhiteboxAccessor
friend

Definition at line 896 of file SolverInterface.hpp.

Member Data Documentation

◆ _impl

std::unique_ptr<impl::SolverInterfaceImpl> precice::SolverInterface::_impl
private

Pointer to implementation of SolverInterface.

Definition at line 893 of file SolverInterface.hpp.


The documentation for this class was generated from the following files: