Interface for all coupling schemes. More...

#include <CouplingScheme.hpp>

Inheritance diagram for precice::cplscheme::CouplingScheme:

Public Types
enum struct	Action { InitializeData , ReadCheckpoint , WriteCheckpoint }
	Actions that are required by CouplingSchemes. More...

Public Member Functions
CouplingScheme &	operator= (CouplingScheme &&)=delete

virtual	~CouplingScheme ()

virtual void	initialize (double startTime, int startTimeWindow)=0
	Initializes the coupling scheme and establishes a communication connection to the coupling partner. Initializes coupling data.

virtual bool	sendsInitializedData () const =0
	Returns whether this participant of the coupling scheme sends initialized data.

virtual bool	isInitialized () const =0
	Returns true, if initialize has been called.

virtual void	finalize ()=0
	Finalizes the coupling and disconnects communication.

virtual std::vector< std::string >	getCouplingPartners () const =0
	Returns list of all coupling partners.

virtual std::string	localParticipant () const =0
	Returns the name of the local participant.

virtual bool	willDataBeExchanged (double lastSolverTimeStepSize) const =0
	Returns true, if data will be exchanged when calling advance().

virtual bool	hasDataBeenReceived () const =0
	Returns true, if data has been exchanged in last call of advance().

virtual double	getTimeWindowStart () const =0

virtual double	getTime () const =0
	Returns the currently computed time of the coupling scheme.

virtual int	getTimeWindows () const =0
	Returns the currently computed time windows of the coupling scheme.

virtual bool	hasTimeWindowSize () const =0
	Returns true, if time window size is prescribed by the cpl scheme.

virtual double	getTimeWindowSize () const =0
	Returns the time window size, if one is given by the coupling scheme.

virtual double	getNextTimeStepMaxSize () const =0
	Returns the maximal size of the next time step to be computed.

virtual bool	isCouplingOngoing () const =0
	Returns true, when the coupled simulation is still ongoing.

virtual bool	isTimeWindowComplete () const =0
	Returns true, when the accessor can advance to the next time window.

virtual bool	isActionRequired (Action action) const =0
	Returns true, if the given action has to be performed by the accessor.

virtual bool	isActionFulfilled (Action action) const =0
	Returns true, if the given action has already been performed by the accessor.

virtual void	markActionFulfilled (Action action)=0
	Tells the coupling scheme that the accessor has performed the given action.

virtual void	requireAction (Action action)=0
	Sets an action required to be performed by the accessor.

virtual std::string	printCouplingState () const =0
	Returns a string representation of the current coupling state.

virtual bool	isImplicitCouplingScheme () const =0
	Returns true if the scheme or one subscheme is implicit.

virtual bool	hasConverged () const =0
	Returns false if the scheme is implicit and hasn't converged.

virtual bool	requiresSubsteps () const =0
	Returns true if any send data of the scheme requires substeps.

virtual ImplicitData	implicitDataToReceive () const =0
	Returns a vector of implicit data to receive in the next advance.

Static Public Member Functions
static std::string	toString (Action action)

Static Public Attributes
static const double	UNDEFINED_MAX_TIME = -1.0
	Does not define a time limit for the coupled simulation.

static const int	UNDEFINED_TIME_WINDOWS = -1
	Does not define limit on time windows for the coupled simulation.

static const double	UNDEFINED_TIME_WINDOW_SIZE = -1.0
	To be used, when the time window size is determined dynamically during the coupling.

static const int	UNDEFINED_MAX_ITERATIONS = -1
	To be used, when the number of max iterations is not defined (for explicit coupling).

static const int	UNDEFINED_MIN_ITERATIONS = -1
	To be used, when the number of min iterations is not defined (for explicit coupling).

static const int	INFINITE_MAX_ITERATIONS = -2
	To be used, when the number of max iterations is infinite (for implicit coupling).

Advancing
Advancing the couplingscheme
using	ChangedMeshes = std::vector<MeshID>

virtual bool	addComputedTime (double timeToAdd)=0
	Adds newly computed time. Has to be called before every advance.

virtual ChangedMeshes	firstSynchronization (const ChangedMeshes &changes)=0

virtual void	firstExchange ()=0

virtual ChangedMeshes	secondSynchronization ()=0

virtual void	secondExchange ()=0

Detailed Description

Interface for all coupling schemes.

! General description A coupling scheme computes the actions to be done by the coupled participants (solvers) in time. It provides interface functions to setup, advance and shutdown the coupling scheme and interface functions to query the state of the coupling scheme and required actions of the participants.

! Usage

create an object of a concrete coupling scheme class (ExplicitCouplingScheme, e.g.)
add all meshes holding data to the coupling scheme by addMesh()
configure the object by adding subclass specific information
start the coupling scheme with initialize(), where the name of the local participant, i.e. the participant using the coupling scheme object, is needed
retrieve necessary information about sent/received data and the state of the coupled simulation
query and fulfill required actions
compute data to be sent (possibly taking into account received data from initialize())
advance the coupling scheme in 4 steps: firstSynchronization, firstExchange, secondSynchronization, secondExchange;
....
when the method isCouplingOngoing() returns false, call finalize() to stop the coupling scheme

Definition at line 42 of file CouplingScheme.hpp.

Member Typedef Documentation

◆ ChangedMeshes

using precice::cplscheme::CouplingScheme::ChangedMeshes = std::vector<MeshID>

Definition at line 110 of file CouplingScheme.hpp.

Member Enumeration Documentation

◆ Action

enum struct precice::cplscheme::CouplingScheme::Action

strong

Actions that are required by CouplingSchemes.

Enumerator
InitializeData	Is the initialization of coupling data required?
ReadCheckpoint	Is the participant required to read a previously written checkpoint?
WriteCheckpoint	Is the participant required to write a checkpoint?

Definition at line 63 of file CouplingScheme.hpp.

Constructor & Destructor Documentation

◆ ~CouplingScheme()

virtual precice::cplscheme::CouplingScheme::~CouplingScheme ( )

inlinevirtual

Definition at line 73 of file CouplingScheme.hpp.

Member Function Documentation

◆ addComputedTime()

virtual bool precice::cplscheme::CouplingScheme::addComputedTime ( double timeToAdd )

pure virtual

Adds newly computed time. Has to be called before every advance.

Parameters

timeToAdd time to be added

Returns: true, if reaches end of the window by adding timeToAdd to time in this time step.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ finalize()

virtual void precice::cplscheme::CouplingScheme::finalize ( )

pure virtual

Finalizes the coupling and disconnects communication.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ firstExchange()

virtual void precice::cplscheme::CouplingScheme::firstExchange ( )

pure virtual

Exchanges the first set of data.

Precondition: firstSynchronization() was called

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::tests::DummyCouplingScheme, and precice::cplscheme::BaseCouplingScheme.

◆ firstSynchronization()

virtual ChangedMeshes precice::cplscheme::CouplingScheme::firstSynchronization ( const ChangedMeshes & changes )

pure virtual

Synchronizes mesh changes with remote participants.

At this point, both participants may have changed the meshes. Thus, we need to send local changes and receive remote changes.

Parameters

[in] changes MeshIDs of locally changed meshes

Returns: MeshIDs of remotely changed meshes.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::tests::DummyCouplingScheme, and precice::cplscheme::BaseCouplingScheme.

◆ getCouplingPartners()

virtual std::vector< std::string > precice::cplscheme::CouplingScheme::getCouplingPartners ( ) const

pure virtual

Returns list of all coupling partners.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BiCouplingScheme, precice::cplscheme::MultiCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ getNextTimeStepMaxSize()

virtual double precice::cplscheme::CouplingScheme::getNextTimeStepMaxSize ( ) const

pure virtual

Returns the maximal size of the next time step to be computed.

If no time window size is prescribed by the coupling scheme, always the maximal double accuracy floating point number value is returned.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ getTime()

virtual double precice::cplscheme::CouplingScheme::getTime ( ) const

pure virtual

Returns the currently computed time of the coupling scheme.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ getTimeWindows()

virtual int precice::cplscheme::CouplingScheme::getTimeWindows ( ) const

pure virtual

Returns the currently computed time windows of the coupling scheme.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ getTimeWindowSize()

virtual double precice::cplscheme::CouplingScheme::getTimeWindowSize ( ) const

pure virtual

Returns the time window size, if one is given by the coupling scheme.

An assertion is thrown, if no valid time window size is given. Check with hasTimeWindowSize().

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ getTimeWindowStart()

virtual double precice::cplscheme::CouplingScheme::getTimeWindowStart ( ) const

pure virtual

Returns the time window start time of the current time window For compositional schemes, this returns the earliest start of an active time window

Implemented in precice::cplscheme::BaseCouplingScheme, precice::cplscheme::CompositionalCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ hasConverged()

virtual bool precice::cplscheme::CouplingScheme::hasConverged ( ) const

pure virtual

Returns false if the scheme is implicit and hasn't converged.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ hasDataBeenReceived()

virtual bool precice::cplscheme::CouplingScheme::hasDataBeenReceived ( ) const

pure virtual

Returns true, if data has been exchanged in last call of advance().

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ hasTimeWindowSize()

virtual bool precice::cplscheme::CouplingScheme::hasTimeWindowSize ( ) const

pure virtual

Returns true, if time window size is prescribed by the cpl scheme.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ implicitDataToReceive()

virtual ImplicitData precice::cplscheme::CouplingScheme::implicitDataToReceive ( ) const

pure virtual

Returns a vector of implicit data to receive in the next advance.

Implemented in precice::cplscheme::BaseCouplingScheme, precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::SerialCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ initialize()

virtual void precice::cplscheme::CouplingScheme::initialize	(	double	startTime,
		int	startTimeWindow )

pure virtual

Initializes the coupling scheme and establishes a communication connection to the coupling partner. Initializes coupling data.

Parameters

[in]	startTime	starting time for coupling @BU correct?
[in]	startTimeWindow	counter of time window for coupling @BU correct?

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ isActionFulfilled()

virtual bool precice::cplscheme::CouplingScheme::isActionFulfilled ( Action action ) const

pure virtual

Returns true, if the given action has already been performed by the accessor.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ isActionRequired()

virtual bool precice::cplscheme::CouplingScheme::isActionRequired ( Action action ) const

pure virtual

Returns true, if the given action has to be performed by the accessor.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ isCouplingOngoing()

virtual bool precice::cplscheme::CouplingScheme::isCouplingOngoing ( ) const

pure virtual

Returns true, when the coupled simulation is still ongoing.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ isImplicitCouplingScheme()

virtual bool precice::cplscheme::CouplingScheme::isImplicitCouplingScheme ( ) const

pure virtual

Returns true if the scheme or one subscheme is implicit.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ isInitialized()

virtual bool precice::cplscheme::CouplingScheme::isInitialized ( ) const

pure virtual

Returns true, if initialize has been called.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ isTimeWindowComplete()

virtual bool precice::cplscheme::CouplingScheme::isTimeWindowComplete ( ) const

pure virtual

Returns true, when the accessor can advance to the next time window.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ localParticipant()

virtual std::string precice::cplscheme::CouplingScheme::localParticipant ( ) const

pure virtual

Returns the name of the local participant.

Implemented in precice::cplscheme::BaseCouplingScheme, precice::cplscheme::CompositionalCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ markActionFulfilled()

virtual void precice::cplscheme::CouplingScheme::markActionFulfilled ( Action action )

pure virtual

Tells the coupling scheme that the accessor has performed the given action.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ operator=()

CouplingScheme & precice::cplscheme::CouplingScheme::operator= ( CouplingScheme && )

delete

◆ printCouplingState()

virtual std::string precice::cplscheme::CouplingScheme::printCouplingState ( ) const

pure virtual

Returns a string representation of the current coupling state.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ requireAction()

virtual void precice::cplscheme::CouplingScheme::requireAction ( Action action )

pure virtual

Sets an action required to be performed by the accessor.

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ requiresSubsteps()

virtual bool precice::cplscheme::CouplingScheme::requiresSubsteps ( ) const

pure virtual

Returns true if any send data of the scheme requires substeps.

Implemented in precice::cplscheme::BaseCouplingScheme, precice::cplscheme::CompositionalCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ secondExchange()

virtual void precice::cplscheme::CouplingScheme::secondExchange ( )

pure virtual

Exchanges the second set of data.

This concludes the step of the coupling scheme

Precondition: secondSynchronization() was called

Implemented in precice::cplscheme::tests::DummyCouplingScheme, precice::cplscheme::CompositionalCouplingScheme, and precice::cplscheme::BaseCouplingScheme.

◆ secondSynchronization()

virtual ChangedMeshes precice::cplscheme::CouplingScheme::secondSynchronization ( )

pure virtual

Receive mesh changes from remote participants in the second step.

At this point, the remote participant may have changed the meshes if it is using a serial coupling scheme. In contrast, the local participant has already communicated local changes to the remote participant during firstSynchronization(). Hence we only need to receive remote changes here.

Note: local changes are covered by firstSynchronization()

Returns: MeshIDs of remotely changed meshes.

Precondition: firstExchange() was called

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::tests::DummyCouplingScheme, and precice::cplscheme::BaseCouplingScheme.

◆ sendsInitializedData()

virtual bool precice::cplscheme::CouplingScheme::sendsInitializedData ( ) const

pure virtual

Returns whether this participant of the coupling scheme sends initialized data.

Returns: true, if this participant of the coupling scheme sends initialized data

Implemented in precice::cplscheme::BaseCouplingScheme, precice::cplscheme::CompositionalCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

◆ toString()

std::string precice::cplscheme::CouplingScheme::toString ( Action action )

static

Definition at line 15 of file CouplingScheme.cpp.

Here is the call graph for this function:

◆ willDataBeExchanged()

virtual bool precice::cplscheme::CouplingScheme::willDataBeExchanged ( double lastSolverTimeStepSize ) const

pure virtual

Returns true, if data will be exchanged when calling advance().

Also returns true after the last call of advance() at the end of the simulation.

Parameters

lastSolverTimeStepSize [IN] The size of the last time step computed by the solver calling willDataBeExchanged().

Implemented in precice::cplscheme::CompositionalCouplingScheme, precice::cplscheme::BaseCouplingScheme, and precice::cplscheme::tests::DummyCouplingScheme.

Member Data Documentation

◆ INFINITE_MAX_ITERATIONS

const int precice::cplscheme::CouplingScheme::INFINITE_MAX_ITERATIONS = -2

static

To be used, when the number of max iterations is infinite (for implicit coupling).

Definition at line 60 of file CouplingScheme.hpp.

◆ UNDEFINED_MAX_ITERATIONS

const int precice::cplscheme::CouplingScheme::UNDEFINED_MAX_ITERATIONS = -1

static

To be used, when the number of max iterations is not defined (for explicit coupling).

Definition at line 54 of file CouplingScheme.hpp.

◆ UNDEFINED_MAX_TIME

const double precice::cplscheme::CouplingScheme::UNDEFINED_MAX_TIME = -1.0

static

Does not define a time limit for the coupled simulation.

Definition at line 45 of file CouplingScheme.hpp.

◆ UNDEFINED_MIN_ITERATIONS

const int precice::cplscheme::CouplingScheme::UNDEFINED_MIN_ITERATIONS = -1

static

To be used, when the number of min iterations is not defined (for explicit coupling).

Definition at line 57 of file CouplingScheme.hpp.

◆ UNDEFINED_TIME_WINDOW_SIZE

const double precice::cplscheme::CouplingScheme::UNDEFINED_TIME_WINDOW_SIZE = -1.0

static

To be used, when the time window size is determined dynamically during the coupling.

Definition at line 51 of file CouplingScheme.hpp.

◆ UNDEFINED_TIME_WINDOWS

const int precice::cplscheme::CouplingScheme::UNDEFINED_TIME_WINDOWS = -1

static

Does not define limit on time windows for the coupled simulation.

Definition at line 48 of file CouplingScheme.hpp.

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

src/cplscheme/CouplingScheme.hpp
src/cplscheme/CouplingScheme.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Advancing

Detailed Description

Member Typedef Documentation

◆ ChangedMeshes

Member Enumeration Documentation

◆ Action

Constructor & Destructor Documentation

◆ ~CouplingScheme()

Member Function Documentation

◆ addComputedTime()

◆ finalize()

◆ firstExchange()

◆ firstSynchronization()

◆ getCouplingPartners()

◆ getNextTimeStepMaxSize()

◆ getTime()

◆ getTimeWindows()

◆ getTimeWindowSize()

◆ getTimeWindowStart()

◆ hasConverged()

◆ hasDataBeenReceived()

◆ hasTimeWindowSize()

◆ implicitDataToReceive()

◆ initialize()

◆ isActionFulfilled()

◆ isActionRequired()

◆ isCouplingOngoing()

◆ isImplicitCouplingScheme()

◆ isInitialized()

◆ isTimeWindowComplete()

◆ localParticipant()

◆ markActionFulfilled()

◆ operator=()

◆ printCouplingState()

◆ requireAction()

◆ requiresSubsteps()

◆ secondExchange()

◆ secondSynchronization()

◆ sendsInitializedData()

◆ toString()

◆ willDataBeExchanged()

Member Data Documentation

◆ INFINITE_MAX_ITERATIONS

◆ UNDEFINED_MAX_ITERATIONS

◆ UNDEFINED_MAX_TIME

◆ UNDEFINED_MIN_ITERATIONS

◆ UNDEFINED_TIME_WINDOW_SIZE

◆ UNDEFINED_TIME_WINDOWS