precice::SolverInterface Class Reference

Main Application Programming Interface of preCICE. More...

#include <SolverInterface.hpp>

Collaboration diagram for precice::SolverInterface:

Public Member Functions
	SolverInterface (const SolverInterface &copy)=delete
	Disable copy construction. More...
SolverInterface &	operator= (const SolverInterface &assign)=delete
	Disable assignment construction. More...
Construction and Configuration
	SolverInterface (const std::string &participantName, const std::string &configurationFileName, int solverProcessIndex, int solverProcessSize)
	Constructs a SolverInterface for the given participant. More...
	SolverInterface (const std::string &participantName, const std::string &configurationFileName, int solverProcessIndex, int solverProcessSize, void *communicator)
	Constructs a SolverInterface for the given participant and a custom MPI communicator. More...
	~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...
void	setMeshTetrahedron (int meshID, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID)
	Set tetrahedron in 3D mesh from vertex ID. 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 values given as block from a mesh. Values correspond to the end of the current time window. More...
void	readVectorData (int dataID, int valueIndex, double *value) const
	Reads vector data at a vertex on a mesh. Values correspond to the end of the current time window. More...
void	readBlockScalarData (int dataID, int size, const int *valueIndices, double *values) const
	Reads scalar data values given as block from a mesh. Values correspond to the end of the current time window. More...
void	readScalarData (int dataID, int valueIndex, double &value) const
	Reads scalar data at a vertex on a mesh. Values correspond to the end of the current time window. More...
Experimental: Direct 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...
Experimental: Time Interpolation
These API functions are experimental and may change in future versions.
void	readBlockVectorData (int dataID, int size, const int *valueIndices, double relativeReadTime, double *values) const
	Reads vector data values given as block from a mesh. Values correspond to a given point in time relative to the beginning of the current timestep. More...
void	readVectorData (int dataID, int valueIndex, double relativeReadTime, double *value) const
	Reads vector data at a vertex on a mesh. Values correspond to a given point in time relative to the beginning of the current timestep. More...
void	readBlockScalarData (int dataID, int size, const int *valueIndices, double relativeReadTime, double *values) const
	Reads scalar data values given as block from a mesh. Values correspond to a given point in time relative to the beginning of the current timestep. More...
void	readScalarData (int dataID, int valueIndex, double relativeReadTime, double &value) const
	Reads scalar data at a vertex on a mesh. Values correspond to a given point in time relative to the beginning of the current timestep. More...
Experimental: Gradient Data
These API functions are experimental and may change in future versions.
bool	isGradientDataRequired (int dataID) const
	Checks if the given data set requires gradient data. We check if the data object has been initialized with the gradient flag. More...
void	writeBlockVectorGradientData (int dataID, int size, const int *valueIndices, const double *gradientValues)
	Writes vector gradient data given as block. More...
void	writeScalarGradientData (int dataID, int valueIndex, const double *gradientValues)
	Writes scalar gradient data to a vertex. More...
void	writeVectorGradientData (int dataID, int valueIndex, const double *gradientValues)
	Writes vector gradient data to a vertex. More...
void	writeBlockScalarGradientData (int dataID, int size, const int *valueIndices, const double *gradientValues)
	Writes scalar gradient data given as block. 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 39 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
	)

Constructs a SolverInterface for the given participant.

Parameters

[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.

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
	)

Constructs a SolverInterface for the given participant and a custom MPI communicator.

Parameters

[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 17 of file SolverInterface.cpp.

~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.

• Sends and resets coupling data written by solver to coupling partners.
• Receives coupling data read by solver.
• Computes and applies data mappings.
• Computes acceleration of coupling data.
• Exchanges and computes information regarding the state of the coupled simulation.

Parameters

[in]

computedTimestepLength

Length 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.

If initialize() has been called:

• Synchronizes with remote participants
• handles final exports
• cleans up general state

Always:

• flushes and finalizes Events
• finalizes managed PETSc
• finalizes managed MPI

Precondition

finalize() has not been called.

Postcondition

Communication channels are closed.

Meshes and data are deallocated

Finalized managed PETSc

Finalized managed MPI

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]	dataName	the name of the data
[in]	meshID	the id of the associated mesh

Returns

the id of the corresponding data

Definition at line 121 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.

The existing names are determined from the configuration.

Parameters

[in]

meshName

the 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]	meshID	ID of the mesh to retrieve positions from
[in]	size	Number of vertices to lookup.
[in]	positions	Positions 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]	ids	IDs 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 175 of file SolverInterface.cpp.

Here is the call graph for this function:

getMeshVertexSize()

int precice::SolverInterface::getMeshVertexSize

(

int

meshID

)

const

Returns the number of vertices of a mesh.

Parameters

[in]

meshID

the 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 151 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]	meshID	the id of the mesh to read the vertices from.
[in]	size	Number of vertices to lookup
[in]	ids	The ids of the vertices to lookup
[out]	positions	a 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 166 of file SolverInterface.cpp.

Here is the call graph for this function:

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.

Attention

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

Parameters

[in]	meshID	corresponding mesh ID
[in]	size	return value of getMeshVertexSize()
[out]	ids	ids corresponding to the coordinates
[out]	coordinates	the 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 401 of file SolverInterface.cpp.

Here is the call graph for this function:

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]	dataName	the name of the data
[in]	meshID	the id of the associated mesh

Returns

whether the mesh is used.

Definition at line 115 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]

meshName

the 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 132 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 127 of file SolverInterface.cpp.

initialize()

double precice::SolverInterface::initialize

(

)

Fully initializes preCICE.

• Sets up a connection to the other participants of the coupled simulation.
• Creates all meshes, solver meshes need to be submitted before.
• Receives first coupling data, when the solver is not starting the coupled simulation.
• Determines length of the first timestep to be computed.

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]

action

the 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.

isGradientDataRequired()

bool precice::SolverInterface::isGradientDataRequired

(

int

dataID

)

const

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]

dataID

the id of the data

Returns

whether gradient is required

Definition at line 110 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]

meshID

the 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.

Deprecated:

Removed to simplify extension to waveform relaxation.

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

Deprecated:

Removed to simplify extension to waveform relaxation.

Parameters

[in]

computedTimestepLength

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

Deprecated:

Unclear use case and difficult to maintain.

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 242 of file SolverInterface.cpp.

mapWriteDataFrom()

void precice::SolverInterface::mapWriteDataFrom

(

int

fromMeshID

)

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

Deprecated:

Unclear use case and difficult to maintain.

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 248 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]

action

the 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() [1/2]

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

Reads scalar data values given as block from a mesh. Values correspond to the end of the current time window.

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]	dataID	ID to read from.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[out]	values	Pointer 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 359 of file SolverInterface.cpp.

Here is the call graph for this function:

readBlockScalarData() [2/2]

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

Reads scalar data values given as block from a mesh. Values correspond to a given point in time relative to the beginning of the current timestep.

Attention

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

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.

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 length of the current time step. Then relativeReadTime = dt corresponds to the data at the end of the time step.

Parameters

[in]	dataID	ID to read from.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[in]	relativeReadTime	Point in time where data is read relative to the beginning of the current time step.
[out]	values	Pointer 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 368 of file SolverInterface.cpp.

Here is the call graph for this function:

readBlockVectorData() [1/2]

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

Reads vector data values given as block from a mesh. Values correspond to the end of the current time window.

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]	dataID	ID to read from.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[out]	values	Pointer 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 322 of file SolverInterface.cpp.

Here is the call graph for this function:

readBlockVectorData() [2/2]

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

Reads vector data values given as block from a mesh. Values correspond to a given point in time relative to the beginning of the current timestep.

Attention

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

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)

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 length of the current time step. Then relativeReadTime = dt corresponds to the data at the end of the time step.

Parameters

[in]	dataID	ID to read from.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[in]	relativeReadTime	Point in time where data is read relative to the beginning of the current time step.
[out]	values	Pointer 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 331 of file SolverInterface.cpp.

Here is the call graph for this function:

readScalarData() [1/2]

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

Reads scalar data at a vertex on a mesh. Values correspond to the end of the current time window.

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

Parameters

[in]	dataID	ID to read from.
[in]	valueIndex	Index of the vertex.
[out]	value	Read destination of the value.

Precondition

initialize() has been called

Postcondition

value contains the read data.

See also

SolverInterface::setMeshVertex()

Definition at line 378 of file SolverInterface.cpp.

readScalarData() [2/2]

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

Reads scalar data at a vertex on a mesh. Values correspond to a given point in time relative to the beginning of the current timestep.

Attention

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

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

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 length of the current time step. Then relativeReadTime = dt corresponds to the data at the end of the time step.

Parameters

[in]	dataID	ID to read from.
[in]	valueIndex	Index of the vertex.
[in]	relativeReadTime	Point in time where data is read relative to the beginning of the current time step
[out]	value	Read destination of the value.

Precondition

initialize() has been called

Postcondition

value contains the read data.

See also

SolverInterface::setMeshVertex()

Definition at line 386 of file SolverInterface.cpp.

readVectorData() [1/2]

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

Reads vector data at a vertex on a mesh. Values correspond to the end of the current time window.

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]	dataID	ID to read from.
[in]	valueIndex	Index of the vertex.
[out]	value	Pointer 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 341 of file SolverInterface.cpp.

readVectorData() [2/2]

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

Reads vector data at a vertex on a mesh. Values correspond to a given point in time relative to the beginning of the current timestep.

Attention

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

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)

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 length of the current time step. Then relativeReadTime = dt corresponds to the data at the end of the time step.

Parameters

[in]	dataID	ID to read from.
[in]	valueIndex	Index of the vertex.
[in]	relativeReadTime	Point in time where data is read relative to the beginning of the current time step.
[out]	value	Pointer 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 349 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]	meshID	ID of the mesh you want to access through the bounding box
[in]	boundingBox	Axis 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 395 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]	meshID	ID 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

Returns

the ID of the edge

Precondition

vertices with firstVertexID and secondVertexID were added to the mesh with the ID meshID

Definition at line 184 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]	meshID	ID of the mesh to add the Quad to
[in]	firstEdgeID	ID of the first edge of the Quad
[in]	secondEdgeID	ID of the second edge of the Quad
[in]	thirdEdgeID	ID of the third edge of the Quad
[in]	fourthEdgeID	ID 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 210 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]	meshID	ID 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

Precondition

vertices with firstVertexID, secondVertexID, thirdVertexID, and fourthVertexID were added to the mesh with the ID meshID

Definition at line 220 of file SolverInterface.cpp.

setMeshTetrahedron()

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

Set tetrahedron in 3D mesh from vertex ID.

Parameters

[in]	meshID	ID of the mesh to add the Tetrahedron to
[in]	firstVertexID	ID of the first vertex of the Tetrahedron
[in]	secondVertexID	ID of the second vertex of the Tetrahedron
[in]	thirdVertexID	ID of the third vertex of the Tetrahedron
[in]	fourthVertexID	ID of the fourth vertex of the Tetrahedron

Precondition

vertices with firstVertexID, secondVertexID, thirdVertexID, and fourthVertexID were added to the mesh with the ID meshID

Definition at line 231 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]	meshID	ID of the mesh to add the triangle to
[in]	firstEdgeID	ID of the first edge of the triangle
[in]	secondEdgeID	ID of the second edge of the triangle
[in]	thirdEdgeID	ID 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 192 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]	meshID	ID of the mesh to add the triangle to
[in]	firstVertexID	ID of the first vertex of the triangle
[in]	secondVertexID	ID of the second vertex of the triangle
[in]	thirdVertexID	ID 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 201 of file SolverInterface.cpp.

setMeshVertex()

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

Creates a mesh vertex.

Parameters

[in]	meshID	the id of the mesh to add the vertex to.
[in]	position	a 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 144 of file SolverInterface.cpp.

setMeshVertices()

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

Creates multiple mesh vertices.

Parameters

[in]	meshID	the id of the mesh to add the vertices to.
[in]	size	Number of vertices to create
[in]	positions	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

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 157 of file SolverInterface.cpp.

Here is the call graph for this function:

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]	dataID	ID to write to.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[in]	values	Pointer 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 288 of file SolverInterface.cpp.

Here is the call graph for this function:

writeBlockScalarGradientData()

void precice::SolverInterface::writeBlockScalarGradientData	(	int	dataID,
		int	size,
		const int *	valueIndices,
		const double *	gradientValues
	)

Writes scalar gradient data given as block.

Attention

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

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 gradients need to be provided in the following format:

The 2D-format of gradientValues is (v0_dx, v0_dy, v1_dx, v1_dy, ... , vn_dx, vn_dy, vn_dz) corresponding to the scalar data v0, v1, ... , vn differentiated in spatial directions x and y.

The 3D-format of gradientValues is (v0_dx, v0_dy, v0_dz, v1_dx, v1_dy, v1_dz, ... , vn_dx, vn_dy, vn_dz) corresponding to the scalar data v0, v1, ... , vn differentiated in spatial directions x, y and z.

Parameters

[in]	dataID	ID to write to.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[in]	gradientValues	Pointer to the gradient 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

Data with dataID has attribute hasGradient = true

See also

SolverInterface::setMeshVertex()

Definition at line 297 of file SolverInterface.cpp.

Here is the call graph for this function:

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]	dataID	ID to write to.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[in]	values	Pointer 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 254 of file SolverInterface.cpp.

Here is the call graph for this function:

writeBlockVectorGradientData()

void precice::SolverInterface::writeBlockVectorGradientData	(	int	dataID,
		int	size,
		const int *	valueIndices,
		const double *	gradientValues
	)

Writes vector gradient data given as block.

Attention

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

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 values are passed in the same format applied in writeVectorGradientData() for each data vertex:

The 2D-format of gradientValues is ( v0x_dx, v0y_dx, v0x_dy, v0y_dy, v1x_dx, v1y_dx, v1x_dy, v1y_dy, ... , vnx_dx, vny_dx, vnx_dy, vny_dy)

corresponding to the vector data v0 = (v0x, v0y) , v1 = (v1x, v1y), ... , vn = (vnx, vny) differentiated in spatial directions x and y.

The 3D-format of gradientValues is ( v0x_dx, v0y_dx, v0z_dx, v0x_dy, v0y_dy, v0z_dy, v0x_dz, v0y_dz, v0z_dz, v1x_dx, v1y_dx, v1z_dx, v1x_dy, v1y_dy, v1z_dy, v1x_dz, v1y_dz, v1z_dz, ... , vnx_dx, vny_dx, vnz_dx, vnx_dy, vny_dy, vnz_dy, vnx_dz, vny_dz, vnz_dz)

corresponding to the vector data v0 = (v0x, v0y, v0z) , v1 = (v1x, v1y, v1z), ... , vn = (vnx, vny, vnz) differentiated in spatial directions x,y and z.

Parameters

[in]	dataID	ID to write to.
[in]	size	Number n of vertices.
[in]	valueIndices	Indices of the vertices.
[in]	gradientValues	Pointer to the gradient values.

Precondition

count of available elements at gradient values matches the configured dimension * size

count of available elements at valueIndices matches the given size

initialize() has been called

Data with dataID has attribute hasGradient = true

See also

SolverInterface::setMeshVertex()

Definition at line 263 of file SolverInterface.cpp.

Here is the call graph for this function:

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]	dataID	ID to write to.
[in]	valueIndex	Index of the vertex.
[in]	value	The value to write.

Precondition

initialize() has been called

See also

SolverInterface::setMeshVertex()

Definition at line 306 of file SolverInterface.cpp.

writeScalarGradientData()

void precice::SolverInterface::writeScalarGradientData	(	int	dataID,
		int	valueIndex,
		const double *	gradientValues
	)

Writes scalar gradient data to a vertex.

Attention

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

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

Parameters

[in]	dataID	ID to write to.
[in]	valueIndex	Index of the vertex.
[in]	gradientValues	Gradient values differentiated in the spacial direction (dx, dy) for 2D space, (dx, dy, dz) for 3D space

Precondition

count of available elements at value matches the configured dimension

initialize() has been called

vertex with dataID exists and contains data

Data with dataID has attribute hasGradient = true

See also

SolverInterface::setMeshVertex()

Definition at line 314 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]	dataID	ID to write to.
[in]	valueIndex	Index of the vertex.
[in]	value	Pointer 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 272 of file SolverInterface.cpp.

writeVectorGradientData()

void precice::SolverInterface::writeVectorGradientData	(	int	dataID,
		int	valueIndex,
		const double *	gradientValues
	)

Writes vector gradient data to a vertex.

Attention

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

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

The gradients need to be provided in the following format:

The 2D-format of gradientValues is (vx_dx, vy_dx, vx_dy, vy_dy) matrix corresponding to the data block v = (vx, vy) differentiated respectively in x-direction dx and y-direction dy

The 3D-format of gradientValues is (vx_dx, vy_dx, vz_dx, vx_dy, vy_dy, vz_dy, vx_dz, vy_dz, vz_dz) matrix corresponding to the data block v = (vx, vy, vz) differentiated respectively in spatial directions x-direction dx and y-direction dy and z-direction dz

Parameters

[in]	dataID	ID to write to.
[in]	valueIndex	Index of the vertex.
[in]	gradientValue	pointer to the gradient value.

Precondition

count of available elements at value matches the configured dimension

initialize() has been called

vertex with dataID exists and contains data

Data with dataID has attribute hasGradient = true

See also

SolverInterface::setMeshVertex()

Definition at line 280 of file SolverInterface.cpp.

Friends And Related Function Documentation

testing::WhiteboxAccessor

friend struct testing::WhiteboxAccessor

friend

Definition at line 1262 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 1259 of file SolverInterface.hpp.

---

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

• src/precice/SolverInterface.hpp
• src/precice/SolverInterface.cpp