3.4.1. Access to library and header files
At this point, it is assumed that the installation of ARKODE, following the procedure described in §14, has been completed successfully.
Regardless of where the user’s application program resides, its associated compilation and load commands must make reference to the appropriate locations for the library and header files required by ARKODE. The relevant library files are
libdir/libsundials_arkode.lib
,libdir/libsundials_nvec*.lib
,
where the file extension .lib
is typically .so
for shared
libraries and .a
for static libraries. The relevant header files
are located in the subdirectories
incdir/include/arkode
incdir/include/sundials
incdir/include/nvector
incdir/include/sunmatrix
incdir/include/sunlinsol
incdir/include/sunnonlinsol
The directories libdir
and incdir
are the installation library
and include directories, respectively. For a default installation,
these are instdir/lib
and instdir/include
, respectively, where
instdir
is the directory where SUNDIALS was installed (see
§14 for further details).
When using ARKODE, the calling program must include several header files so that various macros and data types can be used. One of the following header files is always required:
arkode/arkode_arkstep.h
, the main header file for the ARKStep time-stepping module.arkode/arkode_erkstep.h
, the main header file for the ERKStep time-stepping module.arkode/arkode_mristep.h
, the main header file for the MRIStep time-stepping module.
Each of these define several types and various constants, include
function prototypes, and include the shared arkode/arkode.h
and
arkode/arkode_ls.h
header files.
Note that arkode.h
includes sundials_types.h
directly, which
defines the types realtype
, sunindextype
, and booleantype
and the constants SUNFALSE
and SUNTRUE
, so a user program does
not need to include sundials_types.h
directly.
Additionally, the calling program must also include an NVECTOR
implementation header file, of the form nvector/nvector_***.h
,
corresponding to the user’s preferred data layout and form of
parallelism. See §9 for details for the
appropriate name. This file in turn includes the header file
sundials_nvector.h
which defines the abstract N_Vector
data
type.
If the user wishes to manually select between any of the pre-defined
ERK or DIRK Butcher tables (for ARKStep, ERKStep, or as the basis for
an MIS method), these are defined through a set of constants
that are enumerated in the header files arkode/arkode_butcher_erk.h
and arkode/arkode_butcher_dirk.h
, or if a user wishes to manually
specify one or more Butcher tables, the corresponding ARKodeButcherTable
structure is defined in arkode/arkode_butcher.h
. Alternatively,
for MRIStep, slow-to-fast coupling coefficient tables are enumerated in the
header file arkode/arkode_mristp.h
, or if a user wishes to manually specify
a coupling table, the corresponding MRIStepCouplingMem
structure is defined
in arkode/arkode_mristep.h
.
If the user includes a non-trivial implicit component to their ODE
system in ARKStep, or if the slow time scale for MRIStep should be treated
implicitly, then each implicit stage will require a nonlinear solver for
the resulting system of algebraic equations – the default for this is a
modified or inexact Newton iteration, depending on the user’s choice of
linear solver. If using a non-default nonlinear solver
module, or when interacting with a SUNNONLINSOL module directly, the
calling program must also include a SUNNONLINSOL header file, of the
form sunnonlinsol/sunnonlinsol_***.h
where ***
is the name of
the nonlinear solver module (see §12 for
more information). This file in turn includes the header file
sundials_nonlinearsolver.h
which defines the abstract
SUNNonlinearSolver
data type.
If using a nonlinear solver that requires the solution of a linear system of the form \(\mathcal{A}x=b\) (e.g., the default Newton iteration), then a linear solver module header file will also be required. Similarly, if the ODE system in ARKStep involves a non-identity mass matrix \(M \ne I\), then each time step will require a linear solver for systems of the form \(Mx=b\). The header files corresponding to the SUNDIALS-provided linear solver modules available for use with ARKODE are:
Direct linear solvers:
sunlinsol/sunlinsol_dense.h
, which is used with the dense linear solver module, SUNLINSOL_DENSE;sunlinsol/sunlinsol_band.h
, which is used with the banded linear solver module, SUNLINSOL_BAND;sunlinsol/sunlinsol_lapackdense.h
, which is used with the LAPACK dense linear solver module, SUNLINSOL_LAPACKDENSE;sunlinsol/sunlinsol_lapackband.h
, which is used with the LAPACK banded linear solver module, SUNLINSOL_LAPACKBAND;sunlinsol/sunlinsol_klu.h
, which is used with the KLU sparse linear solver module, SUNLINSOL_KLU;sunlinsol/sunlinsol_superlumt.h
, which is used with the SuperLU_MT sparse linear solver module, SUNLINSOL_SUPERLUMT;sunlinsol/sunlinsol_superludist.h
, which is used with the SuperLU_DIST parallel sparse linear solver module, SUNLINSOL_SUPERLUDIST;sunlinsol/sunlinsol_cusolversp_batchqr.h
, which is used with the batched sparse QR factorization method provided by the NVDIA cuSOLVER library, SUNLINSOL_CUSOLVERSP_BATCHQR;
Iterative linear solvers:
sunlinsol/sunlinsol_spgmr.h
, which is used with the scaled, preconditioned GMRES Krylov linear solver module, SUNLINSOL_SPGMR;sunlinsol/sunlinsol_spfgmr.h
, which is used with the scaled, preconditioned FGMRES Krylov linear solver module, SUNLINSOL_SPFGMR;sunlinsol/sunlinsol_spbcgs.h
, which is used with the scaled, preconditioned Bi-CGStab Krylov linear solver module, SUNLINSOL_SPBCGS;sunlinsol/sunlinsol_sptfqmr.h
, which is used with the scaled, preconditioned TFQMR Krylov linear solver module, SUNLINSOL_SPTFQMR;sunlinsol/sunlinsol_pcg.h
, which is used with the scaled, preconditioned CG Krylov linear solver module, SUNLINSOL_PCG;
The header files for the SUNLINSOL_DENSE and SUNLINSOL_LAPACKDENSE
linear solver modules include the file
sunmatrix/sunmatrix_dense.h
, which defines the SUNMATRIX_DENSE
matrix module, as well as various functions and macros for acting on
such matrices.
The header files for the SUNLINSOL_BAND and SUNLINSOL_LAPACKBAND
linear solver modules include the file sunmatrix/sunmatrix_band.h
,
which defines the SUNMATRIX_BAND matrix module, as well as various
functions and macros for acting on such matrices.
The header files for the SUNLINSOL_KLU and SUNLINSOL_SUPERLUMT linear
solver modules include the file sunmatrix/sunmatrix_sparse.h
,
which defines the SUNMATRIX_SPARSE matrix module, as well as various
functions and macros for acting on such matrices.
The header file for the SUNLINSOL_CUSOLVERSP_BATCHQR
linear solver module includes the file sunmatrix/sunmatrix_cusparse.h
,
which defines the SUNMATRIX_CUSPARSE matrix module, as well as various
functions for acting on such matrices.
The header file for the SUNLINSOL_SUPERLUDIST
linear solver module includes the file sunmatrix/sunmatrix_slunrloc.h
,
which defines the SUNMATRIX_SLUNRLOC matrix module, as well as various
functions for acting on such matrices.
The header files for the Krylov iterative solvers include the file
sundials/sundials_iterative.h
, which enumerates the
preconditioning type and (for the SPGMR and SPFGMR solvers) the
choices for the Gram-Schmidt orthogonalization process.
Other headers may be needed, according to the choice of
preconditioner, etc. For example, if preconditioning for an iterative
linear solver were performed using the ARKBBDPRE module, the header
arkode/arkode_bbdpre.h
is needed to access the preconditioner
initialization routines.
3.4.1.1. Data Types
The header file sundials_types.h
contains the definition of the types:
realtype
– the floating-point type used by the SUNDIALS packagessunindextype
– the integer type used for vector and matrix indicesbooleantype
– the type used for logic operations within SUNDIALSSUNOutputFormat
– an enumerated type for SUNDIALS output formats
3.4.1.1.1. Floating point types
-
type realtype
The type
realtype
can befloat
,double
, orlong double
, with the default beingdouble
. The user can change the precision of the arithmetic used in the SUNDIALS solvers at the configuration stage (seeSUNDIALS_PRECISION
).
Additionally, based on the current precision, sundials_types.h
defines
BIG_REAL
to be the largest value representable as a realtype
,
SMALL_REAL
to be the smallest value representable as a realtype
, and
UNIT_ROUNDOFF
to be the difference between \(1.0\) and the minimum
realtype
greater than \(1.0\).
Within SUNDIALS, real constants are set by way of a macro called RCONST
. It
is this macro that needs the ability to branch on the definition of
realtype
. In ANSI C, a floating-point constant with no suffix is stored as a
double
. Placing the suffix “F
” at the end of a floating point constant
makes it a float
, whereas using the suffix “L
” makes it a long
double
. For example,
#define A 1.0
#define B 1.0F
#define C 1.0L
defines A
to be a double
constant equal to \(1.0\), B
to be a
float
constant equal to \(1.0\), and C
to be a long double
constant equal to \(1.0\). The macro call RCONST(1.0)
automatically
expands to 1.0
if realtype
is double
, to 1.0F
if realtype
is
float
, or to 1.0L
if realtype
is long double
. SUNDIALS uses the
RCONST
macro internally to declare all of its floating-point constants.
Additionally, SUNDIALS defines several macros for common mathematical functions
e.g., fabs
, sqrt
, exp
, etc. in sundials_math.h
. The macros are
prefixed with SUNR
and expand to the appropriate C
function based on the
realtype
. For example, the macro SUNRabs
expands to the C
function
fabs
when realtype
is double
, fabsf
when realtype
is
float
, and fabsl
when realtype
is long double
.
A user program which uses the type realtype
, the RCONST
macro, and the
SUNR
mathematical function macros is precision-independent except for any
calls to precision-specific library functions. Our example programs use
realtype
, RCONST
, and the SUNR
macros. Users can, however, use the
type double
, float
, or long double
in their code (assuming that this
usage is consistent with the typedef for realtype
) and call the appropriate
math library functions directly. Thus, a previously existing piece of C or C++
code can use SUNDIALS without modifying the code to use realtype
,
RCONST
, or the SUNR
macros so long as the SUNDIALS libraries are built
to use the corresponding precision (see §14.1.2).
3.4.1.1.2. Integer types used for indexing
-
type sunindextype
The type
sunindextype
is used for indexing array entries in SUNDIALS modules as well as for storing the total problem size (e.g., vector lengths and matrix sizes). During configurationsunindextype
may be selected to be either a 32- or 64-bit signed integer with the default being 64-bit (seeSUNDIALS_INDEX_SIZE
).
When using a 32-bit integer the total problem size is limited to
\(2^{31}-1\) and with 64-bit integers the limit is \(2^{63}-1\). For
users with problem sizes that exceed the 64-bit limit an advanced configuration
option is available to specify the type used for sunindextype
(see SUNDIALS_INDEX_TYPE
).
A user program which uses sunindextype
to handle indices will work with both
index storage types except for any calls to index storage-specific external
libraries. Our C
and C++
example programs use sunindextype
. Users
can, however, use any compatible type (e.g., int
, long int
,
int32_t
, int64_t
, or long long int
) in their code, assuming that
this usage is consistent with the typedef for sunindextype
on their
architecture. Thus, a previously existing piece of C or C++ code can use
SUNDIALS without modifying the code to use sunindextype
, so long as the
SUNDIALS libraries use the appropriate index storage type (for details see
§14.1.2).
3.4.1.1.3. Boolean type
-
type booleantype
As ANSI C89 (ISO C90) does not have a built-in boolean data type, SUNDIALS defines the type
booleantype
as anint
.
The advantage of using the name booleantype (instead of int) is an increase in
code readability. It also allows the programmer to make a distinction between
int and boolean data. Variables of type booleantype
are intended to have
only the two values SUNFALSE
(0
) and SUNTRUE
(1
).
3.4.1.1.4. Output formatting type
-
enum SUNOutputFormat
The enumerated type
SUNOutputFormat
defines the enumeration constants for SUNDIALS output formats
-
enumerator SUN_OUTPUTFORMAT_TABLE
The output will be a table of values
-
enumerator SUN_OUTPUTFORMAT_CSV
The output will be a comma-separated list of key and value pairs e.g.,
key1,value1,key2,value2,...
Note
The file
scripts/sundials_csv.py
provides python utility functions to read and output the data from a SUNDIALS CSV output file using the key and value pair format.