System Coupling Python library 2023 R2

Participant Steps in a Coupled Analysis

Last update: 10.07.2023

During a coupled analysis, a specific sequence of steps should be traversed. This process is depicted in Figure 1 for a steady analysis and in Figure 2 for a transient analysis. Each step is described in more detail below.


Figure 1: Sequence of participant steps for a steady analysis


Figure 2: Sequence of participant steps for a transient analysis

As described in the introduction, co-simulation and mapping workflows can be combined. To perform mapping while doing the coupled analysis, an additional step, mapping setup, is required prior to heavyweight data access and initialization step. See details of the mapping setup step in Steps to Perform Mapping. Mapping will be performed during inputs update step, inside the coupled analysis loop.

Connect to System Coupling

The connection is established by providing the host name, port number, participant name, and build information.

If running in parallel using a supported MPI distribution, MPI communicator should also be provided. See Execution in a Parallel Environment for more details.

C++

std::string host, name, buildInfo;
unsigned short port;
...
sysc::SystemCoupling sc(host, port, name, buildInfo);

C

char host[STRING_MAX_SIZE];
unsigned short port;
char name[STRING_MAX_SIZE];
char buildInfo[STRING_MAX_SIZE];
...
SyscError ret = syscConnect(host, port, name, buildInfo);

Fortran

character(len=256) :: host
integer :: scPort = 0
character(len=256) :: name
character(len=256) :: buildInfo
...
ret = syscConnectF(scHost, scPort, scName, buildInfo)

Python

import pyExt.SystemCouplingParticipant as sysc
host = str()
port = int()
name = str()
buildInfo = str()
...
sc = sysc.SystemCoupling(host, port, name, buildInfo)

Register Heavyweight Data Access

Register access to the participant's mesh and variable values. Register any other callback functions (e.g. callback for creating restart point). In the examples below, getSurfaceMesh, getInputScalarData, and createRestartPoint are functions that conform to provided prototypes that are to be implemented in the participant solver. See Access to Heavyweight Data and Creating Restart Points and Restarting a Coupled Analysis for more details.

C++

sc.registerSurfaceMeshAccess(&getSurfaceMesh);
sc.registerInputScalarDataAccess(&getInputScalarData);
sc.registerRestartPointCreation(&createRestartPoint);

C

SyscError ret;
ret = syscRegisterSurfMeshAccess(&getSurfaceMesh);
ret = syscRegisterInputScalarDataAccess(&getInputScalarData);
ret = syscRegisterRestartPointCreation(&createRestartPoint);

Fortran

type(SyscErrorF) :: ret
ret = syscRegisterSurfMeshAccessF(getSurfaceMesh)
ret = syscRegisterInputScalarDataAccessF(getInputScalarData)
ret = syscRegisterRestartPointCreationF(createRestartPoint)

Python

sc.registerSurfaceMeshAccess(getSurfaceMesh)
sc.registerInputScalarDataAccess(getInputScalarData)
sc.registerRestartPointCreation(createRestartPoint)

Initialize the Coupled Analysis

Notify System Coupling that the analysis can be initialized.

C++

sc.initializeAnalysis();

C

SyscError ret = syscInitializeAnalysis();

Fortran

type(SyscErrorF) :: ret
ret = syscInitializeAnalysisF()

Python

sc.initializeAnalysis()

Coupled Analysis Loop

Enter a coupled analysis loop until the analysis is complete. This step is different, depending on whether the analysis is steady or transient.

  • For steady analysis, there is the coupling iteration loop. The participant should enter the coupling iteration loop and exit it only when there are no more coupling iterations to be done.
  • For transient analysis, there are two nested loops.
    • The outer loop is the coupling time step loop. The participant should enter the coupling time step loop and exit it only when there are no more coupling time steps to be done.
    • The inner loop is the coupling iteration loop. The participant should enter the coupling iteration loop and exit it only when there are no more coupling iterations to be done within the current coupling time step.

Inside the coupling iteration loop, the participant should iteratively update inputs, perform its solver iterations, and then update outputs.

  • Update Inputs. Notify System Coupling that inputs can be updated. After inputs update, the inputs are up-to-date for the current iteration. The participant solver can perform its solver iterations after inputs update.
  • Update Outputs. Notify System Coupling that outputs are updated and provide solver convergence status. Before outputs update, the participant must update all output data so that it can be consumed by System Coupling.

Steady Analysis Loop

C++

while (sc.doIteration()) {
sc.updateInputs();
// ... solve here ...
sc.updateOutputs(sysc::Converged);
}

C

SyscError ret;
...
while (syscDoIteration() == 1) {
ret = syscUpdateInputs();
/* ... solve here ... */
ret = sysc.updateOutputs(SyscConverged);
}

Fortran

type(SyscErrorF) :: ret
do while (syscDoIterationF())
ret = syscUpdateInputsF()
! ... solve here ...
ret = syscUpdateOutputsF(SyscConverged)
end do

Python

while sc.doIteration():
sc.updateInputs()
# ... solve here ...
sc.updateOutputs(sysc.Converged)

Transient Analysis Loop

C++

while (sc.doTimeStep()) {
while (sc.doIteration()) {
sc.updateInputs();
// ... solve here ...
sc.updateOutputs(sysc::Converged);
}
}

C

SyscError ret;
...
while (syscDoTimeStep() == 1) {
while (syscDoIteration() == 1) {
ret = syscUpdateInputs();
/* ... solve here ... */
ret = sysc.updateOutputs(SyscConverged);
}
}

Fortran

type(SyscErrorF) :: ret
do while (syscDoTimeStepF())
do while (syscDoIterationF())
ret = syscUpdateInputsF()
! ... solve here ...
ret = syscUpdateOutputsF(SyscConverged)
end do
end do

Python

while sc.doTimeStep():
while sc.doIteration():
sc.updateInputs()
# ... solve here ...
sc.updateOutputs(sysc.Converged)

Shutdown the Coupled Analysis

This step is reached after exiting from coupled analysis loop. System Coupling will be disconnected. The solver should proceed to an orderly shutdown after this step.

C++

sc.disconnect();

C

SyscError ret = syscDisconnect();

Fortran

type(SyscErrorF) :: ret
ret = syscDisconnectF()

Python

sc.disconnect()

Connect with Ansys