Professional Documents
Culture Documents
System Coupling Users Guide
System Coupling Users Guide
System Coupling Users Guide
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 User's Guide
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling User's Guide
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. v
System Coupling User's Guide
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
vi of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling User's Guide
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. vii
System Coupling User's Guide
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
viii of ANSYS, Inc. and its subsidiaries and affiliates.
List of Figures
1. Data model example in System Coupling's GUI ......................................................................................... 40
2. Data model example in System Coupling's CLI ......................................................................................... 40
3.The System Coupling GUI ......................................................................................................................... 47
4. Communication between System Coupling and coupling participants .................................................... 102
5. Co-simulation with four participants ...................................................................................................... 103
6. Machine List specified using the --cnf command-line option ............................................................... 110
7. Machine List specified using the System Coupling GUI ........................................................................... 111
8. Machine List specified using the PartitionParticipants command ............................................. 111
9. Resource allocation resulting from the Shared Allocate Cores examples .................................................. 115
10. The System Coupling tab ..................................................................................................................... 125
11. Connecting a System Coupling component system with other types of systems .................................... 128
12. Solution Information node ................................................................................................................... 141
13. Hierarchical availability of plotting data ................................................................................................ 143
14. Selection of Convergence Chart variable .............................................................................................. 145
15. Execution sequence diagram for System Coupling and co-simulation participants ................................ 156
16. Processing details for System Coupling and co-simulation participants ................................................. 157
17. Example of a BSP tree mesh on a 2D target domain, which extends naturally to 3D (source mesh locations
not shown for clarity) ................................................................................................................................ 164
18. Example input and output for Linear Shape Function mapping ............................................................. 166
19. Mapping weights generated for a target node, based upon its projection onto a source element via Linear
Shape Function mapping .......................................................................................................................... 167
20. Example input and output for Radial Basis Function mapping ............................................................... 167
21. Example mapping weights wi generated for a target node (T), based on the distance to nodes with the
associated source elements Si via Radial Basis Function mapping ............................................................... 167
22. Example input and output for Element-Weighted Average mapping ..................................................... 168
23. Mapping weights generated for a target node (T), based upon its extrusion onto source elements via
Element Weighted Average mapping. Representative weight calculation is shown for node 3; other weights
are computed in a similar manner. ............................................................................................................. 169
24. Example input and output for conservative Intersect-Scatter-Gather mapping between like topolo-
gies .......................................................................................................................................................... 170
25. Mapping weights generated for a target element, based on its intersection with source elements via In-
tersect-Scatter-Gather between like topologies ......................................................................................... 170
26. Example input and output for conservative mapping for Intersect-Scatter-Gather between unlike topolo-
gies. Circled values are the total for the elements. ...................................................................................... 171
27. Mapping weights generated for a target node, based upon its extrusion onto a target element via Intersect-
Scatter-Gather between unlike topologies ................................................................................................ 172
28. Schematic of the Linear to Minimum Iterations ramping concept .......................................................... 175
29. Coupling Iteration output .................................................................................................................... 204
30. Coupling Iteration output with simultaneous-solve participants ........................................................... 204
31. Table of step-based restart points ........................................................................................................ 206
32. Table of iteration-based restart points ................................................................................................. 206
33. Workflow to set up a coupled FSI analysis ............................................................................................. 218
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. ix
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
x of ANSYS, Inc. and its subsidiaries and affiliates.
List of Tables
1. System Coupling capabilities by version ..................................................................................................... 4
2. Transfer quantities supported by System Coupling ..................................................................................... 8
3. Participant-specific support of System Coupling capabilities ...................................................................... 9
4. Licenses required for participants in System Coupling analyses ................................................................ 13
5. Status messages ...................................................................................................................................... 49
6. File Menu Options ................................................................................................................................... 49
7. Help menu options .................................................................................................................................. 51
8. Setup context menu options ................................................................................................................... 51
9. Solution context menu options ................................................................................................................ 53
10. Shared Parallel vs. Distributed Parallel execution modes ........................................................................ 107
11. Coupling context support for region topology combinations ................................................................ 161
12. Mapping algorithms by mapping type and region topology ................................................................. 166
13. Initial values used for the reference target-side value ............................................................................ 176
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. xi
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
xii of ANSYS, Inc. and its subsidiaries and affiliates.
Introduction to the System Coupling User's Guide
The System Coupling User's Guide describes how to use the current version of ANSYS System Coupling
to direct two or more otherwise independent physics solvers and/or external data sources to work to-
gether in a coupled multiphysics analysis — for example, in a Fluid-Structure Interaction (FSI) analysis.
• System Coupling Overview (p. 3) offers a high-level overview of the core coupling functionality available
for all analyses run using System Coupling, including troubleshooting information, migration instructions,
and a listing of current known issues and limitations.
• Using System Coupling's User Interfaces (p. 33) describes how to set up and execute coupled analyses using
System Coupling's graphical user interface (GUI) and command-line interface (CLI).
• Using System Coupling in Workbench (p. 121) describes how to set up and execute coupled analyses using
System Coupling in Workbench.
• Coupled Analysis Management (p. 155) describes the processes System Coupling uses to manage coupled
analyses and co-simulations.
• System Coupling Data Transfers (p. 159) provides detailed and context-agnostic information about data
transfers, including the rules that govern their creation, the overall data-transfer process, and details about
the mapping and supplemental processing algorithms used by System Coupling.
• System Coupling Input and Output Files (p. 179) describes the files that System Coupling consumes and
produces during the setup and execution of a coupled analysis.
• Best Practices for System Coupling (p. 211) provides both generally applicable and application-specific best
practices and recommendations for setting up and running coupled analyses.
The previous version of the System Coupling application is referred to as "System Coupling 1.0." For
documentation on the older version of the product, see the System Coupling 1.0 User's Guide .
Context-Specific Notation
When referring to data model items (containers and settings), operations, and other coupling-related
items, different notation is used in discussions of System Coupling's different contexts. In general, the
following conventions are followed:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Introduction to the System Coupling User's Guide
• Bold font
• Title Case
• Bold font
• Code font
• Proper UpperCamelCase
Additional Resources
In addition to this user's guide, the following documentation for the current version of System Coupling
is available on the System Coupling 2020 R1 help page:
• System Coupling Settings and Commands Reference provides a comprehensive listing of available settings,
commands, and command-line options.
• System Coupling Participant Library describes how to use the APIs published in the System Coupling Participant
Library to connect independent solvers to System Coupling.
• System Coupling Beta Features gives instructions for accessing and using the beta and pre-beta capabilities
offered by System Coupling in the 2020 R1 release.
• System Coupling Tutorials includes tutorials showing how to set up and run coupled multiphysics analyses
in the different contexts offered by System Coupling: graphical user interface (GUI), command-line interface
(CLI), and System Coupling in Workbench.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Overview
The ANSYS portfolio of simulation software facilitates the creation of multidisciplinary physics ana-
lyses—not only within the context of a single product, but also through the use of ANSYS System
Coupling. System Coupling can integrate multiple individual analyses, enabling you to leverage different
physics solvers and/or static external data sources in a single multiphysics simulation. When two or
more analyses are coupled, an examination of their combined results can capture more complex inter-
actions than an examination of those results in isolation, producing more accurate results and yielding
an optimal solution.
You can use System Coupling in several different contexts, each of which facilitates comprehensive
multidisciplinary simulations between coupling participants. You can run System Coupling in:
System Coupling manages the execution of simulations between coupling participants, which are the
applications or data sources that send and/or receive data in a coupled analysis. Participant support is
determined by the context you're using.
This chapter provides a high-level introduction to core System Coupling functionality available in all
three contexts. For more information, see:
The ANSYS Product Improvement Program
System Coupling Capabilities
System Coupling Contexts: GUI, CLI, and Workbench
Product Licensing Considerations
Steps of a System Coupling Analysis
System Coupling Analysis Types
System Coupling Settings
Stops and Restarts of System Coupling Analyses
Migrating to ANSYS System Coupling 2020 R1
Known Issues and Limitations
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
System Coupling Overview
For details on the program as a whole, see The ANSYS Product Improvement Program in the Mechanical
User's Guide (or the corresponding section in the documentation for another ANSYS product covered
by the program).
• Number of participants
• Number of participants serving as a data transfer target (i.e., that are receiving data from another coupling
participant)
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Unified access to
✓ ✓
participant transcript file(s)
User
Environment Charting: Collated
participant convergence ✓
and monitors
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Capabilities
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Charting: Data transfer
convergence Beta1 ✓ ✓
Charting: Output of
charting data as Beta1
CSV-formatted files
Optimized, scriptable
✓ ✓
command-line interface
Interactive command-line
✓ ✓
interface
System Coupling run as
✓ ✓ ✓
distributed processes
Automated
startup/shutdown ✓ ✓ ✓ ✓
(including error handling)
Coordinated restart point
✓ ✓
creation
Coordinated restart point
selection and automated ✓ ✓
Coupled Run restarts
Execution Reconnect to running
✓ ✓
System Coupling session
Project submission to
✓ ✓
clusters using RSM
Configurable, script-based
✓ ✓
submission to clusters
Runtime debug output ✓ ✓ ✓ ✓
System Coupling and
participant wall-clock time ✓ ✓ ✓
summary
Surface and volumetric
Postprocessing output in ANSYS EnSight ✓ ✓
Gold4
Two participants in a single
✓ ✓ ✓ ✓
co-simulation
Up to 25 participants in a
✓ ✓
Co-Simulation single co-simulation
Co-simulation Functional
Mock-up Unit (FMU) Beta1 Beta1
2
participants
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
System Coupling Overview
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Simultaneous participant
✓ ✓
solutions
Participant solution
✓ ✓ ✓
sequence control2
Steady coupled analyses ✓ ✓ ✓ ✓
Transient coupled analyses ✓ ✓ ✓ ✓
Mixed steady-transient
✓ ✓ ✓ ✓
coupled analyses
Include content from
ANSYS External Data ✓ ✓ ✓ ✓
system
Participant update
✓ ✓
frequency control2
Geometry transformations
for participant models with
different orientations ✓ ✓
(limited to scalar data
transfers)2
Multiple iterations per
coupling step (for implicit ✓ ✓ ✓ ✓
couplings)
Set minimum and
maximum number of ✓ ✓ ✓ ✓
coupling iterations per step
All fixed topology element
types (except polyhedral)
Note:
✓ ✓ ✓ ✓
High-order
mesh/data is
converted to
Interfaces low-order.
and
Transfers
Polyhedral element types
2 ✓ ✓ ✓
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Capabilities
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Profile-preserving mapping
✓ ✓ ✓ ✓
algorithms
Surface⇒Surface transfer
quantities:2, 3
Force, Incremental
Displacement, ✓ ✓ ✓ ✓
Temperature, Heat Rate,
Heat Transfer Coefficient
and Convection Reference
Temperature
Volume⇒Volume transfer
quantities:2, 3
✓ ✓
Temperature, Heat Rate,
Heat Rate Density
Planar surface⇒Volume
transfer quantities:2, 3
✓ ✓
Heat Rate, Heat Rate
Density
Volume⇒Planar surface
transfer quantities:2, 3
✓ ✓
Temperature
Single scalar value
(co-simulation slave FMU)
transfer quantities:2, 3
• Single scalar
value⇒Surface, volume, Beta1 Beta1
planar surface
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
System Coupling Overview
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Quasi-Newton solution
stabilization algorithm, per ✓ ✓
transfer, per interface
1: For more information about beta functionality, see the System Coupling Beta Features
documentation.
2: For more information about participant-specific support of noted features, see Participant Support
of System Coupling Capabilities (p. 9).
3: For more information about supported quantities, see System Coupling Data Transfer
Quantities (p. 8).
4: The generation of ANSYS EnSight-compatible coupling results is a released feature, but the settings
to control non-default behavior are still beta functionality. For more information, see Settings for
Generating ANSYS EnSight-Compatible Postprocessing Output in the System Coupling Beta Features
documentation.
For details about the System Coupling capabilities listed here, see the subsequent sections of this guide.
For details about System Coupling 1.0 capabilities, see the System Coupling 1.0 User's Guide 1.0.
Applicable
Transfer Quantity
Tensor Type Mapping Notes
Type1
Algorithm Type2
Force [N] Vector3 Conservative
Displacement during the current
Incremental 3
Vector Profile-Preserving coupling step (i.e., since the end of
Displacement [m]
the previous coupling step)
Heat Rate [W] Scalar Conservative
Conservative mapping used when
Heat Rate Density
Scalar Conservative paired with a variable of Heat Rate
[W/m3]
quantity type
Temperature [K] Scalar Profile-Preserving
Heat Transfer
Coefficient Scalar Profile-Preserving
[W/(m2K)]
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Capabilities
Applicable
Transfer Quantity
Tensor Type Mapping Notes
Type1
Algorithm Type2
Convection
Reference Scalar Profile-Preserving
Temperature [K]
1: Quantity types noted in this table are in SI units.
2: For more information about mapping and algorithm types, see System Coupling's Mapping
Capabilities (p. 160).
For participant-specific information on the quantity types that can be transferred via System Coupling,
see the corresponding participant documentation:
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Steady or transient
✓ ✓ ✓ ✓
analysis types
Polyhedral element types ✓ ✓ ✓
Multiple regions per side
✓ ✓
of interface
Participant update
Fluent frequency control Beta1 Beta1
Geometry transformations
for participant models
with different orientations ✓ ✓
(limited to scalar data
transfers)
Surface transfer quantities: ✓ ✓ ✓ ✓
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
System Coupling Overview
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
• Output: Force, Temperature,
Heat Rate, Heat Transfer
Coefficient and Convection
Reference Temperature
• Input: Incremental
Displacement, Temperature,
Heat Rate, Heat Transfer
Coefficient and Convection
Reference Temperature
• Output: Temperature ✓ ✓
• Input: Heat Rate
Steady or transient
✓ ✓ ✓ ✓
analysis types
Participant update
frequency control Beta1 Beta1
Steady or transient
✓ ✓
analysis types
Surface transfer quantities:
• Input: Temperature
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Capabilities
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
Participant update
frequency control Beta1 Beta1
Geometry transformations
for participant models
with different orientations ✓ ✓
(limited to scalar data
transfers)
Surface transfer quantities:
• Output: Incremental
Displacement, Temperature,
Heat Rate
✓ ✓ ✓ ✓
• Input: Force, Temperature,
Heat Rate, Heat Transfer
Coefficient and Convection
Reference Temperature
• Output: Temperature ✓ ✓ ✓ ✓
• Input: Heat Rate Density
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 11
System Coupling Overview
System
System System System
Coupling in
Category Capabilities Coupling Coupling Coupling in
Workbench
GUI CLI Workbench
1.0
• Input: Temperature
Steady or transient
solution type Beta1 Beta1
1: For more information about beta functionality, see the System Coupling Beta Features
documentation.
For information on a given participant's support for System Coupling capabilities, see its coupling-related
product documentation:
• Performing System Coupling Simulations Using Fluent in the Fluent User's Guide
• Coupling CFX to an External Solver: System Coupling Simulations in the CFX-Solver User's Guide
Set up and execute coupled simulations using the System Coupling GUI. A robust API
provides access to System Coupling's infrastructure and functionality, enabling you to create
and solve multiphysics simulations involving the transfer of surface and volume data between
coupling participants.
Set up and execute coupled simulations using the System Coupling CLI. System Coupling
offers the same capabilities when run from its CLI as it does when run from its GUI.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
12 of ANSYS, Inc. and its subsidiaries and affiliates.
Product Licensing Considerations
For more information, see Using System Coupling's User Interfaces (p. 33).
For more information, see Using System Coupling in Workbench (p. 121).
For many of our products, the simultaneous execution of coupling participants precludes the use of
the license sharing capability that exists for some product licenses. For these products, the following
requirements exist:
• Licensing preferences should be set to Use a separate license for each application rather than Share
a single license between applications when possible.
Note:
If you are running one of the ANSYS Academic Mechanical and CFD licenses (Associate,
Research, or Teaching) or an ANSYS Academic Student license with a solver license that
supports license sharing (such as ANSYS CFX), then you can run an FSI simulation with a
single license. With these products, set your licensing preferences to Share a single license
between applications when possible.
Licenses that support license sharing for coupled analyses are in bold text in the table below.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 13
System Coupling Overview
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
14 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Analysis Types
For each participant, set up data transfer variables and regions to be coupled, as well as coupling-
related settings that enable a coupled analysis.
Set up the System Coupling part of the analysis, specifying analysis settings and defining data
transfers.
Run the coupled analysis by starting System Coupling and each of the participant solvers.
Review the solution output produced by both System Coupling and participant solvers. You
can postprocess the results using the methods recommended for a given participant or by
loading coupling results into ANSYS EnSight.
General/Steady
• Used when all coupling participants are performing a steady-state or static solution.
• Accurate coupled solutions can be achieved using different combinations of coupling step and
coupling iteration specifications; you can use either a single coupling step or multiple coupling
steps.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 15
System Coupling Overview
Transient
Note:
For transient solutions involving physics with disparate time scales, System
Coupling offers mixed steady-transient analyses. In such analyses, System
Coupling will show the overall analysis type as Transient, while the physics with
the shorter/faster timescale is solved as steady-state.
• A coupling step is associated with a time interval when the coupling step size (in seconds) is specified.
With a time specified, a coupling step is the same as a time step within the transient analysis.
• determines when result and/or restart data can be written, as the restart points can only be written
at the end of a coupling step,
• allows you to balance the required file storage space and your need for analysis restarts, and
• determines how you can use System Coupling's under-relaxation factor and ramping, as these only
apply to coupling iterations and cannot be applied over coupling steps.
Only the end of a coupling step can be used as a restart point. Results and restart data are generated
only at the end of the solution. The analysis can be terminated as usual, but because intermediate
restart data are not generated, the coupled analysis cannot be restarted if it terminates abnormally
(due to an error, power interruption, etc.) or if you terminate it before the coupling step is completed.
Using only one coupling step within a coupled analysis minimizes file storage space at the expense
of the ability to restart the analysis.
Interrupting the analysis doesn't affect the analysis, because System Coupling completes the current
coupling step (and so complete the solution) before stopping the analysis. Ramping and under-relax-
ation can be applied across coupling iterations within the single coupling step.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
16 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Analysis Types
Only the end of a coupling step can be used as a restart point, but you can specify which steps are
used. Results and restart data are generated at the specified restart points. If the analysis should ter-
minate abnormally within a coupling step, you can restart the analysis from the previous restart point.
By using more coupling steps with fewer coupling iterations per step, as opposed to one coupling
step with many coupling iterations, more points at which restarts can be done are created. For difficult
or complex analyses, which might experience abnormal terminations, more restart points allow restarts
of the analysis (saving time and computational effort) at the expense of file storage space.
System Coupling's ramping and under-relaxation can be used across coupling iterations, but cannot
be used across coupling steps, so System Coupling always transfers the full data transfer value at the
end of each coupling step. Participant solvers may ramp data received from System Coupling at the
coupling steps.
If the analysis duration is specified using only an end time, ensure that an integral number of coupling
steps can be executed between the (re)start time and the specified end time. If this is not done, then
the final coupling step size is reduced to respect the specified end time, and this may introduce
temporal discretization error into the coupled analysis.
The minimum number of coupling iterations may be set to a value larger than one (one is the default).
If the data transfers have been under-relaxed, ensure that a minimum number of coupling iterations
is performed so that you iterate out the effect of the under-relaxation. Note, however, that the data
transfer convergence criteria would usually make this unnecessary. The maximum number of coupling
iterations should be set to allow complete convergence within each coupling step.
Mixed steady-transient solutions (in which one participant runs a steady solution and one runs a
transient solution) have a transient analysis type. By mixing steady and transient participant analyses,
greater solution efficiency can be realized for transient analyses involving physics with disparate time
scales. The coupled analysis remains time-accurate, provided that the physical timescales of the steady-
state participant(s) are orders of magnitude faster than those of the transient participant(s).
For a steady-transient command-line analysis with an AEDT participant (e.g., Fluent is running a
transient analysis and Maxwell is running a steady-state analysis), you can further improve solution
efficiency by moderating the update frequency for the AEDT participant. For more information, see
Update Control in the System Coupling Settings and Commands Reference manual.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 17
System Coupling Overview
• Analysis settings
Settings defining the type of analysis and controls for the initialization, duration, and steps of
the analysis.
• Solution settings
Settings defining the frequency with which coupling output (specifically, restart points) is gener-
ated.
• Participant settings
Settings defining a name for each participant, regions from and to which data can be transferred,
the input and output data transfer variables available for each region, and the frequency with
which the participant is updated.
Settings defining a source and a target for each data transfer. Both source and target are defined
by a coupling participant, along with a region and variable defined for that participant.
Additional data transfer settings control how specified data transfers are executed. These can
include convergence target, relaxation factor, and ramping options.
• Expert settings
Settings providing additional control of the coupled analysis, including debug and restart output
files.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
18 of ANSYS, Inc. and its subsidiaries and affiliates.
Stops and Restarts of System Coupling Analyses
• An interrupted analysis produces a clean stop, where the run continues until the current coupling
step is finished and the restart data are generated. An interrupted run can be restarted later from
end of the coupling step in which it was stopped.
• An aborted analysis terminates the run immediately and does not produce restart data. An aborted
run cannot be restarted from the coupling step in which it was stopped. However, an aborted can
be restarted from an intermediate result that was completed before the analysis was aborted.
Note:
• Mechanical participants do not support restarts for steady-state thermal and transient
thermal analyses.
Information needed to restart the System Coupling is contained in the Results (p. 207) files
generated by System Coupling during the run.
Information needed to restart the coupling participants, as well as the act of restarting those
participants, are managed by the participants themselves.
Tip:
To ensure that participant solvers are writing restart data at synchronized coupling
steps, the creation of restart points is controlled by System Coupling. For details
on how a given participant handles restarts, use the links provided in Supported
Coupling Participants for System Coupling in Workbench (p. 122) or Supported
Coupling Participants (p. 34) to access its documentation.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 19
System Coupling Overview
Once the coupled analysis run is finished or interrupted, or if the solution fails, you can restart
the run from any of the saved restart points. The same restart point must be used by System
Coupling and all coupling participants.
If you've saved changes to analysis settings for System Coupling and/or any participant except
for Mechanical, then the changes are written to a Settings (p. 207) file and included in the
restarted run.
Note:
Note that the convergence history for a restarted run is generally not identical to that
observed in a continuous run. The following factors contribute to changes in convergence:
• Final target-side values are not persisted and available for ramping and/or relaxation.
• Interfaces are re-mapped upon restart, thereby changing the interpolation weights.
• For the first iteration of a restarted run, reference values for ramping (p. 173) and under-
relaxation (p. 175) are reset to initial values upon remapping, so no ramping or under-re-
laxation is applied during this iteration.
• Changes in convergence behavior do not produce different results, provided that solutions
and data transfers are fully converged within coupling steps. Also, changes in convergence
history across restarts yield changes in solution values if solutions are not fully converged
within coupling steps.
This section provides you with the information necessary for a smooth transition of System Coupling
to the current release, ANSYS2020 R1. The following sections describe changes that have been imple-
mented since the previous release and which may impact your usage of System Coupling:
Migrating Across Multiple Releases
Migrating to Use Fluent Face/Cell Transfer Data
Migrating Command-Line System Coupling Scripts
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
20 of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
2. At the upper-right corner of the window, select the appropriate release from the Release drop-down
menu.
4. Use the search bar to locate the "Migrating Command-Line System Coupling Scripts" section.
Note:
These migration instructions are applicable only to the current version of System Coupling.
For documentation on the previous version, see Migrating to the 2020 R1 Release of ANSYS
System Coupling 1.0 in the System Coupling User's Guide 1.0.
To run coupled analyses in which Fluent participants engage in data transfers of conservative
quantities, both Fluent and System Coupling must be using data on the same location (i.e., either
both must use data on faces/cells, or both must use data on nodes).
• For existing cases that were set up and solved with one of System Coupling's user interfaces (GUI or
CLI) using SCP files, both System Coupling and Fluent respect the previous settings and continue to
use conservative nodal data.
– If the case was solved in Workbench, then System Coupling and Fluent apply the new functionality
and use conservative face/cell data.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 21
System Coupling Overview
– If the case was solved using System Coupling's GUI or CLI using the SCI file generated by Workbench,
then System Coupling and Fluent are in an inconsistent state and need some action in order to run,
as described below.
In general, it is recommended that face/cell data is used for conservative transfers — both to benefit
from the improved mapping accuracy and to ensure consistency of diagnostics and results (which
vary slightly according to data location) — and that you perform the migration steps required to
achieve this. However, when required, it is also possible to revert Fluent back to its previous function-
ality.
To migrate existing cases to use face/cell transfers or revert new cases to use nodal transfers, follow
the steps in the appropriate section below, depending on your workflow:
Cases Set Up and Solved with System Coupling GUI or CLI Using SCP Files
Cases Set Up and Solved with Workbench
Cases Set Up in Workbench and Solved with System Coupling's GUI or CLI
Cases Set Up and Solved with System Coupling GUI or CLI Using SCP Files
By default, existing cases that were set up in System Coupling's GUI or CLI using SCP files continue
to use nodal data. To migrate to the use of face/cell data or revert to the use of nodal data, follow
the instructions in one of the sections below:
Migrating to the Use of Face/Cell Data
Reverting to the Use of Nodal Data
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
5. Regenerate results:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
22 of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
5. Regenerate results:
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 23
System Coupling Overview
1. Before starting Workbench to solve the analysis, set the SYC_FLUENT_CONSNODAL environment
variable to any value.
This causes System Coupling to revert to the use of nodal data for conservative data transfers.
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
24 of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
Cases Set Up in Workbench and Solved with System Coupling's GUI or CLI
This use case arises when a case is set up in Workbench and the resulting SCI file is imported into
System Coupling's GUI or CLI. New cases using this workflow will use face/cell data by default. Ex-
isting cases using this workflow are in an inconsistent state, with part of the system expecting to
use face/cell data and part of the system expecting to use nodal data. Perform one of the following
steps to have existing cases consistently use either face/cell data or nodal data:
Migrating to the Use of Face/Cell Data
Reverting to the Use of Nodal Data
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 25
System Coupling Overview
To revert new cases to use nodal data, the following steps are also necessary:
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
Existing coupling cases (i.e., that have been saved to a Settings.h5 file) will be migrated automat-
ically when you re-open them with the most recent release of System Coupling. If you have existing
coupling scripts, however, you may need to update them, so they'll continue to work with the current
and later releases
This following sections contain information on the data model changes that have been introduced
in the 2020 R1 release, as well as instructions on how to migrate your existing scripts:
CPython Upgrade
Changes to Commands
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
26 of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
CPython Upgrade
System Coupling has been updated and now uses CPython 3.7 instead of CPython 2.7. Update your
coupling scripts as needed. For more information, see the Python 3.7 documentation published on
the Python Software Foundation website.
Changes to Commands
The table below lists changes to commands in the 2020 R1 release of System Coupling.
CreateInterfaces-
AndDataTransfers
will be deprecated in a
future release. It is still
supported in the 2020 Use the following
R1 release, with the commands
following exceptions: instead:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 27
System Coupling Overview
For more
information, see
StartParti-
ciapnts.
Deprecated argument.
ParticipantNames
has been deprecated. Run the Start-
Participants
When StartParti- command
cipants is run with without
this argument, it arguments.
ignores provided
participant list and
starts all participants.
Ensure that you
use Coupling-
Iteration only
New argument.
for analyses with
The CouplingItera- iteration-based
tion argument has restart files (Res-
been added. This ults_iter#.h5).
argument is used to
Conversely,
open only
ensure that you
Open() iteration-based restart
use Coupling-
files.
Step only for
Note that the existing analyses with
CouplingStep step-based restart
argument is used to files (Res-
open only step-based ults_step#.h5).
restart files.
For more
information, see
Open.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
28 of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
Now, this option specifies the machine list for analyses with
coupling participants running in parallel.
The SolutionControl
singleton container has been
SolutionControl added at the root-level.
The AllowSimultaneousUp-
date has been added under the
SolutionControl.AllowSimultaneousUpdate SolutionControl singleton.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 29
System Coupling Overview
The ParticipantAna-
lysisType setting has been
added under the CouplingPar-
CouplingParticipant.ParticipantAna- ticipant singleton.
lysisType
Available only when Parti-
cipantType is set to DEFAULT.
The RestartsSupported
setting has been added under
the CouplingParticipant
CouplingParticipant.RestartsSupported singleton.
The ParallelFraction
setting has been added under
the coupling participant's Out-
CouplingParticipant.OutputControl.Paral- putControl singleton.
lelFraction
Specifies the core count or
fraction of compute resources to
be allocated to the participant
when participants are running in
parallel.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
30 of ANSYS, Inc. and its subsidiaries and affiliates.
Known Issues and Limitations
The ParallelArguments
setting has been removed.
To do this, you will need the process ID for the job to be killed. This information is available in
Transcript/Log for the coupled analysis.
If a previous run terminated unexpectedly or was killed manually (or if you are otherwise certain
that no System Coupling instance is running in GUI Server mode in that directory), then you can
delete the orphaned file and restart System Coupling.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 31
System Coupling Overview
If a previous run terminated unexpectedly or was killed manually (or if you are otherwise certain
that no solution is running in that directory), then you can delete the orphaned file and reattempt
a solve.
If issues are encountered, try setting the environment variable QT_QUICK_BACKEND to software
before starting the GUI.
To resolve this, ensure that the hosts file does not contain arbitrary entries. The hosts file is typically
located in the /etc directory on Linux platforms and C:\Windows\System32\Drivers\etc on Windows
platforms.
If the Electronics Desktop/Maxwell participant does not connect to System Coupling because a lock
file is present, then you must delete the lock file manually before attempting to run the coupled
analysis again.
Tip:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
32 of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling's User Interfaces
When running System Coupling in one of its user interfaces, you can use the graphical user interface
(GUI) and/or the command-line interface (CLI) to build and execute coupled analyses. The same func-
tionality is available in both interfaces.
Note:
The System Coupling User's Guide generally uses context designations as needed to enhance
clarity. In this section, however, when the term "System Coupling" is used without qualification,
it refers to System Coupling when run from one of its user interfaces.
• Overview of System Coupling's User Interfaces (p. 34) provides a high-level introduction to using System
Coupling in one of its user interfaces, including information on supported participants, coupling interfaces,
and data transfers.
• Working with System Coupling's Data Model (p. 39) includes a description of the data model structure, an
overview of the root-level containers, and instructions on viewing data model contents.
• Using System Coupling's Graphical User Interface (GUI) (p. 44) provides instructions on starting the GUI and
describes its components and available functions.
• Using the System Coupling Command-Line Interface (CLI) (p. 53) provides instructions on starting the CLI
and includes information on accessing help and navigating the data model from the command line.
• Preparing for a Coupled Analysis (p. 55) provides instructions on preparing a working directory and setting
up participant physics.
• Creating a Coupled Analysis (p. 59) provides instructions on adding participants, interfaces, and data
transfers to a coupled analysis.
• Modifying Coupled Analysis Settings (p. 66) provides instructions on changing data model settings and
expert settings, as well as on requesting debug output.
• Running a Coupled Analysis (p. 80) provides instructions for running and monitoring a coupled analysis.
• Reviewing Coupled Analysis Output and Results (p. 82) provides guidance on accessing and working with
coupling output and results.
• Advanced System Coupling Workflows (p. 86) describes different advanced workflows for coupled analyses,
including restarts, connecting/reconnecting to running coupled analyses, interactive solve commands, and
parallel processing for HPC job submission.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 33
Using System Coupling's User Interfaces
• Supported Coupling Participants (p. 34) specifies the systems that can serve as participants in a coupled
analysis.
• Coupling Interfaces and Data Transfers (p. 35) describes the rules for creating coupling interfaces and
data transfers.
• Steps of a Coupled Analysis (p. 37) lists the steps involved in setting up and running a coupled analysis
in System Coupling's GUI or CLI.
• Participant Solution Sequencing (p. 38) describes the process System Coupling uses to determine the
order in which participant solutions are executed.
CFX
For information on using System Coupling with ANSYS CFX, see the following sections in the CFX-Solver
Modeling Guide:
Fluent
For information on using System Coupling with ANSYS Fluent, see the following sections in the Fluent
User's Guide:
Forte
For information on using System Coupling with ANSYS Forte, see the following sections in the Forte
User's Guide:
• System Coupling
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
34 of ANSYS, Inc. and its subsidiaries and affiliates.
Overview of System Coupling's User Interfaces
Maxwell
For information on using System Coupling with ANSYS Maxwell, see the following section in the Maxwell
Help:
Note:
To enable coupling for Maxwell on a Linux system, you must set the AN-
SYSEM_ROOT201 environment variable to the location of your ANSYS EM Suite install-
ation.
Mechanical
For information on using System Coupling with ANSYS Mechanical, see the following sections in the
Mechanical User's Guide:
• System Coupling
Coupling Interfaces
A coupling interface defines two sets of regions, each set belonging to one participant, between which
data can be transferred during the coupled analysis. A single coupling interface encompasses all transfers
in either direction between a given set of regions on the two sides of the interface.
Interfaces support two-way data transfers, so a given participant can be both a source and a target
in the same interface. Because of this, both the interface sides and their associated participants
and regions are referred to as "side One" and "side Two," instead of "source" and "target."
For more information, see Rules for the Creation of Coupling Interfaces (p. 36).
Data Transfers
A data transfer is the transfer of a single quantity type in one direction between the two sides of the
interface.
Because data transfers go in only one direction, associated participants and regions may still be
referred to as "source" and "target" when discussed in relation to a data transfer.
For more information, see Rules for the Creation of Data Transfers (p. 36).
For more information on supported data transfers, see System Coupling Data Transfer Quantit-
ies (p. 8).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 35
Using System Coupling's User Interfaces
• Interfaces are given default names according to the convention Interface-#, where the suffix -#
indicates the order in which the interfaces were created. For example, if three interfaces are created
for an analysis, they're named Interface-1, Interface-2, and Interface-3.
• An interface encompasses all data transfers between sets of regions on side One and side Two of
the interface.
• Each side of an interface must be associated with a unique participant and unique set of regions.
The same participant cannot serve as both side One and side Two of the same interface, and only
one interface can have a given combination of side One and side Two regions.
• An interface can be created between participant regions with different topologies (e.g., Planar
Surface and Volume).
– For data transfers between like topologies, both sides of the resulting interface must have regions
of the same topology. For example, if side One of the interface has surface regions, then side
Two of the interface must also have surface regions.
– For data transfers between unlike topologies, each side of the resulting interface can have regions
of a different topology. For example, side One can have volume regions and side Two can have
planar surface regions.
• For optimal mapping on an interface between regions of different topologies, the geometries must
be aligned. See Setting Geometry Transformations for Models with Different Orientations (p. 65).
• An interface must have at least one valid data transfer. See Rules for the Creation of Data Trans-
fers (p. 36) and System Coupling Data Transfers (p. 159).
• In a single interface, there can be multiple data transfers of different quantities in both directions.
Note:
For data transfer creation details applicable to all System Coupling contexts, see Rules
for the Creation of Data Transfers (p. 159)
When you create a data transfer (p. 59) in one of System Coupling's user interfaces, the following
rules apply:
• Data transfers are given default names according to the convention Transfer-#, where the suffix
-# indicates the order in which the interfaces were created. For example, if three interfaces are
created for an analysis, they're named Transfer-1, Transfer-2, and Transfer-3.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
36 of ANSYS, Inc. and its subsidiaries and affiliates.
Overview of System Coupling's User Interfaces
• Data transfer names can be duplicated within an analysis, but not within the same interface.
• A given target region can receive a quantity type only once (from any region in any interface).
• A given region cannot both send and receive the same quantity type. For example, the same region
cannot both send and receive temperature data.
• A target region can receive data from only a single source region. However, a given source region
can send data to multiple target regions.
• For a given source/target pair of regions, if a transfer of Heat Transfer Coefficient is defined, then
a transfer of Convection Reference Temperature must also be defined, and vice versa.
• A transfer of HTC+Tref is equivalent to a transfer of heat rate. If a transfer of Heat Transfer Coefficient
and Convection Reference Temperature is defined, then a transfer of Heat Rate cannot be defined,
and vice versa.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 37
Using System Coupling's User Interfaces
6. Disconnect the GUI from and then reconnect to the running analysis. (p. 93)
b. Review the participants results using the method(s) recommended in the participant product
documentation (e.g., CFD-Post).
c. Load coupled analysis results into ANSYS EnSight (p. 82) for postprocessing.
System Coupling performs the following steps to arrange participants into an ordered list:
1. Participants are divided into two sets: those that are sending Incremental Displacement and those that
are not, with the participants sending Incremental Displacements coming first.
This ensures that the final meshes are consistent on source and target participants at the end
of each iteration.
2. Within each of the two participant sets, the following order is applied:
a. Participants with a trailing index in their object names (e.g., FLUENT-1, MAPDL-2, AEDT-3, CFX-
4) are first in the list and are sequenced numerically by their indices.
Note:
When participants are added to the coupled analysis, the participant names are
automatically appended with a trailing index indicating the order in which parti-
cipants were added. Other participants appear next and are ordered alphabetically
by their object names.
b. Other participants appear next and are ordered alphabetically by their object names.
For coupled analyses where the participants will solve individually (the default behavior), participant
data transfers and solutions are executed in the sequence specified by the ordered list.
For coupled analyses where participants are grouped to solve at the same time (the behavior when
simultaneous solutions are enabled), additional sequencing steps are performed. For more information,
see Simultaneous Execution of Participant Solutions (p. 97).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
38 of ANSYS, Inc. and its subsidiaries and affiliates.
Working with System Coupling's Data Model
Settings are grouped and contained in paths in the data model. Items defined in the data model tree
are of two types: containers and settings.
Containers
Containers are used to organize the different branches of the data model and can contain other containers
and/or settings. There are two types of containers: singletons and object containers.
• Singletons are containers that may have multiple instances but can be defined only once within their
context. For example:
– The Coupling Control singleton has only one instance in the data model. Coupling control settings
are applied at the analysis level.
– Coordinate Transformation is a singleton that has multiple instances in the data model, with one
defined for each participant. Coordinate transformation settings are applied to all the regions of
the associated participant.
• Object Containers are containers that may have multiple instances of the same name and that can
contain multiple uniquely named objects. For example:
– There is only one Coupling Participant object container, and it contains multiple named participant
objects, such as MAPDL-1, CFX-2, etc.
There can be multiple instances of the Region and Variable object containers defined for
each coupling participant. They can contain one or more uniquely named region or variable
objects, respectively, for the associated participant.
A coupled analysis includes at least two participant objects and at least one interface object.
Settings
Settings are parameters that have values assigned with an equal sign.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 39
Using System Coupling's User Interfaces
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
40 of ANSYS, Inc. and its subsidiaries and affiliates.
Working with System Coupling's Data Model
Root-Level Containers
Under the root level of the data model, there are four main containers that control aspects of the
coupled analysis:
• Coupling Control
• Solution Control
• Coupling Participant
• Output Control
• Coupling Interface
Coupling Control
• Contains settings that define the coupled analysis and control its behavior.
• Includes settings for analysis type, duration controls, and step controls.
Solution Control
• Includes settings for simultaneous participant solutions and participant partitioning algorithms.
Coupling Participant
• Each participant object includes settings for participant type, execution and update controls, coordinate
transformations, regions, and variables.
Output Control
Coupling Interface
• Each interface object includes settings for mapping, interface sides, and data transfers.
For a comprehensive listing of all data model containers and settings, see the System Coupling Data
Model Settings section of the System Coupling Settings and Commands Reference manual.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 41
Using System Coupling's User Interfaces
>>> DatamodelRoot().CouplingControl.PrintState()
CouplingControl
AnalysisType:
Option = Transient
StepControl:
MaximumIterations = 5
TimeStepSize = 1.0 [s]
MinimumIterations = 1
DurationControl:
EndTime = 1.0 [s]
Option = EndTime
>>> DatamodelRoot().CouplingControl.AnalysisType.DurationControl.PrintState()
CouplingControl
AnalysisType
DurationControl
EndTime = 1.0 [s]
Option = EndTime
>>> DatamodelRoot().CouplingParticipant['CFX-1'].Region['wall'].PrintState()
CouplingParticipant:CFX-1
Region:wall
DisplayName = wall
InputVariables = Mesh Displacement,Temperature
OutputVariables = Total Force,Wall Adjacent Temperature,Wall Heat Transfer Coefficient,
Wall Heat Flow
Topology = Surface
>>> DatamodelRoot().CouplingInterface['Interface-1'].Side['One'].PrintState()
CouplingInterface:Interface-1
Side:One
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
42 of ANSYS, Inc. and its subsidiaries and affiliates.
Working with System Coupling's Data Model
CouplingParticipant = CFX-2
RegionList = plate
>>> DatamodelRoot().CouplingParticipant.GetChildNames()
['MAPDL-1', 'CFX-2']
>>> DatamodelRoot().CouplingParticipant['CFX-2'].Region.GetChildNames()
['wall', 'coupling']
If children exist for the object, then a list of the child names is returned. If children do not exist,
then an empty list ('[]') is returned.
Note:
When running a command with a for loop, in order to complete the loop, you must
hit the Enter key when presented with '…' in the command console.
CouplingInterface:Interface-1
Side:Two
CouplingParticipant = MAPDL-1
RegionList = FSIN_1
CouplingInterface:Interface-1
Side:One
CouplingParticipant = CFX-2
RegionList = coupling
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 43
Using System Coupling's User Interfaces
...
CouplingParticipant:MAPDL-1
Variable:INCD
QuantityType = Incremental Displacement
DisplayName = INCD
Location = Node
CouplingParticipant:MAPDL-1
Variable:FORC
QuantityType = Force
DisplayName = FORC
Location = Node
CouplingParticipant:MAPDL-1
Variable:FORC
QuantityType = Force
DisplayName = Force
1. From the Windows Start menu, select ANSYS 2020 R1 > System Coupling 2020 R1.
The System Coupling GUI opens. Because you are required to select System Coupling's
working directory before starting to populate the data model, the Select working directory
dialog opens immediately.
2. Navigate to the location that will be the working directory for the coupled analysis, select the directory,
and click Select Folder.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
44 of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling's Graphical User Interface (GUI)
The GUI opens and an instance of System Coupling is started. System Coupling runs in this
working directory and creates a SyC subdirectory for its coupling-related output.
The Select Folder dialog closes and the System Coupling GUI is shown. The location of the
working directory cannot be changed for the current session.
Note:
If the state of a previous coupling run has been saved to the SyC directory (i.e., there
are Settings and Results files), then System Coupling automatically loads that analysis
in its most recent state.
2. Run the System Coupling executable for the appropriate platform, using the -G or --gui command-
line option.
• Windows
> "%AWP_ROOT201%\SystemCoupling\bin\systemcoupling" -G
• Linux
$ "$AWP_ROOT201/SystemCoupling/bin/systemcoupling" -G
The System Coupling GUI opens. Because you are required to select a coupling working dir-
ectory before starting to populate the data model, the Select working directory dialog opens
immediately.
3. Navigate to the location that will be the working directory for the coupled analysis, select the directory,
and click Select Folder.
The GUI opens and an instance of System Coupling is started. System Coupling runs in this
working directory and creates a SyC subdirectory for its coupling-related output.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 45
Using System Coupling's User Interfaces
The Select Folder dialog closes and the System Coupling GUI is shown. The location of the
working directory cannot be changed for the current session.
Note:
If the state of a previous coupling run has been saved to the SyC directory (i.e., there
are Settings and Results files), then System Coupling automatically loads that analysis
in its most recent state.
Tip:
• To run a script on startup, you can use the -R command-line option. For more information
on this and other available options, see Command-Line Options in the System Coupling Settings
and Commands Reference.
• To control System Coupling's behavior for parallel runs, you can use the parallel startup op-
tions described in System Coupling Parallel Options in the System Coupling Settings and
Commands Reference manual.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
46 of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling's Graphical User Interface (GUI)
Menu Bar
The Menu Bar contains the File and Help menus.
Outline
The Outline pane provides a tree view for object-focused management of the System Coupling
workflow. This pane mirrors both the structure of the data model and the general sequence of steps
in a coupled simulation. It is divided into two main branches, Setup and Solution. Each of these has
child branches corresponding to the hierarchical organization of the data model's containers and
objects.
Setup
The Setup branch is used to define data model content, including the addition of new objects as
part of the setup process.
Solution
The Solution branch is used to control the execution of the coupled analysis — to start the solution,
to interrupt or abort it once started, and to open EnSight results once completed.
Parent branches can be expanded to show child branches, which may correspond to singleton con-
tainers, object containers, or objects. Parent branches with child containers can be expanded/collapsed
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 47
Using System Coupling's User Interfaces
to show their child containers. Settings under a parent branch are not represented in the tree but
are shown in the Properties (p. 48) pane when the parent branch is selected.
Setup issues that cause data model invalidation are noted on the Messages tab.
Properties
The Properties pane shows the settings associated with the object/branch selected above in the
Outline, with the setting's name on the left and its value on the right. You can edit setting values by
selecting or multi-selecting options from a drop-down menu and by typing new values into a text
field.
For settings with text fields, invalid entries are indicated by red highlighting of the field and/or by
messages on the Messages tab.
Tabs
When a tab is selected, its contents are shown in the area below the tab. The System Coupling GUI
has the following tabs:
Messages
Displayed by default. The Messages tab shows a list of error and warning messages in descending order
by severity (i.e., the most severe issue is at the top). If there are any active error messages, the Solve
option (for the Solution branch in the Outline) is disabled.
Command Console
The Command Console tab is a Python console that enables you to interact with the data model via
command line. The console is divided into two sections:
• the body of the tab, which shows standard System Coupling output resulting from actions taken in
the GUI
• the bottom the tab, with a Command Input area featuring a command line for entering and running
Python commands
Note:
Tip:
System Coupling uses Python 3.7. To use the command console effectively, you should
have some familiarity with working from your operating system command prompt and
a basic knowledge of the Python language. For more information, see the resources
published by the Python Software Foundation.
Status Area
Indicates the status of the coupled analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
48 of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling's Graphical User Interface (GUI)
• On the left side, a status message indicates the status of the System Coupling engine. Possible
messages are shown in the table below:
Message Description
Ready System Coupling is waiting for input.
Busy System Coupling is busy (but not actively solving).
Solving System Coupling is solving.
• In the center, additional messages provide further details about the reported status. For instance,
it indicates when System Coupling is waiting for participants to connect, when participants have
been connected, the percentage of the analysis that's been completed, when the analysis has been
stopped and for what reason, etc.
• On the right side, a progress bar shows the progress of the running solution.
Menu-Bar Menus
The Menu Bar contains the File and Help menus.
Available menu options for each are shown in the tables below:
Option Description
Enabled if Settings and Results files exist in System Coupling's SyC
directory. Opens an existing co-simulation at the specified step.
After selecting this option, select the step at which you want to
open the co-simulation. System Coupling locates the corresponding
restart files from the SyC directory.
Open at step
For more information, see Restarting a Coupled Analysis (p. 88).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 49
Using System Coupling's User Interfaces
Option Description
After selecting this option, select the iteration at which you want to
open the co-simulation. System Coupling locates the corresponding
restart files from the SyC directory.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
50 of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling's Graphical User Interface (GUI)
Option Description
After participants are disconnected, System Coupling writes timing
details to the Transcript and Log. If participants were started
automatically, it ends participant processes.
Option Description
System Coupling User's Guide Opens the System Coupling User's Guide.
Settings and Commands Ref- Opens the System Coupling Settings and Commands
erence Reference manual.
Opens the System Coupling Participant Library
Participant Library
documentation.
Tutorials Opens the System Coupling Tutorials page.
Beta Features Opens the System Coupling Beta Features documentation.
Release Notes Opens to the System Coupling release notes page.
Opens a dialog containing product copyright, version,
About
and build information.
Context Menus
When additional actions are available for an item in the Outline pane's tree view, they are available
as options in the corresponding context menu. Context options can be accessed by right-clicking
the Setup branch, the Solution branch, and many of the items defined under them.
Unless otherwise noted, the context options listed in this section are available and enabled when
the specified branch/data model item exists.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 51
Using System Coupling's User Interfaces
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
52 of ANSYS, Inc. and its subsidiaries and affiliates.
Using the System Coupling Command-Line Interface (CLI)
1. Open the shell for your operating system in System Coupling's working directory.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 53
Using System Coupling's User Interfaces
Note:
• To run a script on startup, you can use the -R command-line option. For more information,
see Command-Line Options.
• If you want to start System Coupling in parallel execution mode, use the parallel startup
options described in Parallel Options for System Coupling (p. 117).
• Windows
> "%AWP_ROOT201%\SystemCoupling\bin\systemcoupling"
• Linux
$ "$AWP_ROOT201/SystemCoupling/bin/systemcoupling"
The command prompt says, "Starting Command Console...", indicating that System
Coupling has started.
Note:
• System Coupling uses Python 3.7. To use the command console effectively, you should have
some familiarity with working from your operating system command prompt and a basic
knowledge of the Python language. For more information, see the resources published by the
Python Software Foundation.
• All sub-processes that are manually started from within the command console will make use
of the system environment that is setup for that console. Review and edit the environment
passed to such sub-process if you encounter any problems with their execution.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
54 of ANSYS, Inc. and its subsidiaries and affiliates.
Preparing for a Coupled Analysis
Descriptions of the available options will be written to the CLI, which will then close. To start System
Coupling, you must run the executable again without the -h or --help option.
Available startup options are described in Command-Line Options in the System Coupling Settings and
Commands Reference.
>>> help(Initialize)
Help on function Initialize:
Initialize(**kwds)
Description :
Essential arguments :
Available commands are described in Commands in the System Coupling Settings and Commands
Reference.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 55
Using System Coupling's User Interfaces
Serves as the working directory for the coupled analysis and is System Coupling's run directory.
This is where System Coupling:
• Automatically creates the SyC subdirectory for its own output files:
– Automatically creates a Results subdirectory for its EnSight-compatible output files (p. 82).
Each ANSYS participant should write its solver input and System Coupling Participant (SCP)
setup files to this directory. When this is done, the <WorkingDirectory> definition in
the SCP file is set to the relative path to this location. (If the working directory is not defined,
the coupled analysis working directory is used by default.)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
56 of ANSYS, Inc. and its subsidiaries and affiliates.
Preparing for a Coupled Analysis
• Writes and accesses its solver input files (e.g., CAS, DAT, DEF, and FTSIM files)
Note:
• If you change the location of a participant's working directory, you must edit
its WorkingDirectory definition to reflect the new location.
• If you change the location of an SCP file, you must specify its new filepath when
referencing it in commands or scripts.
During the coupled analysis, System Coupling manages participant solutions. However, you should
ensure that each participant can solve successfully on its own before being included in the coupled
analysis.
Note:
• When using same material(s) in multiple participants, take care to ensure that common
properties are consistently defined, as described in Additional Participant Setup Consider-
ations (p. 58).
• Directory paths and object names (for interfaces, participants, regions, and variables) must
be in ASCII format. Object names also cannot include forward slashes (/) or the colon
character (:).
For suggestions on how to ensure that your coupled analysis runs smoothly, see Building Up to
a Coupled Analysis (p. 211).
• For CFX and Fluent, this involves creating one or more boundary conditions.
• For Forte, this involves selecting the Enable System Coupling check box for one or more boundary
conditions.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 57
Using System Coupling's User Interfaces
• For Maxwell, this involves setting the solution type, selecting a frequency (for eddy-current solutions),
defining co-simulation start and end times (for transient solutions), ensuring that bodies to receive
thermal data are made of temperature-dependent material properties, and creating a creating a System
Coupling Setup.
For more information on a given participant's settings, use the links in Supported Coupling Parti-
cipants (p. 34) to access its documentation.
Important:
Depending on the type of analysis you're setting up, additional participant physics or
coupling setup steps may be required. For more information, see Additional Participant
Setup Considerations (p. 58).
For example, if heat rate and temperature values are to be transferred between an electromag-
netic solver and a thermal solver, both models must be made of materials that allow for temper-
ature-dependent properties (e.g., electrical conductivity and thermal conductivity, respectively).
• Rotating bodies: Ensure that motion/rotation is defined for all bodies that will move or rotate during
the co-simulation.
• Stationary bodies: Ensure that stationary bodies will not move from the reference position or parti-
cipate in multiple reference frames during the co-simulation.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
58 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
If you later move the solver input file, then you must edit the <WorkingDirectory> element
in the participant's SCP file so it refers to the file's new location.
Participant Setup files (for an analysis set up in a System Coupling user interface)
Note:
For a coupled analysis set up in System Coupling's GUI or CLI, a System Coupling Participant (SCP)
setup file is needed for each coupling participant to be started automatically. It is generated as
follows:
• If coupling and/or automatic SCP-file generation are enabled for a participant, then the participant
automatically generates the SCP file (and any other configuration files needed by System Coupling)
at the same time and in the same location as its solver input file.
• If coupling and/or automatic SCP-file generation are not enabled for a participant, then you can
generate the SCP file on demand using the method noted in the participant's product documentation.
• If you later move a participant's SCP file, no edits to the <WorkingDirectory> element in the file
are necessary.
For details on the contents and generation of SCP files, see Participant Setup File (*.scp) (p. 179).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 59
Using System Coupling's User Interfaces
The participant's display name (defined by the <DisplayName> element of its SCP file) is used, if
available. Otherwise, the internal object name assigned by System Coupling is used. Internally, parti-
cipants are named according to the convention <Participant #>, where "Participant" is the Participant
Type and the suffix "#" is an index indicating the order in which the participant was loaded.
1. In the Outline pane's tree view, right-click the Setup branch and select Add Participant.
By default, this directory is filtered to show all file types that can be used to add the participant
to the coupled analysis: Setup files Participant Setup files (.scp ) and Forte input files (.ftsim).
The Coupling Participant object container is added to the tree, with the Coupling Participant
# object defined underneath it.
Tip:
Once the Coupling Participant container is available, you can right-click it and select
Add Participant to add another participant object.
When the participant is selected in the tree, its Participant Type is shown in the Properties pane.
LoadParticipants
To load multiple participant definitions, run the LoadParticipants command, setting the Input-
Files argument to a list of the participants' setup files.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
60 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
AddParticipant
To add a single coupling participant, you can also run the AddParticipant command, setting the
InputFile argument to the participant's setup file.
When the command is run, the CouplingParticipant object container is added to the data
model, with the CouplingParticipant-# object(s) defined underneath it.
Interface names must be unique within the coupled analysis. When coupling interfaces are added,
they are assigned default names according to the convention <Coupling Interface #>, where the
suffix "#" indicates the order in which the interfaces were created. For example, if three interfaces are
created, they're named Coupling Interface 1, Coupling Interface 2, and Coupling Interface 3.
Note:
The same rules apply to the creation of interfaces in both the GUI and the CLI. For more
information, see Rules for the Creation of Coupling Interfaces (p. 36).
1. In the Outline pane's tree view, right-click the Setup branch and select Add Coupling Interface.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 61
Using System Coupling's User Interfaces
The Coupling Interface container is added to the tree, with the Coupling Interface # object
defined underneath it.
Note:
Once the Coupling Interface container is available, you can right-click it and select
Add Interface to add another interface object.
Two objects representing the sides of the interface, called One and Two, are defined under Side.
3. Review the settings for the interface sides by clicking each of the side objects in turn. The following
settings are shown in the Properties pane, with values populated from the participant setup files:
Coupling Participant: Specifies the participant associated with the interface side.
Region List: Specifies the participant region(s) to be used in data transfers involving the parti-
cipant.
At this point, the values are the same for sides One and Two. By default, both sides are populated
with the information from the first participant added to the analysis. For the data model to be
valid, a different participant must be specified for each side.
4. Specify details for the interface sides, selecting a Coupling Participant and Region List from the drop-
down menus for both One and Two.
Important:
To add a coupling interface, run one of the commands as shown in the examples below:
Example 12: Run AddInterface to add an interface using internal participant and region
names
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
62 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
SideTwoParticipantName = ["MAPDL-2"],
SideTwoRegionNames = ["FVIN_1"])
When the command is run, the CouplingInterface object container is added to the data model,
with the CouplingInterface-<#> object defined underneath it.
Data transfer names must be unique within an interface. When data transfers are added to an interface,
they are assigned default names according to the convention <Data Transfer #>, where the suffix
"#" indicates the order in which the data transfers were created. For example, if two data transfers
are created for each of two interfaces, each interface will have a Data Transfer 1 and a Data Transfer
2.
Note:
The same rules apply to the creation of data transfers in both the GUI and the CLI. For
more information, see Rules for the Creation of Data Transfers (p. 36).
Tip:
Data transfer settings can be adjusted to stabilize the solution and address convergence
issues. For information on stabilization methods that can be applied at the data-transfer
level, see:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 63
Using System Coupling's User Interfaces
1. In the Outline pane's tree view under Coupling Interface, locate the interface object (Coupling Interface
<#>) on which the data transfer is to be created.
The Data Transfer branch is added to the tree, with the Data Transfer <#> object defined un-
derneath it.
3. Click the data transfer object to review its settings and change, if necessary.
The following data transfer settings are shown in the Properties pane, with values populated
from the participant setup files:
• Target Side: Specifies the interface side that will receive the transferred data. Possible values
are One and Two. Default value is One.
• Side One Variable: Automatically populated with the variable for the participant associated
with side One of the interface. (If Target Side is set to One, then this is the participant's input
variable; if set to Two, then this is the participant's output variable.)
• Side Two Variable: Automatically populated with the variable for the participant associated
with side Two of the interface. (If Target Side is set to One, then this is the participant's output
variable; if set to Two, then this is the participant's input variable.)
• Ramping Option: Specifies the ramping option to be applied. Default value is None.
• Relaxation Factor: Specifies the relaxation factor to be applied if ramping is used. Default value
is 1.
• Convergence Target: Specifies the convergence target for the data transfer. Default value is
0.01.
4. Under the data transfer object, click Stabilization to review solution stabilization settings and to change
if needed.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
64 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
After creating data transfers, you can run the GetErrors command to verify that no errors were
introduced.
Important:
To add a data transfer, run one of the commands as shown in the examples below:
Example 14: Run AddDataTransfer to add a data transfer using internal variable names
When the command is run, the DataTransfer object container is added to the data model, with
the DataTransfer-<#> object defined underneath it.
To create a coupling interface in an analysis involving models with different orientations, the participant
geometries must be aligned (e.g., the rotor and stator in a motor simulation are in same relative po-
sition). To move the geometries into the same reference orientation, use a participant's Coordinate
Transformation data model settings to change its origin and coordinate axes system. Transformations
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 65
Using System Coupling's User Interfaces
Note:
Currently, the Coordinate Transformation settings are available only for scalar data
transfers.
Geometry transformations must be defined before the analysis is initialized. Transformations defined
or modified afterward will not be reflected in the analysis. Additionally, participants for which trans-
formations are applied may not be involved in data transfers involving vector quantities. A
datamodel validation error will be reported if this condition is encountered.
Transformation angles are defined as Euler angles, as described in Rotational Order of Coordinate
System Results in the Mechanical User's Guide and as illustrated by Figure 3.2 Euler Rotation angles
in the Mechanical APDL's Modeling and Meshing Guide.
For more information about participant transformations, see Coupling Control in the System Coupling
Settings and Commands Reference manual.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
66 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
Coupling Participant
Important:
Settings that are not noted in this section are set by System Coupling and/or the coupling
participants. These are typically not edited manually — and if edited at all, care should
be taken to not invalidate the data model.
For a comprehensive listing of all available settings, see the System Coupling Data
Model Settings section of the System Coupling Settings and Commands Reference manual.
Coupling Control
Settings defined under the root-level Coupling Control singleton control the behavior of a
coupled analysis.
Option
Setting that specifies whether the analysis will be a co-simulation (both solvers running at the
same time).
Analysis Type
Singleton containing settings that define details about the analysis. The following settings are
available:
Option
Defines the type of analysis to be run.
Possible values:
• Steady: Used when all participants are running a steady or static solution. Default value if Ana-
lysis Type is undefined.
When this value is used and none of the participants has Participant Type set to AEDT,
CFX, FLUENT or MAPDL, then only one coupling step is allowed.
• Transient: Used when any participant is running a transient solution (includes mixed steady-
transient analyses).
Duration Control
Singleton containing settings that define the duration of the analysis. The following settings are
available:
Option
Specifies how the duration of the analysis is defined.
Possible values:
• Number of Steps: Used when the Analysis Type / Option is set to Steady. System
Coupling executes coupling steps until the specified number of steps is reached.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 67
Using System Coupling's User Interfaces
• End Time: Available when the Analysis Type / Option is set to Transient. System
Coupling executes coupling steps until the specified end time is reached.
In this type of transient analysis, each coupling step is a time step, with the time
interval specified by the step size. The final coupling step size is reduced automat-
ically, if needed, so that the specified end time is respected.
Note:
Some participant systems, such as ANSYS Mechanical, require that the end
time specified in their setup to be respected. When a coupled analysis involves
one or more participants that require their setup's end time be respected, then
the maximum allowable end time for the coupled analysis is the minimum of
the end times reported by such participants. In this case, a validation error is
reported if the coupled analysis' specified end time is greater than the minimum
identified.
Other participant systems, such as ANSYS CFX, can run past the end time
specified. These participant systems have no effect on the allowable end time
of the coupled analysis.
Number of Steps
Available when the Duration Control / Option is set to Number of Steps. Defines the number
of steps to be executed by System Coupling.
End Time
Available when the Duration Control / Option is set to EndTime. Defines the end time for the
coupled analysis run.
Accepts decimal values greater than or equal to 0.0 and requires units of [s]. Default value
is 1.0[s].
Step Control
Singleton containing settings that define the coupling steps of the analysis.
The duration of the coupled analysis is broken into a sequence of coupling steps. Data
transfers between the coupled solvers occur at the beginning of each coupling iteration
within a coupling step. Coupling steps are always indexed. During the analysis, each new
coupling step is started when:
• either the maximum number of coupling iterations has been reached or the coupling step has
converged.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
68 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
If the coupling is defined in terms of time (a transient analysis), then a coupling step is
associated with a time interval. The Time Step Size setting specifies the time interval
associated with each coupling step (in seconds). If the Duration Control / Option is set
to End Time, the final coupling step size is reduced automatically, if needed, so that the
specified end time is respected.
The coupling step size is fixed for the duration of the coupled analysis, but it can be
changed when restarting the analysis.
Accepts decimal values greater than or equal to 0.0 and requires units of [s]. Default value
is 1.0[s].
Minimum Iterations
Defines the minimum number of iterations per coupling step.
Maximum Iterations
Defines the maximum number of iterations per coupling step.
Solution Control
Settings defined under the root-level Solution Control singleton control analysis-level solution
settings.
Possible values:
For more information, see Simultaneous Execution of Participant Solutions (p. 97).
Partitioning Algorithm
Used to partition participants for parallel runs. Specifies the name of the partitioning algorithm to
be applied to coupling participants.
The algorithms allow for both shared and distributed execution and for the allocation of
machines or cores. The default value is generally the best choice, as it allows for each parti-
cipant to take advantage of all the allocated resources. The other partitioning methods are
provided to handle situations where not enough resources are available to run the same
machines.
Possible values:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 69
Using System Coupling's User Interfaces
For more information, see Parallel Processing for Coupling Participants (p. 103).
Output Control
Settings defined under the root-level Output Control singleton control the generation of coupled
analysis output.
Option
Available only when all coupling participants support restarts.
Possible values depend on they type of analysis being run and the coupling participants in-
volved. For information on the conditions that determine this, see Results Files (Res-
ults_*#.h5) (p. 207).
• For transient analyses or steady-state analyses with one or more participants of type AEDT, CFX,
FLUENT, or MAPDL, possible values are:
– Last Step: System Coupling generates a restart point only for the last coupling step completed.
(default value)
– Every Step: System Coupling generates a restart point at the end of every coupling step.
– Step Interval: System Coupling generates a restart point at the end of coupling steps at the
interval specified by the Output Frequency setting.
• For steady-state analyses that do not have participants of type AEDT, CFX, FLUENT, or MAPDL,
possible values are:
– Last Iteration: System Coupling generates a restart point only for the last coupling iteration
completed. (default value)
– Every Iteration: System Coupling generates a restart point at the end of every coupling iteration.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
70 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
– Iteration Interval: System Coupling generates a restart point at the end of coupling iteration
at the interval specified by the Output Frequency setting.
Note:
This setting also controls the frequency with which EnSight-compatible coupling
output is generated. For more information, see Postprocessing Coupling Results
in ANSYS EnSight (p. 82).
Tip:
Output Frequency
Available when the Output Control / Option is set to Step Interval or Iteration Interval. Specifies
the frequency with which restart points are generated.
For example, with a value of 2, System Coupling generates a restart point at the end of every
other iteration.
Coupling Interface
Settings defined under the root-level Coupling Interface object container control the details for
data transfers.
Data Transfer
Data transfer objects are assigned default names according to the convention Transfer-<#>,
where the suffix "#" indicates the order in which the data transfers were created. For example, if
three data transfers are created for an analysis, they're named Transfer 1, Transfer 2, and
Transfer 3.
Data transfer object names can be duplicated within an analysis but must be unique within an
interface. They must be in ASCII format and cannot include forward slashes (/) or the colon
character (:).
Convergence Target
Specifies the RMS-based target value used when evaluating convergence of the specified quantity
within a coupling iteration.
For information on how this target is applied, see Evaluating Convergence of Data Trans-
fers (p. 157).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 71
Using System Coupling's User Interfaces
Ramping Option
Determines the behavior of the ramping algorithm for specified quantity.
Ramping is used by System Coupling to slow the application of the source-side value on the
target side of the interface.
Possible values:
• None
No ramping is applied; the full data transfer value is applied to the target side of the inter-
face for all coupling iterations. (default value)
• Linear
Within each coupling step, the ramping factor is used to linearly increase the change in
the data transfer value applied to the target side of the interface. The data transfer value
is increased during each coupling iteration until the specified minimum number of coupling
iterations, , is reached. The ramping factor is applied to the change in the data transfer
value from the last coupling iteration of the previous coupling step. If there is no change
in this value from the last coupling step, the full data transfer value is applied to the target
side of the interface for all coupling iterations of that coupling step.
Relaxation Factor
Specifies the factor multiplying the current data transfer values for specified quantity when under-
relaxing them against the previous values.
Stabilization
Singleton containing settings that control the application and behavior of Quasi-Newton stabilization
methods to the parent data transfer.
Option
Specifies whether Quasi-Newton stabilization is applied to the data transfer. Possible values:
When the Stabilization / Option is set to Quasi-Newton, the following settings are also
available:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
72 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
Note:
For unsteady simulations, if Maximum Retained Time Steps is set to 1, then the
specified relaxation factor is applied at the start of every coupling step. Otherwise, it
is applied only to the first coupling step.
Coupling Participant
Settings defined under the Coupling Participant object control details about the participant.
Important:
Available when Participant Type is set to a value other than EXTERNAL DATA.
Values are populated from the <ExecutionControl> (p. 180) element of the participant's
SCP file. When this element is omitted from the SCP file, values are populated by System Coupling
based on the Participant Type.
Option
Specifies how System Coupling finds the solver executable file to be used to start the participant.
Possible values:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 73
Using System Coupling's User Interfaces
• Program Controlled: Available when Participant Type is set to a value other than DEFAULT
or EXTERNAL DATA. System Coupling finds the executable file based on the participant
type. (default value)
Note:
• User Defined: System Coupling does not automatically find the executable based on par-
ticipant type. When selected, if Participant Type is set to a value other than EXTERNAL
DATA, then System Coupling runs the file specified by the Executable setting.
• Externally Managed: Used for workflows involving execution via System Coupling in
Workbench. Denotes that the startup and shutdown of the participant are managed extern-
ally (that is, not by System Coupling) and that System Coupling expects the participant to
be available before the start of the run.
Note:
This option is available but not recommended for runs in System Coupling's
GUI or CLI.
Executable
Available when the Execution Control / Option is set to User Defined.
Specifies the path and filename of the solver executable file to be used to start the participant.
Default value is None.
Working Directory
Specifies the participant's working directory.
Value is the directory defined by the <WorkingDirectory> (p. 181) element of the
participant's SCP file. If not defined, value is System Coupling's working directory.
Initial Input
Solver input file to be used for the initial coupling run.
Value is the file specified by the <InitialInput> (p. 181) element of the participant's
SCP file. Unless another path is specified, System Coupling looks for this file in the directory
specified by the Working Directory setting.
If a .jou file is specified as the initial input for Fluent, then System Coupling uses this
journal script instead of writing one of its own. In all other instances, it generates its default
.jou file.
Parallel Fraction
Used to partition resources across coupling participants that are running in parallel. Specifies the
core count or fraction of compute resources to be allocated to the participant.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
74 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
For more detailed information on how these fractions are applied, see Resource Allocation
Fractions (p. 106).
Additional Arguments
Arguments to be appended to the participant's executable.
Additional arguments are not specified by the SCP file. Some participants populate this setting
with default values; for details, see the participant's product documentation. Additional argu-
ments can also be issued via the CLI or the GUI's Command Console tab.
When solver-specific parallel customizations are needed, you may use this method instead
of System Coupling's participant partitioning functionality. For more information on using
parallel additional arguments, see Parallel Processing for Coupling Participants (p. 103).
Update Control
Settings defined under the Update Control singleton control the frequency with which the par-
ticipant performs updates during the execution of a coupled analysis.
Tip:
These settings are particularly useful for mixed steady-transient analyses. Specifically,
moderating updates of the steady participant can significantly reduce execution time,
with a modest effect on transient accuracy.
Note:
Every participant performs an update during the first iteration of each run (i.e., during
the first step of both initial and restarted coupling runs), regardless of its Update
Control settings.
The following settings are defined under the Update Control singleton:
Option
Specifies how often the participant will perform updates.
Possible values:
• Program Controlled: Participant updates are always enabled. The participant performs an update
during every coupling iteration. (default value)
This option is active by default. To change this behavior, you must explicitly set Option to
another value.
• Every Iteration: Participant updates are always enabled. The participant performs an update
during every coupling iteration.
This option behaves the same as the Program Controlled option but is explicitly set.
• Step Interval: Available only for AEDT participants. The participant performs an update during
coupling steps at the interval specified by the Update Frequency setting.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 75
Using System Coupling's User Interfaces
• Suspended: Available only for AEDT participants. Participant updates are suspended until you
set another value.
Note:
If under-relaxation is applied to data transfers for which AEDT is the source, the
target values may still be updated during suppressed steps.
Tip:
Support for the Step Interval, Suspended, and Update Frequency options for
all participants is available as beta functionality. For more information, see Parti-
cipant Update Control Settings in the System Coupling Beta Features document-
ation.
During coupling steps in which updates for a participant are suppressed (via either the Step
Interval or the Suspended option), the participant also doesn't engage in data transfers,
either as a sender or receiver. Non-suppressed participants continue to work from the data
obtained from the suppressed participant's last update.
Update Frequency
Available when the Update Control / Option is set to Step Interval. Specifies the interval at which
the participant executes its updates.
For example, with a value of 5, the participant performs an update during every fifth coupling
step: 5, 10, 15, etc. (This is in addition to the standard update for the first coupling step of
every run.)
Coupling Control
Settings defined under the Coordinate Transformation singleton allow you to define coordinate
transforms to control the positioning of the participant's geometry. When a transformation is
defined for a participant, it is applied to all the participant's regions
Note:
Currently, the Coordinate Transformation settings are available only for scalar data
transfers.
The following settings are defined under the Coordinate Transformation singleton:
Option
Specifies whether a transformation is defined for the coordinate system of the participant's geometry.
Possible values:
• None: No coordinate transformation is defined. Default value. Only possible value if a data
transfer of vector quantities exists for the participant.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
76 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
• New Origin and Rotations: A coordinate transformation is defined. The transformed coordinate
system is defined according the values of the Origin, Rotation XY, Rotation YZ, and Rotation
ZX settings.
Origin
Available when the Coordinate Transformation / Option is set to New Origin and Rotations.
Defines the new origin for the transformed coordinate system.
Accepts a real triplet (i.e., accepts a real value for each Cartesian coordinate) which defines
the new coordinates of the origin point. Must be defined in SI units [m]. Default value for the
triplet is 0.0, 0.0, 0.0 [m].
Rotation XY
Available when the Coordinate Transformation / Option is set to New Origin and Rotations.
Defines the participant's angle of rotation in degrees from the XY plane of the coordinate system.
The transformation angle is defined as a Euler angle, the XY plane around the Z axis as the
first rotation in the definition. (Rotations are applied in the following order: XY, Y1Z1, Z2X2.
For an illustration, see Figure 3.2 Euler Rotation angles in Mechanical APDL's Modeling and
Meshing Guide.)
Accepts real values with units of either degrees or radians. Default value is 0.0 [deg].
Note:
• If the unit is left unspecified when the value is changed, then radians are used.
• When a rotation setting value is changed, its unit is automatically applied to rotation
settings with unchanged values.
Rotation YZ
Available when the Coordinate Transformation / Option is set to New Origin and Rotations.
Defines the participant's angle of rotation in degrees from the Y1Z1 plane of the transformed coordin-
ate system.
The transformation angle is defined as a Euler angle, with the rotation of the transformed
Y1Z1 plane around the X1 axis as the second rotation in the definition. (Rotations are applied
in the following order: XY, Y1Z1, Z2X2. For an illustration, see Figure 3.2 Euler Rotation angles
in Mechanical APDL's Modeling and Meshing Guide.)
Accepts real values with units of either degrees or radians. Default value is 0.0 [deg].
Note:
• If the unit is left unspecified when the value is changed, then radians are used.
• When a rotation setting value is changed, its unit is automatically applied to rotation
settings with unchanged values.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 77
Using System Coupling's User Interfaces
Rotation ZX
Available when the Coordinate Transformation / Option is set to New Origin and Rotations
Defines the participant's angle of rotation in degrees from the Z2X2 plane of the transformed co-
ordinate system.
The transformation angle is defined as a Euler angle, with the rotation of the transformed
Z2X2 plane around the Y2 axis as the third rotation in the definition. (Rotations are applied
in the following order: XY, Y1Z1, Z2X2. For an illustration, see Figure 3.2 Euler Rotation angles
in Mechanical APDL's Modeling and Meshing Guide.)
Accepts real values with units of either degrees or radians. Default value is 0.0 [deg].
Note:
• If the unit is left unspecified when the value is changed, then radians are used.
• When a rotation setting value is changed, its unit is automatically applied to rotation
settings with unchanged values.
Important:
Settings that are not noted in this section are set by System Coupling and/or the coupling
participants. These are typically not edited manually — and if edited at all, care should
be taken to not invalidate the data model.
For a comprehensive listing of all available settings, see the System Coupling Data
Model Settings section of the System Coupling Settings and Commands Reference manual.
For information on changing the values of data model settings in a given interface, see:
Changing Data Model Setting Values in the GUI
Changing Data Model Setting Values in the CLI
Each of the branch's settings is shown in the Properties pane, with its setting name in the left
column and its value to the right.
2. In the Value column, change the setting value according to the type of field:
a. Select the new value(s) from a drop-down menu. Only valid options — both in terms of value
and number — are available.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
78 of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
b. Type the new value into the text field. Red highlighting of a field indicates a missing value for a
required setting.
Changes are applied to the data model immediately. Resulting validation warnings and errors are
shown on the Command Console tab.
The change is applied to the data model when you run the command.
To verify a value change for a single setting, enter the path again (without the value) and run it.
This returns the current value of the setting.
To verify value changes for multiple settings, use PrintState method on the settings' container
(as described in Viewing a Container's Contents (p. 42)).
To enable an expert setting, run the SetExpertSettings command in the CLI or on the GUI's
Command Console tab, using a dictionary to specify the setting and its associated value.
For example, the code below enables a setting that allows you to set the initial value for variables of
a given quantity:
Example 17: Enable and specify a value for the source participant's initial Heat Transfer
Coefficient value
For details on available expert settings, see Expert Settings in the System Coupling Settings and Com-
mands Reference guide.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 79
Using System Coupling's User Interfaces
GLOG_log_dir
Path to the directory where System Coupling directs its debug output files. If not set, debug output files
are written to the current directory.
GLOG_v
Controls the level of detail to be included in the debug files written by System Coupling. Accepts integer
values 0 through 5, with a value of 0 generating no output and larger numbers generating more detailed
output. For information on the output generated, see Debug Output (p. 206).
sysc_GLOG_MXARRAYELMS
Controls the maximum number of array entries in the debug output when the GLOG_v environment
variable is set to a value of 3 or higher. Default value is 5.
Note:
System Coupling does not support an interactive mode for participants during coupled
analysis runs.
Note:
This option becomes enabled only when the coupled analysis setup is completed and
free of errors.
Tip:
If you wish to pause the solution at designated points during the run — for example, to
review the solution's progress and adjust settings if needed — you can do this using either
of the following methods:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
80 of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis
• Use the Solution branch's Interrupt solve context option to pause execution. For more inform-
ation, see Stopping a Coupled Analysis in the GUI (p. 87).
• Use System Coupling's interactive commands. For more information, see Using Interactive
Solve Commands (p. 95).
>>> Solve()
Tip:
If you wish to pause the solution at designated points during the run — for example, to
review the solution's progress and adjust settings if needed — System Coupling provides
a set of interactive commands that enable you to do so. For more information, see Using
Interactive Solve Commands (p. 95).
If any participants fail to connect, then System Coupling generates messages which indicate:
• the names of the participants that have not yet connected; and
• the time elapsed since the request for participant connections (i.e., since the participants were started,
or the solution was initialized or started).
These messages are written to the Transcript/Log at the following intervals: 5 minutes, 10 minutes,
30 minutes, 1 hour, 2 hours, and 10 hours.
Tip:
A Coupling Control / Connection Timeout data model setting that allows you to control
how long System Coupling waits for participant connections is available as beta function-
ality. For more information, see Participant Connection Timeout Setting in the System
Coupling Beta Features documentation.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 81
Using System Coupling's User Interfaces
• review the Transcript/Log file and any supplemental diagnostic files you've requested;
• load System Coupling's results into ANSYS EnSight for visualization, animation, and postprocessing.
Note:
This documentation assumes that you have already installed and configured EnSight as
described in the "Necessary Prerequisites" section of the Getting Started with ANSYS EnSight
guide.
Server-of-Servers file:
A Results.sos Server-of-Servers file is written at the beginning of the analysis, prior to the execution
and completion of the first coupling step. Because it contains all the data for the analysis — i.e., it
references all the relevant output files, including the case files for all processors used to execute the
solution — it is recommended that you use this file to load coupling results into EnSight.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
82 of ANSYS, Inc. and its subsidiaries and affiliates.
Reviewing Coupled Analysis Output and Results
Case files:
Case files have a .case extension. At the beginning of the analysis, prior to the execution and com-
pletion of the first coupling step, a single Case file is written for each processor used to execute the
solution and given a filename with an index indicating the associated processor. Each file contains
only the data generated by that processor.
Filenames file:
EnSight's Filenames file is named Results.filenames. Individual file that tells EnSight how
to complete the filenames.
Time file:
EnSight's Time file is named Results.time. Individual file that provides the time (in seconds)
for transient runs.
For more detailed information on these files, see ANSYS EnSight Gold–Formatted Results Files (p. 208).
Note:
• For coupled analyses with participants that do no support restarts, EnSight files are generated
only at the end of the analysis, independently of the restart settings (Output Control). If
beta settings are used to change the EnSight output frequency (Output Control / Results),
then EnSight files are generated independently of the restart frequency or participant restart
capabilities.
• To disable the automatic generation of EnSight output, enable beta features and set the
Output Control / Results / Option to Off.
Tip:
When a coupled analysis is restarted, System Coupling reads the contents of the Results
folder and overwrites the output files for timesteps beyond the initial step of the restarted
run, as well as the EnSight Server-of-Servers, Case, Filenames, and Time files. To postpro-
cess timesteps beyond the step opened for a restart, back up or rename the Results
directory before reopening the case in System Coupling.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 83
Using System Coupling's User Interfaces
1. In the co-simulation working directory, navigate to the SyC/Results subdirectory and open a
prompt for your operating system.
Note:
EnSight must be run from this directory. Opening the prompt in another directory
and specifying the path to the Results.sos file will not work.
2. Execute the platform-appropriate command, using the -sos argument and specifying the name
of the SOS Results file, as shown in the examples below.
• Windows
• Linux
The EnSight GUI opens with the coupling results already loaded.
To verify the connection, click Information in the tools bar at the bottom of EnSight's desktop.
The Message Window dialog opens. If the connection was successful, then the text "Connection
accepted" is displayed at the top of the dialog.
Parts
The Parts pane is a table populated with model parts (i.e., coupling regions) based on the mesh
and associated surfaces defined in the coupled data files.
Each coupled analysis loaded into EnSight as a case, named "Case" with an index indicating its order
in the loading sequence.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
84 of ANSYS, Inc. and its subsidiaries and affiliates.
Reviewing Coupled Analysis Output and Results
Below each coupled analysis is a list of "parts" relevant to the analysis — i.e., the coupling participant
regions with meshes that are involved in data transfers. Each region is listed by its display name
with a prefix indicating the display name of the corresponding participant.
• Id: Part number or part identifier (as designated in the results file or assigned by EnSight).
• Show: When selected, the part is shown in the graphics window (default for all parts on the list).
• To change the columns shown in the table, right-click the header row and select Customize.
• To change the column values for a region, right-click its row and use the available context options.
• To change the attributes of a region, double-click its row and change the desired values in the Edit
Attributes for Tagged Model Part dialog that opens.
Tip:
By default, results are loaded with the initial geometry. To observe changes in the geo-
metry, you must edit the corresponding parts settings as follows:
3. Under Displacement, set Displace by to the vector variable to be used for displace-
ment.
Variables
The Variables pane is a table populated with variables defined in the coupled analysis data files.
Coordinate and Time variables are activated by default. For each of these variables, columns show
values for units (when defined) and range.
Other variables are grouped by type as Scalars, Vectors, or Constants. Under each of these cat-
egories, there's a list of variables relevant to the analysis — i.e., variables that are involved in data
transfers.
Each variable is listed by its display name, concatenated with some or all of the following descriptive
information:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 85
Using System Coupling's User Interfaces
These variables must be activated (loaded into memory) either explicitly by selection of the corres-
ponding Activated check box, or by being called by an operation that requires it.
Note:
Graphics Window
The Graphics Window shows the 3D objects selected in the Parts list. Operations can be performed
on objects shown in the window via the right-click context menus for objects and for the viewport
itself.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
86 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Note that the Save operation or Save command will raise an exception if another instance of System
Coupling is solving in the current working directory.
However, you can also save the state of a coupled analysis on demand, as follows:
• To change the output location, select the intended output directory in the Save dialog.
• To change the output location, set the optional FilePath argument to the name of the intended
output directory.
For more detailed information on the files created, see Settings File (Settings.h5) (p. 207) and
Results Files (Results_*#.h5) (p. 207).
Once these files have been written, you can use them to resume the analysis, as described in Restarting
a Coupled Analysis (p. 88).
Interrupt solve
When the Interrupt solve context option is selected, the coupled analysis is stopped and System
Coupling ends participant processes with a clean shutdown — i.e., the run continues until the current
coupling step is completed and System Coupling generates a corresponding restart point and Results
file before disconnecting.
Abort solve
When the Abort solve context option is selected, the coupled analysis does not shut down cleanly —
i.e., System Coupling stops the run immediately without producing any restart data and signals parti-
cipants that they should shut down, as well.
When the solution stops, the Solution Lock file (p. 196) is removed from the working directory. When
System Coupling exits, the GUI Server file (p. 196) is removed from the working directory.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 87
Using System Coupling's User Interfaces
• For command-line runs, you must create the Shutdown file and place it in System Coupling's working
directory manually.
• When a Shutdown file is used, System Coupling ends participant processes for participants that have
been started automatically.
When the solution stops, the Solution Lock file (p. 196) is removed from the working directory. If System
Coupling was run in GUI Server mode, the GUI Server file (p. 196) is removed from the working directory
when System Coupling exits.
Restarts from the final result are possible only with analyses that have been completed or interrupted
(not aborted). However, restarts from an intermediate result are possible with any analysis for which
intermediate start points have been generated; an aborted run can be restarted from an intermediate
result that was completed before the analysis was aborted.
If restarting from a final result, you must extend the analysis in order to perform the restart.
Tip:
When an analysis is restarted from an intermediate restart point, all subsequent restart
points are removed. To retain data from later restart points, save the corresponding Results
file and Settings file in a different directory.
• When an analysis is restarted from an intermediate restart point, all subsequent restart points
are removed. To retain data from later restart points, save the corresponding Results file and
Settings file in a different directory.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
88 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
• To return to the beginning of an analysis and start over, delete all the Results files. Also, you
may need to edit settings to return the data model to its original state because the Settings
file contains the values used for the most recent run.
Note:
• For ramping and under-relaxation during a restarted run, the final values from the previous
coupling step or iteration of the initial run are not currently available. For the first iteration of
a restarted run, upon remapping, the reference values are reset to initial values upon remapping
(i.e., they're identical to the mapped target-side values). As a result, no ramping or under-relax-
ation is applied during this iteration.
• Mechanical participants do not support restarts for steady-state thermal and transient thermal
analyses.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 89
Using System Coupling's User Interfaces
For each restart point created, the Settings (p. 207) file is updated and a Results (p. 207) file is gener-
ated. These files contain the information necessary to resume the analysis at the designated point.
Tip:
The commands noted above can be used both in the CLI and on the GUI's Command
Console tab. For more information, see Using Interactive Solve Commands (p. 95).
To restart a coupled analysis by opening a new instance of the System Coupling GUI, perform the
following steps:
1. Open the System Coupling GUI using one of the methods described in Starting the System Coupling
GUI (p. 44).
2. On the Select working directory dialog, select the working directory of the coupled analysis to be
restarted.
The coupled analysis opens at the end of the last coupling step or iteration completed in the
previous run and loads all information (both for System Coupling and participants) required
to restart from that point.
If this point is also the final step or iteration defined for the analysis (i.e., the solution was
completed in the previous run), then the Transcript indicates that the analysis must be extended
in order to be restarted.
3. If applicable, extend the analysis using the Duration Control settings (defined under Setup / Coupling
Control / Analysis Type).
4. If desired, make any additional changes to analysis settings for System Coupling and/or participants.
Changes saved prior to the restart (either in System Coupling or in any participant except
Mechanical) are written to the Settings file and included in the restarted run.
System Coupling automatically starts all participants from the selected coupling step or iteration
and continues the solution with the next step or iteration.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
90 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
1. From the File menu, select Open at step or Open at iteration, depending on the type of Results
files generated for the analysis.
Note:
• Results files may have been generated for either coupling steps or coupling iterations,
based on the type of the analysis and the participant types involved. For more informa-
tion, see Results Files (Results_*#.h5) (p. 207).
• By default, the dialog opens to the SyC working directory. If the Results files are saved
to a non-default location, then navigate to that directory.
2. In the dialog that opens, select the Results file from which you want to restart the analysis and click
Open. (To start from the final result, select the most recent file created.)
The coupled analysis opens at the end of the specified step or iteration. If the final step or it-
eration defined for the analysis has completed, then the Transcript indicates that the analysis
must be extended in order to be restarted.
3. If applicable, extend the analysis using the Duration Control settings (defined under Setup / Coupling
Control / Analysis Type).
4. If desired, make any additional changes to analysis settings for System Coupling and/or participants.
Changes saved prior to the restart (either in System Coupling or in any participant except
Mechanical) are written to the Settings file and included in the restarted run.
System Coupling automatically starts all participants from the selected coupling step and continues
the solution with the next step.
Tip:
Alternatively, you can run the solution interactively by issuing commands on the Com-
mand Console tab. For more information, see Using Interactive Solve Commands (p. 95).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 91
Using System Coupling's User Interfaces
Tip:
If your Results files are not saved to the default SyC directory, then use the optional
FilePath argument to specify the directory.
By default, System Coupling finds the last coupling step or iteration completed in the previous
run and loads all information (both for System Coupling and participants) required to restart
from that step or iteration.
2. If the previous run completed, extend the analysis by using the DurationControl settings.
3. If desired, make any necessary changes to analysis settings for System Coupling and/or participants.
Changes saved prior to the restart (either in System Coupling or in any participant except
Mechanical) are written to the Settings file and included in the restarted run.
4. Start the solution using your preferred solve process (using either the Solve command or interactive
solve commands (p. 95)).
System Coupling automatically starts all participants from the last completed coupling step or iter-
ation and continues the solution with the next step or iteration.
1. Run the Open command with the CouplingStep or CouplingIteration argument set to the
number of the step or iteration from which you want to restart the analysis.
Tip:
If your Results files are not saved to the default SyC directory, then use the optional
FilePath argument to specify the directory.
System Coupling automatically finds the specified coupling step or iteration and loads all in-
formation (both for itself and participants) required to restart from that step or iteration.
2. If desired, make any necessary changes to analysis settings for System Coupling and/or participants.
Changes saved prior to the restart (either in System Coupling or in any participant except
Mechanical) are written to the Settings file and included in the restarted run.
3. Start the solution using your preferred solve process (using either the Solve command or interactive
solve commands (p. 95)).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
92 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
System Coupling automatically starts all participants from the specified coupling step or iteration
and continues the solution with the next step or iteration.
Prerequisites
To connect/reconnect the System Coupling GUI to an analysis in-progress, the instance of System
Coupling executing the analysis must meet the following criteria:
System Coupling is always started in this mode when opened in its GUI. It can also be started
in GUI Server mode from the command line, by appending the --guiserver argument to
its executable. Note that when started in GUI Server mode from the command line, System
Coupling operates in a non-interactive session (i.e., its CLI does not stay open after execution
of a script).
When started in GUI Server mode, System Coupling writes a GUI Server (sycGui.srv) file (p. 196)
to its working directory. This file contains the server port and host information needed to con-
nect/reconnect an instance of the GUI to the corresponding coupling solution while it is still
progressing.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 93
Using System Coupling's User Interfaces
Tip:
To continue interacting with the solution, wait until System Coupling has exited fully
and then open the case by restarting the GUI in its working directory. System
Coupling will open the case to its most recently completed coupling step or iteration.
1. Open the System Coupling GUI as described in Starting the System Coupling GUI (p. 44).
When opened in its GUI by any method, System Coupling always starts in GUI Server mode.
A dialog opens, indicating that a solution is in progress and that you may reconnect to it
later.
b. Click Continue.
The GUI closes, but System Coupling continues to run and execute the coupled analysis.
1. Open the shell for your operating system in System Coupling's working directory.
2. Run System Coupling's executable, using the --guiserver argument to start in GUI Server mode
and the -R argument to run a coupling script.
• Windows
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
94 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
• Linux
This starts System Coupling in GUI Server mode, creates the analysis, and begins the solution.
Note that System Coupling is running in a non-interactive mode, which means that its CLI closes
after the script is run. The only way to interact with an analysis started using this method is to
connect it to an instance of the System Coupling GUI during its execution.
• If the working directory already contains a sycGui.srv file, then the GUI will use the server port and
host information it contains to connect with the solution in progress.
When the GUI connects to the running analysis, System Coupling's connection and execution
details are written to the Transcript output in the Command Console tab. Solution details are
written to the Transcript during the remainder of its execution, allowing you to monitor its pro-
gress.
• If the directory does not contain a sycGui.srv file (for example, System Coupling may have exited
when the solution completed), then the System Coupling GUI opens there, starting System Coupling
in GUI Server mode and generating its own sycGui.srv file
Connection to an analysis requires that System Coupling is still running in the working directory.
System Coupling exits under the following circumstances:
• System Coupling is both idle and not attached to a GUI instance — for example, when:
For details on issues you may encounter when using System Coupling's reconnect capabilities, see
Known Issues and Limitations (p. 31).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 95
Using System Coupling's User Interfaces
In general, an interactive solve process is recommended if you require more control over your solution.
Interactive solve commands provide the ability to pause the run at designated points, enabling you
to review its progress and make changes as needed.
Available interactive commands are described briefly below. For more detailed information on a given
command, see its entry int the Commands section of the System Coupling Settings and Commands
Reference manual.
PrintSetup
Prints the Summary of Coupling Setup from the System Coupling Transcript.
StartParticipants
Note:
Reads the participants' System Coupling Participant (SCP) setup files and starts participants on
separate sub-processes. Automatically starts all participants and blocks solution progress until all
participants are connected.
Note that this command will raise an exception if another instance of System Coupling is solving
in the current working directory.
Initialize
Prepares System Coupling for the run, makes connections to participants, starts participants, and prints
participant build information to System Coupling's Transcript.
Disabled when a solution is already in progress. Note that this command will raise an exception
if another instance of System Coupling is solving in the current working directory.
If this command is (re)issued after participants have been started, then the subsequent command's
arguments are used. If there are changes to a participant's SCPfile, then the new file replaces the
previous one.
Step
Specifies the number of coupling steps to be run before pausing the coupled analysis. If necessary, starts
participants. Default value is 1.
Disabled when a solution is already in progress. This command will raise an exception if another
instance of System Coupling is solving in the current working directory.
When you resume the solution, either by reissuing this command or running the Solve command,
System Coupling restarts the analysis at the point it left off and continues the solution with the
next step.
CreateRestartPoint
Creates a restart point in an initialized analysis.
This command signals System Coupling and each participant that a restart point should be created
before the next coupling step begins. The requested restart point is created in addition to any
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
96 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
restart points created either by System Coupling (via the OutputControl (p. 70) data
model settings) or by participant configurations.
Note:
Some participants write their restart files only when the coupling run resumes, so
their files are not available immediately after the CreateRestartPoint com-
mand is issued.
Once a restart point is created, you can close the analysis and then resume working with it later,
as described in Restarting a Coupled Analysis (p. 88).
Shutdown
Shuts down a coupling analysis which has been initialized.
This command signals System Coupling and each participant to create a restart point at the end
of the last completed coupling step and then shut down the analysis as soon as possible. System
Coupling then ends the coupling run, disconnecting from participants and printing timing inform-
ation to the Transcript and Log file (p. 197).
When instances of System Coupling started in GUI Server mode are disconnected, the GUI Server
file (p. 196) is removed from the working directory.
The simultaneous solutions are executed as distributed parallel runs, allocated across available compute
resources by System Coupling's participant partitioning algorithms. In this case, the behavior of System
Coupling's partitioning operations is modified to minimize core-usage conflicts.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 97
Using System Coupling's User Interfaces
a. In the modified ordered participant list, identify the participants that have no dependencies
with other participants on the list.
• If independent participants have been identified, then combine those participants into a
group.
• If no independent participants have been identified, then create a group with the first par-
ticipant on the list as its only member.
c. Adds the new group to the ordered list of groups, determining its position by applying the
participant-ordering process (described in Participant Solution Sequencing (p. 38)) to the
groups.
d. Removes the grouped participant(s) from the ordered list of individual participants.
2. System Coupling repeats step 1 until no ungrouped participants remain on the individual participant
list.
a. In the ordered group list, identify the groups that have dependencies only on groups that
come before them on the list.
c. Add the consolidated group to the ordered list, determining its position by applying the par-
ticipant-ordering process (described in Participant Solution Sequencing (p. 38)) to the groups.
2. System Coupling repeats step 1 until all eligible groups on the ordered list have been combined.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
98 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
When the default Shared Allocate Machines algorithm is used, however, System Coupling adjusts
partitioning behavior to minimize situations where multiple participants are attempting to use the
same core at the same time. When this default algorithm is used, partitioning behavior is as follows:
• Individual participants with sequential solutions are partitioned using the specified Shared Allocate
Machines algorithm.
• Participants that are grouped for simultaneous solution are partitioned using the Distributed Allocate
Cores algorithm.
– Member participants' resource-allocation fractions are renormalized and then partitioned across all
available hosts.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 99
Using System Coupling's User Interfaces
– Participant groups still share machines and cores, but participants within a given group do not share
cores with each other.
In this example, there are nine participants. None are sending Incremental Displacement.
In this example, there are four participants. None are sending Incremental Displacement.
Example 21: Coupled analysis with an MAPDL participant sending Incremental Displacement
In this example, the MAPDL participant is sending Incremental Displacement to the Fluent participant.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
100 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Example 22: Alternate scenario with an MAPDL participant sending Incremental Displacement
In this example, the configuration is the same as in the previous example, but the participant names
are indexed differently.
Note:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 101
Using System Coupling's User Interfaces
Note:
In the sections that follow, "machine" denotes a compute resource with multiple cores and
a fixed amount of memory.
System Coupling always runs in parallel on two cores and has additional parallel execution features
that work in conjunction with the automatic startup of two or more participants. Load balancing of
HPC resources is controlled via selecting how many cores are allocated to each participant and the
algorithm for partitioning them. When participants are run in parallel along with System Coupling, it
accelerates the heavyweight work performed during the simulation.
2. To use parallel-specific command-line options when starting System Coupling, see Parallel Options
for System Coupling (p. 117).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
102 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
5. To run an individual participant product in parallel mode, specify the participant's command-line
execution details. For more information, see Parallel Options for Participant Products (p. 117).
6. To run all coupling participants in parallel, specify how the participants are partitioned across compute
resources. For more information, see Parallel Processing for Coupling Participants (p. 103).
When setting up participants for parallel execution, you can set the following parameters to control
the behavior of the run:
• Machine List: The list of machines to be used and the number of cores each has available for the
parallel run. For more information, see Machine List and Core Counts (p. 106).
Partitioning Algorithm: The algorithm used to specify the resource allocation method
(machines or cores) and parallel execution mode (local or distributed) to be used. For more
information, see Participant Partitioning Algorithms (p. 107).
Participant Fractions: The fractions specifying the core count or fraction of compute re-
sources to be allocated to each participant. For more information, see Resource Allocation
Fractions (p. 106).
The parallel execution details that were specified most recently — regardless of by what method
— replace existing parallel values.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 103
Using System Coupling's User Interfaces
To apply partitioning to coupling participants, your coupled analysis must meet the following
prerequisites:
Note:
When using the System Coupling GUI, apply partitioning to coupling participants as follows:
For information on available algorithms, see Participant Partitioning Algorithms (p. 107).
a. In the Outline tree under Setup, right-click Coupling Participant and select Parallel solve
setup.
b. Under Participant Weights, specify the resource weighting for each coupling participant in
decimal format.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
104 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
In the Parallel Partitioning dialog under Machine Names and Core Counts, specify the
name of each machine and the number of cores it has available for the coupled analysis.
For details on this and other methods of setting this information, see Machine List and Core
Counts (p. 106).
4. Click OK.
When using the System Coupling CLI, apply partitioning to coupling participants by editing the
data model, as follows:
When starting System Coupling, use the -t command-line option to specify the number of
cores to be used when running on the local machine.
Tip:
To explicitly set the machine list and the number of cores to be used for each,
use the --cnf command-line option when starting System Coupling. However,
if the job is being submitted to a job scheduler (i.e., PBS, LSF, or UGE), then the
machine list is automatically detected from the scheduler environment and does
not need to be specified using the --cnf option.
For more information, see Machine List and Core Counts (p. 106).
For information on the -t and --cnf arguments, see Coupling Participant Parallel Options
in the System Coupling Settings and Commands Reference manual.
To specify the partitioning algorithm to be applied to the coupled analysis, edit the Solu-
tionControl \ PartitioningAlgorithm setting in the data model.
For information on available algorithms, see Participant Partitioning Algorithms (p. 107).
Note:
An AEDT participant will not run in distributed parallel; it will run on a single
machine, regardless of the number of machines allocated or the partitioning al-
gorithm.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 105
Using System Coupling's User Interfaces
When running either shared or distributed execution modes, CFX and Fluent
participants should be the last participants added to the analysis because they
tolerate distributed parallel processing well.
To specify the core count or fraction of compute resources to be allocated to each participant,
edit each participants' ExecutionControl / ParallelFraction setting in the data
model.
>>> DatamodelRoot().CouplingParticipant['FLUENT-2'].ExecutionControl.ParallelFraction=1.0/5.0
Note:
• For the default Shared Allocate Machines algorithm, each participant will run on all the allocated
cores.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
106 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
• For all other algorithms, each participant will run on an equal fraction of the total core count.
Note:
The defaults may not be optimal, depending on the participants involved and the
co-simulation resource needs. For instance, the Mechanical APDL structural solver
might run more optimally on a lower core count than the Fluent solver, so you
might want to set a lower fraction for MAPDL.
In this case, each participant will run on exactly that fraction of the total core count.
For example, if two participants are given fractions of 1/2 and 3/4, respectively, then the
first participant will use one-half of the available cores and the second participant will use
three-quarters of them.
If any fraction is greater than 1.0, then all the fractions are normalized with respect to the
largest fraction.
For example, if two participants are given fractions of 100 and 60, respectively, then the
first participant will use all the cores and the second participant will use 60/100, or three-
fifths of them.
• Resource allocation method: Determines whether available compute resources will be allocated
as machines or cores.
• Parallel execution mode: Determines whether participants will be run in shared parallel or dis-
tributed parallel (which are different than the local parallel and distributed parallel modes used
for an individual participant). The table below compares the characteristics of each mode.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 107
Using System Coupling's User Interfaces
When choosing a participant partitioning algorithm, consider the resources needed for each
participant, how many machines/cores are available, and how those resources might be allocated
to best meet your parallel-processing requirements.
• Shared Allocate Machines (p. 112): Participants share both machines and cores. (default value)
Note:
When this algorithm is used and simultaneous solutions are enabled, partitioning
behavior changes slightly. For more information, see Execution of Simultaneous
Participant Solutions (p. 99).
• Shared Allocate Cores (p. 114): Participants share machines but not cores.
• Distributed Allocate Cores (p. 115): Participants minimally share cores and machines.
• Distributed Allocate Machines (p. 116): Participants never share cores or machines.
For many co-simulations, the default algorithm, Shared Allocate Machines, is often the best
choice. It behaves similarly to the methods used by individual solvers, providing for full utilization
of all the allocated cores, and generally results in the best overall performance and scaling.
The other algorithms are provided as means of handling situations for which the default al-
gorithm is not appropriate. For instance, if the total memory available on a machine is insufficient
to handle running more than one participant, then you can use the non-default algorithm that
best fits your parallel setup.
The tables below summarize the advantages and disadvantages generally associated with each
of System Coupling's participant partitioning algorithms.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
108 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Note that all the examples share the following setup details:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 109
Using System Coupling's User Interfaces
• There are 57 cores with the same uneven distribution across nine machines, which are designated as
M0 through M8.
• Each example assumes that the machine list has already been set up using one of the methods shown
below.
The figures below show the three methods you can use to set up the machine list and core count
for the examples that follow:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
110 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
>>> PartitionParticipants(MachineList = [
{'machine-name' : 'host1', 'core-count' : 12},
{'machine-name' : 'host2', 'core-count' : 12},
{'machine-name' : 'host3', 'core-count' : 12},
{'machine-name' : 'host4', 'core-count' : 7},
{'machine-name' : 'host5', 'core-count' : 6},
{'machine-name' : 'host6', 'core-count' : 3},
{'machine-name' : 'host7', 'core-count' : 3},
{'machine-name' : 'host8', 'core-count' : 1},
{'machine-name' : 'host9', 'core-count' : 1}
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 111
Using System Coupling's User Interfaces
])
Note:
Because all the partitioning examples that follow use the same machine/core setup,
the machine list and core counts are the same for all of them. Only the partitioning
algorithms and resource allocation fractions change for each example.
In the examples below, Participant-1, Participant-2, and Participant-3 have been allotted
fractions of 1, 1, and 1/5, respectively.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
112 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Example 23: GUI setup for the default SharedAllocateMachines algorithm with machines
allocated by fractions
Example 24: Data model setup for the SharedAllocateMachines algorithm with
machines allocated by fractions
>>> dm = DatamodelRoot()
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 113
Using System Coupling's User Interfaces
Example 26: Resource allocation resulting from the Shared Allocate Machines examples
The machines are sorted by core count and allocated in blocks, which are sized by the number
of participants. This helps to ensure that each participant gets cores on machines with highest
total core counts, keeping any inter-process communication local to a machine.
In the examples below, Participant-1, Participant-2, and Participant-3 have each been allotted
19 cores.
Example 27: Data model setup for the SharedAllocateCores algorithm with even
allocation of cores
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
114 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Figure 9: Resource allocation resulting from the Shared Allocate Cores examples
The machines are sorted by core count and allocated into blocks, which are sized by the
number of participants. This helps to ensure that each participant gets cores on machines with
highest total core counts, keeping any inter-process communication local to a machine.
In the examples below, Participant-1, Participant-2, and Participant-3 have each been allotted
19 cores.
Example 29: Data model setup for the DistributedAllocateCores algorithm with
even allocation of cores
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 115
Using System Coupling's User Interfaces
Example 31: Resource allocation resulting from the Distributed Allocate Cores examples
The machines are sorted by core count and allocated in blocks, which are sized by the number
of participants. This helps ensure that each participant gets cores on machines with highest
total core counts, keeping any inter-process communication local to a machine.
In the examples below, Participant-1, Participant-2, and Participant-3 have each been allotted
3 machines.
Example 32: Data model setup for the DistributedAllocateMachines algorithm with
even allocation of cores
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
116 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Example 34: Resource allocation resulting from the Distributed Allocate Machines examples
If you also plan to use parallel processing for the coupling participants (p. 103), then you may wish
to review Coupling Participant Parallel Options.
Note:
Some participants populate this setting with default values; for details, see the
participant's relevant product documentation.
When parallel customizations for an individual participant are needed, you may use this method
instead of the partitioning functionality described in Parallel Processing for Coupling Parti-
cipants (p. 103).
When System Coupling starts the coupled analysis execution, these arguments are picked up from
the data model and used to start the participant solver. If the specified additional arguments conflict
with default values set by System Coupling, the new values override the System Coupling defaults.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 117
Using System Coupling's User Interfaces
1. In the Outline pane's tree view under Coupling Participant, locate and expand the branch for the
participant object (<Participant>).
>>> DatamodelRoot().CouplingParticipant['FLUENT-2'].ExecutionControl.AdditionalArguments
= cfx5solve -def model.def -par-dist 'hosta,hostb*2,hostc*4'
• populate the data model with a System Coupling SCI (p. 187) file instead of multiple SCP files, and
• set execution controls in the data model (because the SCI file doesn't provide this information).
Note:
• The use of both SCI and SCP files in the same analysis is not supported.
• Restarts are not supported if the default participant names (as assigned in the SCI file —
Solution, Solution 1, etc.) have been changed.
For instructions on taking a coupled analysis that was set up in Workbench and then running it in a
given user interface, see:
Running a Workbench Setup in the GUI
Running a Workbench Setup in the CLI
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
118 of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
1. Start the System Coupling GUI using one of the methods described in Starting the System Coupling
GUI (p. 44).
c. Click Open.
The Workbench setup is populated to the data model. The Coupling Control, Solution Control,
Coupling Participant, and Coupling Interface branches and their contents are added to the
Outline pane's tree view.
3. To provide information not included in the SCI file, edit the participants' Execution Control settings.
For each participant:
a. In the Outline pane's tree view, select the participant's Execution Control branch.
b. Set Working Directory to the intended working directory for the participant.
This where System Coupling looks for the participant's solver input file and where the parti-
cipant will write its output files. By default, this is set to the coupled analysis working directory
you specified when starting the GUI.
c. Set Initial Input to the name of the participant's solver input file.
Note:
From this point, the steps are the same as for a coupled analysis set up in a user in-
terface.
5. Run the coupled analysis as described Starting the Solution in the GUI (p. 80).
6. If desired, restart the coupled analysis as described in the Restarting a Coupled Analysis in the GUI (p. 90)
section of Restarting a Coupled Analysis (p. 88). Do not reissue the ImportSystemCouplingInput-
File command.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 119
Using System Coupling's User Interfaces
1. Start System Coupling as described in Starting the System Coupling CLI (p. 53).
3. To provide information not included in the SCI file, edit each participant's ExecutionControl settings
in the data model:
Example 36: Set execution controls for two participants in the CLI
>>> dm = DatamodelRoot()
>>> dm.CouplingParticipant['Solution'].ExecutionControl.InitialInput = 'mapdl.dat'
>>> dm.CouplingParticipant['Solution'].ExecutionControl.WorkingDirectory = 'Struct'
>>> dm.CouplingParticipant['Solution 1'].ExecutionControl.InitialInput = 'fluidFlow.cas'
>>> dm.CouplingParticipant['Solution 1'].ExecutionControl.WorkingDirectory = 'Fluid'
Note:
From this point, the steps are the same as for a coupled analysis set up in a user in-
terface.
4. Run the coupled analysis as described in Starting the Solution in the CLI (p. 81).
5. If desired, restart the coupled analysis as described in the Restarting a Coupled Analysis in the CLI (p. 91)
section of Restarting a Coupled Analysis (p. 88). Do not reissue the ImportSystemCouplingInput-
File command.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
120 of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling in Workbench
This section provides a high-level overview of System Coupling in Workbench.
When running System Coupling in Workbench, you use the Workbench interface and workflow to build
and execute coupled analyses.
• Overview of System Coupling in Workbench (p. 121) provides information on supported participants, data
transfers possible, the rules for creating data transfers, and the System Coupling tab.
• Setting Up a Coupled Analysis in Workbench (p. 126) provides instructions on preparing for, creating, and
changing settings for a coupled analysis.
• Running a Coupled Analysis in Workbench (p. 140) provides instructions for running, monitoring, and reviewing
output for a coupled analysis.
• Alternate Workflows for System Coupling in Workbench (p. 148) provides alternate workflows for coupled
analyses run in Workbench—specifically, stopping and restarting analyses and using Workbench to set up
an analysis intended to be run from one of System Coupling's user interfaces.
Note:
Some of these capabilities, however, may not yet be supported in conjunction with
other Workbench systems. For information about systems that can act as participants
in coupled analyses, see Supported Coupling Participants for System Coupling in Work-
bench (p. 122).
• Supported Coupling Participants for System Coupling in Workbench (p. 122) describes the systems that
can serve as participants in a coupled analysis.
• Data Transfers for System Coupling in Workbench (p. 123) describes rules for creating data transfers.
• Steps of a Coupled Analysis in Workbench (p. 124) lists the steps involved in setting up and running a
coupled analysis within Workbench.
• System Coupling Tab in Workbench (p. 124) describes the parts of the System Coupling workspace in
Workbench.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 121
Using System Coupling in Workbench
CFX
For information on using System Coupling with a CFX system, see the following sections in
the CFX-Solver Modeling Guide:
Fluent
For information on using System Coupling with a Fluent system, see the following sections
in the Fluent User's Guide:
Mechanical
For information on using System Coupling with a Mechanical system, see the following sections
in the Mechanical User's Guide:
• System Coupling
External Data
For information on using System Coupling with an External Data system, see the following
section in the Workbench User's Guide:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
122 of ANSYS, Inc. and its subsidiaries and affiliates.
Overview of System Coupling in Workbench
• External Data
Note:
• Only two coupling participants can be connected to the System Coupling system at one
time. However, more than one System Coupling system may be introduced on the same
Project Schematic.
• Coupled analyses are not supported for External Data participant systems that have non-
ASCII characters in the following values:
– Data source Identifier (defined in the External Data tab's Outline of Schematic)
– Data source Data Identifier (defined in the External Data tab's Table of File)
For more information on supported data transfers, see System Coupling Data Transfer Quantities (p. 8).
For information on the data transfers that are supported for a given participant system, use the links
in Supported Coupling Participants for System Coupling in Workbench (p. 122) to review participant
product documentation.
When you create data transfers using the Create Data Transfer context option in the System
Coupling tab's Outline of Schematic, the following rules apply:
• For a given target region, there can only be one source region. However, a given source region can send
data to multiple target regions.
• For one-way thermal transfers, only one of the above three options above can be defined for a given pair
of source and target regions.
• For two-way thermal transfers, two data transfers are set up on the same data transfer region. In a two-
way transfer:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 123
Using System Coupling in Workbench
– variables of the quantity types Heat Transfer Coefficient and Convection Reference Temperature cannot
be transferred on the same data transfer region as a variable of the Heat Flow quantity type, and
– a participant's data transfer region cannot provide and receive the same thermal variable(s); for example,
Fluent cannot both send and receive temperature data on the same data transfer region.
b. Set up each participating system (generally from top-to-bottom, until you have completed all
the required steps for your analysis) and perform a test solve.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
124 of ANSYS, Inc. and its subsidiaries and affiliates.
Overview of System Coupling in Workbench
To open it, edit either the Setup cell or the Solution cell of your System Coupling component system.
The tab opens in your Workbench project, as shown in Figure 10: The System Coupling tab (p. 125).
The System Coupling tab has two nodes which correspond to the cells of the System Coupling
system on the Project Schematic:
• Setup
Use this node to view participant, region, and variable information, and to define analysis
settings and data transfers between participants.
• Solution
Use this node to solve a coupled analysis and to view solution information and charts.
Outline of Schematic:
Shows a tree with nodes relating to different parts of the coupled analysis. It has two nodes which
correspond to the System Coupling system's cells on the Project Schematic:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 125
Using System Coupling in Workbench
• a Setup node, which you'll use to complete analysis settings (p. 129), including details for parti-
cipants, data transfers, and execution controls; and
• a Solution node, which you'll use to start the solution (p. 140) and monitor its progress (p. 141)
during execution.
When a node is selected in the Outline of Schematic, corresponding properties are shown
in the Properties pane.
Properties:
Shows setup nodes and properties (p. 130) corresponding to the item selected in the Outline of
Schematic.
Chart Monitor:
Shows System Coupling charts during and after the solution.
Solution Information:
Shows a text-based log (p. 197) of information output during the execution of the coupled analysis.
For more information about the tabbed panes in Workbench, see Panes within Tabs in the Workbench
User's Guide.
• Add analysis systems for two dynamic participants, such as a Transient Structural system for Mech-
anical and a Fluid Flow (CFX) system for CFX.
• Add systems for a static data source and a dynamic participant, such as an External Data component
system for an external data source and a Fluid Flow (Fluent) analysis system for Fluent.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
126 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
During the coupled analysis, System Coupling manages participant solutions. However, each par-
ticipant should be able to solve successfully on its own prior to being included in the coupled
analysis.
Note:
• When using same material(s) in multiple participants, take care to ensure that common
properties are consistently defined, as described in Additional Participant Setup Consider-
ations (p. 58).
• Directory paths and object names (for interfaces, participants, regions, and variables) must
be in ASCII format. Object names also cannot include forward slashes (/) or the colon
character (:).
For additional suggestions on how to ensure that your coupled analysis runs smoothly, see
Building Up to a Coupled Analysis (p. 211).
• For CFX and Fluent, this involves creating one or more boundary conditions.
For more information on a given participant's settings, use the links in Supported Coupling Parti-
cipants for System Coupling in Workbench (p. 122) to access its documentation.
Most participant systems with Setup cell connections act as co-simulation participants. The exception
to this is the External Data system; although a connection originates from its Setup cell, it acts as a
static data participant.
The CFX-Solver input file is generated when data transfers are created. If the coupled analysis has a
CFX coupling participant and you plan to execute it in System Coupling's GUI or CLI, do not connect
systems on the Project Schematic until after the solver input files and the SCI file have been gener-
ated.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 127
Using System Coupling in Workbench
Figure 11: Connecting a System Coupling component system with other types of systems
The execution of analyses involving couplings between any of these participants is managed by System
Coupling. For details, see Coupled Analysis Management (p. 155).
Once a participant system is connected to the System Coupling system, updates of the participant's
Solution cell are disabled. All solution updates (and the execution of the respective solvers) are
started automatically when System Coupling's Solution cell is updated. Note, however, that these
updates respect all settings (for example parallel, precision, and so on) already made for them.
Note:
Projects that include a System Coupling system can be submitted to Remote Solve Manager
(RSM); only project updates are supported for remote execution. For details, see Submitting
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
128 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
Project Updates to Remote Solve Manager and Submitting System Coupling Jobs to Remote
Solve Manager in the Workbench User's Guide.
The state of the Setup node reflects the state shown by the System Coupling system's Setup cell
on the Project Schematic. Validation of the Setup node depends upon the validation of the individual
sub-nodes defined under it (for example, Analysis Settings and Data Transfer). If any of these sub-
nodes is invalid, then the Setup node is also invalid, as shown by the state of Attention Required ( ).
To access System Coupling properties, right-click the Setup node and select Expand All.
Use the following Setup node functionality to complete your coupled analysis setup:
Setup Node Context Options
Coupling-Specific Properties
Available options:
Rename
Available for data transfer nodes. Renames the selected data transfer. For details, see Data Transfer
Context Options (p. 136).
Duplicate
Available for data transfer nodes. Duplicates the selected data transfer. For details, see Data Transfer
Context Options (p. 136).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 129
Using System Coupling in Workbench
Add Property
Available for the Execution Control > Expert Settings node. Allows you to select and enable an expert
setting. Once enabled, the setting is displayed under Properties whenever the Expert Settings node
is selected. For more information, see Expert Settings.
Remove Property
Available for the Execution Control > Expert Settings node when an expert setting is enabled. Allows
you to select and disable an expert setting. Once disabled, the setting is removed from Properties.
For more on available settings, see Expert Settings.
Useful for atypical situations such as a Workbench crash, when the restart point list may be
empty even though the intermediate restart files exist on your disk. Repopulating the list of
restart points allows you to restart from a previously saved point.
Coupling-Specific Properties
Use the Setup node's coupling-specific properties to define analysis details. To access properties,
select any of the sub-nodes defined under Setup. Any properties associated with the selected node
are displayed below under Properties, where you can edit the properties that are enabled.
Analysis Settings
Defines the basic behavior of the analysis. When Analysis Settings is selected, the following
properties are shown below under Properties:
Analysis Type
Initialization Controls
Duration Controls
Step Controls
Analysis Type
Possible values:
• General
• Transient
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
130 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
Used when any participant is executing a transient solution (includes mixed steady-transient
analyses).
Initialization Controls
Coupling Initialization
Property controlling how the analysis is initialized:
Possible values:
• Program Controlled
For initial runs (that is, not restart runs), the initial time and step are each set to 0.
For restart runs, the initial time and step are set to the values obtained from the most
recent valid restart point.
A coupled simulation can have multiple restart points when Intermediate Restart Data
Output (p. 139) is selected for either all coupling steps or for a set of coupling step intervals.
The next coupled analysis will be started based on the restart point you select.
For more information, see Restarting a Coupled Analysis in Workbench (p. 149).
Important:
Duration Controls
Duration Defined By
Property controlling how the duration of the analysis is defined:
Possible values:
• End Time
System Coupling executes coupling steps until the end time specified by the End Time
property is reached. In a transient analysis, each coupling step is a time step (with the
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 131
Using System Coupling in Workbench
time interval specified by the step size). Note that the final coupling step size is reduced
automatically, if needed, so that the specified end time is respected.
Note:
Some participant systems, such as Mechanical, require that the end time
specified in their setup is respected. When a coupled analysis involves one or
more participants that require their end time to be respected, then the max-
imum allowable end time for the coupled analysis is the minimum of the end
times reported by such participants. In this case, a validation error will be re-
ported if the coupled analysis' specified end time is greater than the minimum
identified.
Other participant systems, such as Fluent, can run past the end time specified.
These participant systems have no effect on the allowable end time of the
coupled analysis.
• Number of Steps
System Coupling executes coupling steps until the number of steps specified by the
Number of Steps property have been executed.
Number of Steps
Property defining the number of coupling steps in the analysis. Available when Duration Defined
by is set to Number of Steps.
Step Controls
The duration of the coupled analysis is broken into a sequence of coupling steps. Data transfers
between the coupled solvers occur at the beginning of each coupling iteration within a coupling
step. Coupling steps are always indexed. During the analysis, each new coupling step is started
when:
• Either the maximum number of coupling iterations has been reached or the coupling step has
converged.
The coupling steps of the analysis are defined by the following properties:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
132 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
Step Size
Property defining the time interval (in seconds) associated with each coupling step. Available
when the coupling is defined in terms of time (a transient analysis).
Note:
The final coupling step size is reduced automatically, if needed, so that the
specified end time is respected. This reduction does not occur if the analysis
duration is set by the Number of Steps.
The coupling step size is fixed for the duration of the coupled analysis but can be changed
when restarting the analysis.
Minimum Iterations
Property defining the fewest number of coupling iterations that can be executed per coupling
step (must be at least 1).
The specified minimum number of coupling iterations is executed even if all measures of
convergence are realized in fewer iterations.
Maximum Iterations
Property defining the greatest number of coupling iterations that can be executed per coupling
step.
The specified maximum number of coupling iterations may not be executed if the analysis
converges before the maximum iteration step is reached.
Participants
Defines the participants involved in the analysis.
Under the Participants node, a read-only sub-node is defined for each participant connected to
System Coupling system's Setup cell on the Project Schematic. The sub-node takes the parti-
cipant name, as presented in the Project Schematic
Regions
Defines the regions for the participant. Contains a collection of participant regions from/to
which data can be transferred.
A region is most often a point, line, surface, or volume that is part (or all) of the participants
geometry or topology. Note, however, that equations or probe (monitored) values may also
be considered as point regions.
Note:
When a given region is selected, the following properties are shown below under Properties.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 133
Using System Coupling in Workbench
Topology
Property indicating the topology of the region. Currently, the only available value is Surface.
Note:
Volumetric regions are available for GUI or CLI-based co-simulations with Maxwell
as a participant.
Input Output
Property indicating the variable (such as force, length, or temperature) transferred to/from the
region.
Physical Type
Property indicating the quantity transferred to/from the region.
Data Transfers
Defines the data transfers to be performed in the analysis.
System Coupling in Workbench defines a data transfer (p. 123) as one source region and one target
region, with the transfer of one variable type in one direction between two participants. For a
two-way data transfer on one region, two individual data transfers are defined.
Note:
For data transfer creation rules applicable to both System Coupling and System
Coupling in Workbench, see Rules for the Creation of Data Transfers (p. 159).
Under the Data Transfers node, a sub-node is defined for each data transfer created. When a
given data transfer is selected, the following properties are shown below, under Properties:
Source/Target
Data Transfer Control
Data Transfer Context Options
Source/Target
Data transfer source and target are defined by the following properties:
Source/Target
Defines the Source and Target for the data transfer. Both are defined by the following properties:
Participant
Defines the participant associated with the data transfer.
Region
Defines the region to/from which data are transferred.
Variable
Defines the variable to be transferred.
When setting up data transfers, follow a top-down approach when defining Source and
Target. Select in this order:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
134 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
1. Source Participant
2. Source Region
3. Source Variable
4. Target Participant
5. Target Region
6. Target Variable
Transfer At
Controls when the data transfer is executed by the solver. Only available option:
• Start of Iteration
Transfer data at the start of every coupling iteration within a coupling step.
Under-Relaxation Factor
Factor multiplying the current data transfer values when under-relaxing them against the previous
values. This is overridden with unity in the first coupling iteration of every coupling step only
when the Analysis Type is Transient.
Note:
• When under-relaxation is used, there's no guarantee that the full value from the
source side of the data transfer is applied to the target by the end of the coupling
step.
Ramping
Determines the behavior of the ramping algorithm for specified quantity.
Ramping is used by System Coupling to slow the application of the source-side value on
the target side of the interface.
Possible values:
• None
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 135
Using System Coupling in Workbench
No ramping is applied; the full data transfer value is applied to the target side of the in-
terface for all coupling iterations. (default value)
Within each coupling step, the ramping factor is used to linearly increase the change in
the data transfer value applied to the target side of the interface. The data transfer value
is increased during each coupling iteration until the specified minimum number of
coupling iterations is reached. The ramping factor is applied to the change in the data
transfer value from the last coupling iteration of the previous coupling step. If there's no
change in this value from the last coupling step, the full data transfer value is applied
to the target side of the interface for all coupling iterations of that coupling step.
For more information on the ramping algorithm, see Ramping Algorithm (p. 173).
Note:
After you connect a participant system's Setup cell to the System Coupling Setup cell in the
Project Schematic and refresh the Setup cell, context options for creating and manipulating
data transfers are available.
To access these context options, right-click the Data Transfers node or any specific data
transfer defined underneath it.
Available options:
Right-click Data Transfers and select Create Data Transfer. This creates a new data
transfer without any source or target properties defined. You can change the data
transfer definition later, in Properties pane.
Multi-select two regions from different participants, right-click one of them and select
Create Data Transfer. This creates multiple data transfers that vary based on the following
criteria:
– Whether the input variable from one region has the same properties (such as the physical
type) as the output variable from the other region
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
136 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
Right-click a single region and select Create Data Transfer. This creates data transfers
for each variable associated with the region. If the variable is an output variable, then
the source participant, source region, and source variable are defined for the new data
transfer. If the variable is an input variable, then the target participant, target region, and
target variable are defined for the new data transfer.
Select a region, then right-click a variable under Properties pane and select Create Data
Transfer. This creates a new data transfer. If the selected variable is an output variable,
then the source participant, source region, and source variable are defined for the new
data transfer. If the selected variable is an input variable, then the target participant,
target region, and target variable is defined for the new data transfer.
Rename
Right-click a data transfer, select Rename, type in the new name, and click Enter. Alternatively,
you can double-click a data transfer to rename it.
Delete
Select one or more data transfers, right-click one of them, and select Delete.
Suppress
Select one or more unsuppressed data transfers, right-click one of them, and select Suppress.
Unsuppress
Select one or more suppressed data transfers, right-click one of them, and select Unsuppress.
Note:
If the data transfer definition is not valid or the data are invalidated for any reason,
the state of the node shows as Attention Required ( ).
Execution Control
Provides the following properties to control the execution of the coupled analysis.
Coupling Engine
Expert Settings
Debug Output
Intermediate Restart Data Output
Coupling Engine
When Execution Control is selected, the Coupling Engine property is shown under Properties.
This property enables you to specify what coupling engine is to be used to run the coupled
analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 137
Using System Coupling in Workbench
Possible values:
• 2.0: The current version of the System Coupling engine will be used to run the analysis. This is the
only value available for new analyses.
• 1.0: The previous version of the System Coupling engine will be used to run the analysis. This is the
default value for analyses created with System Coupling 1.0.
When you open a project containing one or more coupled analyses created with System
Coupling 1.0, you can specify the coupling engine to be used for each System Coupling system
(it's possible to have analyses of both versions on the same Project Schematic). It's recommen-
ded, however, that you switch your analyses to the the current version of System Coupling.
When you switch the Coupling Engine property to a value of 2.0 for a given System Coupling
system:
• Where there are differences in how properties function between versions (such as for Expert Set-
tings (p. 138), Debug Output (p. 139), and Chart Variables (p. 144)), the 2.0 behaviors are used.
• Unless Workbench Beta Options are enabled (accessed via the Appearance tab of the Workbench
Tools > Options dialog), the 1.0 option becomes unavailable for reselection.
Expert Settings
Expert settings provide you with advanced controls for some System Coupling properties.
Note:
When an analysis created with System Coupling 1.0 is switched to 2.0 (using the
Coupling Engine (p. 137) property), only 2.0 expert settings are available for selec-
tion and applied.
The selected setting is shown under Properties with a value of True (enabled).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
138 of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
Debug Output
When Debug Output is selected, the Global Level property is shown under Properties.
When this property is set to any value other than the default value of None, System Coupling
writes debug output files to its working directory. The basic level of detail included is controlled
by the value selected, with None generating no output and higher values generating more
detailed output.
Possible values:
• Level 1
• Level 2
• Level 4
• All Levels
For information on the output generated, see Debug Output (p. 206).
Note:
None of the other settings shown in the Properties pane are enabled; they have
no effect on the debug output generated.
When Intermediate Restart Data Output is selected, the following properties allow you to
define details about the restart data generated during the execution of the solution:
Output Frequency
Specify the frequency with which restart files are generated.
Possible values:
• None
No intermediate restart output files are generated using this option. (default value)
• All Steps
Restart output files are generated at the end of each coupling step.
• At Step Interval
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 139
Using System Coupling in Workbench
Restart output files are generated at the end of the coupling steps corresponding
to the interval specified by the Step Interval property.
Step Interval
Available when Output Frequency is set to At Step Interval. Specifies the interval at which restart
files are generated. For example, with a value of 3, System Coupling generates a restart point at
the end of every third coupling step.
Note:
Depending on the participant, the restart data may or may not be the same as the
results data. Writing of results data for postprocessing should be set from within
the participant Setup cell.
Important:
• All the properties that appear in the Outline of Schematic and Properties panes under the Solution
node.
• Context options for the Solution node and child nodes defined underneath it.
Alternatively, you can start the solution from the Project Schematic by right-clicking the System
Coupling system's Solution cell and selecting Update.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
140 of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
Note:
The default behavior of the Solution Information pane is to always show the latest in-
formation in the Log file. Each time new information is added, the file automatically
scrolls to the end. However, if you move the vertical scroll bar away from the bottom,
the pane won't scroll to the end when new information is added until you move the
scroll bar back to the end.
There are also some keyboard short-cuts that are available when operating in this pane:
For details on the solution information shown when you select System Coupling, see Transcript
and Log File (scLog.scl) (p. 197). For details on the solution information shown for a given
coupling participant, use the links in Supported Coupling Participants for System Coupling in
Workbench (p. 122) to access its product documentation.
Note:
When Beta Options are enabled in ANSYS Workbench, you can also select your own
text files to monitor in the Solution Information pane. To do this, right-click the Solution
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 141
Using System Coupling in Workbench
Information entry in the Outline pane, choose Create Solution Information (Beta)
and select the desired file.
Note:
Currently, System Coupling in Workbench does not plot participant quantities. However,
charting of participant quantities is available as a beta-feature. For more information,
see System Coupling Convergence Charting in the System Coupling Beta Features in the
System Coupling Beta Features documentation.
In the Outline of Schematic, you can use the context options (p. 145) for the Chart Monitors node
to create multiple charts, and then use the context options for the individual Chart nodes to select
the variables (p. 144) to be plotted.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
142 of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
The two variables, Variable 1 and Variable 2, with each being available for plotting at their
respective solver iterations and, by extension, all of the iteration's parent levels:
– Variable 1 is available at the Solver 1 Iteration level, so is also available at parent levels Solver 1
Step, Coupling Iteration, Coupling Step.
– Variable 2 is available at the Solver 2 Iteration level, so is also available at parent levels Solver 2
Step, Coupling Iteration, Coupling Step.
Chart Properties
When a Chart object is selected in the System Coupling tab's Outline of Schematic, its properties
are shown in Properties of Convergence Chart:
Axis X
Contains the following property:
Quantity
Level at which the X data for the variables is plotted. Possible values, which are determined by
the type of analysis being performed, are:
• Coupling Step
• Coupling Iteration
Axis Y
Contains the following property:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 143
Using System Coupling in Workbench
Title
Title of the Y axis for the chart.
Axis X, Axis Y
Properties supported for both axes:
Scale
Scale of the axis.
Possible values:
• Linear Common
• Natural Log
Automatic Range
Defines whether automatic scaling or range maximum and minimum are applied to the axis.
• When not selected, the range specified by the range minimum and maximum properties is
used.
Range Minimum
Available when the Automatic Range property is not selected. Minimum of the range of values
for the axis.
Range Maximum
Available when the Automatic Range property is not selected. Maximum of the range of values
for the axis.
Chart Variables
The System Coupling Chart Monitor plots data produced during the coupled solution process.
It can plot the following variables:
• diagnostic values (sum and average) taken from the nodal data associated with data transfers
You can add a variable to a chart by using its Chart node's Add Variable context option (p. 145).
Variables are organized by coupling participant and data transfer, as shown in Figure 14: Selection
of Convergence Chart variable (p. 145).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
144 of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
The variables to be plotted for a chart are listed under its Chart node in the Outline of
Schematic. When a chart variable is selected, its properties are shown in Properties of Chart
Variable.
Refinement Level
Specifies the level refinement for X axis variable data. Variable data plotted at the X axis level can
be further refined to any of the X axis' child levels. For example, if the X axis Quantity is defined
at the Coupling Step level, then the X data values for its variables can be refined to the Coupling
Iteration level.
In this case, the intermediate values available at the coupling iteration level between con-
secutive coupling steps are distributed equally between the coupling steps — that is, if
coupling step 2 has three coupling iterations, then the data points are plotted at 1.33, 1.66,
and 2.
Style
Contains the following properties that define the appearance of the chart:
Color
Defines the line color of the chart variable in a plot.
Line Width
Defines the width (in pixels) of the line for this chart variable.
Symbol Size
Defines the size of a symbol in (pixels) when a symbol is drawn for this variable.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 145
Using System Coupling in Workbench
Create Chart
Available for the Chart Monitors node.
Creates a new System Coupling chart without any variables defined. By default, the new
chart's X axis Quantity is set to the Coupling Iteration level.
Add Variable
Available for the Chart nodes.
Variables can be added to a chart after the solution has started or completed. Right-click an
existing chart, select Add Variable, and then select the variable to be added.
By default, the new variable's Refinement Level is set to the same level as the X axis
Quantity property. If data for the new variable is not available at that level, then the X axis
Quantity property and the variable's Refinement Level properties are both set to Coupling
Iteration.
Remove Variable
Available for the Chart nodes.
Right-click an existing chart, select Remove Variable, and then select the variable to be re-
moved.
Delete
Available for the Chart and chart variable nodes. Deletes the selected item from the chart.
Rename
Available for the Chart and chart variable nodes. Allows you to rename the selected item.
Note:
When the solution is started, a default chart is added if one is not already present. The
default variables added correspond to the RMS change in data on the target side of
all data transfers. For example:
If Data Transfer and Data Transfer 2 are defined with target participants equal to
Transient Structural and Fluid Flow, respectively, then the chart variables Transient
Structural: Data Transfer: Change: RMS and Fluid Flow: Data Transfer 2: Change:
RMS are added to the default chart.
If you add/delete variables to the default chart, then new variables are not added by
default on consecutive runs.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
146 of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
1. Right-click the background of the chart and select Save Image As.
3. Click the ellipsis ( ) button and navigate to the folder where you want to save the file.
4. Enter a filename.
6. Click Save and then click OK to save the file to the location and at the resolution you've selected.
Note:
When Quantity is set to Coupling Time, the first data point may be generated at 0
instead of the time the first coupling step finishes. The second and all subsequent
data points are then generated at the correct times, according to the Time Step Size
defined.
In turn, both of these are tied to the states of the Solution cells for all co-simulation participant systems
on the Project Schematic. The Solution node and all coupled Solution cells will have the same state,
which will reflect the least complete state of all coupled cells.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 147
Using System Coupling in Workbench
These commands are the same as those available on System Coupling's Solution cell in the Project
Schematic.
– Right-click Chart Monitor and select Create Chart to create a new System Coupling chart.
– Right-click a Chart node and select Add Variable or Remove Variable to change the variables plotted
on the chart.
Select this option to display error messages when System Coupling's Solution items are found to
be incorrect due to validation problems.
Note:
If a coupled analysis is interrupted before reaching the specified coupling duration, then
the Solution cells stay in an Update Required state once execution stops because the cal-
culation must be continued to complete the analysis. You can refresh and/or update
downstream Results cells to review the results generated up to the point at which the
analysis was interrupted.
For more information on typical cell states, see Understanding Cell States in the Workbench User's
Guide.
• Interrupt: Performs a clean shutdown. The analysis stops once the current coupling step is
completed.
• Abort: Stops the analysis immediately. All available generated data are discarded.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
148 of ANSYS, Inc. and its subsidiaries and affiliates.
Alternate Workflows for System Coupling in Workbench
Note:
When you click the Interrupt or Abort button, a Shutdown (p. 194) file is automatically
generated in System Coupling's working directory and tells both System Coupling and
participant services to shut down.
You can also create this file manually and place it in the working directory, as described
in Shutdown File (scStop) (p. 194). In this case, however, you must end any participant
processes yourself.
Note:
For information on restarts from one of System Coupling's user interfaces, see Restarting a Coupled
Analysis (p. 88).
Restart points are generated at the end of a coupling step. To generate restart files for a coupled
analysis:
1. Before starting the initial run of the analysis, ensure that all coupling participants are set up to save
(or retain) the corresponding restart points during the analysis. For information on a given participant,
see Supported Coupling Participants for System Coupling in Workbench (p. 122) for a list of supported
systems and references to their corresponding documentation regarding restarts.
2. Set up the System Coupling system to control the creation of restart points at certain intervals during
the execution of the coupled analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 149
Using System Coupling in Workbench
3. In the Outline, select System Coupling > Setup > Execution Control > Intermediate Restart Data
Output.
4. In Properties pane, set Output Frequency to one of the options described in Intermediate Restart
Data Output (p. 139).
Note:
• For coupled analyses set up in Workbench, restarts are not supported if the default participant
names (Solution, Solution 1, etc.) have been changed.
• For ramping and under-relaxation during a restarted run, the final values from the previous
coupling step of the initial run are not currently available. For the first iteration of a restarted
run, upon remapping, the reference values are reset to initial values upon remapping (i.e.,
they are identical to the mapped target-side values). As a result, no ramping or under-relax-
ation is applied during this iteration.
1. For each participant connected to the System Coupling system, specify a restart point in the participant
application. Make sure that these restart points correspond to the restart point you'll choose in System
Coupling.
For instructions on selecting a restart point for a given participant, see Supported Coupling
Participants for System Coupling in Workbench (p. 122) and follow the link to its documentation.
For instructions on changing settings for a given participant, see Supported Coupling Participants
for System Coupling in Workbench (p. 122) and follow the link to its documentation.
Note:
Changes saved prior to the restart (either in System Coupling or in any participant
except Mechanical) are written to the Settings (p. 207) file and included in the restarted
run.
a. Double-click System Coupling's Setup or Solution cell to open the System Coupling tab.
b. Change the required System Coupling settings. Setup changes commonly include changes to a
combination of the following:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
150 of ANSYS, Inc. and its subsidiaries and affiliates.
Alternate Workflows for System Coupling in Workbench
a. On the Project Schematic, open the System Coupling tab by double-clicking System Coupling's
Setup or Solution cell.
b. In the Outline under Analysis Settings > Properties, set Coupling Initialization to the restart
point corresponding to the restart point you selected in the participant systems.
5. In the Outline, right-click Solution and select Update to restart the solution.
System Coupling goes to the end of the specified coupling step and continues the solution with
the next step.
The usual project directory (ProjectName_files) contains the latest System Coupling results
and restart points (these solvers use the live project instead of running in a temporary directory).
Note that the .backup directory contains the original version of any files which have been modified
since the last save. These files are useful to recover the last saved state, but they are not useful for
restarting your analysis.
2. The project will be locked because it was not shut down cleanly. When asked what you want to do
with the project, click Unlock.
3. When asked if you want to recover the last saved state before opening, click No.
The state shown on the Project Schematic shows that the solution had not started, but you'll
find that backup files are available. Note, however, that your Workbench project doesn't know
about these files.
4. Populate the restart data from the participant systems connected to the System Coupling system,
ensuring that these points correspond to the restart point specified in System Coupling.
For information on how to do this for a given participant, see Supported Coupling Participants
for System Coupling in Workbench (p. 122) and follow the links to its documentation.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 151
Using System Coupling in Workbench
a. On the Project Schematic, right-click System Coupling's Setup cell and select Update.
c. In the Outline, select Analysis Settings, then in Properties of Analysis Settings, right-click
Coupling Initialization and select Read Restart Points.
d. In Properties, for Coupling Initialization, pick a restart point that corresponds to the restart point
you selected in the participant systems.
Note:
Ensure that the paths to all required scripts and executables are added to the PATH envir-
onment variable so that participating applications can be launched from the GUI or CLI.
At the same level as your Workbench project, create a directory structure for the coupling run, as
described in Creating a Coupled Analysis Directory Structure (p. 56).
Set up the coupled analysis exactly as you would for an analysis to be run in Workbench, as de-
scribed in Setting Up a Coupled Analysis in Workbench (p. 126).
After each participant is set up but before you exit the participant application, generate a solver
input file to the participant's coupling working directory.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
152 of ANSYS, Inc. and its subsidiaries and affiliates.
Alternate Workflows for System Coupling in Workbench
For information on acceptable file types for each participant, see the description of the SCP file's
<InitialInput> (p. 181) setting.
Note:
• Before generating input files, ensure that the corresponding system's Setup cell on the
Project Schematic is in an Up-to-Date state.
• Because Mechanical must be set up in Workbench, when it generates a solver input file, it
also always generates a SCP file. This file is only needed, however, for a GUI or CLI-based
analysis in which the other participants are set up outside of Workbench.
• Generate the Fluent solver input file before updating the Workbench solution. Otherwise,
all generated data will be cleared and the file will be generated from the most recent case
and data files, instead of the original ones.
• The CFX-Solver input file is generated when data transfers are created. If the coupled ana-
lysis has a CFX coupling participant and you plan to execute it in System Coupling's GUI or
CLI, do not connect systems on the Project Schematic until after the solver input files and
the SCI file have been generated. Once the files have been generated, you need only to
move the sovler input file to the CFX participant's coupling working directory.
After the System Coupling tab is set up, generate a System Coupling SCI (p. 187) to the coupled
analysis working directory by selecting Export SCI File from the System Coupling tab's File menu.
This file will be used to populate the data model for your coupled analysis run.
Important:
If you plan to import an SCI file for a System Coupling GUI or CLI run, it's a best
practice to always ensure that this information exists for each participant, as follows:
• For projects created with Workbench 18.2 or earlier: Before exporting the SCI file, delete
and then recreate the schematic connections between participant systems and the System
Coupling system.
• For projects created with any earlier version of Workbench: After exporting the SCI file,
verify that it includes a <ParticipantType> definition for each participant and add the
information manually, if needed.
For instructions on running your Workbench setup from a System Coupling user interface, see Running
a Workbench Setup in a User Interface (p. 118).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 153
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
154 of ANSYS, Inc. and its subsidiaries and affiliates.
Coupled Analysis Management
One of the main roles of System Coupling is to manage the coupled analysis. During execution, System
Coupling performs a variety of one-way and two-way data transfers between coupling participants.
• A one-way coupled analysis has a data transfer in only one direction between the coupled participants.
The source region is defined only on the participant sending data and the target region is defined on only
the participant receiving the data.
• A two-way coupled analysis has data transfers in both directions between the coupled participants. Source
and target regions are defined on both participants.
When multiple participants execute their individual parts of a coupled analysis together, it's called a
co-simulation. In co-simulation, each participant can engage in both one-way and two-way data
transfers as either a source or target and perform their solutions simultaneously.
However, when a participant provides access to a static data source, such as existing results or data
incorporated into a Workbench-based coupled analysis, it can engage only in one-way data transfers
as a source.
For details on the various aspects of the coupling management process, see:
Inter-Process Communication
Process Synchronization and Analysis Evolution
Convergence Management
Evaluating Convergence of Data Transfers
Inter-Process Communication
System Coupling and participants, which are often highly optimized physics solvers, are executed as
independent computational processes, and this introduces the need for Inter-Process Communication
(IPC). This communication is realized using a proprietary, light-weight, TCP/IP based client-server infra-
structure that does not interact with other communication mechanisms like the Message Passing Interface
(MPI).
All high-level communication needed for process synchronization, brokering data transfers and managing
convergence between System Coupling and participants is defined in terms of Application Programming
Interfaces (APIs) that use the low-level IPC infrastructure.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 155
Coupled Analysis Management
The five primary synchronization points used to manage advancement through the coupled analysis
are shown in Figure 15: Execution sequence diagram for System Coupling and co-simulation parti-
cipants (p. 156). This figure also features notes on the processing that occurs between these points, as
well as the coupling step and iteration loop structure. Each of these synchronization points, shown in
dark gray, represents a gateway beyond which a given process may not advance until all other processes
(or a subset thereof, as controlled by System Coupling) arrive. Note, as well, that while a process may
serve data both between and at synchronization points, it may only request data between synchroniz-
ation points.
Figure 15: Execution sequence diagram for System Coupling and co-simulation participants
Details on processing between the Solution and Check Convergence synchronization points are shown
in Figure 16: Processing details for System Coupling and co-simulation participants (p. 157). During this
stage of the analysis, System Coupling controls the advancement of co-simulation participants, or
solvers, through two secondary synchronization points: Data Transfer and Solve, both shown in light
gray.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
156 of ANSYS, Inc. and its subsidiaries and affiliates.
Evaluating Convergence of Data Transfers
Figure 16: Processing details for System Coupling and co-simulation participants
These figures highlight that all participants traverse the duration of the entire coupling step during
each coupling iteration. They have complete freedom, however, to traverse the coupling step duration
in one or more "solver" steps, each of which may include one or more solver iterations. If multiple
"solver" steps are used within one coupling step, then this is referred to as sub-stepping (or sub-cycling).
Review the participant systems' documentation to see if sub-stepping occurs and is supported with
System Coupling.
Convergence Management
By default, System Coupling's Log file (p. 197) reports Root Mean Square (RMS) convergence for data
transfers for both the source and target side of the transfer. Convergence of the coupling step is evaluated
at the end of each coupling iteration. Coupling step convergence requires that:
• the target side RMS values have reached the convergence criteria that you specified in the input to the
System Coupling setup, and
• that the minimum number of coupling iterations that you specified are met.
If the coupling step is not yet converged, then a new coupling iteration is started. If the coupling step
has converged, then a new coupling step is started if the coupling duration has not yet been reached.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 157
Coupled Analysis Management
Two global (that is, over all locations) measures of convergence are evaluated and reported during ex-
ecution of the coupled analysis. These include the maximum and Root Mean Square (RMS) of the nor-
malized change in data transfer values. The RMS is the default measure used to determine convergence.
The measure can be changed to the maximum of the normalized value through the System Coupling
Input file.
where is the normalized change in the data transfer value between successive iterations within/across
a given coupling step, and is measured as:
(2)
where is the data transfer value, and l is the location of the data transfer on the coupling interface.
In Equation 2 (p. 158), the denominator, or normalization factor, is evaluated differently in the transient
and general coupling analyses. In the transient coupling case, the normalization factor equals the average
of the range and mean of the magnitude of data transfer values over all locations for the current iteration.
In the general coupling case, it equals the average of the range and mean of the magnitude of data
transfer values over all locations for all iterations in the entire analysis. This normalization factor is a
representative scale for the data transfer values and ensures that division by zero (due either to zero
range or zero mean) is avoided.
In Equation 2 (p. 158), the numerator, , is the un-normalized change between successive iterations,
and is expressed as:
(3)
where and correspond to the current and the previous iterations respectively, and is the
under-relaxation factor applied in forming the final value applied during the current iteration. In the
first coupling iteration of every coupling step, is assumed to be unity.
When there is no change in data transfer values, the default for RMS/MAX is 1.0e-014.
Note:
The global data transfer convergence measures are set to unity in the first coupling it-
eration of the first coupling step during an initial run. After a restart, if a data transfer
involving a new variable is defined or if the region is remeshed, these measures are set
to unity in the first coupling iteration of the first coupling step.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
158 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Data Transfers
During a coupled analysis, one of System Coupling's core functions is to manage data transfers between
the coupling participants. A data transfer is the transfer of a single quantity type in one direction
between regions on the source participant and target participant.
• Force
• Motion
• Thermal
The source participant region must be able to send the quantity and the target participant region must
be able to receive the quantity type being transferred. Data transfers of different quantity types are
possible in different directions between the same participants and regions.
For example, consider a coupled one-way thermal analysis in which Fluent and Mechanical are the
participants. In this co-simulation, the fluids region is the source for the transfer of temperature and
the structural region is the target for the transfer of that temperature. This could be extended to a two-
way thermal analysis by introducing transfer of heat rate from the structural region to the fluids region.
Force and motion transfers are typical for fluid-structure interaction problems, where a load to the
structure is transferred from a fluid solver, and the deformations to the fluid are transferred from the
structural solver.
• A given target region can receive data from only a single source region. However, a given source region
can send data to multiple target regions according to participant support of multi-region interfaces.
Note:
Data transfers to multiple target regions are subject to participant support. Currently,
only Fluent and Maxwell support multiple regions on both source and target locations.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 159
System Coupling Data Transfers
• A given region cannot both send and receive the same quantity type. For example, the same region
cannot both send and receive temperature data.
• A transfer of HTC+Tref is equivalent to a transfer of heat rate. If a transfer of HTC+Tref is defined, then a
transfer of heat rate cannot be defined, and vice versa.
• A single region cannot be the source of both temperature and heat rate, nor the target of both temperature
and heat rate.
Note:
System Coupling and System Coupling in Workbench each define and handle data transfers
slightly differently. For context-specific details, see Data Transfers for System Coupling in
Workbench (p. 123) or Rules for the Creation of Data Transfers (p. 36).
Mapping is the process of using data on a source mesh to calculate data on a target mesh. System
Coupling uses various mapping algorithms perform the following tasks:
Supplemental processing may be applied to data before and/or after mapping. System Coupling
uses various supplemental processing algorithms to perform the following tasks:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
160 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
System Coupling performs two types of mapping, profile-preserving and conservative, and each has
its own objectives.
The mapping process consists of two distinct phases: the association of source and target locations
and the generation of target data.
Mapping Topologies
System Coupling can create mappings between participant regions of the following topologies:
• Surface (2D)
• Volume (3D)
Mapping can occur between participant regions of like topology, and in some cases, between parti-
cipant regions of unlike topologies (e.g., planar surface-to-volume). Support for different combinations
of topologies in a given transfer varies according the coupling context, as shown in the table below.
Because mapping is performed only at the start of the System Coupling simulation, the mesh topology
on the data transfer regions cannot change (that is, cannot be dynamically remeshed) during the
simulation.
Mapping Types
System Coupling performs two types of mapping, each with its own objectives:
Profile-Preserving Mapping
• The goal of profile-preserving mapping is to minimize the difference between the profile, or distribution
of data, on the source and target mesh locations.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 161
System Coupling Data Transfers
• Profile-preservation is enforced to the extent possible, based on the least-resolved topology from the
source/target region combination.
• Not all target locations receive data originating from the interface source. For target locations that
are not mapped (i.e., do not overlap with source locations), target data are generated based on the
values of other mapped nodes. For details, see Generating Data for Target Locations (p. 164).
– Scalar quantities:
→ Temperature
– Vector quantities:
→ Incremental Displacement
Conservative Mapping
• The goal of conservative mapping is to minimize the difference between the sum of the data (locally
and globally) on the source and target mesh locations.
• Conservative mapping is used to transfer conservative quantities, such as force or heat rate, from in-
terface source to target regions.
• Not all target locations receive data originating from the interface source. Specifically, target locations
that do not overlap with source locations are assigned a value of zero.
– Scalar quantities:
→ Mass Flow
→ Heat Rate
– Vector quantities:
→ Force
In all cases, data from the source-side of the interface is used to calculate data on the target-side of
the interface at either element or node locations. If algorithms require data on locations not provided
or consumed by either side of the interface, then it is reconstructed by a supplemental algorithm, as
described in Data Reconstruction Algorithms (p. 172). Diagnostics are provided for all mapping types
to aid in assessing the quality and accuracy of target data.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
162 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
When a source location overlaps a target location and an association is created, the target location
is said to have been successfully "mapped." When no overlap exists and no association can be made,
the target location is said to have been left "unmapped."
The association algorithm used is determined by the topologies of the participant regions involved
in the mapping:
Projection:
– Figure 18: Example input and output for Linear Shape Function mapping (p. 166) (Profile-Preserving)
– Figure 24: Example input and output for conservative Intersect-Scatter-Gather mapping between
like topologies (p. 170) (Conservative)
Coincident:
– Figure 20: Example input and output for Radial Basis Function mapping (p. 167) (Profile-Preserving)
– Figure 24: Example input and output for conservative Intersect-Scatter-Gather mapping between
like topologies (p. 170) (Conservative)
Extrusion:
Note:
The planar surface must be within one diameter of the volume mesh for mapping
to occur. For best results, ensure that the orientation of the planar surface and its
location with respect to the volume are consistent with your problem setup.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 163
System Coupling Data Transfers
– Figure 22: Example input and output for Element-Weighted Average mapping (p. 168) (Profile-Pre-
serving)
– Figure 26: Example input and output for conservative mapping for Intersect-Scatter-Gather between
unlike topologies. Circled values are the total for the elements. (p. 171) (Conservative)
The BSP algorithm fits a uniform structured grid of two cells to the source region(s). Each cell that
contains more than a predetermined number of source mesh locations is recursively subdivided
into two new cells in a direction that is orthogonal to the preceding division. This continues to
form a hierarchical tree structure, as shown in the figure below, until either the maximum number
of levels in the hierarchy is reached or the predetermined number of source mesh locations per
tree cell is reached. BSP tree cells at this level are referred to as "leaf cells."
Figure 17: Example of a BSP tree mesh on a 2D target domain, which extends naturally to 3D
(source mesh locations not shown for clarity)
Each target mesh location is ultimately associated with one or more leaf cells. Efficiency is realized
by associating the target mesh locations with a cell at each level within the tree hierarchy, starting
with the highest (largest) cells first.
• For profile-preserving mapping, the association goes from target to source. Once a target node
is associated with a leaf cell(s), it is associated with the most suitable source element and/or nodes.
• For conservative mapping, the association goes from source to target. Once the source element
is associated with a leaf cell(s):
– For surface transfers or planar surface transfers, the source element is associated with inter-
secting target elements. Care is taken to appropriately consider the relative orientation and
normal distance between associated source and target elements.
– For volume transfers, the source element is associated with intersecting target elements.
When data is transferred to the target location, its fidelity is limited by the least-resolved side of the
interface. For example, if the target mesh is significantly coarser than the source mesh, then fine-scale
features of the source solution may be missed in mapping. Similarly, if the target mesh is significantly
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
164 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
finer than the source mesh, then the piece-wise constant or linear variation of source data will be
apparent over groups of elements on the target side.
Different methods are used to generate data on mapped vs. unmapped target locations, as follows:
The algorithm System Coupling uses is determined by the type of mapping being performed plus
the topologies of involved participant regions. Given coupling support for the various combinations
of these attributes, the following data-generation algorithms are available:
• Element-Weighted Average
• Intersect-Scatter-Gather
– Mapping weights are generated by intersecting the source and target meshes, followed by
scattering source data to and collecting it from the intersected elements
→ A version for like topologies is used for conservative surface-to-surface and volume-to-
volume mapping
→ A version for unlike topologies is used for conservative planar surface-to-volume mapping
For more information, see Profile-Preserving Mapping Algorithms (p. 166) and Conservative Mapping
Algorithms (p. 169).
• For conservative mapping, unmapped target elements are assigned a value of zero.
• For profile-preserving mapping, target data is generated on unmapped target locations based on
the values of other mapped nodes. The variation used is determined by the topology of the source
region.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 165
System Coupling Data Transfers
– For profile-preserving surface mapping or planar surface mapping (with either a 2D or 3D source
region), target data is calculated from the value of the nearest target-side node.
– For profile-preserving volume mapping (with a 3D source region), target data is calculated from
the value of the nearest source-side node.
Table 12: Mapping algorithms by mapping type and region topology (p. 166) below shows the different
association and target data generation algorithms for profile and conservative mapping on various
topologies.
Quantities located on source mesh nodes are mapped to target mesh nodes, as shown in the
figure below.
Figure 18: Example input and output for Linear Shape Function mapping
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
166 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
Mapping weights are generated using linear finite element shape functions of the source element
associated with each target node, as shown in the figure below.
Figure 19: Mapping weights generated for a target node, based upon its projection onto a
source element via Linear Shape Function mapping
Quantities located on source mesh nodes are mapped to target mesh nodes, as shown in the
figure below.
Figure 20: Example input and output for Radial Basis Function mapping
Mapping weights are generated using radial basis functions (RBFs) for the source nodes that
define the associated source elements. Example weights are shown in the figure below.
Figure 21: Example mapping weights wi generated for a target node (T), based on the
distance to nodes with the associated source elements Si via Radial Basis Function mapping
Element-Weighted Average
For transfers of profile-preserving quantities from a volume to a planar surface, the Element-
Weighted Average algorithm is used to generate target data for mapped locations. Figure 20: Ex-
ample input and output for Radial Basis Function mapping (p. 167).
Quantities located on the source mesh nodes are mapped to target mesh nodes, as shown in
the figure below.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 167
System Coupling Data Transfers
Figure 22: Example input and output for Element-Weighted Average mapping
Intersection points are created by projecting the target (surface) nodes through the source
(volumetric) elements. Mapping weights are generated by taking a length-weighted average of
the line segment within each intersecting volumetric element. For an illustration, see the figure
below.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
168 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
Figure 23: Mapping weights generated for a target node (T), based upon its extrusion onto
source elements via Element Weighted Average mapping. Representative weight calculation
is shown for node 3; other weights are computed in a similar manner.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 169
System Coupling Data Transfers
Data located on the source mesh elements are mapped to target mesh elements, as shown in
the figure below.
Note:
Note: For mapping that uses the Coincident association method, the meshes are directly
on top of one another.
Figure 24: Example input and output for conservative Intersect-Scatter-Gather mapping
between like topologies
Mapping weights are generated based upon information extracted from intersecting the target
element with associated source elements. In particular, the size of each intersected region relative
to the size of the respective source element is used, as shown in the figure below.
Figure 25: Mapping weights generated for a target element, based on its intersection with
source elements via Intersect-Scatter-Gather between like topologies
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
170 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
Data located on the source mesh elements are mapped to target mesh elements, as shown in
the figure below.
Figure 26: Example input and output for conservative mapping for Intersect-Scatter-Gather
between unlike topologies. Circled values are the total for the elements.
When the target (surface) elements are extruded onto source (volume) elements, intersections
are created between the resulting target (pseudo-volumetric) elements and the source (volumetric)
elements. Mapping weights are generated by taking a volume-weighted average of the intersecting
volume between the target and source elements. For an illustration, see the figure below.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 171
System Coupling Data Transfers
Figure 27: Mapping weights generated for a target node, based upon its extrusion onto a
target element via Intersect-Scatter-Gather between unlike topologies
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
172 of ANSYS, Inc. and its subsidiaries and affiliates.
Supplemental Processing Algorithms
from those required by the mapper or when the mapper provides values at mesh locations different
from those required by the target participant.
Note:
Creating Nodal Data from Face/Element Centroid Data Conservative variable values (such as
forces or heat rates) may be available on element (face) centroids. If the values are required on nodes,
the following steps are executed:
• For a given element, the contribution to the node value is calculated by dividing the value at the
element by the number of nodes that define that element; and
• These individual element contributions are accumulated at the node for each element adjacent to
this node.
Creating Face/Element Data from Node Data Conservative variable values (such as forces or heat
rates) may be available on nodes. If the values are required on elements/faces, the following steps
are executed:
• For a given node, the contribution to the element value is calculated by dividing the value at the
node by the number of elements adjacent to that node; and
• These individual nodal contributions are accumulated at each element for each node that defines
that element.
Ramping Algorithm
The ramping controlled by System Coupling is used to improve convergence of the overall analysis.
It works by slowing the application of the source-side value on the target-side of the data transfer.
For each data transfer location (node) where is true, the following formula is applied:
(4)
where
is the reference target-side value, which for the first coupling step is the
initial value for the data transfer variable (see Table 13: Initial values used for the
reference target-side value (p. 176)). Thereafter, the reference target-side value is the
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 173
System Coupling Data Transfers
final value from the previous coupling step. The one exception is displacement, where
for every coupling step, is always 0.0 [m].
Note:
For restarted runs, the final values from the last coupling step of the initial
run are currently unavailable. For the first iteration of a restarted run, upon
remapping, the reference values are reset to initial values upon remapping
(i.e., they are identical to the mapped target-side values). As a result, no
ramping is applied during this iteration.
is the raw, target-side value obtained from interpolation or from the initial value
specified with the Source_InitValue_HeatTransferCoef expert setting.
is the current coupling iteration number within the coupling step.
is the minimum number of coupling iterations per coupling step.
When ramping is enabled (i.e., for System Coupling in Workbench, the Ramping setting is set to
Linear to Minimum Iterations; or for command-line System Coupling, the RampingOption data
model setting is set to Linear , within each coupling step, the ramping factor is used to linearly
increase the change in the data transfer value applied to the target side of the interface. The data
transfer value is increased during each coupling iteration until the specified minimum number of
coupling iterations, , is reached. The ramping factor is applied to the change in the data transfer
value from the last coupling iteration of the previous coupling step. If there is no change in this value
from the last coupling step, the full data transfer value is applied to the target side of the interface
for all coupling iterations of that coupling step.
During the coupling iteration (for ), the ramping factor equals . The full data transfer
value is applied for all coupling iterations that are equal to or greater than the minimum number of
coupling iterations. As is always reached, the full data transfer value is always applied by the
end of each coupling step. This ramping behavior is demonstrated in Figure 28: Schematic of the
Linear to Minimum Iterations ramping concept (p. 175) for the case where the minimum number of
iterations specified is 5.
When ramping using Linear to Minimum Iterations, if the minimum number of iterations is the
same as the maximum number of iterations, then it is unlikely that the data transfer will converge. It
is a best practice for your maximum iterations to be larger than your minimum iterations.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
174 of ANSYS, Inc. and its subsidiaries and affiliates.
Supplemental Processing Algorithms
For data model details, see Ramping Option in the System Coupling Settings and Commands Reference
manual.
Under-Relaxation Algorithm
Under-relaxation is used to improve convergence of the overall analysis. It works by limiting a poten-
tially large variation of the target-side data between two successive coupling iterations. For each data
transfer location (node), the following formula is applied:
(5)
where
Note:
For restarted runs, the final values from the last coupling step of the initial
run are currently unavailable. For the first iteration of a restarted run, upon
remapping, the reference values are reset to initial values upon remapping
(i.e., they are identical to the mapped target-side values). As a result, no
under-relaxation is applied during this iteration.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 175
System Coupling Data Transfers
is the raw, target-side value obtained from interpolation or from ramping (if
applied), or from the initial value specified with the settings described in
Source_InitValue_HeatTransferCoef.
Note that if you have applied both ramping and under-relaxation, the data are first
ramped and then under-relaxed. In this case, for the under-relaxation's
raw target-side value.
ω is the under-relaxation factor (URF). In a transient analysis, in the first coupling iteration
of every coupling step, the URF is overridden and set to 1, and so data transferred at
this coupling iteration is not under-relaxed.
For data model details, see Relaxation Factor in the System Coupling Settings and Commands Reference
manual.
Note:
For ramping and under-relaxation during a restarted run, the final values from the previous
coupling step of the initial run are not currently available. For the first iteration of a restarted
run, upon remapping, the reference values are reset to initial values upon remapping (i.e.,
they are identical to the mapped target-side values). As a result, no ramping or under-re-
laxation is applied during this iteration.
Table 13: Initial values used for the reference target-side value
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
176 of ANSYS, Inc. and its subsidiaries and affiliates.
Supplemental Processing Algorithms
Thermal Analysis:
• For transfers of Temperature and Heat Rate quantity types, reaching convergence can be challenging
if the participant sending Heat Rate has a thermal resistance of the same order as, or smaller than, the
participant sending Temperature. Usually, a fluid region sends Heat Rate to a solid region, so this may
occur if the fluid region has a small thickness or large conductivity relative to the solid region.
• Heat Rate transfer with transfers of Heat Transfer Coefficient and Convection Reference Temperature
quantity types (if supported by the participants) is more robust but may also converge slowly.
FSI Simulations:
• For transfers of Force and Incremental Displacement quantity types, reaching convergence can be
challenging if the physics are strongly coupled — i.e., a small change in the fluid Force leads to a sig-
nificant change in deformation or vice versa. This is particularly common when the solid body is slender
or if the solid density is comparable to or smaller than the fluid density, leading to significant added
mass effect.
• Participant solution stabilization (p. 223) may improve stability in this situation but may also require
problem-dependent tuning.
When the Quasi-Newton stabilization method is used, interface unknowns are stabilized using Quasi-
Newton iterations with the inverse Jacobian approximated by a least-squares model [1].
The Quasi-Newton method can be used when System Coupling is run in either of its user interfaces
(GUI or CLI). For more information, see:
Quasi-Newton Recommendations
Quasi-Newton Limitations
For data model details, see Stabilization in the System Coupling Settings and Commands Reference
manual.
Bibliography
[1] Joris Degroote, Robby Haelterman, Sebastiaan Annerel, Peter Bruggeman, and Jan Vierendeels.
Performance of partitioned procedures in fluid-structure interaction. Computers and Structures 88:
446-457, 2010. DOI=http://dx.doi.org/10.1016/j.compstruc.2009.12.006
Quasi-Newton Recommendations
When applying the Quasi-Newton method to a System Coupling data transfer, consider the following
recommendations to ensure optimal stabilization:
• For a thermal analysis, you should transfer Temperature and Heat Rate quantity types (not Heat Transfer
Coefficient and Convection Reference Temperature), since these are conservative and usually converge
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 177
System Coupling Data Transfers
faster when combined with stabilization. Stabilization should be applied to one of the transfers, but
not both. In our experience, applying stabilization to Heat Rate is recommended.
• For an FSI analysis, if you are experiencing convergence difficulties, try applying stabilization to either
Force or Incremental Displacement quantity types, but not both. In our experience, applying stabilization
to Force is recommended.
• If the simulation involves multiple coupling regions, stabilization is most effective if the regions are
grouped together into a single coupling interface rather than keeping them as separate interfaces.
• Strongly-coupled FSI simulations may not converge deeply enough if the number of coupling iterations
is too small. The default maximum number of coupling iterations per timestep in a transient analysis is
five; a larger value of 10 or 20 is recommended for such situations
• Quasi-Newton stabilization should generally not be combined with ramping, relaxation, or participant
stabilization.
Quasi-Newton Limitations
Currently, the Quasi-Newton algorithms has the following limitations:
• For steady-state simulations, Quasi-Newton can be used only if there are multiple coupling iterations
and a single coupling step.
• Quasi-Newton data from previous steps are not restarted when the value of the Maximum Retained
Iterations setting is greater than 1. This may change the convergence history, compared to a
solution which is not restarted, but will not affect the converged result.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
178 of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Input and Output Files
This section describes System Coupling's input and output files – the files it consumes and the files it
produces during the setup and execution of a coupled analysis. For more information, see:
Files Used by System Coupling
Files Generated by System Coupling
<participantObject>.scp
These XML-formatted files provide System Coupling with the participant-specific information needed
to connect the participants to a coupling run.
Important:
The sole purpose of a SCP file is to allow the participant to be added to a coupled analys-
is (p. 59). When participants are added, the information from their SCP file populates the
data model and then is saved, as part of the analysis state, to the Settings file (Set-
tings.h5) (p. 207). From this point, the analysis draws its setup information from the
Settings file, not from the participant SCP files.
It is recommended that you do not attempt to change participant settings by editing SCP
files manually, as this may invalidate the data model and/or cause a mismatch between
the analysis and its Settings file.
Also, keep in mind that re-loading an SCP file to an existing analysis overwrites the setup
details in the corresponding Settings file, so this should not be done unless you intend to
start over with the analysis setup. If you do attempt to change participant settings by
editing SCP files, ensure that edits are made before you start setting up the analysis (i.e.,
load participants, create interfaces, etc.).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 179
System Coupling Input and Output Files
<CouplingParticipant>
<ExecutionControl>
<WorkingDirectory/>
<InitialInput/>
<Command/>
</ExecutionControl>
<CosimulationControl>
<Type/>
<AnalysisType/>
<DisplayName/>
<RestartsSupported/>
<Variables>
<Variable>
<Name/>
<DisplayName/>
<QuantityType/>
<Location/>
</Variable>
</Variables>
<Regions>
<Region>
<Topology/>
<Name/>
<DisplayName/>
<OutputVariables>
<Variable/>
</OutputVariables>
<InputVariables>
<Variable/>
</InputVariables>
</Region>
</Regions>
</CosimulationControl>
</CouplingParticipant>
For an example, see Sample System Coupling Participant File (p. 187).
Note:
• The use of both SCI and SCP files in the same analysis is not supported.
• In the sections that follow, noted commands and queries can be run either in the System
Coupling CLI in the System Coupling GUI's Command Console.
<CouplingParticipant>
<ExecutionControl/> (p. 180)
<CosimulationControl/> (p. 182)
</CouplingParticipant>
<ExecutionControl>
Container element for settings that control the execution of the participant. Provides the information
needed to start the coupling participant.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
180 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
Optional. If this element does not exist, System Coupling populates the Execution Control part of
the data model with values based on the participant type.
<ExecutionControl>
<WorkingDirectory/> (p. 181)
<InitialInput/> (p. 181)
<Command/> (p. 182)
</ExecutionControl>
<WorkingDirectory>
Defines the participant's working directory, where the solver is executed. By default, this is the
full path to the directory to which the participant writes its solver input and SCP files.
Note:
• If you move the SCP file to a different location, then System Coupling can still find it.
However, if you move the participant's solver input file to a different location, then you
must manually edit the SCP file so that the participant's <WorkingDirectory> element
reflects the new location of the input file.
Optional. When this element does not exist, the participant is executed in System Coupling's
working directory.
<InitialInput>
Defines the name of the solver input file to be used for the initial run of the coupled analysis.
• For an AEDT participant, it must refer to a solver input file (.py), which in turn refers to an ANSYS
Electronics Desktop project file (.aedt), such as eddy.aedt and eddy.py.
• For a CFX participant, it must refer to a CFX-Solver input (.def or .res) file, such as cfx.def or
cfx_SC_001.res.
It can refer to a Fluent case file (.cas, .cas.gz, or .cas.h5), either with or without the
extension, such as FFF.cas, FFF.cas.gz, FFF.cas.h5, or FFF. In this case, System
Coupling generates its own Fluent journal script to read this case file.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 181
System Coupling Input and Output Files
– Alternatively, it can refer to a custom Fluent journal file (.jou). In order for this to work, the
journal file must have a .jou extension.
• For an MAPDL participant, it must refer to an Mechanical APDL solver input file (.dat), such as
ds.dat.
<Command>
Specifies the command that can be used to start the coupling participant automatically.
Optional. Note that this element is not included when a participant generates its System Coupling
Participant (SCP) setup file because System Coupling can locate the participant's execution
command based on other information from the file.
To obtain the command used to start a participant, run GetExecutionCommand for the parti-
cipant. For participant-specific details, see the participant's documentation on executing from
the command line.
<CosimulationControl>
Container element for settings that control how the participant can act in a co-simulation. Provides
the information necessary to set up couplings and to execute the participant in the co-simulation.
Required.
<CosimulationControl>
<Type/> (p. 182)
<AnalysisType/> (p. 183)
<DisplayName/> (p. 183)
<RestartsSupported/> (p. 183)
<Variables/> (p. 183)
<Regions/> (p. 185)
</CosimulationControl>
<Type>
Specifies the type of participant.
Possible values:
• AEDT
• CFX
• FLUENT
• MAPDL
• DEFAULT
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
182 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<AnalysisType>
Specifies the type of coupled analysis to be performed.
Possible values:
• Steady: Used when all the participants are executing a steady solution. (default)
• Transient: Used when any of the participants are executing a transient solution (including mixed
steady-transient analyses).
<DisplayName>
Specifies the participant name to be displayed in user-facing communications.
Optional. When not specified, the name of the participant object in the data model is used.
<RestartsSupported>
Indicates whether the participant supports restarts.
Possible values:
• False: Indicates that the participant does not support restarts. (default)
<Variables>
Container element for the set of variables that are available for coupled simulations.
<Variables>
<Variable> (p. 183)
</Variables>
<Variable>
Defines a variable that is available for coupled simulations. Nested under <Vari-
ables> (p. 183).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 183
System Coupling Input and Output Files
<Variable>
<Name> (p. 184)
<DisplayName> (p. 184)
<QuantityType> (p. 184)
<Location> (p. 184)
</Variable>
<Name>
Specifies the variable name to be used internally by System Coupling and the participant.
Required.
<DisplayName>
Optional. If not specified, the variable's data model <Name> (p. 184) is used.
<QuantityType>
Required.
Possible values:
• Force
• Incremental Displacement
• Heat Rate
• Temperature
<Location>
Possible values:
• Element
• Node
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
184 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<Regions>
Container element for the set of regions that are potentially available for coupled simulations.
<Regions>
<Region> (p. 185)
</Regions>
<Region>
Defines a region that is potentially available for coupled simulations. Nested under <Re-
gions> (p. 185).
<Regions>
<Topology> (p. 185)
<Name> (p. 185)
<DisplayName> (p. 186)
<OutputVariables> (p. 186)
<InputVariables> (p. 186)
</Regions>
<Topology>
Defines the spatial dimensionality of the data being transferred to/from the region.
Required.
Possible values:
• Planar Surface
• Surface
• Volume
<Name>
Specifies the region name to be used by System Coupling and the participant.
Required.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 185
System Coupling Input and Output Files
<DisplayName>
Optional. If not specified, the region object's data model <Name> (p. 185) is used.
<OutputVariables>
Container element for the set of output variables for which the region can send data.
Optional. If no output variables are defined, then no data transfers are created with the region
as a source.
<OutputVariables>
<Variable> (p. 186)
</OutputVariables>
<Variable>
Defines an output variable for which the region can send data. Must correspond to the Name
of a variable defined under the <Variables> (p. 182) element.
Optional. If no output variables are defined, then no data transfers are created with the region
as a source.
<InputVariables>
Container element for the set of input variables for which the region can receive data.
Optional. If no input variables are defined, then no data transfers are created with the region
as a target.
<InputVariables>
<Variable> (p. 186)
</InputVariables>
<Variable>
Defines an input variable for which the region can receive data. Must correspond to the Name
of a variable defined under the <Variables> (p. 183) element.
Optional. If no input variables are defined, then no data transfers are created with the region
as a target.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
186 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<CouplingParticipant>
<ExecutionControl>
<WorkingDirectory>MAPDL</WorkingDirectory>
<InitialInput>mapdl.dat</InitialInput>
</ExecutionControl>
<CosimulationControl>
<Type>MAPDL</Type>
<AnalysisType>Steady</AnalysisType>
<DisplayName>MAPDL Steady-State Thermal</DisplayName>
<Regions>
<Region>
<Name>FVIN_1</Name>
<DisplayName>FVIN_1_System Coupling Region</DisplayName>
<Topology>Volume</Topology>
<OutputVariables>
<Variable>TEMP</Variable>
</OutputVariables>
<InputVariables>
<Variable>HGEN</Variable>
</InputVariables>
</Region>
</Regions>
<Variables>
<Variable>
<Name>HGEN</Name>
<DisplayName>Heat Rate Density</DisplayName>
<QuantityType>Heat Rate Density</QuantityType>
<Location>Node</Location>
</Variable>
<Variable>
<Name>TEMP</Name>
<DisplayName>Temperature</DisplayName>
<QuantityType>Temperature</QuantityType>
<Location>Node</Location>
</Variable>
</Variables>
</CosimulationControl>
</CouplingParticipant>
If you're setting up a coupled analysis in Workbench but intend to run it in one of System Coupling's
user interfaces, you'll generate the SCI file manually and verify that it contains required information.
For more information, see Setting Up a Coupled Analysis in Workbench for a User-Interface Run (p. 152).
Note:
Values in this document are set by System Coupling and/or participants. These are typically
not edited manually — and if edited at all, care should be taken to not invalidate the data
model.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 187
System Coupling Input and Output Files
<Transfers>
<ExecutionControl>
<Analysis>
<Participants>
<Transfers>
The <Transfers> element contains details used to define the data transfers between any static
and co-simulation coupling participants.
In this element, you can set the Count (an integer representing the total number of data transfers)
as an attribute.
<Name> (string)
Name of the participant. This is the name with which the participant identifies itself to System Coupling.
This corresponds to the Component ID which is unique to a specific system's Solution cell in the
Workbench user interface.
Possible values:
• 0: Co-simulation
• 1: Static data
<FilePath> (string)
Full path to the primary file used to access source data from a static data participant.
<SupportsCouplingIterations> (boolean)
Controls whether the co-simulation participant supports the execution of multiple coupling iterations
per coupling step.
<UnitSystem>
Unit system used.
<Name> (string)
Name of the region (intrinsic to the participant).
<TopologicalDimensionality> (integer)
Geometry type of the region.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
188 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
Possible values:
• 2: Surface
• 3: Volume
<Name> (string)
Name of the variable (intrinsic to the participant).
<PhysicalType> (string)
Physical type of the variable. Possible values include:
• Length
• Force
<BaseUnits> (strings denoting base units for all data of noted physical type)
Possible values:
• Angle (string)
• ChemicalAmount (string)
• Current (string)
• Length (string)
• Luminance (string)
• Mass (string)
• SolidAngle (string)
• Temperature (string)
• Time (string)
<ExecutionControl>
The <ExecutionControl> element contains details used for the execution of the participant.
Contains the following sub-elements:
<CoSimulationSequence>
Not relevant to System Coupling.
The <CoSimulationSequence> element and the properties it contains are included in the
SCI file but are applicable only to System Coupling 1.0.
<DebugOutput>
The <DebugOutput> element contains properties that control the generation of debug output.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 189
System Coupling Input and Output Files
<Default> (integer)
Specifies whether debug output is generated, as well as the level of detail to be included.
When this property is set to any value other than the default value of 0, System Coupling
writes debug output to files in its working directory. The basic level of detail included is
controlled by the value selected, with a value of 0 generating no output and larger values
generating more detailed output.
Possible values:
• 0 (default value)
• 1
• 2
• 4
• 5
For information on the output generated, see Debug Output (p. 206).
Note:
Other <DebugOutput> properties may be included in the SCI file but aren't relevant
to System Coupling.
<IntermediateResultsFileOutput>
The <IntermediateResultsFileOutput> element contains properties that specify the frequency
at which intermediate result files, which can be used for restarts, are written by System Coupling.
<FrequencyOption> (integer)
Frequency with which intermediate restart files are generated.
Possible values:
<StepInterval> (integer)
Available when hen <FrequencyOption> is set to StepInterval. Coupling step interval at
which intermediate result files are generated. For example, using a step interval of 3, results are
generated at steps 3, 6, 9, ...
<MappingSettings>
May be reported in the SCI file but is not used by System Coupling.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
190 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<Analysis>
The <Analysis> element contains details used to define the coupled analysis. In this element,
you can set the following:
<AnalysisType> (integer)
Defines the nature of the sequential steps used in coupling co-simulation participants.
Possible values:
• 0: General
• 1: Transient
<Initialization>
Defines the initial time for the coupled analysis.
<Option> (integer)
Possible values:
• 0: Program Controlled
System Coupling makes the most appropriate choice of an initial time value. (default
value)
1: Start Time
System Coupling overrides the initial/start time for the analysis with the value specified
as part of <Time>.
<Time> (double)
Available when Initialization <Option> is set to 1. Initial time for the coupled analysis.
<Duration>
Defines the duration of the coupled analysis.
<Option> (integer)
Possible values:
• 0: NumberOfSteps
• 1: EndTime
<NumberOfSteps> (integer)
Available only if no end-time requirements exist for co-simulation participants.
<Time> (double)
Final time of coupling analysis.
<Step>
MaximumIterations (integer)
Maximum number of coupling iterations allowed per coupling step.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 191
System Coupling Input and Output Files
<MinimumIterations> (integer)
Minimum number of coupling iterations allowed per coupling step.
<Size> (double)
Size of the coupling step when it is associated with a time (this is done for transient analyses,
as size is measured in seconds).
<Option> (integer)
Possible values:
<Unit System>
Unit system used.
<Participants>
The read-only <Participants> element contains information obtained through connections to
upstream solver systems.
In this element, you can view the Count (an integer representing the number of connected parti-
cipants).
Note:
Depending upon the type of participant (co-simulation or static data), some of the options
may not be applicable.
Possible values:
• 0: Co-simulation
• 1: Static data
<Name> (string)
Name of the participant. This is the name with which the participant identifies itself to System
Coupling. This corresponds to the Component ID, which is unique to a specific system's Solution
cell in the Workbench user interface.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
192 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<ParticipantType> (string)
Indicates the application participating in the coupled analysis.
Important:
If you plan to use an SCI file for a GUI or CLI-based run, it's a best practice to
always verify that this information exists for each participant before importing
the file. For details, see Setting Up a Coupled Analysis in Workbench for a User-
Interface Run (p. 152).
Possible values:
• CFX
• FLUENT
• MAPDL
• DEFAULT: Used for static participants, such when a static data file is used instead of a solver.
Used when no participant type is specified. (default value)
<FilePath> (string)
Full path to the primary file used to access source data from a static data participant.
<SupportsCouplingIterations> (boolean)
Controls whether the co-simulation participant supports the execution of multiple coupling iter-
ations per coupling step.
<UnitSystem>
Unit system used.
<Name> (string)
Name of the region (intrinsic to the participant).
<TopologicalDimensionality> (integer)
Geometry type of the region.
Possible values:
• 0: Undefined
• 1: Point
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 193
System Coupling Input and Output Files
• 2: Curve
• 3: Surface
• 4: Volume
<Name> (string)
Name of the variable (intrinsic to the participant).
<PhysicalType> (string)
Physical type of the variable.
• Length
• Force
<BaseUnits> (strings denoting base units for all data of noted physical type)
• Angle (string)
• ChemicalAmount (string)
• Current (string)
• Length (string)
• Luminance (string)
• Mass (string)
• SolidAngle (string)
• Temperature (string)
• Time (string)
The Shutdown file is a text file named scStop and indicates whether the run should be interrupted
or aborted. When System Coupling finds this file in its working directory, it shuts down as soon as
possible according to the contents of the file.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
194 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
To abort or interrupt a run in one of System Coupling's user interfaces, create the file and place it in
System Coupling's working directory. In general, the file contains one or two lines:
• The first line contains a single integer, which indicates whether to interrupt (0) or abort (1) the run.
• The second line is optional and contains text that indicates the reason for terminating the run. This inform-
ation is recorded in System Coupling's Transcript.
Ensure that you remove the extension from the Shutdown file so that System Coupling can find it.
Tip:
You can abort a run by simply creating an empty scStop file. This is most useful
when you want to abort the run as abruptly as possible.
When the analysis is interrupted, System Coupling completes the current coupling step and signals
the coupling participants that the execution has ended. This causes System Coupling and participants
to shut down cleanly and create restart points for the end of the run. An example Shutdown file to
interrupt the run is shown below.
0
Interrupt this run because resources are needed for another analysis.
When the analysis is aborted, System Coupling signals the coupling participants to stop the run as
quickly as possible. No restart points are created for the end of the run. Note, however, that any
previously created restart points are retained.
When instances of System Coupling started in GUI Server mode are disconnected, the GUI Server
file (p. 196) is removed from the working directory.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 195
System Coupling Input and Output Files
System Coupling writes the server port and host information to the GUI Server file in the following
format, where "12345" is the server port and "0.0.0.0" is the host information. This information
is used to connect/reconnect an instance of the System Coupling GUI to the running solution.
guiserver=12345@0.0.0.0
An instance of System Coupling started in GUI Server mode can be connected to only one GUI at a
time. The GUI Server file remains in the working directory while System Coupling is running there,
preventing additional instances of the System Coupling GUI from connecting with the active coupling
session.
When System Coupling exits, whether naturally (e.g., due to solve or script completion or because of
an abort or interrupt operation) or unnaturally (e.g., as the result of a handled exception), the GUI
Server file is removed from the working directory.
Important:
The GUI Server file should not be removed manually unless System Coupling was terminated
unexpectedly and cleanup is required. For details on handling this scenario, see Known
Issues and Limitations (p. 31).
This file remains in the working directory and disables the Save, Solve, and Step operations while
the solution is in progress, preventing other instances of System Coupling from interfering its execution.
When the solution stops, whether naturally (e.g., a completed solution, the end of a script, or an in-
terrupt/ abort operation) or via a handled exception, the Solution Lock file is removed from the
working directory.
Important:
The Solution Lock file should not be removed manually unless System Coupling was ter-
minated unexpectedly and cleanup is required. For details on handling this scenario, see
Known Issues and Limitations (p. 31).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
196 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
During the execution of the run, coupled analysis information is written dynamically to the Transcript,
so you can use it both to monitor the analysis during the solution process and to review coupling
results after the solution is finished.
– For System Coupling in Workbench, Transcript output is written to the System Coupling tab's Solution
Information view.
– For System Coupling run in one of its user interfaces, Transcript output is written to the GUI's Command
Console or to the CLI.
During the execution of the run, coupled analysis information from the Transcript is written to the
scLog.scl file, which is created in System Coupling's working directory.
Note:
In the sections that follow, output examples are selected to illustrate variances in output,
so are not all generated from the same coupled analysis.
Executable Information
Provides information related to the start-up and execution of the coupled analysis, such as the
machines being used and details about intranode communications.
Note:
This information is written to the transcript only and does not appear in the log file.
host | 0
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 197
System Coupling Input and Output Files
======|======
0 : SHM
-------------------------------------------------------------------------------
ID Hostname Core O.S. PID Vendor
-------------------------------------------------------------------------------
e0 MYMACHINE 1/12 Windows-x64 14224 Intel(R) Xeon(R) E5-2687W
controller MYMACHINE Windows-x64 6052 Intel(R) Xeon(R) E5-2687W
Execution Information
Provides execution information for System Coupling and coupling participants, with participants
ordered alphabetically by display name.
+=============================================================================+
| Execution Information |
+=============================================================================+
| |
| System Coupling |
| Command Line Arguments: |
| -R script.afd |
| Working Directory: |
| C:\Users\Username\2020R1Cases\InductionHeating |
| |
| ANSYS Electronics Desktop |
| Execution Command: |
| "C:\Program Files\AnsysEM\AnsysEM20.1\Win64\ansysedt.exe" -scport 52525 |
| -schost "MYMACHINE.win.domain.com" -scname "AEDT-2" -ng -runscript |
| "input.py" |
| Working Directory: |
| C:\Users\Username\2020R1Cases\InductionHeating\ |
| |
| MAPDL Steady-State Thermal |
| Execution Command: |
| "C:\Program Files\ANSYS Inc\v201\ansys\bin\winx64\ANSYS201.exe" -b noli |
| st -s noread -o MAPDL-1.out -scport 52525 -schost MYMACHINE.win.domain |
| .com -scname "MAPDL-1" -scid="5555_MYMACHINE.win.domain.com" -sclic=1111|
| @licensename -i "mapdl.dat" |
| Working Directory: |
| C:\Users\Username\2020R1Cases\InductionHeating\MAPDL |
| |
+=============================================================================+
Awaiting connections from coupling participants... done.
+=============================================================================+
| Participants Build Information |
+-----------------------------------------------------------------------------+
| ANSYS Electronics Desktop |
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
198 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
| 2020.1.0 |
| MAPDL Steady-State Thermal |
| Mechanical APDL Release 2020 R1 Build 20.1 20191008 |
| DISTRIBUTED WINDOWS x64 Version |
+=============================================================================+
Information related to coupling participants and coupling interfaces (including the data transfers
on each interface) is ordered alphabetically by the participant and interface display names.
===============================================================================
+=============================================================================+
| |
| Summary of Coupling Setup |
| |
+=============================================================================+
===============================================================================
When you run the Solve command, this section is written to the command console at the beginning
of the coupling run. To write it to the console at other times during the run, you can run the
PrintSetup command.
Coupling Control
Provides information on settings that define and control the behavior of the coupled analysis.
For details about corresponding settings in the data model, see Coupling Control in the System
Coupling Settings and Commands Reference manual.
+============================================================================+
| Coupling Control |
+============================================================================+
| |
| Analysis Type : Steady |
| Duration Control |
| Option : NumberOfSteps |
| Number Of Steps : 1 |
| Step Control |
| Maximum Iterations : 5 |
| Minimum Iterations : 5 |
| |
+============================================================================+
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 199
System Coupling Input and Output Files
Solution Control
Provides information on settings that define and control the behavior of the solution. For details
about corresponding settings in the data model, see Solution Control in the System Coupling
Settings and Commands Reference manual.
+=============================================================================+
| Solution Control |
+=============================================================================+
| |
| Allow Simultaneous Update : True |
| |
+=============================================================================+
Output Control
Provides information on settings that define and control the behavior of the coupled analysis.
For details about corresponding settings in the data model, see Output Control in the System
Coupling Settings and Commands Reference manual.
+============================================================================+
| Output Control |
+============================================================================+
| |
| Output Control Option : LastStep |
| |
+============================================================================+
Participants Information
Provides information about each participant solver.
For details about corresponding settings in the data model, see Coupling Participant in the System
Coupling Settings and Commands Reference manual.
+=============================================================================+
| Participants Information (2) |
+=============================================================================+
| |
| Participant: ANSYS Electronics Desktop |
| Type : AEDT |
| Update Controls: |
| Option : ProgramControlled |
| Region: Coil_2nd |
| Topology : Volume |
| Input Variables : Temperature |
| Output Variables : Loss |
| Region: Coil_1st |
| Topology : Volume |
| Input Variables : Temperature |
| Output Variables : Loss |
| Region: Region |
| Topology : Volume |
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
200 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Interfaces Information
Provides information about each coupling interface.
For details about corresponding settings in the data model, see Coupling Interface in the System
Coupling Settings and Commands Reference manual.
+=============================================================================+
| Interfaces Information (1) |
+=============================================================================+
| |
| Interface: Interface-1 |
| Side: One |
| Coupling Participant : MAPDL Steady-State Thermal |
| Region List : FVIN_1_System Coupling Region |
| Side: Two |
| Coupling Participant : ANSYS Electronics Desktop |
| Region List : Stock |
| Data Transfer: Heat Rate Density |
| Target Side : One |
| Source Variable : Loss |
| Target Variable : Heat Rate Density |
| Convergence Target : 1.00E-03 |
| Ramping Option : None |
| Relaxation Factor : 1.00E+00 |
| Mapping Type : Volume Conservative |
| Stabilization : None |
| Data Transfer: Temperature |
| Target Side : Two |
| Source Variable : Temperature |
| Target Variable : Temperature |
| Convergence Target : 1.00E-03 |
| Ramping Option : None |
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 201
System Coupling Input and Output Files
Coupled Solution
Provides information about the coupled solution in the following sections:
Pre-Solution Warnings and Messages
Coupling Step
+-----------------------------------------------------------------------------+
| Warnings were found during data model validation. |
+-----------------------------------------------------------------------------+
| Restart output is only requested at last step. To enable restarts from |
| intermediate points, use another 'OutputControl' option. |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
| Hidden features are available. |
+-----------------------------------------------------------------------------+
| Beta: 'ConnectionTimeout' in CouplingControl |
| Beta: 'Results' in OutputControl |
+-----------------------------------------------------------------------------+
Coupling Step
Provides information for each coupling step, including the simulation time and details for each
coupling step completed. Within the coupling step, the following information is provided, with
participants ordered according to update sequence:
Mapping Summary
Coupling Iteration
Note that the coupling step's SIMULATION TIME is provided for transient analyses.
+============================================================================+
| COUPLING STEP = 1 |
+----------------------------------------------------------------------------+
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
202 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Mapping Summary
The MAPPING SUMMARY is generated only for the first iteration of the first step for both the
initial run and restarted runs of a coupled analysis. Interfaces and data transfers are ordered
alphabetically by display name.
+-----------------------------------------------------------------------------+
| COUPLING ITERATION = 1 |
+-----------------------------------------------------------------------------+
| MAPPING SUMMARY |
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
| Interface-1 | |
| Heat Rate Density | |
| Mapped Volume [%] | 100 100 |
| Mapped Elements [%] | 100 100 |
| Mapped Nodes [%] | 100 100 |
| Temperature | |
| Mapped Volume [%] | 25 100 |
| Mapped Elements [%] | 14 100 |
| Mapped Nodes [%] | 6 98 |
| Interface-2 | |
| Heat Rate Density | |
| Mapped Volume [%] | 100 100 |
| Mapped Elements [%] | 100 100 |
| Mapped Nodes [%] | 100 100 |
| Temperature | |
| Mapped Volume [%] | 23 100 |
| Mapped Elements [%] | 12 100 |
| Mapped Nodes [%] | 6 99 |
+-----------------------------------------------------------------------------+
Coupling Iteration
Provides details for each coupling iteration in the step, with participants listed in order of the
update sequence. For each iteration, the following information is provided:
• Participant data transfers: A section for each participant indicates the data transfer it receives
and whether the data transfer converged during the iteration.
– Participant data transfers, whether for individual participants or participants grouped for simul-
taneous solution, are ordered by chronologically by participant update sequence, as shown in
Figure 29: Coupling Iteration output (p. 204).
– Data transfers for grouped participants that are solving simultaneously are not separated by a
line in the output, as shown in Figure 30: Coupling Iteration output with simultaneous-solve
participants (p. 204).
• Participant solutions: Indicates whether each participant's solution converged (it solved its
equations) during the iteration.
Possible values:
– Converged: Used for iterative solutions. Indicates that the solution has converged during the
iteration. Not applicable to AEDT.
– Complete: Used for direct solutions and all AEDT solutions (i.e., both iterative and direct). Indic-
ates that the solution has been completed for the iteration.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 203
System Coupling Input and Output Files
– Convergence Not Evaluated: Indicates that the participant's output was not monitored
during the iteration.
– Not Updated: Indicates that the solution was not updated during the iteration, as specified
by the participant's Update Control settings, as described in the System Coupling Settings and
Commands Reference manual.
+-----------------------------------------------------------------------------+
| COUPLING ITERATION = 2 |
+-----------------------------------------------------------------------------+
| MAPDL 1 | |
| Interface: Interface-1 | |
| Heat Rate | Not yet converged |
| RMS Change | 1.25E+00 1.10E+00 |
| Values Sum | -2.03E-01 -1.40E+01 |
+-----------------------------------------------------------------------------+
| MAPDL 2 | |
| Interface: Interface-2 | |
| Heat Rate | Not yet converged |
| RMS Change | 1.30E+00 1.28E+00 |
| Values Sum | -3.22E-01 -1.98E+01 |
+-----------------------------------------------------------------------------+
| Fluent | |
| Interface: Interface-1 | |
| Temperature | Not yet converged |
| RMS Change | 3.80E-04 3.80E-04 |
| Values Average | 1.02E+02 1.02E+02 |
| Interface: Interface-2 | |
| Temperature | Converged |
| RMS Change | 8.64E-05 8.64E-05 |
| Values Average | 1.11E+02 1.11E+02 |
+-----------------------------------------------------------------------------+
| Participant solution status | |
| MAPDL 1 | Converged |
| MAPDL 2 | Converged |
| FLUENT | Converged |
+=============================================================================+
+-----------------------------------------------------------------------------+
| COUPLING ITERATION = 2 |
+-----------------------------------------------------------------------------+
| MAPDL 1 | |
| Interface: Interface-1 | |
| Heat Rate | Not yet converged |
| RMS Change | 1.25E+00 1.10E+00 |
| Values Sum | -2.03E-01 -1.40E+01 |
| MAPDL 2 | |
| Interface: Interface-2 | |
| Heat Rate | Not yet converged |
| RMS Change | 1.30E+00 1.28E+00 |
| Values Sum | -3.22E-01 -1.98E+01 |
+-----------------------------------------------------------------------------+
| Fluent | |
| Interface: Interface-1 | |
| Temperature | Not yet converged |
| RMS Change | 3.80E-04 3.80E-04 |
| Values Average | 1.02E+02 1.02E+02 |
| Interface: Interface-2 | |
| Temperature | Converged |
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
204 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Shut Down
Provides information about the shutdown of System Coupling, including timing details for the
analysis.
Individual participants are ordered alphabetically by display names and are listed before groups of
simultaneous-solve participants.
– For each individual (ungrouped) coupling participant, records its total processing time
– For each participant group, lists its members and records the total processing time for the group (i.e.,
the sum of processing times for all member participants)
• Total Time:
Records the total time of the analysis, from the time when all participants connect to when they
disconnect
===============================================================================
+=============================================================================+
| |
| Shut Down |
| |
+=============================================================================+
===============================================================================
+=============================================================================+
| Timing Summary [s] |
+=============================================================================+
| Coupling Engine Time : 1.2764E+02 |
| Coupling Participant Time |
| ANSYS Electronics Desktop : 7.6999E+02 |
| MAPDL Steady-State Thermal : 2.7004E+02 |
| Total Time : 1.1677E+03 |
+=============================================================================+
+=============================================================================+
| System coupling run completed successfully. |
+=============================================================================+
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 205
System Coupling Input and Output Files
+=============================================================================+
| Available Restart Points |
+=============================================================================+
| Restart Point | File Name |
+-----------------------------------------------------------------------------+
| Coupling Step 1 | Results_step1.h5 |
| Coupling Step 2 | Results_step2.h5 |
| Coupling Step 3 | Results_step3.h5 |
| Coupling Step 4 | Results_step4.h5 |
+=============================================================================+
+=============================================================================+
| Available Restart Points |
+=============================================================================+
| Restart Point | File Name |
+-----------------------------------------------------------------------------+
| Coupling Iteration 1 | Results_iter1.h5 |
| Coupling Iteration 5 | Results_iter5.h5 |
| Coupling Iteration 10 | Results_iter10.h5 |
| Coupling Iteration 11 | Results_iter11.h5 |
+=============================================================================+
Debug Output
You can request that System Coupling generates debugging output for coupled analyses. For analyses
set up in Workbench, you'll set the Global Output (p. 139) property; for analyses set up in one of System
Coupling's user interfaces, you'll set the GLOG_log_dir, GLOG_v, and possibly the sysc_GLOG_MXAR-
RAYELMS environment variables. For details, see Requesting Debug Output (p. 79).
When debug output has been requested, System Coupling writes debug files, either to System
Coupling's working directory or to a directory specified by the GLOG_log_dir environment variable.
For each System Coupling run, the following files are generated:
• one controller file for each control process, named with a sysc_Controller prefix, and
• one compute node file for each computing node, named with a sysc_CNode# prefix, where "#" is the
number of the node.
The compute node files are likely to be the most useful for debugging your coupled analysis. These
files record the transactions between System Coupling and the coupling participants.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
206 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Important:
The Settings file reflects the state of the coupled analysis data model at the time it was
saved. To ensure consistency between the contents of the Settings file and the setup used
by the coupled analysis, it is recommended that you do not attempt to change participant
settings by editing the SCP files manually.
If data model changes are introduced and the Save command is reissued, then the new Settings file
replaces the previous one. Also, if an SCP file is re-loaded to an existing analysis, then the setup details
in the corresponding Settings file are overwritten.
• When you save a coupled analysis using the Save command, a Results file is written to the same
directory as the analysis Settings (p. 207) file.
• By default, when a restart point is created (p. 89) by any method, a Results file containing the inform-
ation necessary to restart the coupled analysis at the end of the last completed step or iteration is
written to the SyC subdirectory in System Coupling's working directory.
When a coupled analysis stops, either because it completed or was shut down, a listing of the Results
files created is written to the Available Restart Points (p. 206) table at the end of the Transcript\Log
file.
Results files may correspond either to coupling iterations or coupling steps, depending on the analysis
type and the types of participants involved, as follows:
Step-based results:
• Produced for transient analyses and steady-state analyses with at least one AEDT, CFX, FLUENT,
or MAPDL participant.
• Named according to the convention Results_step<#>.h5, where "#" is the index of the
coupling step.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 207
System Coupling Input and Output Files
Iteration-based results:
• Produced for steady-state analyses that do not have an AEDT, CFX, FLUENT, or MAPDL participant.
• Named according to the convention Results_iter<#>.h5, where "#" is the index of the
coupling iteration.
Note:
Results files named according to the previous convention (i.e., Results_<#>.h5, without
indication of step or iteration) are still supported. System Coupling can read these files but
names all new files according to the new conventions.
When you restart an analysis, by default the Results file associated with the last solved coupling step
or iteration is used. If you want to begin from an earlier restart point, then you can use the Coup-
lingStep or CouplingIteration argument to specify the point to be used. Note, however, that
when restarting from an earlier point, all the later restart points stored in the same directory are re-
moved (i.e., the Results files are deleted). To keep restart data from one of these later coupling steps
or iterations, rename or create a backup for the corresponding Results files.
For more detailed information on restart points and how to use them in one of System Coupling's
user interfaces, see Restarting a Coupled Analysis (p. 88).
Server-of-Servers file:
A Results.sos Server-of-Servers file is written at the beginning of the analysis, prior to the execution
and completion of the first coupling step. Because it contains all the data for the analysis — i.e., it refer-
ences all the relevant output files, including the case files for all processors used to execute the solution
— it is recommended that you use this file to load coupling results into EnSight.
To use this file, you must start EnSight in SOS mode, as described in Starting ANSYS EnSight (p. 84).
For more information, see Use Server of Servers in the ANSYS EnSight How-To Manual.
Case files:
Case files are written at the beginning of the analysis, prior to the execution and completion of the first
coupling step. A separate file is generated for each individual processor used to execute the solution.
• When multiple processors are used, the files are named according to the convention Res-
ults_<#>.case, where "<#>" is the index of the associated processor.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
208 of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Because System Coupling runs on two processors by default, it generates a results file for each:
Results_0.case and Results_1.case.
Note:
Each file contains only the data generated by the corresponding processor. The only
instance where a Case file contains all data for the analysis (and so could be used to
load results into EnSight) is when a single processor was used to execute the solution.
Named according to the convention Results_V_<######>.dat, where "V " is the variable
transferred and "######" is the six-digit coupling step index.
Note:
Filenames file:
EnSight's Filenames file is named Results.filenames. Individual file that tells EnSight how to
complete the filenames.
This file has n lines, where n is the number of steps in the analysis. Each line in the file lists
a step number.
Time file:
EnSight's Time file is named Results.time.
Individual file that provides the time (in seconds) for transient runs.
This file is the same length as the *.filenames file, with n lines, where n is the number of
steps in the analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 209
System Coupling Input and Output Files
Note:
If the coupling server host reports an unexpected name, review the notes in ??? for
information on how to resolve this.
• Element containing the number of coupling participants connected to System Coupling, including
the automatically generated unique and display names for each. In the System Coupling environment:
• Unique names are used by System Coupling to identify and connect the participants.
• Display names are shown in user-facing communications such as files and console output.
• License server's port and host, separated by an "@" character, at which the coupling participant codes
(i.e., solvers) can reach the license server.
Note:
When the participants are started and instructed to connect to System Coupling, they must
connect using unique names (for example, CFX-1 and Ansys in the example above)
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
210 of ANSYS, Inc. and its subsidiaries and affiliates.
Best Practices for System Coupling
When working with System Coupling, there are certain suggested practices that will help to ensure an
efficient solution and to optimize the accuracy of your results. For best practices and setup recommend-
ations, see:
General Best Practices for Coupled Analyses
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Improving Coupled Analysis Stability
For recommendations on running coupled analyses for FSI applications, see Best Practices for Coupled
Fluid-Structure Interaction (FSI) (p. 216).
As much as possible, try to set up the decoupled analyses so that they replicate the participants'
expected roles in the prospective coupled analyses. (For example, to prepare for an FSI analysis,
you'd apply a pressure load in the structural analysis or set up mesh motion and deformation in
the fluid analysis.)
Once you've verified that each of the problems can be solved individually on its own, you can
proceed to working with one-way coupled analyses.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 211
Best Practices for System Coupling
other participant's decoupled run as inputs, approximating the values it may receive in a two-way coupled
analysis. This allows you to assess the sensitivity of each participant's analysis to the expected inputs.
The one-way coupled analyses should replicate the effects of the intended two-way coupled
analysis as closely as possible. If one or both problems show sensitivity to the inputs it receives,
then further exploration via a two-way coupled analysis may be useful.
Once the one-way analyses have been solved, how you proceed depends on your end goal for
the problem:
• If a one-way coupled analysis is your end goal, then the next step is to evaluate its convergence. For
information on assessing coupled analysis convergence, see Evaluating Convergence and Data
Transfer Accuracy (p. 214). For participant-specific methods of evaluating convergence, see the relevant
participant product documentation.
• If a two-way coupled analysis is your end goal, then proceed to the creation of the two-way analysis.
For an illustration of how these steps might be used for a specific application, see Building a Coupled
FSI Analysis from Decoupled Participant Problems (p. 217).
• Target-side diagnostics:
If less than 100% of the target-side locations were mapped, then System Coupling is implement-
ing a method of generating data on unmapped target locations according to the type of
mapping used for the transfer.
This is often caused by differences in the geometry. For example, mapping might be prevented
because the target geometry does not overlap/intersect the source geometry, or there might
be a gap (too much distance) between the source and target geometries.
• Source-side diagnostics:
If less than 100% of the target-side locations were mapped, then some source data is not being
used.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
212 of ANSYS, Inc. and its subsidiaries and affiliates.
General Best Practices for Coupled Analyses
In conservative mapping, this means that the quantity transferred is either not fully conserved
and/or is conserved only in areas where the mesh overlaps. However, target-side mapping of
less than 100% typically occurs only in cases of profile-preserving mapping where the source
mesh is significantly finer than the target mesh.
• Ensure that there is overlap/intersection between the source and target geometry regions where data
will be transferred.
• Ensure that all source and target regions on the coupling interface have the same reference state.
Note:
• Refine meshes to the degree feasible. Coarse meshes can cause and/or exacerbate mesh gaps or dis-
similarities, which in turn can have an adverse effect on mapping. This is especially important for
geometries with meshes on curved surfaces.
• Ensure that the meshes of the source and target regions of the coupling interface are suitable for the
problem being solved. In general, source and target mesh resolutions should be as similar as is possible.
Variances should be guided primarily by the participant physics and the type of data being transferred.
For example:
– For data transfers of non-conservative quantities (i.e., which use a profile-preserving algorithm),
a target-mesh resolution that is similar to or finer than the source-mesh resolution is recommended.
– For data transfers of conservative quantities (i.e., which use a conservative mapping algorithm),
a target mesh that is similar to the source mesh is recommended, though a target mesh that is
slightly coarser than the source mesh is acceptable.
Keep in mind, however, that a finer target mesh may be beneficial from a physics-modeling
point of view. Mesh resolution should be adjusted as needed to obtain an accurate solution
for the participant physics.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 213
Best Practices for System Coupling
There is a data-transfer diagnostics section for each participant. It indicates the data transfer
the participant receives and whether the data transfer converged during the iteration.
• Participant diagnostics:
The participant-solution status section indicates whether each participant completed its step
during the iteration.
The reported values should be the same for both the source and the target of the data transfer.
When they are not:
• If the target sum is less than the source sum, then this indicates (and should confirm) that System
Coupling is implementing a method of generating data on unmapped target locations according to
the type of mapping used for the transfer.
• If the target average significantly differs from the source average, then the mapped results are
suspect and should be reviewed in greater detail. This can often be attributed to the target-side meshes
that are coarse relative to the source-side meshes, especially in regions with significant source-solution
variations.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
214 of ANSYS, Inc. and its subsidiaries and affiliates.
General Best Practices for Coupled Analyses
Note:
Because restart data is only generated at the end of a completed coupling step,
a single-step analysis can only be restarted at the end of the solution. As such, it
is not possible to restart from an intermediate result or an abnormally terminated
run.
– Allows ramping and under-relaxation across coupling iterations within the single coupling step.
Note:
Restart data is still generated only at the end of coupling steps, but you can specify
which steps for which restart data will be generated. As such, it is possible to restart
from an intermediate result or from an abnormally terminated run, which can be
useful for complex analyses that are at risk of abnormal terminations.
– Allows ramping and under-relaxation across coupling iterations within a coupling step, but not
across coupling steps. When a step is completed, the full data transfer value is transferred to the
next step.
• Slow convergence:
If convergence is not realized within tens of coupling iterations (i.e., up to 100), then consider
introducing stabilization methods such as ramping (p. 173) and under-relaxation (p. 175).
Participant-specific solution stabilization methods, such as those offered by Fluent, may also
be employed. For details, refer to the corresponding participant product documentation.
• Strong non-linearities:
If there are strong non-linearities within the coupled solution, then more coupling iterations
may be required, even with the use of stabilization. Increase the maximum number of coupling
iterations per step and/or introduce additional coupling steps.
• Premature convergence:
In some cases, convergence is realized prematurely (e.g., within one iteration) because the non-
linearities in the coupled solution have not yet been activated. If this is suspected, then set a
minimum number of coupling iterations per step to trigger the non-linearities and force adequate
resolution.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 215
Best Practices for System Coupling
• If a participant's timescales are slightly smaller (e.g., between 1x and 100x) than coupling-related
timescales, then reduce the coupling step size to resolve to the smallest timescale in the participant
physics. This often occurs for fluid-structure interaction applications.
• If a participant's timescales are significantly smaller (e.g., greater than 100x) than coupling-related
timescales, then run that participant using a steady analysis. This often occurs for electromagnet-
ic/thermal applications.
• Slow convergence:
If convergence is not realized for each coupling step within approximately 5 – 10 coupling iter-
ations, then consider reducing the coupling time step size or introducing stabilization methods
such as ramping (p. 173) and under-relaxation (p. 175).
Participant-specific solution stabilization methods, such as those offered by Fluent, may also
be employed. For details, refer to the corresponding participant product documentation.
• Strong non-linearities:
If there are strong non-linearities within the coupled solution, then convergence within approx-
imately 5 – 10 coupling iterations may not be possible. If this is suspected (and the previous
recommendations aren't sufficient to allow convergence), then increase maximum number of
coupling iterations per step.
Note:
Although maximum number of iterations may be used to limit the amount of work
done per step, this is generally not recommended.
• Premature convergence:
In some cases, convergence is realized prematurely (e.g., within one iteration) because the non-
linearities in the coupled solution have not yet been activated. If this is suspected, then set a
minimum number of coupling iterations per step to trigger the non-linearities and force adequate
resolution.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
216 of ANSYS, Inc. and its subsidiaries and affiliates.
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Note:
For participant-specific details on FSI problems, see the corresponding product documentation:
• Modeling Fluid-Structure Interaction (FSI) Within Fluent in the Fluent User's Guide
The procedure for building a coupled analysis is summarized below in Figure 33: Workflow to set up
a coupled FSI analysis (p. 218).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 217
Best Practices for System Coupling
Note:
In the following sections, the structural solver is assumed to be ANSYS Mechanical. The
fluid solver may be any ANSYS CFD solver that supports System Coupling FSI simulations.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
218 of ANSYS, Inc. and its subsidiaries and affiliates.
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Fluid analysis:
Solve only for the fluid-flow part of the problem (i.e., do not solve for mesh motion).
1. Remove any System Coupling motion specifications that would be used to verify mesh motion
and remeshing in the fluid analysis.
3. Define a motion (structural displacement) as an input. This should approximate the motion (or
range of motion) expected from the structural problem.
Structural analysis:
Solve only for the explicit motion and preliminary contact (with no offset) part of the problem (i.e., do
not solve for fluid force).
1. Remove any System Coupling motion specifications (if they exist) that would be used to verify
mesh motion and remeshing in the fluid analysis.
3. If applicable, add contact and contact offsets to ensure that the fluid mesh does not collapse.
4. Define a load (fluid force) as an input. This should approximate the load (magnitude and distribu-
tion) expected from the fluid analysis.
Once you've verified that each of the individual problems can be solved successfully on its own,
you can incorporate them into a series of one-way coupled analyses (p. 219).
Step 2: Solve the Fluid and Structural Problems as One-Way Coupled Analyses
In this step, incrementally add complexity and non-linearity by setting up and solving each problem
as a one-way coupled analysis.
Solve the Fluid Problem as a Series of One-Way Coupled Analyses
Solve the Structural Problem as a One-Way Coupled Analysis
1. Remove the approximated motion input that was applied in the individual fluid analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 219
Best Practices for System Coupling
3. For the fluid side of the analysis, configure mesh motion and deformation (p. 222) settings. If ap-
plicable, set contact detection parameters.
4. For the structural side of the analysis, configure contact offsets to address limitations in the fluid
analysis.
• If using one of System Coupling user interfaces, generate a System Coupling Participant (SCP)
file for each participant.
• If using System Coupling in Workbench, generate a System Coupling Input (SCI) file for the
analysis.
6. Complete the coupled analysis setup (duration, coupling steps, coupling iterations, etc.) according
to the System Coupling context being used.
When this analysis has been successfully solved, move on to solving the analysis with flow
equations.
3. Regenerate the System Coupling files to capture the changes to the participant physics, as de-
scribed previously for Analysis 1.
Once the one-way fluid analysis has been solved with flow equations, how you proceed depends
on your end goal for the problem:
• If a one-way coupled analysis is your end goal, then the next step is to evaluate its convergence.
For information on assessing coupled analysis convergence, see Evaluating Convergence and Data
Transfer Accuracy (p. 214). To evaluate participant convergence, use the method provided by the
CFD solver.
• If a two-way coupled analysis is your end goal (or if you observe significant deformation of the fluid
domain because of the structural motion), then proceed to the creation of the two-way analysis.
Note:
Before doing so, ensure that you have also completed the intermediate step of
solving the structural problem as a one-way coupled analysis (p. 221).
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
220 of ANSYS, Inc. and its subsidiaries and affiliates.
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Additionally, in setting up and running the one-way analysis, you may be able to identify and address
potential issues regarding timescales, mesh folding, maximum stress values, and special solution
considerations (e.g., mixed u-P formulation for nearly incompressible hyperelastic solids).
1. Remove the approximated load that was applied in the individual structural analysis.
• If using one of System Coupling user interfaces, generate a System Coupling Participant (SCP)
file for each participant.
• If using System Coupling in Workbench, generate a System Coupling Input (SCI) file for the
analysis.
5. Complete the coupled analysis setup (duration, coupling steps, coupling iterations, etc.) according
to the System Coupling context being used.
Once the one-way structural analysis has been solved, how you proceed depends on your end goal
for the problem:
• If a one-way coupled analysis is your end goal, then the next step is to evaluate its convergence. For
information on assessing coupled analysis convergence, see Evaluating Convergence and Data Transfer
Accuracy (p. 214). To evaluate participant convergence, use the method provided by the structural
solver.
• If a two-way coupled analysis is your end goal (or if you observe a significant structural deformation
because of the applied load), then proceed to the creation of the two-way analysis.
Note:
Before doing so, ensure that you have also completed the intermediate step of solving
the fluid problem as a one-way coupled analysis (p. 219).
Step 3: Solve the Fluid and Structural Problems as a Two-Way Coupled Analysis
Solve the fluid and structural problems as a two-way coupled analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 221
Best Practices for System Coupling
1. For the fluid analysis, remove the initial structural displacement input that was applied to approximate
the expected motion. This allows the actual displacement data generated by the structural analysis
to be calculated and applied to the fluid analysis.
2. For the structural analysis, remove the initial fluid-force load (explicit displacement) that was applied
to approximate the expected load. This allows the force data generated by the fluid to be calculated
(once the transport equations are solved) and applied to the structural analysis.
To determine the mesh deformation time scale, calculate the time step Δt size based on:
The maximum expected velocity of the mesh can be determined through Mechanical by examining
the total deformation occurring due to the explicit motion. The maximum total deformation can be
divided by the time step size to estimate the expected mesh velocity of the CFD mesh.
As a starting point, attempt to define the boundary so that it can move only a single cell in each time
step. Then, once a successful run has been established, the time step size can be increased.
• Steps and Step Controls for Static and Transient Analyses in the Mechanical User's Guide
CFX:
Fluent:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
222 of ANSYS, Inc. and its subsidiaries and affiliates.
Improving Coupled Analysis Stability
Note:
• For the first coupling step, data is ramped from the initial value defined for the data transfer,
as described in Initial Values Used for the Reference Target-Side Value (p. 176).
• For displacement transfers, data is ramped from 0.0[m] for every coupling step.
• the Ramping option in the Data Transfer Control (p. 135) settings (for System Coupling in Workbench) or
• the Ramping Option data model setting (for System Coupling in its GUI or CLI), as described in the System
Coupling Settings and Commands Reference manual.
For more information about the algorithm used for ramping, see Ramping Algorithm (p. 173).
For an example of participant solution stabilization, refer to the dynamic mesh System Coupling
solution options used in Fluent, described in System Coupling Motion in the Fluent User's Guide.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 223
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
224 of ANSYS, Inc. and its subsidiaries and affiliates.