Participant Setup File

When applicable, coupling participants write a System Coupling Participant setup file (*.scp). Typically, these files are named according to the convention noted below, but other extensions can be used, as well.

<ParticipantObject>.scp

These XML-formatted files provide System Coupling with the participant-specific information needed to connect the participants to a coupling run.

Important:  The sole purpose of an .scp file is to allow the participant to be added to a coupled analysis. When participants are added, the information from their .scp files populates the data model and then is saved, as part of the analysis state, to the Settings file. From this point, the analysis draws its setup information from the Settings file, not from the participant .scp files.

Ansys recommends that you do not attempt to change participant settings by editing .scp files manually, as this may invalidate the data model and/or cause a mismatch between the analysis and its Settings file.

Also, note that reloading an .scp file to an existing analysis overwrites the setup details in the corresponding Settings file, so this should not be done unless you intend to start over with the analysis setup. If you do attempt to change participant settings by editing .scp files, ensure that edits are made before you start setting up the analysis (that is, add participants, create interfaces, and so on).

For an example, see Sample System Coupling Participant File.

Note:

  • The use of both .sci and .scp files in the same analysis is not supported.

  • In the sections that follow, noted commands and queries can be run either in the System Coupling CLI in the System Coupling GUI's Command Console.

The .scp file includes the following main elements:

<CouplingParticipant>
	<ExecutionControl/>
	<CosimulationControl/>      
</CouplingParticipant>
 

<ExecutionControl>

Container element for settings that control the execution of the participant. Provides the information needed to start the coupling participant.

Optional. If this element does not exist, System Coupling populates the ExecutionControl part of the data model with values based on the participant type.

Contains the following sub-elements:

 
<ExecutionControl>	
	<InitialInput/>
	<Command/>
</ExecutionControl>
 
<InitialInput>

Defines the name of the solver input file to be used for the initial run of the coupled analysis.

Required if the parent <ExecutionControl> element exists.

Acceptable <InitialInput> values vary according to coupling participant:

  • For an AEDT participant, it must refer to a solver input file (.py), which in turn refers to an Ansys Electronics Desktop project file (.aedt).

  • For a CFX participant, it must refer to a CFX-Solver input (.def or .res) file.

  • For a Mechanical participant, it must refer to a Mechanical APDL solver input file (.dat).

  • For a Fluent participant, there are two options:

    • It can refer to a Fluent case file (.cas, .cas.gz, or .cas.h5), either with or without the extension. In this case, System Coupling generates its own Fluent journal script to read this case file.

    • It can refer to a custom Fluent journal file (.jou). The journal file must have a .jou extension.

 
<Command>

Specifies the command that can be used to start the coupling participant automatically.

Optional. Note that this element is not included when a participant generates its System Coupling Participant (.scp) setup file because System Coupling can locate the participant's execution command based on other information from the file.

To obtain the command used to start a participant, run GetExecutionCommand() for the participant. For participant-specific details, see the participant's documentation on executing from the command line.

 

<CosimulationControl>

Container element for settings that control how the participant can act in a co-simulation. Provides the information necessary to set up couplings and to execute the participant in the co-simulation.

Required.

Contains the following sub-elements:

 
<CosimulationControl>
	<Type/>
	<Dimension/>
	<AnalysisType/>
	<DisplayName/>
	<RestartsSupported/>
	<Variables/>
	<Regions/>
</CosimulationControl>
 
<Type>

Specifies the type of participant.

Optional. When not specified, the DEFAULT type is used.

Possible values:

  • DEFAULT (default value)

  • AEDT

  • CFX

  • FLUENT

  • MAPDL

 
<Dimension>

Specifies the dimension of the participant.

Optional.

Possible values:

  • 3D (default value)

  • 2D

 
<AnalysisType>

Specifies the type of analysis the participant is running.

Optional. If not specified, defaults to Steady.

Possible values:

  • Steady (default value)

  • Transient

 
<DisplayName>

Specifies the participant name to be displayed in user-facing communications.

Optional. When not specified, the name of the participant object in the data model is used.

 
<RestartsSupported>

Indicates whether the participant supports restarts for this type of coupled analysis.

If any participant in a coupled analysis does not support restarts, then restarts are disabled for the analysis as whole. A participant's restart capabilities may vary according to the type of analysis being performed.

Optional. If not specified, either in the participant's coupling .scp file or in the data model, then the default value is determined by the participant's <ParticipantType> value, as described below:

Possible values:

  • False: Indicates that the participant does not support restarts.

    If not specified, then this is the default value for participants of type FORTE or DEFAULT.

  • True: Indicates that the participant supports restarts.

    If not specified, then this is the default value for participants not of type FORTE or DEFAULT.

 
<Variables>

Container element for the set of variables that are available for coupled simulations.

Optional. If no output/input variables are defined, then the participant is ignored.

Contains one or more <Variable> sub-elements:

  
<Variables>
	<Variable>
</Variables>
 
<Variable>

Defines a variable that is available for coupled simulations. Nested under <Variables>.

Optional. If no output/input variables are defined, then the participant is ignored.

Contains the following sub-elements:

 
<Variable>
	<Name>
	<DisplayName>
	<QuantityType>
	<TensorType>
	<IsExtenstive>
	<Location>
</Variable>
 
<Name>

Specifies the variable name to be used internally by System Coupling and the participant.

Required.

 
<DisplayName>

Specifies the variable name to be displayed in user-facing communications.

Optional. If not specified, the variable's data model <Name> is used.

 
<QuantityType>

Indicates the quantity type of the data provided by the variable.

Required when values are not specified for the variable's <TensorType> and/or <IsExtensive> elements.

Otherwise, optional. If a quantity type is not available (that is, either the <QuantityType> element is left blank or set to Unspecified), then:

  • Values for the <TensorType> and/or <IsExtensive> elements are required.

  • Any variables with the same <TensorType> can be coupled.

Possible values:

  • Unspecified

  • Convection Reference Temperature

  • Force

  • Incremental Displacement

  • Heat Rate

  • Heat Transfer Coefficient

  • Temperature

 
<TensorType>

Indicates the tensor type of the variable being transferred.

Required when the <QuantityType> is not available (that is, either the <QuantityType> element is left blank or set to Unspecified).

Otherwise, optional. If a value is not specified for the <TensorType> element, then System Coupling infers this value, either from the variable's <Name> (for MAPDL participants) or from its <QuantityType> (for all other participant types).

Possible values:

  • Scalar

  • Vector

 
<IsExtensive>

Indicates whether the variable is extensive. A property is extensive if its value depends on the size of the system.

Not available for FMU participants.

Required when the <QuantityType> is not available (that is, either the <QuantityType> element is left blank or set to Unspecified).

Otherwise, optional. If a value is not specified for the <IsExtensive> element, then System Coupling infers this value, either from the variable's <Name> (for MAPDL participants) or from its <QuantityType> (for all other participant types).

Possible values:

  • True: The variable is extensive.

  • False: The variable is intensive.

 
<Location>

Defines the mesh location on which data exists.

Optional. If not specified, defaults to Node.

Possible values:

  • Element

  • Node (default value)

 

<Parameters>

Container element for the set of parameters that are available for coupled simulations.

Optional. When no parameters are defined, parameters are not added to the data model.

Contains one or more <Parameter> sub-elements:

 
<Parameters>
	<Parameter>
</Parameters>
 
<Parameter>

Defines a parameter that is available for couplied simulations. Nested under <Parameters>.

Required when the <Parameters> element exists.

Contains the following sub-elements:

<Parameter>
	
	<Name>
	<DisplayName>
	<TensorType>	
</Parameter>
 
<Name>

Specifies the region name to be used by System Coupling and the participant.

Required.

 
<DisplayName>

Specifies the region name to be displayed in user-facing communications.

Optional. If not specified, the parameter object's data model <Name> is used.

 
<TensorType>

Indicates the tensor type of the parameter being transferred. The only value allowed is Scalar.

 

<InputParameters>

Container element for the set of parameters for which the parameter can receive data.

Optional. If no input variables are defined, then no data transfers may be created with the parameter as a target. Contains one or more <Parameter> sub-elements. 

 
<InputParameters>
	<Parameter>
</InputParameters>
 
<Parameter>

Defines an input parameter for which the parameter can receive data. Must correspond to the <Name> of a parameter defined under the <Parameters> element.

Optional. If no input parameters are defined, then no data transfers may be created with the parameter as a target.

 

<OutputParameters>

Container element for the set of parameters for which the parameter can send data.

Optional. If no input variables are defined, then no data transfers may be created with the parameter as a target. Contains one or more <Parameter> sub-elements. 

 
<OutputParameters>
	<Parameter>
</OutputParameters>
 
<Parameter>

Defines an output parameter for which the parameter can receive data. Must correspond to the <Name> of a parameter defined under the <Parameters> element.

Optional. If no output parameters are defined, then no data transfers may be created with the parameter as a source.

 

<Regions>

Container element for the set of regions that are potentially available for coupled simulations.

Optional. When no regions are defined, the participant is ignored.

Contains one or more <Region> sub-elements:

 
<Regions>
	<Region>
</Regions>
 
<Region>

Defines a region that is potentially available for coupled simulations. Nested under <Regions>.

Optional. When no regions are defined, the participant is ignored.

Contains the following sub-elements:

<Regions>
	<Topology>
	<Name>
	<DisplayName>
	<OutputVariables>
	<InputVariables>
</Regions>
 
<Topology>

Defines the spatial dimensionality of the data being transferred to/from the region.

Required.

Possible values:

  • Surface

  • Volume

 
<Name>

Specifies the region name to be used by System Coupling and the participant.

Required.

 
<DisplayName>

Specifies the region name to be displayed in user-facing communications.

Optional. If not specified, the region object's data model <Name> is used.

 
<OutputVariables>

Container element for the set of output variables for which the region can send data.

Optional. If no output variables are defined, then no data transfers may be created with the region as a source.

Contains one or more <Variable> sub-elements.

<OutputVariables>
	<Variable>
</OutputVariables>
 
<Variable>

Defines an output variable for which the region can send data. Must correspond to the <Name> of a variable defined under the <Variables> element.

Optional. If no output variables are defined, then no data transfers may be created with the region as a source.

 
<InputVariables>

Container element for the set of input variables for which the region can receive data.

Optional. If no input variables are defined, then no data transfers may be created with the region as a target.

Contains one or more <Variable> sub-elements.

<InputVariables>
	<Variable>
</InputVariables>
 
<Variable>

Defines an input variable for which the region can receive data. Must correspond to the <Name> of a variable defined under the <Variables> element.

Optional. If no input variables are defined, then no data transfers may be created with the region as a target.

 

Sample System Coupling Participant File

The following is an example .scp file for the Electronics Desktop participant in a coupled analysis.

<CouplingPartipant>
   <ExecutionControl>
      <InitialInput>FreeBurningArc_Maxwell3DDesign1_SystemCouplingSetup2.py</InitialInput>
   </ExecutionControl>
   <CosimulationControl>
      <Type>AEDT</Type>
      <AnalysisType>Transient</AnalysisType>
      <RestartsSupported>False</RestartsSupported>
      <DisplayName>Ansys Electronics Desktop</DisplayName>
      <Variables>
         <Variable>
            <Name>Loss</Name>
            <QuantityType>Heat Rate</QuantityType>
            <TensorType>Scalar</TensorType>
            <IsExtensive>True</IsExtensive>
            <Location>Element</Location>
         </Variable>
         <Variable>
            <Name>Temperature</Name>
            <QuantityType>Temperature</QuantityType>
            <TensorType>Scalar</TensorType>
            <IsExtensive>False</IsExtensive>
            <Location>Element</Location>
         </Variable>
         <Variable>
            <Name>Conductivity</Name>
            <QuantityType>Electrical Conductivity</QuantityType>
            <TensorType>Scalar</TensorType>
            <IsExtensive>False</IsExtensive>
            <Location>Element</Location>
         </Variable>
         <Variable>
            <Name>LorentzForce</Name>
            <QuantityType>Force</QuantityType>
            <TensorType>Vector</TensorType>
            <IsExtensive>True</IsExtensive>
            <Location>Element</Location>
         </Variable>
         <Variable>
            <Name>SurfaceLoss</Name>
            <QuantityType>Heat Rate</QuantityType>
            <TensorType>Scalar</TensorType>
            <IsExtensive>True</IsExtensive>
            <Location>Element</Location>
         </Variable>
      </Variables>
      <Parameters>
         <Parameter>
            <Name>Current</Name>
            <DisplayName>Current</DisplayName>
         </Parameter>
         <Parameter>
            <Name>Voltage</Name>
            <DisplayName>Voltage</DisplayName>
         </Parameter>
      </Parameters>
      <InputParameters>
         <Parameter>Current</Parameter>
      </InputParameters>
      <OutputParameters>
         <Parameter>Voltage</Parameter>
      </OutputParameters>
      <Regions>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region15</Name>
            <DisplayName>Cathode</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
            <InputVariables>
               <Variable>Temperature</Variable>
            </InputVariables>
         </Region>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region24</Name>
            <DisplayName>Anode</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
            <InputVariables>
               <Variable>Temperature</Variable>
            </InputVariables>
         </Region>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region105</Name>
            <DisplayName>Arc_region_inner</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
         </Region>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region317</Name>
            <DisplayName>Arc_region_Separate2</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
         </Region>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region343</Name>
            <DisplayName>Arc_start_region</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
            <InputVariables>
               <Variable>Conductivity</Variable>
               <Variable>Temperature</Variable>
            </InputVariables>
         </Region>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region763</Name>
            <DisplayName>Arc_region_inner1</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
            <InputVariables>
               <Variable>Conductivity</Variable>
               <Variable>Temperature</Variable>
            </InputVariables>
         </Region>
         <Region>
            <Topology>Volume</Topology>
            <Name>Region826</Name>
            <DisplayName>Arc_region_Separate3</DisplayName>
            <OutputVariables>
               <Variable>Loss</Variable>
               <Variable>LorentzForce</Variable>
               <Variable>SurfaceLoss</Variable>
            </OutputVariables>
            <InputVariables>
               <Variable>Conductivity</Variable>
               <Variable>Temperature</Variable>
            </InputVariables>
         </Region>
      </Regions>
   </CosimulationControl>
</CouplingPartipant>