Residual Evaluation

This function computes the vector form of of the residual from the vector form of the solution, ie. q_vec -> rhs_vec, for a given physics. This is one of the two functions required by newtonInner.

Users of newtonInner that are not physics modules (for example, implicit time marching schemes) will need to implement their own version of this function. See the Implimentation Notes section below.

Inputs

• mesh: an AbstractMesh

• sbp: an AbstractSBP

• eqn: an AbstractSolutionData (may be modified during this function)

• opts: the options dictionary

• ctx_residual: a tuple of values. ctx_residual[1] must be a function that computes (q -> res). Typically this is evalResidual. The other entries of the tuple (if any) are not used.

            The purpose of this argument is to make the signature of
            the function generic enough so that implict time marching
            methods can use it.  (If you are confused about this
            programming pattern, google how callback are implemented
            in C, this ctx is like a void* in C).

• t: the time at which to evalute the residual

Inputs/Outputs

• rhs_vec: vector to put the residual in

Output

• norm of the residual vector

Implementation Notes:

This function is really a wrapper around an evalResidual-like function. It has to do 5 things:

1. scatter eqn.q_vec -> eqn.q
2. start parallel communication if needed
3. call the evalResidual-like function to compute eqn.q -> eqn.res
4. assemble the residual into the output vector, ie. eqn.res -> rhs_vec
5. compute the norm of the rhs_vec

Any implementation of this function (used with newtonInner) must have the following properties:

1. on exit, eqn.q and eqn.q_vec must be consistent
2. this function start parallel communication if needed
3. allow for the possibility that rhs_vec and eqn.res_vec alias

Is is recommended to use calcNorm to compute the norm.

Other implementations of this function are encouraged to use this function to help construct their rhs_vec.

NonlinearSolvers.assembleResidual

This function takes the residual in eqn.res and performs an additive reduction into res_vec. This function wraps array3DTo1D.

Inputs: mesh: AbstractMesh sbp: SBP operator eqn: AbstractEquation object opts: options dictionary res_vec: residual vector to put the residual into

Outputs: none

Aliasing restrictions: none

NonlinearSolvers.array1DTo3D

This function performs the scatter q_vec -> eqn.q

Inputs: mesh: AbstractMesh sbp: SBP operator eqn: AbstractEquation object opts: options dictionary q_vec: vector containing solution variables

Outputs: none

Aliasing Restrictions: none