System Coupling User's Guide
ANSYS, Inc.
Southpointe
2600 ANSYS Drive
Canonsburg, PA 15317
ansysinfo@ansys.com
http://www.ansys.com
(T) 724-746-3304
(F) 724-514-9494
Release 2020 R1
January 2020
ANSYS, Inc. and
ANSYS Europe,
Ltd. are UL
registered ISO
9001: 2015
companies.
Copyright and Trademark Information
© 2020 ANSYS, Inc. Unauthorized use, distribution or duplication is prohibited.
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 CONFIDENTIAL 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.
U.S. Government Rights
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.
Published in the U.S.A.
Table of Contents
Introduction to the System Coupling User's Guide ...................................................................................... 1
System Coupling Overview ........................................................................................................................ 3
The ANSYS Product Improvement Program ............................................................................................. 3
System Coupling Capabilities .................................................................................................................. 4
System Coupling Contexts: GUI, CLI, and Workbench .............................................................................. 12
Product Licensing Considerations ......................................................................................................... 13
Steps of a System Coupling Analysis ...................................................................................................... 15
System Coupling Analysis Types ............................................................................................................ 15
General/Steady Analysis Type .......................................................................................................... 16
Transient Analysis Type ................................................................................................................... 17
System Coupling Settings ..................................................................................................................... 18
Stops and Restarts of System Coupling Analyses ................................................................................... 18
Stopping a Coupled Analysis ........................................................................................................... 19
Restarting a Coupled Analysis ......................................................................................................... 19
Migrating to ANSYS System Coupling 2020 R1 ....................................................................................... 20
Migrating Across Multiple Releases ................................................................................................. 21
Migrating to Use Fluent Face/Cell Transfer Data ............................................................................... 21
Cases Set Up and Solved with System Coupling GUI or CLI Using SCP Files ................................. 22
Cases Set Up and Solved with Workbench ................................................................................. 24
Cases Set Up in Workbench and Solved with System Coupling's GUI or CLI ................................. 25
Migrating Command-Line System Coupling Scripts ........................................................................ 26
CPython Upgrade .................................................................................................................... 27
Changes to Commands ............................................................................................................. 27
Changes to Command-Line Options .......................................................................................... 28
Changes to the Data Model ....................................................................................................... 29
Known Issues and Limitations ............................................................................................................... 31
Using System Coupling's User Interfaces ................................................................................................. 33
Overview of System Coupling's User Interfaces ...................................................................................... 34
Supported Coupling Participants .................................................................................................... 34
Coupling Interfaces and Data Transfers ............................................................................................ 35
Rules for the Creation of Coupling Interfaces ............................................................................. 36
Rules for the Creation of Data Transfers ..................................................................................... 36
Steps of a Coupled Analysis ............................................................................................................. 37
Participant Solution Sequencing ..................................................................................................... 38
Working with System Coupling's Data Model ........................................................................................ 39
Data Model Structure ...................................................................................................................... 39
Root-Level Containers ..................................................................................................................... 41
Viewing Data Model Contents ......................................................................................................... 41
Viewing a Container's Contents ................................................................................................. 42
Viewing an Object's Children .................................................................................................... 43
Viewing the Contents of an Object's Children ............................................................................ 43
Using System Coupling's Graphical User Interface (GUI) ......................................................................... 44
Starting the System Coupling GUI ................................................................................................... 44
Starting the GUI from the Start Menu ........................................................................................ 44
Starting the GUI from the Command Prompt ............................................................................. 45
System Coupling GUI Components ................................................................................................. 46
System Coupling GUI Menus ........................................................................................................... 49
Menu-Bar Menus ...................................................................................................................... 49
Context Menus ......................................................................................................................... 51
Using the System Coupling Command-Line Interface (CLI) ..................................................................... 53
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
Starting the System Coupling CLI .................................................................................................... 53
Getting Help in the System Coupling CLI ......................................................................................... 54
Preparing for a Coupled Analysis ........................................................................................................... 55
Creating a Coupled Analysis Directory Structure .............................................................................. 56
Completing Participant Setups ........................................................................................................ 57
Additional Participant Setup Considerations .................................................................................... 58
Generating Participant Files ............................................................................................................ 58
Creating a Coupled Analysis .................................................................................................................. 59
Adding the Participants .................................................................................................................. 59
Adding a Coupling Interface ........................................................................................................... 61
Adding a Data Transfer .................................................................................................................... 63
Setting Geometry Transformations for Models with Different Orientations ....................................... 65
Modifying Coupled Analysis Settings .................................................................................................... 66
Changing Data Model Settings ........................................................................................................ 66
Frequently Edited Data Model Settings ..................................................................................... 66
Coupling Control ................................................................................................................ 67
Solution Control ................................................................................................................. 69
Output Control ................................................................................................................... 70
Coupling Interface .............................................................................................................. 71
Coupling Participant ........................................................................................................... 73
Changing Data Model Setting Values ........................................................................................ 78
Enabling Expert Settings ................................................................................................................. 79
Requesting Debug Output .............................................................................................................. 79
Running a Coupled Analysis .................................................................................................................. 80
Starting the Solution ...................................................................................................................... 80
Monitoring Solution Progress .......................................................................................................... 81
Reviewing Coupled Analysis Output and Results ................................................................................... 82
Postprocessing Coupling Results in ANSYS EnSight ......................................................................... 82
Generation of EnSight-Formatted Output Files .......................................................................... 82
Starting ANSYS EnSight ............................................................................................................ 84
Reviewing Results Loaded in EnSight ........................................................................................ 84
Advanced System Coupling Workflows .................................................................................................. 86
Saving a Coupled Analysis ............................................................................................................... 86
Stopping a Coupled Analysis ........................................................................................................... 87
Restarting a Coupled Analysis ......................................................................................................... 88
Creation of Restart Points .......................................................................................................... 89
Restarting a Coupled Analysis in the GUI ................................................................................... 90
Restarting a Coupled Analysis in the CLI ................................................................................... 91
Reconnecting the GUI to a Running Coupled Solution ..................................................................... 93
Prerequisites ............................................................................................................................. 93
Disconnecting from the Running Solution ................................................................................. 94
Reconnecting to the Running Solution ...................................................................................... 95
Using Interactive Solve Commands ................................................................................................. 95
Simultaneous Execution of Participant Solutions ............................................................................. 97
System Coupling's Participant Grouping Process ....................................................................... 97
Creation of Participant Groups ............................................................................................ 98
Consolidation of Participant Groups .................................................................................... 98
Enabling Simultaneous Participant Solutions ............................................................................. 99
Enable Simultaneous Participant Solutions in the GUI .......................................................... 99
Enable Simultaneous Participant Solutions in the CLI ........................................................... 99
Execution of Simultaneous Participant Solutions ....................................................................... 99
Simultaneous Participant Solution Examples ........................................................................... 100
iv
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling User's Guide
Using Parallel Processing Capabilities ............................................................................................ 101
Recommended Workflow for Parallel Execution ....................................................................... 102
Parallel Processing for Coupling Participants ............................................................................ 103
Applying Partitioning to Coupling Participants .................................................................. 104
Machine List and Core Counts ........................................................................................... 106
Resource Allocation Fractions ........................................................................................... 106
Participant Partitioning Algorithms ................................................................................... 107
Choosing a Partitioning Algorithm .............................................................................. 108
Partitioning Algorithm Pros and Cons .......................................................................... 108
Participant Partitioning Examples ...................................................................................... 109
Shared Parallel: Allocate Machines ............................................................................... 112
Shared Parallel: Allocate Cores ..................................................................................... 114
Distributed Parallel: Allocate Cores .............................................................................. 115
Distributed Parallel: Allocate Machines ........................................................................ 116
Parallel Options for System Coupling ....................................................................................... 117
Parallel Options for Participant Products .................................................................................. 117
Running a Workbench Setup in a User Interface ............................................................................. 118
Using System Coupling in Workbench .................................................................................................... 121
Overview of System Coupling in Workbench ....................................................................................... 121
Supported Coupling Participants for System Coupling in Workbench ............................................. 122
Data Transfers for System Coupling in Workbench ......................................................................... 123
Steps of a Coupled Analysis in Workbench ..................................................................................... 124
System Coupling Tab in Workbench .............................................................................................. 124
Setting Up a Coupled Analysis in Workbench ....................................................................................... 126
Creating a Coupled Analysis .......................................................................................................... 126
Completing Participant Setups ...................................................................................................... 126
Connecting Systems on the Project Schematic .............................................................................. 127
Completing the Coupling Setup .................................................................................................... 129
Setup Node Context Options .................................................................................................. 129
Coupling-Specific Properties ................................................................................................... 130
Analysis Settings ............................................................................................................... 130
Analysis Type .............................................................................................................. 130
Initialization Controls .................................................................................................. 131
Duration Controls ....................................................................................................... 131
Step Controls .............................................................................................................. 132
Participants ...................................................................................................................... 133
Regions ...................................................................................................................... 133
Data Transfers ................................................................................................................... 134
Source/Target ............................................................................................................. 134
Data Transfer Control .................................................................................................. 135
Data Transfer Context Options ..................................................................................... 136
Execution Control ............................................................................................................. 137
Coupling Engine ......................................................................................................... 137
Expert Settings ........................................................................................................... 138
Debug Output ............................................................................................................ 139
Intermediate Restart Data Output ............................................................................... 139
Running a Coupled Analysis in Workbench .......................................................................................... 140
Starting the Solution ..................................................................................................................... 140
Monitoring Solution Progress ........................................................................................................ 141
Viewing Transcript Output ...................................................................................................... 141
Viewing System Coupling Charts ............................................................................................. 142
Availability of Chartable Data ............................................................................................ 142
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
Chart Properties ............................................................................................................... 143
Chart Variables ................................................................................................................. 144
Adding a Chart Variable .............................................................................................. 144
Chart Variable Properties ............................................................................................. 145
Chart Context Options ...................................................................................................... 145
Chart Monitor Controls ..................................................................................................... 146
Saving a Chart as a Graphic ............................................................................................... 147
Solution Validation and State ........................................................................................................ 147
Solution Node Context Options ..................................................................................................... 147
Alternate Workflows for System Coupling in Workbench ...................................................................... 148
Stopping a System Coupling Analysis in Workbench ...................................................................... 148
Restarting a Coupled Analysis in Workbench ................................................................................. 149
Generating Restart Files in Workbench .................................................................................... 149
Restarting a Coupled Analysis in Workbench ........................................................................... 150
Recovering from a Workbench Crash ....................................................................................... 151
Setting Up a Coupled Analysis in Workbench for a User-Interface Run ............................................ 152
Coupled Analysis Management .............................................................................................................. 155
Inter-Process Communication ............................................................................................................. 155
Process Synchronization and Analysis Evolution .................................................................................. 155
Convergence Management ................................................................................................................. 157
Evaluating Convergence of Data Transfers ........................................................................................... 157
System Coupling Data Transfers ............................................................................................................. 159
Rules for the Creation of Data Transfers ............................................................................................... 159
System Coupling's Data Transfer Process ............................................................................................. 160
System Coupling's Mapping Capabilities ............................................................................................. 160
Mapping Topologies ..................................................................................................................... 161
Mapping Types ............................................................................................................................. 161
Associating Source and Target Locations ...................................................................................... 163
Binary Space Partitioning Algorithm ........................................................................................ 164
Generating Data for Target Locations ............................................................................................ 164
Profile-Preserving Mapping Algorithms ................................................................................... 166
Linear Shape Function ...................................................................................................... 166
Radial Basis Function ........................................................................................................ 167
Element-Weighted Average .............................................................................................. 167
Conservative Mapping Algorithms .......................................................................................... 169
Intersect-Scatter-Gather for Like Topologies ...................................................................... 169
Intersect-Scatter Gather for Unlike Topologies ................................................................... 170
Supplemental Processing Algorithms .................................................................................................. 172
Data Reconstruction Algorithms ................................................................................................... 172
Ramping Algorithm ...................................................................................................................... 173
Under-Relaxation Algorithm ......................................................................................................... 175
Initial Values Used for the Reference Target-Side Value ................................................................... 176
Quasi-Newton Stabilization Algorithm .......................................................................................... 177
Quasi-Newton Recommendations ........................................................................................... 177
Quasi-Newton Limitations ....................................................................................................... 178
System Coupling Input and Output Files ................................................................................................ 179
Files Used by System Coupling ............................................................................................................ 179
Participant Setup File (*.scp) ...................................................................................................... 179
<ExecutionControl> ....................................................................................................... 180
<WorkingDirectory> ................................................................................................. 181
<InitialInput> .......................................................................................................... 181
<Command> ..................................................................................................................... 182
vi
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling User's Guide
<CosimulationControl> ................................................................................................ 182
<Type> ........................................................................................................................... 182
<AnalysisType> .......................................................................................................... 183
<DisplayName> ............................................................................................................ 183
<RestartsSupported> ............................................................................................... 183
<Variables> ................................................................................................................ 183
<Variable> ............................................................................................................ 183
<Name> ............................................................................................................... 184
<DisplayName> ................................................................................................ 184
<QuantityType> .............................................................................................. 184
<Location> ...................................................................................................... 184
<Regions> ........................................................................................................................... 185
<Region> ....................................................................................................................... 185
<Topology> ............................................................................................................ 185
<Name> ..................................................................................................................... 185
<DisplayName> ...................................................................................................... 186
<OutputVariables> ............................................................................................. 186
<Variable> ...................................................................................................... 186
<InputVariables> ............................................................................................... 186
<Variable> ...................................................................................................... 186
Sample System Coupling Participant File ................................................................................. 187
Input File (scInput.sci) ........................................................................................................... 187
<Transfers> ...................................................................................................................... 188
<ExecutionControl> ....................................................................................................... 189
<Analysis> ........................................................................................................................ 191
<Participants> ................................................................................................................ 192
Shutdown File (scStop) .............................................................................................................. 194
Files Generated by System Coupling .................................................................................................... 195
GUI Server File (sycGui.srv) ..................................................................................................... 196
Solution Lock File (sycSolve.lock) .......................................................................................... 196
Transcript and Log File (scLog.scl) ........................................................................................... 197
Executable Information ........................................................................................................... 197
Execution Information ............................................................................................................ 198
Participants Build Information ................................................................................................. 198
Summary of Coupling Setup .................................................................................................. 199
Coupling Control .............................................................................................................. 199
Solution Control ............................................................................................................... 200
Output Control ................................................................................................................. 200
Participants Information ................................................................................................... 200
Interfaces Information ...................................................................................................... 201
Coupled Solution ................................................................................................................... 202
Pre-Solution Warnings and Messages ................................................................................ 202
Coupling Step ................................................................................................................... 202
Mapping Summary ..................................................................................................... 203
Coupling Iteration ....................................................................................................... 203
Shut Down ............................................................................................................................. 205
Available Restart Points ........................................................................................................... 206
Debug Output .............................................................................................................................. 206
Settings File (Settings.h5) ....................................................................................................... 207
Results Files (Results_*#.h5) ................................................................................................... 207
ANSYS EnSight Gold–Formatted Results Files ................................................................................. 208
Server File (scServer.scs) ....................................................................................................... 210
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
Best Practices for System Coupling ........................................................................................................ 211
General Best Practices for Coupled Analyses ....................................................................................... 211
Building Up to a Coupled Analysis ................................................................................................. 211
Improving Mapping Quality .......................................................................................................... 212
Evaluating Convergence and Data Transfer Accuracy ..................................................................... 214
Improving the Accuracy of Steady Analyses ................................................................................... 214
Improving the Accuracy of Transient Analyses ............................................................................... 216
Best Practices for Coupled Fluid-Structure Interaction (FSI) .................................................................. 216
Building a Coupled FSI Analysis from Decoupled Participant Problems ........................................... 217
Step 1: Solve the Fluid and Structural Problems Independently ................................................ 218
Step 2: Solve the Fluid and Structural Problems as One-Way Coupled Analyses ......................... 219
Step 3: Solve the Fluid and Structural Problems as a Two-Way Coupled Analysis ........................ 221
Choosing the Mesh-Related Timescale .......................................................................................... 222
Defining Mesh Motion and Deformation Settings .......................................................................... 222
Improving Coupled Analysis Stability .................................................................................................. 223
Data Transfer Ramping .................................................................................................................. 223
Participant Solution Stabilization .................................................................................................. 223
viii
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 topologies .......................................................................................................................................................... 170
25. Mapping weights generated for a target element, based on its intersection with source elements via Intersect-Scatter-Gather between like topologies ......................................................................................... 170
26. Example input and output for conservative mapping for Intersect-Scatter-Gather between unlike topologies. 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 IntersectScatter-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
x
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
xii
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 together in a coupled multiphysics analysis — for example, in a Fluid-Structure Interaction (FSI) analysis.
System Coupling User's Guide Contents
The following topics are addressed:
• 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.
System Coupling Versions
When the term "System Coupling" is used without qualification, it refers to the current version of the
System Coupling application, which in earlier releases was designated as "System Coupling 2.0."
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
When referencing core, context-agnostic functionality:
• Bold font
• Title Case
When referencing functionality in terms of the graphical user interface (GUI):
• Bold font
• Proper Case, with the following exceptions:
– Sentence case for File menu options
– Proper UpperCamelCase for setting drop-down values
When referencing functionality in terms of the command-line interface (CLI):
• Code font
• Proper UpperCamelCase
• Hyphenated indexed object names
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.
2
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Overview
The ANSYS portfolio of simulation software facilitates the creation of multidisciplinary physics analyses—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 interactions 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:
• the System Coupling graphical user interface (GUI)
• the System Coupling command-line interface (CLI), and
• within ANSYS Workbench (WB).
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
The ANSYS Product Improvement Program
ANSYS System Coupling is covered by the ANSYS Product Improvement Program (APIP), which enables
ANSYS, Inc. to collect and analyze anonymous usage data reported by our software without affecting
your work or product performance. Analyzing product usage data helps us to understand customer
usage trends and patterns, interests, and quality or performance issues. The data enable us to develop
or enhance product features that better address your needs.
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).
APIP Participation Preferences
ANSYS System Coupling respects the participation preferences you've set in other ANSYS products. If,
when starting System Coupling, you have not yet specified a preference in another product, System
Coupling assumes that you have not agreed to participate and does not collect data. If you wish to
change your existing participation preference, access the ANSYS Product Improvement Program
dialog from a participant product's Help menu.
Data Collected by ANSYS System Coupling
If you agree to participate in the APIP program, System Coupling collects the following coupling-specific
data:
• Number of participants
• Participant type (i.e., the ANSYS product engaging as a coupling participant)
• Number of participants serving as a data transfer target (i.e., that are receiving data from another coupling
participant)
System Coupling Capabilities
This section provides information on System Coupling's capabilities and participant-specific support of
available coupling functionality. For more information, see:
System Coupling Capabilities by Version
System Coupling Data Transfer Quantities
Participant Support of System Coupling Capabilities
System Coupling Capabilities by Version
Table 1: System Coupling capabilities by version (p. 4) shows the key coupling capabilities available
for System Coupling in Workbench, command-line System Coupling, and System Coupling in Workbench
1.0.
Table 1: System Coupling capabilities by version
Category
User
Environment
4
Capabilities
Unified access to
participant transcript file(s)
System
System
Coupling Coupling
GUI
CLI
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
✓
✓
Charting: Collated
participant convergence
and monitors
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
✓
System Coupling Capabilities
Category
Coupled Run
Execution
Capabilities
System
System
Coupling Coupling
GUI
CLI
Charting: Data transfer
convergence
Beta1
Charting: Data transfer
diagnostics, per quantity
Beta1
Charting: Output of
charting data as
CSV-formatted files
Beta1
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
✓
✓
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
restarts
✓
✓
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)
participants
2
Beta1
✓
✓
Beta1
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
Category
Capabilities
Simultaneous participant
solutions
System
System
Coupling Coupling
GUI
CLI
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
✓
✓
✓
✓
Steady coupled analyses
✓
✓
✓
✓
Transient coupled analyses
✓
✓
✓
✓
Mixed steady-transient
coupled analyses
✓
✓
✓
✓
Include content from
ANSYS External Data
system
✓
✓
✓
✓
✓
✓
✓
✓
Multiple iterations per
coupling step (for implicit
couplings)
✓
✓
✓
✓
Set minimum and
maximum number of
coupling iterations per step
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
Participant solution
sequence control2
Participant update
frequency control2
Geometry transformations
for participant models with
different orientations
(limited to scalar data
✓
transfers)2
All fixed topology element
types (except polyhedral)
Note:
High-order
mesh/data is
converted to
low-order.
Interfaces
and
Transfers
Polyhedral element types
2
Multiple regions per side
of interface
2
Locally and globally
conservative mapping
algorithms
6
✓
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
✓
System Coupling Capabilities
Category
Capabilities
Profile-preserving mapping
algorithms
System
System
Coupling Coupling
GUI
CLI
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
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,
planar surface
Beta1
Beta1
• Surface, volume, planar
surface⇒ Single scalar
value
Convergence control per
transfer, per interface
✓
✓
✓
✓
Under-relaxation per
transfer, per interface
✓
✓
✓
✓
Ramping per transfer, per
interface
✓
✓
✓
✓
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
Category
System
System
Coupling Coupling
GUI
CLI
Capabilities
Quasi-Newton solution
stabilization algorithm, per
transfer, per interface
✓
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
✓
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.
System Coupling Data Transfer Quantities
Table 2: Transfer quantities supported by System Coupling (p. 8) provides a summary of the various
transfer quantity types (e.g., force) that are referenced in System Coupling Capabilities by Version (p. 4).
Coupling participants declare variables of a given quantity type, and System Coupling ensures that data
transfers are created between variables of the same/compatible quantity type.
Table 2: Transfer quantities supported by System Coupling
Transfer Quantity
Type1
Force [N]
Incremental
Displacement [m]
Heat Rate [W]
Tensor Type
Applicable
Mapping
Algorithm Type2
Vector3
Conservative
Vector
3
Scalar
Profile-Preserving
Displacement during the current
coupling step (i.e., since the end of
the previous coupling step)
Conservative
Heat Rate Density
[W/m3]
Scalar
Temperature [K]
Scalar
Profile-Preserving
Heat Transfer
Coefficient
[W/(m2K)]
Scalar
Profile-Preserving
8
Notes
Conservative
Conservative mapping used when
paired with a variable of Heat Rate
quantity type
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Capabilities
Transfer Quantity
Type1
Convection
Reference
Temperature [K]
Tensor Type
Scalar
Applicable
Mapping
Algorithm Type2
Notes
Profile-Preserving
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).
3: All vector quantities consist of three Cartesian components.
For participant-specific information on the quantity types that can be transferred via System Coupling,
see the corresponding participant documentation:
• Variables Available for System Coupling in the Fluent User's Guide
• Variables Available for System Coupling in the CFX-Solver User's Guide
• Variables Available for System Coupling in the Mechanical User's Guide
• Variables Available for System Coupling in the Forte User's Guide
• "System Coupling Analyses Using Maxwell" in the Maxwell Help
Participant Support of System Coupling Capabilities
Table 3: Participant-specific support of System Coupling capabilities (p. 9) shows participant support
of the key coupling capabilities available for System Coupling in Workbench, command-line System
Coupling, and System Coupling in Workbench 1.0.
Table 3: Participant-specific support of System Coupling capabilities
Category
Fluent
Capabilities
System
System
Coupling Coupling
GUI
CLI
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
✓
Steady or transient
analysis types
✓
✓
✓
Polyhedral element types
✓
✓
✓
Multiple regions per side
of interface
✓
✓
Participant update
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
Category
Capabilities
System
System
Coupling Coupling
GUI
CLI
System
Coupling in
Workbench
System
Coupling in
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
Volume transfer quantities:
• Output: Temperature
✓
✓
✓
✓
• Input: Heat Rate
Steady or transient
analysis types
Participant update
frequency control
Beta1
Beta1
Surface transfer quantities:
CFX
• 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
Steady or transient
analysis types
Surface transfer quantities:
Forte
• Output: Heat Rate, Heat
Transfer Coefficient and
Convection Reference
Temperature
• Input: Temperature
Mechanical
APDL
10
Steady or transient
analysis types
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Capabilities
Category
Capabilities
Participant update
frequency control
Geometry transformations
for participant models
with different orientations
(limited to scalar data
transfers)
System
System
Coupling Coupling
GUI
CLI
Beta1
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
Beta1
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
Eddy current (3D) or
transient (2D & 3D)
solution type
✓
✓
Multiple regions per side
of interface
✓
✓
Participant update
frequency control
✓
✓
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
Volume transfer quantities:
• Output: Temperature
• Input: Heat Rate Density
Electronics
Desktop /
Maxwell
Volume transfer quantities:
• Output: Heat Rate
• Input: Temperature
Planar Surface transfer
quantities:
• Output: Heat Rate
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
Category
Capabilities
System
System
Coupling Coupling
GUI
CLI
System
Coupling in
Workbench
System
Coupling in
Workbench
1.0
• Input: Temperature
Steady or transient
solution type
Functional
Mock-up Unit
(FMU)
Beta1
Beta1
Beta1
Beta1
Single value, scalar
transfer quantities (input
and output):
• Input and Output:
Temperature, Heat Rate, Heat
Transfer Coefficient and
Convection Reference
Temperature
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
• System Coupling in the Forte User's Guide
• System Coupling in the Mechanical User's Guide
• "System Coupling Analyses Using Maxwell" in the Maxwell Help
System Coupling Contexts: GUI, CLI, and Workbench
You can run System Coupling in the following contexts:
System Coupling's User Interfaces:
• System Coupling's Graphical User Interface (GUI)
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.
• System Coupling's Command-Line Interface (CLI)
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.
12
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Product Licensing Considerations
For more information, see Using System Coupling's User Interfaces (p. 33).
System Coupling in Workbench
Run System Coupling in Workbench, using the Workbench interface and workflow to build and execute
coupled analyses. Workbench's System Coupling component system is an easy-to-use, all-purpose
infrastructure that enables you to build and execute simulations involving the transfer of surface data
between coupling participants.
For more information, see Using System Coupling in Workbench (p. 121).
Product Licensing Considerations
The licenses needed for System Coupling analyses are listed in Table 4: Licenses required for participants
in System Coupling analyses (p. 13). No additional licenses are required for the System Coupling infrastructure.
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:
• Distinct licenses are required for each coupling participant.
• 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.
Table 4: Licenses required for participants in System Coupling analyses
Product
Commercial License Required
Academic License Required
• ANSYS Academic Associate
Mechanical and CFD
• ANSYS Mechanical Enterprise
and ANSYS CFD Enterprise
• ANSYS Academic Associate CFD
• ANSYS CFD
• ANSYS Academic Research
Mechanical and CFD
• ANSYS Fluent
• ANSYS Academic Research CFD
• ANSYS Fluent Solver
• ANSYS Academic Teaching
Mechanical and CFD
ANSYS Fluent
• ANSYS Academic Teaching CFD
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
Product
Commercial License Required
Academic License Required
• ANSYS Academic Associate
Mechanical and CFD
• ANSYS Academic Associate CFD
• ANSYS Mechanical Enterprise
and ANSYS CFD Enterprise
• ANSYS Academic Research
Mechanical and CFD
• – ANSYS CFX
• ANSYS Academic Research CFD
ANSYS CFX
• ANSYS Academic Teaching
Mechanical and CFD
• ANSYS Academic Student
ANSYS Forte
• ANSYS Mechanical Enterprise
and ANSYS CFD Enterprise
• ANSYS Academic Associate
Chemical Kinetics
• ANSYS CFD
• ANSYS Academic Research Chemical
Kinetics
• ANSYS Mechanical CFD
Maxwell
• ANSYS Forte CFD
• ANSYS Academic Teaching Chemical
Kinetics
• ANSYS Academic Associate
Mechanical and CFD
ANSYS
Mechanical
• ANSYS Mechanical Enterprise
and ANSYS CFD Enterprise
• ANSYS Academic Research
Mechanical and CFD
• ANSYS Mechanical Enterprise
• ANSYS Academic Research
Mechanical
• ANSYS Mechanical Enterprise
Solver
• ANSYS Academic Teaching
Mechanical and CFD
• ANSYS Academic Student
• ANSYS Maxwell
• ANSYS Maxwell QS
ANSYS Maxwell
3D Design
• ANSYS Mechanical CFD
Maxwell
• ANSYS Mechanical Maxwell
14
• ANSYS Academic Associate EM
• ANSYS Academic Research EM
• ANSYS Academic Teaching
Mechanical EM
• ANSYS Academic Multiphysics
Campus Solution
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Analysis Types
Steps of a System Coupling Analysis
Coupled analyses performed using System Coupling are composed of the following general steps:
1. Set up the physics for coupling participants.
For each participant, set up data transfer variables and regions to be coupled, as well as couplingrelated settings that enable a coupled analysis.
2. Set up System Coupling.
Set up the System Coupling part of the analysis, specifying analysis settings and defining data
transfers.
3. Run the coupled analysis.
Run the coupled analysis by starting System Coupling and each of the participant solvers.
4. During the coupled analysis run, you can:
• Monitor solution progress.
• Stop and resume the analysis.
5. After the coupled analysis run, you can:
• Extend and restart the analysis.
• Debug your coupled analysis.
6. Review the analysis output.
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.
System Coupling Analysis Types
When using System Coupling, you can perform the following types of analyses:
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.
• For more information, see General/Steady Analysis Type (p. 16).
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
• Used when any coupling participant is performing a transient solution.
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.
• For more information, see Transient Analysis Type (p. 17).
General/Steady Analysis Type
This section describes the two ways you can combine coupling steps and coupling iterations in a
general or steady analysis: by using a single coupling step, or by using multiple coupling steps. Your
specific combination of coupling steps and coupling iterations:
• 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.
General/Steady Coupled Analysis with One Coupling Step
When a general/steady coupled analysis is solved using a single coupling step, the coupling step is
made up of many coupling iterations and the solution is complete at the end of the step. The analysis
continues executing until either the solution converges, or the specified maximum number of coupling
iterations is completed.
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-relaxation can be applied across coupling iterations within the single coupling step.
16
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling Analysis Types
General/Steady Coupled Analysis with Multiple Coupling Steps
When a general/steady coupled analysis is solved using multiple coupling steps, the coupling steps
are made up of one or more coupling iterations. The analysis continues executing until the specified
number of coupling steps is completed. The transition from one coupling step to the next occurs
when either the solution converges, or the specified maximum number of coupling iterations is
completed.
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 terminate 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.
Transient Analysis Type
In a transient analysis, 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. The coupling step size used should reflect the time scales of the physics being
studied. Note that unless sub-stepping is supported by the coupling participants, coupling step size
is typically limited by the finest/smallest time scale of the participants.
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 steadystate 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
System Coupling Settings
All coupled analyses have settings that enable you to control various aspects of the analysis. The following
types of settings are available:
• Analysis settings
Settings defining the type of analysis and controls for the initialization, duration, and steps of
the analysis.
• Solution settings
Settings defining analysis-level solution controls, such as simultaneous execution of participant
solutions.
• Execution control settings
Settings defining details about the execution of the coupled analysis.
• Output control settings
Settings defining the frequency with which coupling output (specifically, restart points) is generated.
• 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.
• Data transfer settings
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.
Stops and Restarts of System Coupling Analyses
In some cases, you may want to stop an coupled analysis during its execution, before it is completed.
If you've interrupted the run, you can restart the analysis from a specified restart point.
For general information on stops and restarts, see:
Stopping a Coupled Analysis
Restarting a Coupled Analysis
18
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Stops and Restarts of System Coupling Analyses
Stopping a Coupled Analysis
You can stop a coupled analysis run by either interrupting or aborting it.
• 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.
For context-specific details, see:
• Stopping a System Coupling Analysis in Workbench (p. 148)
• Stopping a Coupled Analysis (p. 87)
Restarting a Coupled Analysis
You can restart a completed or interrupted coupled analysis run, either from the final result or from
an intermediate result. Restarts require relevant files from System Coupling and each of the coupling
participants.
Note:
Some participants may not allow restarts. For example:
• AEDT participants do not support restarts from intermediate results.
• Mechanical participants do not support restarts for steady-state thermal and transient
thermal analyses.
To restart an interrupted analysis, perform the following steps:
1. Generate restart files.
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
2. Execute the restart run.
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:
• Participants are not guaranteed to deliver identical behavior.
• 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 underrelaxation (p. 175) are reset to initial values upon remapping, so no ramping or under-relaxation 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.
For context-specific information on restarts, see:
• Restarting a Coupled Analysis in Workbench (p. 149)
• Restarting a Coupled Analysis (p. 88)
Migrating to ANSYS System Coupling 2020 R1
As improvements are made to System Coupling's data model and functionality, care is taken to maintain
backward compatibility. With each new release, however, it is recommended that you familiarize yourself
with any changes and identify areas where your scripts or workflows may be affected.
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 implemented 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
20
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
Migrating Across Multiple Releases
If you are migrating across multiple releases, you may find it helpful to consult the migration instructions for the intervening releases, as well. Starting with the 2019 R2 release, migration guidance for
command-line System Coupling has been published in the System Coupling User's Guide. To access
this documentation:
1.
Go to the System Coupling page of the online ANSYS Help site.
2.
At the upper-right corner of the window, select the appropriate release from the Release drop-down
menu.
3.
Under Documentation, open the System Coupling User's Guide.
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.
Migrating to Use Fluent Face/Cell Transfer Data
Starting with the 2020 R1 release, Fluent coupling participants automatically receive and send data
on face/cell locations (instead of on nodes) when engaging in transfers of conservative quantities.
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).
Default behavior in 2020 R1 is as follows:
New Coupled Analyses
New coupled analyses created with the 2020 R1 release will be set up with face/cell-based transfers.
Both System Coupling and Fluent apply the new functionality to these cases and use conservative
face/cell data.
Existing Coupled Analyses
For existing coupled analyses that were created with an earlier (pre-2020 R1) releases and set up with
node-based data transfers, default behavior is as follows:
• 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.
• For existing cases that were set up in Workbench:
– 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 functionality.
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
Migrating to the Use of Face/Cell Data
1.
Open the case in Fluent.
2.
Run the TUI command:
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
A prompt is shown, indicating the current setting for the feature:
Use face based data transfer? [no]
3.
To change the setting, type in "yes" and press Enter:
Use face based data transfer? [no] yes
Fluent's use of face/cell-based locations for conservative data transfers is enabled.
22
4.
Save the case in Fluent.
5.
Regenerate results:
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
a.
Regenerate the SCP file.
b.
Re-solve the coupled analysis.
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
Reverting to the Use of Nodal Data
1.
Open the case in Fluent.
2.
Run the TUI command:
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
A prompt is shown, indicating the current setting for the feature:
Use face based data transfer? [yes]
3.
To change the setting, type in "no" and press Enter:
Use face based data transfer? [yes] no
Fluent's use of face/cell-based locations for conservative data transfers is disabled.
4.
Save the case in Fluent.
5.
Regenerate results:
a.
Regenerate the SCP file.
b.
Re-solve the coupled analysis.
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
Cases Set Up and Solved with Workbench
By default, existing cases that were set up and run in Workbench use face/cell 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
Migrating to the Use of Face/Cell Data
The new functionality is applied automatically. No further migration steps are required.
Reverting to the Use of Nodal Data
To go back to using nodal data, you must instruct both System Coupling and Fluent to revert to
the previous functionality, as follows:
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.
2.
Disable Fluent's use of conservative face/cell data:
a.
Open the case in Fluent through the Workbench user interface.
b.
Run the TUI command:
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
A prompt is shown, indicating the current setting for the feature:
Use face based data transfer? [yes]
c.
To change the setting, type in "no" and press Enter:
Use face based data transfer? [yes] no
Fluent's use of face/cell-based locations for conservative data transfers is disabled.
3.
24
Save the case in Fluent.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
4.
Re-solve the coupled analysis.
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. Existing 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
Migrating to the Use of Face/Cell Data
1.
Open the case in Fluent.
2.
Run the TUI command:
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
A prompt is shown, indicating the current setting for the feature:
Use face based data transfer? [no]
3.
To change the setting, type in "yes" and press Enter:
Use face based data transfer? [no] yes
Fluent's use of face/cell-based locations for conservative data transfers is enabled.
4.
Save the case in Fluent.
5.
Re-solve the coupled analysis.
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
Reverting to the Use of Nodal Data
Before importing the SCI file into System Coupling's GUI or CLI, set the environment variable
SYC_FLUENT_CONSNODAL to any value. This causes System Coupling to revert to the use of
nodal data for conservative data transfers.
To revert new cases to use nodal data, the following steps are also necessary:
1.
Open the case in Fluent.
2.
Run the TUI command:
/define/models/system-coupling-settings/use-face-or-element-based-data-transfer?
A prompt is shown, indicating the current setting for the feature:
Use face based data transfer? [yes]
3.
To change the setting, type in "no" and press Enter:
Use face based data transfer? [yes] no
Fluent's use of face/cell-based locations for conservative data transfers is disabled.
4.
Save the case in Fluent.
5.
Re-solve the coupled analysis.
Note:
For instructions on using Fluent's text user interface (TUI), see the Fluent Text Command
List manual.
Migrating Command-Line System Coupling Scripts
System Coupling 2020 R1 contains changes that can impact existing coupling scripts.
Existing coupling cases (i.e., that have been saved to a Settings.h5 file) will be migrated automatically 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
26
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
Changes to Command-Line Options
Changes to the Data Model
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.
Command
Change
Recommendation
Command pending
deprecation.
CreateInterfacesAndDataTransfers
will be deprecated in a
future release. It is still
supported in the 2020
R1 release, with the
following exceptions:
• Not supported for
Mechanical-Maxwell
couplings.
CreateInterfacesAndDataTransfers()
• May cause unexpected
results when used to
create new analyses with
data transfer between 2D
and 3D region.
When this command is
run, a warning is
generated and the
recommended
replacement commands
for creating the
interfaces and data
transfers are written to
the Transcript.
Command pending
deprecation.
StartParticipants()
StartParticipants
will be deprecated in a
future release.
Use the following
commands
instead:
• AddInterface()
• AddInterfaceByDisplayNames()
• AddDataTransfer()
• AddDataTransferByDisplayNames()
Consider
adopting
workflows where
participants are
started by
another method,
such as the Ini-
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
Command
Change
Recommendation
tialize, Step,
or Solve
commands.
For more
information, see
StartParticiapnts.
Deprecated argument.
ParticipantNames
has been deprecated.
When StartParticipants is run with
this argument, it
ignores provided
participant list and
starts all participants.
New argument.
The CouplingIteration argument has
been added. This
argument is used to
open only
iteration-based restart
files.
Open()
Note that the existing
CouplingStep
argument is used to
open only step-based
restart files.
Run the StartParticipants
command
without
arguments.
Ensure that you
use CouplingIteration only
for analyses with
iteration-based
restart files (Results_iter#.h5).
Conversely,
ensure that you
use CouplingStep only for
analyses with
step-based restart
files (Results_step#.h5).
For more
information, see
Open.
Changes to Command-Line Options
The table below lists changes to command-line options in the 2020 R1 release of System Coupling.
Command-Line Option
Change
Changed option.
--cnf
Behavior for the --cnf command-line argument has changed.
28
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Migrating to ANSYS System Coupling 2020 R1
Command-Line Option
Change
Previously, this option specified the machine list for analyses
with the System Coupling engine running in parallel.
Now, this option specifies the machine list for analyses with
coupling participants running in parallel.
For more information, see Coupling Participant Parallel
Options.
Changed option.
Behavior for the -t and --nprocs command-line arguments
has changed.
Previously, these options specified the number of cores used
for System Coupling in a parallel run. (This information can
now be specified using the -s or --sycnprocs
command-line option.)
-t
--nprocs
Now, these options specify number of cores used for
participants in a parallel run.
For more information, see Coupling Participant Parallel
Options.
Changes to the Data Model
The table below lists changes to the data model in the 2020 R1 release of System Coupling.
Data Model Item
Change
New container.
SolutionControl
The SolutionControl
singleton container has been
added at the root-level.
Contains analysis-level settings
that control how solutions are
executed.
New setting.
SolutionControl.AllowSimultaneousUpdate
The AllowSimultaneousUpdate has been added under the
SolutionControl singleton.
Specifies whether simultaneous
solutions for independent
participants are enabled.
New setting.
SolutionControl.PartitioningAlgorithm
The PartitioningAlgorithm setting has been
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
Data Model Item
Change
added under the SolutionControl singleton.
Specifies the partitioning
algorithm to be used when
coupling participants are running
in parallel.
Changed setting.
OutputControl.Option
Behavior for the output control
Option setting has changed.
Available only when all
participants support restarts.
New setting.
CouplingParticipant.ParticipantAnalysisType
The ParticipantAnalysisType setting has been
added under the CouplingParticipant singleton.
Available only when ParticipantType is set to DEFAULT.
Indicates whether the participant
is running a Steady or Transient
analysis.
New setting.
CouplingParticipant.RestartsSupported
The RestartsSupported
setting has been added under
the CouplingParticipant
singleton.
Available only when ParticipantType is set to DEFAULT.
Indicates whether the participant
supports restarts.
New setting.
CouplingParticipant.OutputControl.ParallelFraction
The ParallelFraction
setting has been added under
the coupling participant's OutputControl singleton.
Specifies the core count or
fraction of compute resources to
be allocated to the participant
when participants are running in
parallel.
30
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Known Issues and Limitations
Data Model Item
Change
Removed setting.
The ParallelArguments
setting has been removed.
In existing scripts, any arguments
specified by this setting are
ignored.
CouplingParticipant.ExecutionControl.ParallelArguments
Parallel arguments will be
determined automatically based
on the PartitioningAlgorithm and ParallelFraction settings, and, if applicable,
on the --cnf input argument.
Alternatively, use the AdditionalArguments setting to
manually set the parallel
command-line arguments for a
participant.
Removed setting.
CouplingParticipant.ExecutionControl.ExecutablePrefix
The ExecutablePrefix
setting has been removed.
Known Issues and Limitations
This section lists issues and limitations that are known to exist in ANSYS System Coupling 2020 R1.
Where possible, suggested workarounds are provided.
Detached instances of System Coupling
A System Coupling session that was started in GUI Server mode, as described in Reconnecting the GUI to
a Running Coupled Solution (p. 93), can be ended cleanly only from a connected instance of the System
Coupling GUI. If this is not possible, you must end it manually by issuing an OS-specific kill request.
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.
Orphaned GUI Server files
In most cases, the GUI Server (sycGui.srv) file (p. 196) should not be removed manually. This file is
automatically removed from the coupling working directory the instance of System Coupling running in
GUI Server mode exits. However, unexpected termination of a coupling run may leave orphaned (i.e., not
connected to any active session) GUI Server files, which prevents subsequent instances of System Coupling
from starting in GUI Server mode in that directory.
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
Orphaned Solution Lock files
In most cases, the Solution Lock (sycSolve.lock) file (p. 196) should not be removed manually. This file
is automatically removed from the coupling working directory when the solution stops. However, unexpected termination of a coupling run may leave orphaned (i.e., not connected to any active session)
Solution Lock files, which blocks any subsequent solves in that directory.
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.
GUI issues on Linux caused by inadequate remote graphics setup
When the System Coupling GUI is run on a remote Linux system without an adequate remote graphics
display set up it may crash at start-up. (For details on graphics setup requirements, see the related ANSYS
installation documentation.)
If issues are encountered, try setting the environment variable QT_QUICK_BACKEND to software
before starting the GUI.
Participant connection issues
A participant may fail to connect to System Coupling if it attempts to use the wrong host name for the
machine on which System Coupling is running. This can occur if the hosts file on that system has been
modified manually (for example, to circumvent access to network locations).
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.
OpenMPI is not supported in the System Coupling Participant Library
Currently, if a participant solver is using the OpenMPI Message Passing Interface distribution for parallel
execution, then the System Coupling Participant APIs should be implemented as described in the Using
an Unsupported MPI Distribution section in the System Coupling Participant Library documentation.
Unicode path requirements described incorrectly in CLI help
System Coupling cannot be run in a directory path containing Unicode characters. For its Save and Open
commands, the FilePath argument accepts a WriteableDirectory value — which requires that
only ASCII characters are used in the directory path — instead of a WriteableUnicodeDirectory,
as is stated in the help obtained from the command-line interface.
AEDT participants abort the run if a lock file exists
ANSYS Electronics Desktop/Maxwell participants will abort a coupled analysis run if a lock file exists. When
this happens, you must stop System Coupling processes, either manually or by using a Shutdown file (p. 194).
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:
If a participant is taking a long time to connect, a warning message will be written to
System Coupling's Transcript. You can use the Connection Timeout beta parameter to
set the maximum amount of time System Coupling waits for participants to connect. For
more information, see Participant Connection Timeout Setting in the System Coupling
Beta Features documentation.
32
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 functionality 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.
The following topics are addressed in this section:
• 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
Overview of System Coupling's User Interfaces
This section provides a high-level overview of how to use System Coupling in its user interfaces. The
following topics are addressed:
• 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.
Supported Coupling Participants
System Coupling participants are applications (i.e., solvers) that send and/or receive data in a coupled
analysis. The following is the list of applications that can act as coupling participants in coupled
analyses run in one of System Coupling's user interfaces:
CFX
For information on using System Coupling with ANSYS CFX, see the following sections in the CFX-Solver
Modeling Guide:
• Coupling CFX to an External Solver: System Coupling Simulations
• System Coupling Related Settings in CFX
• Running CFX as a Participant from System Coupling's GUI or CLI
Fluent
For information on using System Coupling with ANSYS Fluent, see the following sections in the Fluent
User's Guide:
• Performing System Coupling Simulations Using Fluent
• System Coupling Related Settings in Fluent
• Running Fluent as a Participant from System Coupling's GUI or CLI
Forte
For information on using System Coupling with ANSYS Forte, see the following sections in the Forte
User's Guide:
• System Coupling
• System Coupling Related Settings
• Setting Up a Coupled Simulation
34
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
• System Coupling Analyses Using Maxwell
Note:
To enable coupling for Maxwell on a Linux system, you must set the ANSYSEM_ROOT201 environment variable to the location of your ANSYS EM Suite installation.
Mechanical
For information on using System Coupling with ANSYS Mechanical, see the following sections in the
Mechanical User's Guide:
• System Coupling
• System Coupling Related Settings in Mechanical
• Running Mechanical as a Coupling Participant in System Coupling's GUI or CLI
Coupling Interfaces and Data Transfers
In a coupled analysis performed in a System Coupling user interface, data are transferred between
the two sides of a given coupling interface.
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 Quantities (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
Rules for the Creation of Coupling Interfaces
When you create a coupling interface (p. 59) in one of System Coupling's user interfaces, the following rules apply:
• 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.
Interface names must be unique within an analysis.
• 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.
• Each interface side can have regions of only a single topology.
• 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 Transfers (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.
Rules for the Creation of Data Transfers
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.
36
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
• On a given interface, if a transfer of Force is defined, then a transfer of Incremental Displacement
cannot also be defined in the same direction, and vice versa.
• 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.
Steps of a Coupled Analysis
To create and run a coupled analysis in one of System Coupling's user interfaces, perform the following
steps:
1. Prepare for the analysis. (p. 55)
a. Create a directory structure. (p. 56)
b. Set up participants. (p. 57)
c. Generate participant input files. (p. 58)
2. Create the analysis. (p. 59)
a. Load the participants. (p. 59)
b. Create the coupling interface(s) and data transfers. (p. 61)
3. Modify the analysis. Optionally, you can:
a. Change data model settings. (p. 66)
4. Run the analysis. (p. 80)
a. Start the solution. (p. 80)
b. Monitor the solution progress. (p. 197)
5. Stop and restart the analysis. Optionally, you can:
a. Stop the analysis. (p. 87)
b. Modify the analysis as needed.
c. Restart the analysis. (p. 88)
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)
7. Review analysis output.
a. Review System Coupling's output. (p. 195)
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.
Participant Solution Sequencing
System Coupling's participant solution sequencing — the order in which participant solutions are
executed within an analysis — is based on a combination of participant object names and data
transfer ordering requirements. An initial ordering of individual participants is a necessary step for
all coupled analyses, both cases where the participants will solve individually and cases where groups
of independent participants will be solved simultaneously.
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, CFX4) 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 participants 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).
38
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Working with System Coupling's Data Model
Working with System Coupling's Data Model
When working in one of System Coupling's user interfaces, you interact with System Coupling by editing
its data model in the GUI or the CLI. Once you're familiar with the data model, you can use it to create
and/or modify your coupled analysis as described in Creating a Coupled Analysis (p. 59) and Modifying
Coupled Analysis Settings (p. 66).
For information on working with the data model, see:
Data Model Structure
Root-Level Containers
Viewing Data Model Contents
Data Model Structure
System Coupling's data model has a hierarchical structure, much like that of a directory system or file
system.
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
Figure 1: Data model example in System Coupling's GUI
Figure 2: Data model example in System Coupling's CLI
40
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
• Contains analysis-level settings that define how solutions are executed.
• 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
• Contains settings that determine what coupled analysis output is produced.
• Includes settings for output frequency.
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.
Viewing Data Model Contents
The following sections provide instructions on different ways to view the contents of the data model:
Viewing a Container's Contents
Viewing an Object's Children
Viewing the Contents of an Object's Children
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
Viewing a Container's Contents
To view the contents of a container, use the PrintState command on the container. Examples
for viewing the contents of singletons (p. 42) and viewing the contents of objects (p. 42) are
provided below.
Viewing the Contents of a Singleton
Example 1: View the contents of the CouplingControl singleton
>>> DatamodelRoot().CouplingControl.PrintState()
CouplingControl
AnalysisType:
Option = Transient
StepControl:
MaximumIterations = 5
TimeStepSize = 1.0 [s]
MinimumIterations = 1
DurationControl:
EndTime = 1.0 [s]
Option = EndTime
Example 2: View the contents of the DurationControl singleton
>>> DatamodelRoot().CouplingControl.AnalysisType.DurationControl.PrintState()
CouplingControl
AnalysisType
DurationControl
EndTime = 1.0 [s]
Option = EndTime
Viewing the Contents of an Object
Example 3: View the contents of a participant's Region:wall object
>>> 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
Example 4: View the contents of the interface's Side:One object
>>> DatamodelRoot().CouplingInterface['Interface-1'].Side['One'].PrintState()
CouplingInterface:Interface-1
Side:One
42
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Working with System Coupling's Data Model
CouplingParticipant = CFX-2
RegionList = plate
Viewing an Object's Children
To view a list of all of an object's children, use the GetChildNames method on the object.
Example 5: View the children of the CouplingParticipant object
>>> DatamodelRoot().CouplingParticipant.GetChildNames()
['MAPDL-1', 'CFX-2']
Example 6: View the children of a participant's Region object
>>> 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.
Viewing the Contents of an Object's Children
To view the contents for all of an object's children, use a Python for loop in conjunction with the
GetChildNames method.
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.
Example 7: View the contents of an interface's Side child objects
>>> for side in DatamodelRoot().CouplingInterface['Interface-1'].Side.GetChildNames():
DatamodelRoot().CouplingInterface['Interface-1'].Side[side].PrintState()
...
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
Example 8: View the contents of a participant's Variable child objects
>>> for variable in DatamodelRoot().CouplingParticipant['MAPDL-1'].Variable.GetChildNames():
DatamodelRoot().CouplingParticipant['MAPDL-1'].Variable[variable].PrintState()
...
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
Using System Coupling's Graphical User Interface (GUI)
System Coupling's graphical user interface (GUI) offers a direct, GUI-based workflow for convenient access
to coupling functionality outside the Workbench environment.
For more information, see:
Starting the System Coupling GUI
System Coupling GUI Components
System Coupling GUI Menus
Starting the System Coupling GUI
You can start the System Coupling GUI using either of the following methods:
Starting the GUI from the Start Menu
Starting the GUI from the Command Prompt
Starting the GUI from the Start Menu
To start the System Coupling GUI from the Windows Start menu:
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.
44
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
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.
Starting the GUI from the Command Prompt
To start the System Coupling GUI from the command prompt:
1.
Open the shell for your operating system.
2.
Run the System Coupling executable for the appropriate platform, using the -G or --gui commandline 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 directory 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 options described in System Coupling Parallel Options in the System Coupling Settings and
Commands Reference manual.
System Coupling GUI Components
The System Coupling GUI includes the following components:
Menu Bar
Outline
Properties
Tabs
Status Area
46
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Using System Coupling's Graphical User Interface (GUI)
Figure 3: The System Coupling GUI
Menu Bar
The Menu Bar contains the File and Help menus.
For details on available options, see Menu-Bar Menus (p. 49).
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 containers, 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:
Convergence charting and a corresponding Charting tab is available as beta-functionality. For more information, see System Coupling Convergence Charting in the System
Coupling Beta Features documentation.
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.
48
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
Table 5: Status messages
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.
System Coupling GUI Menus
This section provides quick-reference information on the menus available in the System Coupling
GUI. Where applicable, links are provided to more detailed treatment of menu-option usage.
For more information, see:
Menu-Bar Menus
Context Menus
Menu-Bar Menus
The Menu Bar contains the File and Help menus.
Available menu options for each are shown in the tables below:
Table 6: File Menu Options
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).
For details on the command corresponding to this operation, see
Open in the System Coupling Settings and Commands Reference
manual.
Open at iteration
Enabled if Settings and Results files exist in System Coupling's SyC
directory. Opens an existing co-simulation at the specified iteration.
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.
For more information, see Restarting a Coupled Analysis (p. 88).
For details on the command corresponding to this operation, see
Open in the System Coupling Settings and Commands Reference
manual.
Saves the current co-simulation to a Settings file and a Results file.
By default, files corresponding to the end of the last completed
coupling step are saved to the SyC subdirectory in System Coupling's
working directory.
Save
For more information, see Saving a Coupled Analysis (p. 86).
For details on the command corresponding to this operation, see
Save in the System Coupling Settings and Commands Reference
manual.
Loads the specified System Coupling Input (SCI) file (which is
created for coupled analyses that are set up in Workbench) and
pushes its information to the data model.
Cannot be used after participants have been started.
Load SCI file
For more information, see Running a Workbench Setup in a User
Interface (p. 118).
For details on the command corresponding to this operation, see
ImportSystemCouplingInputFile in the System Coupling
Settings and Commands Reference guide.
Runs the specified Python script in System Coupling's Command
Console tab.
Run script
After selecting this option, navigate to and select the script to be
run.
Enables engine command journalling.
Journal engine
commands
50
After selecting this option, specify path for the file to which a log
of engine commands will be written as the commands are executed.
Stop journal
Available when engine command journalling is enabled. Stops the
journalling of executed commands.
Exit
Exits the co-simulation, ending the coupling run and signaling
participants to end the run. This produces a clean shutdown,
generating the final restart point and corresponding Results file
before System Coupling disconnects from participants.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Table 7: Help menu options
Option
Description
System Coupling User's Guide
Opens the System Coupling User's Guide.
Settings and Commands Reference
Opens the System Coupling Settings and Commands
Reference manual.
Participant Library
Opens the System Coupling 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.
About
Opens a dialog containing product copyright, version,
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.
Table 8: Setup context menu options
Branch
Option
Description
Adds a single participant to the coupled
analysis.
Add Participant
For more information, see Adding the
Participants (p. 59).
Available when two coupling
participants have been added to the
coupled analysis.
Setup
Add Coupling Interface
Adds a coupling interface to the coupled
analysis.
For more information, see Adding a
Coupling Interface (p. 61).
Activate Hidden
Features
Available when hidden feature controls
are not activated.
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
Branch
Option
Description
Activates hidden feature controls and
adds the Hidden Feature Control
branch to the tree view under Setup.
Hidden Feature Control
Remove
Deactivates hidden feature controls and
removes the Hidden Feature Control
branch from the Setup branch.
Adds a single coupling participant to
the coupled analysis.
Add
For more information, see Adding the
Participants (p. 59).
Coupling Participant
Parallel solve
setup
Opens the Parallel Partitioning dialog,
which allows you to configure
participant's parallel execution settings
for the coupled analysis.
For more information, see Applying
Partitioning to Coupling
Participants (p. 104).
Rename
In the tree view, changes the label
indicating the participant's name.
Remove
Removes the participant from the
analysis.
<ParticipantName>
Adds a coupling interface to the coupled
analysis.
Coupling Interface
Add
For more information, see Adding a
Coupling Interface (p. 61).
Adds a data transfer to the coupling
interface.
Add Data Transfer
For more information, see Adding a Data
Transfer (p. 63).
<CouplingInterfaceName>
Rename
In the tree view, changes the label
indicating the coupling interface's name.
Remove
Removes the coupling interface (and
any data transfers defined on it) from
the analysis.
Adds a data transfer to the coupling
interface.
Data Transfer
Add
For more information, see Adding a Data
Transfer (p. 63).
<DataTransferName>
52
Rename
In the tree view, changes the label
indicating the data transfer's name.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Using the System Coupling Command-Line Interface (CLI)
Branch
Option
Description
Remove
Removes the data transfer from the
interface.
Table 9: Solution context menu options
Branch
Option
Description
Enabled when the coupled analysis setup is
free of data model errors and the solution is
not currently executing.
Solve
Begins solving the coupled analysis.
For more information, see Starting the
Solution (p. 80).
Enabled when the solution is executing.
Interrupt solve
Interrupts the execution of the solution.
For more information, see Stopping a
Coupled Analysis (p. 87).
Solution
Enabled when the solution is executing.
Abort solve
Aborts the execution of the solution.
For more information, see Stopping a
Coupled Analysis (p. 87).
Enabled when the solution is completed if
EnSight-compatible results exist.
Open Results in
EnSight
Opens results for the current analysis in
ANSYS EnSight.
For more information, see Postprocessing
Coupling Results in ANSYS EnSight (p. 82).
Using the System Coupling Command-Line Interface (CLI)
For information on using the System Coupling command-line interface (CLI), see:
Starting the System Coupling CLI
Getting Help in the System Coupling CLI
Starting the System Coupling CLI
To start the System Coupling 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
2.
Execute the command for the platform you're using:
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.
Getting Help in the System Coupling CLI
You can get help from within the System Coupling CLI using any of the following methods:
Help on Python Usage
To obtain usage information from the Python interpreter's help utility, use the help command as
follows:
• To access interactive help, type: help()
• To get information on an object, type: help(<object>)
• To exit the help utility, type: quit
54
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Preparing for a Coupled Analysis
Help on System Coupling Command-Line Options
Before starting the System Coupling CLI, you can get information on the command-line options that
can be applied when System Coupling's execution script is run. To do so, you can use either the -h
or --help command-line option when running the execution script. For example:
>>> "%AWP_ROOT201%\SystemCoupling\bin\systemcoupling" --help
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 on System Coupling Commands
To obtain help on commands from within the System Coupling CLI, use the help(<command>).
For example:
>>> help(Initialize)
Help on function Initialize:
Initialize(**kwds)
Description :
Interactive command that initializes a coupled analysis.
This includes preparing the coupling service, establishing connections
between the coupling service and all participants,and writing
participant build information to the transcript.
Supported keyword arguments :
Essential arguments :
Return type is NoneType
Available commands are described in Commands in the System Coupling Settings and Commands
Reference.
Preparing for a Coupled Analysis
When preparing a coupled analysis to be run in one of System Coupling's user interfaces, you'll perform
the following steps:
Creating a Coupled Analysis Directory Structure
Completing Participant Setups
Additional Participant Setup Considerations
Generating Participant Files
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
Creating a Coupled Analysis Directory Structure
Create a directory structure where you'll run System Coupling and store the analysis files generated
and used by System Coupling and coupling participants.
Placement of the Directory Structure
Ensure that you create the coupled analysis directory structure outside of any Workbench project
directories. Even if a participant's setup is performed in Workbench, the coupled analysis is not
managed by Workbench. Everything related to the coupled analysis should be stored or executed in
a directory independent of Workbench processes.
Recommended Directory Structure
The recommended directory structure for a coupled analysis is as follows:
• Coupled analysis working directory
– Participant 1 working directory
– Participant 2 working directory
– Participant 3 working directory
The parts of the recommended directory structure are described below:
Coupled analysis working directory:
Also called "System Coupling's working directory" or the "co-simulation working directory."
Serves as the working directory for the coupled analysis and is System Coupling's run directory.
This is where System Coupling:
• Accesses System Coupling Participant (SCP) setup files
• Accesses Shutdown (scStop) files
• Automatically creates the SyC subdirectory for its own output files:
– Settings (Settings.h5) and Results (Results_*#.h5) files
– Log (scLog.scl) files
– Any additional diagnostic or results files that may be generated
– Automatically creates a Results subdirectory for its EnSight-compatible output files (p. 82).
Participant working directories:
For each participant, the coupled analysis working directory should contain a participant working
directory to store coupled analysis input and output files.
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.)
56
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Preparing for a Coupled Analysis
This is where a participant solver:
• Writes and accesses its solver input files (e.g., CAS, DAT, DEF, and FTSIM files)
• Directs its coupling-related output, such as participant logs and transcripts
• Directs its solver-specific output and results files
Note:
If you change the recommended directory structure, additional steps may be
needed to ensure that System Coupling and participants can find necessary files.
For example:
• 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.
Completing Participant Setups
Finish setting up the physics and coupling-specific settings for participants to be included in the
coupled analysis. For each participant, open the product and perform the following steps:
1. Complete the fluid, solid, or electromagnetic physics setup.
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 Considerations (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).
2. Configure coupling-specific settings to enable coupling.
• 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.
• For Mechanical, this involves creating a System Coupling Region.
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 Participants (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).
Additional Participant Setup Considerations
Depending on the type of coupled analysis being performed, additional physics setup steps may be
necessary. When applicable, consider:
Compatible material properties:
When using the same material(s) in multiple participants, take care to ensure that material common
properties (e.g., conductivity) are consistently defined. This consideration is often relevant in analyses
involving thermal data transfers and, in particular, should always be taken into account for thermal
analyses involving an electromagnetic participant.
For example, if heat rate and temperature values are to be transferred between an electromagnetic solver and a thermal solver, both models must be made of materials that allow for temperature-dependent properties (e.g., electrical conductivity and thermal conductivity, respectively).
Compatible topological properties:
For coupled analyses that will include data transfers between regions of different topologies, ensure
that the models have compatible circumferential extents and geometric alignment. For more information,
see Setting Geometry Transformations for Models with Different Orientations (p. 65).
Appropriate motion definitions:
• 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 participate in multiple reference frames during the co-simulation.
Generating Participant Files
Once participant physics and coupling setups are complete, generate the solver input file and, where
applicable, the System Coupling Participant (SCP) setup file for each participant. The directory to
which you generate these files becomes the participant's working directory for the coupled analysis.
58
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
Participant solver input files
After you've finished each participant's setup, generate the solver input file(s) to the participant's working
directory before exiting the participant application. Use the method noted in the participant's product
documentation.
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 Forte participants, there is no need to generate a System Coupling Participant
(.scp) setup file; all information required for coupling is contained in the Forte solver
(.ftsim) file. In most cases, documentation on participant setup files is applicable to
both file types.
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).
Creating a Coupled Analysis
To create a System Coupling analysis in either of its user interfaces, perform the following steps:
Adding the Participants
Adding a Coupling Interface
Adding a Data Transfer
Setting Geometry Transformations for Models with Different Orientations
Adding the Participants
Each coupled analysis must have at least two coupling participants. You can add participants to the
coupled analysis by specifying and loading their System Coupling Participant (SCP) setup files. When
participant definitions are loaded, the data model is populated with information from the setup files
— specifically, the Coupling Control and Output Control singletons, the Coupling Participant object
container, and the participant objects themselves.
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, participants 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.
For instructions on adding coupling participants in a given user interface, see:
Adding a Coupling Participant in the GUI
Adding a Coupling Participant in the CLI
Adding a Coupling Participant in the GUI
When using the System Coupling GUI, you must add coupling participants individually. For each
coupling participant, perform the following steps:
1.
In the Outline pane's tree view, right-click the Setup branch and select Add Participant.
The Open dialog opens.
2.
Navigate to the working directory that contains the participant file.
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).
3.
Select the file and click Open.
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.
Adding a Coupling Participant in the CLI
When using System Coupling's CLI, you can add one or more participants by running the LoadParticipants and/or the AddParticipant commands, as shown in the examples below:
LoadParticipants
To load multiple participant definitions, run the LoadParticipants command, setting the InputFiles argument to a list of the participants' setup files.
Example 9: Run LoadParticipants to add two participants
>>> LoadParticipants(InputFiles = ["mechanical.scp", "fluent.scp"])
60
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
Example 10: Run LoadParticipants to add one participant
>>> LoadParticipants(InputFiles = ["cfx.scp"])
AddParticipant
To add a single coupling participant, you can also run the AddParticipant command, setting the
InputFile argument to the participant's setup file.
Example 11: Run AddParticipant to add one participant
>>> AddParticipant(InputFile = ["fluent.scp"])
When the command is run, the CouplingParticipant object container is added to the data
model, with the CouplingParticipant-# object(s) defined underneath it.
Adding a Coupling Interface
Each coupled analysis must have at least once coupling interface. Coupling interfaces must be added
to the analysis individually. To add a coupling interface, you must specify the participant name and
participant region(s) to be included on each side of the coupling interface. When the interface is
created, the Coupling Interface object becomes available in the data model.
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).
For instructions on adding a coupling interface in a given user interface, see:
Adding a Coupling Interface in the GUI
Adding a Coupling Interface in the CLI
Adding a Coupling Interface in the GUI
To add a coupling interface in the System Coupling GUI, perform the following steps:
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.
2.
Under Coupling Interface #, expand Side.
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 participant.
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 dropdown menus for both One and Two.
The coupling participant object is now fully defined.
Adding a Coupling Interface in the CLI
In the System Coupling CLI, the AddInterface and AddInterfaceByDisplayNames commands
allow you to use internal and display object names, respectively, to specify the participants and regions
to be associated with each interface side.
Important:
The CreateInterfacesAndDataTransfers command has been deprecated and will
be removed in a future release. This command can still be used for volume-to-volume
transfers (with the exception of transfers between Maxwell-Mechanical couplings) and for
surface-to-surface, but for other transfers may not create all possible valid interfaces and
data transfers. Consider using the AddInterface command and the AddInterfaceByDisplayName commands instead.
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
>>> AddInterface(SideOneParticipantName = ["AEDT-1"],
SideOneRegionNames = ["Volume5"],
62
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Coupled Analysis
SideTwoParticipantName = ["MAPDL-2"],
SideTwoRegionNames = ["FVIN_1"])
Example 13: Run AddInterfaceByDisplayName to add an interface using participant and
region display names
>>> AddInterfaceByDisplayNames(SideOneParticipantName = ["Maxwell 2D Participant"],
SideOneRegionNames = ["Maxwell Surface Region"],
SideTwoParticipantName = ["Fluent 3D Participant"],
SideTwoRegionNames = ["Fluent Volume Region"])
When the command is run, the CouplingInterface object container is added to the data model,
with the CouplingInterface-<#> object defined underneath it.
Adding a Data Transfer
Each coupling interface must have at least one data transfer. Data transfers must be added to the
coupling interface(s) individually. When you add a data transfer, you must specify the interface on
which the transfer is to be added, the target side for the transfer, and the variables to be associated
with each side of the interface.
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).
For instructions on adding a data transfer in a given user interface, see:
Adding a Data Transfer in the GUI
Adding a Data Transfer in CLI
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:
• Quasi-Newton Stabilization Algorithm (p. 177)
• Ramping Algorithm (p. 173)
• Under-Relaxation Algorithm (p. 175)
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
For information on convergence criteria, see Evaluating Convergence of Data Transfers (p. 157).
Adding a Data Transfer in the GUI
To add a data transfer in the System Coupling GUI, perform the following steps:
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.
2.
Right-click the interface object and select Add Data Transfer.
The Data Transfer branch is added to the tree, with the Data Transfer <#> object defined underneath 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.
Adding a Data Transfer in CLI
To create a data transfer in the System Coupling CLI, run the AddDataTransfer or the AddDataTransferByDisplayNames command. These commands allow you to use internal and display
object names, respectively, to specify data transfer details: the interface, the target side of the transfer,
and variables to be associated with each side of the interface To create a two-way data transfer on
an interface, you must run the command twice, once for each direction.
64
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
The CreateInterfacesAndDataTransfers command has been deprecated and will
be removed in a future release. This command can still be used for volume-to-volume
transfers (with the exception of transfers between Maxwell-Mechanical couplings) and for
surface-to-surface, but for other transfers may not create all possible valid interfaces and
data transfers.
When CreateInterfacesAndDataTransfers is run, a warning is generated and the
recommended replacement commands for creating the interfaces and data transfers are
written to the Transcript. Consider using this information to update your scripts and recreate
existing interfaces and data transfers.
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
>>> AddDataTransfer(Interface = "Interface-1",
TargetSide = "Two",
SideOneVariable = "Loss",
SideTwoVariable = "HGEN")
Example 15: Run AddDataTransferByDisplayNames to add a data transfer using variable
display names
>>> AddDataTransferByDisplayNames(Interface = "Interface-1",
TargetSide = "Two",
SideOneVariable = "Heat Loss",
SideTwoVariable = "Heat Rate")
When the command is run, the DataTransfer object container is added to the data model, with
the DataTransfer-<#> object defined underneath it.
Setting Geometry Transformations for Models with Different Orientations
System Coupling supports the creation of interfaces and data transfers between source and target
models with different orientations.
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 position). 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
can be performed on multiple participant models in a single co-simulation. When a transformation
is defined for a participant model, it is applied to all the model's regions.
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 transformations 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.
Modifying Coupled Analysis Settings
You can modify a coupled analysis using following types of System Coupling settings:
Changing Data Model Settings
Enabling Expert Settings
Requesting Debug Output
Changing Data Model Settings
You can change coupled analysis settings either by using the fields in the System Coupling GUI or
by using commands in the CLI to interact directly with the data model. For instructions on changing
System Coupling's data model settings in either of its user interfaces, see:
Frequently Edited Data Model Settings
Changing Data Model Setting Values
Frequently Edited Data Model Settings
The following sections describe settings commonly used to modify a coupled analysis:
Coupling Control
Solution Control
Output Control
Coupling Interface
66
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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).
Currently, CoSimulation is the only available value.
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 Analysis 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 steadytransient 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 automatically, 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.
Accepts integer values greater than or equal to 1. Default value is 1.
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:
• The analysis duration has not been reached, and
• either the maximum number of coupling iterations has been reached or the coupling step has
converged.
The following settings are available:
Time Step Size
Available when the Duration Control / Option is set to Number of Steps or End Time. Defines
the time interval of the coupling steps.
68
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Accepts integer values 1 ≤ x ≤ Maximum Iterations. Default value is 1.
Maximum Iterations
Defines the maximum number of iterations per coupling step.
Accepts integer values 1 ≤ x ≤ 9999. Default value is 5.
Solution Control
Settings defined under the root-level Solution Control singleton control analysis-level solution
settings.
The following settings are available:
Allow Simultaneous Update
Specifies whether simultaneous solution of groups of independent participants is enabled.
Possible values:
• False: Simultaneous participant solutions are disabled. (default value)
• True: Simultaneous participant solutions are enabled.
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 participant 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:
• Shared Allocate Machines (default value)
• Shared Allocate Cores
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
• Distributed Allocate Machines
• Distributed Allocate Cores
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.
The following settings are available:
Option
Available only when all coupling participants support restarts.
Specifies when restart points are generated.
Possible values depend on they type of analysis being run and the coupling participants involved. For information on the conditions that determine this, see Results Files (Results_*#.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.
70
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
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.
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.
Accepts integer values greater than or equal to 1. Default value is 1.
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 (:).
The following Data Transfer settings are available:
Convergence Target
Specifies the RMS-based target value used when evaluating convergence of the specified quantity
within a coupling iteration.
Accepts decimal values 1e-15 < x ≤ 1.0. Default value is 1e-2.
For information on how this target is applied, see Evaluating Convergence of Data Transfers (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.
For more detailed information, see Ramping Algorithm (p. 173).
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 interface 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 underrelaxing them against the previous values.
Accepts decimal values 0.0 ≤ x ≤ 1.0. Default value is 1.0.
For more detailed information, see Under-Relaxation Algorithm (p. 175).
Stabilization
Singleton containing settings that control the application and behavior of Quasi-Newton stabilization
methods to the parent data transfer.
The following settings are available:
Option
Specifies whether Quasi-Newton stabilization is applied to the data transfer. Possible values:
• None: No stabilization method is applied to the data transfer. (default value)
• Quasi-Newton: The Quasi-Newton stabilization method is applied to the data transfers.
When the Stabilization / Option is set to Quasi-Newton, the following settings are also
available:
Maximum Retained Time Steps
Specifies the maximum number of time steps to be retained in the Quasi-Newton history.
72
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Modifying Coupled Analysis Settings
Accepts integer values greater than or equal to than 1. Default value is 1.
Note:
Setting Maximum Retained Time Steps to a value greater than 1 may
lead to faster convergence on some problems but may also reduce robustness on other problems.
Initial Relaxation Factor
Specifies the under-relaxation factor to be applied during the startup iteration (i.e., before
the Quasi-Newton algorithm starts modifying the data transfers).
Accepts real values 0.0 ≤ x ≤ 1.0. Default value is 0.01.
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:
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. Instead, you should use System Coupling's
GUI or CLI to edit setting values directly in the data model so the changes are captured
in the analysis Settings file.
Execution Control (singleton)
Singleton containing settings that control the execution of the participant.
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.
The following Execution Control settings are available:
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:
For coupled analyses executed via System Coupling in Workbench, this
option is replaced by the Externally Managed option.
• User Defined: System Coupling does not automatically find the executable based on participant 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 externally (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.
Accepts real values ≥ 0. Default value is 1.
74
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 arguments 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).
Default value is None.
Update Control
Settings defined under the Update Control singleton control the frequency with which the participant 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 Participant Update Control Settings in the System Coupling Beta Features documentation.
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.)
Accepts integer values greater than or equal to 1. Default value is 1.
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.
76
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 coordinate 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 coordinate 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.
Changing Data Model Setting Values
Data model settings can be changed either in the System Coupling GUI or by interacting with the
data model directly in the CLI.
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
Changing Data Model Setting Values in the GUI
To change the value of a data model setting in the GUI, perform the following steps:
1.
In the Outline, select the branch that contains the setting.
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.
78
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
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.
Changing Data Model Setting Values in the CLI
To change the value of a data model setting in the CLI, enter the setting's path in the CLI and use
an equal sign to set the new value, as shown in the example below:
Example 16: Change the value of the TimeStepSize setting
>>> DatamodelRoot().CouplingControl.AnalysisType.StepControl.TimeStepSize = '1.0 [s]'
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)).
Enabling Expert Settings
System Coupling's expert settings provide you with advanced controls for coupled analyses. Expert
settings must be enabled from the command-line.
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
>>> SetExpertSettings(Settings={'Source_InitValue_HeatTransferCoef': 2})
For details on available expert settings, see Expert Settings in the System Coupling Settings and Commands Reference guide.
Requesting Debug Output
You can request that System Coupling generates debug output by setting the following environment
variables:
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.
Running a Coupled Analysis
To run a coupled analysis, perform the following steps:
Starting the Solution
Monitoring Solution Progress
Note:
System Coupling does not support an interactive mode for participants during coupled
analysis runs.
Starting the Solution
When the solution is started, System Coupling connects with the coupling participants and begins
the coupled analysis. A successful solution runs straight through without stopping.
For instructions on starting the solution in a given user interface, see:
Starting the Solution in the GUI
Starting the Solution in the CLI
Starting the Solution in the GUI
To start the solution in the System Coupling GUI, in the Outline pane's tree view, right-click the
Solution branch and select Solve.
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:
80
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 information, 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).
Starting the Solution in the CLI
To start the solution in the CLI, run the Solve command:
Example 18: Start the coupled solution
>>> 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).
Monitoring Solution Progress
When there is activity in the coupled analysis, a Transcript containing coupling output is generated
and written to the GUI's Command Console tab or to the CLI. Solution output is written to the
Transcript after the analysis is started and when the PrintSetup or GetState command is issued
before the solve.
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 functionality. 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
Reviewing Coupled Analysis Output and Results
Once the solution has completed, you can review System Coupling's output and perform postprocessing
on the coupled analysis results. You can:
• review the Transcript/Log file and any supplemental diagnostic files you've requested;
• load individual participant results into their respective postprocessing applications;
• load System Coupling's results into ANSYS EnSight for visualization, animation, and postprocessing.
For more information, see:
Postprocessing Coupling Results in ANSYS EnSight
Postprocessing Coupling Results in ANSYS EnSight
System Coupling generates coupling output in the ANSYS EnSight Gold case file format, which makes
it possible to load results into EnSight for high-performance 3D postprocessing. For all coupled analysis runs, System Coupling automatically produces postprocessing files after each restart point and
at the end of the run. These files can be loaded into EnSight for interactive postprocessing, including
visualization and animation, of coupled analysis results.
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.
For more information, see:
Generation of EnSight-Formatted Output Files
Starting ANSYS EnSight
Reviewing Results Loaded in EnSight
Generation of EnSight-Formatted Output Files
System Coupling automatically generates EnSight-compatible output according to default settings.
For each coupled analysis run, it generates output files at the same frequency for restart results
(i.e., via the Output Control / Option setting). Thus, it generates a result file corresponding to each
restart point created (i.e., at the end of each coupling step completed), and then a final result file
at the end of the run. System Coupling writes these files to a Results subdirectory, a folder created
for this purpose inside the SyC directory.
System Coupling generates the following EnSight-formatted output files:
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.
82
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 completion 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.
Geometry data files:
Geometry data files have a .geo extension. Geometry results are written for each restart point and
at the end of the run.
Variable data files:
Variable data files have a .dat extension. For each variable, coupling step results are written for each
restart point and at the end of the run.
Multi-step data files:
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.
• Data model settings to control System Coupling's generation of EnSight-compatible output
are available as beta functionality. For more information, see Settings for Generating ANSYS
EnSight-Compatible Postprocessing Output in the System Coupling Beta Features documentation.
• 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 postprocess 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
Starting ANSYS EnSight
You can start EnSight using either the System Coupling GUI or the command line for your operating
system.
Starting EnSight in the GUI (recommended):
From the System Coupling GUI's File menu, select Open Results in EnSight.
Starting EnSight from the Command Line:
On the machine where the EnSight client and server have been installed, perform the following steps:
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
> "%AWP_ROOT201%\CEI\bin\ensight.bat" -sos Results.sos
• Linux
$ "$AWP_ROOT201/CEI/bin/ensight” -sos Results.sos
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.
Reviewing Results Loaded in EnSight
When coupled analysis results are loaded into EnSight, results are populated to the user interface
as follows:
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.
84
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
For each coupling region, columns show the following information:
• 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).
• Color: Color used for the region in the graphics window.
• Color by: Variable the part is colored by in the graphics window.
You can work with regions in the Parts pane as follows:
• 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 geometry, you must edit the corresponding parts settings as follows:
1. Double-click the part.
The Edit Attributes for Tagged Model Part dialog opens.
2. Select the Advanced check box.
3. Under Displacement, set Displace by to the vector variable to be used for displacement.
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 categories, 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:
• Mapping location (elements, nodes)
• Data model details (data transfer, coupling interface, interface side)
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
• Mapping type (conservative, profile-preserving)
• Data location (face, node)
• Conservative topology (per unit area, per unit volume)
These variables must be activated (loaded into memory) either explicitly by selection of the corresponding Activated check box, or by being called by an operation that requires it.
Note:
To facilitate postprocessing, System Coupling provides a total-displacement variable
which accumulates calculations for all incremental displacement variables defined for
the Coupling Interface object. For analyses with one or more transfers of Incremental
Displacement quantities, a single total-displacement variable will hold the accumulated
totals of all incremental displacement variables.
In the EnSight-formatted postprocessing file, the total-displacement variable output is
the sum of the displacement since the last mesh import. For restarted cases, its shows
the displacement from the restart point used to restart the run — not from the beginning
of the initial run.
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.
Advanced System Coupling Workflows
For information on advanced workflows that can used when running System Coupling in one of its user
interfaces, see:
Saving a Coupled Analysis
Stopping a Coupled Analysis
Restarting a Coupled Analysis
Reconnecting the GUI to a Running Coupled Solution
Using Interactive Solve Commands
Simultaneous Execution of Participant Solutions
Using Parallel Processing Capabilities
Running a Workbench Setup in a User Interface
Saving a Coupled Analysis
System Coupling automatically saves the state of a coupled analysis during its creation and execution.
When a coupled analysis has run and completed a coupling step or iteration, its state is automatically
written to HDF5-formatted files (a Settings file and one or more Results files) that contain information
necessary to restart the analysis. Files corresponding to the end of the last completed coupling step
or iteration are saved, by default, to the SyC subdirectory in System Coupling's working directory.
86
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
Saving the coupled analysis state in the GUI:
• Select the File > Save menu option.
• To change the output location, select the intended output directory in the Save dialog.
Saving the coupled analysis state in the CLI:
• Run the Save command.
• 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).
Stopping a Coupled Analysis
For instructions on stopping a coupled analysis in a given user interface, see:
Stopping a Coupled Analysis in the GUI
Stopping a Coupled Analysis in the CLI
Stopping a Coupled Analysis in the GUI
When using the System Coupling GUI, right-click the Solution branch of the Outline pane's tree
view and select one of the following menu options:
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 participants 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.
Stopping a Coupled Analysis in the CLI
When using the System Coupling CLI, you can stop a coupled analysis using the methods described
below:
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
Run the Shutdown command.
When using an interactive solve process described in Using Interactive Solve Commands (p. 95), you
can use the Shutdown command to stop down the analysis at any point at which the solution is paused.
This produces a clean shutdown, generating a restart point and writing the corresponding Results file
before System Coupling is disconnected.
Use a Shutdown file.
The Shutdown file (p. 194) is a text file named scStop that indicates whether the coupling run should
be interrupted or aborted. When System Coupling finds the file in its working directory, it shuts down
as soon as possible according to the contents of the file and signals participants that they should shut
down, as well.
• 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.
Restarting a Coupled Analysis
You can restart a completed or interrupted coupled analysis from either the final result or an intermediate result. Based on the restart point selected, System Coupling automatically finds all the necessary
restart files (both for itself and for all participants) and then restarts the run from the designated point
in the analysis.
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.
88
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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-relaxation is applied during this iteration.
• AEDT participants do not support restarts from intermediate results.
• Mechanical participants do not support restarts for steady-state thermal and transient thermal
analyses.
For more information, see:
Creation of Restart Points
Restarting a Coupled Analysis in the GUI
Restarting a Coupled Analysis in the CLI
Creation of Restart Points
Restarts of a coupled analysis require corresponding restart points in System Coupling and in each
of the coupling participants. Restart points are generated at the end of a coupling step, and can
be created by the following methods:
• When requested by:
– Output Control data model settings
– the CreateRestartPoint command
• When the analysis is shut down cleanly because:
– the solution completed,
– the solution was saved,
– the analysis was stopped by:
– the Shutdown command
– a Shutdown (p. 194) file
– the GUI's Solution branch context options (p. 53)
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 generated. 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).
Restarting a Coupled Analysis in the GUI
When restarting a coupled analysis in the System Coupling GUI, you can restart from either the
final result or an intermediate result. The steps vary according to whether the analysis is being restarted by opening a new instance of the GUI or by specifying restart details in an existing instance
of the GUI. For more information, see:
Restarting a Coupled Analysis in a New GUI (Final Result)
Restarting a Coupled Analysis in an Existing GUI (Final or Intermediate Result)
Restarting a Coupled Analysis in a New GUI (Final Result)
When you start the System Coupling GUI in a working directory in which the state of a previous
coupling run has been saved (i.e., Results (p. 207) files have been written to the SyC subdirectory),
System Coupling automatically loads that analysis in its most recent state. Based on the state of
the analysis, the restart may occur from either the final or an intermediate result.
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.
5.
Right-click the Solution branch and select Solve.
System Coupling automatically starts all participants from the selected coupling step or iteration
and continues the solution with the next step or iteration.
90
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Restarting a Coupled Analysis in an Existing GUI (Final or Intermediate Result)
In an instance of the System Coupling GUI that is already open, you can restart an analysis from
either a final or an intermediate result. To do so, perform the following steps:
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 information, 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 iteration 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.
5.
Right-click the Solution branch and select Solve.
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 Command Console tab. For more information, see Using Interactive Solve Commands (p. 95).
Restarting a Coupled Analysis in the CLI
When restarting a coupled analysis in the System Coupling CLI, the steps vary according to
whether the analysis is being restarted from final or an intermediate result. For more information,
see:
Restarting from the Final Result in the CLI
Restarting from an Intermediate Result in the CLI
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
Restarting from the Final Result in the CLI
To restart a coupled analysis from the final result in the System Coupling CLI, perform the following
steps:
1.
Run the Open command without arguments.
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 iteration and continues the solution with the next step or iteration.
Restarting from an Intermediate Result in the CLI
To restart a coupled analysis from an intermediate result in the System Coupling CLI:
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 information (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.
92
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
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.
Reconnecting the GUI to a Running Coupled Solution
System Coupling provides you with the ability to connect the System Coupling GUI to a running
coupled analysis — functionality that can be especially useful when a solution is expected to have a
long runtime. This feature allows you to start the analysis, disengage from it, and then come back
later to connect/reconnect to the running instance of System Coupling and check on the simulation's
progress.
For more information, see:
Prerequisites
Disconnecting from the Running Solution
Reconnecting to the Running Solution
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 running in GUI Server mode.
System Coupling must be running in GUI Server mode, a GUI-only mode in which System Coupling is
launched as a server and waits for an instance of the System Coupling GUI to connect to it.
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 connect/reconnect an instance of the GUI to the corresponding coupling solution while it is still
progressing.
System Coupling's working directory is visible to the GUI.
The System Coupling instance may be running either locally or on a remote host. If running on a remote
host, then its working directory must be visible/accessible to the GUI attempting to connect.
System Coupling has no active GUI connections.
System Coupling must have no active connection with an existing instance of the System Coupling
GUI that is running in the working directory. The presence of a GUI Server (sycGui.srv) file (p. 196)
in the working directory indicates that another connection already exists.
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
System Coupling is not in the process of shutting down.
If System Coupling is in the process of shutting down because an Interrupt or Abort operation has
been requested, then attempts to reconnect to the solution may place the analysis in an invalid state.
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.
Disconnecting from the Running Solution
To reconnect an instance of the System Coupling GUI to a coupled analysis that is in progress, the
solution must be actively running with System Coupling in GUI Server mode, and it must be disconnected from any GUI. To do this, use one of the following methods:
Disconnecting from the Solution in the GUI
Disconnecting from the Solution from the Command Line
Disconnecting from the Solution in the GUI
To start and disconnect from the solution using the System Coupling GUI, perform the following
steps:
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.
2.
Set up the analysis and start its solution.
3.
Disconnect the GUI from the running analysis, as follows:
a.
From the GUI's File menu, select Exit.
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.
Disconnecting from the Solution from the Command Line
To start and disconnect from the solution using the command line, perform the following steps:
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
94
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
> "%AWP_ROOT195%\SystemCoupling\bin\systemcoupling" -R <scriptname> --guiserver
• Linux
$ "$AWP_ROOT201/SystemCoupling/bin/systemcoupling" -R <scriptname> --guiserver
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.
Reconnecting to the Running Solution
To connect/reconnect to a solution in progress, open the System Coupling GUI in the working
directory for the coupled analysis.
• 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 progress.
• 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:
– the GUI is exited when no coupling processes are running, or
– the solution completes after the GUI has disconnected.
• An Interrupt or Abort operation has been requested for the analysis.
For details on issues you may encounter when using System Coupling's reconnect capabilities, see
Known Issues and Limitations (p. 31).
Using Interactive Solve Commands
System Coupling provides a series of advanced commands that enable an interactive solve process
(as opposed to solving straight through, as when a coupling run is initiated by the Solve command).
These commands can be issued both from the System Coupling CLI and the System Coupling GUI's
Command Console.
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:
The StartParticipants command will be deprecated in a future release. Consider
adopting workflows where participants are started by another method, such as the
Initialize, Step, or Solve commands.
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
96
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 command 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 information 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.
Simultaneous Execution of Participant Solutions
System Coupling allows for groups of independent participants to execute their solutions simultaneously. If enabled, groups of participants which have no direct or indirect dependence on one another
within a coupling iteration are solved simultaneously; System Coupling groups only those participants
for which an iteration of the defined data transfer will introduce no dependence on any of the other
participants in the group.
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.
For more information, see:
System Coupling's Participant Grouping Process
Enabling Simultaneous Participant Solutions
Execution of Simultaneous Participant Solutions
Simultaneous Participant Solution Examples
System Coupling's Participant Grouping Process
For all coupled analyses, System Coupling performs an initial ordering of participants, as described
in Participant Solution Sequencing (p. 38). When simultaneous participant solutions are enabled,
additional resequencing is performed — first, when System Coupling creates groups of independent
participants, and then, when it consolidates those groups (where possible) by combining them.
For details on System Coupling's participant grouping process, see:
Creation of Participant Groups
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
Consolidation of Participant Groups
Creation of Participant Groups
Using the ordered participant list obtained via the process described in Participant Solution Sequencing (p. 38), System Coupling groups the ordered participants based on their interdependencies with one another, as follows:
1.
System Coupling creates the group, as follows:
a.
In the modified ordered participant list, identify the participants that have no dependencies
with other participants on the list.
b.
Create the participant group, using the same criteria as previously:
• 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 participant on the list as its only member.
2.
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.
System Coupling repeats step 1 until no ungrouped participants remain on the individual participant
list.
Consolidation of Participant Groups
Once an ordered list of participant groups has been created (as described in Creation of Participant
Groups (p. 98)), System Coupling further consolidates the list by combining groups together,
where possible. It combines the ordered groups (essentially grouping the groups) according to
their interdependencies with one another, as follows:
1.
2.
98
System coupling creates the first consolidated group, as follows:
a.
In the ordered group list, identify the groups that have dependencies only on groups that
come before them on the list.
b.
Combine the identified groups into a consolidated group.
c.
Add the consolidated group to the ordered list, determining its position by applying the participant-ordering process (described in Participant Solution Sequencing (p. 38)) to the groups.
d.
Remove the combined groups from the ordered list.
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
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Enabling Simultaneous Participant Solutions
For information on enabling simultaneous participant solutions in a given user interface, see:
Enable Simultaneous Participant Solutions in the GUI
Enable Simultaneous Participant Solutions in the CLI
Enable Simultaneous Participant Solutions in the GUI
To enable simultaneous participant solutions in the GUI:
•
In the Outline tree view, select the Solution Control branch.
Solution control settings are shown in the Properties pane.
Set Allow Simultaneous Update to True.
Simultaneous participant updates are enabled.
Enable Simultaneous Participant Solutions in the CLI
To enable simultaneous participant solutions in the CLI, change the SolutionControl
singleton's AllowSimultaneousUpdate setting to True, as shown below:
>>> DatamodelRoot().SolutionControl.AllowSimultaneousUpdate = True
Simultaneous participant updates are enabled.
Execution of Simultaneous Participant Solutions
Simultaneous solutions are executed as distributed parallel runs, allocated across available compute
resources by System Coupling's participant partitioning algorithms. When simultaneous solves are
enabled, the behavior of System Coupling's partitioning operations is modified to prevent coreusage conflicts.
When a non-default algorithm is used, the corresponding partitioning functionality is unchanged;
whether solving individual participants or groups of simultaneously solved participants, the Distributed Allocate Cores, Distributed Allocate Machines, and Shared Allocate Cores algorithms behave
as described in Parallel Processing for Coupling Participants (p. 103).
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.
Simultaneous Participant Solution Examples
This section provides examples of coupling participant groupings for simultaneous solutions. Each
example includes:
• Details of the ordering and grouping processes
• A diagram depicting dependencies and the final participant groupings
Example 19: Nine- participants with multiple dependent participant groups
In this example, there are nine participants. None are sending Incremental Displacement.
Stage
Resulting Ordering/Grouping
Stage 1: Participant Ordering
[P-1, P-2, P-3, P-4, P-5, P-6, P-7, P-8, P-9]
Stage 2: Participant Grouping
[[P-3, P-4, P-5, P-8], [P-2, P-6], [P-1, P-7, P-9]]
Stage 3: Group Consolidation
[[P-3, P-4, P-5, P-8], [P-2, P-6], [P-1, P-7, P-9]]
Example 20: Four-participants with multiple dependent participant groups
In this example, there are four participants. None are sending Incremental Displacement.
Stage
Resulting Ordering/Grouping
Stage 1: Participant Ordering
[P-1, P-2, P-3, P-4]
Stage 2: Participant Grouping
[[P-1], [P-2], [P-3], [P-4]]
Stage 3: Group Consolidation
[[P-1], [P-2, P-4], [P-3]]
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.
100
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Stage
Resulting Ordering/Grouping
Stage 1: Participant Ordering
[MAPDL-2, FLUENT-1, AEDT-3]
Stage 2: Participant Grouping
[[MAPDL-2], [FLUENT-1], [AEDT-3]]
Stage 3: Group Consolidation
[[MAPDL-2], [FLUENT-1], [AEDT-3]]
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.
Stage
Resulting Ordering/Grouping
Stage 1: Participant Ordering
[MAPDL-1, AEDT-2, FLUENT-3]
Stage 2: Participant Grouping
[[MAPDL-1], [AEDT-2], [FLUENT-3]]
Stage 3: Group Consolidation
[[MAPDL-1, AEDT-2], [FLUENT-3]]
Using Parallel Processing Capabilities
System Coupling provides you with the ability to execute a coupled analysis using High-Performance
Computing (HPC) resources in parallel. You can run the analysis on a single machine or distributed
on two or more machines. Distributed runs are executed directly or indirectly with a queuing system,
with Linux support for LSF, PBS Pro, and UGE.
Note:
Support for the SLURM job scheduler is available as beta functionality.
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
Figure 4: Communication between System Coupling and coupling participants
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.
For more information, see:
Recommended Workflow for Parallel Execution
Parallel Processing for Coupling Participants
Parallel Options for System Coupling
Parallel Options for Participant Products
Recommended Workflow for Parallel Execution
102
1.
Set up your analysis, as described in Preparing for a Coupled Analysis (p. 55).
2.
To use parallel-specific command-line options when starting System Coupling, see Parallel Options
for System Coupling (p. 117).
3.
Set up your coupled analysis.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
4.
Edit your data model settings.
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).
7.
Run the solution.
Parallel Processing for Coupling Participants
Parallel processing for co-simulation tends to be more involved than it is for single-solver simulations.
A co-simulation involves, at minimum, three participants (i.e., System Coupling and at least two
coupling participants). Figure 5: Co-simulation with four participants (p. 103) shows a co-simulation
with four participants, each with different number of compute processes per participant. System
Coupling partitions the simulation work across participants, and that work is then allocated across
available computing resources.
Figure 5: Co-simulation with four participants
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 resources 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.
For more information, see:
Applying Partitioning to Coupling Participants
Machine List and Core Counts
Resource Allocation Fractions
Participant Partitioning Algorithms
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
Participant Partitioning Examples
Applying Partitioning to Coupling Participants
Partitioning coupling participants allows you to control how they're distributed across compute
resources, specifying the partitioning algorithm to be applied, how available resources will be
allocated, and what machines will be available for the parallel execution.
To apply partitioning to coupling participants, your coupled analysis must meet the following
prerequisites:
• System Coupling has been started with one or more cores.
• At least one participant is defined.
• No participants are already started.
Note:
When simultaneous execution of participant solutions is enabled, the explicit application
of partitioning is changed as described in Participant Partitioning Algorithms (p. 107).
For more information, see:
Applying Participant Partitioning in the GUI
Applying Participant Partitioning in the CLI
Applying Participant Partitioning in the GUI
When using the System Coupling GUI, apply partitioning to coupling participants as follows:
1.
Specify the partitioning algorithm.
a.
In the Outline pane under Setup, select Solution Control.
Solution control settings are shown under Properties.
b.
Set Partition Algorithm to the algorithm to be applied to the analysis.
For information on available algorithms, see Participant Partitioning Algorithms (p. 107).
2.
Specify the resource allocation fractions for each participant.
a.
In the Outline tree under Setup, right-click Coupling Participant and select Parallel solve
setup.
The Parallel Partitioning dialog opens.
b.
Under Participant Weights, specify the resource weighting for each coupling participant in
decimal format.
For more information, see Resource Allocation Fractions (p. 106).
3.
104
Specify the available machines and cores.
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Applying Participant Partitioning in the CLI
When using the System Coupling CLI, apply partitioning to coupling participants by editing the
data model, as follows:
1.
Specify the number of cores to be used by the local machine.
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.
> "%AWP_ROOT201%\SystemCoupling\bin\systemcoupling" -t4 -R run.py
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.
2.
Specify the partitioning algorithm.
To specify the partitioning algorithm to be applied to the coupled analysis, edit the SolutionControl \ PartitioningAlgorithm setting in the data model.
>>> DatamodelRoot().SolutionControl.PartitioningAlgorithm = "DistributedAllocateCores"
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 algorithm.
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.
3.
Specify the resource allocation fractions for each participant.
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
For more information, see Resource Allocation Fractions (p. 106).
Note:
The PartitionParticipants command is available as an alternative method of
applying partitioning to coupling participants. For more information, see PartitionParticipants in the System Coupling Settings and Commands Reference manual.
Machine List and Core Counts
By default, coupling participants run serially on one core (-t1). In many cases, you won't need
to specify the machine list and core counts for a parallel run because these details are often
handled by a load manager or job scheduler. However, if you do want to explicitly specify this
information, you can use one of the following methods:
When starting System Coupling (recommended):
Use the command-line options described in the Coupling Participant Parallel Options section of the
System Coupling Settings and Commands Reference manual.
When running the System Coupling GUI:
In the Parallel solve setup dialog (accessed by right-clicking Outline / Setup / Coupling Participant),
add details under Machine Names and Core Counts.
When running the System Coupling CLI:
Run the PartitionParticipants command.
Resource Allocation Fractions
When applying partitioning to coupling participants, you can use a resource allocation parameter
specify the core count or fraction of compute resources to be allocated to each participant. With
regard to this parameter, partitioning behavior is as follows:
If this parameter is omitted and fractions are not provided:
Default values are used, as follows:
• For the default Shared Allocate Machines algorithm, each participant will run on all the allocated
cores.
106
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
If this parameter is used and fractions are provided:
There are two different possibilities:
• All the fractions are between 0.0 and 1.0.
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.
• At least one of the fractions is greater than 1.0.
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 threefifths of them.
Participant Partitioning Algorithms
System Coupling has four different participant-partitioning algorithms, which provides for different
permutations of parallel execution and resource allocation. When selecting a participant-partitioning algorithm, you specify the following information:
• 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 distributed 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.
Table 10: Shared Parallel vs. Distributed Parallel execution modes
Characteristics
Shared Parallel
Distributed Parallel
Resource
Sharing
Discrete participants share
allocated machine resources.
Discrete participants are executed on
non-overlapping machines so that they
do not share machine resources.
Memory
Requirements
Ideally, the number of
processes run on the
machine should not exceed
the total core count on a
machine.
Useful when the co-simulation total
memory requirements are greater than
what is available for a shared simulation
(i.e., if the required memory to run in
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
Characteristics
Shared Parallel
Distributed Parallel
shared mode exceeds a machine's total
memory).
Resource
Requirements
Multiple machines may be
utilized, and the total
number of required
machines is dictated by the
participant requiring the
most resources.
Depending on how the cores are
allocated, participants may end up
sharing resources on some machines.
The number of machines with shared
resources may be as high as the total
number of participants.
For more information, see:
Choosing a Partitioning Algorithm
Partitioning Algorithm Pros and Cons
Choosing a Partitioning Algorithm
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.
The following algorithms are available:
• 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 algorithm 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.
Partitioning Algorithm Pros and Cons
The tables below summarize the advantages and disadvantages generally associated with each
of System Coupling's participant partitioning algorithms.
108
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Shared Allocate Machines
Pro:
Allows for full utilization of all cores (no idle cores)
Con:
Machines must have enough memory for all participants (highest memory
demand)
Shared Allocate Cores
Pro:
Cores are more evenly loaded – a better option for low memory machines
Cores remain idle when individual participants are executing
Cons:
Participants must be tolerant of distributed memory execution
The last participant may run on more machines if high core count machines are
consumed by the other participants
Distributed Allocate Machines
Pros:
Participants have complete access to all machine resources
Useful if solving with participants that have high memory use
Shared memory parallel gets higher utilization (better scaling for a participant)
Cannot control how many cores will be assigned to each participant
Cons:
Last participant may get fewer cores
Only useful if requesting that resources are allocated exclusively so you know how
many cores on each machine you will be getting
Distributed Allocate Cores
Pros: Participants have complete access to all machine resources
Useful if solving with participants that have high memory use
Useful if you are requesting that resources are allocated exclusively
Shared memory parallel gets higher utilization (better scaling for a participant)
Cores remain idle when individual participants are executing
You may get overlap (sharing) but the maximum is equal to the total participant
Cons: count
The last participant may run on more machines if high core count machines are
consumed by the other participants
Participant Partitioning Examples
This section provides a description and usage example for each of System Coupling's participant
partitioning algorithms.
Shared Parallel: Allocate Machines
Shared Parallel: Allocate Cores
Distributed Parallel: Allocate Cores
Distributed Parallel: Allocate Machines
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.
• System Coupling runs on the first machine on a single core.
• 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:
Figure 6: Machine List specified using the --cnf command-line option
> "%AWP_ROOT201%\SystemCoupling\bin\systemcoupling" --cnf="host0:12,host1:12,host2:12,host3:7,
host4:6,host5:3,host6:3,host7:1,host8:1" -R run.py
110
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Figure 7: Machine List specified using the System Coupling GUI
Figure 8: Machine List specified using the PartitionParticipants command
>>> PartitionParticipants(MachineList = [
{'machine-name' : 'host1', 'core-count' :
{'machine-name' : 'host2', 'core-count' :
{'machine-name' : 'host3', 'core-count' :
{'machine-name' : 'host4', 'core-count' :
{'machine-name' : 'host5', 'core-count' :
{'machine-name' : 'host6', 'core-count' :
{'machine-name' : 'host7', 'core-count' :
{'machine-name' : 'host8', 'core-count' :
{'machine-name' : 'host9', 'core-count' :
12},
12},
12},
7},
6},
3},
3},
1},
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.
Shared Parallel: Allocate Machines
Participants share both machines and cores.
In the examples below, Participant-1, Participant-2, and Participant-3 have been allotted
fractions of 1, 1, and 1/5, respectively.
112
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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()
>>>
>>>
>>>
>>>
dm.SolutionControl.PartitioningAlgorithm = "SharedAllocateMachines"
dm.CouplingParticipant['PARTICIPANT-1'].ExecutionControl.ParallelFraction = 1.0
dm.CouplingParticipant['PARTICIPANT-2'].ExecutionControl.ParallelFraction = 1.0
dm.CouplingParticipant['PARTICIPANT-3'].ExecutionControl.ParallelFraction = 1.0/5.0
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 25: PartitionParticipants setup for the SharedAllocateMachines
algorithm with machines allocated by fractions
>>> PartitionParticipants(AlgorithmName = "SharedAllocateMachines",
NamesAndFractions = [('PARTICIPANT-1', 1.0),
('PARTICIPANT-2', 1.0),
('PARTICIPANT-3', 1.0/5.0)])
Example 26: Resource allocation resulting from the Shared Allocate Machines examples
Shared Parallel: Allocate Cores
Participants share machines but not cores.
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
>>> DatamodelRoot().SolutionControl.PartitioningAlgorithm = "SharedAllocateCores"
Example 28: PartitionParticipants setup for the SharedAllocateCores algorithm
with even allocation of cores
>>> PartitionParticipants(AlgorithmName = 'SharedAllocateCores')
114
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Figure 9: Resource allocation resulting from the Shared Allocate Cores examples
Distributed Parallel: Allocate Cores
Participants minimally share cores and machines.
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
>>> DatamodelRoot().SolutionControl.PartitioningAlgorithm = "DistributedAllocateCores"
Example 30: PartitionParticipants setup for the DistributedAllocateCores
algorithm with even allocation of cores
>>> PartitionParticipants(AlgorithmName = 'DistributedAllocateCores')
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
Distributed Parallel: Allocate Machines
Participants never share cores or machines.
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
>>> DatamodelRoot().SolutionControl.PartitioningAlgorithm = "DistributedAllocateMachines"
Example 33: PartitionParticipants setup for the DistributedAllocateMachines algorithm
with even allocation of cores
>>> PartitionParticipants(AlgorithmName = 'DistributedAllocateMachines')
116
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Example 34: Resource allocation resulting from the Distributed Allocate Machines examples
Parallel Options for System Coupling
When running in parallel, System Coupling always runs on two cores. For information on parallel
command-line options, see System Coupling Parallel Options in the System Coupling Settings and
Commands Reference manual.
If you also plan to use parallel processing for the coupling participants (p. 103), then you may wish
to review Coupling Participant Parallel Options.
Parallel Options for Participant Products
The System Coupling (SCP) setup file does not include parallel processing information. To run an
individual coupling participant product in parallel execution mode, you must introduce solverspecific parallel details via the Additional Arguments data model setting.
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 Participants (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.
For instructions on adding solver-specific parallel arguments in a given interface, see:
Adding Solver-Specific Parallel Arguments in the GUI
Adding Solver-Specific Parallel Arguments in the CLI
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
Adding Solver-Specific Parallel Arguments in the GUI
When using the System Coupling GUI, specify solver-specific parallel arguments by adding them
to the Additional Arguments setting, as follows:
1.
In the Outline pane's tree view under Coupling Participant, locate and expand the branch for the
participant object (<Participant>).
2.
Under the participant object, click Execution Control.
The participant's execution controls are shown in the Properties pane.
3.
Enter the solver-specific arguments into the Additional Arguments field.
Adding Solver-Specific Parallel Arguments in the CLI
When using the System Coupling CLI, specify solver-specific parallel arguments by adding them to
the AdditionalArguments setting in the participant's execution controls, as shown in the example below:
Example 35: Adding CFX parallel arguments on Windows
>>> DatamodelRoot().CouplingParticipant['FLUENT-2'].ExecutionControl.AdditionalArguments
= cfx5solve -def model.def -par-dist 'hosta,hostb*2,hostc*4'
Running a Workbench Setup in a User Interface
You can set up a coupled analysis in Workbench (as described in Setting Up a Coupled Analysis in
Workbench for a User-Interface Run (p. 152)) and then run it in either of System Coupling's user interfaces. The execution process is similar to the one used for an analysis set up in the GUI or CLI, except
that you'll:
• 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
118
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Advanced System Coupling Workflows
Running a Workbench Setup in the GUI
To run your Workbench setup in the GUI:
1.
Start the System Coupling GUI using one of the methods described in Starting the System Coupling
GUI (p. 44).
2.
Import the SCI file:
a.
From the File menu, select Load SCI file.
The Select SCI file dialog opens.
b.
Navigate to and select the SCI file to be imported.
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.
Execution control settings are shown in the Properties pane.
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 participant 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.
This file should be inside the participant's working directory.
4.
Right-click the Solution branch and select Solve.
Note:
From this point, the steps are the same as for a coupled analysis set up in a user interface.
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 ImportSystemCouplingInputFile 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
Running a Workbench Setup in the CLI
To run your Workbench setup in the CLI:
1.
Start System Coupling as described in Starting the System Coupling CLI (p. 53).
2.
Import the SCI file by running the ImportSystemCouplingInputFile command.
This populates the Workbench setup to System Coupling's data model.
3.
To provide information not included in the SCI file, edit each participant's ExecutionControl settings
in the data model:
• Set WorkingDirectory to the participant's coupling working directory.
• Set InitialInput to the name of the participant's solver input file.
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 interface.
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 ImportSystemCouplingInputFile command.
120
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
The following topics are addressed in this section:
• 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.
Overview of System Coupling in Workbench
This section provides a high-level overview of System Coupling in Workbench, describing the capabilities
supported by the System Coupling component system.
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 Workbench (p. 122).
The following topics are addressed:
• 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
Supported Coupling Participants for System Coupling in Workbench
System Coupling participants are systems that send and/or receive data in a coupled analysis. Supported
participant systems for System Coupling in Workbench include:
CFX
• Fluid Flow (CFX) analysis system
• CFX component system
For information on using System Coupling with a CFX system, see the following sections in
the CFX-Solver Modeling Guide:
• Coupling CFX to an External Solver: System Coupling Simulations
• Restarting CFX Analyses as Part of System Coupling
Fluent
• Fluid Flow (Fluent) analysis system
• Fluent component system
For information on using System Coupling with a Fluent system, see the following sections
in the Fluent User's Guide:
• Performing System Coupling Simulations Using Fluent
• Restarting Fluent Analyses as Part of System Couplings
Mechanical
• Static Structural analysis system
• Transient Structural analysis system
• Transient Thermal analysis system
• Steady-State Thermal analysis system
• Thermal Electric analysis system
For information on using System Coupling with a Mechanical system, see the following sections
in the Mechanical User's Guide:
• System Coupling
• Restarting Structural Mechanical Analyses as Part of System Coupling
External Data
• External Data component system
For information on using System Coupling with an External Data system, see the following
section in the Workbench User's Guide:
122
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Overview of System Coupling in Workbench
• External Data
Note:
The following limitations are placed on the participants of a coupled analysis:
• 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.
• Fluent can be connected with any of the other supported participants.
• Coupled analyses are not supported for External Data participant systems that have nonASCII characters in the following values:
– Display names for regions or variables
– 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)
Data Transfers for System Coupling in Workbench
A data transfer is the transfer of a single quantity type in one direction between source and target
regions of two participant meshes. For System Coupling in Workbench, each data transfer is defined
by a variety of user interface settings (p. 134) such as Source, Target, and Data Transfer Control.
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.
• Thermal data can be transferred:
– between Fluent and Mechanical directly through System Coupling,
– between CFX and Mechanical directly through System Coupling, and
– through the coupling of an External Data component system.
• 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 twoway 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.
Steps of a Coupled Analysis in Workbench
To create and run a coupled analysis, perform the following steps:
1. Create the analysis on the Project Schematic. (p. 126)
a. Add participant systems to the Project Schematic.
b. Add the System Coupling system to the Project Schematic.
2. Set up the physics for each participant system. (p. 126)
a. Configure the participant settings that enable a coupled analysis.
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.
3. Connect the systems. (p. 127)
4. Set up the System Coupling system.
a. Modify settings needed to complete the coupled analysis. (p. 129)
b. Optionally, enable expert settings (p. 138).
5. Run the analysis. (p. 140)
a. Start the solution. (p. 140)
b. Monitor the solution progress. (p. 141)
6. Optionally, stop and restart the analysis..
a. Stop the analysis. (p. 148)
b. Modify the analysis as needed. (p. 129)
c. Restart the analysis. (p. 149)
7. Review analysis output.
a. Review System Coupling's output. (p. 195)
b. Review the participant results.
System Coupling Tab in Workbench
The System Coupling tab is the workspace where you'll finish setting up and then run a coupled
analysis.
124
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Figure 10: The System Coupling tab
The following panes are all displayed by default:
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 participants, 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.
Setting Up a Coupled Analysis in Workbench
To set up a coupled analysis using System Coupling in Workbench, perform the following steps:
Creating a Coupled Analysis
Completing Participant Setups
Connecting Systems on the Project Schematic
Completing the Coupling Setup
Creating a Coupled Analysis
To create a coupled analysis in Workbench:
1. Add individual participant systems to the Workbench Project Schematic.
For example, you might:
• Add analysis systems for two dynamic participants, such as a Transient Structural system for Mechanical 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.
2. Add a System Coupling component system to the Project Schematic.
This system will be used to connect the participants later.
Completing Participant Setups
Complete the physics setup for each participant to enable its inclusion in the coupled analysis. For
each participant, open the product and perform the following steps:
126
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
1. Complete the fluid and/or solid physics setup.
During the coupled analysis, System Coupling manages participant solutions. However, each participant 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 Considerations (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).
2. Configure coupling-specific settings to enable coupling.
• For Mechanical, this involves creating a System Coupling Region.
• 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 Participants for System Coupling in Workbench (p. 122) to access its documentation.
Connecting Systems on the Project Schematic
Connect the systems on the Project Schematic via their Setup cells, as shown in Figure 11: Connecting
a System Coupling component system with other types of systems (p. 128).
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 generated.
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
128
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Completing the Coupling Setup
Set up the System Coupling portion of the coupled analysis using the sub-nodes and corresponding
properties available under the Setup node, which is defined in the System Coupling tab's Outline.
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 subnodes 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
Setup Node Context Options
Use the Setup node's context options to perform various set-up tasks. To access available options,
right-click a sub-node defined under the Setup node.
Available options:
Expand All / Contract All
Available for all nodes. Expands or contracts all nodes in the Outline.
Start/Stop highlighting linked nodes
Available for the Setup node. Controls whether nodes related to the selected node are highlighted
in the Outline.
Create Data Transfer
Available for the Data Transfers container node. Creates a new data transfer. For details, see Data
Transfer Context Options (p. 136).
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).
Display Validation Failure
Available for any node that is invalid, as indicated by a state of Attention Required ( ). Displays error
messages with details on validation problems.
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.
Read restart points
When Analysis Settings is selected in the Outline, available for the Coupling Initialization property
under Properties. Populates the list of restart points.
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.
Coupling properties are defined under the following nodes:
Analysis Settings
Participants
Data Transfers
Execution Control
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
Property defining the type of the analysis.
Possible values:
• General
Used when all participants are executing a steady-state or static solution.
• Transient
130
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
• Restart Points (indicated by Step and Time)
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:
Program-controlled or explicitly specified restart points affect only the
coupling step and/or time used to restart System Coupling. Appropriate
restart points must also be specified for the co-simulation participants
that are part of the coupled analysis.
Duration Controls
The duration of the analysis is defined by the following properties.
Duration Defined By
Property controlling how the duration of the analysis is defined:
Possible values:
• End Time
Available when the Analysis Type is Transient
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 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 will be reported 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
Available when the Analysis Type is General.
System Coupling executes coupling steps until the number of steps specified by the
Number of Steps property have been executed.
End Time [s]
Property defining the duration of the analysis in seconds. Available when Duration Defined by
is set to End Time.
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:
• The coupling analysis duration has not been reached, and
• 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:
132
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 participant name, as presented in the Project Schematic
Under a given participant node, a Regions (p. 133) node is defined.
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:
System Coupling in Workbench requires participants to use 3D meshes, with data
transfer regions consisting of element faces from a 3D mesh. System Coupling, when
run from one of its user interfaces, supports both 2D and 3D meshes.
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:
134
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
Data Transfer Control
Data transfer behavior is defined by the following properties:
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.
For more detailed information, see Under-Relaxation Algorithm (p. 175).
Note:
• Ramping and under-relaxation are independent operations. Ramping is applied before
under-relaxation.
• 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.
RMS Convergence Target
Target value used when evaluating convergence of the data transfer within a coupling iteration.
The default value is 1e-2. The convergence target is RMS-based. For information regarding how
this target is applied, see Evaluating Convergence of Data Transfers (p. 157).
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 interface for all coupling iterations. (default value)
• Linear to Minimum Iterations
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:
System Coupling's ramping interacts with ramping behaviors of the participant
systems. To understand the full ramping behavior, verify ramping settings to
see if your participant system is ramping loads received from System Coupling.
For ramping behavior in Mechanical, see System Coupling Related Settings in
Mechanical in the Mechanical User's Guide.
Data Transfer Context Options
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:
Create Data Transfer
Use to create single and multiple data transfers in any of the following ways:
• Create an uninitialized data transfer:
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.
• Create data transfers for two regions from different participants:
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 two regions have the same topology
– Whether the input variable from one region has the same properties (such as the physical
type) as the output variable from the other region
136
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
• Create data transfers for a single region:
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.
• Create a data transfer for a single variable:
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.
Duplicate Data Transfer
Select one or more data transfers, right-click one of them, and select Duplicate. This operation
creates new data transfers with the same Source, Target, and Data Transfer Control properties.
Note that you can change these properties as needed.
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 recommended, 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:
• All data generated for the analysis previously is cleared.
• Where there are differences in how properties function between versions (such as for Expert Settings (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.
To enable an expert setting:
1. In System Coupling Outline, expand Execution Control.
2. Right-click Expert Settings and select Add Property.
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 selection and applied.
3. Select the expert setting to be enabled.
The selected setting is shown under Properties with a value of True (enabled).
To edit an enabled expert setting:
1. In Outline, select Expert Settings.
2. Under Properties, select a different value for the setting.
To disable an expert setting:
1. In Outline, right-click Expert Settings and select Remove Property.
138
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Setting Up a Coupled Analysis in Workbench
2. Select the expert setting to be disabled.
The setting is removed from Properties.
For details on available expert settings, see Expert Settings.
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:
• None (default value)
• Level 1
• Level 2
• Level 3 (recommended starting value for debug output generation)
• 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.
Intermediate Restart Data Output
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.
Accepts integer values greater than or equal to 1. Default value is 1.
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:
During execution of the coupled analysis, co-simulation participants are automatically
requested to generate intermediate restart data at the same frequency as System
Coupling. Note that this feature only affects the frequency at which data are generated; the content of data is determined by the participant.
Running a Coupled Analysis in Workbench
This section describes the properties and controls used to run a coupled analysis using System Coupling
in Workbench.
• 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.
The following topics are covered:
Starting the Solution
Monitoring Solution Progress
Solution Validation and State
Solution Node Context Options
Starting the Solution
Once the coupled analysis setup is complete, start the solution. In the System Coupling tab's Outline,
right-click Solution and select Update.
Alternatively, you can start the solution from the Project Schematic by right-clicking the System
Coupling system's Solution cell and selecting Update.
140
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
Monitoring Solution Progress
As the solution proceeds, you can monitor its progress as follows:
Viewing Transcript Output
Viewing System Coupling Charts
Viewing Transcript Output
Solution information is automatically generated for output of System Coupling and the coupling
participants. Figure 12: Solution Information node (p. 141) shows an example of the Outline of
Schematic's Solution Information node. Select one of the solution information sources underneath
it to view its output in the Solution Information pane.
Note:
The default behavior of the Solution Information pane is to always show the latest information 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:
• Page Up scrolls up one page.
• Page Down scrolls down one page.
• Ctrl+Home jumps to the top of the Log.
• Ctrl+End jumps to the bottom of the Log.
Figure 12: Solution Information node
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.
Viewing System Coupling Charts
The System Coupling Chart Monitor displays the coupling chart selected in the System Coupling
tab's Outline of Schematic. System Coupling charts plot the data produced by System Coupling
during its execution. They're updated dynamically during the analysis, so you can use them to
monitor convergence as the solution progresses.
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.
For information on monitoring fluid participant quantities in a CFD participant product,
see one of the following sections
• Monitoring and Reporting Solution Data
• CFX-Solver Manager Monitors Menu
• CFD-Post Monitor Menu.
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.
For more information on working with System Coupling charts, see:
Availability of Chartable Data
Chart Properties
Chart Variables
Chart Context Options
Chart Monitor Controls
Saving a Chart as a Graphic
Availability of Chartable Data
Multiple levels of X-axis data are available for plotting. The higher (coarser) levels of data are
called parent levels, and the lower (finer) levels of data are called child levels. Any data present in
a child level is also available to its parent level. For example, Figure 13: Hierarchical availability
of plotting data (p. 143) shows a flowchart illustrating the availability of plotting data for an sample
coupled analysis run.
142
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
Figure 13: Hierarchical availability of plotting data
In this coupling run:
• Coupling Step is the parent level for
– Coupling Iteration, which is the parent level for
→ Solver 1 Step and Solver 1 Iteration, and
→ Solver 2 Step and Solver 2 Iteration.
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
• Coupling Time (transient analyses only)
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
• Log (Log base 10)
• Natural Log
Automatic Range
Defines whether automatic scaling or range maximum and minimum are applied to the axis.
• When selected, automatic scaling is used.
• 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:
• the RMS change in data transfer values
• diagnostic values (sum and average) taken from the nodal data associated with data transfers
For more information on System Coupling chart variables, see:
Adding a Chart Variable
Chart Variable Properties
Adding a Chart Variable
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).
144
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
Figure 14: Selection of Convergence Chart variable
Chart Variable Properties
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 consecutive 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.
Chart Context Options
Context options are available for working with System Coupling charts. In the System Coupling
tab's Outline of Schematic, you can access these options by right-clicking the Chart Monitor
node or any chart or chart variable nodes defined underneath it.
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 removed.
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.
Chart Monitor Controls
You can manipulate the display of a chart using the Zoom, Pan, and Fit operations:
• Zoom by using the mouse wheel or Shift+middle mouse button
• Box zoom by using the right mouse button
• Pan by using Ctrl+middle mouse button
• Fit by using the F key.
146
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Running a Coupled Analysis in Workbench
Saving a Chart as a Graphic
To save a System Coupling chart as a graphic:
1. Right-click the background of the chart and select Save Image As.
A dialog that displays, showing a small image of the chart.
2. Select the Size (resolution) to be used when saving the chart.
3. Click the ellipsis (
) button and navigate to the folder where you want to save the file.
4. Enter a filename.
5. Select a graphic file type (.png or .bmp).
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.
Solution Validation and State
The state of the Solution node in the System Coupling tab's Outline of Schematic corresponds to
the state of System Coupling system's Solution cell on the Project Schematic.
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.
Solution Node Context Options
Context options are available for working with System Coupling solutions. In the System Coupling
tab's Outline of Schematic, you can access these options by right-clicking the Solution node or any
of the child nodes defined underneath it.
• From the Solution node, you can:
– Update the solution;
– Continue Calculation if the solution was interrupted;
– Refresh the solution;
– Clear Generated Data; and
– Reset the solution.
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.
• From the Chart Monitor node, you can:
– 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.
– Right-click a chart variable and select Rename or Delete.
• Display Validation Failure:
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 calculation 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.
Alternate Workflows for System Coupling in Workbench
For information on alternate workflows for System Coupling in Workbench, see:
Stopping a System Coupling Analysis in Workbench
Restarting a Coupled Analysis in Workbench
Setting Up a Coupled Analysis in Workbench for a User-Interface Run
Stopping a System Coupling Analysis in Workbench
To stop a coupled analysis in Workbench:
1. In the Workbench Progress pane, click the Stop (
) button.
2. On the dialog that displays, select from the following options:
• 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.
148
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Alternate Workflows for System Coupling in Workbench
• Cancel: Continues with the current run.
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.
Restarting a Coupled Analysis in Workbench
You can restart a completed or interrupted coupled analysis in Workbench, either from the final result
or from an intermediate result. When restarting a coupled analysis Workbench, you must select the
necessary participant restart files and start participants manually.
Note:
Mechanical Steady-State Thermal Transient Thermal analysis system do not support
restarts.
For more information, see:
Generating Restart Files in Workbench
Restarting a Coupled Analysis in Workbench
Recovering from a Workbench Crash
For information on restarts from one of System Coupling's user interfaces, see Restarting a Coupled
Analysis (p. 88).
Generating Restart Files in Workbench
Restarts of a System Coupling analysis require corresponding restart points to exist in System
Coupling and in each of the solvers participating in the analysis.
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.
a. On the Project Schematic, double-click System Coupling's Setup cell.
The System Coupling tab opens.
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).
Restarting a Coupled Analysis in Workbench
Once the execution of the Workbench coupled analysis is finished or interrupted, or if the solution
fails, you can restart from any of the saved restart points. You must select the same restart point
for the System Coupling system and all coupling participants.
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-relaxation is applied during this iteration.
To restart the coupled analysis run:
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.
2. Make any necessary changes to analysis settings for participants.
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.
3. Make any necessary changes to the System Coupling system:
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:
• Coupling analysis type
150
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Alternate Workflows for System Coupling in Workbench
• Coupling initialization and duration settings
• Coupling step size
• Minimum and maximum number of coupling iterations per coupling step
• Data transfer convergence target and under-relaxation factors
4. Select the restart point for the System Coupling system:
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.
Recovering from a Workbench Crash
Workbench or one of its component systems may crash in such a way that restart files are available,
but not recognized or populated in the Workbench project. In this case, you can recover your project
and restart your analysis using the steps below.
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.
To recover the project so you can restart from a specified point:
1. Launch Workbench and open the project.
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.
5. Recover System Coupling's restart points:
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.
b. Double-click the Setup cell to open the System Coupling tab.
c. In the Outline, select Analysis Settings, then in Properties of Analysis Settings, right-click
Coupling Initialization and select Read Restart Points.
The restart points will now be available in System Coupling as usual.
d. In Properties, for Coupling Initialization, pick a restart point that corresponds to the restart point
you selected in the participant systems.
e. Right-click Solution and select Update.
Your restarted coupled analysis will begin to solve.
Setting Up a Coupled Analysis in Workbench for a User-Interface Run
You can set up a coupled analysis in Workbench and then run it in one of System Coupling's user
interfaces, either the GUI or the CLI. The setup process is similar to that for an analysis to be run in
Workbench, as described in Setting Up a Coupled Analysis in Workbench (p. 126), except that you'll:
• create a coupled analysis working directory;
• generate a solver input file for each participant; and
• export a System Coupling SCI file.
Note:
Ensure that the paths to all required scripts and executables are added to the PATH environment variable so that participating applications can be launched from the GUI or CLI.
To set up a coupled analysis in Workbench, perform the following steps:
1. Create a coupled analysis directory structure.
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).
2. Set up the coupled analysis.
Set up the coupled analysis exactly as you would for an analysis to be run in Workbench, as described in Setting Up a Coupled Analysis in Workbench (p. 126).
3. Generate participants' solver input files.
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.
152
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 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 generated. Once the files have been generated, you need only to
move the sovler input file to the CFX participant's coupling working directory.
4. Export a System Coupling Input (SCI) file.
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:
A <ParticipantType> is required for each participant in a GUI or CLI coupling run.
However, it may not be present in an SCI file exported for a project created with an
earlier version of Workbench.
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
154
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 infrastructure 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.
Process Synchronization and Analysis Evolution
System Coupling and participants advance synchronously through a coupled analysis. High-level synchronization is managed with the use of synchronization points, and low-level synchronization, between
synchronization points, is managed using a token-based protocol.
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 participants (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 synchronization 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.
156
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Evaluating Convergence of Data Transfers
To evaluate convergence of data transfers, each iteration is measured against the previous iteration.
The change in all the data transfer values between these two successive iterations is reduced to a normalized value. When two successive iterations produce a normalized value that is under the convergence
(you can change the convergence target default value of 1e-2), the data transferred has converged.
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 execution of the coupled analysis. These include the maximum and Root Mean Square (RMS) of the normalized 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.
The RMS value is evaluated as:
(1)
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,
and is expressed as:
, is the un-normalized change between successive iterations,
(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 iteration 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.
Although monotonic convergence to the specified target values is ideal, oscillatory
convergence and/or divergence (that is, constant or increasing convergence measures)
may also occur.
158
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
System Coupling currently supports transfers of the following types of data:
• 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 twoway 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.
For more information on System Coupling data transfers in general, see:
Rules for the Creation of Data Transfers
System Coupling's Data Transfer Process
System Coupling's Mapping Capabilities
Supplemental Processing Algorithms
Rules for the Creation of Data Transfers
The following rules for the creation of data transfers are applicable to all System Coupling analyses.
• 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.
Regarding transfers of thermal data:
• For a given source/target pair of regions, if a transfer of HTC is defined, then a transfer of Tref must also be
defined, and vice versa.
• 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).
System Coupling's Data Transfer Process
System Coupling's data transfer process can be divided into two components, each of which executes
its own set of algorithms:
• Mapping (p. 160)
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:
– Associate source and target locations
– Generate data for target locations
• Supplemental Processing (p. 172)
Supplemental processing may be applied to data before and/or after mapping. System Coupling
uses various supplemental processing algorithms to perform the following tasks:
– Reconstruct data on mesh locations
– Apply ramping and under-relaxation factors
– Apply unit conversions as needed
– Apply Quasi-Newton stabilization
System Coupling's Mapping Capabilities
In System Coupling, all data transfers are accomplished via mapping, which is the process of using the
data from locations on a source mesh to calculate data for locations on a target mesh.
160
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
For more detailed information on the mapping process, see:
Mapping Topologies
Mapping Types
Associating Source and Target Locations
Generating Data for Target Locations
Mapping Topologies
System Coupling can create mappings between participant regions of the following topologies:
• Surface (2D)
• Planar Surface (2D)
• Volume (3D)
Mapping can occur between participant regions of like topology, and in some cases, between participant 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.
Table 11: Coupling context support for region topology combinations
Region Topology Combinations
System Coupling GUI
and CLI
2D-to-2D
Surface⇒Surface
✓
3D-to-3D
Volume⇒Volume
✓
2D-to-3D
Planar
Surface⇒Volume
✓
3D-to-2D
Volume⇒Planar
Surface
✓
System Coupling in
Workbench
✓
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-preserving mapping is used to transfer non-conservative quantities, such as Temperature, from
interface source to target regions.
• 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).
• Supports the following profile-preserving quantities:
– Scalar quantities:
→ Temperature
→ Heat Transfer Coefficient
→ Convection Reference 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 interface 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.
• Supports the following conservative quantities:
– Scalar quantities:
→ Mass Flow
→ Heat Rate
→ Heat Rate Density (automatically multiplied by local element size)
– 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.
162
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
System Coupling's Mapping Capabilities
Associating Source and Target Locations
To begin the mapping process, System Coupling creates associations between locations on the source
mesh and locations on the target mesh, essentially placing them in the same simulation space. The
association process begins with a Binary Space Partitioning (BSP) search to quickly identify the required set of candidate mesh locations to be used in the generation of mapping weights.
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:
• Used for Surface-to-Surface (2D-to-2D) mapping
• Source mesh is projected (or scattered) onto the target mesh
• For illustrations, see:
– 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:
• Used for Volume-to-Volume (3D-to-3D) mapping
• Source mesh is mapped directly to the target mesh
• For illustrations, see:
– 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:
• Used for Volume-to-Planar Surface (3D-to-2D) mapping
• Used for Planar Surface-to-Volume (2D-to-3D) mapping
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.
• Source mesh is extruded onto the target mesh
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
• For illustrations, see:
– Figure 22: Example input and output for Element-Weighted Average mapping (p. 168) (Profile-Preserving)
– 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)
Binary Space Partitioning Algorithm
A Binary Space Partitioning (BSP) tree algorithm is used to quickly identify the required set of
candidate mesh locations to use for generating mapping weights.
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.
From here, the association process varies as follows:
• 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 intersecting 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.
Generating Data for Target Locations
After System Coupling has associated source and target locations, it generates data on the mapped
target location, and when applicable, the unmapped target locations.
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
164
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
Generating data on mapped locations
System Coupling calculates mapping weights and then uses the weights to interpolate the source location's data onto the target location.
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:
• Linear Shape Function
– Mapping weights are generated using linear shape functions
– Used for profile-preserving surface-to-surface mapping
• Radial Basis Function
– Mapping weights are generated using radial basis functions
– Used for profile-preserving volume-to-volume mapping
• Element-Weighted Average
– Mapping weights are generated using an element-weighted average
– Used for profile-preserving volume-to-planar surface mapping
• 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
– Different variations of the algorithm are used according to participant topologies:
→ A version for like topologies is used for conservative surface-to-surface and volume-tovolume 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).
Generating data on unmapped locations
System Coupling handles the lack of associated source data according to the type of mapping being
performed plus the topologies of involved participant regions.
• 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.
Table 12: Mapping algorithms by mapping type and region topology
Topology
Mapping
Type
ProfilePreserving
Conservative
Target Data Generation Algorithm
On Mapped
Locations
(Mapping
Weights)
Source
Target
Association
Algorithm
Surface
Surface
Projection
Linear Shape
Function
Volume
Planar
Surface
Extrusion
Element-Weighted
Average
Radial Basis
Function
Volume
Volume
Coincident
Surface
Surface
Projection
Planar
Surface
Volume
Extrusion
Volume
Volume
Coincident
On
Unmapped
Locations
Nearest
target
node value
Nearest
source
node value
Intersect-Scatter-Gather Zero value
Profile-Preserving Mapping Algorithms
For data transfers of profile-preserving quantities, the following algorithms are used to generate
data for mapped target locations:
Linear Shape Function
Radial Basis Function
Element-Weighted Average
Linear Shape Function
For transfers of profile-preserving quantities between surfaces, the Linear Shape Function algorithm
is used to generate target data for mapped locations.
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
166
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
Radial Basis Function
For transfers of profile-preserving quantities between volumes, the Radial Basis Function algorithm
is used to generate target data for mapped locations.
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 ElementWeighted Average algorithm is used to generate target data for mapped locations. Figure 20: Example 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.
168
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Conservative Mapping Algorithms
For data transfers of conservative quantities, the Intersect-Scatter-Gather algorithm is used to
generate data for mapped target locations. There are two variations of this algorithm, and the
variation used is determined by participant region topologies.
Intersect-Scatter-Gather for Like Topologies
Intersect-Scatter Gather for Unlike Topologies
Intersect-Scatter-Gather for Like Topologies
The version of Intersect-Scatter-Gather for like topologies (i.e., applied when either the Projection
or Coincident association method is used) is used when conservative quantities are transferred
between two surfaces or between two volumes.
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
Intersect-Scatter Gather for Unlike Topologies
The version of Intersect-Scatter-Gather for unlike topologies (i.e., applied when the Extrusion
association method is used) is used when conservative quantities are transferred from a planar
surface to a volume.
170
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
Supplemental Processing Algorithms
Supplemental processing algorithms are used both before and after mapping to preprocess and
postprocess the data being transferred. The following algorithms are available:
Data Reconstruction Algorithms
Ramping Algorithm
Under-Relaxation Algorithm
Initial Values Used for the Reference Target-Side Value
Quasi-Newton Stabilization Algorithm
Data Reconstruction Algorithms
In both the pre-interpolation are post-interpolation stages of the data transfer process, data reconstruction algorithms are used to create variable data on specific mesh locations (e.g. nodes), given
that data for this variable already exists at different mesh locations (e.g. face centroids). These reconstruction algorithms are used when a source participant provides values at mesh locations different
172
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
Algorithms to reconstruct profile-preserving variable data (such as temperatures or displacements) are not currently needed, so this section describes only the algorithms for conservative variables.
Conservative variable data are reconstructed by one of the following methods:
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 ramped, target-side value.
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.
174
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Supplemental Processing Algorithms
Figure 28: Schematic of the Linear to Minimum Iterations ramping concept
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 potentially 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
is the relaxed, target-side value.
is the reference target-side value. For coupling iterations within a coupling
step, the reference target-side value is the final value from the last coupling iteration.
For the first coupling iteration of the first coupling step, the reference target-side value
is the initial value for the data transfer variable (see Table 13: Initial values used for the
reference target-side value (p. 176)). For the first coupling iteration of all subsequent
steps, the reference target-side value is the final value from the last coupling step.
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.
Initial Values Used for the Reference Target-Side Value
For ramping and under-relaxation, the default for the initial value used as the reference target-side
value (
) in Equation 4 (p. 173) and Equation 5 (p. 175) is based on the physical type of the
variable. The default values are listed in Table 13: Initial values used for the reference target-side
value (p. 176).
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-relaxation is applied during this iteration.
Table 13: Initial values used for the reference target-side value
Variable Type
Initial Value Used for the
Reference Target-Side Value
(
0.0 [m]
Force
0.0 [N]
Heat Rate
Heat Transfer
Coefficient
176
)
Incremental
displacement
Temperature
Notes
295.15 [K]
For the ramping algorithm, the
reference target-side value for
incremental displacement is
always 0.0 [m] for every coupling
step.
Variables of this type include
temperature and near wall
temperature.
0.0 [W]
0.0 [Wm-2K-1]
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Supplemental Processing Algorithms
Quasi-Newton Stabilization Algorithm
System Coupling offers the Quasi-Newton solution stabilization and acceleration method, which is
based on the Interface Quasi-Newton – Inverse Least Squares (IQN-ILS) algorithm. The Quasi-Newton
method can be used to address convergence issues in two-way System Coupling simulations, which
can sometimes experience difficulties in the following contexts:
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 significant 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 QuasiNewton 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.
178
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
Files Used by System Coupling
This section describes the files used by System Coupling during its execution:
Participant Setup File (*.scp)
Input File (scInput.sci)
Shutdown File (scStop)
Participant Setup File (*.scp)
When coupled analysis participants are set up from one of System Coupling's user interfaces, each
participant in the analysis writes a System Coupling Participant setup file (*.scp). Typically, these
files are named according to the convention noted below, but other extensions can be used, as well.
<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 analysis (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 (Settings.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.).
Each SCP file has the following format:
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.
The SCP file includes the following main elements:
<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.
180
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Contains the following sub-elements:
<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:
• <WorkingDirectory> can be set to the absolute path to the participant's working
directory, but the relative path can also be used. If you use a relative path, it must be relative
to System Coupling's working directory.
• 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.
Required if the parent <ExecutionControl> (p. 180) element exists.
Acceptable <InitialInput> values vary according to coupling participant:
• 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.
• For a FLUENT participant, there are two options:
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 participant. 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.
Contains the following sub-elements:
<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.
Optional. When not specified, the DEFAULT type is used.
Possible values:
• AEDT
• CFX
• FLUENT
• MAPDL
• DEFAULT
182
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<AnalysisType>
Specifies the type of coupled analysis to be performed.
Optional. When not defined, the Steady analysis type is used.
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.
Optional. When not defined, a value of False is used.
Possible values:
• False: Indicates that the participant does not support restarts. (default)
• True: Indicates that the participant supports restarts.
<Variables>
Container element for the set of variables that are available for coupled simulations.
Optional. If no output/input variables are defined, then the participant is ignored.
Contains one or more <Variable> (p. 183) sub-elements:
<Variables>
<Variable> (p. 183)
</Variables>
<Variable>
Defines a variable that is available for coupled simulations. Nested under <Variables> (p. 183).
Optional. If no output/input variables are defined, then the participant is ignored.
Contains the following sub-elements:
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>
Specifies the variable name to be displayed in user-facing communications.
Optional. If not specified, the variable's data model <Name> (p. 184) is used.
<QuantityType>
Specifies the quantity type of the data provided by the variable.
Required.
Possible values:
• Convection Reference Temperature
• Force
• Incremental Displacement
• Heat Rate
• Heat Rate Density
• Heat Transfer Coefficient
• Temperature
<Location>
Defines the mesh location on which data exists.
Optional. If not specified, defaults to Node.
Possible values:
• Element
• Node
184
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Optional. When no regions are defined, the participant is ignored.
Contains one or more <Region> sub-elements:
<Regions>
<Region> (p. 185)
</Regions>
<Region>
Defines a region that is potentially available for coupled simulations. Nested under <Regions> (p. 185).
Optional. When no regions are defined, the participant is ignored.
Contains the following sub-elements:
<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>
Specifies the region name to be displayed in user-facing communications.
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.
Contains one or more <Variable> (p. 186) sub-elements.
<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.
Contains one or more <Variable> (p. 186) sub-elements.
<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.
186
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
Sample System Coupling Participant File
The following is an example SCP file for the MAPDL participant in a coupled analysis.
<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>
Input File (scInput.sci)
The System Coupling Input SCI file is generated by the System Coupling system for coupled analyses
set up in Workbench.
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.
The SCI file includes the following elements:
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.
For each coupling transfer, the following properties are available:
<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.
<Type> (integer attribute)
Type of coupling participant.
Possible values:
• 0: Co-simulation
• 1: Static data
<DisplayName> (wide string)
Display name of the participant, as provided in the Workbench user interface.
<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.
<Regions> (options below are applicable to an individual region)
For each region, the following properties are available:
<Name> (string)
Name of the region (intrinsic to the participant).
<DisplayName> (wide string)
Display name of the region, as provided in the Workbench user interface.
<TopologicalDimensionality> (integer)
Geometry type of the region.
188
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
Possible values:
• 2: Surface
• 3: Volume
<Variables> (options below are applicable to an individual variable)
<Name> (string)
Name of the variable (intrinsic to the participant).
<DisplayName> (wide string)
Display name of the variable, as in the Workbench user interface.
<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
The only property relevant to System Coupling is:
<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
• 3 (recommended starting value for debug output generation)
• 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:
• 0: Every coupling step
• 1: Coupling step interval
<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.
190
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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:
• 1: Coupling step size. Used for transient analyses.
• 0: Non-dimensional step size. Used for general analyses.
<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 participants).
Note:
Depending upon the type of participant (co-simulation or static data), some of the options
may not be applicable.
For each connected participant, you can view the following:
Type (integer attribute)
Type of coupling participant.
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.
<DisplayName> (wide string)
Display name of the participant, as provided in the Workbench user interface.
192
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Used by System Coupling
<ParticipantType> (string)
Indicates the application participating in the coupled analysis.
Important:
A <ParticipantType> is required for each participant in a coupled analysis
executed in one of System Coupling's user interfaces. However, it may not be
present in an SCI file exported for a project created with an earlier version of
Workbench.
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 UserInterface 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 iterations per coupling step.
<UnitSystem>
Unit system used.
<Regions> (options below are applicable to an individual region)
For each region, the following properties are available:
<Name> (string)
Name of the region (intrinsic to the participant).
<DisplayName> (wide string)
Display name of the region, as provided in the Workbench user interface.
<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
Variables (options below are applicable to an individual variable)
For each variable, the following properties are available:
<Name> (string)
Name of the variable (intrinsic to the participant).
<DisplayName> (wide string)
Display name of the variable, as provided in the Workbench user interface.
<PhysicalType> (string)
Physical type of the variable.
Possible values include:
• 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)
Shutdown File (scStop)
A coupled analysis that is run using the Solve operation performs the entire solution straight through
(as opposed to an analysis that is run using advanced solve commands (p. 95), which provide the
ability to pause, interact with, and shut down the run at designated points). However, an analysis run
using the Solve operation can be either interrupted or aborted using a Shutdown file.
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.
194
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 information 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.
Files Generated by System Coupling
This section describes the files generated by System Coupling during its execution:
GUI Server File (sycGui.srv)
Solution Lock File (sycSolve.lock)
Transcript and Log File (scLog.scl)
Debug Output
Settings File (Settings.h5)
Results Files (Results_*#.h5)
ANSYS EnSight Gold–Formatted Results Files
Server File (scServer.scs)
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
GUI Server File (sycGui.srv)
When you start System Coupling in GUI Server mode — whether started from the GUI or from the
command-line with the --guiserver argument — it writes a System Coupling GUI Server file
(sycGui.srv) is written to its working directory.
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.
Example 37: Example scServer.scs file
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).
Solution Lock File (sycSolve.lock)
When a coupled analysis solution is started by any method, System Coupling writes a System Coupling
Solution Lock file (sycSolve.lock) to its working directory.
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 interrupt/ 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 terminated unexpectedly and cleanup is required. For details on handling this scenario, see
Known Issues and Limitations (p. 31).
196
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Transcript and Log File (scLog.scl)
System Coupling writes coupled analysis information to two output formats:
• System Coupling Transcript:
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.
• System Coupling Log file (scLog.scl) File:
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.
The Transcript and Log file include the following sections:
Executable Information
Execution Information
Participants Build Information
Summary of Coupling Setup
Coupled Solution
Shut Down
Available Restart Points
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 spawning Node 0 on machine "MYMACHINE" (win64).
WARNING: No cached password or password provided.
use '-pass' or '-cache' to provide password
Host 0 -- ip 192.168.1.1 -- ranks 0
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
Prot -
All Intra-node communication is: 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
MPI Option Selected: ibmmpi
------------------------------------------------------------------------------Cleanup script file is C:\Users\USERNAME\TestCases\syc-2d-to-3d\cleanup-afd-MACHINE-6052.bat
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
Provides build information for each participant, with participants ordered alphabetically by display
name.
+=============================================================================+
|
Participants Build Information
|
+-----------------------------------------------------------------------------+
| ANSYS Electronics Desktop
|
198
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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
|
+=============================================================================+
Summary of Coupling Setup
Provides information about the coupled analysis setup in the following subsections:
Coupling Control
Solution Control
Output Control
Participants Information
Interfaces Information
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 |
200
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
|
Input Variables :
Temperature |
|
Output Variables :
Loss |
|
Region: Core_1st
|
|
Topology :
Volume |
|
Input Variables :
Temperature |
|
Output Variables :
Loss |
|
Region: Core_2nd
|
|
Topology :
Volume |
|
Input Variables :
Temperature |
|
Output Variables :
Loss |
|
Coordinate Transformation:
|
|
Option :
None |
|
|
+-----------------------------------------------------------------------------+
|
|
| Participant: MAPDL Steady-State Thermal
|
|
Type :
MAPDL |
|
Update Controls:
|
|
Option :
ProgramControlled |
|
Region: FVIN_2_System Coupling Region 2
|
|
Topology :
Volume |
|
Input Variables :
Heat Rate Density |
|
Output Variables :
Temperature |
|
Region: FVIN_1_System Coupling Region
|
|
Topology :
Volume |
|
Input Variables :
Heat Rate Density |
|
Output Variables :
Temperature |
|
Coordinate Transformation:
|
|
Option :
None |
|
|
+=============================================================================+
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
|
Relaxation Factor :
1.00E+00 |
|
Mapping Type :
Volume Profile Preserving |
|
Stabilization :
None |
|
|
+=============================================================================+
Coupled Solution
Provides information about the coupled solution in the following sections:
Pre-Solution Warnings and Messages
Coupling Step
Pre-Solution Warnings and Messages
Prior to the solution details, System Coupling prints validation warnings about issues that could
affect execution. When applicable, it prints messages indicating that hidden features are activated
and which beta features will be applied to the analysis.
+-----------------------------------------------------------------------------+
| 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
|
+----------------------------------------------------------------------------+
202
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 simultaneous 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). Indicates 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.
Figure 29: Coupling Iteration output
+-----------------------------------------------------------------------------+
|
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
|
+=============================================================================+
Figure 30: Coupling Iteration output with simultaneous-solve participants
+-----------------------------------------------------------------------------+
|
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
|
204
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
|
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
|
+=============================================================================+
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.
• Coupling Engine Time:
Records the total processing time for System Coupling
• Coupling Participant Time:
– 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
Provides a table of the restart points generated during the execution of the analysis, whether from
the current run or previous runs. The corresponding Results files are named according to the analysis type and the types of participants involved, as described in Results Files (Results_*#.h5) (p. 207).
Figure 31: Table of step-based restart points
+=============================================================================+
|
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
|
+=============================================================================+
Figure 32: Table of iteration-based restart points
+=============================================================================+
|
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_MXARRAYELMS 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.
206
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Files Generated by System Coupling
Settings File (Settings.h5)
When the state is saved for a coupled analysis run in one of System Coupling's user interfaces, the
analysis settings are written to a System Coupling Settings file (Settings.h5). By default, the file
is written to the SyC directory in the coupled analysis directory. When the state is saved using the
Save command, you can specify an alternate location by using the FilePath argument.
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.
Results Files (Results_*#.h5)
For a coupled analysis run in one of System Coupling's user interfaces, results are written to a System
Coupling Results file (Results_*#.h5) at the end of the last coupling step or iteration completed.
By default, these files are written to the SyC subdirectory in System Coupling's working directory.
Results files are named according to the convention Results_step#.h5 or Results_iter#.h5,
where "#" is the index of the corresponding coupling step or iteration.
Results files are created in two scenarios:
• 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 information 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 CouplingStep 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 removed (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).
ANSYS EnSight Gold–Formatted Results Files
When a coupled simulation is run, System Coupling generates results files in the ANSYS EnSight Gold
file format. The following results files are written to the SyC/Results directory in System Coupling's
working directory:
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.
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.
Named according to the following conventions:
• When a single processor is used, the file is named Results.case.
• When multiple processors are used, the files are named according to the convention Results_<#>.case, where "<#>" is the index of the associated processor.
208
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Geometry data files:
Geometry data files have a .geo extension. Geometry results are written for each restart point and at
the end of the run.
Named according to the convention Results_<######>.geo, where "######" is the six-digit
coupling step index.
Variable data files:
Variable data files have a .dat extension. For each variable, coupling step results are written for each
restart point and at the end of the run.
Named according to the convention Results_V_<######>.dat, where "V " is the variable
transferred and "######" is the six-digit coupling step index.
Note:
To facilitate postprocessing, System Coupling provides a total-displacement variable
which accumulates calculations for all incremental displacement variables defined for
the Coupling Interface object. For analyses with one or more transfers of Incremental
Displacement quantities, a single total-displacement variable will hold the accumulated
totals of all incremental displacement variables.
Multi-step data files:
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
Server File (scServer.scs)
The System Coupling System Coupling Server file (scServer.scs) is written to System Coupling's
working directory if any participant is not started automatically. This text file contains the information
needed to manually connect participants to System Coupling.
The file contains the following lines of data:
• Coupling server's port and host, separated by an "@" character.
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.
• Licensing ID of the coupled analysis.
• License server's port and host, separated by an "@" character, at which the coupling participant codes
(i.e., solvers) can reach the license server.
Example 38: Example scServer.scs File
12345@CouplingServer.mydomain.com `
2
CFX-1
CFX Solver Display Name
Ansys
Ansys Solver Display Name
12345
54321@LicenseServer.mydomain.com
!Coupling server's port and host
!Number of participants
!Participant 1 Unique Name
!Participant 1 Display Name
!Participant 2 Unique Name
!Participant 2 Display Name
!Licensing ID for analysis
!License server's port and host
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)
210
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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 recommendations, see:
General Best Practices for Coupled Analyses
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Improving Coupled Analysis Stability
General Best Practices for Coupled Analyses
This section provides best practices and recommendations that are generally applicable to all coupled
analyses. For more information, see:
Building Up to a Coupled Analysis
Improving Mapping Quality
Evaluating Convergence and Data Transfer Accuracy
Improving the Accuracy of Steady Analyses
Improving the Accuracy of Transient Analyses
For recommendations on running coupled analyses for FSI applications, see Best Practices for Coupled
Fluid-Structure Interaction (FSI) (p. 216).
Building Up to a Coupled Analysis
Once you've determined that a running a two-way coupled analysis is your objective, it is recommended
that you build up to the final two-way analysis incrementally, progressively adding complexity with
each step. The following sequence of steps is recommended for building any coupled analysis:
Step 1: Solve each participant problem individually as a decoupled analysis.
Before coupling your participant problems, verify that each one of them can be solved individually, as
decoupled solutions. By running each one independently, you can get an approximation of their expected
inputs to a coupled analysis.
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.
Step 2: Solve each participant problem as part of a one-way coupled analysis.
Verify that each of the participant problems can be run successfully as part of a one-way coupled analysis.
To do this, create a one-way coupled analysis for each participant problem and use the results of the
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.
Step 3: Solve both participant problems as a two-way coupled analysis.
Solve both participant problems as a two-way coupled analysis. To do this, remove the approximated
inputs used for the one-way analyses and then incorporate each participant problem into the two-way
simulation.
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).
Improving Mapping Quality
When a coupled analysis is executed, System Coupling executes a mapping process, using data from
source-mesh locations to calculate data for target-mesh locations. When mapping is performed, the
process runs to completion and generates data regardless of any existing issues that may impact the
quality of the mapping. Use the following best practices to help ensure the accuracy of the mapping
and the resulting data transfer.
Review mapping diagnostics.
Mapping diagnostics written to the Mapping Summary (p. 203) of the Transcript/Log file provide insight
into the ultimate accuracy of the data transfers. They show the percentage of the target and source
mesh locations that were successfully mapped, providing insight into the ultimate accuracy of the data
transfers.
• Target-side diagnostics:
If less than 100% of the target-side locations were mapped, then System Coupling is implementing 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.
212
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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.
Use similar participant geometries.
Use geometries that are as similar as possible on all participant regions on the coupling interface. For
example:
• Minimize the gap between the source and target geometries.
• 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:
In most cases, reference-state disparities must be addressed as part of the geometry
and/or participant setup. For thermal-electromagnetic problems, however, they can
be addressed by System Coupling during the coupled analysis setup.
Use similar participant meshes.
Use meshes that are as similar as possible on all participant regions on the coupling interface. For example:
• Refine meshes to the degree feasible. Coarse meshes can cause and/or exacerbate mesh gaps or dissimilarities, 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.
When a profile-preserving algorithm is used, the transferred quantity is better preserved
when the target mesh has either the same number or more nodes than the source mesh.
This prevents features that are resolved on the source mesh from being lost in the transfer
to the coarser target mesh.
– 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.
When a conservative algorithm is used, there is no benefit (from a mapping point-of-view)
in the target mesh having more nodes than the source mesh; the conservative nature of the
transfer ensures that the quantity is preserved even when transferred to a coarser target
mesh.
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
Evaluating Convergence and Data Transfer Accuracy
Use the following best practices to evaluate the convergence and the accuracy of data transfers.
Set appropriate convergence target.
Set data transfer and participant convergence target that are strict enough to ensure that the data on
the target is not affected by the input data once the convergence criteria have been reached.
Review convergence diagnostics.
Review convergence diagnostics for each coupling iteration (p. 203) of each coupling step. The coupling
step/iteration sections of the Transcript/Log show the convergence status for data transfers and participants. Data transfers, and, in most cases, participants should reach convergence in each coupling step.
• Data transfer diagnostics:
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.
Review data transfer diagnostics.
Review the data transfer diagnostics reported for each coupling iteration (p. 203) of each coupling step.
The coupling step/iteration sections of the Transcript/Log show the values data transfer values reported
by the source and target participants. The sum is reported for conservative transfers, and the average
(over all regions in the interface) is reported for profile-preserving transfers.
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.
Improving the Accuracy of Steady Analyses
Use the following best practices to improve the accuracy of steady coupled analyses (p. 16).
Define an appropriate number of coupling steps/iterations.
In a steady analysis, coupling steps and coupling iterations can be combined so the analysis has either
one coupling step with multiple iterations or multiple coupling steps, each with one or more iterations.
Set the number of coupling steps and coupling iterations according to how you need to balance your
requirements for restarting the analysis, minimizing file-storage space, and/or using System Coupling's
ramping and under-relaxation Equation 5 (p. 175).
• One coupling step:
214
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
General Best Practices for Coupled Analyses
– Minimizes storage space at the expense of restart capabilities.
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.
• Multiple coupling steps:
– Allows multiple restarts at the expense of storage space.
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.
Assess the convergence status of the analysis.
Identify and address any issues that may be affecting the convergence of the analysis.
• 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 nonlinearities 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
Improving the Accuracy of Transient Analyses
Use the following best practices to improve the accuracy of transient coupled analyses (p. 17).
Define an appropriate coupling step size.
Set the coupling step size to resolve the coupling-related timescales. For example, with thermal couplings,
choose a coupling time step size that is long enough to resolve the thermal timescales.
• 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 electromagnetic/thermal applications.
Assess the convergence status of the analysis.
Identify and address any issues that may be affecting the convergence of the analysis.
• Slow convergence:
If convergence is not realized for each coupling step within approximately 5 – 10 coupling iterations, 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 approximately 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 nonlinearities 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.
Best Practices for Coupled Fluid-Structure Interaction (FSI)
This section provides best practices information and recommendations for working with Fluid-Structure
Interaction (FSI) problems. For more information, see:
216
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Building a Coupled FSI Analysis from Decoupled Participant Problems
Choosing the Mesh-Related Timescale
Defining Mesh Motion and Deformation Settings
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
• Fluid Structure Interaction in the CFX Reference Guide
• Fluid-Structure Interaction (FSI) in the Mechanical User's Guide
Building a Coupled FSI Analysis from Decoupled Participant Problems
If it will be advantageous to run an FSI problem as a coupled analysis, then the recommended approach
is to build up to the final analysis in stages of progressive complexity. This section takes the generalized
process described in Building Up to a Coupled Analysis (p. 211) and applies it to the incremental creation
of a two-way coupled FSI analysis.
Step 1: Solve the Fluid and Structural Problems Independently
Step 2: Solve the Fluid and Structural Problems as One-Way Coupled Analyses
Step 3: Solve the Fluid and Structural Problems as a Two-Way Coupled Analysis
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
Figure 33: Workflow to set up a coupled FSI analysis
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.
Step 1: Solve the Fluid and Structural Problems Independently
Because the constituent fluid and structural problems may each be quite complex on their own,
you should ensure that they can each be solved individually before attempting to join them in a
coupled analysis. Solve the problems independently, as follows:
218
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
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).
To set up the fluid-flow analysis:
1.
Remove any System Coupling motion specifications that would be used to verify mesh motion
and remeshing in the fluid analysis.
2.
Introduce the initial and boundary conditions.
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).
To set up the structural analysis:
1.
Remove any System Coupling motion specifications (if they exist) that would be used to verify
mesh motion and remeshing in the fluid analysis.
2.
Introduce the initial and boundary conditions.
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 distribution) 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
Solve the Fluid Problem as a Series of One-Way Coupled Analyses
Set up and run two one-way coupled analyses with a structural source participant and a fluid target
participant, where the displacement data generated by the structural analysis is applied to the fluid
analysis. Solve for the motion transfer, first without and then with fluid-flow calculations.
Analysis 1: Motion transfer to fluid (without solving flow equations)
First, solve for the transfer of motion from the structural analysis to the fluid analysis, but without
solving the flow equations. This allows you to test mesh motion and remeshing. It can help you to
identify and address issues that cause mesh folding, as well as to determine contact offsets and
timescales.
To set up the analysis without flow equations:
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
2.
Add System Coupling mesh motion to the analysis.
3.
For the fluid side of the analysis, configure mesh motion and deformation (p. 222) settings. If applicable, set contact detection parameters.
4.
For the structural side of the analysis, configure contact offsets to address limitations in the fluid
analysis.
5.
Generate System Coupling files.
• 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.
Analysis 2: Motion transfer to fluid (with solving flow equations)
Next, expand on the previous one-way analysis, this time activating the flow equations so that they'll
be solved with the transfer of motion from structural analysis. This allows you to verify that the flow
equations can still be solved after the introduction of motion to the analysis.
To set up the analysis with flow equations:
1.
Remove the results from the individual structural analysis.
2.
Activate flow equations for the fluid analysis.
3.
Regenerate the System Coupling files to capture the changes to the participant physics, as described 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).
220
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Best Practices for Coupled Fluid-Structure Interaction (FSI)
Solve the Structural Problem as a One-Way Coupled Analysis
Solve for the transfer of force from the fluid analysis to the structural analysis as a one-way coupled
analysis by adding coupling specifications to the problem. This allows you to verify that the structural equations can still be solved after the introduction of applied force to the analysis.
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).
Force transfer to structural
When setting up the one-way structural analysis:
1.
Remove the approximated load that was applied in the individual structural analysis.
2.
Add a System Coupling Region to the analysis.
3.
Suppress the displacement data transfer so that the analysis is one-way.
4.
Generate System Coupling files.
• 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.
When setting up the two-way simulation:
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.
3.
Incorporate each participant problem into the two-way simulation.
Choosing the Mesh-Related Timescale
Choosing the correct time step size for System Coupling is critical, since an incorrect time step size
can lead to mesh folding and other potential issues. Mesh deformation is one aspect of an appropriate
participant timescale and should be always be evaluated against other relevant timescales in each
participant.
To determine the mesh deformation time scale, calculate the time step Δt size based on:
• The length of the smallest cell, Δs
• The maximum expected velocity of the mesh, v
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.
For participant-specific details, see the corresponding product documentation:
• Performing Time-Dependent Calculations in the Fluent User's Guide
• Timestep Selection in the CFX-Solver Modeling Guide
• Steps and Step Controls for Static and Transient Analyses in the Mechanical User's Guide
Defining Mesh Motion and Deformation Settings
For participant-specific recommendations on mesh motion and deformation settings, see the corresponding CFD product documentation:
CFX:
• Mesh Motion Options in the CFX-Solver Modeling Guide
• Mesh Deformation in the CFX-Pre User's Guide
Fluent:
• Using Dynamic Meshes in the Fluent User's Guide
222
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Improving Coupled Analysis Stability
• Specifying the Motion of Dynamic Zones in the Fluent User's Guide
Improving Coupled Analysis Stability
You can improve the stability of a coupled analysis using the following methods:
Data Transfer Ramping
Participant Solution Stabilization
Data Transfer Ramping
If the full magnitude of data is applied to the target side of a data transfer interface within one iteration,
it can initiate oscillatory convergence — or even divergence — within and between the coupling
participants. To avoid this, you can ramp the target-side data from the final value in the previous
coupling step to the full magnitude during the initial coupling iterations within the current step.
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.
For more information about ramping behavior and controls, see:
• 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).
Participant Solution Stabilization
Solution instabilities that manifest as a very rapid divergence of the coupled analysis may arise if a
given coupling participant is particularly sensitive to data obtained from another participant. In these
cases, it may be helpful to use various solution stabilization algorithms that have been implemented
in the target participant.
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
224
Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.