STAGGER

Specifies a stagger for the solution of an equation.

Type

AcuSolve Command

Syntax

STAGGER("name") {parameters...}

Qualifier

User-given name.

Parameters

equation (enumerated) [=none]

Equation to be solved.

none: No equation solved.
pressure or pres: Discrete pressure Poisson equation.
velocity or vel: Momentum equations.
flow: Flow equations - momentum and continuity equations.
compressible_flow: Compressible equations.
temperature or temp: Energy equation.
radiation or rad: Radiation heat flux equation. Also, p1 incident radiation equation or discrete ordinates method for solving the radiative transfer equation.
temperature_flow or temp_flow: Coupled energy and flow equations.
species_1 or spec1: Species 1 transport equation.
species_2 or spec2: Species 2 transport equation.
species_3 or spec3: Species 3 transport equation.
species_4 or spec4: Species 4 transport equation.
species_5 or spec5: Species 5 transport equation.
species_6 or spec6: Species 6 transport equation.
species_7 or spec7: Species 7 transport equation.
species_8 or spec8: Species 8 transport equation.
species_9 or spec9: Species 9 transport equation.
field: Field transport equation. Used with phase field multi field transport model.
levelset: Level set transport equation. Used with level set multi field transport model.
levelset_redistancing: Level set sharpening equation. Used with level set multi field transport model.
turbulence or turb: Turbulence equation. Valid only with Spalart-Allmaras and Detached Eddy Simulation turbulence models.
kinetic_energy or tke: Turbulent kinetic energy equation. Valid only with SST, k-omega, and SST-DES turbulence models.
eddy_frequency or tomega: Eddy frequency equation. Valid only with SST, k-omega, and SST-DES turbulence models.
dissipation_rate or teps: Dissipation rate equation. Valid only with k-epsilon, realizable k-epsilon and RNG k-epsilon turbulence models.
intermittency or tintc: Turbulence intermittency equation. Valid only with the Gamma-Re_theta and Gamma turbulent transition models.
transition_re_theta or treth: Critical momentum thickness Reynolds Number equation. Valid only with the Gamma-Re_theta turbulent transition models.
viscoelastic or vest: Viscoelastic stress equations.
topology_pressure or topopres: Adjoint (topology) pressure equation.
topology_velocity or topovel: Adjoint (topology) momentum equations.
topology_flow: Adjoint (topology) flow equations – adjoint momentum and adjoint pressure equations.
mesh_displacement or mesh: Mesh displacement equation.
external_code: Solution for solid/structural equations provided by an external code.
particle: Solution for particle equations by AcuTrace.

explicit_type (enumerated) [=none]

Type of explicit strategy for this stagger.

none: Standard implicit strategy used.
advection or convection: Advection term treated explicitly.

min_stagger_iterations or min_stg_iters (integer) >=0 [=1]

Minimum number of nonlinear iterations for this stagger.

max_stagger_iterations or max_stg_iters (integer) >=0 [=1]

Maximum number of nonlinear iterations of this stagger. If zero, this option is ignored.

convergence_tolerance or conv_tol (real) >=0 [=1.e-4]

Convergence tolerance to end nonlinear iterations of this stagger.

lhs_update_frequency or lhs_freq (integer) >=0 [=1]

The nonlinear iteration frequency at which the left-hand-side (LHS) matrix of this stagger is discarded. If zero, this option is ignored.

linear_solver or les (enumerated) [=gmres]

Linear equation solver of this stagger.

gmres: GMRES iterative solver. May be used for all but the pressure and mesh equations.
bicgstab: BiCGStab iterative solver. May be used for all but the pressure and mesh equations.
conjugate_gradient or cg: Conjugate-Gradient iterative solver. May be used only for the pressure and mesh equations.

min_linear_solver_iterations or min_les_iters (integer) >=0 [=1]

Minimum number of iterations of the linear solution.

max_linear_solver_iterations or max_les_iters (integer) >0 [=1000]

Maximum number of iterations of the linear solution.

num_krylov_vectors or kvecs (integer) >0 [=10]

Number of Krylov vectors used by GMRES and BiCGStab.

linear_solver_tolerance or les_tol (real) >=0 [=0.1]

Linear solver convergence tolerance.

pressure_projection_tolerance or pres_tol (real) >=0 [=0.1]

Convergence tolerance of the pressure projection algorithm used for the flow or temperature_flow equation. Used if pressure_projection is turned on.

velocity_projection_tolerance or vel_tol (real) >=0 [=0.1]

Convergence tolerance of the velocity projection algorithm used for the flow or temperature_flow equation. Used if velocity_projection is turned on.

temperature_projection_tolerance or temp_tol (real) >=0 [=0.1]

Convergence tolerance of the temperature projection algorithm used for the temperature_flow equation. Used if temperature_projection is turned on.

projection or proj (boolean) [=on]

Flag specifying whether or not to use projection (deflation) within the linear solution.

pressure_projection or pres_proj (boolean) [=on]

Flag specifying whether or not to use pressure projection within the linear solver for the solution of the flow or temperature_flow equation.

velocity_projection or vel_proj (boolean) [=off]

Flag specifying whether or not to use velocity projection within the linear solver for the solution of the flow or temperature_flow equation.

temperature_projection or temp_proj (boolean) [=off]

Flag specifying whether or not to use temperature projection within the linear solver for the solution of the temperature_flow equation.

pressure_algebraic_multigrid or pres_amg (boolean) [=off]

Flag specifying whether or not to use pressure algebraic multigrid preconditioning for the preconditioned conjugated gradient solver. Used with pressure, flow, and temperature_flow equations.

pressure_algebraic_multigrid_update_frequency (integer) >0 [=0]

Frequency to update the pressure algebraic multigrid parameters.

algebraic_multigrid or amg (boolean) [=off]

Flag specifying whether or not to use algebraic multigrid preconditioning. Used with flow, turbulence, temperature, species, mesh_displacement, and viscoelastic equations.

algebraic_multigrid_update_frequency (integer) >0 [=0]

Frequency to update the algebraic multigrid parameters. Used with flow, turbulence, temperature, species, mesh_displacement, and viscoelastic equations when algebraic_multigrid=on.

velocity_algebraic_multigrid or vel_amg (boolean) [=off]

Flag specifying whether or not to use algebraic multigrid preconditioning for the GMRES solver when solving the velocity equations. Used with flow and temperature_flow equations when the velocity_projection=on.

velocity_algebraic_multigrid_update_frequency (integer) >0 [=0]

Frequency to update the velocity algebraic multigrid parameters. Used with flow and temperature_flow equations when velocity_projection=on and when velocity_algebraic_multigrid=on.

temperature_algebraic_multigrid or temp_amg (boolean) [=off]

Flag specifying whether or not to use algebraic multigrid preconditioning for the GMRES solver when solving the temperature equation. Used with temperature_flow equations when temperature_projection=on.

temperature_algebraic_multigrid_update_frequency (integer) >0 [=0]

Frequency to update the temperature algebraic multigrid parameters. Used with temperature_flow equations when temperature_projection=on and temperature_algebraic_multigrid=on.

staggers or stgs (list) (no default)

List of sub-staggers to be executed. The sub-staggers, if any, are executed after the main equation of the stagger is solved.

Description

This command specifies the nonlinear iteration and linear solver parameters for the solution of an equation. This command also accommodates execution of other staggers. For a detailed description of time stepping and nonlinear solution strategy, see the TIME_SEQUENCE command.

In order for a stagger to be executed, it must be referenced directly or indirectly by the TIME_SEQUENCE command. Direct reference is accomplished by adding the user-given name of the STAGGER command to the list of staggers in the staggers parameter of the TIME_SEQUENCE command. For example, in the following:

TIME_SEQUENCE {
    staggers                 = { "flow" }
}
STAGGER( "flow" ) {
   equation                  = flow
}
STAGGER( "temp" ) {
   equation                  = temperature
}

The "flow" stagger is directly referenced, therefore its equation is solved. The "temp" stagger is not referenced, therefore its equation is not solved.

A stagger may also be indirectly referenced through another (referenced) stagger. For example,

EQUATION {
   flow                               = navier_stokes
   multi_field                        = levelset
   fields                             = {"water","air";}
}
TIME_SEQUENCE {
   staggers = { "flow_levelset", "redistancing" }
   ...
}
STAGGER( "flow_levelset" ) {
   equation                            = none
   min_stagger_iterations              = 2
   max_stagger_iterations              = 6
   ...
   staggers                            = { "flow","levelset"}
}
STAGGER( "flow" ) {
   equation                            = flow
   ...
}
STAGGER( "levelset" ) {
   equation                            = levelset
   ...
}
STAGGER( "redistancing" ) {
   equation                            = levelset_redistancing
   ...
}

This example demonstrates the use of this feature for an immiscible multi-field simulation where it is desirable to iterate the flow and scalar fields to convergence before performing any sharpening of the interface.

The turbulence equation types dynamic_model and large_eddy_simulation are not solved through staggers, but rather recomputed at the beginning of each nonlinear iteration. The turbulence equations for the SST, k-omega, BSL k-omega, SST-DES, k-epsilon, realizable k-epsilon and RNG k-epsilon turbulence models are solved in a segregated fashion, requiring a separate stagger for each equation. In the case of the k-omega based models, the staggers can be specified as follows:

STAGGER( "eddy_frequency" ) {
   equation                            = eddy_frequency
   lhs_update_frequency                = 1
   linear_solver                       = gmres
   linear_solver_tolerance             = .001
   projection                          = off
}
STAGGER( "kinetic_energy" ) {
   equation                           = kinetic_energy
   lhs_update_frequency               = 1
   linear_solver                      = gmres
   linear_solver_tolerance            = .01
   projection                         = off
}
STAGGER( "turbulence" ) {
   equation                           = none
   min_stagger_iterations             = 1
   max_stagger_iterations             = 3
   staggers                           = {"eddy_frequency","kinetic_energy"}
}

The eddy frequency-equation does not have a strong dependence on the kinetic energy equation. However, the kinetic energy source term is strongly impacted by changes in eddy frequency. Therefore, the kinetic energy is typically solved after the eddy frequency in the stagger sequence.

Additionally, the kinetic energy and eddy frequency are solved multiple times for each solve of the flow equations. Experience has shown that this leads to the most optimal convergence rate:

TIME_SEQUENCE{
 staggers = {   "flow",
                "turbulence" }
}

The eddy frequency stagger represents a special case in which the transport quantity used by the stagger deviates from the standard equation for eddy frequency. Instead of solving directly for $ω$ , AcuSolve constructs the transport equation in terms of 1/sqrt( $ω$ ). This change of variables does not change the solution produced by the SST and k-omega turbulence models. However, the change of variables does lead to significant improvements in stability. The actual transport quantity (1/sqrt( $ω$ )) is written as sqrt_eddy_period in the nodal field outputs. The eddy_frequency variable that appears in the nodal outputs is computed based on the solution for sqrt_eddy_period.

For k-epsilon based models, a similar solution strategy is used. The dissipation rate is solved before the kinetic energy and the turbulence equations are solved multiple times for each flow solve:

STAGGER( "dissipation_rate" ) {
   equation                            = dissipation_rate
   lhs_update_frequency                = 1
   linear_solver                       = gmres
   linear_solver_tolerance             = .001
   projection                          = off
}
STAGGER( "kinetic_energy" ) {
   equation                            = kinetic_energy
   lhs_update_frequency                = 1
   linear_solver                       = gmres
   linear_solver_tolerance             = .01
   projection                          = off
}
STAGGER( "turbulence" ) {
   equation                            = none
   min_stagger_iterations              = 1
   max_stagger_iterations              = 3
   staggers = {"dissipation_rate","kinetic_energy"}
}
TIME_SEQUENCE{
   staggers                            = {   "flow",
                                             turbulence"}
}

The viscoelastic stress equations are solved as a coupled set, and therefore only require a single stagger. For example:

STAGGER( "viscoelastic" ) {
   equation                       = viscoelastic
   lhs_update_frequency           = 1
   linear_solver                  = gmres
   linear_solver_tolerance        = .01
   projection                     = off
}

The equation of a referenced stagger must be set via the EQUATION command. On the other hand, an equation set by the EQUATION command does not need to be referenced by any stagger. In this case, the solution field(s) of such equations simply retain their initial values throughout the analysis. The initial values come from either the NODAL_INITIAL_CONDITION command or the restart file.

Each stagger loops over a number of nonlinear iterations, within which the residual and optionally the LHS matrix of the stagger are formed, the resulting linear equation system is solved, the corresponding solution field is updated and its sub-staggers are executed. A minimum of min_stagger_iterations and a maximum of max_stagger_iterations nonlinear iterations are performed. If the convergence measures are less than the convergence_tolerance and min_stagger_iterations iterations performed, the stagger loop is done. See the TIME_SEQUENCE command for definitions.

Setting the explicit_type to advection removes the advection term from the LHS. It has no effect on the residual but it imposes a CFL limit of about one for stability. For transient problems where small time increments are used anyway for accuracy, this strategy can greatly reduce the CPU required. It is most effective when used together with a strategy that reforms the LHS less often and has just one stagger iteration per time step. However, explicit strategies are far less robust than the standard implicit strategies so you should approach this parameter with caution.

The iterative solvers gmres, bicgstab and conjugate_gradient are used to solve the linear equation systems resulting from the linearization of the discrete finite element formulation. The first two solvers are used for non-symmetric equation systems, while conjugate_gradient is used for the symmetric discrete pressure Poisson and mesh equations. In all cases, a minimum of min_linear_solver_iterations and a maximum of max_linear_solver_iterations linear iterations are performed. The linear solver may terminate earlier if the residual norm, normalized with respect to the initial residual norm, reaches the linear_solver_tolerance and the min_linear_solver_iterations criteria is satisfied.

Both gmres and bicgstab algorithms require a set of Krylov vectors, whose sizes are defined by num_krylov_vectors. Larger Krylov spaces typically increase the robustness and the rate of convergence of the algorithm, but require more memory. For simple problems, the Krylov space of 10 for the flow equation is sufficient. For harder problems, a Krylov space of 40 or larger may be required.

The memory for the Krylov vectors of the staggers is overlapped. This memory is proportional to the product of the num_krylov_vectors, the number of degrees of freedom (DOF) per node and the number of nodes in the system. The flow stagger has four dofs per node, the velocity stagger has three DOFs per node, the viscoelastic stagger has six DOFs per node, and all others have one DOF per node. Optimum memory usage is achieved when the num_krylov_vectors of the staggers keeps the same proportions. For example,

STAGGER( "flow" ) {
   equation                            = flow
   num_krylov_vectors                  = 15
}
STAGGER( "turb" ) {
   equation                            = turbulence
   num_krylov_vectors                  = 60
}

Each of the three linear solvers are equipped with a projection, also known as deflation, algorithm which accelerates the convergence rate of the linear solver at the expense of memory and computational cost per iteration. Projection algorithms work by building information about the linear equation system in the course of solving each linear system. This information is then used to accelerate convergence. The projection is turned on and off through the projection parameter. The dimension of the projection vectors is given by the LINEAR_SOLVER_PARAMETERS command.

Experience has shown that projection helps difficult problems while it is more expensive for simple ones. For problems where the LHS matrix does not change significantly from one nonlinear iteration to the next, projection is very effective. Use of projection with a tight convergence tolerance is recommended for the solution of the temperature equation when solving a conjugate heat transfer problem. For example,

STAGGER( "temp" ) {
   equation                            = temperature
   min_stagger_iterations              = 1
   max_stagger_iterations              = 1
   convergence_tolerance               = 1.e-3
   lhs_update_frequency                = 1
   linear_solver                       = gmres
   min_linear_solver_iterations        = 10
   max_linear_solver_iterations        = 400
   num_krylov_vectors                  = 40
   linear_solver_tolerance             = 1.e-3
   projection                          = on
}
LINEAR_SOLVER_PARAMETERS {
   num_temperature_projection_vectors  = 10
}

A special and proprietary variant of the GMRES and BiCGStab algorithms is used for solving the flow equation. This algorithm performs pressure and velocity projections to greatly enhance the robustness and convergence of the linear solver. These projections are controlled by the pressure_projection and velocity_projection parameters and their associated tolerance parameters. The tighter the tolerance of the pressure projection, the better the continuity equation can be satisfied. Typically, pressure_projection_tolerance is set an order of magnitude tighter than linear_solver_tolerance, while velocity_projection_tolerance is set equal to linear_solver_tolerance. The number of pressure and velocity projection vectors is set in the LINEAR_SOLVER_PARAMETERS command. The following is a typical flow stagger:

STAGGER( "flow" ) {
   equation                            = flow
   min_stagger_iterations              = 1
   max_stagger_iterations              = 1
   convergence_tolerance               = 1.e-3
   lhs_update_frequency                = 1
   linear_solver                       = gmres
   min_linear_solver_iterations        = 10
   max_linear_solver_iterations        = 400
   num_krylov_vectors                  = 10
   linear_solver_tolerance             = 0.1
   pressure_projection_tolerance       = 0.01
   pressure_projection                 = on
   velocity_projection_tolerance       = 0.1
   velocity_projection                 = on
   projection                          = off
}
LINEAR_SOLVER_PARAMETERS {
   num_pressure_projection_vectors     = 10
   num_velocity_projection_vectors     = 4
   num_flow_projection_vectors         = 4
}

For hard problems the num_krylov_vectors can be increased and the projection flag turned on. Experience has shown that velocity projection is rarely helpful, with one exception being for flows with highly nonlinear non-Newtonian viscosity models.

Pressure algebraic multigrid preconditioning can be added to the preconditioned conjugated gradient solver for the pressure, flow, and temperature_flow equations. The frequency of updating the algebraic multigrid state variables is controlled with pressure_algebraic_multigrid_update_frequency. See ALGEBRAIC_MULTIGRID_PARAMETERS to adjust the other parameters of the method. For example,

STAGGER( "flow" ) {
   equation                                        = flow
   ...
   pressure_algebraic_multigrid                    = on
   pressure_projection                             = on
   pressure_algebraic_multigrid_update_frequency   = 0
}

The pressure and velocity stagger equations are used to solve a flow problem via a segregated solver strategy. The pressure equation corresponds to a discrete pressure Poisson equation, which updates both the pressure and velocity equations to satisfy the continuity equation. The velocity equation corresponds to a regularized momentum solver for the velocity field. These equations, collectively known as the segregated solver, are rarely used. Instead the use of a flow stagger is recommended. The flow stagger is significantly more stable and has a much faster nonlinear convergence rate.

For flows where the temperature, velocity, and pressure are all tightly coupled together, such as free convection flows at high Grashof numbers, a solution strategy that contains separate flow and temperature staggers can behave much like a segregated solver. That is, because key coupling terms are neglected in the linearization of the system, the nonlinear convergence may be a lot slower than you would expect. In the temperature_flow equation, these coupling terms are included. This results in nonlinear convergence comparable to that for isothermal flows. However, the memory usage will be about 50 percent greater than for the two-stagger strategy and the cost for each linear solve will typically be much greater due to the complexity and stiffness of the matrix system. In addition to velocity and pressure projections, the algorithm includes temperature projection. This projection is controlled by the temperature_projection and temperature_projection_tolerance parameters, and is recommended for most cases. The following is a typical temperature_flow stagger:

STAGGER( "temperature_flow" ) {
   equation                                 = temperature_flow
   min_stagger_iterations                   = 1
   max_stagger_iterations                   = 1
   convergence_tolerance                    = 1.e-3
   lhs_update_frequency                     = 1
   linear_solver                            = gmres
   min_linear_solver_iterations             = 10
   max_linear_solver_iterations             = 400
   num_krylov_vectors                       = 10
   linear_solver_tolerance                  = 0.1
   pressure_projection_tolerance            = 0.01
   pressure_projection                      = on
   velocity_projection_tolerance            = 0.1
   velocity_projection                      = on
   temperature_projection_tolerance         = 0.001
   temperature_projection                   = on
   projection                               = off
}
LINEAR_SOLVER_PARAMETERS {
   num_pressure_projection_vectors          = 10
   num_velocity_projection_vectors          = 4
   num_temperature_flow_projection_vectors  = 4
   num_temperature_projection_vectors       = 4
}

Since the cost, per linear iteration, of solving the turbulence and species linear equation system is significantly less than that of the flow equation, it is recommended to have tighter tolerances for these equations. Also, as mentioned above, the num_krylov_vectors may be four times larger than the one for the flow equation without increasing the memory usage. Hence, the stagger for the turbulence equation may be set up as follows:

STAGGER( "turb" ) {
   equation                            = turbulence
   min_stagger_iterations              = 1
   max_stagger_iterations              = 1
   convergence_tolerance               = 1.e-3
   lhs_update_frequency                = 1
   linear_solver                       = gmres
   min_linear_solver_iterations        = 10
   max_linear_solver_iterations        = 400
   num_krylov_vectors                  = 40
   linear_solver_tolerance             = 0.01
   projection                          = off
}
LINEAR_SOLVER_PARAMETERS {
   num_turbulence_projection_vectors   = 5
}

The stagger for each species may be set up in a similar fashion.

If the radiation equation is of type enclosure, the heat fluxes from the radiation stagger are automatically incorporated into the temperature or temperature_flow stagger. If the radiation equation is of type p1_model or discrete_ordinate, radiative heat sources and sinks are automatically incorporated as a source term in the energy equation when temperature = advective_diffusive. Thus the radiation stagger looks very similar to the other scalar equation staggers. For example,

STAGGER( "radiation" ) {
    equation = radiation
    min_stagger_iterations = 1
    max_stagger_iterations = 1
    convergence_tolerance = 1.e-3
    lhs_update_frequency = 1
    linear_solver = gmres
    min_linear_solver_iterations = 10
    max_linear_solver_iterations = 400
    num_krylov_vectors = 40
    linear_solver_tolerance = 0.01
    projection = on
}
LINEAR_SOLVER_PARAMETERS {
    num_radiation_projection_vectors = 5
}

For the discrete ordinates model the above would include a list of sub-staggers, which represent the staggers for the individual ordinate directions. For example, if the radiation_quadrature = S2 then the radiation stagger would be:

STAGGER( "radiation" ) {
    equation = radiation
    min_stagger_iterations = 1
    max_stagger_iterations = 1
    convergence_tolerance = 1.e-3
    lhs_update_frequency = 1
    linear_solver = gmres
    min_linear_solver_iterations = 10
    max_linear_solver_iterations = 400
    num_krylov_vectors = 40
    linear_solver_tolerance = 0.01
    projection = on
    staggers = {"discrete_ordinate_1",
                "discrete_ordinate_2",
                "discrete_ordinate_3",
                "discrete_ordinate_4",
                "discrete_ordinate_5",
                "discrete_ordinate_6",
                "discrete_ordinate_7",
                "discrete_ordinate_8" } ;
}

The sub-stagger discrete_ordinate_N, where N is the ordinate number, for example, 1-8 for S2, would then be defined for each ordinate direction. For example, the first ordinate direction:

STAGGER( "discrete_ordinate_1" ) {
      equation = radiation ;
      discrete_ordinate_direction = 1 ;
      explicit_type = none ;
      min_stagger_iterations = 1 ;
      max_stagger_iterations = 1 ;
      convergence_tolerance = 0.1 ;
      lhs_update_frequency = 1 ;
      linear_solver = gmres ;
      min_linear_solver_iterations = 10 ;
      max_linear_solver_iterations = 1000 ;
      num_krylov_vectors = 40 ;
      linear_solver_tolerance = 0.1 ;
      pressure_projection_tolerance = 0.1 ;
      velocity_projection_tolerance = 0.1 ;
      temperature_projection_tolerance = 0.1 ;
      projection = on ;
}

For solving the solid/structural part of a Direct Coupling Fluid Structural Interaction (DC-FSI) problem, set equation to external_code. This transfers control to an external code for this part of the solution. For example,

STAGGER( "abaqus" ) {
 equation                              = external_code
 min_stagger_iterations                = 1
 max_stagger_iterations                = 1
}

The above command specifies the Conventional Sequential Staggered (CSS) explicit coupling strategy. If max_stagger_iterations is larger than one then the Multi-Iterative Coupling (MIC) implicit strategy is used. See the EXTERNAL_CODE command for more information on solving DC-FSI problems.

For solving the particle part of a coupled particle-flow problem, set equation to particle. This transfers control to AcuTrace for this part of the solution. For example,

STAGGER( "particle" ) {
 equation                              = particle
}