STAGGER

Type

AcuTrace Command

Syntax

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

Qualifier

User-given name.

Parameters

equation (enumerated) [=none]

Equation to be solved.

none: No equation solved.
particle: Particle motion equation.
stretch: Stretch equation.
user_equation: User-defined equation.

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 for this stagger. If 0, this option is ignored.

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

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, that is, the LHS is not updated. Is this its own entry or a subset of the one above?

Nonlinear (boolean) [=on]

Flag specifying whether or not to use the nonlinear solver. Ignored if equation is particle (nonlinear is always on) or stretch (nonlinear is always off.)

user_equation (string) [no default]

User equation to use if equation is user_equation.

staggers (list) [={}]

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 = { "particle" }
}
STAGGER( "particle" ) {
   equation = particle
}
STAGGER( "stretch" ) {
   equation = stretch
}

The particle stagger is directly referenced, therefore its equation is solved. The stretch stagger is not referenced, therefore its equation is not solved.

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

TIME_SEQUENCE {
   staggers = { "particle", "reaction" }
}
STAGGER( "reaction" ) {
   equation               = none
   min_stagger_iterations = 2
   max_stagger_iterations = 2
   staggers               = { "temperature", "composition" }
}
STAGGER( "particle" ) {
   equation = particle
...
}
STAGGER( "temperature" ) {
   equation      = user_equation
   user_equation = temperature
...
}
STAGGER( "composition" ) {
   equation      = user_equation
   user_equation = composition
...
}

This option does provide a powerful mechanism for building a custom nonlinear solution strategy. It is currently needed only for solving coupled user equations, as in the example just above, where the user equations temperature and composition are coupled.

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 one or more PARTICLE_SEED commands or one or more USER_EQUATION_INITIAL_CONDITION commands.

Generally speaking, 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. Particle traces are computed as a series of segments using fifth-order time-discontinuous Galerkin (TDG) with error control. Given a segment start point, a particle stagger computes the endpoint of a single segment of the trace of a single particle using a nonlinear iterative solver. A stretch stagger, on the other hand, is always solved with a linear, non-iterative, direct update. User equation staggers can also be solved in this manner if appropriate, although generally a nonlinear iterative solver is used.

For all nonlinear iterative solutions, 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.