System Coupling Participant Library
System Coupling Participant Library
ANSYS, ANSYS Workbench, AUTODYN, CFX, FLUENT and any and all ANSYS, Inc. brand, product, service and feature
names, logos and slogans are registered trademarks or trademarks of ANSYS, Inc. or its subsidiaries located in the
United States or other countries. ICEM CFD is a trademark used by ANSYS, Inc. under license. CFX is a trademark
of Sony Corporation in Japan. All other brand, product, service and feature names or trademarks are the property
of their respective owners. FLEXlm and FLEXnet are trademarks of Flexera Software LLC.
Disclaimer Notice
THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFID-
ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.
ANSYS, Inc. and ANSYS Europe, Ltd. are UL registered ISO 9001: 2015 companies.
For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).
Third-Party Software
See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, contact ANSYS, Inc.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
System Coupling Participant Library
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv of ANSYS, Inc. and its subsidiaries and affiliates.
List of Figures
1. Sequence of participant steps for a steady analysis ..................................................................................... 5
2. Sequence of participant steps for a transient analysis ................................................................................. 6
3. Fluent geometry ...................................................................................................................................... 49
4. Mock solver geometry ............................................................................................................................. 50
5. Fluent temperature results after co-simulation with the mock solver ......................................................... 54
6. Structural solver geometry ...................................................................................................................... 58
7. Surface mesh in the damping solver ........................................................................................................ 59
8. Plot of plate tip x-displacements over time for different damping coefficients ........................................... 64
9. Comparison of results between the continuous and restarted runs ........................................................... 65
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. v
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
vi of ANSYS, Inc. and its subsidiaries and affiliates.
Introduction to the System Coupling Participant Library
The System Coupling Participant Library includes application programming interfaces (APIs) that allow
for the connection of solvers to System Coupling.
Note:
"System Coupling" refers to the current version of the System Coupling application, which
in previous releases was designated as "System Coupling 2.0."
Prerequisites
This documentation assumes that you've met the following prerequisites:
You're familiar with basic functionality available in System Coupling. Before you start working
with the System Coupling Participant Library, it is recommended that you first:
• Complete the following command-line tutorials from the Tutorials with Command-Line Interface (CLI)
Workflows page of the System Coupling Tutorials package:
• Ensure that you become familiar with System Coupling's data model and commands, as described in
the System Coupling Settings and Commands Reference.
You're a participant solver developer, with some programming experience in one of the suppor-
ted languages (p. 38) and the ability to modify the participant solver build process. These APIs
are intended to be connected with the participant solver inside the solver iteration loop, so you must
include the System Coupling Participant Library as a dependency.
Contents
For details on the System Coupling Participant Library's functionality and usage, see the following
documentation:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Participant Library Developer's Guide
System Coupling provides a co-simulation solver to perform multiphysics analyses. The System Coupling
Participant Library provides interfaces that allow coupling participant solvers to connect to the co-
simulation solver and to take part in the coupled analysis.
• Each coupling participant (also referred to as "participant," "participant solver," or "solver") is an instance
of a standalone application that provides a solution to one or more physical models.
• A coupled analysis is the process in which the coupled participants are executed in an iterative sequence
for the purpose of converging the overall coupled solution. A coupled analysis is controlled by the
System Coupling application, rather than the participants.
Participants declare which regions can be used in the coupled analysis. Each region can declare input
variables and output variables.
• Input variables represent physical quantities for which the participant expects System Coupling to
provide values.
• Output variables represent physical quantities for which System Coupling expects the participant to
provide values.
Note:
Once the participant solver is instrumented with System Coupling APIs, it can participate in a coupled
analysis with other coupled participants, taking advantage of all the functionality provided by System
Coupling.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
System Coupling Participant Library Developer's Guide
The connection is established by providing the host name, port number, and participant name.
Register access to the participant's mesh and variable values. Initialize the heavyweight data.
Notify System Coupling that the analysis can be initialized. After this step, additional data access
functions can no longer be registered.
Enter a coupled analysis loop until the analysis is complete. This step is different, depending on
whether the analysis is steady or transient.
• Steady analysis
For a 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.
• Transient analysis
– 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.
a. Inputs update
Notify System Coupling that inputs can be updated. After this step, the inputs are up-to-date
for the current solver iteration. The participant solver can perform its solver iterations after
the inputs update.
b. Outputs update
Notify System Coupling that outputs are updated and provide solver convergence status. Before
updating the outputs, the participant must update all output data so that it can be consumed
by System Coupling.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
Participant Steps in a Coupled Analysis
This step is reached after exiting from the coupled analysis loop. System Coupling will be discon-
nected. The solver should proceed to an orderly shutdown after this step.
This process is depicted in Figure 1: Sequence of participant steps for a steady analysis (p. 5) and Fig-
ure 2: Sequence of participant steps for a transient analysis (p. 6).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
System Coupling Participant Library Developer's Guide
It is recommended that you create a wrapper script (either batch script, shell script, or any other kind
of script) around the actual solver executable. This script can parse the arguments provided by System
Coupling and set any environment variables, as needed.
--schost HOSTNAME
Name of the host where System Coupling is running. This value should be passed in as input into the
participant library function that establishes the connection with System Coupling.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
Command Line Arguments for Participant Solvers
--scport PORTNUMBER
Port number on which System Coupling is listening for incoming connections from the participant
solvers. This value should be passed in as input into the participant library function that establishes the
connection with System Coupling.
--scname PARTICIPANTNAME
Unique name for this participant, given by System Coupling. This value should be passed in as input into
the participant library function that establishes the connection with System Coupling.
--screstart RESTART_STRING
This command-line argument is used only during a restart run. The provided string is used to tell the
participant solver which restart point to use. During a previous run, the participant solver provided this
string to System Coupling. For details, see Creating Restart Points and Restarting a Coupled Analys-
is (p. 25).
-np NPROCS
Here, NPROCS is replaced with the number of processes. For example, if the participant solver is to
be executed on local machine using four processes, the command line argument will be as follows:
-np 4
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
System Coupling Participant Library Developer's Guide
-hostlist HOSTLIST
Here, HOSTLIST is replaced with the comma-separated list of machines and number of cores available
on that machine. For example, if there are two machines available named hostA and hostB, and
each machine has four cores available, then the command line argument will be as follows:
-hostlist hostA:4,hostB:4
participant = DatamodelRoot().CouplingParticipant['DEFAULT-1']
participant.ExecutionControl.AdditionalArguments = '--input input.file'
For more information on the data model structure, see the System Coupling User's Guide.
The participant library uses Fluent's MPI wrapper library for run-time switching between the compatible
MPI distributions. For a full list of available MPIs for the Windows and Linux platforms, see the Fluent
product documentation. The participant library is expected to be compatible with those MPIs.
The second part of the Heat Transfer in Square Channel Air Flow (p. 47) tutorial demonstrates the usage
of the parallel APIs.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
Execution in a Parallel Environment
The following sections provide examples of using the participant library to implement interfaces
in parallel:
C++
...
// initialize the MPI
MPI_Init(&argc, &argv);
...
std::string scHost, scname, buildInfo;
unsigned short int scPort;
...
// pass the MPI communicator when connecting to System Coupling
sysc::SystemCoupling sc(scHost, scPort, scName, MPI_COMM_WORLD, buildInfo));
...
...
/* initialize the MPI */
MPI_Init(&argc, &argv);
...
const char* scHost, scName, buildInfo;
unsigned short int scPort;
...
/* pass the MPI communicator when connecting to System Coupling */
syscConnectParallel(scHost, scPort, scName, MPI_COMM_WORLD, buildInfo);
...
Fortran
...
integer :: err_code
character(len=256) :: scHost
integer :: scPort
character(len=256) :: scName
character(len=256) :: buildInfo
...
! initialize the MPI
call MPI_Init(err_code)
...
! pass the MPI communicator when connecting to System Coupling
syscConnectF(scHost, scPort, scName, MPI_COMM_WORLD, buildInfo)
...
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
System Coupling Participant Library Developer's Guide
This will link to the MPI wrapper library in that directory (mpi_wrapper.dll on Windows and
libmpi_wrapper.so on Linux).
If, for example, the IBM MPI library is used, then the ibmmpi directory should be used instead of
intel in the path above.
For examples of compiling, linking, and executing a program that uses the participant library and
a supported MPI, see Compiling, Linking, and Executing Applications That Use the Participant Lib-
rary (p. 37).
For more detailed examples, see Compiling, Linking, and Executing Applications That Use the Participant
Library (p. 37).
The setup file should be generated during the participant solver setup and prior to starting System
Coupling.
The participant library provides a utility to create the setup files via a function called writeSetupFile
so that the library can be used during the setup stage, as well as during the coupled analysis stage.
The following sections provide examples of using the participant library to create the setup files:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating System Coupling Participant Setup Files Using the Participant Library
C++
In C++, create a sysc::SystemCoupling instance and provide an empty host name.
After the completeCouplingSetup method is called, the setup file can be created using the
writeSetupFile method, which that takes in the sysc::SetupFileInfo structure.
C
In C, start standalone mode by passing an empty host name to the syscConnect function.
After the syscCompleteCouplingSetup function is called, the setup file can be created using the
syscWriteSetupFile function, which takes in the SyscSetupFileInfo structure.
region.name = "region";
region.topology = SyscSurface;
ret = syscAddRegion(region);
SyscVariable variable;
variable.name = "variable";
variable.quantityType = SyscTemperature;
variable.location = SyscNode;
ret = syscAddInputVariable(region, variable);
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 11
System Coupling Participant Library Developer's Guide
Fortran
In Fortran, start standalone mode by passing an empty host name to the syscConnectF function.
After the syscCompleteCouplingSetupF function is called, the setup file can be created using
the syscWriteSetupFileF function, which takes in the SyscSetupFileInfoF type.
type(SyscErrorF) :: ret
type(SyscSetupFileInfoF) :: setupFileInfo
type(SyscRegionF) :: region
type(SyscVariableF) :: variable
logical :: isWritten
setupFileInfo%setupFileName = "example.scp"
region%regionName = "FSIN_1"
region%topology = SyscSurface
variable%variableName = "TEMP"
variable%quantityType = SyscTemperature
variable%location = SyscNode
ret = syscAddRegionF(region)
ret = syscAddOutputVariableF(region, variable)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
12 of ANSYS, Inc. and its subsidiaries and affiliates.
Access to Heavyweight Data
Relevant Concepts
Input data
Input data is for input variables provided to the participant by System Coupling. The participant library
needs to have read and write access to this data.
Output data
Output data is for output variables provided to System Coupling by the participant, including mesh
data. The participant library needs to have read-only access to this data.
Scalar
Scalar data has one component. Temperature values are an example of scalar data.
Vector
Vector data has three components. Nodal coordinates values are an example of vector data.
Scalar Arrays
• C/C++ double
• FORTRAN real(kind=8)
• C/C++ float
• FORTRAN real(kind=4)
• C/C++ int
• FORTRAN integer(kind=4)
• FORTRAN integer(kind=8)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 13
System Coupling Participant Library Developer's Guide
Vector Arrays
32-bit floating point arrays (for vector variable field values and for mesh node coordinates)
• C/C++ float
• FORTRAN real(kind=4)
64-bit floating point arrays (for vector variable field values and for mesh node coordinates)
• C/C++ double
• FORTRAN real(kind=8)
Compact layout
Split layout
Note:
• If vector data is stored in a single array where the vector components are separated (e.g.,
[x0, x1, ..., y0, y1, ..., z0, z1, zN]), then it can be handled as a special
case of split layout.
• If vector data is stored in a two-dimensional array, then it can be handled as a special case
of one of the above layouts.
If the participant solver stores heavyweight data in a format compatible with the participant library,
then this reduces the need to make unnecessary copies of the data and thus improves memory effi-
ciency during the coupled analysis. The participant solver should implement and register data access
functions that provide direct access to that heavyweight data.
If the data is stored in a format that is not directly compatible with the participant library, then the
participant solver should create compatible heavyweight data structures and register data access
functions that provide access to that heavyweight data. In such a case, the participant solver should
make sure that this heavyweight data and the original data are synchronized at certain steps during
the coupled analysis (p. 4):
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
14 of ANSYS, Inc. and its subsidiaries and affiliates.
Access to Heavyweight Data
• Before the coupled analysis initialization is entered, the heavyweight input and output data are
expected to be available. Output data, including the mesh data, should contain valid initial values.
• After the inputs update completes, all input variable values will be up-to-date in the heavyweight
data. The participant should make sure that the latest input values are available in the original data
structures before doing solver iterations
• Before the outputs update is entered, the participant should make sure that the heavyweight data
contains the updated values for all the output variables, as well as for the mesh.
• OutputScalarData
• OutputVectorData
• InputScalarData
• InputVectorData
• SurfaceMesh
The SurfaceMesh data access structure groups the following set of output data objects that
describe surface mesh:
These structures require three pieces of information during their initialization (depending on the
target language, some of this information is deduced automatically and does not need to be explicitly
specified):
1. Primitive type of data (e.g., float, double, unsigned 16-bit integer, etc.)
The following examples show how to create data access structures to provide access to heavyweight
data to the participant library:
Scalar Data Structure Examples
Vector Data Structure Examples
Other Data Structure Examples
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 15
System Coupling Participant Library Developer's Guide
C++
// heavyweight array(s)
double temperature[] = { 1.0, 2.0, 3.0, 4.0 };
std::size_t numScalars = 4;
/* heavyweight array(s) */
double temperature[] = { 1.0, 2.0, 3.0, 4.0 };
size_t numScalars = 4;
Fortran
! heavyweight array(s)
real(kind=8), target :: temperature(4) = (/ 1.0, 2.0, 3.0, 4.0 /)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
16 of ANSYS, Inc. and its subsidiaries and affiliates.
Access to Heavyweight Data
C++
// heavyweight array(s)
float heatflow[] = { 1.0, 2.0, 3.0, 4.0 };
std::size_t numScalars = 4;
/* heavyweight array(s) */
float heatflow[] = { 1.0, 2.0, 3.0, 4.0 };
size_t numScalars = 4;
Fortran
! heavyweight array(s)
real(kind=4), target :: heatflow(4) = (/ 1.0, 2.0, 3.0, 4.0 /)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 17
System Coupling Participant Library Developer's Guide
Note that the size provided is 10 — there are 10 vectors, each with 3 components. So, the total
size of the array in memory is 30, but the size passed in here must be 10, not 30.
C++
// heavyweight array(s)
double displacement[] = { 0, 0, 0, 0.25, 0, 0, 0.5, 0, 0, 0.75, 0, 0, 1, 0, 0, 0, 0.1, 0, 0.25, 0.1,
0, 0.5, 0.1, 0, 0.75, 0.1, 0, 1, 0.1, 0 };
std::size_t numVectors = 10;
/* heavyweight array(s) */
double displacement[] = { 0, 0, 0, 0.25, 0, 0, 0.5, 0, 0, 0.75, 0, 0, 1, 0, 0, 0, 0.1, 0, 0.25, 0.1,
0, 0.5, 0.1, 0, 0.75, 0.1, 0, 1, 0.1, 0 };
size_t numVectors = 10;
Fortran
! heavyweight array(s)
real(kind=8), target :: displacement(30) = (/ 0D0, 0D0, 0D0, 0.25D0, 0D0, 0D0, 0.5D0, 0D0, 0D0, 0.75D0, 0D0, 0
integer(kind=8) :: numVectors = 10
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
18 of ANSYS, Inc. and its subsidiaries and affiliates.
Access to Heavyweight Data
Note that the size provided is 2 — there are 2 vectors, each with 3 components.
C++
// heavyweight array(s)
const std::size_t numVectors = 2;
const std::size_t numComponents = 3;
float force[numVectors][numComponents] = {{0.0, 0.0, 0.0}, {1.0, 1.0, 1.0}};
/* heavyweight array(s) */
#define NUMVECTORS 2
#define NUMCOMPONENTS 3
float force[NUMVECTORS][NUMCOMPONENTS] = {{0.0, 0.0, 0.0}, {1.0, 1.0, 1.0}};
Fortran
Note that Fortran stores data in column-major order, so a compactly stored two-dimensional array
has component as the first index and vector as the second index.
! heavyweight array(s)
integer(kind=8), parameter :: numVectors = 2
integer(kind=4), parameter :: numComponents = 3
real(kind=4), target :: force(numComponents, numVectors)
force(1, 1) = 0D0
force(2, 1) = 0D0
force(3, 1) = 0D0
force(1, 2) = 1D0
force(2, 2) = 1D0
force(3, 2) = 1D0
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 19
System Coupling Participant Library Developer's Guide
Note that the size provided is 4 — there are 4 vectors, each with 3 components.
C++
// heavyweight array(s)
double dx[] = { 1.0, 2.0, 3.0, 4.0 };
double dy[] = { 1.0, 2.0, 3.0, 4.0 };
double dz[] = { 1.0, 2.0, 3.0, 4.0 };
std::size_t numVectors = 4;
/* heavyweight array(s) */
double dx[] = { 1.0, 2.0, 3.0, 4.0 };
double dy[] = { 1.0, 2.0, 3.0, 4.0 };
double dz[] = { 1.0, 2.0, 3.0, 4.0 };
size_t numVectors = 4;
Fortran
! heavyweight array(s)
integer(kind=8), parameter :: numVectors = 4
real(kind=8), target :: dx(numVectors) = (/ 1.0, 2.0, 3.0, 4.0 /)
real(kind=8), target :: dy(numVectors) = (/ 1.0, 2.0, 3.0, 4.0 /)
real(kind=8), target :: dz(numVectors) = (/ 1.0, 2.0, 3.0, 4.0 /)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
20 of ANSYS, Inc. and its subsidiaries and affiliates.
Access to Heavyweight Data
Note that the size provided is 2 — there are 2 vectors, each with 3 components.
C++
// heavyweight array(s)
const std::size_t numVectors = 2;
const std::size_t numComponents = 3;
double coords[numComponents][numVectors] = {{0.0, 1.0}, {0.0, 1.0}, {0.0, 1.0}};
/* heavyweight array(s) */
#define NUMVECTORS 2
#define NUMCOMPONENTS 3
double coords[NUMCOMPONENTS][NUMVECTORS] = {{0.0, 1.0}, {0.0, 1.0}, {0.0, 1.0}};
Fortran
Note that Fortran stores data in column-major order, so a non-compactly stored two-dimensional
array has the vector as the first index and the vector component as the second index.
! heavyweight array(s)
integer(kind=8), parameter :: numVectors = 2
integer(kind=4), parameter :: numComponents = 3
real(kind=8), target :: coords(numVectors, numComponents)
coords(1, 1) = 0D0
coords(1, 2) = 0D0
coords(1, 3) = 0D0
coords(2, 1) = 1D0
coords(2, 2) = 1D0
coords(2, 3) = 1D0
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 21
System Coupling Participant Library Developer's Guide
Note that the size provided is 2 — there are 2 vectors, each with 3 components.
C++
// heavyweight array(s)
double force[] = {0.0, 1.0, 0.0, 1.0, 0.0, 1.0};
std::size_t numVectors = 2;
/* heavyweight array(s) */
double force[] = {0.0, 1.0, 0.0, 1.0, 0.0, 1.0};
size_t numVectors = 2;
Fortran
! requires iso_c_binding
use iso_c_binding
! heavyweight array(s)
integer(kind=8) :: numVectors = 2
real(kind=8), target :: force(6) = (/ 0D0, 1D0, 0D0, 1D0, 0D0, 1D0 /)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
22 of ANSYS, Inc. and its subsidiaries and affiliates.
Access to Heavyweight Data
C++
// heavyweight array(s)
std::size_t numNodes = 4;
std::size_t numElems = 1;
std::size_t numElemNodeIds = 4;
long long int nodeIds[] = { 1, 2, 3, 4 };
double x[] = { 0, 1, 1, 0 };
double y[] = { 0, 0, 1, 1 };
double z[] = { 0, 0, 0, 0 };
std::vector<unsigned short int> elemNodeCounts(numElems, 4);
long long int elemNodeIds[] = { 1, 2, 3, 4 };
/* heavyweight array(s) */
size_t numNodes = 4;
size_t numElems = 1;
size_t numElemNodeIds = 4;
long long int nodeIds[] = { 1, 2, 3, 4 };
double x[] = { 0, 1, 1, 0 };
double y[] = { 0, 0, 1, 1 };
double z[] = { 0, 0, 0, 0 };
unsigned short int elemNodeCounts[] = { 4 };
long long int elemNodeIds[] = { 1, 2, 3, 4 };
SyscOutputVectorData nodeCoordsData;
nodeCoordsData.primitiveType = SyscDouble;
nodeCoordsData.data0 = x;
nodeCoordsData.data1 = y;
nodeCoordsData.data2 = z;
nodeCoordsData.size = numNodes;
SyscOutputScalarData elemNodeCountsData;
elemNodeCountsData.primitiveType = SyscUnsignedInt16;
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 23
System Coupling Participant Library Developer's Guide
elemNodeCountsData.data = elemNodeCounts;
elemNodeCountsData.size = numElems;
SyscOutputScalarData elemNodeIdsData;
elemNodeIdsData.primitiveType = SyscInt64;
elemNodeIdsData.data = elemNodeIds;
elemNodeIdsData.size = numElemNodeIds;
Fortran
Note that for Fortran, one can make use of the helper functions syscGetOutputScalarDataF
and syscGetOutputVectorDataSplitF as shown below.
! heavyweight array(s)
integer(kind=8), target :: nodeIds(4) = (/ 1, 2, 3, 4 /)
real(kind=8), target :: x(4) = (/ 0, 1, 1, 0 /)
real(kind=8), target :: y(4) = (/ 0, 0, 1, 1 /)
real(kind=8), target :: z(4) = (/ 0, 0, 0, 0 /)
integer(kind=4), target :: elemNodeCounts(1) = (/ 4 /)
integer(kind=8), target :: elemNodeIds(4) = (/ 1, 2, 3, 4 /)
nodeIdsData = syscGetOutputScalarDataF(nodeIds)
nodeCoordsData = syscGetOutputVectorDataSplitF(x, y, z)
elemNodeCountsData = syscGetOutputScalarDataF(elemNodeCounts)
elemNodeIdsData = syscGetOutputScalarDataF(elemNodeIds)
To provide access to this array, create the InputScalarData structure as shown below.
Note that the size does not need to be provided because it can be automatically deduced from
the STL vector size.
C++
// heavyweight array(s)
std::size_t numScalars = 15;
std::vector<double> coords(numScalars, 0.0);
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
24 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating Restart Points and Restarting a Coupled Analysis
• Function to access input scalar variable data (input scalar variable access)
• Function to access input vector variable data (input vector variable access)
• Function to access output scalar variable data (output scalar variable access)
• Function to access output vector variable data (output vector variable access)
There is no need to implement and register functions that will not be used. For example, if there are
no scalar output variables, there is no need to implement and register a function for output scalar
variable access.
For information on how to implement data access functions, see Heat Transfer in Square Channel Air
Flow Tutorial (p. 47).
C++
Data access function prototypes are defined in the following header file:
• SystemCouplingParticipant/FunctionTypes.hpp
C
Data access function prototypes are defined in the following header file:
• syscDataAccess.h
Fortran
Data access function interfaces are defined in the following header file (located either in the Fortran-
FreeForm or the FortranFixedForm subdirectory, depending on the desired Fortran layout):
• syscDataAccessF.fi
The System Coupling Participant Library provides the APIs needed to create restart points. For more
information, see:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 25
System Coupling Participant Library Developer's Guide
When using the participant library to create the setup file, the restartsSupported flag can be
set in the Setup File Info structure. Once that structure is created, the setup file can be written. For
details, see Creating System Coupling Participant Setup Files Using the Participant Library (p. 10).
C++
Fortran
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
26 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating Restart Points and Restarting a Coupled Analysis
C++
...
// sample implementation of the restart callback function
std::string createRestartPoint()
{
std::string restartPoint;
... // solver-specific implementation, sets string value
return restartPoint;
}
...
// System Coupling object
sysc::SystemCoupling sc(host, port, name);
...
// register restart point creation callback
sc.registerSurfaceMeshAccess(&createRestartPoint);
...
...
/* sample implementation of the restart callback function */
const char* createRestartPoint()
{
char* restartPoint;
/* solver-specific implementation, sets string value */
...
return restartPoint;
}
...
/* register restart point creation callback */
syscRegisterRestartPointCreation(&createRestartPoint);
...
Fortran
...
! sample implementation of the restart callback function
function createRestartPoint() result(restartPoint)
character(len=SyscFilePathLen) :: restartPoint
! solver-specific implementation, sets string value
...
end function createRestartPoint
...
! register restart point creation callback
syscRegisterRestartPointCreationF(createRestartPoint)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 27
System Coupling Participant Library Developer's Guide
--screstart RESTART_STRING
The participant solver is expected to resume the analysis from the state it was in when the restart
point was created. The participant steps in a coupled analysis are the same as for the initial run. For
details, see Participant Steps in a Coupled Analysis (p. 4).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
28 of ANSYS, Inc. and its subsidiaries and affiliates.
Multi-Region Coupling Interfaces
System Coupling will detect a shared node by its node id. For example, if node A is given an id of 4
when defining the mesh for Region L and the same id of 4 when defining mesh for the Region R,
then System Coupling will interpret the node A as shared between the two regions. To further illustrate
this example, surface mesh arrays for both regions are shown in Example 2: Mesh arrays for the case
with shared nodes (p. 30).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 29
System Coupling Participant Library Developer's Guide
As shown in Example 2: Mesh arrays for the case with shared nodes (p. 30), nodes with ids 3 and 4
are repeated in the definitions of both regions. From the above example, it is obvious that some re-
dundant information is provided for shared nodes — node coordinates are provided multiple times,
once for each shared node for each region. For a given shared node, System Coupling will use only
one set of coordinates (from one of the regions) and will disregard all others. Therefore, it is critical
that nodal coordinates for shared nodes are identical.
To contrast the case with shared nodes and the case without shared nodes, compare Example 2: Mesh
arrays for the case with shared nodes (p. 30) to Example 3: Mesh arrays for the case with non-shared
nodes (p. 31). The latter example shows the case without shared nodes. Note that this is a different
setup and may result in a different solution.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
30 of ANSYS, Inc. and its subsidiaries and affiliates.
Multi-Region Coupling Interfaces
Finally, these two regions can be agglomerated into a single region, as shown in Example 4: Mesh
arrays for the case where regions are agglomerated into one (p. 32). If the two regions above are to
be used in a single coupling interface, then agglomeration is preferred but not necessary.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 31
System Coupling Participant Library Developer's Guide
Example 4: Mesh arrays for the case where regions are agglomerated into one
Values for conservative variables are accumulated on shared nodes by System Coupling. Example 5: Nod-
al conservative variable (heat rate) values for the multi-region case with shared nodes (p. 33) shows
an example of a conservative nodal variable (heat rate) for two regions, where each region consists
of one quadrilateral mesh face (see previous section for how to define the mesh for this example).
Nodes A and B are shared between these two regions.
Note that in Region L, nodes A and B each have heat rate value of 2 Watts. In Region R, nodes A
and B each have heat rate values of 3 Watts. Since heat rate is a conservative variable, the values on
shared nodes will be accumulated. Therefore, when both regions are taken together, the shared nodes
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
32 of ANSYS, Inc. and its subsidiaries and affiliates.
Multi-Region Coupling Interfaces
A and B will each have heat rate value of 5 Watts. The sum of heat rate values for both regions in
this example is 30 Watts.
Example 5: Nodal conservative variable (heat rate) values for the multi-region case with shared
nodes
Values for profile-preserving variables should be identical on shared nodes. Example 6: Nodal profile-
preserving variable (temperature) values for the multi-region case with shared nodes (p. 34) shows
an example of profile-preserving nodal variable (temperature) for the same two regions as in the
previous example. Note that shared nodes A and B each have identical temperature values in both
Region L and Region R. To get the average temperature on these two regions, the sum of temperature
nodal values is divided by the number of unique nodes. In this example, the average temperature is
(500 + 300 + 800 + 600 + 500 + 300) / 6 = 500 [K].
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 33
System Coupling Participant Library Developer's Guide
Example 6: Nodal profile-preserving variable (temperature) values for the multi-region case
with shared nodes
Note:
Sometimes, variable values on shared nodes can differ. For example, a shared node can
exist between a region that represents fluid flow inlet and a region that represents a non-
slip wall. In this situation, fluid flow velocity on the inlet node could be non-zero, but on
the wall node the velocity will be zero. However, in these situations, one would not want
to include both these regions in one coupling interface. If multiple regions with shared
nodes are included in one coupling interface, then the profile-preserving variable values
on those shared nodes should be identical.
Debugging Tools
The participant library includes the following tools to help with debugging:
Standalone Mode
Mesh Validity Check
Standalone Mode
Once the APIs are implemented, you can use the standalone mode to run the participant solver
without connecting to System Coupling. When running in standalone mode, the participant solver
will run for a few coupling time steps (if transient) and coupling iterations. At each iteration, it will
call all registered data access functions and print the contents of heavyweight data into a text file.
The standalone mode allows you to check for run-time issues more quickly and can help to provide
a measure of confidence that the APIs are implemented correctly. Before running a solver as part of
an overall coupled analysis, you should first confirm that the participant solver can run successfully
in standalone mode.
To run in standalone mode, provide an empty host name when the connection to System Coupling
would be typically established. No other changes are required to run in standalone mode. For a
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
34 of ANSYS, Inc. and its subsidiaries and affiliates.
Debugging Tools
demonstration of how to run a participant solver in standalone mode, see Heat Transfer in Square
Channel Air Flow Tutorial (p. 47).
C++
Fortran
character(len=256) :: scHost
integer :: scPort = 0
character(len=256) :: partName
...
scHost = ""
ret = syscConnectF(scHost, scPort, partName)
For example, it will check to verify that array sizes are consistent — that the element node ids array
contains only ids that are found in the node ids array, etc.
Note:
• This is not an exhaustive validity check — the mesh can still have problems even if all checks
pass. However, it can provide a measure of confidence that the mesh being provided to System
Coupling is correct.
• To ensure optimal performance, this function should not be called in production workflows.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 35
System Coupling Participant Library Developer's Guide
C++
sysc::SystemCoupling sc(...);
sysc::Region region(...);
...
sysc::MeshValidityStatus meshStatus = sc.checkMeshValidity(region);
if (meshStatus.isInvalid) {
std::cout << meshStatus.message;
}
SyscRegion region;
...
SyscError ret = syscCheckMeshValidity(region);
if (ret.retcode != 0) {
printf(ret.message);
}
Fortran
type(SyscRegionF) :: region
type(SyscErrorF) :: ret
...
ret = syscCheckMeshValidityF(region)
if (ret%retcode .NE. SyscStatusOk) then
print *, trim(ret%message)
endif
Migration Guide
The information in this section is provided to help migrate the System Coupling APIs implementation
between the releases.
Setup APIs
The APIs that are related to setup (e.g. add region, add input/output variable, complete coupling
setup) should no longer be used during the coupled analysis. These APIs will remain available and
can be used to generate the setup (SCP) files during the setup stage.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
36 of ANSYS, Inc. and its subsidiaries and affiliates.
Compiling, Linking, and Executing Applications That Use the Participant Library
For information on creating the setup files, see Creating System Coupling Participant Setup Files Using
the Participant Library (p. 10).
For the most up-to-date information on the steps in a coupled analysis, see Participant Steps in a
Coupled Analysis (p. 4).
// LEGACY PROTOTYPE:
sysc::SurfaceMesh getSurfaceMesh(const sysc::Region& region);
// NEW PROTOTYPE:
sysc::SurfaceMesh getSurfaceMesh(const std::string& regionName);
• syscGetInputScalarDataF
• syscGetOutputScalarDataF
• syscGetInputVectorDataSplitF
• syscGetInputVectorDataCompactF
• syscGetOutputVectorDataSplitF
• syscGetOutputVectorDataCompactF
For the most up-to-date information on the usage of these helper functions, see Access to Heavyweight
Data (p. 12).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 37
System Coupling Participant Library Developer's Guide
Supported Languages
System Coupling interfaces are provided for the following target languages:
Language Standard
C++ C++11 or later
C C89 or later
Fortran 2003 or later (both fixed-form and free-form)
• <ANSYSInstallationPath>/SystemCoupling/runTime/<platform>/include/Sys-
temCouplingParticipant
Note:
All public header files for the C++, C, and Fortran interfaces are located in the above
directory. Both fixed and free form headers are available for Fortran codes.
Link-Time Dependencies
Windows
• ANSYSInstallationPath>/SystemCoupling/runTime/<platform>/lib/SysC.Sys-
temCouplingParticipantParticipant.lib
– SysC.SystemCouplingParticipantParticipant.lib
• <ANSYSInstallationPath>/SystemCoupling/runTime/<platform>/cnlauncher/flu-
ent/fluent<MultiportVersion>/multiport/mpi_wrapper/<platform>/<mpi>
– mpi_wrapper.lib
Linux
• <ANSYSInstallationPath>/System Coupling/runTime/<platform>/bin
– SysC.SystemCouplingParticipant.so
• <ANSYSInstallationPath>/SystemCoupling/runTime/<platform>/cnlauncher/flu-
ent/fluent<MultiportVersion>/multiport/mpi_wrapper/<platform>/<mpi>
– libmpi_wrapper.so
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
38 of ANSYS, Inc. and its subsidiaries and affiliates.
Compiling, Linking, and Executing Applications That Use the Participant Library
Run-Time Dependencies
• <ANSYSInstallationPath>/System Coupling/runTime/<platform>/bin
– SysC.SystemCouplingParticipant.dll (Windows)
– SysC.SystemCouplingParticipant.so (Linux)
• <ANSYSInstallationPath>/System Coupling/runTime/<platform>/bin/compiler
• <ANSYSInstallationPath>/SystemCoupling/runTime/<platform>/cnlauncher/flu-
ent/fluent<MultiportVersion>/multiport/mpi_wrapper/<platform>/<mpi>
If not using a supported MPI distribution (this includes not using MPI at all), stub MPI wrapper
should be used (replace <mpi> with "stub" above).
The above directories must be included in the PATH environment variable (on Windows) or
LD_LIBRARY_PATH environment variable (on Linux) at run-time.
Examples
In the following examples, mock solver applications from the Heat Transfer in Square Channel Air
Flow (p. 47) tutorial are built with different configurations. These examples can be used as a reference
when building more complex applications. The actual build steps depend on your system configuration,
compilers, and other details. The source code for these applications is provided with the System
Coupling Participant Library tutorial package.
The following compiler and MPI versions are used in the examples:
Linux
Windows
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 39
System Coupling Participant Library Developer's Guide
The following sections provide examples for Linux (p. 40) and Windows (p. 43).
Linux Examples
The following Linux examples are available:
• C (p. 40)
• ???
• ???
• ???
• ???
• Executing Parallel Version in Standalone Mode Using Intel MPI (p. 43)
C++
Fortran
GNU Fortran Compiler
gfortran -I<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/include/
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
40 of ANSYS, Inc. and its subsidiaries and affiliates.
Compiling, Linking, and Executing Applications That Use the Participant Library
SystemCouplingParticipant/FortranFixedForm -L<ANSYSInstallationPath>/SystemCoupling/
runTime/linx64/bin -L<ANSYSInstallationPath> /SystemCoupling/runTime/linx64/
cnlauncher/fluent/fluent<MultiportVersion>/multiport/mpi_wrapper/lnamd64/stub
-o ChannelFlowMockSolver ChannelFlowMockSolver.f -lSysC.SystemCouplingParticipantFortran
-lmpi_wrapper
ifort -I<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/include/
SystemCouplingParticipant/FortranFixedForm -I<IntelMPIPath>/intel64/include
-L<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/bin -L<IntelMPIPath>/intel64/lib
-L<IntelMPIPath>/intel64/lib/release -L<ANSYSInstallationPath>/SystemCoupling/runTime/
linx64/cnlauncher/fluent/fluent<MultiportVersion>/multiport/mpi_wrapper/lnamd64/stub
-o ChannelFlowMockSolverMPI ChannelFlowMockSolverMPI.f -lSysC.SystemCouplingParticipantFortran
-lmpifort lmpi -lmpi_wrapper -lgfortran
gfortran -I<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/include/
SystemCouplingParticipant/FortranFixedForm -I<IntelMPIPath>/intel64/include -L<ANSYSInstallationPath>/
SystemCoupling/runTime/linx64/bin -L<IntelMPIPath>/intel64/lib -L<IntelMPIPath>/intel64/lib/release
-L<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/cnlauncher/fluent/fluent<MultiportVersion>/
multiport/mpi_wrapper/lnamd64/stub -o ChannelFlowMockSolverMPI ChannelFlowMockSolverMPI.f
-lSysC.SystemCouplingParticipantFortran -lmpifort -lmpi -lmpi_wrapper
ifort -I<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/include/SystemCouplingParticipant/
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 41
System Coupling Participant Library Developer's Guide
#include "mpif.h"
The C preprocessor must be used. The GNU Fortran compiler option for this is -cpp.
• <ANSYSInstallationPath>/SystemCoupling/runTime/linx64/bin
• <ANSYSInstallationPath>/SystemCoupling/runTime/linx64/bin/compiler
• <ANSYSInstallationPath>/SystemCoupling/runTime/linx64/cnlauncher/flu-
ent/fluent<MultiportVersion>/multiport/mpi_wrapper/lnamd64/stub
./ChannelFlowMockSolver --scname="test"
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
42 of ANSYS, Inc. and its subsidiaries and affiliates.
Compiling, Linking, and Executing Applications That Use the Participant Library
• <ANSYSInstallationPath>/SystemCoupling/runTime/linx64/bin
• <ANSYSInstallationPath>/SystemCoupling/runTime/linx64/bin/compiler
• <ANSYSInstallationPath>/SystemCoupling/runTime/linx64/cnlauncher/flu-
ent/fluent<MultiportVersion>/multiport/mpi_wrapper/lnamd64/intel
2. Now, execute the program in standalone mode locally using two processes:
Windows Examples
The following Linux examples are available:
• C (p. 43)
• Executing Parallel Version in Standalone Mode Using Intel MPI (p. 45)
C++
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 43
System Coupling Participant Library Developer's Guide
Fortran
ifort -I"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\include\SystemCouplingParticipant\
FortranFixedForm" /FeChannelFlowMockSolver.exe ChannelFlowMockSolver.f /link /subsystem:console
/LIBPATH:"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\lib"
SysC.SystemCouplingParticipantFortran.lib
ifort -I"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\include\SystemCouplingParticipant\
FortranFixedForm" -I"<IntelMPIPath>\intel64\include" /FeChannelFlowMockSolverMPI.exe
ChannelFlowMockSolverMPI.f /link /subsystem:console /LIBPATH:"<ANSYSInstallationPath>\SystemCoupling\
runTime\winx64\lib" SysC.SystemCouplingParticipantFortran.lib /LIBPATH:"<IntelMPIPath>\intel64\lib"
impi.lib
cl /EHsc /I"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\include"
/I"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\cnlauncher\fluent\
fluent<MultiportVersion>\multiport\mpi_wrapper\include" ChannelFlowMockSolverMPI.cpp
/FeChannelFlowMockSolverMPI.exe /link /subsystem:console /LIBPATH:"<ANSYSInstallationPath>\
SystemCoupling\runTime\winx64\lib" SysC.SystemCouplingParticipant.lib
/LIBPATH:"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\cnlauncher\fluent\
fluent<MultiportVersion>\multiport\mpi_wrapper\win64\stub" mpi_wrapper.lib
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
44 of ANSYS, Inc. and its subsidiaries and affiliates.
Compiling, Linking, and Executing Applications That Use the Participant Library
#include "mpif.h"
The C preprocessor must be used. The Intel Fortran compiler option for this is -fpp.
• <ANSYSInstallationPath>\SystemCoupling\runTime\winx64\bin
• <ANSYSInstallationPath>\SystemCoupling\runTime\winx64\bin\compiler
• <ANSYSInstallationPath>\SystemCoupling\runTime\winx64\cnlauncher\flu-
ent\fluent<MultiportVersion>\multiport\mpi_wrapper\win64\intel
ChannelFlowMockSolver.exe --scname="test"
• <ANSYSInstallationPath>\SystemCoupling\runTime\winx64\bin
• <ANSYSInstallationPath>\SystemCoupling\runTime\winx64\bin\compiler
• <ANSYSInstallationPath>\SystemCoupling\runTime\winx64\cnlauncher\flu-
ent\fluent<MultiportVersion>\multiport\mpi_wrapper\win64\intel
2. Now, execute the program in standalone mode locally using two processes:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 45
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
46 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Participant Library Tutorials
The following tutorials demonstrate how to implement the APIs provided by the System Coupling Par-
ticipant Library:
Heat Transfer in Square Channel Air Flow Tutorial
Transient Oscillating Plate Damping Tutorial
The latter part of the tutorial demonstrates the use of parallel interfaces. The mock solver code is
modified to be executed within the MPI environment.
Topics covered:
• Steady analysis
• Parallel execution
Verify Prerequisites
Ensure that the following prerequisites are met. You've installed:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 47
System Coupling Participant Library Tutorials
Fluent Setup
The Fluent setup involves the flow of air through a rectangular 1-meter-long channel with a square
0.1 by 0.1 [m] cross-section. The geometry is discretized using tetrahedral mesh, as shown in Fig-
ure 3: Fluent geometry (p. 49).
• The inlet is the surface coincident with the YZ plane, with a velocity of 0.1 m/s. Temperature of the
air is 273.15 [K] (0 [C])
• The outlet is the side opposite from the inlet, with 0 Pa gauge pressure.
• The region participating in the coupled analysis is the surface coincident with the XY plane. This
makes the System Coupling interface region a rectangle extending from origin to point (1, 0.1, 0).
• The case is set up to perform five Fluent solver iterations per coupling iteration.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
48 of ANSYS, Inc. and its subsidiaries and affiliates.
Heat Transfer in Square Channel Air Flow Tutorial
The mesh consists of four quad elements, evenly dividing the region, as shown in Figure 4: Mock
solver geometry (p. 50).
• It sends heat rate on elements as outputs on the FSI region. Each of the four elements provides 5
[W], so a total of 20 [W] is supplied to Fluent by the mock solver.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 49
System Coupling Participant Library Tutorials
Inside the resulting directory, you will find a subdirectory called HeatTransferSquareChannel. This
will serve as the simulation working directory and contains all the files needed for this tutorial. The
contents of this subdirectory are:
• fluent
• mocksolver
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
50 of ANSYS, Inc. and its subsidiaries and affiliates.
Heat Transfer in Square Channel Air Flow Tutorial
• fluent.scp
System Coupling Participant setup file containing the Fluent solver setup information to be
consumed by System Coupling
• mocksolver.scp
System Coupling Participant setup file containing the mock solver setup information to be
consumed by System Coupling
Note:
Note that this file has been pre-generated for this tutorial.
Refer to Creating System Coupling Participant Setup Files Using the Participant Library (p. 10)
in the System Coupling Participant Library Developer's Guide (p. 3) for information about
how to generate setup files using the participant library.
• runSerial.py
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 51
System Coupling Participant Library Tutorials
System Coupling script file that sets up and executes the coupled analysis using the serial
version of the mock solver
• runParallel.py
System Coupling script file that sets up and executes the coupled analysis using the parallel
version of the mock solver
Note:
Pre-built mock solver executables are provided along with the source code, so this step
is optional.
To run in standalone mode, an empty string should be provided for the System Coupling host
name. Since this mock solver program takes in the SC host name as the first command line argument,
iif the argument is omitted an empty host name will be used, as shown below:
ChannelFlowMockSolver.bat
./ChannelFlowMockSolver.sh
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
52 of ANSYS, Inc. and its subsidiaries and affiliates.
Heat Transfer in Square Channel Air Flow Tutorial
This will print a few lines to the console, containing host, port, and name information. It will execute
the mock coupled analysis for five coupling iterations.
Note:
The batch and the shell scripts use the environment variable AWP_ROOT201 to set up
the participant solver environment. Make sure that this environment variable is set to
the ANSYS installation path (e.g., C:\Program Files\ANSYS Inc\v201). Alternat-
ively, modify the scripts to use a different environment variable.
<ANSYSInstallationPath>/SystemCoupling/bin/systemcoupling -R runSerial.py
Note:
Alternatively, you can run System Coupling interactively. Start System Coupling by running
<ANSYSInstallationPath>/SystemCoupling/bin/systemcoupling and
then type the contents of the script(s) into the command console line-by-line.
You can monitor the solution progress by watching the Transcript output.
If the case runs without issue, you've successfully created a mock solver and run a co-simulation
between Fluent and the mock solver.
1. Open CFD-Post.
b. In the Load Results File dialog, select the Fluent results file that was generated during co-simu-
lation, fluent-1-00061.dat.h5.
The Fluent results file is loaded, and the geometry is displayed on the 3D Viewer tab of
CFD-Post's viewer.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 53
System Coupling Participant Library Tutorials
3. Add a cut-plane along the air flow and visualize the air temperature by coloring the plane with
temperature.
a. In the CFD-Post toolbar, select Insert > Location > Plane, enter the name of the plane in the
dialog box, and click OK.
i. On the Geometry tab, set Method to ZX Plane and set the Y field to 0.05 [m].
ii. On the Color tab, set Mode to Variable and set Variable to Temperature.
This allows you to visualize the air temperature as the air flows through the channel and the
hot air is mixed with the colder air.
Figure 5: Fluent temperature results after co-simulation with the mock solver
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
54 of ANSYS, Inc. and its subsidiaries and affiliates.
Heat Transfer in Square Channel Air Flow Tutorial
• The parallel mock solver source code is provided with the tutorial package.
• The Fluent solver will also run in local parallel, using its default MPI.
In a more realistic solver, the partitioning can be done according to an algorithm suitable for that
solver. In this example, the partitioning details are hard-coded for simplicity. Suppose we label each
of the four mesh elements in the mock solver A, B, C, and D, as shown in the schematic below.
(0,0.1,0) (1,0.1,0)
6-----7-----8-----9-----10
| | | | |
| A | B | C | D |
| | | | |
1-----2-----3-----4-----5
(0,0,0) (1,0,0)
The following table shows how the mesh elements are distributed among the processes, depending
on the total number of available processes.
Number of
Rank Elements Nodes
processes
A, B, 1, 2, 3, 4, 5, 6, 7,
1 0
C, D 8, 9, 10
2 0 A, B 1, 2, 3, 6, 7, 8
2 1 C, D 3, 4, 5, 8, 9, 10
3 0 A 1, 2, 6, 7
3 1 B 2, 3, 7, 8
3 2 C, D 3, 4, 5, 8, 9, 10
4 or more 0 A 1, 2, 6, 7
4 or more 1 B 2, 3, 7, 8
4 or more 2 C 3, 4, 8, 9
4 or more 3 D 4, 5, 9, 10
4 or No
4 or more No nodes
greater elements
Note that the above partitioning requires that some mesh nodes are duplicated among different
processes. The participant library is robust to having nodes and elements duplicated in multiple
processes.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 55
System Coupling Participant Library Tutorials
The source code for the parallel version is provided with the same tutorial package, in each supported
language. Refer to that source code and the comments for more implementation details.
More details about implementing the participant library APIs for execution in a parallel environment
are provided in the Using an Unsupported MPI Distribution (p. 10) section of the System Coupling
Participant Library Developer's Guide (p. 3).
To do that, use the -t4 command line argument when starting System Coupling to solve the case.
Execute the runParallel.py script to run System Coupling in batch mode:
You can monitor the solution progress by watching the Transcript output.
During the execution, note the "Execution Information" section in the System Coupling
Transcript will show that both Fluent and the mock solver are executed in parallel using four pro-
cesses. The -np 4 command-line argument is passed to the mock solver, and the -t4 command-
line argument is passed to Fluent.
+=============================================================================+
| Execution Information |
+=============================================================================+
...
| DEFAULT-2 |
| Execution Command: |
| ...ChannelFlowMockSolverMPI.bat ... -np 4 |
...
| Fluid Flow (Fluent) |
| Execution Command: |
| ...fluent.exe ... -t4 |
...
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
56 of ANSYS, Inc. and its subsidiaries and affiliates.
Transient Oscillating Plate Damping Tutorial
+=============================================================================+
Once the coupled analysis completes, you've successfully created a parallel mock solver and run a
co-simulation between Fluent and the mock solver. The post-processing step is identical to that of
the serial run.
This example also shows how to implement the restart interfaces in the participant solver, how to create
restart points at specified intervals, and how to restart the coupled analysis from a previously generated
restart point.
Topics covered:
• Transient analysis
• Restarts
Verify Prerequisites
Ensure that the following prerequisites are met. You've installed:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 57
System Coupling Participant Library Tutorials
The setup of the Mechanical participant is identical to that tutorial. A thin, flexible plate, made of a
linear elastic material, (Young's modulus = 2.5E6 [Pa], Poisson's ratio = 0.35, density = 2550 [kg m^-
3]) has a fixed support along its bottom face. A pressure load of 100 [Pa] is applied on one side of
the plate for the first 0.5 [s] of the simulation, which starts the oscillation. The setup is illustrated in
Figure 6: Structural solver geometry (p. 58).
Since the purpose of this example is to demonstrate the use of Participant Library APIs for a transient
analysis, a simple damping force solver will be used that will couple with Mechanical via System
Coupling. This solver receives nodal displacements from Mechanical and calculate the damping
force using the following formula:
(1)
where is the damping coefficient and is the rate of change of nodal positions with respect to
time (nodal velocities).
The damping solver will then provide the calculated forces to Mechanical via System Coupling, and
these damping forces will cause the oscillations to diminish in amplitude. The higher the damping
coefficient value is, the faster the oscillations will diminish. The damping coefficient value of 1.0 will
be provided to the damping solver via a command line argument --dampcoeff 1.0.
The surface mesh for the damping solver consists of 11 quadrilateral elements that overlap the plate
surface in Mechanical. The surface mesh is shown in Figure 7: Surface mesh in the damping solv-
er (p. 59).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
58 of ANSYS, Inc. and its subsidiaries and affiliates.
Transient Oscillating Plate Damping Tutorial
Inside the resulting directory, you will find a subdirectory called OscillatingPlateDamping. This will
serve as the simulation working directory and contains all the files needed for this tutorial. The contents
of this subdirectory are:
• mapdl
• dampingsolver
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 59
System Coupling Participant Library Tutorials
• mapdl.scp
System Coupling Participant setup file containing the Mechanical solver setup information to be
consumed by System Coupling
• damping.scp
System Coupling Participant setup file containing the damping solver setup information to be
consumed by System Coupling.
Note:
Note that this file has been pre-generated for this tutorial.
Refer to Creating System Coupling Participant Setup Files Using the Participant Library (p. 10) in
the System Coupling Participant Library Developer's Guide (p. 3) for information about how to
generate setup files using the participant library
• run.py
System Coupling script file that sets up and executes the coupled analysis
• runRestart.py
System Coupling script file that restarts the coupled analysis from a previously created intermediate
restart point
Note:
Pre-built damping solver executables are provided along with the source code, so this step
is optional.
The source code is provided in the dampingsolver subdirectory. In the following examples, damping
solver applications are built with different configurations. The actual build steps depend on your
system configuration, compilers, and other details. Refer to the Compiling, Linking, and Executing
Applications That Use the Participant Library (p. 37) section of the System Coupling Participant Library
Developer's Guide (p. 3) for additional information.
• Linux
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
60 of ANSYS, Inc. and its subsidiaries and affiliates.
Transient Oscillating Plate Damping Tutorial
• Windows
Linux
C++
Fortran
gfortran -I<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/include/SystemCouplingParticipant/
FortranFixedForm -L<ANSYSInstallationPath>/SystemCoupling/runTime/linx64/bin -L<ANSYSInstallationPath>/
SystemCoupling/runTime/linx64/cnlauncher/fluent/fluent<MultiportVersion>/multiport/mpi_wrapper/lnamd64/
stub -o OscillatingPlateDamping OscillatingPlateDamping.f -lSysC.SystemCouplingParticipantFortran
-lmpi_wrapper
Windows
C++
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 61
System Coupling Participant Library Tutorials
Fortran
ifort -I"<ANSYSInstallationPath>\SystemCoupling\runTime\winx64\include\SystemCouplingParticipant\FortranFixedFor
/FeOscillatingPlateDamping.exe OscillatingPlateDamping.f /link /subsystem:console /LIBPATH:"<ANSYSInstallationPa
SystemCoupling\runTime\winx64\lib" SysC.SystemCouplingParticipantFortran.lib
If the case runs without issue, you've successfully created a simple damping solver and run a co-
simulation between Mechanical and this damping solver.
1. Open CFD-Post.
b. In the Load Results File dialog, select the Mechanical results file that was generated during co-
simulation, file.rst.
The Mechanical results file is loaded and the geometry is displayed on the 3D Viewer tab
of CFD-Post's viewer.
This point is at the top corner of the solid body and will be used to track the deformation of the
plate.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
62 of ANSYS, Inc. and its subsidiaries and affiliates.
Transient Oscillating Plate Damping Tutorial
a. In CFD-Post's toolbar, select Insert > Location > Pointand then click OK to accept the default
name.
c. Click Apply.
On the model, cross-hairs appear on node number 77, so you can see where this point is
on the solid body.
To view the deformation using the point you just created, insert an XY Transient Chart for the
data at this node (Point 1). In the chart you create, the x-axis is time and the y-axis is the total
mesh displacement.
a. In CFD-Post's toolbar, select Insert > Chart and then click OK to accept the default name.
After the chart is generated, note the damping that is visible in the plate's motion.
Figure 8: Plot of plate tip x-displacements over time for different damping coefficients (p. 64) shows
the chart of plate tip position over time for different damping coefficients. As expected, the higher
the damping coefficient is, the faster the plate oscillations diminish in amplitude.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 63
System Coupling Participant Library Tutorials
Figure 8: Plot of plate tip x-displacements over time for different damping coefficients
• When the above function is called, it will create a text file and write current nodal coordinates and force
values. This is the only information that is required to cleanly restart the damping solver at a given time
step. The name of the restart file is returned from that function.
• When System Coupling restarts from a given coupling step, it will pass the restart file name as a command
line argument to the damping solver.
• The damping solver will read in the nodal coordinates and forces from the restart file prior to entering
the coupled analysis loop.
The coupled analysis will now be restarted from the 50th step (simulation time 5.0 [s]) and solved
through the 100th step (simulation time 10.0 [s]).
The restart script runRestart.py is provided with this tutorial. To run the coupled analysis, execute
the restart script in batch mode:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
64 of ANSYS, Inc. and its subsidiaries and affiliates.
Transient Oscillating Plate Damping Tutorial
The coupled analysis should restart and solve until the end. The ANSYS Mechanical results can be
post-processed the same way as for the initial run. Figure 9: Comparison of results between the con-
tinuous and restarted runs (p. 65) shows the chart of the plate tip position over time for the continuous
and restarted analysis. The results show that nearly identical displacements are achieved from the
restarted run. The very slight differences can be attributed to the limitations within System Coupling
and ANSYS Mechanical. See Restarting a Coupled Analysis in the System Coupling User's Guide for a
more detailed description of these limitations.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 65
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
66 of ANSYS, Inc. and its subsidiaries and affiliates.