Main Application Programming Interface of preCICE. Include using #include <precice/precice.hpp>. More...

#include <Participant.hpp>

Public Member Functions
	Participant (const Participant &copy)=delete
	Disable copy construction.

Participant &	operator= (const Participant &assign)=delete
	Disable assignment construction.

Construction and Configuration
The API of preCICE is accessible via the Participant class. A constructed Participant directly corresponds to a participant in the configuration file. Constructors require defining the parallel context of the Participant by providing index and size of the current process, which are equivalent to rank and size in the MPI terminology. If preCICE is compiled with MPI, then there are multiple ways for it to be used: if a custom communicator is provided, preCICE uses it if MPI is already initialized, preCICE uses the MPI_COMM_WORLD otherwise, preCICE initializes MPI itself and uses the MPI_COMM_WORLD The MPI initialization is independent of which kind IntraCommunicator is configured.
	Participant (::precice::string_view participantName, ::precice::string_view configurationFileName, int solverProcessIndex, int solverProcessSize)
	Constructs a Participant for the given participant.

	Participant (::precice::string_view participantName, ::precice::string_view configurationFileName, int solverProcessIndex, int solverProcessSize, void *communicator)
	Constructs a Participant for the given participant and a custom MPI communicator.

	~Participant ()

Steering Methods
The steering methods are responsible for the coupling logic in preCICE. initialize() connects participants, handles partitioned meshes, initializes coupling data, and computes mappings. advance() steps the participant forwards in time, exchanging data, applying acceleration, and transparently handling subcycling as well as implicit coupling. finalize() closes down communication and optionally waits for other participants. This is implicitly called in ~Participant().
void	initialize ()
	Fully initializes preCICE and coupling data.

void	advance (double computedTimeStepSize)
	Advances preCICE after the solver has computed one time step.

void	finalize ()
	Finalizes preCICE.

Implicit Coupling
These functions are only required when you configure implicit coupling schemes. Implicitly-coupled solvers may iterate each time step until convergence is achieved. This generally results in an outer loop handling time steps and an inner loop handling iterations. The preCICE abstracts the inner loop away by managing the iteration logic in advance. If implicit coupling is configured, the adapter is required to either read or write checkpoints using the API requiresWritingCheckpoint() and requiresReadingCheckpoint(). The general flow looks as follows:
bool	requiresWritingCheckpoint ()

bool	requiresReadingCheckpoint ()

Status Queries
In addition to the steering methods, the participant still needs some information regarding the coupling state. Use isCouplingOngoing() to check if the simulation has reached its end. Control your time stepping using getMaxTimeStepSize(). To correctly size input and output buffers, you can access the dimensionality of meshes using getMeshDimensions() and data using getDataDimensions().
int	getMeshDimensions (::precice::string_view meshName) const
	Returns the spatial dimensionality of the given mesh.

int	getDataDimensions (::precice::string_view meshName, ::precice::string_view dataName) const
	Returns the spatial dimensionality of the given data on the given mesh.

bool	isCouplingOngoing () const
	Checks if the coupled simulation is still ongoing.

bool	isTimeWindowComplete () const
	Checks if the current coupling window is completed.

double	getMaxTimeStepSize () const
	Get the maximum allowed time step size of the current window.

Mesh Access
Connectivity is optional. Use requiresMeshConnectivityFor() to check if the current participant can make use of the connectivity. Only set the mesh connectivity that you require for your use-case and use the face/cell elements that your solver provides. preCICE removes all connectivity duplicates in initialize(). We recommend you to do the following depending on your case: 2D surface coupling: Use setMeshEdge() and setMeshEdges() to specify the coupling interface. 2D volume coupling: Use setMeshTriangle() and setMeshTriangles() to specify the coupling area. 3D surface coupling: Use setMeshTriangle() and setMeshTriangles() to specify the coupling interface. 3D volume coupling: Use setMeshTetrahedron() and setMeshTetrahedra() to specify the coupling volume. As an alternative to triangles, preCICE supports planar quads using setMeshQuad() and setMeshQuads(). These quads will be triangulated by preCICE, hence specifying triangles is generally preferred. Before using quads, we recommended to check if your solver provides a way to traverse triangulated faces.
bool	requiresMeshConnectivityFor (::precice::string_view meshName) const
	Checks if the given mesh requires connectivity.

VertexID	setMeshVertex (::precice::string_view meshName, ::precice::span< const double > position)
	Creates a mesh vertex.

int	getMeshVertexSize (::precice::string_view meshName) const
	Returns the number of vertices of a mesh.

void	setMeshVertices (::precice::string_view meshName, ::precice::span< const double > coordinates, ::precice::span< VertexID > ids)
	Creates multiple mesh vertices.

void	setMeshEdge (::precice::string_view meshName, VertexID first, VertexID second)
	Sets a mesh edge from vertex IDs.

void	setMeshEdges (::precice::string_view meshName, ::precice::span< const VertexID > ids)
	Sets multiple mesh edges from vertex IDs.

void	setMeshTriangle (::precice::string_view meshName, VertexID first, VertexID second, VertexID third)
	Sets mesh triangle from vertex IDs.

void	setMeshTriangles (::precice::string_view meshName, ::precice::span< const VertexID > ids)
	Sets multiple mesh triangles from vertex IDs.

void	setMeshQuad (::precice::string_view meshName, VertexID first, VertexID second, VertexID third, VertexID fourth)
	Sets a planar surface mesh quadrangle from vertex IDs.

void	setMeshQuads (::precice::string_view meshName, ::precice::span< const VertexID > ids)
	Sets multiple mesh quads from vertex IDs.

void	setMeshTetrahedron (::precice::string_view meshName, VertexID first, VertexID second, VertexID third, VertexID fourth)
	Set tetrahedron in 3D mesh from vertex ID.

void	setMeshTetrahedra (::precice::string_view meshName, ::precice::span< const VertexID > ids)
	Sets multiple mesh tetrahedra from vertex IDs.

Data Access
Data in preCICE is always associated to vertices on a defined mesh. Use getDataDimensions() to get the dimensionality of a data on a mesh. In each time step, you can access data on a mesh using writeData() and readData(). Calling advance() may use written data to create a new sample in time, maps data between meshes, and communicates between participants. If you perform multiple time steps per time window, then preCICE may decide to keep samples of written data to enable configured higher-order time interpolation in coupled participants. The time interpolation is implemented by the relative time in readData(). Written data is reset to 0 after each call to advance(). All data is initialized to 0 by default. If you configure preCICE to provide custom initial data, then participants need to provide this data before calling initialize(). After you defined the meshes, use requiresInitialData() to check if initial data is required. Then use writeData() to specify your initial data and continue to initialize().
bool	requiresInitialData ()

void	writeData (::precice::string_view meshName, ::precice::string_view dataName, ::precice::span< const VertexID > ids, ::precice::span< const double > values)
	Writes data to a mesh.

void	readData (::precice::string_view meshName, ::precice::string_view dataName, ::precice::span< const VertexID > ids, double relativeReadTime, ::precice::span< double > values) const
	Reads data values from a mesh. Values correspond to a given point in time relative to the beginning of the current timestep.

Direct Access
If you want or need to provide your own data mapping scheme, then you can use direct mesh access to directly modify data on a received mesh. This requires to specify a region of interest using setMeshAccessRegion() before calling initialize(). After initialize(), you can use getMeshVertexIDsAndCoordinates() to receive information on the received mesh. Use the coordinates to compute your own data mapping scheme, and use the vertex IDs to read data form and write data to the mesh.
void	setMeshAccessRegion (::precice::string_view meshName, ::precice::span< const double > boundingBox) const
	setMeshAccessRegion Define a region of interest on a received mesh (<receive-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

void	getMeshVertexIDsAndCoordinates (::precice::string_view meshName, ::precice::span< VertexID > ids, ::precice::span< double > coordinates) const
	getMeshVertexIDsAndCoordinates Iterates over the region of interest defined by bounding boxes and reads the corresponding coordinates omitting the mapping.

Experimental: Gradient Data
These API functions are experimental and may change in future versions.
bool	requiresGradientDataFor (::precice::string_view meshName, ::precice::string_view dataName) const
	Checks if the given data set requires gradient data. We check if the data object has been initialized with the gradient flag.

void	writeGradientData (::precice::string_view meshName, ::precice::string_view dataName, ::precice::span< const VertexID > ids, ::precice::span< const double > gradients)
	Writes vector gradient data to a mesh.

Private Attributes
std::unique_ptr< impl::ParticipantImpl >	_impl
	Pointer to implementation of Participant.

Friends
struct	testing::WhiteboxAccessor

Detailed Description

Main Application Programming Interface of preCICE. Include using #include <precice/precice.hpp>.

The flow of the API looks as follows:

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

Definition at line 168 of file Participant.hpp.

Constructor & Destructor Documentation

◆ Participant() [1/3]

precice::Participant::Participant	(	::precice::string_view	participantName,
		::precice::string_view	configurationFileName,
		int	solverProcessIndex,
		int	solverProcessSize )

Constructs a Participant 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 25 of file Participant.cpp.

◆ Participant() [2/3]

precice::Participant::Participant	(	::precice::string_view	participantName,
		::precice::string_view	configurationFileName,
		int	solverProcessIndex,
		int	solverProcessSize,
		void *	communicator )

Constructs a Participant 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 34 of file Participant.cpp.

◆ ~Participant()

precice::Participant::~Participant ( )

default

◆ Participant() [3/3]

precice::Participant::Participant ( const Participant & copy )

delete

Disable copy construction.

Member Function Documentation

◆ advance()

void precice::Participant::advance ( double computedTimeStepSize )

Advances preCICE after the solver has computed one time step.

There are two cases to distinguish at this point. If computedTimeStepSize == getMaxTimeStepSize(), then the solver has reached the end of a time window and proceeds the coupling. This call is a computationally expensive process as it involves among other tasks:

Sending and resetting coupling data written by solver to coupling partners.
Receiving coupling data read by solver.
Computing and applying data mappings.
Computing convergence measures in implicit coupling schemes.
Computing acceleration of coupling data.
Exchanging and computing information regarding the state of the coupled simulation.

If computedTimeStepSize < getMaxTimeStepSize(), then the solver hasn't reached the end of a time window and it is subcycling. Depending on the configuration, written data can be used by preCICE to generate additional samples allowing for time interpolation using readData(). This call is computationally inexpensive.

Parameters

[in] computedTimeStepSize Size of time step used by the solver.

Attention: All ranks of participants running in parallel must pass the same computedTimeStep to advance().

See also: getMaxTimeStepSize to get the maximum allowed value for computedTimeStepSize.

Precondition: initialize() has been called successfully.; The solver has computed one time step.; The solver has written all coupling data.; isCouplingOngoing() returns true.; finalize() has not yet been called.

Postcondition: Coupling data values specified in the configuration are exchanged.; Coupling scheme state (computed time, computed time steps, ...) 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.

Definition at line 51 of file Participant.cpp.

◆ finalize()

void precice::Participant::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 57 of file Participant.cpp.

◆ getDataDimensions()

int precice::Participant::getDataDimensions	(	::precice::string_view	meshName,
		::precice::string_view	dataName ) const

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]	meshName	the name of the associated mesh
[in]	dataName	the name of the data to get the dimensions for

Returns: the dimensions of the given Data

See also: getMeshDimensions

Definition at line 67 of file Participant.cpp.

◆ getMaxTimeStepSize()

double precice::Participant::getMaxTimeStepSize ( ) const

Get the maximum allowed time step size of the current window.

Returns: Maximum size of time step to be computed by solver.

Allows the user to query the maximum allowed time step size in the current window. This should be used to compute the actual time step that the solver uses.

Precondition: initialize() has been called successfully.

Definition at line 82 of file Participant.cpp.

◆ getMeshDimensions()

int precice::Participant::getMeshDimensions ( ::precice::string_view meshName ) const

Returns the spatial dimensionality of the given mesh.

Parameters

[in] meshName the name of the associated mesh

Returns: the dimensions of the given mesh

Definition at line 62 of file Participant.cpp.

◆ getMeshVertexIDsAndCoordinates()

void precice::Participant::getMeshVertexIDsAndCoordinates	(	::precice::string_view	meshName,
		::precice::span< VertexID >	ids,
		::precice::span< double >	coordinates ) const

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

Parameters

[in]	meshName	corresponding mesh name
[out]	ids	ids corresponding to the coordinates
[out]	coordinates	the coordinates associated to the `ids` and corresponding data values

Precondition: ids.size() == getMeshVertexSize(meshName); coordinates.size() == getMeshVertexSize(meshName) * getMeshDimensions(meshName); This function can be called on received meshes as well as provided meshes. However, you need to call this function after initialize(), if the meshName corresponds to a received mesh, since the relevant mesh data is exchanged during the initialize() call.

See also: getMeshVertexSize() to get the amount of vertices in the mesh; getMeshDimensions() to get the spacial dimensionality of the mesh

Definition at line 224 of file Participant.cpp.

◆ getMeshVertexSize()

int precice::Participant::getMeshVertexSize ( ::precice::string_view meshName ) const

Returns the number of vertices of a mesh.

Parameters

[in] meshName the name 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 meshName corresponds to a received mesh, since the relevant mesh data is exchanged during the initialize() call.

Definition at line 120 of file Participant.cpp.

◆ initialize()

void precice::Participant::initialize ( )

Fully initializes preCICE and coupling data.

Sets up a connection to the other participants of the coupled simulation.
Pre-processes defined meshes and handles partitions in parallel.
Receives first coupling data. The starting values for coupling data are zero by default.
Determines maximum allowed size of the first time step to be computed.

Precondition: initialize() has not yet been called.

Postcondition: Parallel communication to the coupling partner(s) is setup.; Meshes are exchanged between coupling partners and the parallel partitions are created.; Initial coupling data was exchanged.

See also: getMaxTimeStepSize(); requiresInitialData()

Definition at line 46 of file Participant.cpp.

◆ isCouplingOngoing()

bool precice::Participant::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 72 of file Participant.cpp.

◆ isTimeWindowComplete()

bool precice::Participant::isTimeWindowComplete ( ) const

Checks if the current coupling window is completed.

Returns: whether the current time window is complete.

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

A solver chooses to perform subcycling, i.e. using a smaller timestep than the time window.
An implicit coupling iteration is not yet converged.

Hence, a time window is complete if we reach the end of the time window and the implicit coupling has converged.

For implicit coupling this condition is equivalent with the requirement to write an iteration checkpoint. This is, however, not the case for explicit coupling.

Precondition: initialize() has been called successfully.

Definition at line 77 of file Participant.cpp.

◆ operator=()

Participant & precice::Participant::operator= ( const Participant & assign )

delete

Disable assignment construction.

◆ readData()

void precice::Participant::readData	(	::precice::string_view	meshName,
		::precice::string_view	dataName,
		::precice::span< const VertexID >	ids,
		double	relativeReadTime,
		::precice::span< double >	values ) const

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

This function reads values of specified vertices from data of a mesh. Values are read into a block of continuous memory defined by values in the order specified by vertices.

The 1D/Scalar-format of values is (d0, d1, ..., dn) The 2D-format of values is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format of values is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)

The data is read at relativeReadTime, which indicates the point in time measured from the beginning of the current time step. relativeReadTime = 0 corresponds to data at the beginning of the time step. Assuming that the user will call advance(dt) at the end of the time step, dt indicates the size of the current time step. Then relativeReadTime = dt corresponds to the data at the end of the time step.

Parameters

[in]	meshName	the name of mesh that hold the data.
[in]	dataName	the name of the data to read from.
[in]	ids	the vertex ids of the vertices to read data from.
[in]	relativeReadTime	Point in time where data is read relative to the beginning of the current time step.
[out]	values	the destination memory to read the data from.

Precondition: every VertexID in ids is a return value of setMeshVertex or setMeshVertices; values.size() == getDataDimensions(meshName, dataName) * ids.size()

Postcondition: values contain the read data as specified in the above format.

See also: Participant::setMeshVertex(); Participant::setMeshVertices(); Participant::getDataDimensions()

Definition at line 208 of file Participant.cpp.

◆ requiresGradientDataFor()

bool precice::Participant::requiresGradientDataFor	(	::precice::string_view	meshName,
		::precice::string_view	dataName ) 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]	meshName	the name of mesh that hold the data.
[in]	dataName	the name of the data.

Returns: whether gradient is required

Definition at line 107 of file Participant.cpp.

◆ requiresInitialData()

bool precice::Participant::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 87 of file Participant.cpp.

◆ requiresMeshConnectivityFor()

bool precice::Participant::requiresMeshConnectivityFor ( ::precice::string_view meshName ) 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] meshName the name of the mesh

Returns: whether connectivity is required

Definition at line 102 of file Participant.cpp.

◆ requiresReadingCheckpoint()

bool precice::Participant::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 92 of file Participant.cpp.

◆ requiresWritingCheckpoint()

bool precice::Participant::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 97 of file Participant.cpp.

◆ setMeshAccessRegion()

void precice::Participant::setMeshAccessRegion	(	::precice::string_view	meshName,
		::precice::span< const double >	boundingBox ) const

setMeshAccessRegion Define a region of interest on a received mesh (<receive-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

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]	meshName	name 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.; boundingBox.size() == 2 * getMeshDimensions(meshName)

Definition at line 218 of file Participant.cpp.

◆ setMeshEdge()

void precice::Participant::setMeshEdge	(	::precice::string_view	meshName,
		VertexID	first,
		VertexID	second )

Sets a mesh edge from vertex IDs.

Ignored if preCICE doesn't require connectivity for the mesh.

Note: The order of vertices does not matter.

Parameters

[in]	meshName	name of the mesh to add the edge to
[in]	first	ID of the first vertex of the edge
[in]	second	ID of the second vertex of the edge

Precondition: vertices with IDs first and second were added to the mesh with the name meshName

Definition at line 134 of file Participant.cpp.

◆ setMeshEdges()

void precice::Participant::setMeshEdges	(	::precice::string_view	meshName,
		::precice::span< const VertexID >	ids )

Sets multiple mesh edges from vertex IDs.

vertices contain pairs of vertex indices for each edge to define. The format follows: e1a, e1b, e2a, e2b, ... Ignored if preCICE doesn't require connectivity for the mesh.

Note: The order of vertices per edge does not matter.

Parameters

[in]	meshName	the name of the mesh to add the n edges to
[in]	ids	an array containing 2n vertex IDs for n edges

Precondition: vertices in ids were added to the mesh with the name meshName; ids.size() is multiple of 2

See also: requiresMeshConnectivityFor()

Definition at line 142 of file Participant.cpp.

◆ setMeshQuad()

void precice::Participant::setMeshQuad	(	::precice::string_view	meshName,
		VertexID	first,
		VertexID	second,
		VertexID	third,
		VertexID	fourth )

Sets a planar surface mesh quadrangle from vertex IDs.

The planar quad will be triangulated, maximizing area-to-circumference. Ignored if preCICE doesn't require connectivity for the mesh.

Warning: The order of vertices does not matter, however, only planar quads are allowed.

Parameters

[in]	meshName	name of the mesh to add the Quad to
[in]	first	ID of the first vertex of the Quad
[in]	second	ID of the second vertex of the Quad
[in]	third	ID of the third vertex of the Quad
[in]	fourth	ID of the fourth vertex of the Quad

Precondition: vertices with IDs first, second, third, and fourth were added to the mesh with the name meshName

See also: requiresMeshConnectivityFor()

Definition at line 165 of file Participant.cpp.

◆ setMeshQuads()

void precice::Participant::setMeshQuads	(	::precice::string_view	meshName,
		::precice::span< const VertexID >	ids )

Sets multiple mesh quads from vertex IDs.

vertices contain quadruples of vertex indices for each quad to define. The format follows: q1a, q1b, q1c, q1d, q2a, q2b, q2c, q2d, ...

Each planar quad will be triangulated, maximizing area-to-circumference. Ignored if preCICE doesn't require connectivity for the mesh.

Warning: The order of vertices per quad does not matter, however, only planar quads are allowed.

Parameters

[in]	meshName	name of the mesh to add the n quads to
[in]	ids	an array containing 4n vertex IDs for n quads

Precondition: vertices in ids were added to the mesh with the name meshName; ids.size() is multiple of 4

See also: requiresMeshConnectivityFor()

Definition at line 175 of file Participant.cpp.

◆ setMeshTetrahedra()

void precice::Participant::setMeshTetrahedra	(	::precice::string_view	meshName,
		::precice::span< const VertexID >	ids )

Sets multiple mesh tetrahedra from vertex IDs.

vertices contain quadruples of vertex indices for each tetrahedron to define. The format follows: t1a, t1b, t1c, t1d, t2a, t2b, t2c, t2d, ... Ignored if preCICE doesn't require connectivity for the mesh.

Note: The order of vertices per tetrahedron does not matter.

Parameters

[in]	meshName	name of the mesh to add the n tetrahedra to
[in]	ids	an array containing 4n vertex IDs for n tetrahedra

Precondition: vertices in ids were added to the mesh with the name meshName; ids.size() is multiple of 4

See also: requiresMeshConnectivityFor()

Definition at line 192 of file Participant.cpp.

◆ setMeshTetrahedron()

void precice::Participant::setMeshTetrahedron	(	::precice::string_view	meshName,
		VertexID	first,
		VertexID	second,
		VertexID	third,
		VertexID	fourth )

Set tetrahedron in 3D mesh from vertex ID.

Note: The order of vertices does not matter.

Parameters

[in]	meshName	name of the mesh to add the Tetrahedron to
[in]	first	ID of the first vertex of the Tetrahedron
[in]	second	ID of the second vertex of the Tetrahedron
[in]	third	ID of the third vertex of the Tetrahedron
[in]	fourth	ID of the fourth vertex of the Tetrahedron

Precondition: vertices with IDs first, second, third, and fourth were added to the mesh with the name meshName

See also: requiresMeshConnectivityFor()

Definition at line 182 of file Participant.cpp.

◆ setMeshTriangle()

void precice::Participant::setMeshTriangle	(	::precice::string_view	meshName,
		VertexID	first,
		VertexID	second,
		VertexID	third )

Sets mesh triangle from vertex IDs.

Note: The order of vertices does not matter.

Parameters

[in]	meshName	name of the mesh to add the triangle to
[in]	first	ID of the first vertex of the triangle
[in]	second	ID of the second vertex of the triangle
[in]	third	ID of the third vertex of the triangle

Precondition: vertices with IDs first, second, and third were added to the mesh with the name meshName

See also: requiresMeshConnectivityFor()

Definition at line 149 of file Participant.cpp.

◆ setMeshTriangles()

void precice::Participant::setMeshTriangles	(	::precice::string_view	meshName,
		::precice::span< const VertexID >	ids )

Sets multiple mesh triangles from vertex IDs.

vertices contain triples of vertex indices for each triangle to define. The format follows: t1a, t1b, t1c, t2a, t2b, t2c, ... Ignored if preCICE doesn't require connectivity for the mesh.

Note: The order of vertices per triangle does not matter.

Parameters

[in]	meshName	name of the mesh to add the n triangles to
[in]	ids	an array containing 3n vertex IDs for n triangles

Precondition: vertices in ids were added to the mesh with the name meshName; ids.size() is multiple of 3

See also: requiresMeshConnectivityFor()

Definition at line 158 of file Participant.cpp.

◆ setMeshVertex()

VertexID precice::Participant::setMeshVertex	(	::precice::string_view	meshName,
		::precice::span< const double >	position )

Creates a mesh vertex.

Parameters

[in]	meshName	the name of the mesh to add the vertex to.
[in]	position	the coordinates of the vertex.

Returns: the id of the created vertex

Precondition: initialize() has not yet been called; position.size() == getMeshDimensions(meshName)

See also: getMeshDimensions()

Definition at line 113 of file Participant.cpp.

◆ setMeshVertices()

void precice::Participant::setMeshVertices	(	::precice::string_view	meshName,
		::precice::span< const double >	coordinates,
		::precice::span< VertexID >	ids )

Creates multiple mesh vertices.

Parameters

[in]	meshName	the name of the mesh to add the vertices to.
[in]	coordinates	a span to the coordinates of the vertices The 2D-format is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)
[out]	ids	The ids of the created vertices

Precondition: initialize() has not yet been called; coordinates.size() == getMeshDimensions(meshName) * ids.size()

See also: getDimensions()

Definition at line 126 of file Participant.cpp.

◆ writeData()

void precice::Participant::writeData	(	::precice::string_view	meshName,
		::precice::string_view	dataName,
		::precice::span< const VertexID >	ids,
		::precice::span< const double >	values )

Writes data to a mesh.

This function writes values of specified vertices to data of a mesh. Values are provided as a block of continuous memory defined by values. The order of the provided data follows the order specified by vertices.

The 1D/Scalar-format of values is (d0, d1, ..., dn) The 2D-format of values is (d0x, d0y, d1x, d1y, ..., dnx, dny) The 3D-format of values is (d0x, d0y, d0z, d1x, d1y, d1z, ..., dnx, dny, dnz)

Parameters

[in]	meshName	the name of mesh that hold the data.
[in]	dataName	the name of the data to write to.
[in]	ids	the vertex ids of the vertices to write data to.
[in]	values	the values to write to preCICE.

Precondition: every VertexID in ids is a return value of setMeshVertex or setMeshVertices; values.size() == getDataDimensions(meshName, dataName) * ids.size()

See also: Participant::setMeshVertex(); Participant::setMeshVertices(); Participant::getDataDimensions()

Definition at line 199 of file Participant.cpp.

◆ writeGradientData()

void precice::Participant::writeGradientData	(	::precice::string_view	meshName,
		::precice::string_view	dataName,
		::precice::span< const VertexID >	ids,
		::precice::span< 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]	meshName	the name of mesh that hold the data.
[in]	dataName	the name of the data to write to.
[in]	ids	the vertex ids of the vertices to write gradient data to.
[in]	gradients	the linearised gradient data to write to preCICE.

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 231 of file Participant.cpp.

Friends And Related Symbol Documentation

◆ testing::WhiteboxAccessor

friend struct testing::WhiteboxAccessor

friend

Definition at line 1036 of file Participant.hpp.

Member Data Documentation

◆ _impl

std::unique_ptr<impl::ParticipantImpl> precice::Participant::_impl

private

Pointer to implementation of Participant.

Definition at line 1033 of file Participant.hpp.

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

src/precice/Participant.hpp
src/precice/Participant.cpp

Public Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Participant() [1/3]

◆ Participant() [2/3]

◆ ~Participant()

◆ Participant() [3/3]

Member Function Documentation

◆ advance()

◆ finalize()

◆ getDataDimensions()

◆ getMaxTimeStepSize()

◆ getMeshDimensions()

◆ getMeshVertexIDsAndCoordinates()

◆ getMeshVertexSize()

◆ initialize()

◆ isCouplingOngoing()

◆ isTimeWindowComplete()

◆ operator=()

◆ readData()

◆ requiresGradientDataFor()

◆ requiresInitialData()

◆ requiresMeshConnectivityFor()

◆ requiresReadingCheckpoint()

◆ requiresWritingCheckpoint()

◆ setMeshAccessRegion()

◆ setMeshEdge()

◆ setMeshEdges()

◆ setMeshQuad()

◆ setMeshQuads()

◆ setMeshTetrahedra()

◆ setMeshTetrahedron()

◆ setMeshTriangle()

◆ setMeshTriangles()

◆ setMeshVertex()

◆ setMeshVertices()

◆ writeData()

◆ writeGradientData()

Friends And Related Symbol Documentation

◆ testing::WhiteboxAccessor

Member Data Documentation

◆ _impl