3.4.2.3. Relaxation Methods
This section describes usercallable functions for applying relaxation methods with ARKStep. For more information on relaxation Runge–Kutta methods see §3.2.14.
Note
Relaxation support as not been evaluated with nonidentity mass matrices. While this usage mode is supported, feedback from users who explore this combination would be appreciated.
3.4.2.3.1. Enabling or Disabling Relaxation

int ARKStepSetRelaxFn(void *arkode_mem, ARKRelaxFn rfn, ARKRelaxJacFn rjac)
Attaches the user supplied functions for evaluating the relaxation function (
rfn
) and its Jacobian (rjac
).Both
rfn
andrjac
are required and an error will be returned if only one of the functions isNULL
. If bothrfn
andrjac
areNULL
, relaxation is disabled.With DIRK and IMEXARK methods or when a fixed mass matrix is present, applying relaxation requires allocating \(s\) additional state vectors (where \(s\) is the number of stages in the method).
 Parameters:
arkode_mem – the ARKStep memory structure
rfn – the userdefined function to compute the relaxation function \(\xi(y)\)
rjac – the userdefined function to compute the relaxation Jacobian \(\xi'(y)\)
 Return values:
ARK_SUCCESS – the function exited successfully
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_ILL_INPUT – an invalid input combination was provided (see the output error message for more details)
ARK_MEM_FAIL – a memory allocation failed
Warning
Applying relaxation requires using a method of at least second order with \(b^E_i \geq 0\) and \(b^I_i \geq 0\). If these conditions are not satisfied,
ARKStepEvolve()
will return with an error during initialization.Note
When combined with fixed time step sizes, ARKStep will attempt each step using the specified step size. If the step is successful, relaxation will be applied, effectively modifying the step size for the current step. If the step fails or applying relaxation fails,
ARKStepEvolve()
will return with an error.Added in version 5.6.0.
3.4.2.3.2. Optional Input Functions
This section describes optional input functions used to control applying relaxation.

int ARKStepSetRelaxEtaFail(void *arkode_mem, sunrealtype eta_rf)
Sets the step size reduction factor applied after a failed relaxation application.
The default value is 0.25. Input values \(\leq 0\) or \(\geq 1\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
eta_rf – the step size reduction factor
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepSetRelaxLowerBound(void *arkode_mem, sunrealtype lower)
Sets the smallest acceptable value for the relaxation parameter.
Values smaller than the lower bound will result in a failed relaxation application and the step will be repeated with a smaller step size (determined by
ARKStepSetRelaxEtaFail()
).The default value is 0.8. Input values \(\leq 0\) or \(\geq 1\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
lower – the relaxation parameter lower bound
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepSetRelaxUpperBound(void *arkode_mem, sunrealtype upper)
Sets the largest acceptable value for the relaxation parameter.
Values larger than the upper bound will result in a failed relaxation application and the step will be repeated with a smaller step size (determined by
ARKStepSetRelaxEtaFail()
).The default value is 1.2. Input values \(\leq 1\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
upper – the relaxation parameter upper bound
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepSetRelaxMaxFails(void *arkode_mem, int max_fails)
Sets the maximum number of times applying relaxation can fail within a step attempt before the integration is halted with an error.
The default value is 10. Input values \(\leq 0\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
max_fails – the maximum number of failed relaxation applications allowed in a step
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepSetRelaxMaxIters(void *arkode_mem, int max_iters)
Sets the maximum number of nonlinear iterations allowed when solving for the relaxation parameter.
If the maximum number of iterations is reached before meeting the solve tolerance (determined by
ARKStepSetRelaxResTol()
andARKStepSetRelaxTol()
), the step will be repeated with a smaller step size (determined byARKStepSetRelaxEtaFail()
).The default value is 10. Input values \(\leq 0\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
max_iters – the maximum number of solver iterations allowed
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepSetRelaxSolver(void *arkode_mem, ARKRelaxSolver solver)
Sets the nonlinear solver method used to compute the relaxation parameter.
The default value is
ARK_RELAX_NEWTON
. Parameters:
arkode_mem – the ARKStep memory structure
solver – the nonlinear solver to use:
ARK_RELAX_BRENT
orARK_RELAX_NEWTON
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
ARK_ILL_INPUT – an invalid solver option was provided
Added in version 5.6.0.

int ARKStepSetRelaxResTol(void *arkode_mem, sunrealtype res_tol)
Sets the nonlinear solver residual tolerance to use when solving (3.48).
If the residual or iteration update tolerance (see
ARKStepSetRelaxMaxIter()
) is not reached within the maximum number of iterations (determined byARKStepSetRelaxMaxIters()
), the step will be repeated with a smaller step size (determined byARKStepSetRelaxEtaFail()
).The default value is \(4 \epsilon\) where \(\epsilon\) is floatingpoint precision. Input values \(\leq 0\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
res_tol – the nonlinear solver residual tolerance to use
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepSetRelaxTol(void *arkode_mem, sunrealtype rel_tol, sunrealtype abs_tol)
Sets the nonlinear solver relative and absolute tolerance on changes in \(r\) iterates when solving (3.48).
If the residual (see
ARKStepSetRelaxResTol()
) or iterate update tolerance is not reached within the maximum number of iterations (determined byARKStepSetRelaxMaxIters()
), the step will be repeated with a smaller step size (determined byARKStepSetRelaxEtaFail()
).The default relative and absolute tolerances are \(4 \epsilon\) and \(10^{14}\), respectively, where \(\epsilon\) is floatingpoint precision. Input values \(\leq 0\) will result in the default value being used.
 Parameters:
arkode_mem – the ARKStep memory structure
rel_tol – the nonlinear solver relative solution tolerance to use
abs_tol – the nonlinear solver absolute solution tolerance to use
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.
3.4.2.3.3. Optional Output Functions
This section describes optional output functions used to retrieve information about the performance of the relaxation method.

int ARKStepGetNumRelaxFnEvals(void *arkode_mem, long int *r_evals)
Get the number of times the user’s relaxation function was evaluated.
 Parameters:
arkode_mem – the ARKStep memory structure
r_evals – the number of relaxation function evaluations
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepGetNumRelaxJacEvals(void *arkode_mem, long int *J_evals)
Get the number of times the user’s relaxation Jacobian was evaluated.
 Parameters:
arkode_mem – the ARKStep memory structure
J_evals – the number of relaxation Jacobian evaluations
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepGetNumRelaxFails(void *arkode_mem, long int *fails)
Get the total number of times applying relaxation failed.
The counter includes the sum of the number of nonlinear solver failures (see
ARKStepGetNumRelaxSolveFails()
) and the number of failures due an unacceptable relaxation value (seeARKStepSetRelaxBoundFactor()
). Parameters:
arkode_mem – the ARKStep memory structure
fails – the total number of failed relaxation attempts
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepGetNumRelaxBoundFails(void *arkode_mem, long int *fails)
Get the number of times the relaxation parameter was deemed unacceptable.
 Parameters:
arkode_mem – the ARKStep memory structure
fails – the number of failures due to an unacceptable relaxation parameter value
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepGetNumRelaxSolveFails(void *arkode_mem, long int *fails)
Get the number of times the relaxation parameter nonlinear solver failed.
 Parameters:
arkode_mem – the ARKStep memory structure
fails – the number of relaxation nonlinear solver failures
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.

int ARKStepGetNumRelaxSolveIters(void *arkode_mem, long int *iters)
Get the number of relaxation parameter nonlinear solver iterations.
 Parameters:
arkode_mem – the ARKStep memory structure
iters – the number of relaxation nonlinear solver iterations
 Return values:
ARK_SUCCESS – the value was successfully set
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_RELAX_MEM_NULL – the internal relaxation memory structure was
NULL
Added in version 5.6.0.