Acts as one coupling scheme, but consists of several composed ones. More...

#include <CompositionalCouplingScheme.hpp>

Inheritance diagram for precice::cplscheme::CompositionalCouplingScheme:

Collaboration diagram for precice::cplscheme::CompositionalCouplingScheme:

Public Member Functions
virtual	~CompositionalCouplingScheme ()
	Destructor, empty.

void	addCouplingScheme (const PtrCouplingScheme &scheme)
	Adds another coupling scheme in parallel to this scheme.

void	initialize (double startTime, int startTimeWindow) final override
	Initializes the coupling scheme and establishes a communication connection to the coupling partner.

bool	sendsInitializedData () const override final
	Returns true, if any of the composed coupling schemes sendsInitializedData for this participant.

bool	isInitialized () const final override
	Returns true, if initialize has been called.

bool	addComputedTime (double timeToAdd) final override
	Adds newly computed time. Has to be called before every advance.

ChangedMeshes	firstSynchronization (const ChangedMeshes &changes) override
	Exchanges data and updates the state of the coupling scheme.

void	firstExchange () override

ChangedMeshes	secondSynchronization () override

void	secondExchange () override

void	finalize () final override
	Finalizes the coupling and disconnects communication.

std::vector< std::string >	getCouplingPartners () const final override
	Returns list of all coupling partners.

std::string	localParticipant () const override final
	Returns the name of the local participant.

bool	willDataBeExchanged (double lastSolverTimeStepSize) const final override
	Returns true, if data will be exchanged when calling advance().

bool	hasDataBeenReceived () const final override
	checks all coupling schemes this coupling scheme is composed of.

double	getTime () const final override
	Returns the currently computed time of the coupling scheme.

double	getTimeWindowStart () const override final

int	getTimeWindows () const final override
	Returns the currently computed time windows of the coupling scheme.

bool	hasTimeWindowSize () const final override
	Returns true, if time window size is given by any of the coupling schemes in this compositional coupling scheme.

double	getTimeWindowSize () const final override
	Returns the time window size, if one is given by the coupling scheme.

double	getNextTimeStepMaxSize () const final override
	Returns the maximal size of the next time step to be computed.

bool	isCouplingOngoing () const final override
	Returns true, when the coupled simulation is still ongoing.

bool	isTimeWindowComplete () const final override
	Returns true, when the accessor can advance to the next time window.

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

bool	isActionFulfilled (Action action) const final override
	Returns true, if the given action has been performed by the accessor.

void	markActionFulfilled (Action action) final override
	Tells the coupling scheme that the accessor has performed the given action.

void	requireAction (Action action) final override
	Sets an action required to be performed by the accessor.

std::string	printCouplingState () const final override
	Returns a string representation of the current coupling state.

bool	isImplicitCouplingScheme () const final
	True if one cplscheme is an implicit scheme.

bool	hasConverged () const final
	True if the implicit scheme has converged or no implicit scheme is defined.

bool	requiresSubsteps () const override final
	Returns true if any send data of the scheme requires substeps.

ImplicitData	implicitDataToReceive () const override final
	Returns a vector of implicit data to receive in the next advance.

Public Member Functions inherited from precice::cplscheme::CouplingScheme
CouplingScheme &	operator= (CouplingScheme &&)=delete

virtual	~CouplingScheme ()

Private Types
using	Schemes = std::vector<PtrCouplingScheme>

Private Member Functions
void	updateActiveSchemes ()

std::vector< CouplingScheme * >	allSchemes () const
	Returns all schemes in execution order, explicit as well as implicit.

std::vector< CouplingScheme * >	activeOrAllSchemes () const
	Actions also work before initialize is called.

void	checkCompatibleTimeWindowSizes (const CouplingScheme &impl, const CouplingScheme &expl) const
	check if time windows are compatible

Private Attributes
logging::Logger	_log {"cplscheme::CompositionalCouplingScheme"}

Schemes	_explicitSchemes
	Explicit coupling schemes to be executed.

PtrCouplingScheme	_implicitScheme
	The optional implicit scheme to be handled last.

bool	_explicitOnHold = false
	Are explicit schemes on hold?

std::vector< CouplingScheme * >	_activeSchemes

Additional Inherited Members
Public Types inherited from precice::cplscheme::CouplingScheme
enum struct	Action { InitializeData , ReadCheckpoint , WriteCheckpoint }
	Actions that are required by CouplingSchemes. More...

using	ChangedMeshes = std::vector<MeshID>

Static Public Member Functions inherited from precice::cplscheme::CouplingScheme
static std::string	toString (Action action)

Static Public Attributes inherited from precice::cplscheme::CouplingScheme
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).

Detailed Description

Acts as one coupling scheme, but consists of several composed ones.

The sequence of how the schemes are added by addCouplingScheme() determines their execution sequence. The schemes are executed from first added to last added, following the rule that implicit schemes need to be converged before executing the next explicit scheme/s. An example with implicit schemes I1, ..., I5 and explicit schemes E1, ..., E4 is given here. The schemes are added in the sequence

I1, I2, E1, E2, I3, E3, I4, I5, E4

The execution is as follows:

I1 and I2 iterate until convergence
E1 and E2 are computed
I3 iterates until convergence
E3 is computed
I4 and I5 iterate until convergence
E4 is computed

Steps 2 and 3 are computed directly when 1 is converged, i.e., no additional solver iteration/computation is necessary. Step 3, however, will require additional solver computations for every additional iteration. Similarly, 4 and 5 are computed directly when 3 is converged and 6 is computed directly when 5 is converged.

The grouping into such "active" sets is repeatedly done, in order to know which coupling schemes should be executed. The implicit coupling scheme actions constants::actionWrite/ReadIterationCheckpoint() is used to find out about whether a coupling scheme does perform iterations.

When, in an active set of implicit coupling schemes, a scheme is converged but others not, the converged scheme is put on hold until all schemes in the active set are converged. This assumes that the converged state of a coupling scheme is not deteriorated by the further iteration of the remaining non-converged schemes.

The execution of each scheme does not only depend on this sequence, but also on how the participants are configured to be first and second in the schemes. If not configured properly, a deadlock might be created.

Definition at line 57 of file CompositionalCouplingScheme.hpp.

Member Typedef Documentation

◆ Schemes

using precice::cplscheme::CompositionalCouplingScheme::Schemes = std::vector<PtrCouplingScheme>

private

Definition at line 219 of file CompositionalCouplingScheme.hpp.

Constructor & Destructor Documentation

◆ ~CompositionalCouplingScheme()

virtual precice::cplscheme::CompositionalCouplingScheme::~CompositionalCouplingScheme ( )

inlinevirtual

Destructor, empty.

Definition at line 60 of file CompositionalCouplingScheme.hpp.

Member Function Documentation

◆ activeOrAllSchemes()

std::vector< CouplingScheme * > precice::cplscheme::CompositionalCouplingScheme::activeOrAllSchemes ( ) const

private

Actions also work before initialize is called.

Definition at line 487 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ addComputedTime()

bool precice::cplscheme::CompositionalCouplingScheme::addComputedTime ( double timeToAdd )

finaloverridevirtual

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.

Implements precice::cplscheme::CouplingScheme.

Definition at line 109 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ addCouplingScheme()

void precice::cplscheme::CompositionalCouplingScheme::addCouplingScheme ( const PtrCouplingScheme & scheme )

Adds another coupling scheme in parallel to this scheme.

If this coupling scheme is a normal coupling scheme, an object of CompositionalCouplingScheme will be created that contains this and the new scheme in parallel. If this coupling scheme is already a composed scheme, the new scheme will be added as another parallel scheme.

Returns: Pointer to composition of coupling schemes.

Definition at line 60 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ allSchemes()

std::vector< CouplingScheme * > precice::cplscheme::CompositionalCouplingScheme::allSchemes ( ) const

private

Returns all schemes in execution order, explicit as well as implicit.

Definition at line 477 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ checkCompatibleTimeWindowSizes()

void precice::cplscheme::CompositionalCouplingScheme::checkCompatibleTimeWindowSizes	(	const CouplingScheme &	impl,
		const CouplingScheme &	expl ) const

private

check if time windows are compatible

Definition at line 41 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ finalize()

void precice::cplscheme::CompositionalCouplingScheme::finalize ( )

finaloverridevirtual

Finalizes the coupling and disconnects communication.

Implements precice::cplscheme::CouplingScheme.

Definition at line 237 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ firstExchange()

void precice::cplscheme::CompositionalCouplingScheme::firstExchange ( )

overridevirtual

Exchanges the first set of data.

Precondition: firstSynchronization() was called

Implements precice::cplscheme::CouplingScheme.

Definition at line 162 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ firstSynchronization()

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

overridevirtual

Exchanges data and updates the state of the coupling scheme.

Implements precice::cplscheme::CouplingScheme.

Definition at line 149 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ getCouplingPartners()

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

finaloverridevirtual

Returns list of all coupling partners.

Implements precice::cplscheme::CouplingScheme.

Definition at line 245 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ getNextTimeStepMaxSize()

double precice::cplscheme::CompositionalCouplingScheme::getNextTimeStepMaxSize ( ) const

finaloverridevirtual

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

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

This is the minimum of all max sizes of the composed coupling schemes.

Implements precice::cplscheme::CouplingScheme.

Definition at line 338 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ getTime()

double precice::cplscheme::CompositionalCouplingScheme::getTime ( ) const

finaloverridevirtual

Returns the currently computed time of the coupling scheme.

This time is the minimum time of any coupling scheme in the composition.

Implements precice::cplscheme::CouplingScheme.

Definition at line 284 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ getTimeWindows()

int precice::cplscheme::CompositionalCouplingScheme::getTimeWindows ( ) const

finaloverridevirtual

Returns the currently computed time windows of the coupling scheme.

The time window is the minimum time window in any coupling scheme in the composition.

Implements precice::cplscheme::CouplingScheme.

Definition at line 308 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ getTimeWindowSize()

double precice::cplscheme::CompositionalCouplingScheme::getTimeWindowSize ( ) const

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 330 of file CompositionalCouplingScheme.cpp.

◆ getTimeWindowStart()

double precice::cplscheme::CompositionalCouplingScheme::getTimeWindowStart ( ) const

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 296 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ hasConverged()

bool precice::cplscheme::CompositionalCouplingScheme::hasConverged ( ) const

finalvirtual

True if the implicit scheme has converged or no implicit scheme is defined.

Implements precice::cplscheme::CouplingScheme.

Definition at line 497 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ hasDataBeenReceived()

bool precice::cplscheme::CompositionalCouplingScheme::hasDataBeenReceived ( ) const

finaloverridevirtual

checks all coupling schemes this coupling scheme is composed of.

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 274 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ hasTimeWindowSize()

bool precice::cplscheme::CompositionalCouplingScheme::hasTimeWindowSize ( ) const

finaloverridevirtual

Returns true, if time window size is given by any of the coupling schemes in this compositional coupling scheme.

Implements precice::cplscheme::CouplingScheme.

Definition at line 322 of file CompositionalCouplingScheme.cpp.

◆ implicitDataToReceive()

ImplicitData precice::cplscheme::CompositionalCouplingScheme::implicitDataToReceive ( ) const

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 516 of file CompositionalCouplingScheme.cpp.

◆ initialize()

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

finaloverridevirtual

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

Parameters

[in]	startTime	TODO
[in]	startTimeWindow	TODO

Implements precice::cplscheme::CouplingScheme.

Definition at line 80 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ isActionFulfilled()

bool precice::cplscheme::CompositionalCouplingScheme::isActionFulfilled ( Action action ) const

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 401 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ isActionRequired()

bool precice::cplscheme::CompositionalCouplingScheme::isActionRequired ( Action action ) const

finaloverridevirtual

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

True, if any of the composed coupling schemes requires the action.

Implements precice::cplscheme::CouplingScheme.

Definition at line 385 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ isCouplingOngoing()

bool precice::cplscheme::CompositionalCouplingScheme::isCouplingOngoing ( ) const

finaloverridevirtual

Returns true, when the coupled simulation is still ongoing.

As long as one composed coupling scheme is still ongoing, returns true.

Implements precice::cplscheme::CouplingScheme.

Definition at line 364 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ isImplicitCouplingScheme()

bool precice::cplscheme::CompositionalCouplingScheme::isImplicitCouplingScheme ( ) const

finalvirtual

True if one cplscheme is an implicit scheme.

Implements precice::cplscheme::CouplingScheme.

Definition at line 492 of file CompositionalCouplingScheme.cpp.

◆ isInitialized()

bool precice::cplscheme::CompositionalCouplingScheme::isInitialized ( ) const

finaloverridevirtual

Returns true, if initialize has been called.

Implements precice::cplscheme::CouplingScheme.

Definition at line 101 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ isTimeWindowComplete()

bool precice::cplscheme::CompositionalCouplingScheme::isTimeWindowComplete ( ) const

finaloverridevirtual

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

Only true, if all composed coupling schemes have completed the time window.

Implements precice::cplscheme::CouplingScheme.

Definition at line 375 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ localParticipant()

std::string precice::cplscheme::CompositionalCouplingScheme::localParticipant ( ) const

finaloverridevirtual

Returns the name of the local participant.

Implements precice::cplscheme::CouplingScheme.

Definition at line 256 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ markActionFulfilled()

void precice::cplscheme::CompositionalCouplingScheme::markActionFulfilled ( Action action )

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 416 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ printCouplingState()

std::string precice::cplscheme::CompositionalCouplingScheme::printCouplingState ( ) const

finaloverridevirtual

Returns a string representation of the current coupling state.

Implements precice::cplscheme::CouplingScheme.

Definition at line 434 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ requireAction()

void precice::cplscheme::CompositionalCouplingScheme::requireAction ( Action action )

finaloverridevirtual

Sets an action required to be performed by the accessor.

Implements precice::cplscheme::CouplingScheme.

Definition at line 427 of file CompositionalCouplingScheme.cpp.

◆ requiresSubsteps()

bool precice::cplscheme::CompositionalCouplingScheme::requiresSubsteps ( ) const

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 506 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ secondExchange()

void precice::cplscheme::CompositionalCouplingScheme::secondExchange ( )

overridevirtual

Exchanges the second set of data.

This concludes the step of the coupling scheme

Precondition: secondSynchronization() was called

Implements precice::cplscheme::CouplingScheme.

Definition at line 197 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ secondSynchronization()

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

overridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 185 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ sendsInitializedData()

bool precice::cplscheme::CompositionalCouplingScheme::sendsInitializedData ( ) const

finaloverridevirtual

Returns true, if any of the composed coupling schemes sendsInitializedData for this participant.

Implements precice::cplscheme::CouplingScheme.

Definition at line 92 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ updateActiveSchemes()

void precice::cplscheme::CompositionalCouplingScheme::updateActiveSchemes ( )

private

Updates _activeSchemes to the next ones that will participate in the upcoming step in time Called from secondExchange

Definition at line 451 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

◆ willDataBeExchanged()

bool precice::cplscheme::CompositionalCouplingScheme::willDataBeExchanged ( double lastSolverTimeStepSize ) const

finaloverridevirtual

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

Implements precice::cplscheme::CouplingScheme.

Definition at line 263 of file CompositionalCouplingScheme.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ _activeSchemes

std::vector<CouplingScheme *> precice::cplscheme::CompositionalCouplingScheme::_activeSchemes

private

All schemes to run next

This is the core of the CompositionalCouplingScheme

All schemes start at t=0, so they all run on the first time step. This is updated by finishing the complete advance calling secondExchange() using updateActiveSchemes().

Definition at line 237 of file CompositionalCouplingScheme.hpp.

◆ _explicitOnHold

bool precice::cplscheme::CompositionalCouplingScheme::_explicitOnHold = false

private

Are explicit schemes on hold?

Definition at line 228 of file CompositionalCouplingScheme.hpp.

◆ _explicitSchemes

Schemes precice::cplscheme::CompositionalCouplingScheme::_explicitSchemes

private

Explicit coupling schemes to be executed.

Definition at line 222 of file CompositionalCouplingScheme.hpp.

◆ _implicitScheme

PtrCouplingScheme precice::cplscheme::CompositionalCouplingScheme::_implicitScheme

private

The optional implicit scheme to be handled last.

Definition at line 225 of file CompositionalCouplingScheme.hpp.

◆ _log

logging::Logger precice::cplscheme::CompositionalCouplingScheme::_log {"cplscheme::CompositionalCouplingScheme"}

mutableprivate

Definition at line 217 of file CompositionalCouplingScheme.hpp.

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

src/cplscheme/CompositionalCouplingScheme.hpp
src/cplscheme/CompositionalCouplingScheme.cpp

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Schemes

Constructor & Destructor Documentation

◆ ~CompositionalCouplingScheme()

Member Function Documentation

◆ activeOrAllSchemes()

◆ addComputedTime()

◆ addCouplingScheme()

◆ allSchemes()

◆ checkCompatibleTimeWindowSizes()

◆ finalize()

◆ firstExchange()

◆ firstSynchronization()

◆ getCouplingPartners()

◆ getNextTimeStepMaxSize()

◆ getTime()

◆ getTimeWindows()

◆ getTimeWindowSize()

◆ getTimeWindowStart()

◆ hasConverged()

◆ hasDataBeenReceived()

◆ hasTimeWindowSize()

◆ implicitDataToReceive()

◆ initialize()

◆ isActionFulfilled()

◆ isActionRequired()

◆ isCouplingOngoing()

◆ isImplicitCouplingScheme()

◆ isInitialized()

◆ isTimeWindowComplete()

◆ localParticipant()

◆ markActionFulfilled()

◆ printCouplingState()

◆ requireAction()

◆ requiresSubsteps()

◆ secondExchange()

◆ secondSynchronization()

◆ sendsInitializedData()

◆ updateActiveSchemes()

◆ willDataBeExchanged()

Member Data Documentation

◆ _activeSchemes

◆ _explicitOnHold

◆ _explicitSchemes

◆ _implicitScheme

◆ _log