9.3. NVECTOR functions required by ARKODE

In Table 9.2 below, we list the vector functions in the N_Vector module that are called within the ARKODE package. The table also shows, for each function, which ARKODE module uses the function. The ARKStep, ERKStep, MRIStep, and SPRKStep columns show function usage within the main time-stepping modules and the shared ARKODE infrastructure, while the remaining columns show function usage within the ARKLS linear solver interface, within constraint-handling (i.e., when ARKStepSetConstraints() and ERKStepSetConstraints() are used), relaxation (i.e., when ARKStepSetRelaxFn(), ERKStepSetRelaxFn() and related are used), the ARKBANDPRE and ARKBBDPRE preconditioner modules.

Note that for ARKLS we only list the N_Vector routines used directly by ARKLS, each SUNLinearSolver module may have additional requirements that are not listed here. In addition, specific SUNNonlinearSolver modules attached to ARKODE may have additional N_Vector requirements. For additional requirements by specific SUNLinearSolver and SUNNonlinearSolver modules, please see the accompanying sections §11 and §12.

At this point, we should emphasize that the user does not need to know anything about ARKODE’s usage of vector functions in order to use ARKODE. Instead, this information is provided primarily for users interested in constructing a custom N_Vector module. We note that a number of N_Vector functions from the section §9.1 are not listed in the above table. Therefore a user-supplied N_Vector module for ARKODE could safely omit these functions from their implementation (although some may be needed by SUNNonlinearSolver or SUNLinearSolver modules).

Table 9.2 List of vector functions usage by ARKODE code modules
Routine	ARKStep	ERKStep	MRIStep	SPRKStep	ARKLS	Constraints	Relaxation	BBDPRE, BANDPRE
`N_VAbs()`	X	X	X	X
`N_VAddConst()`	X	X	X	X
`N_VClone()`	X	X	X	X	X
`N_VCloneEmpty()`					1
`N_VConst()`	X	X	X	X	X
`N_VConstrMask()`						X
`N_VDestroy()`	X	X	X	X	X
`N_VDiv()`	X	X
`N_VDotProd()`							X
`N_VGetArrayPointer()`					1			X
`N_VGetLength()`					4
`N_VInv()`	X	X	X	X
`N_VLinearCombination()`³	X	X	X	X
`N_VLinearSum()`	X	X	X	X	X		X
`N_VMaxNorm()`	X	X				X
`N_VMin()`	X	X	X	X
`N_VMinQuotient()`						X
`N_VProd()`						X
`N_VScale()`	X	X	X	X	X	X	X	X
`N_VSetArrayPointer()`					1
`N_VSpace()`²	X	X	X	X	X			X
`N_VWrmsNorm()`	X	X	X	X	X			X

Special cases (numbers match markings in table):

This is only required with the SUNMATRIX_DENSE or SUNMATRIX_BAND modules, where the default difference-quotient Jacobian approximation is used.
The N_VSpace() function is only informational, and will only be called if provided by the N_Vector implementation.
The N_VLinearCombination() function is in fact optional; if it is not supplied then N_VLinearSum() will be used instead.
The N_VGetLength() function is only required when an iterative or matrix iterative SUNLinearSolver module is used.

9.4. NVECTOR functions used by CVODE

In Table 9.3 below, we list the vector functions in the NVECTOR module used within the CVODE package. The table also shows, for each function, which of the code modules uses the function. The CVODE column shows function usage within the main integrator module, while the remaining columns show function usage within each of the CVODE linear solver interfaces, the CVBANDPRE and CVBBDPRE preconditioner modules. Here CVLS stands for the generic linear solver interface in CVODE, and CVDIAG stands for the diagonal linear solver interface in CVODE.

At this point, we should emphasize that the CVODE user does not need to know anything about the usage of vector 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 vector functions usage by CVODE code modules
	CVODE	CVLS	CVDIAG	CVBANDPRE	CVBBDPRE
`N_VGetVectorID()`
`N_VGetLength()`		4
`N_VClone()`	x	x	x
`N_VCloneEmpty()`		1
`N_VDestroy()`	x	x	x
`N_VSpace()`	x	2
`N_VGetArrayPointer()`		1		x	x
`N_VSetArrayPointer()`		1
`N_VLinearSum()`	x	x	x
`N_VConst()`	x	x
`N_VProd()`	x		x
`N_VDiv()`	x		x
`N_VScale()`	x	x	x	x	x
`N_VAbs()`	x
`N_VInv()`	x		x
`N_VAddConst()`	x		x
`N_VMaxNorm()`	x
`N_VWrmsNorm()`	x	x		x	x
`N_VMin()`	x
`N_VMinQuotient()`	x
`N_VConstrMask()`	x
`N_VCompare()`	x		x
`N_VInvTest()`			x
`N_VLinearCombination()`	x
`N_VScaleAddMulti()`	x
`N_VDotProdMulti()`	3	3
`N_VScaleVectorArray()`	x

Special cases (numbers match markings in table):

These routines are only required if an internal difference-quotient routine for constructing SUNMATRIX_DENSE or SUNMATRIX_BAND Jacobian matrices is used.
This routine is optional, and is only used in estimating space requirements for CVODE modules for user feedback.
The optional function N_VDotProdMulti is only used in the SUNNONLINSOL_FIXEDPOINT module, or when Classical Gram-Schmidt is enabled with SPGMR or SPFGMR. The remaining operations from §9.2.2 – §9.2.3 not listed above are unused and a user-supplied NVECTOR module for CVODE could omit these operations.
This routine is only used when an iterative or matrix iterative SUNLINSOL module is supplied to CVODE.

Each SUNLINSOL object may require additional NVECTOR routines not listed in the table above. Please see the the relevant descriptions of these modules in §11 for additional detail on their NVECTOR requirements.

The vector functions listed in §9.2 that are not used by CVODE are: N_VWL2Norm(), N_VDotProd(), N_VL1Norm(), N_VWrmsNormMask(), and N_VGetCommunicator(). Therefore, a user-supplied NVECTOR module for CVODE could omit these functions (although some may be needed by SUNNONLINSOL or SUNLINSOL modules). The functions N_MinQuotient(), N_VConstrMask(), and N_VCompare() are only used when constraint checking is enabled and may be omitted if this feature is not used.

9.5. NVECTOR functions used by CVODES

In Table 9.4 below, we list the vector functions in the N_Vector module used within the CVODES package. The table also shows, for each function, which of the code modules uses the function. The CVODES column shows function usage within the main integrator module, while the remaining columns show function usage within each of the CVODES linear solver interfaces, the CVBANDPRE and CVBBDPRE preconditioner modules, and the CVODES adjoint sensitivity module (denoted here by CVODEA). Here CVLS stands for the generic linear solver interface in CVODES, and CVDIAG stands for the diagonal linear solver interface in CVODES.

At this point, we should emphasize that the CVODES user does not need to know anything about the usage of vector 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 vector functions usage by CVODES code modules
	CVODES	CVLS	CVDIAG	CVBANDPRE	CVBBDPRE	CVODEA
`N_VGetVectorID()`
`N_VGetLength()`		4
`N_VClone()`	x	x	x			x
`N_VCloneEmpty()`		1
`N_VDestroy()`	x	x	x			x
`N_VCloneVectorArray()`	x					x
`N_VDestroyVectorArray()`	x					x
`N_VSpace()`	x	2
`N_VGetArrayPointer()`		1		x	x
`N_VSetArrayPointer()`		1
`N_VLinearSum()`	x	x	x			x
`N_VConst()`	x	x
`N_VProd()`	x		x
`N_VDiv()`	x		x
`N_VScale()`	x	x	x	x	x	x
`N_VAbs()`	x
`N_VInv()`	x		x
`N_VAddConst()`	x		x
`N_VMaxNorm()`	x
`N_VWrmsNorm()`	x	x		x	x
`N_VMin()`	x
`N_MinQuotient()`	x
`N_VConstrMask()`	x
`N_VCompare()`	x		x
`N_VInvTest()`			x
`N_VLinearCombination()`	x
`N_VScaleAddMulti()`	x
`N_VDotProdMulti()`	3	3
`N_VLinearSumVectorArray()`	x
`N_VScaleVectorArray()`	x
`N_VConstVectorArray()`	x
`N_VWrmsNormVectorArray()`	x
`N_VScaleAddMultiVectorArray()`	x
`N_VLinearCombinationVectorArray()`	x

Special cases (numbers match markings in table):

These routines are only required if an internal difference-quotient routine for constructing SUNMATRIX_DENSE or SUNMATRIX_BAND Jacobian matrices is used.
This routine is optional, and is only used in estimating space requirements for CVODES modules for user feedback.
The optional function N_VDotProdMulti() is only used in the SUNNONLINSOL_FIXEDPOINT module, or when Classical Gram-Schmidt is enabled with SPGMR or SPFGMR.
This routine is only used when an iterative or matrix iterative SUNLinearSolver module is supplied to CVODES.

Each SUNLinearSolver object may require additional N_Vector routines not listed in the table above. Please see the the relevant descriptions of these modules in §11 for additional detail on their N_Vector requirements.

The remaining operations from §9.2 not listed above are unused and a user-supplied N_Vector module for CVODES could omit these operations (although some may be needed by SUNNonlinearSolver or SUNLinearSolver modules). The functions N_VMinQuotient(), N_VConstrMask(), and N_VCompare() are only used when constraint checking is enabled and may be omitted if this feature is not used.

9.6. NVECTOR functions used by IDA

In Table 9.5 below, we list the vector functions used in the N_Vector module used by the IDA package. The table also shows, for each function, which of the code modules uses the function. The IDA column shows function usage within the main integrator module, while the remaining columns show function usage within the IDALS linear solvers interface, and the IDABBDPRE preconditioner module.

At this point, we should emphasize that the IDA user does not need to know anything about the usage of vector 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 vector functions usage by IDA code modules
	IDA	IDALS	IDABBDPRE
`N_VGetVectorID()`
`N_VGetLength()`		4
`N_VClone()`	x	x	x
`N_VCloneEmpty()`		1
`N_VDestroy()`	x	x	x
`N_VSpace()`	x	2
`N_VGetArrayPointer()`		1	x
`N_VSetArrayPointer()`		1
`N_VLinearSum()`	x	x
`N_VConst()`	x	x
`N_VProd()`	x
`N_VDiv()`	x
`N_VScale()`	x	x	x
`N_VAbs()`	x
`N_VInv()`	x
`N_VAddConst()`	x
`N_VMaxNorm()`	x
`N_VWrmsNorm()`	x
`N_VMin()`	x
`N_VMinQuotient()`	x
`N_VConstrMask()`	x
`N_VWrmsNormMask()`	x
`N_VCompare()`	x
`N_VLinearCombination()`	x
`N_VScaleAddMulti()`	x
`N_VDotProdMulti()`		3
`N_VLinearSumVectorArray()`	x
`N_VScaleVectorArray()`	x

Special cases (numbers match markings in table):

These routines are only required if an internal difference-quotient routine for constructing SUNMATRIX_DENSE or SUNMATRIX_BAND Jacobian matrices is used.
This routine is optional, and is only used in estimating space requirements for IDA modules for user feedback.
The optional function N_VDotProdMulti is only used when Classical Gram-Schmidt is enabled with SPGMR or SPFGMR. The remaining operations from Tables §9.2.2 and §9.2.3 not listed above are unused and a user-supplied N_Vector module for IDA could omit these operations.
This routine is only used when an iterative or matrix iterative SUNLinearSolver module is supplied to IDA.

Of the functions listed in §9.2, N_VWL2Norm(), N_VL1Norm(), N_VInvTest(), and N_VGetCommunicator() are not used by IDA. Therefore a user-supplied N_Vector module for IDA could omit these functions (although some may be needed by SUNNonlinearSolver or SUNLinearSolver modules).

9.7. NVECTOR functions used by IDAS

In Table 9.6 below, we list the vector functions used in the N_Vector module used by the IDAS package. The table also shows, for each function, which of the code modules uses the function. The IDAS column shows function usage within the main integrator module, while the remaining columns show function usage within the IDALS linear solvers interface, and the IDABBDPRE preconditioner module.

At this point, we should emphasize that the IDAS user does not need to know anything about the usage of vector 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 vector functions usage by IDAS code modules
	IDAS	IDALS	IDABBDPRE	IDAA
`N_VGetVectorID()`
`N_VGetLength()`	4
`N_VClone()`	x	x	x	x
`N_VCloneEmpty()`	1
`N_VDestroy()`	x	x	x	x
`N_VCloneVectorArray()`	x	x
`N_VDestroyVectorArray()`	x	x
`N_VSpace()`	x	2
`N_VGetArrayPointer()`	1	x
`N_VSetArrayPointer()`	1
`N_VLinearSum()`	x	x	x
`N_VConst()`	x	x	x
`N_VProd()`	x
`N_VDiv()`	x
`N_VScale()`	x	x	x	x
`N_VAbs()`	x
`N_VInv()`	x
`N_VAddConst()`	x
`N_VMaxNorm()`	x
`N_VWrmsNorm()`	x	x
`N_VMin()`	x
`N_VMinQuotient()`	x
`N_VConstrMask()`	x
`N_VWrmsNormMask()`	x
`N_VCompare()`	x
`N_VLinearCombination()`	x
`N_VScaleAddMulti()`	x
`N_VDotProdMulti()`	3
`N_VLinearSumVectorArray()`	x
`N_VScaleVectorArray()`	x
`N_VConstVectorArray()`	x
`N_VWrmsNormVectorArray()`	x
`N_VWrmsNormMaskVectorArray()`	x
`N_VScaleAddMultiVectorArray()`	x
`N_VLinearCombinationVectorArray()`	x

Special cases (numbers match markings in table):

These routines are only required if an internal difference-quotient routine for constructing SUNMATRIX_DENSE or SUNMATRIX_BAND Jacobian matrices is used.
This routine is optional, and is only used in estimating space requirements for IDAS modules for user feedback.
The optional function N_VDotProdMulti is only used when Classical Gram-Schmidt is enabled with SPGMR or SPFGMR. The remaining operations from Tables §9.2.2 and §9.2.3 not listed above are unused and a user-supplied N_Vector module for IDAS could omit these operations.
This routine is only used when an iterative or matrix iterative SUNLinearSolver module is supplied to IDAS.

Of the functions listed in §9.2, N_VDotProd() N_VWL2Norm(), N_VL1Norm(), N_VInvTest(), and N_VGetCommunicator() are not used by IDAS. Therefore a user-supplied N_Vector module for IDAS could omit these functions (although some may be needed by SUNNonlinearSolver or SUNLinearSolver modules).

9.8. NVECTOR functions used by KINSOL

In Table 9.7 below, we list the vector functions used in the N_Vector module used by the KINSOL package. The table also shows, for each function, which of the code modules uses the function. The KINSOL column shows function usage within the main integrator module, while the remaining columns show function usage within the KINLS linear solvers interface, and the KINBBDPRE preconditioner module.

At this point, we should emphasize that the KINSOL user does not need to know anything about the usage of vector 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 vector functions usage by KINSOL code modules
Function name	KINSOL	KINLS	KINBBDPRE
`N_VGetVectorID()`
`N_VGetLength()`	4
`N_VClone()`	x	x
`N_VCloneEmpty()`
`N_VDestroy()`	x	x
`N_VSpace()`	x	2
`N_VGetArrayPointer()`	1	x
`N_VSetArrayPointer()`	1
`N_VLinearSum()`	x	x
`N_VConst()`	x
`N_VProd()`	x	x
`N_VDiv()`	x
`N_VScale()`	x	x	x
`N_VAbs()`	x
`N_VInv()`	x
`N_VDotProd()`	x	x
`N_VMaxNorm()`	x
`N_VMin()`	x
`N_VWL2Norm()`	x	x
`N_VL1Norm()`	3
`N_VConstrMask()`	x
`N_VMinQuotient()`	x
`N_VLinearCombination()`	x	x
`N_VDotProdMulti()`	x

Special cases (numbers match markings in table):

These routines are only required if an internal difference-quotient routine for constructing SUNMATRIX_DENSE or SUNMATRIX_BAND Jacobian matrices is used.
This routine is optional, and is only used in estimating space requirements for IDA modules for user feedback.
These routines are only required if the internal difference-quotient routine for approximating the Jacobian-vector product is used.
This routine is only used when an iterative SUNLinearSolver module that does not support the SUNLinSolSetScalingVectors() routine is supplied to KINSOL.

Each SUNLinearSolver object may require additional N_Vector routines not listed in the table above. Please see the the relevant descriptions of these modules in §11 for additional detail on their N_Vector requirements.

The vector functions listed in §9.2 that are not used by KINSOL are N_VAddConst(), N_VWrmsNorm(), N_VWrmsNormMask(), N_VCompare(), N_VInvTest(), and N_VGetCommunicator(). Therefore a user-supplied N_Vector module for KINSOL could omit these functions.

The optional function N_VLinearCombination() is only used when Anderson acceleration is enabled or the SPBCG, SPTFQMR, SPGMR, or SPFGMR linear solvers are used. N_VDotProd() is only used when Anderson acceleration is enabled or Classical Gram-Schmidt is used with SPGMR or SPFGMR. The remaining operations from §9.2.2 and §9.2.3 are unused and a user-supplied N_Vector module for KINSOL could omit these operations.