2.4.8.2. Relaxation Methods

This section describes ERKStep-specific user-callable functions for applying relaxation methods with ERKStep. All of these routines have been deprecated in favor of shared ARKODE-level routines, but this documentation will be retained for as long as these functions are present

2.4.8.2.1. Enabling or Disabling Relaxation

int ERKStepSetRelaxFn(void *arkode_mem, ARKRelaxFn rfn, ARKRelaxJacFn rjac)

Attaches the user supplied functions for evaluating the relaxation function (rfn) and its Jacobian (rjac).

Both rfn and rjac are required and an error will be returned if only one of the functions is NULL. If both rfn and rjac are NULL, relaxation is disabled.

Parameters:

  • arkode_mem – the ERKStep memory structure

  • rfn – the user-defined function to compute the relaxation function \(\xi(y)\)

  • rjac – the user-defined function to compute the relaxation Jacobian \(\xi'(y)\)

Return values:

  • ARK_SUCCESS – the function exited successfully

  • ARK_MEM_NULL – arkode_mem was NULL

  • 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_i \geq 0\). If these conditions are not satisfied, ERKStepEvolve() will return with an error during initialization.

Note

When combined with fixed time step sizes, ERKStep 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, ERKStepEvolve() will return with an error.

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxFn() instead.

2.4.8.2.2. Optional Input Functions

This section describes optional input functions used to control applying relaxation.

int ERKStepSetRelaxEtaFail(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 ERKStep memory structure

  • eta_rf – the step size reduction factor

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxEtaFail() instead.

int ERKStepSetRelaxLowerBound(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 ERKStepSetRelaxEtaFail()).

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 ERKStep memory structure

  • lower – the relaxation parameter lower bound

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxLowerBound() instead.

int ERKStepSetRelaxUpperBound(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 ERKStepSetRelaxEtaFail()).

The default value is 1.2. Input values \(\leq 1\) will result in the default value being used.

Parameters:

  • arkode_mem – the ERKStep memory structure

  • upper – the relaxation parameter upper bound

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxUpperBound() instead.

int ERKStepSetRelaxMaxFails(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 ERKStep 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 was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxMaxFails() instead.

int ERKStepSetRelaxMaxIters(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 ERKStepSetRelaxResTol() and ERKStepSetRelaxTol()), the step will be repeated with a smaller step size (determined by ERKStepSetRelaxEtaFail()).

The default value is 10. Input values \(\leq 0\) will result in the default value being used.

Parameters:

  • arkode_mem – the ERKStep 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 was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxMaxIters() instead.

int ERKStepSetRelaxSolver(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 ERKStep memory structure

  • solver – the nonlinear solver to use

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • 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.

Deprecated since version 6.1.0: Use ARKodeSetRelaxSolver() instead.

int ERKStepSetRelaxResTol(void *arkode_mem, sunrealtype res_tol)

Sets the nonlinear solver residual tolerance to use when solving (2.48).

If the residual or solution tolerance (see ERKStepSetRelaxMaxIters()) is not reached within the maximum number of iterations (determined by ERKStepSetRelaxMaxIters()), the step will be repeated with a smaller step size (determined by ERKStepSetRelaxEtaFail()).

The default value is \(4 \epsilon\) where \(\epsilon\) is floating-point precision. Input values \(\leq 0\) will result in the default value being used.

Parameters:

  • arkode_mem – the ERKStep 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 was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxResTol() instead.

int ERKStepSetRelaxTol(void *arkode_mem, sunrealtype rel_tol, sunrealtype abs_tol)

Sets the nonlinear solver relative and absolute tolerance on changes in \(r\) when solving (2.48).

If the residual (see ERKStepSetRelaxResTol()) or solution tolerance is not reached within the maximum number of iterations (determined by ERKStepSetRelaxMaxIters()), the step will be repeated with a smaller step size (determined by ERKStepSetRelaxEtaFail()).

The default relative and absolute tolerances are \(4 \epsilon\) and \(10^{-14}\), respectively, where \(\epsilon\) is floating-point precision. Input values \(\leq 0\) will result in the default value being used.

Parameters:

  • arkode_mem – the ERKStep 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 was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetRelaxTol() instead.

2.4.8.2.3. Optional Output Functions

This section describes optional output functions used to retrieve information about the performance of the relaxation method.

int ERKStepGetNumRelaxFnEvals(void *arkode_mem, long int *r_evals)

Get the number of times the user’s relaxation function was evaluated.

Parameters:

  • arkode_mem – the ERKStep memory structure

  • r_evals – the number of relaxation function evaluations

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeGetNumRelaxFnEvals() instead.

int ERKStepGetNumRelaxJacEvals(void *arkode_mem, long int *J_evals)

Get the number of times the user’s relaxation Jacobian was evaluated.

Parameters:

  • arkode_mem – the ERKStep memory structure

  • J_evals – the number of relaxation Jacobian evaluations

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeGetNumRelaxJacEvals() instead.

int ERKStepGetNumRelaxFails(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 ERKStepGetNumRelaxSolveFails()) and the number of failures due an unacceptable relaxation value (see ERKStepSetRelaxLowerBound() and ERKStepSetRelaxUpperBound()).

Parameters:

  • arkode_mem – the ERKStep memory structure

  • fails – the total number of failed relaxation attempts

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeGetNumRelaxFails() instead.

int ERKStepGetNumRelaxBoundFails(void *arkode_mem, long int *fails)

Get the number of times the relaxation parameter was deemed unacceptable.

Parameters:

  • arkode_mem – the ERKStep 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 was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeGetNumRelaxBoundFails() instead.

int ERKStepGetNumRelaxSolveFails(void *arkode_mem, long int *fails)

Get the number of times the relaxation parameter nonlinear solver failed.

Parameters:

  • arkode_mem – the ERKStep memory structure

  • fails – the number of relaxation nonlinear solver failures

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeGetNumRelaxSolveFails() instead.

int ERKStepGetNumRelaxSolveIters(void *arkode_mem, long int *iters)

Get the number of relaxation parameter nonlinear solver iterations.

Parameters:

  • arkode_mem – the ERKStep memory structure

  • iters – the number of relaxation nonlinear solver iterations

Return values:

  • ARK_SUCCESS – the value was successfully set

  • ARK_MEM_NULL – arkode_mem was NULL

  • ARK_RELAX_MEM_NULL – the internal relaxation memory structure was NULL

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeGetNumRelaxSolveIters() instead.