# 4.5. Solution Control

All Fuego input files must include either a Solution Control Description or a Time Control block in the Procedure section of the input file. When using Solution Control this description contains directives for executing a transient analysis ranging from simple single-region analyses to more complicated multi-region execution including transfer, nested nonlinear iterations, and/or subcycling.

A solution control block has three parts:

System

  Controls how the simulation is advanced

Parameters

  Parameters to inform how each region is handled by `system`

Initialization

  Additional actions to do at startup before `system`-defined behavior

See the command reference for details on all possible commands.

The system block controls how the analysis progresses by `advance`ing the relevant region(s). For a Transient Analysis this corresponds to taking a time step.

When there are multiple regions involved in an analysis, it is often necessary to transfer information between them. Once a transfer block is set up, this is accomplished with the `transfer` directive. These more complex analyses may also require explicitly initialization of fields. Depending on the simulation types, various parameters are required, as is demonstrated in the sections below.

Though its often more favorable to solve fully-coupled physics within a single application, this is not always possible. As an alternative, loose-coupling is often carried out by exchanging solution information across multiple applications. Solution control provides various means of carrying out these analyses depending upon the strength of physics coupling within a solution step.

Note

This section refers to coupling within the Sierra ecosystem, e.g. coupling Fuego and Aria via fuego_aria.

## 4.5.1. Transient Analysis

A Transient block defines the way transient region(s) advance. Parameters are required to describe the time range of the simulation. Additionally, parameters defining the time integration for each Region must also be supplied by the user. The example below demonstrates both a `fixed` and `adaptive` timestep transient.

###### Simple Transient Input

    Begin Sierra myJob

      # Materials, Solvers, Finite Element Model, etc
      ...

      Begin Procedure My_Fuego_Procedure

        Begin Solution Control Description

          Use System Main

          Begin System Main
            Simulation Start Time            = 0.0
            Simulation Termination Time      = 10.0
            Simulation Max Global Iterations = 1000

            Begin Transient Time_Block_1
              Advance My_Fuego_Region
            End
            Begin Transient Time_Block_2
              Advance My_Fuego_Region
            End
          End

          #Parameters for Time_Block_1 behavior
          Begin Parameters For Transient Time_Block_1
            Start Time      = 0.0
            Number of steps = 8
            Initial deltat = 0.1
            Begin Parameters For Fuego Region My_Fuego_Region
              transient step type is fixed
            End
          End

          #Parameters for Time_Block_2 behavior
          Begin Parameters For Transient Time_Block_2
            Begin Parameters For Fuego Region My_Fuego_Region
              transient step type is automatic
              CFL LIMIT = 1.0
              Time Step Change Factor = 1.2
            End
          End
        End

        ...
      End Procedure My_Fuego_Procedure
    End Sierra myJob

Note

Note that for each named `Begin Transient [NAME]` command block there should be a corresponding `Begin Parameters for Transient [NAME]` command block which defines its parameters.

Multiple regions can be tied together either in a weak or strong coupling using `transfer`s and Nonlinear command blocks. The stronger case is demonstrated below. Here, the time step for advancement to the next solution step is negotiated between the coupled Regions based upon their respective Transient parameters. A weaker coupling can be obtained by omitting the `Begin Nonlinear` block and associated `Begin Parameters for Nonlinear Iteration`.

###### Coupled Transient Input

    Begin Sierra myJob

      # Materials, Solvers, Finite Element Model, etc
      ...

      Begin Procedure My_Fuego_Procedure

        Begin Solution Control Description

          Use System Main

          Begin System Main
            Simulation Start Time            = 0.0
            Simulation Termination Time      = 10.0
            Simulation Max Global Iterations = 1000

            Begin Transient Time_Block
                Begin Nonlinear Iteration
                  Advance myAriaRegion
                  transfer aria_to_fuego
                  Advance myFuegoRegion
                  transfer fuego_to_aria
                End Nonlinear Iteration
            End
          End

          Begin Parameters for Nonlinear Iteration
            Converged when "myFuegoRegion.MaxInitialNonlinearResidual(0) < 1E-1 && \$
                              myAriaRegion.MaxInitialNonlinearResidual(0) < 1E-1 "
          End

          Begin Parameters For Transient Time_Block_1
            Start Time      = 0.0
            Termination Time = 10.0

            #Aria region-specific parameters for Time_Block_1
            Begin Parameters For Aria Region myAriaRegion
                Time Step Variation    = adaptive
                Initial Time Step Size = 0.001
                Predictor-Corrector Tolerance = 1e-3
                Minimum Time Step Size        = 1e-6
            End

            #Fuego region-specific parameters for Time_Block_1
            Begin Parameters For Fuego Region myFuegoRegion
              transient step type is automatic
              CFL LIMIT = 1.0
              Time Step Change Factor = 1.2
            End
          End

        End Solution Control Description

        Begin transfer fuego_to_aria
          # transfer commands
          ...
        End transfer fuego_to_aria

        Begin transfer aria_to_fuego
          # transfer commands
          ...
        End transfer aria_to_fuego

        ...
      End Procedure My_Aria_Procedure
    End Sierra myJob

Note

Note here that a subblock for parameters of each region participating in the transient is present in the `Parameters` block of the transient.

Depending on the two physics being coupled, the two regions can have differing time scales. In this case a Subcycle command block can be used to subcycle the region with a smaller timescale, rather than forcing the larger timestep region to follow this smaller step. The solution will advance when the two time applications arrive at the same solution time.

###### Subcycled Transient Input

    Begin Sierra myJob

      # Materials, Solvers, Finite Element Model, etc
      ...

      Begin Procedure myProcedure

        Begin Solution Control Description

          Use System Main

          Begin System Main
            Simulation Start Time            = 0.0
            Simulation Termination Time      = 10.0
            Simulation Max Global Iterations = 1000

            Begin Transient Time_Block_1
              Transfer Fuego_to_Aria
              Advance My_Aria_Region
              Transfer Aria_to_Fuego
              Begin Subcycle FuegoSubcycle
                Advance FuegoRegion
              End
            End

          End

          Begin Parameters For Transient Time_Block_1
            Start Time      = 0.0
            Number of steps = 8
            Initial deltat = 0.01

            Begin Parameters For Aria Region My_Aria_Region
              Time Step Variation    = Fixed
              Initial Time Step Size = 1.
            End

            Begin Parameters for Fuego Region FuegoRegion
              transient step type is fixed
              maximum time step = 0.01
            End
          End

        End

        Begin transfer fuego_to_aria
          ...
        End transfer fuego_to_aria

        Begin transfer aria_to_fuego
          ...
        End transfer aria_to_fuego

        Begin Aria Region myAriaRegion
          ...
        End Aria Region myAriaRegion

        Begin Fuego Region myFuegoRegion
          ...
        End Fuego Region myFuegoRegion

      End Procedure myProcedure
    End Sierra myJob

## 4.5.2. Variable Initialization

In the case of transient analysis it is sometimes necessary to initialize a distribution of values before the analysis actually begins. This can be useful, for example, to transfer a field containing initial conditions to a coupled region. This is accomplished by using an Initialize command block. An example of this case is provided below

###### Initialization Transient Input

    Begin Sierra myJob

      # Materials, Solvers, Finite Element Model, etc
      ...

      Begin Procedure My_Aria_Procedure

        Begin Solution Control Description

          Use System Main

          begin initialize init
            Advance FuegoRegion
            Transfer Fuego_to_Aria
          end initialize init

          Begin System Main

            # Note that the system calls out the initialize to use
            Use initialize init

            Simulation Start Time            = 0.0
            Simulation Termination Time      = 10.0
            Simulation Max Global Iterations = 1000

            Begin Transient Time_Block_1
              Transfer Fuego_to_Aria
              Advance My_Aria_Region
              Transfer Aria_to_Fuego
              Begin Subcycle FuegoSubcycle
                Advance FuegoRegion
              End
            End

          End

          Begin Parameters For Transient Time_Block_1
            Start Time      = 0.0
            Number of steps = 8
            Initial deltat = 0.01

            Begin Parameters For Aria Region My_Aria_Region
              Time Step Variation    = Fixed
              Initial Time Step Size = 1.
            End

            Begin Parameters for Fuego Region FuegoRegion
              transient step type is fixed
              maximum time step = 0.01
            End
          End
        End

        Begin transfer fuego_to_aria
          ...
        End transfer fuego_to_aria

        Begin transfer aria_to_fuego
          ...
        End transfer aria_to_fuego

        Begin Aria Region myAriaRegion
          ...
        End Aria Region myAriaRegion

        Begin Fuego Region myFuegoRegion
          ...
        End Fuego Region myFuegoRegion

      End Procedure myProcedure
    End Sierra myJob