COUPLING_FIELDS

Specifies which AcuTrace fields couple with AcuSolve and how they couple when flow_field_type is two_way_coupling.

Type

AcuTrace Command

Syntax

COUPLING_FIELDS {parameters}

Qualifier

This command has no qualifier.

Parameters

coupling_iterations or coup_iters (integer) >=1 [=1]
Number of AcuTrace iterations per AcuSolve time step. An AcuTrace iteration is an advance of all the particles from the beginning to the end of the AcuSolve time step.
momentum_type (enumerated) [=none]
Type of momentum coupling to AcuSolve. Specifies what type of momentum data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Momentum source terms are sent to AcuSolve.
momentum_flux_type (enumerated) [=finite_mass]
When momentum_type equals flux, specifies how the momentum source terms sent to AcuSolve are computed.
finite_mass
Momentum source terms are computed according to the finite mass model.
temperature_type (enumerated) [=none]
Type of temperature coupling to AcuSolve. Specifies what type of temperature data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Temperature source terms are sent to AcuSolve.
value
Temperature values are sent to AcuSolve.
temperature_flux_type (enumerated) [=user_equation]
When temperature_type equals flux, specifies how the temperature source terms sent to AcuSolve are computed.
user_equation
Temperature source terms are computed in a user equation.
temperature_value_type (enumerated) [=user_equation]
When temperature_type equals value, specifies how the temperature values sent to AcuSolve are computed.
user_equation
Temperature values are computed in a user equation.
component
Temperature values are set equal to a particle component.
temperature_user_equation (string) [No default]
When temperature_type equals flux and temperature_flux_type equals user_equation or temperature_type equals value and temperature_value_type equals user_equation, specifies which AcuTrace user equation provides the temperature values sent to AcuSolve.
temperature_user_index (integer) >=0 [=0]
When temperature_type equals flux and temperature_flux_type equals user_equation or temperature_type equals value and temperature_value_type equals user_equation, specifies which term in the user equation source term is used. temperature_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
temperature_component_index (integer) >=0 [=0}
When temperature_type equals value and temperature_value_type equals component, specifies which particle component is used. temperature_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
temperature_scaling_factor (real) [=1.0]
When temperature_type equals value, the temperature values sent to AcuSolve are multiplied by this value before they are sent.
species_1_type (enumerated) [=none]
Type of species 1 coupling to AcuSolve. Specifies what type of species 1 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 1 source terms are sent to AcuSolve.
value
Species 1 values are sent to AcuSolve.
species_1_flux_type (enumerated) [=user_equation]
When species_1_type equals flux, specifies how the species 1 source terms sent to AcuSolve are computed.
user_equation
Species 1 source terms are computed in a user equation
species_1_value_type (enumerated) [=component]
When species_1_type equals value, specifies how the species 1 values sent to AcuSolve are computed.
user_equation
Species 1 values are computed in a user equation.
component
Species 1 values are set equal to a particle component.
species_1_user_equation (string) [No default]
When species_1_type equals flux and species_1_flux_type equals user_equation or species_1_type equals value and species_1_value_type equals user_equation, specifies which AcuTrace user equation provides the species 1 values sent to AcuSolve.
species_1_user_index (integer) >=0 [=0]
When species_1_type equals flux and species_1_flux_type equals user_equation or species_1_type equals value and species_1_value_type equals user_equation, specifies which term in the user equation source term is used. species_1_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_1_component_index (integer) >=0 [=0]
When species_1_type equals value and species_1_value_type equals component, specifies which particle component is used. species_1_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_1_scaling_factor (real) [=1.0]
When species_1_type equals value, the species 1 values sent to AcuSolve are multiplied by this value before they are sent.
species_2_type (enumerated) [=none]
Type of species 2 coupling to AcuSolve. Specifies what type of species 2 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 2 source terms are sent to AcuSolve.
value
Species 2 values are sent to AcuSolve.
species_2_flux_type (enumerated) [=user_equation]
When species_2_type equals flux, specifies how the species 2 source terms sent to AcuSolve are computed.
user equation
Species 2 source terms are computed in a user equation.
species_2_value_type (enumerated) [=component]
When species_2_type equals value, specifies how the species 2 values sent to AcuSolve are computed.
user equation
Species 2 values are computed in a user equation.
component
Species 2 values are set equal to a particle component.
species_2_user_equation (string) [No default]
When species_2_type equals flux and species_2_flux_type equals user_equation or species_2_type equals value and species_2_value_type equals user_equation, specifies which AcuTrace user equation provides the species 2 values sent to AcuSolve.
species_2_user_index (integer) >=0 [=0]
When species_2_type equals flux and species_2_flux_type equals user_equation or species_2_type equals value and species_2_value_type equals user_equation, specifies which term in the user equation source term is used. species_2_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_2_component_index (integer) >=0 [=0]
When species_2_type equals value and species_2_value_type equals component, specifies which particle component is used. species_2_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_2_scaling_factor (real) [=1.0]
When species_2_type equals value, the species 2 values sent to AcuSolve are multiplied by this value before they are sent.
species_3_type (enumerated) [=none]
Type of species 3 coupling to AcuSolve. Specifies what type of species 3 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 3 source terms are sent to AcuSolve.
value
Species 3 values are sent to AcuSolve.
species_3_flux_type (enumerated) [=user_equation]
When species_3_type equals flux, specifies how the species 3 source terms sent to AcuSolve are computed.
user_equation
Species 3 source terms are computed in a user equation
species_3_value_type (enumerated) [=component]
When species_3_type equals value, specifies how the species 3 values sent to AcuSolve are computed.
user_equation
Species 3 values are computed in a user equation.
component
Species 3 values are set equal to a particle component.
species_3_user_equation (string) [No default]
When species_3_type equals flux and species_3_flux_type equals user_equation or species_3_type equals value and species_3_value_type equals user_equation, specifies which AcuTrace user equation provides the species 3 values sent to AcuSolve.
species_3_user_index (integer) >=0 [=0]
When species_3_type equals flux and species_3_flux_type equals user_equation or species_3_type equals value and species_3_value_type equals user_equation, specifies which term in the user equation source term is used. species_3_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_3_component_index (integer) >=0 [=0]
When species_3_type equals value and species_3_value_type equals component, specifies which particle component is used. species_3_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_3_scaling_factor (real) [=1.0]
When species_3_type equals value, the species 3 values sent to AcuSolve are multiplied by this value before they are sent.
species_4_type (enumerated) [=none]
Type of species 4 coupling to AcuSolve. Specifies what type of species 4 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 4 source terms are sent to AcuSolve.
value
Species 4 values are sent to AcuSolve.
species_4_flux_type (enumerated) [=user_equation]
When species_4_type equals flux, specifies how the species 4 source terms sent to AcuSolve are computed.
user_equation
Species 4 source terms are computed in a user equation.
species_4_value_type (enumerated) [=user_equation]
When species_4_type equals value, specifies how the species 4 values sent to AcuSolve are computed.
user_equation
Species 4 values are computed in a user equation.
component
Species 4 values are set equal to a particle component.
species_4_user_equation (string) [No default]
When species_4_type equals flux and species_4_flux_type equals user_equation or species_4_type equals value and species_4_value_type equals user_equation, specifies which AcuTrace user equation provides the species 4 values sent to AcuSolve.
species_4_user_index (integer) >=0 [=0]
When species_4_type equals flux and species_4_flux_type equals user_equation or species_4_type equals value and species_4_value_type equals user_equation, specifies which term in the user equation source term is used. species_4_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_4_component_index (integer) >=0 [=0]
When species_4_type equals value and species_4_value_type equals component, specifies which particle component is used. species_4_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_4_scaling_factor (real) [=1.0]
When species_4_type equals value, the species 4 values sent to AcuSolve are multiplied by this value before they are sent.
species_5_type (enumerated) [=none]
Type of species 5 coupling to AcuSolve. Specifies what type of species 5 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 5 source terms are sent to AcuSolve.
value
Species 5 values are sent to AcuSolve.
species_5_flux_type (enumerated) [=user_equation]
When species_5_type equals flux, specifies how the species 5 source terms sent to AcuSolve are computed.
user_equation
Species 5 source terms are computed in a user equation.
species_5_value_type (enumerated) [=component]
When species_5_type equals value, specifies how the species 5 values sent to AcuSolve are computed.
user_equation
Species 5 values are computed in a user equation.
component
Species 5 values are set equal to a particle component.
species_5_user_equation (string) [No default])
When species_5_type equals flux and species_5_flux_type equals user_equation or species_5_type equals value and species_5_value_type equals user_equation, specifies which AcuTrace user equation provides the species 5 values sent to AcuSolve.
species_5_user_index (integer) >=0 [=0]
When species_5_type equals flux and species_5_flux_type equals user_equation or species_5_type equals value and species_5_value_type equals user_equation, specifies which term in the user equation source term is used. species_5_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_5_component_index (integer) >=0 [=0)]
When species_5_type equals value and species_5_value_type equals component, specifies which particle component is used. species_5_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_5_scaling_factor (real) [=1.0]
When species_5_type equals value, the species 5 values sent to AcuSolve are multiplied by this value before they are sent.
species_6_type (enumerated) [=none]
Type of species 6 coupling to AcuSolve. Specifies what type of species 6 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 6 source terms are sent to AcuSolve.
value
Species 6 values are sent to AcuSolve.
species_6_flux_type (enumerated) [=user_equation]
When species_6_type equals flux, specifies how the species 6 source terms sent to AcuSolve are computed.
user_equation
Species 6 source terms are computed in a user equation.
species_6_value_type (enumerated) [=component]
When species_6_type equals value, specifies how the species 6 values sent to AcuSolve are computed.
user_equation
Species 6 values are computed in a user equation.
component
Species 6 values are set equal to a particle component.
species_6_user_equation (string) [No default]
When species_6_type equals flux and species_6_flux_type equals user_equation or species_6_type equals value and species_6_value_type equals user_equation, specifies which AcuTrace user equation provides the species 6 values sent to AcuSolve.
species_6_user_index (integer) >=0 [=0)]
When species_6_type equals flux and species_6_flux_type equals user_equation or species_6_type equals value and species_6_value_type equals user_equation, specifies which term in the user equation source term is used. species_6_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_6_component_index (integer) >=0 [=0]
When species_6_type equals value and species_6_value_type equals component, specifies which particle component is used. species_6_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_6_scaling_factor (real) [=1.0]
When species_6_type equals value, the species 6 values sent to AcuSolve are multiplied by this value before they are sent.
species_7_type (enumerated) [=none]
Type of species 7 coupling to AcuSolve. Specifies what type of species 7 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 7 source terms are sent to AcuSolve.
value
Species 7 values are sent to AcuSolve.
species_7_flux_type (enumerated) [=user_equation]
When species_7_type equals flux, specifies how the species 7 source terms sent to AcuSolve are computed.
user_equation
Species 7 source terms are computed in a user equation.
species_7_value_type (enumerated) [=component]
When species_7_type equals value, specifies how the species 7 values sent to AcuSolve are computed.
user_equation
Species 7 values are computed in a user equation.
component
Species 7 values are set equal to a particle component.
species_7_user_equation (string) [No default]
When species_7_type equals flux and species_7_flux_type equals user_equation or species_7_type equals value and species_7_value_type equals user_equation, specifies which AcuTrace user equation provides the species 7 values sent to AcuSolve.
species_7_user_index (integer) >=0 [=0]
When species_7_type equals flux and species_7_flux_type equals user_equation or species_7_type equals value and species_7_value_type equals user_equation, specifies which term in the user equation source term is used. species_7_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_7_component_index (integer) >=0 [=0]
When species_7_type equals value and species_7_value_type equals component, specifies which particle component is used. species_7_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_7_scaling_factor (real) [=1.0]
When species_7_type equals value, the species 7 values sent to AcuSolve are multiplied by this value before they are sent.
species_8_type (enumerated) [=none]
Type of species 8 coupling to AcuSolve. Specifies what type of species 8 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 8 source terms are sent to AcuSolve.
value
Species 8 values are sent to AcuSolve.
species_8_flux_type (enumerated) [=component]
When species_8_type equals flux, specifies how the species 8 source terms sent to AcuSolve are computed.
user_equation
Species 8 source terms are computed in a user equation.
species_8_value_type (enumerated) [=user_equation]
When species_8_type equals value, specifies how the species 8 values sent to AcuSolve are computed.
user_equation
Species 8 values are computed in a user equation.
component
Species 8 values are set equal to a particle component.
species_8_user_equation (string) [No default]
When species_8_type equals flux and species_8_flux_type equals user_equation or species_8_type equals value and species_8_value_type equals user_equation, specifies which AcuTrace user equation provides the species 8 values sent to AcuSolve.
species_8_user_index (integer) >=0 [=0]
When species_8_type equals flux and species_8_flux_type equals user_equation or species_8_type equals value and species_8_value_type equals user_equation, specifies which term in the user equation source term is used. species_8_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_8_component_index (integer) >=0 [=0]
When species_8_type equals value and species_8_value_type equals component, specifies which particle component is used. species_8_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_8_scaling_factor (real) [=1.0]
When species_8_type equals value, the species 8 values sent to AcuSolve are multiplied by this value before they are sent.
species_9_type (enumerated) [=none]
Type of species 9 coupling to AcuSolve. Specifies what type of species 9 data is sent to AcuSolve.
none
No coupling (no data sent).
flux
Species 9 source terms are sent to AcuSolve.
value
Species 9 values are sent to AcuSolve.
species_9_flux_type (enumerated) [=user_equation]
When species_9_type equals flux, specifies how the species 9 source terms sent to AcuSolve are computed.
user_equation
Species 9 source terms are computed in a user equation.
species_9_value_type (enumerated) [=component]
When species_9_type equals value, specifies how the species 9 values sent to AcuSolve are computed.
user_equation
Species 9 values are computed in a user equation.
component
Species 9 values are set to a particle component.
species_9_user_equation (string) [No default]
When species_9_type equals flux and species_9_flux_type equals user_equation or species_9_type equals value and species_9_value_type equals user_equation, specifies which AcuTrace user equation provides the species 9 values sent to AcuSolve.
species_9_user_index (integer) >=0 [=0]
When species_9_type equals flux and species_9_flux_type equals user_equation or species_9_type equals value and species_9_value_type equals user_equation, specifies which term in the user equation source term is used. species_9_user_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of variables in the user equation.
species_9_component_index (integer) >=0 [=0]
When species_9_type equals value and species_9_value_type equals component, specifies which particle component is used. species_9_component_index is 0 based. It must be greater than or equal to 0 and strictly less than the number of particle components.
species_9_scaling_factor (real) [=1.0]
When species_9_type equals value, the species 9 values sent to AcuSolve are multiplied by this value before they are sent.

Description

When the flow_field_type parameter in the FLOW_FIELD command is two_way_coupling, particle source terms and values are sent from AcuTrace to a concurrently running AcuSolve simulation. The source terms and values sent as well as how AcuSolve uses them are specified in the COUPLING_FIELDS command.

The set up for a coupled particle-flow problem with AcuSolve and AcuTrace also requires several general inputs in the AcuSolve input file regardless of the details of the coupling:
  • Particle trace must be enabled:
    EQUATION {
      ...
      particle_trace             = on 
      ...
}
  • The host on which AcuTrace runs must be specified in the PARTICLE_TRACE command:
    PARTICLE_TRACE{
      ...
      socket_host                = "avocet"
      ...
}

    In this example, AcuTrace runs on a host named avocet.

  • Either AUTO_SOLUTION_STRATEGY must be used:
    AUTO_SOLUTION_STRATEGY {
      ...
}
or a stagger for the particle trace must be defined and included as part of the TIME_SEQUENCE command:
TIME_SEQUENCE {
      ...
      staggers                   = { "flow",
                                 "particle_trace" }
      ...
}
STAGGER( "particle_trace" ) {
      equation                   = particle_trace
}
Two examples now follow. The first example illustrates flux, that is, source term, coupling. In this example, particles exchange energy via conductive heat transfer. The COUPLING_FIELDS command
COUPLING_FIELDS {
      temperature_type           = flux
      temperature_flux_type      = user_equation
      temperature_user_equation  = energy
}

specifies that the AcuTrace user equation energy provides a source term to the AcuSolve temperature equation.

The user equation energy must be used in an active AcuTrace stagger for the coupling to have effect. For example,
USER_EQUATION( "energy" ) {
      user_function              = "usrEnergy"
      num_variables              = 1
}
EQUATION {
      ...
      user_equations             = {energy}
      ...
}
STAGGER( energy ) {
      equation                   = user_equation
      user_equation              = "energy"
}
TIME_SEQUENCE {
      ...
      staggers                   = {particle,energy}
      ...
}
The C AcuTrace user function usrEnergy could be written as follows:
Void usrEnergy (
               UfpHd       ufpHd,
               Real*       outVec
               Integer     nItems,
               Integer     vecDim  
)
{
      ... 
      outVec[0] =  cond /  ( m_p * cp_p ) * e_particle[0] – 
                   cond * t_fluid[0] ;
      ...
}

outVec[0] contains the source term for the particle energy; the source term provided to AcuSolve is this same value times -1.

See the AcuTrace User-Defined Function Reference Manual for more details on writing and using AcuTrace user-defined functions.

Another requirement in this example for the coupling to have effect is that the AcuSolve input file should have the temperature equation defined:
EQUATION {
      ...
      temperature                = advective_diffusive
      ...
}
and used in an active stagger, for example:
TIME_SEQUENCE {
      ...
      staggers                   = { "flow",
                                 "temp_part" }
      ...
}
STAGGER( "temp_part" ) {
      ...
      equation                   = none
      staggers                   { "temperature",
                                 "particle_trace" }
      ...
}
STAGGER( "temperature" ) {
      equation                   = temperature 
}

Our second example illustrates using value coupling as an alternative to AcuSolve species transport. In this example, particles are used to represent species 1 and, therefore, AcuTrace is effectively evolving species 1.

The number of particle components is set to 1 in the equation command:
EQUATION {
      ...
      number particle components = 1
      ...
}
The COUPLING_FIELDS command
COUPLING_FIELDS {
      ...
      species_1_type             = value
      species_1_value_type       = component
      ...
}
specifies that the value of the particle component couples to AcuSolve species 1. In other words, the particle component will be averaged over all the particles onto the AcuSolve mesh to provide AcuSolve with values of species 1. The components of the particles can be initialized as follows in the trace input file:
PARTICLE_SEED( "honey" ) {
      ...
      component_type             = constant 
      constant_components        = { 1.0 } 
      ...
}
PARTICLE_SEED( "tea" ) {
      ...
      component_type             = constant 
      constant_components        = { 0.0 } 
      ...
}

The component for the particles in seed group "honey" is set to 1, in other words, species 1 will equal 1 in regions containing these particles alone. Similarly, species 1 will equal 0 in regions containing particles from the second seed group alone.

In the AcuSolve input file, the EQUATION command specifies that there is a single species,
EQUATION {
      ...
      species_transport          = advective_diffusive 
      num_species                = 1 
      ...
}
but that a particle trace stagger is to be used instead of a species stagger:
TIME_SEQUENCE {
      ...
      staggers                   = { "flow",
                                 "particle_trace" }
      ...
}

The parameter coupling_iterations specifies the number of AcuTrace iterations per AcuSolve time step. A single AcuTrace iteration advances all the particles from the beginning to the end of the AcuSolve time step. Ideally, the value of coupling_iterations should equal to the number of times the particle trace stagger is invoked during an AcuSolve time step.

For example, suppose the AcuSolve inputs include following time sequence and stagger parameters:
TIME_SEQUENCE {
      ...
      staggers                   = { "flow",
                                 "temp_part" }
      ...
}
STAGGER( "temp_part" ) {
      equation                   = none 
      min_stagger_iterations     = 3 
      max_stagger_iterations     = 3
      staggers                   = { "temperature",
                                 "particle_trace" }
}
STAGGER( "particle_trace" ) {
      equation                   = particle_trace 
}

Here AcuSolve will invoke the particle trace stagger three times per AcuSolve time step; therefore, the value of coupling_iterations should be three. If the value of coupling_iterations is smaller than three, the two and three invocations of the particle trace stagger will have no effect on the AcuSolve solution. A value of coupling_iterations greater than three is effectively ignored since AcuSolve will invoke AcuTrace exactly three times.

If the AUTO_SOLUTION_STRATEGY is used by AcuSolve, AcuSolve will invoke AcuTrace only once, so the value of coupling_iterations is effectively one.