Skip to content

Time Integration and Numerical Schemes

This page covers the blocks inside unst { } that control how the equations are integrated in time and discretized in space: the explicit and implicit time integrators, the gradient reconstruction, the convective schemes, the Navier-Stokes and turbulence model options, and the wall function.

Explicit Stepping

Explicit time stepping is available for unsteady simulations, typically used for WMLES or LES.

explicit {
    # Specify the type of Runge-Kutta time integration scheme
    # Options: rk1, rk4, ssprk22, ssprk32, ssprk33, ssprk53
    method = ssprk33 # default
}

Implicit Stepping

Implicit stepping options for either steady simulations, or pseudo-time stepping unsteady simulations are specified in the implicit section.

implicit {
    # method options are either 1st order accurate backward differencing formula (BDF1) or
    # the second order version BDF2. The default is BDF2
    # This option is not relevant for steady runs and can be skipped.
    method = BDF2
    # Number of implicit iterations.
    # For steady runs, this is the maximum number of iterations
    # For unsteady runs, this is the maximum number of sub-iterations for each time step
    number of steps = 10000
    # Specify CFL value
    CFL = 10
}
CFL entry is interpreted as local CFL, meaning that every cell has a different pseudo-time step size that is computed to match the CFL number in every cell.

In most cases, we favor using adaptive local CFL time stepping. This allows the code to try larger step sizes while adjusting as needed. Adaptive stepping generally improves robustness and results in faster convergence.

    implicit {
        ...
        # Allow CFL to adaptively vary between min and max
        adaptive {
            min CFL = 0.5
            # [default = 1e4]
            max CFL = 1e4
            # In cases where turbulence model is used, CFL for
            # turbulence model equations can be limited differently
            # [default = max CFL]
            max CFL turbulence = 1e4
            # Steady runs: linearize the flow equations matrix free
            # once no CFL cures a stall [default = true]
            matrix free on stall = true
        }
    }
}

The adaptive CFL starts at min CFL and is updated after every implicit step:

  • While the steady residual falls, the CFL grows by up to 1.5 times per step, in proportion to the share of the update the step took (the line-search step length and the per-cell change limits below).
  • A step that raises the residual by more than 10% halves the CFL. A rejected step, after a failed line search or linear solve, cuts it to a quarter. Above 70% of the CFL that failed, the CFL then grows by at most 5% per step, or 1.5 times once the residual falls by more than half per step. That ceiling relaxes by 2% per step.
  • When convergence stalls (the residual falls by less than 3% per step over three steps) and the line search shortened every one of those steps, the CFL descends by 20% per step. The descent remembers the CFL that gave its best convergence rate. Once ten steps have passed without a better rate and the residual has fallen, on average, less than half as fast as at the best rate, the CFL returns there, so a stall that a lower CFL does not cure does not drag the CFL down to min CFL.
  • In a steady run, a stall that no CFL cures means the assembled Jacobian no longer gives a usable Newton direction. Once the residual is below 1% of its initial value, the flow equations then switch to a matrix-free linearization: GMRES applies the Jacobian of the full second-order residual by finite differences, preconditioned with the assembled Jacobian, so each GMRES iteration costs one residual evaluation. The switch happens when the descent returns to its best CFL, or when the line search shortened or rejected at least 18 of the last 20 steps while the residual fell by less than 3% per step on average. It lasts for the rest of the run, carries over to a restart, and is announced in the log. matrix free on stall = false keeps the assembled Jacobian throughout.
  • Each cell also has its own factor on the pseudo-time step. It shrinks in cells whose update the change limits clip and regrows where they do not, so a few stiff cells do not hold the CFL of the whole domain down. With dual time stepping, these factors and the convergence history restart with every physical time step.

max CFL is a safety limit: the adaptive CFL does not need it to converge.

Following are some options for the evaluation of Jacobian and the non-linear convergence

implicit {
    ...
    # Compute the jacobian analytically (approximate) or numerically (via finite difference)
    jacobian method = numerical # numerical (default) or analytical
    # Interval of implicit steps at which the jacobian is updated
    jacobian interval = 5 # default
    # For numerical Jacobians, we can use the Q vector to automatically
    # determine the choice of epsilon. This input controls that option.
    do auto epsilon = true #default
    # If auto epsilon set false, then instead read an input epsilon value.
    jacobian epsilon  = 1.e-6 # default
}

By default, the Jacobian is numerical: it is evaluated by finite differencing the RHS operator, so it accounts for the second order MUSCL reconstruction and the actual flux function, and supports deep convergence. The analytical option uses the analytical derivative of the van Leer convective flux instead. It is cheaper to evaluate, but approximate: it ignores the second order reconstruction, which can limit the depth of convergence. The epsilon value is what is used to perturb primitive variables (normalized by reference quantities) when computing finite difference (numerical) Jacobians. It is computed automatically by default, but may be set to a fixed value if desired.

Finally, you may choose to activate a line search algorithm for the non-linear implicit iterations to find asymptotic convergence path.

implicit {
    ...
    # Whether to use line search [default = true for steady, false for dual-time]
    do line search = true
    # Maximum relaxation factor for line search updates
    max relax = 1. # default
}

The line search is on by default for steady runs and off for dual-time (unsteady) runs. It is what keeps a lagged Jacobian usable, so it pairs with the jacobian interval = 5 default; with a dual-time inner loop the interval is back at 1 and the line search only costs an extra residual per sub-iteration. max relax adjusts what portion of the line search update to advance the solution with.

Convergence Criteria

Convergence tolerances for implicit iterations can be specified as:

convergence {
    test continuity only = true #default
    relative tolerance = 1.e-6
    absolute tolerance = 1.e-12
}

The values are L2 error norms either relative to the first iteration (normalized), or in absolute (non-normalized) sense. The implicit iterations are deemed converged when all L2 error norms for all the equations meet either the relative or absolute criteria. If the test continuity only flag is set to true (default value), L2 error norm of only the continuity equation is considered as convergence criteria.

If these inputs are not provided, the code will simply perform the full number of steps specified in the implicit section regardless of convergence level.

Gradients

Gradients feed both the MUSCL reconstruction of the convective terms and the viscous fluxes. They are specified in the gradient section:

gradient {
    # Cell gradient reconstruction method [options = gglex, lsqr, gg | default = gglex]
    method = gglex
    # Exponent p in the least-squares weight w = 1/|dx|^p [default = 2]
    lsqr weight exponent = 2
    # Fall back to Green-Gauss above this estimated condition number [default = 1.e8]
    lsqr max cond = 1.e8
}

method = gglex is Green-Gauss with corrected face averages and is the default. It is linear-exact on any mesh — a linear field is differentiated exactly — while keeping the surface-sum form, so it costs essentially the same as plain Green-Gauss. method = lsqr is a least-squares fit over the face neighbors and is also linear-exact. However, it is not recommended for high anisotropic meshes such as wall prism layers over curved surfaces. method = gg is Green-Gauss with a plain arithmetic face average, which is not linear-exact.

Convective Terms

Convective flux options are specified in the convective terms section. Three different convective schemes can be setup; MUSCL, CENTRALQ and KEEPBLEND, latter two of which are low dissipation schemes to be used in scale-resolving simulations (i.e. LES and WMLES).

MUSCL Scheme

The traditional \(2^\mathrm{nd}\) order MUSCL scheme with limited gradient reconstruction can be setup with:

convective terms {
    # Convective flux scheme (options = MUSCL, CentralQ, KEEPBLEND) [default = MUSCL]
    scheme = MUSCL
    # MUSCL reconstruction order [options = 1,2 | default = 2]
    order = 2
    # Limiter [options = none, minmod, minmod soft, rminmod, rvlmc | default = none]
    limiter = rminmod
    # Only for rminmod and rvlmc: leave faces without a shock unlimited [default = true]
    # false limits every face (see Limiter options)
    limiter gate = true
    # Only active for minmod soft, the overshoot parameter will allow normalized
    # overshoots of the specified amount. In this example, it is set to 5%
    limiter overshoot = 0.05
    # Blended (U-MUSCL) reconstruction [range = 0 to 1 | default = 1/3]
    # 1/3 minimizes dispersion error; 0 reproduces the plain MUSCL reconstruction
    reconstruction kappa = 0.33333333333333333
    # Flux function [options = roep,ausmpw+,hrslau2,rusanov,hllec,hlleclm | default = ausmpw+]
    flux function = ausmpw+
}
Choice of flux function can have a large impact in simulation accuracy and stability. Our current best practice is ausmpw+ for runs with explicit time integration and for implicit runs at supersonic speeds or with dual time stepping, and hlleclm for steady implicit runs of low-speed viscous flows, where it converges faster and is more accurate in the low-Mach regions. At high Mach numbers, we recommend adding extra dissipation (see High Mach Simulations section).

hlleclm is the HLLEC flux with a low-Mach correction. Selecting it sets hllcmalimit = 0.1 and hllcphifloor = 0.3 by default: the first is the Mach number below which the low-Mach branch engages, the second the floor on its dissipation scaling, which is what keeps the flux stable on stretched viscous meshes. Both can be overridden in the same section. The hlle/hllec/hlleclm family is implemented on the CPU only and is rejected with an error on a GPU run.

roep option stands for preconditioned Roe flux function, which has additional options:

convective terms {
    ...
    flux function = roep
    # Entropy fix method
    # 0: No entropy fix
    # 1: Entropy fix version 1
    # 2: Entropy fix version 2 (default)
    ientropy = 2   # default
    # Activate low-speed preconditioning
    # 1: No preconditioning (default)
    # 2: Local inviscid velocity
    # 3: Constant beta
    iprecon  = 0   # default
    # For iprecon = 2, beta is a measure of local Mach number (but w.r.t to the reference speed of sound)
    # Local speed of sound is scaled according to this Mach number
    beta     = 1.  # default
    # Epsilon threshold for eigen values in entropy fix
    eigeps   = 0.5 # default
}

limiter is only required for transonic or supersonic cases to preserve monotonicity around discontinuities, and defaults to none.

Limiter options

minmod is the long-standing option and is retained unchanged. It compares the reconstructed face increment against the jump to the neighbor cell only, which means it does not limit at the foot of a shock, where the upstream side is flat and the downstream side is not. In practice this shows up as an overshoot at shocks.

rminmod and rvlmc remove both problems. They reconstruct the missing upstream information from the cell's own gradient, so they apply a genuine two-sided test without reading any additional cells and without any extra memory. Both also release themselves automatically on faces carrying no shock. This gate measures the pressure jump across each face against the local \(\rho c^2\): a face whose pressure jump is under 1% of \(\rho c^2\) is left unlimited, and the limiter is fully applied above 3%. Shocks and compressions carry a pressure jump, while shear layers and boundary layers carry none, so smooth flow and boundary layers are reconstructed at full order without needing a shock sensor. Contacts (a temperature or composition jump at uniform pressure, such as a plume boundary) are caught by the density jump instead: the limiter is applied where \(|\rho_R-\rho_L|/(\rho_L+\rho_R)\) exceeds 0.05 and fully above 0.1. Faces next to a cell clipped to the minimum pressure are always limited. The two-sided test sees a face increment only along the line between the two cell centroids; where the increment is carried mostly across that line, as on skewed or curved near-wall cells, the test is discounted accordingly, so it cannot switch such an increment on and off from one implicit iteration to the next. They differ only in how aggressively they limit:

Limiter Shock capture Robustness
minmod Sharp, but overshoots Baseline
rminmod No overshoot, slightly wider shock Most robust of the three
rvlmc No overshoot, sharp shock Least robust on strong 3D shocks

rminmod is the recommended starting point for supersonic and hypersonic cases. Choose rvlmc if shock thickness matters more than robustness for your case, and be prepared to fall back to rminmod if a strong bow shock proves difficult.

Slip lines without a significant density jump (for example the slip line behind a Mach stem) are reconstructed without a limiter and can show some overshoot. If that causes trouble, set limiter gate = false (default true): the limiter is then applied on every face, at the cost of also limiting smooth flow and boundary layers, which can stall steady implicit convergence.

limiter gate applies only to rminmod and rvlmc; setting it to false with any other limiter stops with an input error.

Reconstruction kappa

reconstruction kappa blends the usual gradient extrapolation with an interpolation toward the neighbor cell. The default is 1/3; setting reconstruction kappa = 0 gives the plain MUSCL reconstruction. The default 0.33333333333333333 cancels the leading dispersion error of the second-order scheme, which improves how well the solver preserves waves over long distances. It affects only the reconstructed states used by the upwind flux, so for KEEPBLEND the kinetic-energy-preserving central flux is untouched.

Values between 0 and 1 are accepted. 1 is excluded because it removes the upwind dissipation entirely.

Scale-Resolving Simulations

Scale-resolving simulations require reduced dissipation numerics to preserve smaller turbulent fluctuations that are at a comparable scale to individual grid cells. LAVA unstructured offers two different low dissipation schemes: CENTRALQ and KEEPBLEND. Both of them utilize blending sensors to selectively reduce dissipation in smooth flow regions (free of shocks) where turbulent fluctuations are present.

Upwind Blending Sensors

These sensors dictate where and to what degree the scheme deploys upwind dissipation. There are a variety of sensor options:

convective terms {
    # Sensor(s) that determine the amount of central Q blending or flux blending,
    # and how much of the limiter is applied
    # Options: ducros, ducrosmod, strain, strainmod,
    #          limiter, neumann
    # More than one sensor can be activated through the list below
    upwind blending sensors = [ducrosmod, limiter]
    # For ducrosmod and strainmod sensors, this parameter adjust the localization of the sensor
    # as a multiplier for the enstrophy term
    # Higher values represent more localization (i.e. less dissipation)
    # A value of 1 recovers original formulation, e.g. ducrosmod becomes the standard ducros sensor
    upwind sensor enstrophy factor = 100 # [default]
    # Limits of blending
    # 0: no upwind (full central), 1: full upwind
    upwind blending min          = 0. # default: 0
    upwind blending max          = 1. # default: 1
    # Same limits but only applied at wall adjacent faces
    wall upwind blending min     = 0. # default: 0
    wall upwind blending max     = 0. # default: 1
}

The sensors are combined by taking the maximum, and the result drives the central-versus-upwind blend, which is what sets how much upwind dissipation the scheme deploys. T

strain and strainmod are protection sensors rather than shock sensors: they return 1 (full upwind) in irrotational flow and fall toward 0 only where the flow is genuinely rotational, so a resolved vortex is handed to the central scheme while the rest of the field stays upwind. ducros and ducrosmod are the opposite sense and fire where the dilatation dominates the rotation, rising continuously out of the dead band rather than switching. They are symmetric in the sign of the dilatation, so they fire on strong expansions as well as on compressions; that is deliberate, because in this solver the sensor sets how much upwind dissipation is deployed and a strong expansion needs it too. Pairing a strain sensor with neumann is the intended setting for a supersonic scale-resolving case: outside vortices and shocks the scheme is upwind, inside a resolved vortex it is central.

The blend weight itself can be inspected directly by requesting the upwind volume-output variable.

CENTRALQ Scheme

This scheme blends left and right reconstructed primitive flow variables based on the upwind sensor. The details can be found in Sozer et al.1. Example usage is shown below:

convective terms {
    scheme  = CentralQ
    order   = 2
    limiter = minmod
    # Pick which Q components to centralize (options: p,u,v,w,t)
    central components = [p,u,v,w]
    upwind blending sensors = [ducrosmod]
    flux function = ausmpw+
}

Note that you have the option to individually centralize primitive variables via central components specification. In the example usage, we have excluded t which stands for temperature. This results in a more stable and smooth scheme compared to full centralization.

CENTRALQ approach results in a low dissipation scheme suitable for LES. However, convective scheme dissipation can be further reduced by using the KEEPBLEND scheme which is the current recommended best practice.

KEEPBLEND Scheme

Instead of blending reconstructed primitive variables at flux faces, KEEPBLEND scheme computes two individual fluxes: i) A non-dissipative kinetic energy and entropy preserving (KEEP) flux (our implementation is approximately entropy preserving), and ii) A dissipative upwind flux. The two fluxes are then blended based on the choice of the upwind sensor. More details about this scheme can be found in Sozer et al.2. This scheme will always centralize all flux components, so the central components input is not used. order and limiter only affect the MUSCL reconstruction of the dissipative flux. An example usage is shown below:

convective terms {
    scheme = KEEPBLEND
    # MUSCL reconstruction order [default = 2]
    order   = 2
    limiter = minmod
    upwind blending sensors = [ducrosmod]
    flux function = ausmpw+
}

High Mach Simulations

At high Mach numbers, shocks can develop numerical artifacts, especially if they are not perfectly aligned to the mesh. To remedy this, use the add shock dissipation = true option which employs a shock sensor to detect the shock locations and selectively add extra dissipation.

convective terms {
    # This will employ a shock sensor to add extra dissipation near shocks
    # extra dissipation is computed with Rusanov flux and blended into the
    # flux function selection above
    add shock dissipation = true # [default: false]
}
If performing scale-resolving simulations with ducrosmod or strainmod upwind blending sensors, we recommend setting upwind sensor enstrophy factor = 1 to provide additional robustness at high Mach numbers.

This section sets up the option for integrating the Navier-Stokes equations. For explicit time integration, the options are:

navier stokes {
    # Switch between viscous or inviscid
    viscous = true #default
    # Following flow variables are clipped from below and top
    # according to the limits specified. These are not required
    maximum mach        = 2
    minimum density     = 1e-20
    minimum pressure    = 0.1
    maximum pressure    = 1e20
    minimum temperature = 0.1
    maximum temperature = 1e20
}

The minimum and maximum limits of the flow quantities act in various ways. min/max pressure and tempeature are checked during MUSCL reconstruction. If the robust mode is active, these quantities along with maximum Mach number are also used to test for the health of time integration as described in the robust mode section.

For implicit runs, there are a few other inputs, all or most of which can be omitted in favor of using defaults.

navier stokes {
    ...
    # Maximum number of GMRES linear solver iterations
    maximum iterations  = 40 #default
    # Maximum number of Krylov vectors computed with GMRES algorithm.
    subspace size  = 40 # default same as "maximum iterations"
    # Relative (normalized) convergence tolerance for GMRES
    # The linear solver iterations will stop when this level is met
    relative tolerance  = 1.e-2 #default
    # Absolute (non-normalized) converfence tolerance for GMRES
    # The linear solver iterations will stop when this level is met
    absolute tolerance  =  1.e-20 # default
    # If the linear solver residual exceeds the maximum tolerance, the adaptive CFL
    # grows by at most 5% per step above 70% of the CFL of that step
    maximum tolerance = 0.5 # default
    # If the linear solver residual is above the failure tolerance,
    # the implicit step is considered to have failed and the update is rejected
    # The adaptive CFL is cut to a quarter
    failure tolerance = 0.8 # default
    # Within each implicit iteration, expected density change in each cell
    # is checked before the linear solver. Cells that will likely exceed the
    # value specified below (20% change allowance) will trigger a reduction
    # in their CFL (hence step size).
    density change threshold = 0.2 # default
    # Similar to above but operates on primary flow variables (p,u,v,w,T) and
    # applied after the linear solver.
    q change threshold       = 0.2 # default
    # The Jacobian calculation algorithm may be chosen separately for Navier-Stokes
    # and turbulence. To override the setting specified in the implicit input section,
    # specify the equation below.
    jacobian method = numerical # numerical (default) or analytical
}

Robust Mode

Note

Some features of the robust mode is currently only supported for explicit time integration

In rare cases where solver is unstable, you can turn on the robust mode. In this mode, at every time integration step (or Runge-Kutta integrator stage), the solver will test the solution update against the Mach, density, pressure and temperature limits as specified in the navier stokes section. If any of these criteria are violated, the solver will attempt to recover by applying a smoothing operator to the problematic cells and repeating the step by using dissipative numerics for those cells for the repeated step only.

expert {
    robust mode = true # false by default
    max bomb recovery attempts = 5
    # Permanently add the crashing cell to the problem cell list
    mark bomb cells as problem = false
    # When enabled, write the geometry and flow solution of the offending tiles to
    # volume/bombTiles.cgns on abort
    # This option is TRUE by default
    dump bomb tiles = false
}

If the stability issue persists after max bomb recovery attempts consecutive attempts, the solver will abort the solution and write out the problematic tile solutions to volume/bombTiles.cgns file.

If mark bomb cells as problem = true, the cells experience the stability issue are permanently added to the problem list and are no longer solved for.

Tip

On abort, the solver writes volume/ABORT_Unst.problemCells.<step>.cgns containing the flow solution at the time of abort. If mark bomb cells as problem = true is set in the input file, the cell that caused the crash will also be a part of the problem cell list. Open this file in ParaView and use the Process Unst Mask filter from the LAVAParaviewPlugin (please refer to the plugin documentation here) to extract more details about the cell.

Warning

In implicit simulations, robust mode only considers the maximum mach specification in the navier stokes section. mark bomb cells as problem and max bomb recovery attempts inputs are not used.

Turbulence Options

LAVA unstructured can currently use Spalart Allmaras (SA) turbulence model and it's various variants for RANS and URANS simulations.

turbulence {
    # Available options: [sa,sa-des,sa-ddes,sa,sa-qcr,sa-qcr-rc,sa-rc]
    model = sa
    # If using qcr variations, pick which version (options: 2000, 2013, 2013-v)
    # 2013-v = QCR2013 with vorticity instead of strain in the extra term (NASA TMR QCR2013-V)
    qcr version = 2000
    # Maximum number of GMRES linear solver iterations
    maximum iterations  = 40 # default
    # Maximum number of Krylov vectors computed with GMRES algorithm.
    subspace size  = 40 # default same as "maximum iterations"
    # Relative (normalized) convergence tolerance for GMRES
    # The linear solver iterations will stop when this level is met
    relative tolerance  = 1.e-2 # default
    # Absolute (non-normalized) convergence tolerance for GMRES
    # The linear solver iterations will stop when this level is met
    absolute tolerance  =  1.e-20 # default
    # If the linear solver residual is above the failure tolerance, the turbulence
    # update is rejected and retried at a quarter of the turbulence CFL. At the
    # minimum CFL, the turbulence variable is left unchanged for that step
    failure tolerance = 0.5 # default
    # Limit ratio of eddy viscosity to laminar viscosity
    viscosity ratio limit = 1e6 #default
    # Limit change of turbulence variable to 20% in each implicit iteration
    # this guides the adaptive implicit stepping
    change threshold = 0.2 # default
    # Lower limit for SA working variable
    minimum nut = 1e-12 # default
    # Turbulent Prandtl number
    Pr = 0.9 # default
    # Turbulent Schmidt number
    Sc = 0.9 # default
    # The Jacobian calculation algorithm may be chosen separately for Navier-Stokes
    # and turbulence. To override the setting specified in the implicit input section,
    # specify the equation below.
    jacobian method = numerical # numerical (default) or analytical
}

For LES, subgrid scale model is also specified in this section.

turbulence {
    # SGS model (options: none, vreman, smag)
    sgs model = vreman
    # SGS constant for Vreman, default is 0.07
    # but for unstructured solver, best practice is using 0.08
    sgs const = 0.08
}

Wall Function

Wall function is supported for both WMLES and RANS simulations. However, the implicit RANS solver doesn't currently account for wall function Jacobians, leading to decreased stability and lower CFL requirements.

wall function {
    # Pick wall function, options: musker (default), reichardts, blendedlog, rough
    type = blendedlog 
    # If using rough wall model, specify the roughness in meters
    # 0.25e-6m : highly polished
    # 0.50e-6m : polished
    # 3.33e-6m : painted
    roughness = 0.5e-6
    # If activates, this will make the wall function switch between 
    # modeled wall stress and no-slip boundary condition depending on 
    # a wall turbulence sensor. When the sensor indicates laminar, 
    # no-slip will be used
    do transition = false # default
    # Adjusts the threshold where the sensor decides between laminar and turbulent
    # The smaller the number, the earlier the transition
    transition threshold = 0.05 # default
}

References


  1. Sozer, E., Ghate, A. S., Kenway, G. K., Barad, M. F., Sousa, V. C., and Kiris, C. C., "Evaluation of Voronoi Meshes for Large Eddy Simulations of High Lift Aerodynamics," American Institute of Aeronautics; Astronautics, 2023. https://doi.org/10.2514/6.2023-0255 ↩

  2. Sozer, E., Barad, M. F., Housman, J. A., Cadieux, F., Sousa, V., Dumlupinar, E., Saurabh, K., Ravikumar, K., and Duensing, J. C., "LAVA WMLES Results for the 5th High-Lift Prediction Workshop," American Institute of Aeronautics; Astronautics, 2025. https://doi.org/10.2514/6.2025-0887 ↩