preCICE v3.1.2
Loading...
Searching...
No Matches
Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
precice::cplscheme::CompositionalCouplingScheme Class Referencefinal

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

#include <CompositionalCouplingScheme.hpp>

Inheritance diagram for precice::cplscheme::CompositionalCouplingScheme:
[legend]
Collaboration diagram for precice::cplscheme::CompositionalCouplingScheme:
[legend]

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

  1. I1 and I2 iterate until convergence
  2. E1 and E2 are computed
  3. I3 iterates until convergence
  4. E3 is computed
  5. I4 and I5 iterate until convergence
  6. 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

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
timeToAddtime 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]startTimeTODO
[in]startTimeWindowTODO

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: