# 4.8.1. Solution Control

All Aria input files must include a Solution Control Description block in the Procedure section of the input file. This description contains directives for executing a steady-state (sequential) or 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 step, whereas for a Steady Analysis this corresponds to solving the steady problem (i.e. taking the ONLY 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.

Typically, regions control their own postprocessing when they during `advance`. In rare cases, one may wish to trigger the postprocessors manually (e.g. adaptivity). To do so, one can explicitly `postprocess` at any point in a solution control block.

## 4.8.1.1. Steady Analysis

To set up a simple steady analysis, a Sequential block can be used to `advance` a region. As a simple example

###### Simple Sequential Input

    Begin Sierra myJob

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

      Begin Procedure myProcedure

        Begin Solution Control Description
          # Note that the description calls out the system to use
          Use System Main
          Begin System Main
            Begin Sequential MySolveBlock
              Advance steadyRegion
            End
          End
        End

        Begin Aria Region steadyRegion
          # ICs, BCs, equations, output, etc
          ...
        End Aria Region steadyRegion

        ...
      End Procedure myProcedure
    End Sierra myJob

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 Aria and Adagio via Arpeggio. For weak coupling with apps outside of the Sierra ecosystem, see File Based Coupling. For stronger coupling, see MPMD Coupling.

When the different problem physics are weakly-coupled, one is assuming that for each solution step it is sufficient to supply current values of variables involved in the coupling. In this case, the regions can be sequentially `advance`d with information exchanged in between via `transfer`s. Below, an example of a weakly coupled Aria-Adagio simulation is provided

###### Weakly Coupled Sequential Input

    Begin Sierra myJob

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

      Begin Procedure myProcedure

        Begin Solution Control Description
          Use System Main
          Begin System Main
            Begin Sequential MySolveBlock
              Advance ariaRegion
              transfer aria_to_adagio
              Advance adagioRegion
              transfer adagio_to_aria
            End
          End
        End

        Begin Aria Region ariaRegion
          # ICs, BCs, equations, output, etc
          ...
        End Aria Region ariaRegion

        Begin Adagio Region adagioRegion
          # ICs, BCs, equations, output, etc
          ...
        End Adagio Region adagioRegion

        Begin transfer adagio_to_aria
          # transfer commands
          ...
        End transfer adagio_to_aria

        Begin transfer aria_to_adagio
          # transfer commands
          ...
        End transfer aria_to_adagio

        ...
      End Procedure myProcedure
    End Sierra myJob

For a stronger coupling, one may chose to iterate within a solution step until the interaction between physics has converged. This is accomplished by specifying a Nonlinear command block within the sequential block. Here the nonlinear iteration will continue until user specified criteria Parameters for Nonlinear Iteration is satisfied

###### Stronger Coupled Sequential Input

    Begin Sierra myJob

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

      Begin Procedure myProcedure

        Begin Solution Control Description
          Use System Main
          Begin System Main
            Begin Sequential MySolveBlock
              Begin Nonlinear Iteration
                Advance ariaRegion
                transfer aria_to_adagio
                Advance adagioRegion
                transfer adagio_to_aria
              End
            End
          End
        End

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

        Begin Aria Region ariaRegion
          # ICs, BCs, equations, output, etc
          ...
        End Aria Region ariaRegion

        Begin Adagio Region adagioRegion
          # ICs, BCs, equations, output, etc
          ...
        End Aria Region adagioRegion

        Begin transfer adagio_to_aria
          # transfer commands
          ...
        End transfer adagio_to_aria

        Begin transfer aria_to_adagio
          # transfer commands
          ...
        End transfer aria_to_adagio

        ...
      End Procedure myProcedure
    End Sierra myJob

## 4.8.1.2. Transient Analysis

Similar to a sequential block, a Transient block defines the way transient region(s) advance. A simple example of a transient solution control block will look similar to that of a sequential analog, except that additional 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 `adapative` timestep transient. See Time Step Selection for guidance on setting these parameters.

###### Simple Transient Input

    Begin Sierra myJob

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

      Begin Procedure My_Aria_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_Aria_Region
            End
            Begin Transient Time_Block_2
              Advance My_Aria_Region
            End
          End

          #Parameters for Time_Block_1 behavior
          Begin Parameters For Transient Time_Block_1
            Start Time      = 0.0
            Number of steps = 8
            Begin Parameters For Aria Region My_Aria_Region
              Time Step Variation    = Fixed
              Initial Time Step Size = 0.001
            End
          End

          #Parameters for Time_Block_2 behavior
          Begin Parameters For Transient Time_Block_2
            Begin Parameters For Aria Region My_Aria_Region
              Time Step Variation           = Adaptive
              Initial Time Step Size        = 0.001
              Predictor-Corrector Tolerance = 1e-3
              Minimum Time Step Size        = 1e-6
            End
          End
        End

        ...
      End Procedure My_Aria_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.

Similar to the sequential case, 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.

###### Coupled Transient Input

    Begin Sierra myJob

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

      Begin Procedure My_Aria_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_adagio
                  Advance myAdagioRegion
                  transfer adagio_to_aria
                End Nonlinear Iteration
            End
          End

          Begin Parameters for Nonlinear Iteration
            Converged when "myAdagioRegion.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

            #Adagio region-specific parameters for Time_Block_1
            Begin Parameters For Adagio Region myAdagioRegion
                Time increment = 0.001
            End
          End

        End Solution Control Description

        Begin transfer adagio_to_aria
          # transfer commands
          ...
        End transfer adagio_to_aria

        Begin transfer aria_to_adagio
          # transfer commands
          ...
        End transfer aria_to_adagio

        ...
      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 My_Aria_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
              Transfer Adagio_to_Aria
              Advance My_Aria_Region
              Transfer Aria_to_Adagio
              Begin Subcycle AdagioSubcycle
                Advance AdagioRegion
              End
            End

          End

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

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

            Begin Parameters for Adagio Region AdagioRegion
              initial time step = 1.0e-6
              # time step scale factor = 1.0
              time step increase factor = 10.
              # step interval = 500
            End
          End

        End

        Begin transfer adagio_to_aria
          ...
        End transfer adagio_to_aria

        Begin transfer aria_to_adagio
          ...
        End transfer aria_to_adagio

        Begin Aria Region myAriaRegion
          ...
        End Aria Region myAriaRegion

        Begin Adagio Region myAdagioRegion
          ...
        End Adagio Region myAdagioRegion

      End Procedure myProcedure
    End Sierra myJob

## 4.8.1.3. 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 AdagioRegion
            Transfer Adagio_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
              Advance My_Aria_Region
              Transfer Aria_to_Adagio
              Begin Subcycle AdagioSubcycle
                Advance AdagioRegion
              End
              Transfer Adagio_to_Aria
            End

          End

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

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

            Begin Parameters for Adagio Region AdagioRegion
              initial time step = 1.0e-6
              # time step scale factor = 1.0
              time step increase factor = 10.
              # step interval = 500
            End
          End
        End

        Begin transfer adagio_to_aria
          ...
        End transfer adagio_to_aria

        Begin transfer aria_to_adagio
          ...
        End transfer aria_to_adagio

        Begin Aria Region myAriaRegion
          ...
        End Aria Region myAriaRegion

        Begin Adagio Region myAdagioRegion
          ...
        End Adagio Region myAdagioRegion

      End Procedure myProcedure
    End Sierra myJob