The SUNLinSol_SPGMR Module¶

SUNLinSol_SPGMR Usage¶

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:

SUNLinearSolver 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.

int 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.

int 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.

int 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.

int SUNLinSolSetInfoFile_SPGMR(SUNLinearSolver LS, FILE* info_file)¶

The function SUNLinSolSetInfoFile_SPGMR() sets the output file where all informative (non-error) messages should be directed.

Arguments:

• LS – a SUNLinSol object
• info_file – pointer to output file (stdout by default); a NULL input will disable output

Return value:

• SUNLS_SUCCESS if successful
• SUNLS_MEM_NULL if the SUNLinearSolver memory was NULL
• SUNLS_ILL_INPUT if SUNDIALS was not built with monitoring enabled

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.

int SUNLinSolSetPrintLevel_SPGMR(SUNLinearSolver LS, int print_level)¶

The function SUNLinSolSetPrintLevel_SPGMR() specifies the level of verbosity of the output.

Arguments:

• 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

Return value:

• SUNLS_SUCCESS if successful
• SUNLS_MEM_NULL if the SUNLinearSolver memory was NULL
• SUNLS_ILL_INPUT if SUNDIALS was not built with monitoring enabled, or if the print level value was invalid

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:

SUNLinearSolver SUNSPGMR(N_Vector y, int pretype, int maxl)¶

Wrapper function for SUNLinSol_SPGMR()

int SUNSPGMRSetPrecType(SUNLinearSolver S, int pretype)¶

Wrapper function for SUNLinSol_SPGMRSetPrecType()

int SUNSPGMRSetGSType(SUNLinearSolver S, int gstype)¶

Wrapper function for SUNLinSol_SPGMRSetGSType()

int 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.

subroutine 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.

Arguments:

• CODE (int, input) – flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4.
• PRETYPE (int, input) – flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3.
• MAXL (int, input) – number of GMRES basis vectors to use.
• IER (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.

subroutine 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.

Arguments:

• PRETYPE (int, input) – flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3.
• MAXL (int, input) – number of GMRES basis vectors to use.
• IER (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:

subroutine 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.

subroutine 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.

subroutine 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.

subroutine 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.

subroutine 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.

subroutine 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.

SUNLinSol_SPGMR Description¶

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

  \[\begin{split}F_i = \begin{bmatrix} 1 & & & & & & & \\ & \ddots & & & & & & \\ & & 1 & & & & & \\ & & & c_i & -s_i & & & \\ & & & s_i & c_i & & & \\ & & & & & 1 & & \\ & & & & & & \ddots & \\ & & & & & & & 1\end{bmatrix},\end{split}\]

  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:

• During construction, the xcor and vtemp arrays are cloned from a template N_Vector that is input, and default solver parameters are set.
• User-facing “set” routines may be called to modify default solver parameters.
• Additional “set” routines are called by the SUNDIALS solver that interfaces with SUNLinSol_SPGMR to supply the ATimes, PSetup, and Psolve function pointers and s1 and s2 scaling vectors.
• In the “initialize” call, the remaining solver data is allocated (V, Hes, givens, and yg )
• In the “setup” call, any non-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).
• In the “solve” call, the GMRES iteration is performed. This will include scaling, preconditioning, and restarts if those options have been 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