9.3. SUNMATRIX functions used by ARKODE

In Table Table 9.2, we list the matrix functions in the SUNMatrix module used within the ARKODE package. The table also shows, for each function, which of the code modules uses the function. The main ARKODE time step modules, ARKStep, ERKStep, and MRIStep, do not call any SUNMatrix functions directly, so the table columns are specific to the ARKLS interface and the ARKBANDPRE and ARKBBDPRE preconditioner modules. We further note that the ARKLS interface only utilizes these routines when supplied with a matrix-based linear solver, i.e. the SUNMatrix object (J or M) passed to ARKStepSetLinearSolver() or ARKStepSetMassLinearSolver() was not NULL.

At this point, we should emphasize that the ARKODE user does not need to know anything about the usage of matrix functions by the ARKODE code modules in order to use ARKODE. The information is presented as an implementation detail for the interested reader.

Table 9.2 List of matrix functions usage by ARKODE code modules
	ARKLS	ARKBANDPRE	ARKBBDPRE
`SUNMatGetID()`	X
`SUNMatClone()`	X
`SUNMatDestroy()`	X	X	X
`SUNMatZero()`	X	X	X
`SUNMatCopy()`	X	X	X
`SUNMatScaleAddI()`	X	X	X
`SUNMatScaleAdd()`	1
`SUNMatMatvec()`	1
`SUNMatMatvecSetup()`	1,2
`SUNMatSpace()`	2	2	2

These matrix functions are only used for problems involving a non-identity mass matrix.
These matrix functions are optionally used, in that these are only called if they are implemented in the SUNMatrix module that is being used (i.e. their function pointers are non-NULL). If not supplied, these modules will assume that the matrix requires no storage.

We note that both the ARKBANDPRE and ARKBBDPRE preconditioner modules are hard-coded to use the SUNDIALS-supplied band SUNMatrix type, so the most useful information above for user-supplied SUNMatrix implementations is the column relating to ARKLS requirements.

9.4. SUNMatrix functions used by CVODE

In Table 9.3, we list the matrix functions in the SUNMatrix module used within the CVODE package. The table also shows, for each function, which of the code modules uses the function. The main CVODE integrator does not call any SUNMatrix functions directly, so the table columns are specific to the CVLS interface and the CVBANDPRE and CVBBDPRE preconditioner modules. We further note that the CVLS interface only utilizes these routines when supplied with a matrix-based linear solver, i.e., the SUNMatrix object passed to CVodeSetLinearSolver() was not NULL.

At this point, we should emphasize that the CVODE user does not need to know anything about the usage of matrix functions by the CVODE code modules in order to use CVODE. The information is presented as an implementation detail for the interested reader.

Table 9.3 List of matrix functions usage by CVODE code modules
	CVLS	CVBANDPRE	CVBBDPRE
`SUNMatClone()`	x
`SUNMatDestroy()`	x	x	x
`SUNMatZero()`	x	x	x
`SUNMatGetID()`	x
`SUNMatCopy()`	x	x	x
`SUNMatScaleAddI()`	x	x	x
`SUNMatSpace()`	\(\dagger\)	\(\dagger\)	\(\dagger\)

The matrix functions listed with a \(\dagger\) symbol are optionally used, in that these are only called if they are implemented in the SUNMatrix module that is being used (i.e. their function pointers are non-NULL). The matrix functions listed in §9.1 that are not used by CVODE are: SUNMatScaleAdd() and SUNMatMatvec(). Therefore a user-supplied SUNMatrix module for CVODE could omit these functions.

We note that the CVBANDPRE and CVBBDPRE preconditioner modules are hard-coded to use the SUNDIALS-supplied band SUNMatrix type, so the most useful information above for user-supplied SUNMatrix implementations is the column relating the CVLS requirements.

9.5. SUNMatrix functions used by CVODES

In Table 9.4, we list the matrix functions in the SUNMatrix module used within the CVODES package. The table also shows, for each function, which of the code modules uses the function. The main CVODES integrator does not call any SUNMatrix functions directly, so the table columns are specific to the CVLS interface and the CVBANDPRE and CVBBDPRE preconditioner modules. We further note that the CVLS interface only utilizes these routines when supplied with a matrix-based linear solver, i.e., the SUNMatrix object passed to CVodeSetLinearSolver() was not NULL.

At this point, we should emphasize that the CVODES user does not need to know anything about the usage of matrix functions by the CVODES code modules in order to use CVODES. The information is presented as an implementation detail for the interested reader.

Table 9.4 List of matrix functions usage by CVODES code modules
	CVLS	CVBANDPRE	CVBBDPRE
`SUNMatClone()`	x
`SUNMatDestroy()`	x	x	x
`SUNMatZero()`	x	x	x
`SUNMatGetID()`	x
`SUNMatCopy()`	x	x	x
`SUNMatScaleAddI()`	x	x	x
`SUNMatSpace()`	\(\dagger\)	\(\dagger\)	\(\dagger\)

The matrix functions listed with a \(\dagger\) symbol are optionally used, in that these are only called if they are implemented in the SUNMatrix module that is being used (i.e. their function pointers are non-NULL). The matrix functions listed in §9.1 that are not used by CVODES are: SUNMatScaleAdd() and SUNMatMatvec(). Therefore a user-supplied SUNMatrix module for CVODES could omit these functions.

We note that the CVBANDPRE and CVBBDPRE preconditioner modules are hard-coded to use the SUNDIALS-supplied band SUNMatrix type, so the most useful information above for user-supplied SUNMatrix implementations is the column relating the CVLS requirements.

9.6. SUNMatrix functions used by IDA

In Table 9.5, we list the matrix functions in the SUNMatrix module used within the IDA package. The table also shows, for each function, which of the code modules uses the function. The main IDA integrator does not call any SUNMatrix functions directly, so the table columns are specific to the IDALS and IDABBDPRE preconditioner modules. We further note that the IDALS interface only utilizes these routines when supplied with a matrix-based linear solver, i.e., the SUNMatrix object passed to IDASetLinearSolver() was not NULL.

At this point, we should emphasize that the IDA user does not need to know anything about the usage of matrix functions by the IDA code modules in order to use IDA. The information is presented as an implementation detail for the interested reader.

Table 9.5 List of matrix functions usage by IDA code modules
	IDALS	IDABBDPRE
`SUNMatGetID()`	x
`SUNMatDestroy()`		x
`SUNMatZero()`	x	x
`SUNMatSpace()`		\(\dagger\)

The matrix functions listed with a \(\dagger\) symbol are optionally used, in that these are only called if they are implemented in the SUNMatrix module that is being used (i.e. their function pointers are non-NULL). The matrix functions listed in §9.1 that are not used by IDA are: SUNMatCopy(), SUNMatClone(), SUNMatScaleAdd(), SUNMatScaleAddI() and SUNMatMatvec(). Therefore a user-supplied SUNMatrix module for IDA could omit these functions.

We note that the IDABBDPRE preconditioner module is hard-coded to use the SUNDIALS-supplied band SUNMatrix type, so the most useful information above for user-supplied SUNMatrix implementations is the column relating the IDALS requirements.

9.7. SUNMatrix functions used by IDAS

In Table 9.6, we list the matrix functions in the SUNMatrix module used within the IDAS package. The table also shows, for each function, which of the code modules uses the function. The main IDAS integrator does not call any SUNMatrix functions directly, so the table columns are specific to the IDALS and IDABBDPRE preconditioner modules. We further note that the IDALS interface only utilizes these routines when supplied with a matrix-based linear solver, i.e., the SUNMatrix object passed to IDASetLinearSolver() was not NULL.

At this point, we should emphasize that the IDAS user does not need to know anything about the usage of matrix functions by the IDAS code modules in order to use IDAS. The information is presented as an implementation detail for the interested reader.

Table 9.6 List of matrix functions usage by IDAS code modules
	IDALS	IDABBDPRE
`SUNMatGetID()`	x
`SUNMatDestroy()`		x
`SUNMatZero()`	x	x
`SUNMatSpace()`		\(\dagger\)

The matrix functions listed with a \(\dagger\) symbol are optionally used, in that these are only called if they are implemented in the SUNMatrix module that is being used (i.e. their function pointers are non-NULL). The matrix functions listed in §9.1 that are not used by IDAS are: SUNMatCopy(), SUNMatClone(), SUNMatScaleAdd(), SUNMatScaleAddI() and SUNMatMatvec(). Therefore a user-supplied SUNMatrix module for IDAS could omit these functions.

We note that the IDABBDPRE preconditioner module is hard-coded to use the SUNDIALS-supplied band SUNMatrix type, so the most useful information above for user-supplied SUNMatrix implementations is the column relating the IDALS requirements.

9.8. SUNMatrix functions used by KINSOL

In Table 9.7, we list the matrix functions in the SUNMatrix module used within the KINSOL package. The table also shows, for each function, which of the code modules uses the function. The main KINSOL integrator does not call any SUNMatrix functions directly, so the table columns are specific to the KINLS and KINBBDPRE preconditioner modules. We further note that the KINLS interface only utilizes these routines when supplied with a matrix-based linear solver, i.e., the SUNMatrix object passed to KINSetLinearSolver() was not NULL.

At this point, we should emphasize that the KINSOL user does not need to know anything about the usage of matrix functions by the KINSOL code modules in order to use KINSOL. The information is presented as an implementation detail for the interested reader.

Table 9.7 List of matrix functions usage by KINSOL code modules
	KINLS	KINBBDPRE
`SUNMatGetID()`	x
`SUNMatDestroy()`		x
`SUNMatZero()`	x	x
`SUNMatSpace()`		\(\dagger\)

The matrix functions listed with a \(\dagger\) symbol are optionally used, in that these are only called if they are implemented in the SUNMatrix module that is being used (i.e. their function pointers are non-NULL). The matrix functions listed in §9.1 that are not used by KINSOL are: SUNMatCopy(), SUNMatClone(), SUNMatScaleAdd(), SUNMatScaleAddI() and SUNMatMatvec(). Therefore a user-supplied SUNMatrix module for KINSOL could omit these functions.

We note that the KINBBDPRE preconditioner module is hard-coded to use the SUNDIALS-supplied band SUNMatrix type, so the most useful information above for user-supplied SUNMatrix implementations is the column relating the KINLS requirements.