The SPGMR (Scaled, Preconditioned, Generalized Minimum
Residual [SS1986]) implementation of the SUNLinearSolver
module
provided with SUNDIALS, SUNLinSol_SPGMR, is an iterative linear
solver that is designed to be compatible with any N_Vector
implementation (serial, threaded, parallel, and user-supplied) that
supports a minimal subset of operations (N_VClone()
,
N_VDotProd()
, N_VScale()
,
N_VLinearSum()
, N_VProd()
, N_VConst()
,
N_VDiv()
, and N_VDestroy()
).
The header file to be included when using this module
is sunlinsol/sunlinsol_spgmr.h
. The SUNinSol_SPGMR module
is accessible from all SUNDIALS solvers without
linking to the libsundials_sunlinsolspgmr
module library.
The module SUNLinSol_SPGMR provides the following user-callable routines:
SUNLinSol_SPGMR
(N_Vector y, int pretype, int maxl)¶This constructor function creates and allocates memory for a SPGMR
SUNLinearSolver
. Its arguments are an N_Vector
, the desired
type of preconditioning, and the number of Krylov basis vectors to use.
This routine will perform consistency checks to ensure that it is
called with a consistent N_Vector
implementation (i.e. that it
supplies the requisite vector operations). If y
is
incompatible, then this routine will return NULL
.
A maxl
argument that is \(\le0\) will result in the default
value (5).
Allowable inputs for pretype
are PREC_NONE
(0),
PREC_LEFT
(1), PREC_RIGHT
(2) and PREC_BOTH
(3);
any other integer input will result in the default (no
preconditioning). We note that some SUNDIALS solvers are designed
to only work with left preconditioning (IDA and IDAS) and others
with only right preconditioning (KINSOL). While it is possible to
configure a SUNLinSol_SPGMR object to use any of the
preconditioning options with these solvers, this use mode is not
supported and may result in inferior performance.
SUNLinSol_SPGMRSetPrecType
(SUNLinearSolver S, int pretype)¶This function updates the type of preconditioning to use. Supported
values are PREC_NONE
(0), PREC_LEFT
(1),
PREC_RIGHT
(2) and PREC_BOTH
(3).
This routine will return with one of the error codes
SUNLS_ILL_INPUT
(illegal pretype
), SUNLS_MEM_NULL
(S
is NULL
) or SUNLS_SUCCESS
.
SUNLinSol_SPGMRSetGSType
(SUNLinearSolver S, int gstype)¶This function sets the type of Gram-Schmidt orthogonalization to
use. Supported values are MODIFIED_GS
(1) and
CLASSICAL_GS
(2). Any other integer input will result in a
failure, returning error code SUNLS_ILL_INPUT
.
This routine will return with one of the error codes
SUNLS_ILL_INPUT
(illegal gstype
), SUNLS_MEM_NULL
(S
is NULL
) or SUNLS_SUCCESS
.
SUNLinSol_SPGMRSetMaxRestarts
(SUNLinearSolver S, int maxrs)¶This function sets the number of GMRES restarts to allow. A negative input will result in the default of 0.
This routine will return with one of the error codes
SUNLS_MEM_NULL
(S
is NULL
) or SUNLS_SUCCESS
.
SUNLinSolSetInfoFile_SPGMR
(SUNLinearSolver LS, FILE* info_file)¶The function SUNLinSolSetInfoFile_SPGMR()
sets the
output file where all informative (non-error) messages should be directed.
stdout
by default);
a NULL
input will disable outputNULL
Notes:
This function is intended for users that wish to monitor the linear
solver progress. By default, the file pointer is set to stdout
.
SUNDIALS must be built with the CMake option ``SUNDIALS_BUILD_WITH_MONITORING``, to utilize this function. See section Configuration options (Unix/Linux) for more information.
SUNLinSolSetPrintLevel_SPGMR
(SUNLinearSolver LS, int print_level)¶The function SUNLinSolSetPrintLevel_SPGMR()
specifies the
level of verbosity of the output.
LS – a SUNLinSol object
print_level – flag indicating level of verbosity; must be one of:
- 0, no information is printed (default)
- 1, for each linear iteration the residual norm is printed
NULL
Notes: This function is intended for users that wish to monitor the linear solver progress. By default, the print level is 0.
SUNDIALS must be built with the CMake option ``SUNDIALS_BUILD_WITH_MONITORING``, to utilize this function. See section Configuration options (Unix/Linux) for more information.
For backwards compatibility, we also provide the wrapper functions, each with identical input and output arguments to the routines that they wrap:
SUNSPGMR
(N_Vector y, int pretype, int maxl)¶Wrapper function for SUNLinSol_SPGMR()
SUNSPGMRSetPrecType
(SUNLinearSolver S, int pretype)¶Wrapper function for SUNLinSol_SPGMRSetPrecType()
SUNSPGMRSetGSType
(SUNLinearSolver S, int gstype)¶Wrapper function for SUNLinSol_SPGMRSetGSType()
SUNSPGMRSetMaxRestarts
(SUNLinearSolver S, int maxrs)¶Wrapper function for SUNLinSol_SPGMRSetMaxRestarts()
For solvers that include a Fortran interface module, the
SUNLinSol_SPGMR module also includes the Fortran-callable
function FSUNSPGMRInit()
to initialize
this SUNLinSol_SPGMR module for a given SUNDIALS solver.
FSUNSPGMRInit
(CODE, PRETYPE, MAXL, IER)¶Initializes a SPGMR SUNLinearSolver
structure for
use in a SUNDIALS package.
This routine must be called after the N_Vector
object has
been initialized.
int
, input) – flag denoting the SUNDIALS solver
this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4.int
, input) – flag denoting type of
preconditioning to use: none=0, left=1, right=2, both=3.int
, input) – number of GMRES basis vectors to use.int
, output) – return flag (0 success, -1 for failure).Additionally, when using ARKode with a non-identity mass matrix, the
Fortran-callable function FSUNMassSPGMRInit()
initializes
this SUNLinSol_SPGMR module for solving mass matrix linear systems.
FSUNMassSPGMRInit
(PRETYPE, MAXL, IER)¶Initializes a SPGMR SUNLinearSolver
structure for use in
solving mass matrix systems in ARKode.
This routine must be called after the N_Vector
object has
been initialized.
int
, input) – flag denoting type of
preconditioning to use: none=0, left=1, right=2, both=3.int
, input) – number of GMRES basis vectors to use.int
, output) – return flag (0 success, -1 for failure).The SUNLinSol_SPGMRSetGSType()
, SUNLinSol_SPGMRSetPrecType()
and
SUNLinSol_SPGMRSetMaxRestarts()
routines also support Fortran
interfaces for the system and mass matrix solvers:
FSUNSPGMRSetGSType
(CODE, GSTYPE, IER)¶Fortran interface to SUNLinSol_SPGMRSetGSType()
for system
linear solvers.
This routine must be called after FSUNSPGMRInit()
has
been called.
Arguments: all should have type int
, and have meanings
identical to those listed above.
FSUNMassSPGMRSetGSType
(GSTYPE, IER)¶Fortran interface to SUNLinSol_SPGMRSetGSType()
for mass matrix
linear solvers in ARKode.
This routine must be called after FSUNMassSPGMRInit()
has
been called.
Arguments: all should have type int
, and have meanings
identical to those listed above.
FSUNSPGMRSetPrecType
(CODE, PRETYPE, IER)¶Fortran interface to SUNLinSol_SPGMRSetPrecType()
for system
linear solvers.
This routine must be called after FSUNSPGMRInit()
has
been called.
Arguments: all should have type int
, and have meanings
identical to those listed above.
FSUNMassSPGMRSetPrecType
(PRETYPE, IER)¶Fortran interface to SUNLinSol_SPGMRSetPrecType()
for mass matrix
linear solvers in ARKode.
This routine must be called after FSUNMassSPGMRInit()
has
been called.
Arguments: all should have type int
, and have meanings
identical to those listed above.
FSUNSPGMRSetMaxRS
(CODE, MAXRS, IER)¶Fortran interface to SUNLinSol_SPGMRSetMaxRS()
for system
linear solvers.
This routine must be called after FSUNSPGMRInit()
has
been called.
Arguments: all should have type int
, and have meanings
identical to those listed above.
FSUNMassSPGMRSetMaxRS
(MAXRS, IER)¶Fortran interface to SUNLinSol_SPGMRSetMaxRS()
for mass matrix
linear solvers in ARKode.
This routine must be called after FSUNMassSPGMRInit()
has
been called.
Arguments: all should have type int
, and have meanings
identical to those listed above.
The SUNLinSol_SPGMR module defines the content field of a
SUNLinearSolver
to be the following structure:
struct _SUNLinearSolverContent_SPGMR {
int maxl;
int pretype;
int gstype;
int max_restarts;
int numiters;
realtype resnorm;
int last_flag;
ATimesFn ATimes;
void* ATData;
PSetupFn Psetup;
PSolveFn Psolve;
void* PData;
N_Vector s1;
N_Vector s2;
N_Vector *V;
realtype **Hes;
realtype *givens;
N_Vector xcor;
realtype *yg;
N_Vector vtemp;
int print_level;
FILE* info_file;
};
These entries of the content field contain the following information:
maxl
- number of GMRES basis vectors to use (default is 5),
pretype
- flag for type of preconditioning to employ
(default is none),
gstype
- flag for type of Gram-Schmidt orthogonalization
(default is modified Gram-Schmidt),
max_restarts
- number of GMRES restarts to allow
(default is 0),
numiters
- number of iterations from the most-recent solve,
resnorm
- final linear residual norm from the most-recent
solve,
last_flag
- last error return flag from an internal
function,
ATimes
- function pointer to perform \(Av\) product,
ATData
- pointer to structure for ATimes
,
Psetup
- function pointer to preconditioner setup routine,
Psolve
- function pointer to preconditioner solve routine,
PData
- pointer to structure for Psetup
and Psolve
,
s1, s2
- vector pointers for supplied scaling matrices
(default is NULL
),
V
- the array of Krylov basis vectors
\(v_1, \ldots, v_{\text{maxl}+1}\), stored in
V[0], ... V[maxl]
. Each \(v_i\) is a vector of type
N_Vector
,
Hes
- the \((\text{maxl}+1)\times\text{maxl}\)
Hessenberg matrix. It is stored row-wise so that the (i,j)th
element is given by Hes[i][j]
,
givens
- a length \(2\,\text{maxl}\) array which represents
the Givens rotation matrices that arise in the GMRES
algorithm. These matrices are \(F_0, F_1, \ldots, F_j\), where
are represented in the givens
vector as
givens[0]
\(= c_0\),
givens[1]
\(= s_0\),
givens[2]
\(= c_1\),
givens[3]
\(= s_1\), \(\ldots\),
givens[2j]
\(= c_j\),
givens[2j+1]
\(= s_j\),
xcor
- a vector which holds the scaled, preconditioned
correction to the initial guess,
yg
- a length \((\text{maxl}+1)\) array of realtype
values used to hold “short” vectors (e.g. \(y\) and \(g\)),
vtemp
- temporary vector storage.
print_level
- controls the amount of information to be printed to the info file
info_file
- the file where all informative (non-error) messages will be directed
This solver is constructed to perform the following operations:
xcor
and vtemp
arrays are
cloned from a template N_Vector
that is input, and default
solver parameters are set.ATimes
, PSetup
, and Psolve
function pointers and
s1
and s2
scaling vectors.V
, Hes
, givens
, and yg
)NULL
PSetup
function is called. Typically, this is provided by
the SUNDIALS solver itself, that translates between the generic
PSetup
function and the solver-specific routine (solver-supplied
or user-supplied).The SUNLinSol_SPGMR module defines implementations of all “iterative” linear solver operations listed in the section The SUNLinearSolver API:
SUNLinSolGetType_SPGMR
SUNLinSolInitialize_SPGMR
SUNLinSolSetATimes_SPGMR
SUNLinSolSetPreconditioner_SPGMR
SUNLinSolSetScalingVectors_SPGMR
SUNLinSolSetup_SPGMR
SUNLinSolSolve_SPGMR
SUNLinSolNumIters_SPGMR
SUNLinSolResNorm_SPGMR
SUNLinSolResid_SPGMR
SUNLinSolLastFlag_SPGMR
SUNLinSolSpace_SPGMR
SUNLinSolFree_SPGMR