C language bindings to main Application Programming Interface of preCICE. More...

#include <precice/Version.h>
#include <precice/export.h>

Include dependency graph for preciceC.h:

This graph shows which files directly or indirectly include this file:

Functions
PRECICE_API const char *	precicec_getVersionInformation ()
	Returns information on the version of preCICE.

Construction and Configuration
PRECICE_API void	precicec_createParticipant_withCommunicator (const char participantName, const char configFileName, int solverProcessIndex, int solverProcessSize, void *communicator)

PRECICE_API void	precicec_createParticipant (const char participantName, const char configFileName, int solverProcessIndex, int solverProcessSize)
	Creates the coupling interface and configures it.

Steering Methods
PRECICE_API void	precicec_initialize ()
	Initiates the coupling to the coupling supervisor and initializes coupling data.

PRECICE_API void	precicec_advance (double computedTimeStepSize)
	Exchanges data between solver and coupling supervisor.

PRECICE_API void	precicec_finalize ()
	Finalizes the coupling to the coupling supervisor.

Implicit coupling
PRECICE_API int	precicec_requiresWritingCheckpoint ()

PRECICE_API int	precicec_requiresReadingCheckpoint ()

Status Queries
PRECICE_API int	precicec_getMeshDimensions (const char *meshName)
	Returns the spatial dimensionality of the given mesh.

PRECICE_API int	precicec_getDataDimensions (const char meshName, const char dataName)
	Returns the spatial dimensionality of the given data on the given mesh.

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

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

PRECICE_API double	precicec_getMaxTimeStepSize ()
	Returns maximum allowed time step size.

Mesh Access

PRECICE_API int	precicec_requiresMeshConnectivityFor (const char *meshName)
	Checks if the given mesh requires connectivity.

PRECICE_API int	precicec_setMeshVertex (const char meshName, const double coordinates)
	Creates a mesh vertex.

PRECICE_API int	precicec_getMeshVertexSize (const char *meshName)
	Returns the number of vertices of a mesh.

PRECICE_API void	precicec_setMeshVertices (const char meshName, int size, const double coordinates, int *ids)
	Creates multiple mesh vertices.

PRECICE_API void	precicec_setMeshEdge (const char *meshName, int firstVertexID, int secondVertexID)
	Sets mesh edge from vertex IDs.

PRECICE_API void	precicec_setMeshEdges (const char meshName, int size, const int ids)
	Sets multiple mesh edge from vertex IDs.

PRECICE_API void	precicec_setMeshTriangle (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID)
	Sets a triangle from vertex IDs. Creates missing edges.

PRECICE_API void	precicec_setMeshTriangles (const char meshName, int size, const int ids)
	Sets multiple mesh triangles from vertex IDs.

PRECICE_API void	precicec_setMeshQuad (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID)
	Sets surface mesh quadrangle from vertex IDs.

PRECICE_API void	precicec_setMeshQuads (const char meshName, int size, const int ids)
	Sets multiple mesh quads from vertex IDs.

PRECICE_API void	precicec_setMeshTetrahedron (const char *meshName, int firstVertexID, int secondVertexID, int thirdVertexID, int fourthVertexID)
	Sets mesh tetrahedron from vertex IDs.

PRECICE_API void	precicec_setMeshTetrahedra (const char meshName, int size, const int ids)
	Sets multiple mesh tetrahedra from vertex IDs.

Data Access
PRECICE_API int	precicec_requiresInitialData ()

PRECICE_API void	precicec_writeData (const char meshName, const char dataName, int size, const int valueIndices, const double values)
	Writes vector data values given as block.

PRECICE_API void	precicec_readData (const char meshName, const char dataName, int size, const int valueIndices, double relativeReadTime, double values)
	Reads vector data values given as block.

Direct mesh access
PRECICE_API void	precicec_setMeshAccessRegion (const char meshName, const double boundingBox)
	See precice::Participant::setMeshAccessRegion().

PRECICE_API void	precicec_getMeshVertexIDsAndCoordinates (const char meshName, const int size, int ids, double *coordinates)
	See precice::Participant::getMeshVertexIDsAndCoordinates().

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

PRECICE_API void	precicec_writeGradientData (const char meshName, const char dataName, int size, const int valueIndices, const double gradients)
	Writes vector gradient data to a mesh.

Detailed Description

C language bindings to main Application Programming Interface of preCICE.

The C bindings are thin wrappers around the C++ API.

Refer to precice::Participant for detailed documentation.

Definition in file preciceC.h.

Function Documentation

◆ precicec_advance()

PRECICE_API void precicec_advance ( double computedTimeStepSize )

Exchanges data between solver and coupling supervisor.

Parameters

[in] computedTimeStepSize Size of time step computed by solver.

Definition at line 62 of file preciceC.cpp.

◆ precicec_createParticipant()

PRECICE_API void precicec_createParticipant	(	const char *	participantName,
		const char *	configFileName,
		int	solverProcessIndex,
		int	solverProcessSize )

Creates the coupling interface and configures it.

Has to be called before any other method of this interface.

Parameters

[in]	participantName	Name of the participant accessing the interface. Has to match one of the names specified in the configuration xml file.
[in]	configFileName	(Path and) name of the xml configuration file containing the precice configuration.
[in]	solverProcessIndex	If the solver code runs with several processes, each process using preCICE has to specify its index, which has to start from 0 and end with solverProcessSize - 1.
[in]	solverProcessSize	The number of solver processes using preCICE.

Definition at line 43 of file preciceC.cpp.

◆ precicec_createParticipant_withCommunicator()

PRECICE_API void precicec_createParticipant_withCommunicator	(	const char *	participantName,
		const char *	configFileName,
		int	solverProcessIndex,
		int	solverProcessSize,
		void *	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 28 of file preciceC.cpp.

◆ precicec_finalize()

PRECICE_API void precicec_finalize ( )

Finalizes the coupling to the coupling supervisor.

Definition at line 68 of file preciceC.cpp.

◆ precicec_getDataDimensions()

PRECICE_API int precicec_getDataDimensions	(	const char *	meshName,
		const char *	dataName )

Returns the spatial dimensionality of the given data on the given mesh.

Note that vectorial data dimensionality directly depends on the 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 81 of file preciceC.cpp.

◆ precicec_getMaxTimeStepSize()

PRECICE_API double precicec_getMaxTimeStepSize ( )

Returns maximum allowed time step size.

Definition at line 105 of file preciceC.cpp.

◆ precicec_getMeshDimensions()

PRECICE_API int precicec_getMeshDimensions ( const char * meshName )

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

◆ precicec_getMeshVertexIDsAndCoordinates()

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

See precice::Participant::getMeshVertexIDsAndCoordinates().

Definition at line 307 of file preciceC.cpp.

◆ precicec_getMeshVertexSize()

PRECICE_API int precicec_getMeshVertexSize ( const char * meshName )

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

Definition at line 158 of file preciceC.cpp.

◆ precicec_getVersionInformation()

PRECICE_API const char * precicec_getVersionInformation ( )

Returns information on the version of preCICE.

Returns a semicolon-separated C-string containing:

1) the version of preCICE 2) the revision information of preCICE 3) the configuration of preCICE including MPI, PETSC, PYTHON

Definition at line 294 of file preciceC.cpp.

◆ precicec_initialize()

PRECICE_API void precicec_initialize ( )

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

Definition at line 56 of file preciceC.cpp.

◆ precicec_isCouplingOngoing()

PRECICE_API int precicec_isCouplingOngoing ( )

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

Definition at line 87 of file preciceC.cpp.

◆ precicec_isTimeWindowComplete()

PRECICE_API int precicec_isTimeWindowComplete ( )

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

Definition at line 96 of file preciceC.cpp.

◆ precicec_readData()

PRECICE_API void precicec_readData	(	const char *	meshName,
		const char *	dataName,
		int	size,
		const int *	valueIndices,
		double	relativeReadTime,
		double *	values )

Reads vector data values given as block.

The block contains the vector values in the following form: values = (d0x, d0y, d0z, d1x, d1y, d1z, ...., dnx, dny, dnz), where n is the number of vector values. In 2D, the z-components are removed.

Parameters

[in]	meshName	the name of the mesh
[in]	dataName	the name of the data to be read.
[in]	size	Number of indices, and number of values * dimensions.
[in]	valueIndices	Indices (from setReadPosition()) of data values.
[in]	relativeReadTime	Point in time where data is read relative to the beginning of the current time step.
[in]	values	Values of the data to be read.

See also: Participant::readData

Definition at line 258 of file preciceC.cpp.

◆ precicec_requiresGradientDataFor()

PRECICE_API int precicec_requiresGradientDataFor	(	const char *	meshName,
		const char *	dataName )

Checks if the given data set requires gradient data. We check if the data object has been initialized with the gradient flag.

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

◆ precicec_requiresInitialData()

PRECICE_API int precicec_requiresInitialData ( )

Checks if the participant is required to provide initial data.

If true, then the participant needs to write initial data to defined vertices prior to calling initialize().

Note: If initial data is configured, then this function needs to be called.

Precondition: initialize() has not yet been called

Definition at line 110 of file preciceC.cpp.

◆ precicec_requiresMeshConnectivityFor()

PRECICE_API int precicec_requiresMeshConnectivityFor ( const char * meshName )

Checks if the given mesh requires connectivity.

preCICE may require connectivity information from the solver and ignores any API calls regarding connectivity if it is not required. Use this function to conditionally generate this connectivity.

Parameters

[in] meshName the name of the mesh

Returns: whether connectivity is required

Definition at line 128 of file preciceC.cpp.

◆ precicec_requiresReadingCheckpoint()

PRECICE_API int precicec_requiresReadingCheckpoint ( )

Checks if the participant is required to read an iteration checkpoint.

If true, the participant is required to read an iteration checkpoint before calling advance().

Note: If implicit coupling is configured for this Participant, then this function needs to be called.; This function returns false before the first call to advance().

Precondition: initialize() has been called

See also: requiresWritingCheckpoint()

Definition at line 122 of file preciceC.cpp.

◆ precicec_requiresWritingCheckpoint()

PRECICE_API int precicec_requiresWritingCheckpoint ( )

Checks if the participant is required to write an iteration checkpoint.

If true, the participant is required to write an iteration checkpoint before calling advance().

Note: If implicit coupling is configured for this Participant, then this function needs to be called.

Precondition: initialize() has been called

See also: requiresReadingCheckpoint()

Definition at line 116 of file preciceC.cpp.

◆ precicec_setMeshAccessRegion()

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

See precice::Participant::setMeshAccessRegion().

Definition at line 299 of file preciceC.cpp.

◆ precicec_setMeshEdge()

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

Sets mesh edge from vertex IDs.

Parameters

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

Precondition: ids were added to the mesh with the name meshName

Definition at line 165 of file preciceC.cpp.

◆ precicec_setMeshEdges()

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

Sets multiple mesh edge from vertex IDs.

Parameters

[in]	meshName	the name of the mesh to add the edges to
[in]	size	the amount of edges to set
[in]	ids	an array containing 2*size vertex IDs

Precondition: ids were added to the mesh with the name meshName

Definition at line 174 of file preciceC.cpp.

◆ precicec_setMeshQuad()

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

Sets surface mesh quadrangle from vertex IDs.

Parameters

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

Definition at line 204 of file preciceC.cpp.

◆ precicec_setMeshQuads()

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

Sets multiple mesh quads from vertex IDs.

Parameters

[in]	meshName	the name of the mesh to add the quad to
[in]	size	the amount of quads to set
[in]	ids	an array containing 4*size vertex IDs

Precondition: vertices in \ids were added to the mesh with the name meshName

Definition at line 215 of file preciceC.cpp.

◆ precicec_setMeshTetrahedra()

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

Sets multiple mesh tetrahedra from vertex IDs.

Parameters

[in]	meshName	the name of the mesh to add the tetrahedra to
[in]	size	the amount of tetrahedra to set
[in]	ids	an array containing 4*size vertex IDs

Precondition: vertices in ids were added to the mesh with the name meshName

Definition at line 236 of file preciceC.cpp.

◆ precicec_setMeshTetrahedron()

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

Sets mesh tetrahedron from vertex IDs.

Parameters

[in]	meshName	the name of the mesh to add the Tetra to
[in]	firstVertexID	ID of the first vertex of the Tetra
[in]	secondVertexID	ID of the second vertex of the Tetra
[in]	thirdVertexID	ID of the third vertex of the Tetra
[in]	fourthVertexID	ID of the fourth vertex of the Tetra

Definition at line 225 of file preciceC.cpp.

◆ precicec_setMeshTriangle()

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

Sets a triangle from vertex IDs. Creates missing edges.

Definition at line 184 of file preciceC.cpp.

◆ precicec_setMeshTriangles()

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

Sets multiple mesh triangles from vertex IDs.

Parameters

[in]	meshName	the name of the mesh to add the triangles to
[in]	size	the amount of triangles to set
[in]	ids	an array containing 3*size vertex IDs

Precondition: vertices in ids were added to the mesh with the name meshName

Definition at line 194 of file preciceC.cpp.

◆ precicec_setMeshVertex()

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

Creates a mesh vertex.

Parameters

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

Returns: the id of the created vertex

Definition at line 137 of file preciceC.cpp.

◆ precicec_setMeshVertices()

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

Creates multiple mesh vertices.

Parameters

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

Definition at line 146 of file preciceC.cpp.

◆ precicec_writeData()

PRECICE_API void precicec_writeData	(	const char *	meshName,
		const char *	dataName,
		int	size,
		const int *	valueIndices,
		const double *	values )

Writes vector data values given as block.

The block must contain the vector values in the following form: values = (d0x, d0y, d0z, d1x, d1y, d1z, ...., dnx, dny, dnz), where n is the number of vector values. In 2D, the z-components are removed.

Parameters

[in]	meshName	the name of the mesh
[in]	dataName	the name of the data to be written.
[in]	size	Number of indices, and number of values * dimensions.
[in]	values	Values of the data to be written.

See also: Participant::writeData

Definition at line 246 of file preciceC.cpp.

◆ precicec_writeGradientData()

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

Writes vector gradient data to a mesh.

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

Functions

Detailed Description

Function Documentation

◆ precicec_advance()

◆ precicec_createParticipant()

◆ precicec_createParticipant_withCommunicator()

◆ precicec_finalize()

◆ precicec_getDataDimensions()

◆ precicec_getMaxTimeStepSize()

◆ precicec_getMeshDimensions()

◆ precicec_getMeshVertexIDsAndCoordinates()

◆ precicec_getMeshVertexSize()

◆ precicec_getVersionInformation()

◆ precicec_initialize()

◆ precicec_isCouplingOngoing()

◆ precicec_isTimeWindowComplete()

◆ precicec_readData()

◆ precicec_requiresGradientDataFor()

◆ precicec_requiresInitialData()

◆ precicec_requiresMeshConnectivityFor()

◆ precicec_requiresReadingCheckpoint()

◆ precicec_requiresWritingCheckpoint()

◆ precicec_setMeshAccessRegion()

◆ precicec_setMeshEdge()

◆ precicec_setMeshEdges()

◆ precicec_setMeshQuad()

◆ precicec_setMeshQuads()

◆ precicec_setMeshTetrahedra()

◆ precicec_setMeshTetrahedron()

◆ precicec_setMeshTriangle()

◆ precicec_setMeshTriangles()

◆ precicec_setMeshVertex()

◆ precicec_setMeshVertices()

◆ precicec_writeData()

◆ precicec_writeGradientData()