Jacobian Freezing

Jacobian and Preconditioner Freezing

It is often faster to reuse the Jacobian and/or preconditioner than calculate a new one each major iteration. The functions described here provide a consistant API for doing so.

Each method in NonlinearSolvers should specify if it supports Jacobian and PC freezing. If it does, it should specify the prefix (see Construction).

Note that some methods use newtonInner internally. It is sometimes beneficial to have newtonInner recompute the Jacobian and PC. In other cases, using the same Jacobian and PC for several calls to newtonInner is beneficial. Both these use cases are supported. Both newtonInner and the outer method can have their own RecalculationPolicy objects. When the newtonInner RecalculationPolicy is RecalculateNever, it will never recalculate the Jacobian and PC and the outer method will be the soley responsible for updaing the Jacobian and PC. In the reverse case, the outer method can use RecalculateNever and let newtonInner recalculate the Jacobian and PC.

API

NonlinearSolvers.doRecalculation — Function.

This function uses decideRecalculation and the LinearSolver interface to recalculate the PC and/or LO as specified by the policy.

This is the main interface the different methods should use for recalculating the PC and/or LO. The only case when decideRecalculation is better is when the method is not using the LinearSolvers module to define the PC and LO.

Inputs

The following arguments exactly match the signature of calcPCandLO

  • ls

  • mesh

  • sbp

  • eqn

  • opts

  • ctx_residual

  • t

When this function exits, the PC and/or LO will have been updated, if specified by the RecalculationPolicy.

source
NonlinearSolvers.decideRecalculation — Function.

This function returns the enum specifying whether the PC and/or LO should be recalculated.

Every implementation of RecalculationPolicy should extend this function with a new method.

Inputs

Outputs

source
NonlinearSolvers.resetRecalculationPolicy — Function.

This function should reset the RecalculationPolicy to its initial state. This function is called at the beginning of Newton's method (making it safe to reuse the RecalculationPolicy for repeated calls to Newton)

Every RecalculationPolicy should extend function with a new method.

Inputs

Outputs

  • none

source
NonlinearSolvers.RECALC_BOTH — Constant.

Enums returned by decideRecalculation telling the caller what to recalculate.

Enum Names

  • RECALC_BOTH: recalculate PC and LO

  • RECALC_PC: recalculate PC only

  • RECALC_LO: recalculate LO only

  • RECALC_NONE: don't recalculate anything

source

Construction

NonlinearSolvers.getRecalculationPolicy — Function.

This function constructs and returns the recalculation policy specified by the options dictionary.

Methods that want to use a RecalculationPolicy should this this function to get it (do not call the constructors directly).

Inputs

  • opts: options dictionary

  • prefix: prefix of options to use. This is usually the name of the method the returned object will be used in, eg. "newton"

Outputs

  • policy: a RecalculationPolicy of some kind

Options Keys

  • "prefix_recalculation_policy": name of recalculation policy to get

Current Policies

String["RecalculateFixedIntervals", "RecalculateNever"]

source
NonlinearSolvers.RecalculationPolicyDict — Constant.

Maps names to RecalculationPolicy constructors. All new recalculation policies must be added to this list.

The constructors must have the signature:

MyPolicyName(opts::Dict, prefix::String)

where opts is the options dictionary and prefix is the prefix passed into getRecalculationPolicy.

source

Recalculation Policies

NonlinearSolvers.RecalculateFixedIntervals — Type.

This RecalculationPolicy recalculates the LO and PC every x number if iterations.

Options Keys

  • "prefix_prec_recalc_freq": frequency of PC recalculation

  • "prefix_jac_recalc_freq": frequency of LO recalculation

  • "prefix_recalc_first": if true, recalculate the PC and LO on the first iteration, even if other criteria not met.

where "prefix" is the prefix passed into getRecalculationPolicy

source
NonlinearSolvers.RecalculateNever — Type.

This RecalculationPolicy never recalculates the PC or LO. This is useful when Newton's method is used inside other methods to solve easy problems.

source
NonlinearSolvers.RecalculationPolicy — Type.

This is the supertype of all types that tell a method when to recalculate the Jacobian. Each subtype defines a different policy for when to recalculate.

source