The input XML file is composed of several different sections: participants, analysis, transfers, and execution control.
The participant section contains information obtained through the coupling data interface (CDI) and the connections to upstream solver systems. It is intended to be read-only. In the participants section, you can view the Count (an integer representing the number of connected participants). For each connected participant, you can view the following: Note that depending upon the type of participant (co-simulation or static data), some of the options may or may not be applicable.
• Type (integer attribute)
The type of coupling participant (0 – co-simulation, 1 – static data)
• Name (string)
The name of the participant. This is the name with which the participant identifies itself to the system coupling. This corresponds to the “Component ID” which is unique to a specific system’s Solution cell in the Workbench user interface.
• DisplayName (wide string)
The display name of the participant provided by you in the in Workbench user interface.
• FilePath (string)
The full path to the primary file used to access source data from a static data participant.
• SupportsCouplingIterations (boolean)
Whether or not the co-simulation participant supports the execution of multiple coupling iterations per coupling step.
• UnitSystem
• Regions (options below are applicable to an individual region) – Name (string)
The name of the region (intrinsic to the participant).
– DisplayName (wide string)
The display name of the region given by you in the Workbench user interface.
– TopologicalDimensionality (integer)
The geometry type of the region (0 – undefined, 1 – point, 2 – curve, 3 – surface, 4 – volume).
• Variables (options below are applicable to an individual variable) – Name (string)
The name of the variable (intrinsic to the participant).
– DisplayName (wide string)
The display name of the variable given by you in the Workbench user interface.
– PhysicalType (string)
The physical type of the variable (options include: Length / Force).
• BaseUnits (strings denoting base units for all data of noted physical type) – Length (string)
– Time (string) – Mass (string) – Luminance (string) – Angle (string) – SolidAngle (string) – Temperature (string) – ChemicalAmount (string) – Current (string)
The analysis section contains details used to define the coupled analysis. In the analysis section, you can set the following:
Understanding the System Coupling Input File
• AnalysisType (integer)
This setting defines the nature of the sequential steps used in coupling co-simulation participants.
Available option is 0 (general), and 1 (transient).
• Initialization
This setting defines the initial time for the coupled analysis – Option (integer)
Available options are 0 (Program Controlled) and 1 (Start Time). The former is the default option for coupling initialization. When this option is used, the coupling service will make the most appro-priate choice of an initial time value. When the latter option is used, the coupling service will override the initial/start time for the analysis with the value specified as part of Time (see below).
– Time (double)
If option 1 is chosen above, then this is the initial time for the coupling analysis.
• Duration
This setting defines the duration of the coupled analysis.
– Option (integer)
Available options are 0 (NumberOfSteps) and 1 (EndTime).
– NumberOfSteps (integer)
This option is available only if no end-time requirements exist for co-simulation participants.
– Time (double)
Final time of coupling analysis.
• Step
– MaximumIterations (integer)
The maximum number of coupling iterations allowed per coupling step.
– MinimumIterations (integer)
The minimum number of coupling iterations allowed per coupling step.
– Size (double)
The size of the coupling step when it is associated with a time (this is done for transient analyses, size is measured in seconds).
– Option (integer)
Available option is 1 (coupling step size, used for transient analyses) and 0 (non dimensional step size, used for general analyses).
• UnitSystem (string)
The transfers section contains details used to define the data transfers between any static and co-sim-ulation coupling participants. In the transfers section, you can set the Count (an integer representing the total number of data transfers) as an attribute. For each coupling transfer, you can set the following:
• Name (string)
The name of the transfer (which you provided) in the Workbench user interface.
• ExecuteCouplingAt (integer)
This setting defines “when” the current data transfer is executed during the coupled analysis. The only available option is 2 (Start of Iteration).
• Source
The information related to the source participant involved in the data transfer.
– Participant (string)
The name of the source participant.
– Region (string)
The name of the source region (defined for a given participant) participating in the data transfer.
– Variable (string)
The name of the source variable, the data corresponding to which is exchanged during the data transfer (also defined for a given participant).
• Target
The information related to the target participant involved in the data transfer – Participant (string)
The name of the target participant – Region (string)
The name of the target region participating in the data transfer – Variable (string)
The name of the target variable, the data corresponding to which is exchanged during the data transfer
• ConvergenceOption (integer)
Specifies the type of data transfer convergence check in an implicit coupling (that is, if more than one coupling iteration per coupling step is specified; a value of 0 indicates the RMS normalized change).
• ConvergenceTarget (double)
Understanding the System Coupling Input File
The target value that determines the convergence of the data transfer
• UnderRelaxationFactor (double)
The under-relaxation factor (URF) applied to the data increments between any two successive coupling iterations. The URF has a range of . Note that when transferring incremental displacement, the URF must equal 1. In this case, a value less than 1 can lead to an accumulation of errors, and the following warning will be displayed in your SCL file:
The under relaxation factor for the data transfer named '<name of data transfer>' is smaller than one. Under relaxation factor less than one for incremental displacement might lead to errors.
• Ramping (integer)
This setting defines if and how ramping is used when applying data from the source-side to the target-side of the data transfer. Valid options are: 0 – none (that is, stepped), and 1 – linearly ramped up to the minimum number of coupling iterations. The default is none, which implies the target side of the data transfer experiences the full value from the source side during the first coupling iteration.
The execution control section contains details used to define the solution sequence between the coupling participants, the system coupling debug output, intermediate result files output, and expert settings. For each participant, you can set the following:
• CoSimulationSequence
This subsection is used to specify the sequencing of co-simulation coupling participants (most often solvers) during a coupling iteration. In the CoSimulationSequence subsection, the 'Count' attribute specifies the number of participants for which sequencing information will be provided.
– Participant
A Participant subsection is required for each co-simulation participant.
→Name (string)
The name of the participant.
→SolutionSequence (integer)
The sequence number of the participant in the coupled solution. Within a coupling iteration, a participant with a larger sequence number will solve later than another with a lower sequence number.
• DebugOutput
This subsection is used to specify the section(s) of debug output to write to the system coupling log (SCL) file. As presented below, the level of detail is specified for each section or all sections (the default).
– DefaultOutputLevel (integer)
This setting provides the default level for the different sections of debug output. If this entry is set and another specific entry (for example, Startup) also exists, then the output level for the specific entry will override the level set here.
– Startup (integer)
This setting controls the level of output from the start of the coupling service until creation of the
“Summary of SC Setup” banner in the SCL file.
– ParticipantConnection (integer)
This setting controls the level of output from the end of the setup validation until the “Initial Syn-chronization” synchronization point.
– AnalysisInitialization (integer)
This setting controls the level of output from the “Analysis Initialization” until the “Solution” syn-chronization point.
– SolutionInitialization (integer)
This setting controls the level of output during the setup of coupling steps and iterations. This output does not include information related to the data transfers.
– ConvergenceChecks (integer)
This setting controls the level of output from the “Check Convergence” synchronization point until the next synchronization point, which may be either “Shutdown” or “Solution.”
– Shutdown (integer)
This setting controls the level of output after the “Shutdown” synchronization point.
– Transfers
This section is used to specify the debug output generated for data transfers. Note that header information for mapping is generated whenever the mesh coordinate or mesh topology output is requested. Similarly, header information for the data transfers is generated whenever the transfer data output is requested.
→DefaultOutputLevel (integer)
This setting provides the default level for the different kinds of debug output. If this entry is set and another specific entry (for example,SourceMeshCoords) also exists, then the output level for the specific entry will override the level set here.
→SourceMeshCoords (integer)
This setting controls the level of output for mesh coordinates of the source region in all data transfers.
→SourceMeshTopol (integer)
This setting controls the level of output for mesh topology (elements and nodes) of the source region in all data transfers.
→SourceData (integer)
This setting controls the level of output for the source data in all data transfers.
→TargetMeshCoords (integer)
Understanding the System Coupling Input File
This setting controls the level of output for mesh coordinates of the source region in all data transfers.
→TargetMeshTopol (integer)
This setting controls the level of output for mesh topology (elements and nodes) of the source region in all data transfers.
→TargetData (integer)
This setting controls the level of output for the target data in all data transfers.
The level of detail to include in debug output is controlled using one of the following integer values for either the default or specific sections of output:
– 0: None – 1: Level 1 – 2: Level 2 – 3: Level 3 – 4: Level 4 – 5: All Levels
Increasing values always generate more detailed output. Note, as well, that the output level settings for each of the mesh coordinates and topology, and transfer data control the number of lines of output generated. Specifically, 10L lines of data will be written for an output level setting of L (for example, 100 lines will be written for an output level of 2, or “Level 2”).
• IntermediateResultsFileOutput
This subsection is used to specify the frequency at which intermediate result files, which can be used for restarts, are written by the System Coupling service.
– FrequencyOption (integer)
Available options are 0 (every coupling step) and 1 (coupling step interval) – StepInterval (integer)
The coupling step interval at which intermediate result files should be generated (Note that this is valid only when FrequencyOption is set to Step Interval). For example, using a step interval of 3, results will be generated at steps 3, 6, 9, ...
The following entry may be reported in the SCI file, but is not used by the System Coupling service:
• MappingSettings