System Coupling Settings and Commands

Reference

ANSYS, Inc. Release 2020 R1

Southpointe January 2020
2600 ANSYS Drive
Canonsburg, PA 15317 ANSYS, Inc. and
[email protected] ANSYS Europe,
Ltd. are UL
http://www.ansys.com registered ISO
(T) 724-746-3304 9001: 2015
(F) 724-514-9494 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 CONFID-
ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.

ANSYS, Inc. and ANSYS Europe, Ltd. are UL registered ISO 9001: 2015 companies.

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 Settings and Commands Reference ................................................... 1
Data Model Settings ................................................................................................................................... 3
Coupling Control (singleton) ................................................................................................................... 3
Option (setting) ................................................................................................................................ 3
Analysis Type (singleton) ................................................................................................................... 3
*Option (setting) ........................................................................................................................ 4
Duration Control (singleton) ....................................................................................................... 4
*Option (setting) .................................................................................................................. 4
*Number of Steps (setting) ................................................................................................... 5
*End Time (setting) ............................................................................................................... 5
Step Control (singleton) .............................................................................................................. 5
*Time Step Size (setting) ....................................................................................................... 6
*Minimum Iterations (setting) ............................................................................................... 6
*Maximum Iterations (setting) .............................................................................................. 6
Solution Control (singleton) .................................................................................................................... 6
*Allow Simultaneous Update (setting) ............................................................................................... 6
*Partitioning Algorithm (setting) ....................................................................................................... 7
Output Control (singleton) ...................................................................................................................... 7
*Option (setting) .............................................................................................................................. 7
*Output Frequency (setting) ............................................................................................................. 8
Coupling Interface (object) ..................................................................................................................... 8
Mapping Control (singleton) ............................................................................................................. 9
Gap Tolerance (singleton) ........................................................................................................... 9
Absolute Gap Value (setting) ................................................................................................. 9
Side (object) ..................................................................................................................................... 9
Coupling Participant (setting) ................................................................................................... 10
*Region List (setting) ................................................................................................................ 10
Data Transfer (object) ...................................................................................................................... 10
*Convergence Target (setting) ................................................................................................... 10
*Ramping Option (setting) ........................................................................................................ 10
*Relaxation Factor (setting) ....................................................................................................... 11
Stabilization (singleton) ............................................................................................................ 11
*Option (setting) ................................................................................................................ 11
*Maximum Retained Time Steps (setting) ............................................................................ 11
*Initial Relaxation Factor (setting) ........................................................................................ 12
Coupling Participant (object) ................................................................................................................ 12
*Display Name (setting) .................................................................................................................. 12
Participant Type (setting) ................................................................................................................ 13
Participant Analysis Type (setting) ................................................................................................... 13
Restarts Supported (setting) ........................................................................................................... 13
Execution Control (singleton) .......................................................................................................... 13
*Option (setting) ...................................................................................................................... 14
*Executable (setting) ................................................................................................................ 14
*Working Directory (setting) ..................................................................................................... 15
*Initial Input (setting) ................................................................................................................ 15
*Parallel Fraction (setting) ......................................................................................................... 15
*Additional Arguments (setting) ............................................................................................... 16
*External Data File (setting) ............................................................................................................. 16
Update Control (singleton) .............................................................................................................. 16
*Option (setting) ...................................................................................................................... 17

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
System Coupling Settings and Commands Reference

*Update Frequency (setting) ..................................................................................................... 17

Coordinate Transformation (singleton) ............................................................................................ 18
*Option (setting) ...................................................................................................................... 18
*Origin (setting) ........................................................................................................................ 19
*Rotation XY (setting) ............................................................................................................... 19
*Rotation YZ (setting) ............................................................................................................... 19
*Rotation ZX (setting) ............................................................................................................... 20
Region (object) ............................................................................................................................... 20
*Display Name (setting) ............................................................................................................ 20
Input Variables (setting) ............................................................................................................ 20
Output Variables (setting) ......................................................................................................... 21
Topology (setting) .................................................................................................................... 21
Variable (object) ............................................................................................................................. 21
*Display Name (setting) ............................................................................................................ 21
Quantity Type (setting) ............................................................................................................. 21
Location (setting) ..................................................................................................................... 22
Commands ................................................................................................................................................ 23
AddDataTransfer ........................................................................................................................... 24
AddDataTransferByDisplayNames ............................................................................................ 25
AddInterface .................................................................................................................................. 26
AddInterfaceByDisplayNames ................................................................................................... 27
AddParticipant ............................................................................................................................. 28
ClearState ...................................................................................................................................... 29
CreateInterfacesAndDataTransfers ...................................................................................... 29
CreateRestartPoint ..................................................................................................................... 32
DatamodelRoot ................................................................................................................................ 32
DeleteObject .................................................................................................................................. 33
ExecuteCommandString ................................................................................................................ 33
GetChildNames ................................................................................................................................ 33
GetChildren .................................................................................................................................... 34
GetCommandAndQueryNames .......................................................................................................... 34
GetErrors ........................................................................................................................................ 35
GetErrorsXML .................................................................................................................................. 35
GetExecutionCommand .................................................................................................................. 36
GetParameter .................................................................................................................................. 36
GetParameterOptions .................................................................................................................. 36
GetRegionNamesForParticipant ............................................................................................... 37
GetState ........................................................................................................................................... 38
ImportSystemCouplingInputFile ............................................................................................ 38
Initialize ...................................................................................................................................... 39
LoadParticipants ......................................................................................................................... 40
Open ................................................................................................................................................... 40
PartitionParticipants .............................................................................................................. 42
PrintSetup ..................................................................................................................................... 43
PrintState ...................................................................................................................................... 43
ReadScriptFile ............................................................................................................................. 44
Save ................................................................................................................................................... 45
SetExpertSettings ....................................................................................................................... 46
SetState ........................................................................................................................................... 46
Shutdown ........................................................................................................................................... 47
Solve ................................................................................................................................................. 47
StartParticipants ....................................................................................................................... 48

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv of ANSYS, Inc. and its subsidiaries and affiliates.
 System Coupling Settings and Commands Reference

Step ................................................................................................................................................... 49
WriteCsvChartFiles ..................................................................................................................... 50
Command-Line Options ........................................................................................................................... 51
Expert Settings ......................................................................................................................................... 57
ExportInterfaceDataPerStep ................................................................................................... 57
Source_InitValue_HeatTransferCoef .................................................................................... 58
WriteDiagnosticsDictionary ................................................................................................... 58

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. v
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
vi of ANSYS, Inc. and its subsidiaries and affiliates.
Introduction to the System Coupling Settings and Commands
Reference
The System Coupling Settings and Commands Reference provides a comprehensive list of all the settings,
commands, and command-line options available to be used with System Coupling. For more information,
see the following sections:

• Data Model Settings (p. 3)

• Commands (p. 23)

• Command-Line Options (p. 51)

• Expert Settings (p. 57)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 1
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
Data Model Settings
This section provides a comprehensive listing of data model items, both coupling-related settings and
their containers. For descriptions of available containers and settings, see:
Coupling Control (singleton)
Solution Control (singleton)
Output Control (singleton)
Coupling Interface (object)
Coupling Participant (object)

Important:

Many settings are determined 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.

Settings that are commonly used to modify coupled analyses are listed in the Modifying
Coupled Analysis Settings section of the System Coupling User's Guide. In the sections that
follow, these settings are marked with an asterisk (*).

Coupling Control (singleton)

Contains settings that control the characteristics and behavior of the coupled analysis.

Coupling Control contents:

Option (setting)
Analysis Type (singleton)

Option (setting)
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)

Contains settings that define the details about the type of analysis.

Analysis Type contents:

*Option (setting)
Duration Control (singleton)
Step Control (singleton)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
Data Model Settings

*Option (setting)
Defines the type of analysis to be run.

Possible values:

• Steady: Used when all participants are running a steady-state or static solution. Default value if
Analysis Type (p. 3) is undefined.

When this value is used and none of the participants has Participant Type set to AEDT, CFX,
FLUENT or MAPDL, only one coupling step is allowed.

• Transient: Used when any participant is running a transient solution (includes mixed steady-tran-
sient analyses).

Note:

For transient solutions involving physics with disparate time scales, System
Coupling offers mixed steady-transient analyses in which the physics with the
shorter/faster timescale is solved as steady-state. For these analyses, Option is
set to Transient.

Duration Control (singleton)

Contains settings that define the duration of the analysis.

Duration Control contents:

*Option (setting)
*Number of Steps (setting)
*End Time (setting)

*Option (setting)
Defines the duration of the analysis.

Possible values:

• Number of Steps: Available when the Analysis Type / Option (p. 4) is set to Steady. System
Coupling performs coupling steps until the specified number of steps is reached.

• End Time: Available when the Analysis Type / Option (p. 4) is set to Transient. System
Coupling executes coupling steps until the specified end time is reached.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Control (singleton)

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 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 par-
ticipants. 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 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 (setting)

Available when the Duration Control / Option (p. 4) 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 (setting)

Available when the Duration Control / Option (p. 4) is set to End Time. Defines the end time
for the coupled analysis run.

Accepts decimal values greater than or equal to 0.0 [s]. Default value is 1.0 [s].

Step Control (singleton)

Contains settings that control 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.

Step Control contents:

*Time Step Size (setting)
*Minimum Iterations (setting)
*Maximum Iterations (setting)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
Data Model Settings

*Time Step Size (setting)

Available when the Analysis Type / Option (p. 4) is set to Transient. Defines the time interval
of the coupling steps.

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 (p. 4) 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 [s]. Default value is 1.0 [s].

*Minimum Iterations (setting)

Defines the minimum number of iterations per coupling step.

Accepts integer values 1 ≤ x ≤ Maximum Iterations. Default value is 1.

*Maximum Iterations (setting)

Defines the maximum number of iterations per coupling step.

Accepts integer values 1 ≤ x ≤ 9999. Default value is 5.

Solution Control (singleton)

Settings defined under the Solution Control singleton control analysis-level solution settings.

Solution Control contents:

*Allow Simultaneous Update (setting)
*Partitioning Algorithm (setting)

*Allow Simultaneous Update (setting)

Specifies whether simultaneous solution of independent participants is enabled.

When enabled, solutions for groups of independent participants are updated simultaneously. The
participant solutions are executed in distributed parallel mode, allocated across available compute
resources by means of System Coupling's participant partitioning algorithms.

Possible values:

• False: Simultaneous solutions are disabled. Default value.

• True: Simultaneous solutions are enabled.

For more information, see Execution of Simultaneous Participant Solutions in the System Coupling
User's Guide.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
 Output Control (singleton)

*Partitioning Algorithm (setting)

Specifies the partitioning algorithm to be used when participants are running in parallel.

System Coupling's partitioning 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: Participants share both machines and cores (default value).

• Shared Allocate Cores: Participants share machines but not cores.

• Distributed Allocate Machines: Participants minimally share cores and machines.

• Distributed Allocate Cores: Participants never share cores or machines.

Note:

When simultaneous execution of participant solutions is enabled, the explicit application

of partitioning is changed as described in Execution of Simultaneous Participant Solutions
in the System Coupling User's Guide.

Output Control (singleton)

Contains settings that control the generation of analysis output.

Optional. When not defined, the default output settings are used and a restart point is generated at
the end of the analysis.

Note:

The generation of ANSYS EnSight-compatible coupling results is a released feature, but the
Output Control settings to control their output frequency are available as beta functionality.
For more information, see Settings for Generating ANSYS EnSight-Compatible Postprocessing
Output in the System Coupling Beta Features documentation.

Output Control contents:

*Option (setting)
*Output Frequency (setting)

*Option (setting)
Available only when all coupling participants support restarts. Specifies when restart points are gen-
erated.

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).

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
Data Model Settings

• 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.

– 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 in
the System Coupling User's Guide.

• The generation of ANSYS EnSight-compatible coupling results is a released feature, but the
settings to control their output frequency are available as beta functionality. For more inform-
ation, see Settings for Generating ANSYS EnSight-Compatible Postprocessing Output in the
System Coupling Beta Features documentation.

*Output Frequency (setting)

Available when the Output Control / Option (p. 7) is set to Step Interval or Iteration Interval.
Specifies the frequency at 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 (object)

Contains settings that define the coupling interfaces and the details for each data transfer included in
the interfaces.

Interfaces are assigned 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.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Interface (object)

Interface object names must be unique within the analysis, must be in ASCII format, and cannot include
forward slashes (/) or the colon character (:).

Coupling Interface contents:

Mapping Control (singleton)
Side (object)
Data Transfer (object)

Mapping Control (singleton)

Contains settings that, for the interface being defined, determine the mapping algorithm to be used.
Currently, the only mapping control available is a setting to control the absolute gap tolerance for
surface mapping.

Mapping Control contents:

Gap Tolerance (singleton)

Gap Tolerance (singleton)

Available only when mapping will occur between surface regions. Contains settings that determine
the interface's overall gap settings, which in turn control what locations are mapped.

If the gap tolerance is smaller than the gap between the source element and the target element,
the elements are not mapped to one another.

Gap Tolerance contents:

Absolute Gap Value (setting)

Absolute Gap Value (setting)

Available when the Gap Tolerance (p. 9) singleton is present. Sets the absolute gap tolerance
value.

Accepts decimal values greater than or equal to 0 in meters. Default value is 0.0 [m].

Side (object)
Contains settings that, for the interface being defined, define details for each side of the coupling
interface.

System Coupling assigns a name to each interface side and uses it to identify the side. The objects
for the interface sides are named One and Two.

Side contents:
Coupling Participant (setting)
*Region List (setting)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
Data Model Settings

Coupling Participant (setting)

Defines the object name assigned and used by System Coupling to identify the participant associated
with the side of the interface being defined.

When a display name is not defined, this value is shown in user-facing communications.

*Region List (setting)

Defines the collection of the regions on the interface side that can send or receive data. Required
for the creation of data transfers.

Data Transfer (object)

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 (:).

Data Transfer contents:

*Convergence Target (setting)
*Ramping Option (setting)
*Relaxation Factor (setting)
Stabilization (singleton)

*Convergence Target (setting)

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.

*Ramping Option (setting)

Determines the behavior of the ramping algorithm for specified quantity.

Ramping is used by System Coupling to slow the application of the source-side value on the target
side of the interface.

Possible values:

• None

No ramping is applied; the full data transfer value is applied to the target side of the interface
for all coupling iterations. (default value)

• Linear

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Interface (object)

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 in-
creased during each coupling iteration until the specified minimum number of coupling it-
erations, , 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.

For more detailed information, see Ramping Algorithm.

*Relaxation Factor (setting)

Specifies the factor multiplying the current data transfer values for specified quantity when under-
relaxing 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.

Stabilization (singleton)
Contains settings that control the application and behavior of Quasi-Newton stabilization methods
to the parent data transfer.

Stabilization contents:
*Option (setting)
*Maximum Retained Time Steps (setting)
*Initial Relaxation Factor (setting)

For more detailed information, see Quasi-Newton Stabilization Algorithm in the System Coupling
User's Guide.

*Option (setting)
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.

*Maximum Retained Time Steps (setting)

Available when the Stabilization / Option (p. 11) is set to Quasi-Newton. Specifies the maximum
number of time steps to be retained in the Quasi-Newton history.

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.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 11
Data Model Settings

*Initial Relaxation Factor (setting)

Available when the Stabilization / Option (p. 11) is set to Quasi-Newton. 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 relax-
ation factor is applied at the start of every coupling step. Otherwise, it is applied only to the first
coupling step.

Coupling Participant (object)

Coupling participant objects are assigned names which are then used by System Coupling to identify
the participant. Participants are named according to the convention <Participant-#>, where "Participant"
is the Participant Type (p. 13) and "#" is an index indicating the order in which the participant was
loaded. For example, if CFX is loaded first and Mechanical is loaded second, then their participant names
are CFX-1 and MAPDL-2, respectively.

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.

Coupling Participant contents:

*Display Name (setting)
Participant Type (setting)
Participant Analysis Type (setting)
Restarts Supported (setting)
Execution Control (singleton)
*External Data File (setting)
Update Control (singleton)
Coordinate Transformation (singleton)
Region (object)
Variable (object)

*Display Name (setting)

Participant name to be displayed in user-facing communications.

Specified by the <DisplayName> element in the participant's SCP file.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
12 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Participant (object)

Participant Type (setting)

Indicates the application participating in the coupled analysis.

Specified by the <Type> element in the participant's SCP file.

Possible values:

• AEDT

• CFX

• FLUENT

• FORTE

• MAPDL

• EXTERNAL DATA: Used for static participants, such when a static data file is used instead of a solver,
for workflows involving System Coupling in Workbench. When selected, the Execution Control (p. 13)
singleton does not exist and System Coupling accesses the XML data file specified by the External
Data File (p. 16) setting.

• DEFAULT: Used when no participant type is specified. (default value)

Participant Analysis Type (setting)

Available when Participant Type (p. 13) is set to a value of DEFAULT or FORTE. Specifies the type
of analysis that the participants is running.

Specified by the <AnalysisType> element in the participant's SCP file.

Possible values:

• Steady

• Transient

Restarts Supported (setting)

Available when Participant Type (p. 13) is set to a value of DEFAULT. Indicates whether restarts are
supported by the participant.

Specified by the <RestartsSupported> element in the participant's SCP file.

Possible values:

• False (default)

• True

Execution Control (singleton)

Available when Participant Type (p. 13) is set to a value other than EXTERNAL DATA.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 13
Data Model Settings

Contains settings that control the participant's execution in the coupled analysis. Values are populated
from the <Execution Control> element of participant's SCP file. When this element is omitted,
System Coupling populates values based on participant types.

Execution Control contents:

*Option (setting)
*Executable (setting)
*Working Directory (setting)
*Initial Input (setting)
*Parallel Fraction (setting)
*Additional Arguments (setting)

*Option (setting)
Specifies how System Coupling finds the solver executable file to be used to start the participant.

Possible values:

• Program Controlled: Available when Participant Type (p. 13) 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 (p. 13) is set to a value other than EXTERNAL DATA, then
System Coupling runs the file specified by the Executable (p. 14) 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).

When used, System Coupling will not start the participant using either this command or any
of the other commands that automatically start participants, but will wait for the participant
to connect to it during participant startup.

Note:

This option is available but not recommended for runs in either of System
Coupling's user interfaces.

*Executable (setting)
Available when the Execution Control / Option (p. 14) is set to User Defined.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
14 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Participant (object)

Specifies the path and filename of the solver executable file to be used to start the participant.
Default value is None.

*Working Directory (setting)

Specifies the participant's working directory.

For coupled analyses set up from the command line, by default this value is the directory defined
by the <WorkingDirectory> element of the participant's SCP file. If not defined, defaults to
System Coupling's working directory.

For coupled analyses set up in Workbench to be run from the command line (as described in Running
a Workbench Setup in a User Interface, you must set this value directly in the data model before
starting the run.

*Initial Input (setting)

Solver input file to be used for the initial coupling run.

For coupled analyses set up from the command line, by default this value is the file specified by
the <InitialInput> 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 (p. 15) setting.

To run a coupled analysis set up in Workbench from the command line (as described in Running
a Workbench Setup in a User Interface), you must set this value directly in the data model before
starting the run.

Acceptable Initial Input 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 file (.def or .res), 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 exten-
sion, 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.

– 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 a FORTE participant, it must refer a Forte solver input file (.ftsim), such as
Forte_GDI.ftsim.

• For an MAPDL participant, it must refer to an MAPDL solver input file (.dat), such as ds.dat.

*Parallel Fraction (setting)

Used to partition resources across coupling participants that are running in parallel.

Specifies the core count or fraction of compute resources to be allocated to the participant.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 15
Data Model Settings

Accepts real values ≥ 0. Default value is 1.

For more detailed information, see Resource Allocation Fractions in the System Coupling User's
Guide

*Additional Arguments (setting)

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 System
CouplingSystem Coupling's participant partitioning functionality. However, you should not use the
Additional Arguments setting to supply parallel arguments if the case is set up in such a way that
a parallel partitioning algorithm will be applied. For more information on using parallel additional
arguments, see Parallel Processing for Participant Products.

Default value is None.

*External Data File (setting)

Available when the Participant Type (p. 13) is set to EXTERNAL DATA (i.e., only available for workflows
involving a Workbench setup).

Specifies the path and filename of the XML data file containing the information to be consumed by
System Coupling.

Update Control (singleton)

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.

Update Control contents:

*Option (setting)
*Update Frequency (setting)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
16 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Participant (object)

*Option (setting)
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)

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 (p. 17) setting.

• 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 parti-
cipants 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 sup-
pressed participant's last update.

*Update Frequency (setting)

Available when the Update Control / Option (p. 17) 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.)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 17
Data Model Settings

Accepts integer values greater than or equal to 1. Default value is 1.

Tip:

Support for the Step Interval, Suspended, and Update Frequency options by all parti-
cipants is available as beta functionality. For more information, see Participant Update
Control Settings in the System Coupling Beta Features documentation.

Coordinate Transformation (singleton)

Settings defined under the Coordinate Transformation singleton allow you to define coordinate
transforms to control the positioning of the participant's geometry.

Note:

Currently, Coordinate Transformation settings are available only for scalar data transfers.

Transformations must be added before the analysis is initialized command is run. 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 data
model validation error will be reported if this condition is encountered.

Note:

Currently, the Coordinate Transformation settings are available only for:

• Scalar data transfers

• AEDT, Fluent, and MAPDL participants

Update Control contents:

*Option (setting)
*Origin (setting)
*Rotation XY (setting)
*Rotation YZ (setting)
*Rotation ZX (setting)

For more information, see Setting Geometry Transformations for Models with Different Orientations
in the System Coupling User's Guide.

*Option (setting)
Specifies whether a transformation is defined for the coordinate system of the participant's geometry.

Possible values:

• None: No coordinate transformation is defined. Default value. Only possible value if a data transfer
of vector quantities exists for the participant.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
18 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Participant (object)

• New Origin and Rotations: A coordinate transformation is defined. The transformed coordinate
system is defined according the values of the Origin (p. 19), Rotation XY (p. 19), Rotation
YZ (p. 19), and Rotation ZX (p. 20) settings.

*Origin (setting)
Available when the Coordinate Transformation / Option (p. 18) is set to New Origin and Rota-
tions. Defines the new origin for the transformed coordinate system.

When a transformation is defined for a participant, it is applied to all the participant's regions

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 (setting)
Available when the Coordinate Transformation / Option (p. 18) is set to New Origin and Rota-
tions. 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 illus-
tration, 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 (setting)
Available when the Coordinate Transformation / Option (p. 18) is set to New Origin and Rota-
tions. 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 fol-
lowing 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.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 19
Data Model Settings

• When a rotation setting value is changed, its unit is automatically applied to rotation settings
with unchanged values.

*Rotation ZX (setting)
Available when the Coordinate Transformation / Option (p. 18) is set to New Origin and Rota-
tions. 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.

Region (object)
Contains settings that define the details for each of the participant's regions.

Each region object has a name that is specified by the <Name> element in the participant's SCP file
and that is used by System Coupling to identify the region object.

Region object names must be unique within the analysis, must be in ASCII format, and cannot include
forward slashes (/) or the colon character (:).

Region contents:
*Display Name (setting)
Input Variables (setting)
Output Variables (setting)
Topology (setting)

*Display Name (setting)

Defines the region name to be displayed in user-facing communications. Specified by the region's
<DisplayName> element in the participant's SCP file.

Input Variables (setting)

Specifies the variables for which the region can receive data.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
20 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Participant (object)

Blank values are permitted.

Output Variables (setting)

Specifies the variables for which the region can send data.

Blank values are permitted.

Topology (setting)
Specifies the type of data being transferred from/to the region.

Possible values:

• 2 = Surface

• 3 = Volume

• 4 = Planar Surface

Note:

The number options listed above are used to indicate the corresponding topology in
command-line analyses.

Variable (object)
Contains settings that define the details for each of the variables for which the participant can send
or receive data.

Each variable object has a name that is specified by the <Name> element in the participant's SCP
file and that is used by System Coupling to identify the variable object.

Variable object names must be unique within the analysis, must be in ASCII format, and cannot include
forward slashes (/) or the colon character (:).

Variable contents:
*Display Name (setting)
Quantity Type (setting)
Location (setting)

*Display Name (setting)

Defines the variable name to be displayed in user-facing communications. Specified by the variable's
<DisplayName> element in the participant's SCP file.

Quantity Type (setting)

Quantity type of the variable being transferred.

Required.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 21
Data Model Settings

Possible values:

• Convection Reference Temperature

• Force

• Heat Rate

• Heat Rate Density

• Heat Transfer Coefficient

• Incremental Displacement

• Temperature

Location (setting)
Location of the variable being transferred.

If not defined, then set to Node by default.

Possible values:

• Node (default value)

• Element

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
22 of ANSYS, Inc. and its subsidiaries and affiliates.
Commands
This section provides detailed information on the commands you can use to interact with System
Coupling from the command line, whether from System Coupling's command-line interface (CLI) or
from the Command Console tab of its graphical user interface (GUI).

Commands are listed in alphabetical order. For details on a given command, follow click it in the list
below:
AddDataTransfer
AddDataTransferByDisplayNames
AddInterface
AddInterfaceByDisplayNames
AddParticipant
ClearState
CreateInterfacesAndDataTransfers
CreateRestartPoint
DatamodelRoot
DeleteObject
ExecuteCommandString
GetChildNames
GetChildren
GetCommandAndQueryNames
GetErrors
GetErrorsXML
GetExecutionCommand
GetParameter
GetParameterOptions
GetRegionNamesForParticipant
GetState
ImportSystemCouplingInputFile
Initialize
LoadParticipants
Open
PartitionParticipants
PrintSetup
PrintState
ReadScriptFile

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 23
Commands

Save
SetExpertSettings
SetState
Shutdown
Solve
StartParticipants
Step
WriteCsvChartFiles

AddDataTransfer
Adds a single data transfer based on arguments that specify the interface, target side, and variables to
be associated with each side of the interface.

Requires that you specify variables using their internal names, as described below in Essential Keyword
Arguments (p. 24). To add a two-way data transfer on an interface, you must run this command twice,
once for each direction.

Cannot be run after participants have been started.

Note:

To specify the variables by their display names, use the AddDataTransferByDisplay-

Names (p. 24) command.

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.

Returns the name of the data transfer created.

Essential Keyword Arguments

Interface : str
String indicating the internal object name of the interface on which the data transfer is to be created.

TargetSide : str
String indicating the side of the interface to receive the data transfer variable. Possible values:

• One

• Two

SideOneVariable : str
String specifying the internal object name of the variable associated with side One of the interface. If
TargetSide is set to:

• One: this is the variable to be received by side One.

• Two: this is the variable to be sent by side One.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
24 of ANSYS, Inc. and its subsidiaries and affiliates.
 AddDataTransferByDisplayNames

SideTwoVariable : str
String specifying the internal object name of the variable associated with side Two of the interface. If
TargetSide is set to:

• Two: this is the variable to be received by side Two.

• One: the is the variable to be sent by side Two.

Return Type
str

Example 1: Add a two-way data transfer using internal variable names

>>> AddDataTransfer(
Interface = "Interface-1",
TargetSide = "One",
SideOneVariable = "FORC",
SideTwoVariable = "Total Force")

>>> AddDataTransfer(
Interface = "Interface-1",
TargetSide = "Two",
SideOneVariable = "INCD",
SideTwoVariable = "MeshDisplacement")

AddDataTransferByDisplayNames
Adds a single data transfer based on arguments that specify the interface, target side, and variables to
be associated with each side of the interface.

Requires that you specify variables using their display names, as described below in Essential Keyword
Arguments (p. 25).To add a two-way data transfer on an interface, you must run this command twice,
once for each direction.

Cannot be run after participants have been started.

Note:

To specify the variables by their internal names, use the AddDataTransfer (p. 24) com-
mand.

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.

Returns the name of the data transfer created.

Essential Keyword Arguments

Interface : str
String indicating the object display name of the interface on which the data transfer is to be created.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 25
Commands

TargetSide : str
String indicating the side of the interface to receive the data transfer variable. Possible values:

• One

• Two

SideOneVariable : str
String specifying the object display name of the variable associated with side One of the interface. If
TargetSide is set to:

• One: this is the variable to be received by side One.

• Two: this is the variable to be sent by side One.

SideTwoVariable : str
String specifying the object display name of the variable associated with side Two of the interface. If
TargetSide is set to:

• Two: this is the variable to be received by side Two.

• One: the is the variable to be sent by side Two.

Return Type
str

Examples
Example 2: Add a two-way data transfer using variable display names

>>> AddDataTransferByDisplayNames(
Interface = "Interface-1",
TargetSide = "One",
SideOneVariable = "Temperature",
SideTwoVariable = "Temperature")

>>> AddDataTransferByDisplayNames(
Interface = "Interface-1",
TargetSide = "Two",
SideOneVariable = "Heat Loss",
SideTwoVariable = "Heat Rate Density")

AddInterface
Adds a single interface based on the participant and region names specified as arguments for each side
of the interface.

Requires that you specify participants and regions using their internal object names as described below
in Essential Keyword Arguments (p. 27).

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
26 of ANSYS, Inc. and its subsidiaries and affiliates.
 AddInterfaceByDisplayNames

Cannot be run after participants have been started.

Note:

To specify the participants and regions by display names, use the AddInterfaceByDis-
playNames (p. 27) command.

Interfaces are assigned 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.

Returns the name of the coupling interface created.

Essential Keyword Arguments

SideOneParticipant : str
String indicating the internal object name of the participant to be associated with side One of the interface.

SideTwoParticipant : str
String indicating the internal object name of the participant to be associated with side Two of the interface.

SideOneRegions : list
List specifying the internal object name(s) of region(s) to be added to side One of the interface.

SideTwoRegions : list
List specifying the internal object name(s) of region(s) to be added to side Two of the interface.

Return Type
str

Examples
Example 3: Add an interface using internal participant and region names

>>> AddInterface(
SideOneParticipant = "AEDT-1",
SideOneRegions = ["Volume5"],
SideTwoParticipant = "MAPDL-2",
SideTwoRegions = ["FVIN_1"])

AddInterfaceByDisplayNames
Adds a single interface based on the participant and region names specified as arguments for each side
of the interface.

Requires that you specify participants and regions using their object display names, as described below
in Essential Keyword Arguments (p. 28).

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 27
Commands

Cannot be run after participants have been started.

Note:

To specify the participants and regions by their internal names, use the AddInter-
face (p. 26) command.

Interfaces are assigned 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.

Returns the name of the coupling interface created.

Essential Keyword Arguments

SideOneParticipant : str
String indicating the object display name of the participant to be associated with side One of the interface.

SideTwoParticipant : str
String indicating the object display name of the participant to be associated with side Two of the interface.

SideOneRegions : list
List specifying the object display name(s) of region(s) to be added to side One of the interface.

SideTwoRegions : list
List specifying the object display name(s) of region(s) to be added to side Two of the interface.

Return Type
str

Examples
Example 4: Add an interface using participant and region display names

>>> AddInterfaceByDisplayNames(
SideOneParticipant = "ANSYS Electronics Desktop",
SideOneRegions = ["Core"],
SideTwoParticipant = "Fluid Flow (Fluent)",
SideTwoRegions = ["Core 2"])

AddParticipant
Given a single input file containing participant coupling information, reads the specified file, pushes
the participant's information to the data model, and returns the name of the added participant.

When run, this command adds the new participant to the analysis without removing any interfaces or
data transfers created previously.

Cannot be run after participants have been started.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
28 of ANSYS, Inc. and its subsidiaries and affiliates.
 CreateInterfacesAndDataTransfers

Essential Keyword Arguments

InputFile : ReadableFileName
Name of the input file to be read. Currently supported formats are System Coupling Participant (SCP)
setup files, Forte input (FTSIM) files, and FMU (FMU) files (Beta).

Return Type
str

Examples
Example 5: Add a participant to a coupled analysis

>>> AddParticipant(InputFile = "MAPDL.scp")

'MAPDL-1'

ClearState
Clears the state of System Coupling, removing all data model items, setting values, and calculated values.

Cannot be run after participants have been started.

Supported Keyword Arguments

None

Return Type
NoneType

CreateInterfacesAndDataTransfers

Important:

This command will be deprecated. It is recommended that you use the AddInter-
face (p. 26) and AddDataTransfer (p. 24) commands instead.

Creates one or more coupling interfaces and data transfers between participants.

By default, creates interfaces when there are only two participants and/or when each participant has
only one region, using all available regional data not already accounted for in the data model; all regions
that can be used to create valid data transfers are included on the interface(s). When given optional
arguments, behaves as described below in Optional Keyword Arguments (p. 30).

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 29
Commands

An interface must have at least one valid data transfer; if no valid data transfers are possible, then no
interface is created. When interfaces are created using this command, all valid data transfers are created
automatically in the following order:

• Heat Transfer Coefficient and Convection Reference Temperature (HTC+Tref )

• Heat Rate

Tip:

If you want a heat rate data transfer but an HTC+Tref data transfer has already been
automatically created, use DeleteObject (p. 33) to remove the HTC+Tref data
transfer and run the AddDataTransfer (p. 24) command to create the heat rate
transfer.

• Temperature

• Force

• Incremental Displacement

The number of interfaces generated is determined by regional support of data transfer quantities, as
follows:

• When there is full regional support of the same quantities (i.e., all regions on both sides of the interface
support the same quantities), then only one interface is created.

• When there is only partial regional support of one or more quantities (i.e., only a subset of regions on one
or both sides of the interface support the same quantities), then multiple interfaces are created (unless
other interface creation rules or data transfer creation rules prevent it).

A reissue of this command creates new interfaces from any regional data not already accounted for in
the data model but does not affect existing interfaces.

Optional Keyword Arguments

Side1ParticipantName : str
String indicating the internal object name of the participant to be associated with side One of the interface.
Required when there are more than two participants.

Side2ParticipantName : str
String indicating the internal object name of the participant to be associated with side Two of the interface.
Required when there are more than two participants.

Side1ParticipantDisplayName : str
String indicating the display name of the participant to be associated with side One of the interface. If the
participant display name is unique, may be used instead of Side1ParticipantName.

Side2ParticipantDisplayName : str
String indicating the display name of the participant to be associated with side Two of the interface. If the
participant display name is unique, may be used instead of Side2ParticipantName.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
30 of ANSYS, Inc. and its subsidiaries and affiliates.
 CreateInterfacesAndDataTransfers

Side1RegionNames : list
List specifying the internal object name(s) of region(s) to be added to side One of the interface. When
used, only the specified regions are considered when creating interfaces and data transfers.

Side2RegionNames : list
List specifying the internal object name(s) of region(s) to be added to side Two of the interface. When
used, only the specified regions are considered when creating interfaces and data transfers.

Side1RegionDisplayNames : list
List specifying the display name(s) of region(s) to be added to side One of the interface. When used, only
the specified regions are considered when creating interfaces and data transfers. If the region display
name(s) in the list are unique, may be used instead of Side1RegionNames.

Side2RegionDisplayNames : list
List specifying the display name(s) of region(s) to be added to side Two of the interface. When used, only
the specified regions are considered when creating interfaces and data transfers. If the region display
name(s) in the list are unique, may be used instead of Side2RegionNames.

Return Type
NoneType

Examples
Example 6: Automatically include all regions when there are only two participants.

>>> CreateInterfacesAndDataTransfers()

Example 7: Automatically include all regions for the specified participants. Participants are specified
by display names.

>>> CreateInterfacesAndDataTransfers(Side1ParticipantDisplayName = 'Mech-Structural',

Side2ParticipantDisplayName = 'CFX-Fluids')

Example 8: Specify regions to be included (participant names required). Participants and regions
are both specified by internal names.

>>> CreateInterfacesAndDataTransfers(Side1ParticipantName = 'MAPDL-1', Side2ParticipantName = 'CFX-2',

Side1RegionNames = ['FSIN_1'], Side2RegionNames = ['Interface'])

Example 9: Specify regions to be included (participant names required). Region for side One is
specified using the display name.

>>> CreateInterfacesAndDataTransfers(Side1ParticipantName = 'MAPDL-1', Side2ParticipantName = 'CFX-2',

Side1RegionDisplayNames = ['Fluid-Structure Interface 1'], Side2RegionNames = ['Interface'])

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 31
Commands

CreateRestartPoint
Interactive command that creates a restart point at the end of the last completed coupling step.

Signals System Coupling and all coupling participants that a restart point should be created before the
next coupling step begins. The restart point is created in addition to restart points created by the
OutputControl (p. 7) setting in the data model.

Note:

Some participants write their restart files only when the coupling run resumes, so their files
are not available immediately after the CreateRestartPoint (p. 32) command is
issued.

Results information for the coupling step is written to a file named according to the convention Res-
ults_#.h5, where "_#" is the number of the coupling step. By default, the restart files are written to the
SyC directory, which is automatically created by System Coupling when restart points are created.

Supported Keyword Arguments

None

Return Type
NoneType

DatamodelRoot
Returns the root object of the System Coupling data model.

Supported Keyword Arguments

None

Return Type
ObjectPath

Examples
Example 10: Use DatamodelRoot to get the path of a specified participant

>>> DatamodelRoot().CouplingParticipant['MAPDL-1']

'/System Coupling/CouplingParticipant:MAPDL-1'

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
32 of ANSYS, Inc. and its subsidiaries and affiliates.
 GetChildNames

DeleteObject
Deletes the specified object from the database.

Essential Keyword Arguments

ObjectPath : str
String indicating the path of the object to be deleted.

Return Type
NoneType

Examples
Example 11: Delete a database object

>>> DeleteObject(ObjectPath = '/SystemCoupling/CouplingInterface:Interface-1')

ExecuteCommandString
Executes a command in the Python interpreter, enabling you to issue a generic Python command to
System Coupling.

Essential Keyword Arguments

CommandString : str
String indicating the command to be executed.

Return Type
object

Examples
Example 12: Execute a command string to print the state of a singleton

>>> ExecuteCommandString(CommandString = 'DatamodelRoot().OutputControl.PrintState()')

OutputControl
Option = LastStep

GetChildNames
Gets the names of the specified object's children and returns them as a list.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 33
Commands

Essential Keyword Arguments

ObjectPath : ObjectPath
Path of the object for which a list of child names is returned.

Return Type
list

Examples
Example 13: Get a list of names for child interfaces

>>> DatamodelRoot().CouplingInterface.GetChildNames()

['Interface-1', 'Interface-2']

GetChildren
Gets the full path to each of the specified object's children and returns them as a list.

Essential Keyword Arguments

ObjectPath : ObjectPath
Path of the object for which a list of its children's paths is returned.

Return Type
list

Examples
Example 14: Getting a list of paths for interfaces defined under CouplingInterface

>>> DatamodelRoot().CouplingInterface.GetChildren()

['/SystemCoupling/CouplingInterface:Interface-1', '/SystemCoupling/CouplingInterface:Interface-2']

GetCommandAndQueryNames
Gets all of the System Coupling command and query names available for coupled analyses and returns
them as a formatted list.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
34 of ANSYS, Inc. and its subsidiaries and affiliates.
 GetErrorsXML

Supported Keyword Arguments

None

Return Type
list

GetErrors
If errors exist, returns a dictionary with the errors as keys and the content of the errors as values; other-
wise, returns an empty list.

See also: GetErrorsXML (p. 35)

Supported Keyword Arguments

None

Return Type
list

GetErrorsXML
If errors exist, returns them in XML format within a <validationmessages> element; otherwise,
returns an empty <validationmessages/> element.

See also: GetErrors (p. 35)

Supported Keyword Arguments

None

Return Type
object

Examples
Example 15: List returned when validation errors exist

>>> GetErrorsXML()

'<validationmessages><message><type>Bounds</type><subtype>BelowLower</subtype>
<entity>/SystemCoupling</entity><property>CouplingControl/AnalysisType/DurationControl/
NumberOfSteps</property><value>1</value></message></validationmessages>'

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 35
Commands

GetExecutionCommand
Gets the execution command needed to start the specified participant.

Essential Keyword Arguments

ParticipantName : str
Name of the participant for which the execution command will be returned.

Return Type
NoneType

Examples
Example 16: Get a participant's execution command

>>> GetExecutionCommand(ParticipantName = 'MAPDL-1')

...

'"C:\\Program Files\\ANSYS Inc\\v201\\ansys\\bin\\winx64\\ANSYS201.exe" -b nolist -s noread

-o MAPDL-1.out -scport 9525 -schost MYMACHINE.win.ansys.com -scname "MAPDL-1" -scid="" -sclic=0@
-i ds.dat'

GetParameter
Gets the value of the specified System Coupling parameter (setting).

Essential Keyword Arguments

ObjectPath : str
Path of the object under which the specified parameter is defined.

Name : object
String indicating the object name of the parameter for which a value is returned.

Return Type
object

GetParameterOptions
Gets the available options for the value of the specified System Coupling parameter (setting) and returns
them as a list.

If called for a non-string valued parameter or a parameter that does not have a finite set of available
options defined, then an empty list ('[]') is returned.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
36 of ANSYS, Inc. and its subsidiaries and affiliates.
 GetRegionNamesForParticipant

This query should be used only for parameters that are known to exist in the data model state.

Essential Keyword Arguments

ObjectPath : str
Path of the object under which the specified parameter is defined.

Name : object
String indicating the internal name of the parameter for which a list of options is returned

Return Type
list

Examples
Example 17: Get regions for a given participant

>>> GetParameterOptions(ObjectPath='/SystemCoupling/CouplingControl/AnalysisType', Name='Option')

('Steady', 'Transient')

GetRegionNamesForParticipant
Gets all the specified participant's regions.

Returns a dictionary with the regions as keys and the corresponding display names as values.

Essential Keyword Arguments

ParticipantName : str
String indicating the participant for which regions are returned.

Return Type
dict

Examples
Example 18: Get regions for a given participant

>>> GetRegionNamesForParticipant(ParticipantName = 'CFX-2')

{'plate': 'plate', 'coupling': 'coupling'}

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 37
Commands

GetState
Gets the state of a specified data model container (can be either a singleton or an object).

Returns a dictionary with parameters (settings) as keys and the parameter values as values.

If given a container path that doesn't match a stored path, then returns an empty dictionary, regardless
of path validity.

Note that this command can also be used with DatamodelRoot (p. 32); in this case, no argument
is required.

Essential Keyword Arguments

ObjectPath : str
Path of the container for which a state is returned.

Return Type
dict

Examples
Example 19: Use with ObjectPath to get the state of a singleton

>>> GetState(ObjectPath = '/SystemCoupling/CouplingControl/AnalysisType')

{'DurationControl': {'EndTime': '0.5 [s]', 'Option': 'EndTime'}, 'Option': 'Transient',

'StepControl': {'MaximumIterations': 1, 'TimeStepSize': '0.1 [s]',
'MinimumIterations': 1}}

Example 20: Use with DatamodelRoot to get the state of a singleton

>>> DatamodelRoot().CouplingControl.AnalysisType.DurationControl.GetState()

{'EndTime': '1.0 [s]', 'Option': 'EndTime'}

ImportSystemCouplingInputFile
Reads the specified System Coupling SCI file and pushes its information into the data model. The SCI
file is the required System Coupling input format for the initial command-line run of a coupled analysis
set up in Workbench.

After the initial command-line run based on an imported SCI file, a reissue of the ImportSystem-
CouplingInputFile command is unnecessary and is not recommended.

Cannot be run after participants have been started.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
38 of ANSYS, Inc. and its subsidiaries and affiliates.
 Initialize

Essential Keyword Arguments

FilePath : ReadableFileName
Path and filename for the SCI file to be read.

Return Type
NoneType

Examples
Example 21: Import an SCI file for an initial run

>>> ImportSystemCouplingInputFile(FilePath = 'scInput.sci')

Initialize
Interactive command that initializes a coupled analysis.

Initialization includes preparing System Coupling, making connections between System Coupling and
all participants, starting participants (if necessary), and writing participant build information to the
Transcript and Log.

For analyses with differently oriented models, geometry transformations must be defined before running
the Initialize command.

This command will raise an exception if another instance of System Coupling is solving in the current
working directory.

Note:

If the ExecutionControl / Option for a participant is set to ExternallyManaged,

then System Coupling will not start the participant using either this command or any of the
other commands that automatically start participants. The user is expected to manually start
the participant. This function will not return until all participants have been connected.

Supported Keyword Arguments

None

Return Type
NoneType

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 39
Commands

LoadParticipants
Given a list of input files containing participant coupling information, reads the specified files and pushes
their information into the data model.

When run, this command removes any interfaces and data transfers created previously and creates new
interfaces based on the available regional information.

Cannot be run after participants have been started.

Essential Keyword Arguments

InputFiles : list
List of the files for participants to be loaded. Currently supported formats are System Coupling Participant
(SCP) setup files, Forte input (FTSIM) files, and FMU (FMU) files (Beta).

Return Type
NoneType

Examples
Example 22: Load participants for a coupled analysis

>>> LoadParticipants(InputFiles=['mechanical.scp', 'cfx.scp'])

Open
Reads the state of a coupled analysis. The state consists of settings to populate the datamodel and
results to restart the analysis at the end of a specified coupling step.

Results files may correspond either to coupling iterations or coupling steps, depending on the analysis
type and the types of participants involved. For more information, see Results Files (Results_*#.h5)
in the System Coupling User's Guide.

Settings are stored in a file named Settings.h5. For more information, see Settings File (Set-
tings.h5) in the System Coupling User's Guide

By default, this command looks for the SyC subdirectory in System Coupling's current working directory.
By default, if multiple Results files exist, it opens the most recent one.

When given optional arguments, behaves as described below in Optional Keyword Arguments (p. 40).

Cannot be run after participants have been started.

Optional Keyword Arguments

FilePath : WritableDirectory
Working directory containing the SyC directory (which contains the .h5 files to be read).

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
40 of ANSYS, Inc. and its subsidiaries and affiliates.
 Open

The directory path must contain only ASCII characters.

CouplingStep : int
Integer specifying the coupling step at which the coupled analysis is restarted. When used, System Coupling
reads the corresponding Results_step<#>.h5 file in the specified directory and restarts the analysis
at the end of the specified coupling step.

If the simulation's Results files are associated with coupling iterations, then System Coupling prints
an error message indicating this.

CouplingIteration : int
Integer specifying the coupling iteration at which the coupled analysis is restarted. When used, System
Coupling reads the corresponding Results_iter<#>.h5 file in the specified directory and restarts the
analysis at the end of the specified coupling iteration.

If the simulation's Results files are associated with coupling steps, then System Coupling prints an
error message indicating this.

Return Type
NoneType

Examples
Example 23: Read the last solved coupling step or iteration from the default directory

>>> Open()

Example 24: Read coupling step 6 from the specified working directory for a transient analysis

>>> Open(FilePath = 'WorkingDirectoryWithResults', CouplingStep = 6)

Example 25: Read coupling iteration 2 from the specified working directory for a steady analysis

>>> Open(FilePath = 'WorkingDirectoryWithResults', CouplingIteration = 2)

Example 26: Read analysis settings from a specified working directory containing only a Settings
file

>>> Open(FilePath = 'WorkingDirectoryWithOnlySettings')

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 41
Commands

PartitionParticipants
Provides a utility for setting the parallel algorithm, parallel partitioning fractions for each participant,
and machine list information.

At least one participant must be defined for this command to be used. Use of this command is not re-
commended if participants are already running.

Note:

An AEDT participant cannot be run in distributed parallel; it will run on one machine, regard-
less of the number of machines allocated by this command.

For more detailed information, see Parallel Processing for Coupling Participants.

Optional Keyword Arguments

AlgorithmName : str
Name of the partitioning algorithm.

Possible values:

• SharedAllocateMachines (default value)

• SharedAllocateCores

• DistributedAllocateMachines

• DistributedAllocateCores

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 ad-
vantage of all the allocated resources. The other partitioning methods are provided to handle situ-
ations where not enough resources are available to run the same machines.

For more detailed information, see Participant Partitioning Algorithms.

NamesAndFractions : list
List of tuples specifying the fractions of core count applied for each participant

Each tuple must have the ParticipantName as its first item and the associated fraction as its
second item. If this parameter is omitted, then cores will be allocated for all participants set in the
data model.

For more detailed information, see Resource Allocation Fractions.

MachineList : list
List of dictionaries specifying the machines available for distributed run. Each dictionary must have:

• machine-name as a key with the machine's name as its value

• core-count as a key with the number of cores for that machine as its value

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
42 of ANSYS, Inc. and its subsidiaries and affiliates.
 PrintState

Providing this argument will override any machine-list information detected from the scheduler
environment and any information provided by the --cnf command-line argument."

Return Type
NoneType

Examples
Example 27: Allocate cores for participants based on fraction specified for each participant

In this example, the SOLVER-1 participant gets 6 cores and the SOLVER-2 participant gets 14 cores
allocated on machine 'host-1'. No cores are shared between the participants.

>>> PartitionParticipants(AlgorithmName = 'DistributedAllocateCores',NamesAndFractions = [('SOLVER-1', 0.3),

('SOLVER-2', 0.7)], MachineList = [{'machine-name' : 'host1', 'core-count' : 10},{'machine-name' : 'host2',
'core-count' : 10}])

PrintSetup
Interactive command that prints the "Summary of Coupling Setup" to the System Coupling Transcript
and Log.

Supported Keyword Arguments

None

Return Type
NoneType

PrintState
Prints the data model state to the System Coupling Transcript.

By default, prints the state for the entire data model.

If given optional arguments, behaves as described below in Optional Keyword Arguments (p. 43).

Optional Keyword Arguments

ObjectPath : str (default = None)
String indicating the path of the object for which the state is printed. When used, the state is printed only
for the specified object.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 43
Commands

FilePath : str (default = None)

String indicating the path and filename of the file to which the state is printed. When used, the state is
printed to the specified file instead of the command console.

FileMode : str (default = w)

String indicating the mode to be used when the state is printed. Possible values:

• w: Write mode (default value); subsequent actions are written to a new file.

• a: Append mode; actions are appended to an existing file.

ExplicitSettingsOnly : bool (default = False)

Boolean indicating whether all settings is included (False, default) or only the explicit settings is included
(True) when the state is printed.

Return Type
NoneType

Examples
Example 28: Print the state of a specified singleton

>>> PrintState(ObjectPath = '/SystemCoupling/CouplingControl/AnalysisType/DurationControl')

CouplingControl
AnalysisType
DurationControl
EndTime = 1.0 [s]
Option = EndTime

ReadScriptFile
Reads a script file in the command environment.

Essential Keyword Arguments

FileName : ReadableFileName
Name of the script file that is to be read.

Return Type
NoneType

Examples
Example 29: Read a Python script file

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
44 of ANSYS, Inc. and its subsidiaries and affiliates.
 Save

>>> ReadScriptFile(FileName = 'run.py')

Save
Saves the state of a coupled analysis.

Cannot be run after the coupling run has been initialized. 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.

• Analysis settings are written to a single Settings file which can be used to reload analysis settings.

• The last completed coupling step or iteration is written to a Results file which can be used to restart the
analysis at the end of that step or iteration.

• 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.

Returns a Boolean value of True if the files were saved successfully; otherwise, returns a value of
False.

If given optional arguments, then behaves as described below in Optional Keyword Arguments (p. 45).

Note:

If the ExecutionControl / Option for a participant is set to ExternallyManaged,

then System Coupling will not start the participant using either this command or any of the
other commands that automatically start participants. The user is expected to manually start
the participant. This function will not return until all participants have been connected.

Optional Keyword Arguments

FilePath : WritableDirectory
Writeable directory to which the SyC directory is added. (Settings and Results .h5 files will be written to
the SyC directory.)

The directory path must contain only ASCII characters.

Return Type
bool

Examples
Example 30: Save the state of a coupled analysis in a "SyC" directory in the current working
directory.

>>> Save()

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 45
Commands

True

Example 31: Save the state of a coupled analysis in a "SyC" directory in a new, specified working
directory.

>>> Save(FilePath = 'WorkingDirectory')

True

SetExpertSettings
Given a dictionary of expert settings, enables the specified settings and sets their values.

Essential Keyword Arguments

Settings : dict
Dictionary used to specify the expert settings to be enabled and set, with setting names as keys and their
values as values.

Return Type
NoneType

Examples
Example 32: Enable a single expert setting

>>> SetExpertSettings(Settings={'Source_InitValue_HeatTransferCoef': 2})

SetState
Sets the state of a specified data model container (can be either a singleton or an object).

Returns a Boolean value of True if the state change was successful; otherwise, returns a value of
False.

Essential Keyword Arguments

ObjectPath : str
String indicating the path of the container to have its state set.

State : dict
Dictionary with the container state (settings) as keys and intended values as values.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
46 of ANSYS, Inc. and its subsidiaries and affiliates.
 Solve

Return Type
bool

Examples
Example 33: Use SetState on a singleton

>>> SetState(ObjectPath = '/SystemCoupling/CouplingControl/AnalysisType/

DurationControl', State = {'EndTime': '0.5 [s]', 'Option': 'EndTime'})

True

Example 34: Use SetState on an object

>>> SetState(ObjectPath = '/SystemCoupling/CouplingParticipant:MAPDL-1/

Variable:FORC', State = {'QuantityType': 'Force', 'DisplayName': 'TestForce'})

True

Shutdown
Interactive command that shuts down a coupled analysis.

Shutdown includes 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 disconnecting
from participants.

After participants are disconnected, System Coupling writes timing details to the Transcript and Log. If
participants were started automatically, it ends participant processes.

When System Coupling disconnects from the analysis and shuts down, the GUI Server file is removed
from the working directory.

Supported Keyword Arguments

None

Return Type
NoneType

Solve
Starts the participants (if necessary) and solves the coupled analysis. By default, the solution runs straight
through without pause unless stopped by an scStop file.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 47
Commands

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.

For restarts, the Open command must be run before the Solve command.

For analyses with differently oriented models, geometry transformations must be defined before running
the Solve command.

Note:

If the ExecutionControl / Option for a participant is set to ExternallyManaged,

then System Coupling will not start the participant using either this command or any of the
other commands that automatically start participants. The user is expected to manually start
the participant. This function will not return until all participants have been connected.

Supported Keyword Arguments

None

Return Type
NoneType

StartParticipants

Important:

This command will be deprecated. Consider adopting workflows where participants are
started by another method, such as the Initialize, Step, or Solve commands.

Interactive command that reads the participants' System Coupling Participant setup files (SCP) and
starts participants on separate sub-processes. Automatically starts all participants and blocks solution
progress until all participants are connected.

This command will raise an exception if another instance of System Coupling is solving in the current
working directory.

If a participant's SCP file doesn't include the <ExecutionControl> element, the participant cannot
be started automatically; it must be started manually, as described in the participant's command-line
documentation.

If omitted and the Solve, Initialize, or Step command is issued, then participants are started
automatically during the execution of the command.

Note:

If the ExecutionControl / Option for a participant is set to ExternallyManaged,

then System Coupling will not start the participant using either this command or any of the

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
48 of ANSYS, Inc. and its subsidiaries and affiliates.
 Step

other commands that automatically start participants. The user is expected to manually start
the participant. This function will not return until all participants have been connected.

Supported Keyword Arguments

None

Return Type
NoneType

Examples
Example 35: Automatically start all participants

>>> StartParticipants()

Step
Interactive command that initializes the analysis and starts participants (if necessary), and then runs the
specified number of coupling steps before pausing the coupled analysis.

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.

By default, runs a single step. If given the optional Count argument, then runs the specified number
of steps.

For restarts, the Open command must be run before the Step command.

For analyses with differently oriented models, geometry transformations must be defined before running
the Step command.

When you run this command, System Coupling initializes the analysis if needed and then begins the
solution. When the specified number of coupling steps has been run, the solution is paused, providing
you with an opportunity to interact with the analysis.

When you resume the solution, either by reissuing this command or by running the Solve (p. 47)
command, System Coupling restarts the analysis at the point it left off and continues the solution with
the next step.

Note:

If the ExecutionControl Option for a participant is set to ExternallyManaged, then

System Coupling will not start the participant using either this command or any of the other
commands that automatically start participants.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 49
Commands

Optional Keyword Arguments

Count : int
Integer specifying the number of steps to be run. Defaults to 1.

Return Type
NoneType

Examples
Example 36: Use the default (the analysis runs one coupling step)

>>> Step()

Example 37: Specify that the analysis runs three coupling steps

>>> Step(Count = 3)

WriteCsvChartFiles

Important:

This is a beta-level command. When beta features are not enabled, WriteCsvChartFiles
is available but non-functional. To use this command, enable beta features and set the
Output Control / Generate CSV Charting Output setting to True.

For more information on CSV-formatted charting output, see System Coupling Convergence
Charting in the System Coupling Beta Features documentation.

For each coupling interface, exports a CSV file containing chart data (convergence and source/target
quantity transfer values) for that interface.

Each file is named <interface>.csv where <interface> is the object name of the corresponding
coupling interface.

This command will overwrite any CSV charting files that already exist, including any that were written
during the solution.

Supported Keyword Arguments

None

Return Type
NoneType

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
50 of ANSYS, Inc. and its subsidiaries and affiliates.
Command-Line Options
This section provides information on the available command-line arguments that can be used when
starting System Coupling from the command line.

For information on the different categories of command-line options, see:

General Command-Line Options
System Coupling Parallel Options
Coupling Participant Parallel Options

General Command-Line Options

Option Details
-G Description:

--gui Starts the System Coupling GUI from the command line.

Automatically starts System Coupling in GUI Server mode.

--guiserv- Description:
er
Starts System Coupling in GUI Server mode and writes connection information
to the sycGUI.srv file. This file prevents the use of interactive input to the
session being started and prevents other instances of System Coupling from
being started in the same mode.

Applied automatically when the System Coupling GUI is started.

When used, the -I and --interactiveMode options are ignored and the
CLI is closed after the script is run.

Required in order to connect/reconnect the System Coupling GUI to a running

instance of System Coupling.

To be shut down cleanly, session started in this mode must be ended from a
connected GUI instance. Otherwise, it must be shut down using an OS-specific
kill request.
-h Description:

--help Displays help on command-line startup options and then exits the command-line
interface.
-I Description:

--inter- Starts System Coupling in Interactive mode.

active-
Mode

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 51
Command-Line Options

Option Details
When used with -R or --runScript, keeps the CLI open after the script has
run.

This option is overridden when the --guiserver option is used to start

System Coupling in GUI Server mode.
-R Description:

--run- Runs the specified script(s).

Script
Argument:

Accepts a single script name.

Usage:

-R <SCRIPTFILE>

--runScript=<SCRIPTFILE>

To run multiple script files in succession, supply the argument multiple times.

-R <SCRIPTFILE1> -R <SCRIPTFILE2>

System Coupling Parallel Options

Option Details
--mpi Description:

Specifies the type of MPI to be used by System Coupling.

If the option is not specified, the default MPI for the given interconnect will be used (the
use of the default MPI is recommended).

Argument:

Accepts the type of MPI of the cluster head node. Available types: default, ibmmpi, in-
tel, msmpi, openmpi, cray

Usage:

--mpi=<MPI>

--mpi- Description:
opt
Passes vendor MPI options to System Coupling. Options must be in quotation marks.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
52 of ANSYS, Inc. and its subsidiaries and affiliates.
 System Coupling Parallel Options

Option Details
Argument:

Accepts an MPI option.

Usage:

--mpiopt="<MPIOPTION>"

-p Description:

--ic Specifies the type interconnect to be used by System Coupling.

Argument:

Accepts the type of interconnect. Available types: default, eth, myrinet, ib

• Windows: The ethernet interconnect is used by default if the option is not explicitly
specified.

• Linux:

The auto-select interconnect is used by default so that the best available

interconnect is used if the option is not explicitly specified.

Usage:

-p <INTERCONNECT>

--ic=<INTERCONNECT>

-s Description:

--sy- Specifies the number of cores to be used by System Coupling.

cn-
procs Defaults to 2.
System Coupling will not use more cores than are available on the machine containing the
root process.

Argument:

Accepts an integer.

Usage:

-s<SYCNPROCS>

--sycnprocs=<SYCNPROCS>

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 53
Command-Line Options

Coupling Participant Parallel Options

Option Details
--cnf Description:

Optional. When running coupling participants in parallel, specifies the machine list and
core count for the run.

When present, this argument is used to determine which machines to use for parallel
job execution and the number of cores available on each.

If the machines and core count have been set by the --cnf option and then are reset
explicitly by another method, then the values set by the --cnf option are ignored.

Argument:
For both Windows and Linux, accepts either a comma-separated list of machines and cores
(recommended method) or the name of the hosts file.

Usage:

--cnf="<MACHINE2:CORECOUNT,MACHINE2:CORECOUNT,MACHINE3:CORECOUNT>"

--cnf=<HOSTSFILE>

In the examples below, one core is available on machine-1, three cores are available on
machine-2, and four cores are available on machine-3.

• Using a list to specify machines and core counts:

--cnf="machine-1:1,machine-2:3,machine-3:4"

• Using a hosts file to specify machines and core counts:

--cnf=hosts.txt

Sample hosts file contents:

machine-1:1
machine-2:3
machine-3:4

-t Description:

--nprocs Specifies the number of cores to be used by coupling participants when running locally.

Defaults to 1 (serial).

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
54 of ANSYS, Inc. and its subsidiaries and affiliates.
 Coupling Participant Parallel Options

Option Details
If no machine list is provided, no job scheduler is being used, and two or more cores
have been specified using this option, then the participants are run in local parallel with
the local machine as host.

If the core count has been set using this option and then a machine list is set, either
explicitly or by inheritance from a job scheduler, then the values set by this option are
ignored.

Argument:

Accepts an integer.

Usage:

-t<NPROCS>

--nprocs=<NPROCS>

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 55
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
56 of ANSYS, Inc. and its subsidiaries and affiliates.
Expert Settings
This section provides detailed information on the expert settings available for System Coupling. Expert
settings are listed in alphabetical order.

For details on a setting, click it in the list below.

ExportInterfaceDataPerStep
Source_InitValue_HeatTransferCoef
WriteDiagnosticsDictionary

For information on the command used to enable expert settings, see SetExpertSettings (p. 46).

ExportInterfaceDataPerStep
Generates interface/data transfer diagnostics files for each coupling step.

When enabled, System Coupling generates and exports two AXDT files for each transfer on coupling
interfaces, with one file for each participant.

Note:

Note that one interface is created for a given side One/side Two pair of regions, and that all
valid data transfers for the pair occur within the interface.

At the end of the final iteration of each coupling step, the two AXDT files are written to System Coupling's
working directory. The files are named according the following convention:

<interfaceName>_step<#>_side<#>_<regionName>.axdt

For a given step, these files include the mesh for all nodes (mapped and unmapped) and the results
for data transfer variables corresponding to the final coupling iteration in that step.

Possible values for the command-line context:

• True: enabled (default value)

• False: disabled

Example 38: Enable ExportInterfaceDataPerStep

>>> SetExpertSettings(Settings={"ExportInterfaceDataPerStep": True})

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 57
Expert Settings

Source_InitValue_HeatTransferCoef
Specifies the initial value to be used for variables of a given quantity.

When enabled, the specified initial value is used as the raw variable value provided by the source par-
ticipant to initialize the simulation (that is, for the first iteration of the first step of the simulation).

If an actual raw value has been provided by the source participant, the specified initial value overrides
it.

Accepts decimal values 0.0   x   1e+30. Default value is 0.0.

Example 39: Enable Source_InitValue_HeatTransferCoef

>>> SetExpertSettings(Settings={"Source_InitValue_HeatTransferCoef": 295.15})

WriteDiagnosticsDictionary
Generates mapping weight and interpolation diagnostic files.

When enabled, System Coupling generates and exports the following JSON output files:

Weights Diagnostics:
A single file is generated during the first iteration of the first step of the coupled analysis. Its contents are
written both to the System Coupling command console and to a JSON file in System Coupling's working
directory. The file is named according the following convention:

weightsDiagnostics_step1.json

For a given interface, this file contains full weights diagnostics for the mapping process of that in-
terface.

Interpolation Diagnostics:
A file is generated for every iteration in the coupled analysis. Their contents are written both to the System
Coupling command console and to a JSON file in the System Couplings working directory. The files are
named according the following convention:

interpolationDiagnostics_step<#>_iteration<#>.json

For a given step, these files contain full interpolation diagnostics. Contents include mesh and results
— specifically, the (un)mapped and data transfer variable(s) corresponding to the final iteration of
the step.

Note:

When this setting is enabled, newly generated interpolation diagnostic files will replace
any existing interpolation diagnostic files in System Coupling's working directory.

Possible values:

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
58 of ANSYS, Inc. and its subsidiaries and affiliates.
 WriteDiagnosticsDictionary

• True: enabled (default value)

• False: disabled

Example 40: Enable WriteDiagnosticsDictionary

>>> SetExpertSettings(Settings={"WriteDiagnosticsDictionary": True})

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 59
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
60 of ANSYS, Inc. and its subsidiaries and affiliates.