2.7. ARKODE Constants

Below we list all input and output constants used by the main solver, timestepper, and linear solver modules, together with a short description of their meaning. Table 2.12 contains the ARKODE input constants, and Table 2.13 contains the ARKODE output constants.

Table 2.12 ARKODE input constants

Shared input constants

ARK_NORMAL

Solver should return at a specified output time.

ARK_ONE_STEP

Solver should return after each successful step.

Full right-hand side evaluation constants

ARK_FULLRHS_START

Calling the full right-hand side function at the start of the integration.

ARK_FULLRHS_END

Calling the full right-hand side function at the end of a step.

ARK_FULLRHS_OTHER

Calling the full right-hand side function at the some other point e.g., for dense output.

Interpolation module input constants

ARK_INTERP_NONE

Disables polynomial interpolation for dense output.

ARK_INTERP_HERMITE

Specifies use of the Hermite polynomial interpolation module (for non-stiff problems).

ARK_INTERP_LAGRANGE

Specifies use of the Lagrange polynomial interpolation module (for stiff problems).

ARK_INTERP_MAX_DEGREE

Maximum possible interpolating polynomial degree.

Relaxtion module input constants

ARK_RELAX_BRENT

Specifies Brent’s method as the relaxation nonlinear solver.

ARK_RELAX_NEWTON

Specifies Newton’s method as the relaxation nonlinear solver.

Explicit Butcher table specification

ARKODE_FORWARD_EULER_1_1

Use the Forward-Euler-1-1 ERK method.

ARKODE_HEUN_EULER_2_1_2

Use the Heun-Euler-2-1-2 ERK method.

ARKODE_RALSTON_EULER_2_1_2

Use the Ralston-Euler-2-1-2 ERK method.

ARKODE_EXPLICIT_MIDPOINT_EULER_2_1_2

Use the Explicit-Midpoint-Euler-2-1-2 ERK method.

ARKODE_ARK2_ERK_3_1_2

Use the ARK2-ERK-3-1-2 ERK method.

ARKODE_BOGACKI_SHAMPINE_4_2_3

Use the Bogacki-Shampine-4-2-3 ERK method.

ARKODE_ARK324L2SA_ERK_4_2_3

Use the ARK-4-2-3 ERK method.

ARKODE_SOFRONIOU_SPALETTA_5_3_4

Use the Sofroniou-Spaletta-5-3-4 ERK method.

ARKODE_ZONNEVELD_5_3_4

Use the Zonneveld-5-3-4 ERK method.

ARKODE_ARK436L2SA_ERK_6_3_4

Use the ARK-6-3-4 ERK method.

ARKODE_SAYFY_ABURUB_6_3_4

Use the Sayfy-Aburub-6-3-4 ERK method.

ARKODE_CASH_KARP_6_4_5

Use the Cash-Karp-6-4-5 ERK method.

ARKODE_FEHLBERG_6_4_5

Use the Fehlberg-6-4-5 ERK method.

ARKODE_DORMAND_PRINCE_7_4_5

Use the Dormand-Prince-7-4-5 ERK method.

ARKODE_ARK548L2SA_ERK_8_4_5

Use the ARK-8-4-5 ERK method.

ARKODE_VERNER_8_5_6

Use the Verner-8-5-6 ERK method.

ARKODE_FEHLBERG_13_7_8

Use the Fehlberg-13-7-8 ERK method.

ARKODE_KNOTH_WOLKE_3_3

Use the Knoth-Wolke-3-3 ERK method.

ARKODE_ARK437L2SA_ERK_7_3_4

Use the ARK-7-3-4 ERK method.

ARKODE_ARK548L2SAb_ERK_8_4_5

Use the ARK-8-4-5b ERK method.

ARKODE_SHU_OSHER_3_2_3

Use the Shu-Osher-3-2-3 ERK method.

ARKODE_VERNER_9_5_6

Use the Verner-9-5-6 ERK method.

ARKODE_VERNER_10_6_7

Use the Verner-10-6-7 ERK method.

ARKODE_VERNER_13_7_8

Use the Verner-13-7-8 ERK method.

ARKODE_VERNER_16_8_9

Use the Verner-16-8-9 ERK method.

ARKSTEP_DEFAULT_ERK_1

Use ARKStep’s default first-order ERK method (ARKODE_FORWARD_EULER_1_1).

ARKSTEP_DEFAULT_ERK_2

Use ARKStep’s default second-order ERK method (ARKODE_HEUN_EULER_2_1_2).

ARKSTEP_DEFAULT_ERK_3

Use ARKStep’s default third-order ERK method (ARKODE_BOGACKI_SHAMPINE_4_2_3).

ARKSTEP_DEFAULT_ERK_4

Use ARKStep’s default fourth-order ERK method (ARKODE_ZONNEVELD_5_3_4).

ARKSTEP_DEFAULT_ERK_5

Use ARKStep’s default fifth-order ERK method (ARKODE_CASH_KARP_6_4_5).

ARKSTEP_DEFAULT_ERK_6

Use ARKStep’s default sixth-order ERK method (ARKODE_VERNER_8_5_6).

ARKSTEP_DEFAULT_ERK_7

Use ARKStep’s default seventh-order ERK method (ARKODE_VERNER_10_6_7).

ARKSTEP_DEFAULT_ERK_8

Use ARKStep’s default eighth-order ERK method (ARKODE_FEHLBERG_13_7_8).

ARKSTEP_DEFAULT_ERK_9

Use ARKStep’s default ninth-order ERK method (ARKODE_VERNER_16_8_9).

ERKSTEP_DEFAULT_1

Use ERKStep’s default first-order ERK method (ARKODE_FORWARD_EULER_1_1).

ERKSTEP_DEFAULT_2

Use ERKStep’s default second-order ERK method (ARKODE_HEUN_EULER_2_1_2).

ERKSTEP_DEFAULT_3

Use ERKStep’s default third-order ERK method (ARKODE_BOGACKI_SHAMPINE_4_2_3).

ERKSTEP_DEFAULT_4

Use ERKStep’s default fourth-order ERK method (ARKODE_ZONNEVELD_5_3_4).

ERKSTEP_DEFAULT_5

Use ERKStep’s default fifth-order ERK method (ARKODE_CASH_KARP_6_4_5).

ERKSTEP_DEFAULT_6

Use ERKStep’s default sixth-order ERK method (ARKODE_VERNER_8_5_6).

ERKSTEP_DEFAULT_7

Use ERKStep’s default seventh-order ERK method (ARKODE_VERNER_10_6_7).

ERKSTEP_DEFAULT_8

Use ERKStep’s default eighth-order ERK method (ARKODE_FEHLBERG_13_7_8).

ERKSTEP_DEFAULT_9

Use ERKStep’s default ninth-order ERK method (ARKODE_VERNER_16_8_9).

Implicit Butcher table specification

ARKODE_BACKWARD_EULER_1_1

Use the Backward-Euler-1-1 SDIRK method.

ARKODE_SDIRK_2_1_2

Use the SDIRK-2-1-2 SDIRK method.

ARKODE_ARK2_DIRK_3_1_2

Use the ARK2-DIRK-3-1-2 SDIRK method.

ARKODE_IMPLICIT_MIDPOINT_1_2

Use the Implicit-Midpoint-1-2 SDIRK method.

ARKODE_IMPLICIT_TRAPEZOIDAL_2_2

Use the Implicit-Trapezoidal-2-2 ESDIRK method.

ARKODE_BILLINGTON_3_3_2

Use the Billington-3-3-2 SDIRK method.

ARKODE_ESDIRK324L2SA_4_2_3

Use the ESDIRK324L2SA-4-2-3 ESDIRK method.

ARKODE_ESDIRK325L2SA_5_2_3

Use the ESDIRK325L2SA-5-2-3 ESDIRK method.

ARKODE_ESDIRK32I5L2SA_5_2_3

Use the ESDIRK32I5L2SA-5-2-3 ESDIRK method.

ARKODE_TRBDF2_3_3_2

Use the TRBDF2-3-3-2 ESDIRK method.

ARKODE_KVAERNO_4_2_3

Use the Kvaerno-4-2-3 ESDIRK method.

ARKODE_ARK324L2SA_DIRK_4_2_3

Use the ARK-4-2-3 ESDIRK method.

ARKODE_CASH_5_2_4

Use the Cash-5-2-4 SDIRK method.

ARKODE_CASH_5_3_4

Use the Cash-5-3-4 SDIRK method.

ARKODE_SDIRK_5_3_4

Use the SDIRK-5-3-4 SDIRK method.

ARKODE_KVAERNO_5_3_4

Use the Kvaerno-5-3-4 ESDIRK method.

ARKODE_ARK436L2SA_DIRK_6_3_4

Use the ARK-6-3-4 ESDIRK method.

ARKODE_KVAERNO_7_4_5

Use the Kvaerno-7-4-5 ESDIRK method.

ARKODE_ESDIRK436L2SA_6_3_4

Use the ESDIRK436L2SA-6-3-4 method.

ARKODE_ESDIRK43I6L2SA_6_3_4

Use the ESDIRK43I6L2SA-6-3-4 method.

ARKODE_QESDIRK436L2SA_6_3_4

Use the QESDIRK436L2SA-6-3-4 method.

ARKODE_ESDIRK437L2SA_7_3_4

Use the ESDIRK437L2SA-7-3-4 method.

ARKODE_ARK548L2SA_DIRK_8_4_5

Use the ARK-8-4-5 ESDIRK method.

ARKODE_ARK437L2SA_DIRK_7_3_4

Use the ARK-7-3-4 ESDIRK method.

ARKODE_ARK548L2SAb_DIRK_8_4_5

Use the ARK-8-4-5b ESDIRK method.

ARKODE_ESDIRK547L2SA_7_4_5

Use the ESDIRK547L2SA-7-4-5 ESDIRK method.

ARKODE_ESDIRK547L2SA2_7_4_5

Use the ESDIRK547L2SA2-7-4-5 ESDIRK method.

ARKSTEP_DEFAULT_DIRK_1

Use ARKStep’s default first-order DIRK method (ARKODE_BACKWARD_EULER_1_1).

ARKSTEP_DEFAULT_DIRK_2

Use ARKStep’s default second-order DIRK method (ARKODE_SDIRK_2_1_2).

ARKSTEP_DEFAULT_DIRK_3

Use ARKStep’s default third-order DIRK method (ARKODE_ARK324L2SA_DIRK_4_2_3).

ARKSTEP_DEFAULT_DIRK_4

Use ARKStep’s default fourth-order DIRK method (ARKODE_SDIRK_5_3_4).

ARKSTEP_DEFAULT_DIRK_5

Use ARKStep’s default fifth-order DIRK method (ARKODE_ARK548L2SA_DIRK_8_4_5).

ImEx Butcher table specification

ARKODE_ARK2_ERK_3_1_2 & ARKODE_ARK2_DIRK_3_1_2

Use the ARK-3-1-2 ARK method.

ARKODE_ARK324L2SA_ERK_4_2_3 & ARKODE_ARK324L2SA_DIRK_4_2_3

Use the ARK-4-2-3 ARK method.

ARKODE_ARK436L2SA_ERK_6_3_4 & ARKODE_ARK436L2SA_DIRK_6_3_4

Use the ARK-6-3-4 ARK method.

ARKODE_ARK437L2SA_ERK_7_3_4 & ARKODE_ARK437L2SA_DIRK_7_3_4

Use the ARK-7-3-4 ARK method.

ARKODE_ARK548L2SA_ERK_8_4_5 & ARKODE_ARK548L2SA_DIRK_8_4_5

Use the ARK-8-4-5 ARK method.

ARKODE_ARK548L2SAb_ERK_8_4_5 & ARKODE_ARK548L2SAb_DIRK_8_4_5

Use the ARK-8-4-5b ARK method.

ARKSTEP_DEFAULT_ARK_ETABLE_3 & ARKSTEP_DEFAULT_ARK_ITABLE_3

Use ARKStep’s default third-order ARK method (ARKODE_ARK324L2SA_ERK_4_2_3 and ARKODE_ARK324L2SA_DIRK_4_2_3).

ARKSTEP_DEFAULT_ARK_ETABLE_4 & ARKSTEP_DEFAULT_ARK_ITABLE_4

Use ARKStep’s default fourth-order ARK method (ARKODE_ARK436L2SA_ERK_6_3_4 and ARKODE_ARK436L2SA_DIRK_6_3_4).

ARKSTEP_DEFAULT_ARK_ETABLE_5 & ARKSTEP_DEFAULT_ARK_ITABLE_5

Use ARKStep’s default fifth-order ARK method (ARKODE_ARK548L2SA_ERK_8_4_5 and ARKODE_ARK548L2SA_DIRK_8_4_5).

Symplectic Method storage specification

ARKODE_SPRK_EULER_1_1

Symplectic Euler 1st order method with 1 stage.

ARKODE_SPRK_LEAPFROG_2_2

Symplectic Leapfrog 2nd order method with 2 stages.

ARKODE_SPRK_PSEUDO_LEAPFROG_2_2

Symplectic Pseudo Leapfrog 2nd order method with 2 stages.

ARKODE_SPRK_RUTH_3_3

Symplectic Ruth 3rd order method with 3 stages.

ARKODE_SPRK_MCLACHLAN_2_2

Symplectic McLachlan 2nd order method with 2 stages.

ARKODE_SPRK_MCLACHLAN_3_3

Symplectic McLachlan 3rd order method with 3 stages.

ARKODE_SPRK_CANDY_ROZMUS_4_4

Symplectic Candy-Rozmus 4th order method with 4 stages.

ARKODE_SPRK_MCLACHLAN_4_4

Symplectic McLachlan 4th order method with 4 stages.

ARKODE_SPRK_MCLACHLAN_5_6

Symplectic McLachlan 5th order method with 6 stages.

ARKODE_SPRK_YOSHIDA_6_8

Symplectic Yoshida 6th order method with 8 stages.

ARKODE_SPRK_SUZUKI_UMENO_8_16

Symplectic McLachlan 8th order method with 16 stages.

ARKODE_SPRK_SOFRONIOU_10_36

Symplectic Sofroniou 10th order method with 36 stages.

MRI method types

MRISTEP_EXPLICIT

Use an explicit (at the slow time scale) MRI method.

MRISTEP_IMPLICIT

Use an implicit (at the slow time scale) MRI method.

MRISTEP_IMEX

Use an ImEx (at the slow time scale) MRI method.

MRI coupling table specification

ARKODE_MRI_GARK_FORWARD_EULER

Use the forward Euler MRI-GARK method.

ARKODE_MRI_GARK_ERK22b

Use the ERK22b MRI-GARK method.

ARKODE_MRI_GARK_ERK22a

Use the ERK22a MRI-GARK method.

ARKODE_MRI_GARK_RALSTON2

Use the second order Ralston MRI-GARK method.

ARKODE_MIS_MW3

Use the Knoth-Wolke-3 MIS method.

ARKODE_MRI_GARK_ERK33a

Use the ERK33a MRI-GARK method.

ARKODE_MRI_GARK_RALSTON3

Use the third order Ralston MRI-GARK method.

ARKODE_MRI_GARK_ERK45a

Use the ERK45a MRI-GARK method.

ARKODE_MRI_GARK_BACKWARD_EULER

Use the backward Euler MRI-GARK method.

ARKODE_MRI_GARK_IRK21a

Use the IRK21a MRI-GARK method.

ARKODE_MRI_GARK_IMPLICIT_MIDPOINT

Use the implicit midpoint MRI-GARK method.

ARKODE_MRI_GARK_ESDIRK34a

Use the ESDIRK34a MRI-GARK method.

ARKODE_MRI_GARK_ESDIRK46a

Use the ESDIRK46a MRI-GARK method.

ARKODE_IMEX_MRI_GARK_EULER

Use the Euler IMEX-MRI-GARK method.

ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL

Use the trapezoidal rule IMEX-MRI-GARK method.

ARKODE_IMEX_MRI_GARK_MIDPOINT

Use the midpoint rule IMEX-MRI-GARK method.

ARKODE_IMEX_MRI_GARK3a

Use the IMEX-MRI-GARK3a method.

ARKODE_IMEX_MRI_GARK3b

Use the IMEX-MRI-GARK3b method.

ARKODE_IMEX_MRI_GARK4

Use the IMEX-MRI-GARK4 method.

MRISTEP_DEFAULT_EXPL_TABLE_1

Use MRIStep’s default 1st-order explicit method (MRI_GARK_FORWARD_EULER).

MRISTEP_DEFAULT_EXPL_TABLE_2

Use MRIStep’s default 2nd-order explicit method (MRI_GARK_ERK22b).

MRISTEP_DEFAULT_EXPL_TABLE_3

Use MRIStep’s default 3rd-order explicit method (MIS_MW3).

MRISTEP_DEFAULT_EXPL_TABLE_4

Use MRIStep’s default 4th-order explicit method (MRI_GARK_ERK45a).

MRISTEP_DEFAULT_IMPL_SD_TABLE_1

Use MRIStep’s default 1st-order solve-decoupled implicit method (MRI_GARK_BACKWARD_EULER).

MRISTEP_DEFAULT_IMPL_SD_TABLE_2

Use MRIStep’s default 2nd-order solve-decoupled implicit method (MRI_GARK_IRK21a).

MRISTEP_DEFAULT_IMPL_SD_TABLE_3

Use MRIStep’s default 3rd-order solve-decoupled implicit method (MRI_GARK_ESDIRK34a).

MRISTEP_DEFAULT_IMPL_SD_TABLE_4

Use MRIStep’s default 4th-order solve-decoupled implicit method (MRI_GARK_ESDIRK46a).

MRISTEP_DEFAULT_IMEX_SD_TABLE_1

Use MRIStep’s default 1st-order solve-decoupled ImEx method (IMEX_MRI_GARK_EULER).

MRISTEP_DEFAULT_IMEX_SD_TABLE_2

Use MRIStep’s default 2nd-order solve-decoupled ImEx method (ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL).

MRISTEP_DEFAULT_IMEX_SD_TABLE_3

Use MRIStep’s default 3rd-order solve-decoupled ImEx method (IMEX_MRI_GARK3b).

MRISTEP_DEFAULT_IMEX_SD_TABLE_4

Use MRIStep’s default 4th-order solve-decoupled ImEx method (IMEX_MRI_GARK4).

Table 2.13 ARKODE output constants

Shared output constants

ARK_SUCCESS

0

Successful function return.

ARK_TSTOP_RETURN

1

ARKODE succeeded by reaching the specified stopping point.

ARK_ROOT_RETURN

2

ARKODE succeeded and found one more more roots.

ARK_WARNING

99

ARKODE succeeded but an unusual situation occurred.

ARK_TOO_MUCH_WORK

-1

The solver took mxstep internal steps but could not reach tout.

ARK_TOO_MUCH_ACC

-2

The solver could not satisfy the accuracy demanded by the user for some internal step.

ARK_ERR_FAILURE

-3

Error test failures occurred too many times during one internal time step, or the minimum step size was reached.

ARK_CONV_FAILURE

-4

Convergence test failures occurred too many times during one internal time step, or the minimum step size was reached.

ARK_LINIT_FAIL

-5

The linear solver’s initialization function failed.

ARK_LSETUP_FAIL

-6

The linear solver’s setup function failed in an unrecoverable manner.

ARK_LSOLVE_FAIL

-7

The linear solver’s solve function failed in an unrecoverable manner.

ARK_RHSFUNC_FAIL

-8

The right-hand side function failed in an unrecoverable manner.

ARK_FIRST_RHSFUNC_ERR

-9

The right-hand side function failed at the first call.

ARK_REPTD_RHSFUNC_ERR

-10

The right-hand side function had repeated recoverable errors.

ARK_UNREC_RHSFUNC_ERR

-11

The right-hand side function had a recoverable error, but no recovery is possible.

ARK_RTFUNC_FAIL

-12

The rootfinding function failed in an unrecoverable manner.

ARK_LFREE_FAIL

-13

The linear solver’s memory deallocation function failed.

ARK_MASSINIT_FAIL

-14

The mass matrix linear solver’s initialization function failed.

ARK_MASSSETUP_FAIL

-15

The mass matrix linear solver’s setup function failed in an unrecoverable manner.

ARK_MASSSOLVE_FAIL

-16

The mass matrix linear solver’s solve function failed in an unrecoverable manner.

ARK_MASSFREE_FAIL

-17

The mass matrix linear solver’s memory deallocation function failed.

ARK_MASSMULT_FAIL

-18

The mass matrix-vector product function failed.

ARK_CONSTR_FAIL

-19

The inequality constraint test failed repeatedly or failed with the minimum step size.

ARK_MEM_FAIL

-20

A memory allocation failed.

ARK_MEM_NULL

-21

The arkode_mem argument was NULL.

ARK_ILL_INPUT

-22

One of the function inputs is illegal.

ARK_NO_MALLOC

-23

The ARKODE memory block was not allocated by a call to ARKStepCreate(), ERKStepCreate(), or MRIStepCreate().

ARK_BAD_K

-24

The derivative order \(k\) is larger than allowed.

ARK_BAD_T

-25

The time \(t\) is outside the last step taken.

ARK_BAD_DKY

-26

The output derivative vector is NULL.

ARK_TOO_CLOSE

-27

The output and initial times are too close to each other.

ARK_VECTOROP_ERR

-28

An error occurred when calling an N_Vector routine.

ARK_NLS_INIT_FAIL

-29

An error occurred when initializing a SUNNonlinSol module.

ARK_NLS_SETUP_FAIL

-30

A non-recoverable error occurred when setting up a SUNNonlinSol module.

ARK_NLS_SETUP_RECVR

-31

A recoverable error occurred when setting up a SUNNonlinSol module.

ARK_NLS_OP_ERR

-32

An error occurred when calling a set/get routine in a SUNNonlinSol module.

ARK_INNERSTEP_ATTACH_ERR

-33

An error occurred when attaching the inner stepper module.

ARK_INNERSTEP_FAIL

-34

An error occurred in the inner stepper module.

ARK_PREINNERFN_FAIL

-35

An error occurred in the MRIStep pre inner integrator function.

ARK_POSTINNERFN_FAIL

-36

An error occurred in the MRIStep post inner integrator function.

ARK_INTERP_FAIL

-40

An error occurred in the ARKODE polynomial interpolation module.

ARK_INVALID_TABLE

-41

An invalid Butcher or MRI table was encountered.

ARK_CONTEXT_ERR

-42

An error occurred with the SUNDIALS context object

ARK_RELAX_FAIL

-43

An error occurred in computing the relaxation parameter

ARK_RELAX_MEM_FAIL

-44

The relaxation memory structure is NULL

ARK_RELAX_FUNC_FAIL

-45

The relaxation function returned an unrecoverable error

ARK_RELAX_JAC_FAIL

-46

The relaxation Jacobian function returned an unrecoverable error

ARK_CONTROLLER_ERR

-47

An error with a SUNAdaptController object was encountered.

ARK_STEPPER_UNSUPPORTED

-48

An operation was not supported by the current time-stepping module.

ARK_UNRECOGNIZED_ERROR

-99

An unknown error was encountered.

ARKLS linear solver module output constants

ARKLS_SUCCESS

0

Successful function return.

ARKLS_MEM_NULL

-1

The arkode_mem argument was NULL.

ARKLS_LMEM_NULL

-2

The ARKLS linear solver interface has not been initialized.

ARKLS_ILL_INPUT

-3

The ARKLS solver interface is not compatible with the current N_Vector module, or an input value was illegal.

ARKLS_MEM_FAIL

-4

A memory allocation request failed.

ARKLS_PMEM_NULL

-5

The preconditioner module has not been initialized.

ARKLS_MASSMEM_NULL

-6

The ARKLS mass-matrix linear solver interface has not been initialized.

ARKLS_JACFUNC_UNRECVR

-7

The Jacobian function failed in an unrecoverable manner.

ARKLS_JACFUNC_RECVR

-8

The Jacobian function had a recoverable error.

ARKLS_MASSFUNC_UNRECVR

-9

The mass matrix function failed in an unrecoverable manner.

ARKLS_MASSFUNC_RECVR

-10

The mass matrix function had a recoverable error.

ARKLS_SUNMAT_FAIL

-11

An error occurred with the current SUNMatrix module.

ARKLS_SUNLS_FAIL

-12

An error occurred with the current SUNLinearSolver module.

enum ARKRelaxSolver

Nonlinear solver identifiers used to specify the method for solving (2.48) when relaxation is enabled.

enumerator ARK_RELAX_NEWTON

Newton’s method

enumerator ARK_RELAX_BRENT

Brent’s method