preCICE v3.1.2
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
precice::cplscheme::CouplingScheme Class Referenceabstract

Interface for all coupling schemes. More...

#include <CouplingScheme.hpp>

Inheritance diagram for precice::cplscheme::CouplingScheme:
[legend]

Public Types

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

Public Member Functions

CouplingSchemeoperator= (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::stringgetCouplingPartners () 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

  1. create an object of a concrete coupling scheme class (ExplicitCouplingScheme, e.g.)
  2. add all meshes holding data to the coupling scheme by addMesh()
  3. configure the object by adding subclass specific information
  4. start the coupling scheme with initialize(), where the name of the local participant, i.e. the participant using the coupling scheme object, is needed
  5. retrieve necessary information about sent/received data and the state of the coupled simulation
  6. query and fulfill required actions
  7. compute data to be sent (possibly taking into account received data from initialize())
  8. advance the coupling scheme in 4 steps: firstSynchronization, firstExchange, secondSynchronization, secondExchange;
  9. ....
  10. 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

Definition at line 110 of file CouplingScheme.hpp.

Member Enumeration Documentation

◆ Action

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
timeToAddtime 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

◆ firstExchange()

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

◆ 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]changesMeshIDs 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

◆ 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

◆ 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

◆ 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]startTimestarting time for coupling @BU correct?
[in]startTimeWindowcounter 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

◆ isImplicitCouplingScheme()

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

◆ isInitialized()

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

◆ 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

◆ 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

◆ 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: