# Module Spils

module Spils: sig .. end
Scaled Preconditioned Iterative Linear Solvers routines.

Global constants and general purpose solver routines.

Author(s): Timothy Bourke (Inria/ENS), Jun Inoue (Inria/ENS), Marc Pouzet (UPMC/ENS/Inria)
Version: 2.7.0
See sundials: The SPILS Modules

## Types

type gramschmidt_type = 
 | ModifiedGS (* Modified Gram-Schmidt orthogonalization (MODIFIED_GS) *) | ClassicalGS (* Classical Gram Schmidt orthogonalization (CLASSICAL_GS) *)
The type of Gram-Schmidt orthogonalization in SPGMR linear solvers.
See sundials: ModifiedGS/ClassicalGS
type preconditioning_type = 
 | PrecNone (* No preconditioning *) | PrecLeft (* $(P^{-1}A)x = P^{-1}b$ *) | PrecRight (* $(AP^{-1})Px = b$ *) | PrecBoth (* $(P_L^{-1}AP_R^{-1})P_Rx = P_L^{-1}b$ *)
The type of preconditioning in Krylov solvers.
See sundials: Preconditioning
See sundials: CVSpgmr/CVSpbcg/CVSptfqrm

## Exceptions

exception ZeroDiagonalElement of int
Raised by Spils.qr_fact and Spils.qr_sol on a zero diagonal element during factorization. The argument gives the equation number (from 1).
exception ConvFailure
Raised when a solver fails to converge. (*_CONVFAIL)
exception QRfactFailure
Raised when QR factorization yields a singular matrix. (*_SPTFQMR_QRFACT_FAIL)
exception PSolveFailure of bool
Raised when a preconditioner solver fails. The argument is true for a recoverable failure and false for an unrecoverable one. (*_PSOLVE_FAIL_REC/_UNREC)
exception ATimesFailure of bool
Raised when an atimes function fails. The argument is true for a recoverable failure and false for an unrecoverable one. (*_ATIMES_FAIL_REC/_UNREC)
exception PSetFailure of bool
Raised when a preconditioner setup routine fails. The argument is true for a recoverable failure and false for an unrecoverable one. (*_PSET_FAIL_REC/_UNREC)
exception GSFailure
Raised when a Gram-Schmidt routine fails. (*_GS_FAIL)
exception QRSolFailure
Raised QR solution finds a singular result. (*_QRSOL_FAIL)

## Basic routines

val qr_fact : Sundials.RealArray2.t -> Sundials.RealArray.t -> bool -> unit
Performs a QR factorization of a Hessenberg matrix. The call qr_fact h q newjob, where h is the n+1 by n Hessenberg matrix (stored row-wise), q stores the computed Givens rotation, and newjob=false indicates that the first n-1 columns of h have already been factored. The computed Givens rotation has the form $\begin{bmatrix} c & -s \\ s & c \end{bmatrix}$ . It is stored in the 2n elements of q as [|c; s; c; s; ...; c; s|].
Raises ZeroDiagonalElement Zero found in matrix diagonal
val qr_sol : Sundials.RealArray2.t -> Sundials.RealArray.t -> Sundials.RealArray.t -> unit
Solve the linear least squares problem. In qr_sol h q b, h and q are, respectively, the upper triangular factor $R$ of the original Hessenberg matrix and Q the Givens rotations used to factor it—both computed by Spils.qr_fact. The function computes the n+1 elements of b to solve $Rx = Qb$.
Raises ZeroDiagonalElement Zero found in matrix diagonal
val modified_gs : ('d, 'k) Nvector.t array -> Sundials.RealArray2.t -> int -> int -> float
Performs a modified Gram-Schmidt orthogonalization. In modified_gs v h k p,
• v is an array of at least k + 1 vectors with an L2-norm of 1,
• h is the output k by k Hessenberg matrix of inner products,
• k specifies the vector in v to be orthogonalized against previous ones, and,
• p is the number of previous vectors in v to orthogonalize against.
The vector v[k] is orthogonalized against the p unit vectors at v.{k-1}, v.{k-2}, ..., v.{k-p}. The matrix h must be allocated row-wise so that the (i,j)th entry is h.{i}.{j}. The inner products are computed, $\mathtt{h.\{}i\mathtt{, k-1\}} = \mathtt{v.\{}i\mathtt{\}} \cdot \mathtt{v.\{k\}}$ , for $i=\max(0, \mathtt{k}-\mathtt{p})\ldots \mathtt{k}-1$ . The orthogonalized v.{k} is not normalized and is stored over the old v.{k}. The function returns the Euclidean norm of the orthogonalized vector.
val classical_gs : ('d, 'k) Nvector.t array ->       Sundials.RealArray2.t ->       int -> int -> ('d, 'k) Nvector.t -> Sundials.RealArray.t -> float
Performs a classical Gram-Schmidt orthogonalization. In classical_gs v h k p temp s,
• v is an array of at least k + 1 vectors with an L2-norm of 1,
• h is the output k by k Hessenberg matrix of inner products,
• k specifies the vector in v to be orthogonalized against previous ones, and,
• p is the number of previous vectors in v to orthogonalize against.
• temp and s are used as workspaces.
The vector v[k] is orthogonalized against the p unit vectors at v.{k-1}, v.{k-2}, ..., v.{k-p}. The matrix h must be allocated row-wise so that the (i,j)th entry is h.{i}.{j}. The inner products are computed, $\mathtt{h.\{}i\mathtt{, k-1\}} = \mathtt{v.\{}i\mathtt{\}} \cdot \mathtt{v.\{k\}}$ , for $i=\max(0, \mathtt{k}-\mathtt{p})\ldots \mathtt{k}-1$ . The orthogonalized v.{k} is not normalized and is stored over the old v.{k}. The function returns the Euclidean norm of the orthogonalized vector.

## Solvers

type 'd atimes = 'd -> 'd -> unit
Functions f v z that calculate z = A v using an internal representation of A. Results are stored in z, v must not be changed. Raise Sundials.RecoverableFailure to indicate a recoverable failure, any other exception indicates an unrecoverable failure.
type 'd psolve = 'd -> 'd -> bool -> unit
Functions f r z lr that solve the preconditioner equation P z = r for the vector z. If lr = true then P is used as a left preconditioner and otherwise as a right preconditioner. Raise Sundials.RecoverableFailure to indicate a recoverable failure, any other exception indicates an unrecoverable failure.
module SPGMR: sig .. end
The Scaled Preconditioned Generalized Minimum Residual (GMRES) method.
module SPFGMR: sig .. end
The Scaled Preconditioned Flexible Generalized Minimum Residual (GMRES) method.
module SPBCG: sig .. end
The Scaled Preconditioned Biconjugate Gradient Stabilized (Bi-CGStab) method.
module SPTFQMR: sig .. end
The Scaled Preconditioned Transpose-Free Quasi-Minimal Residual (SPTFQMR) method
module PCG: sig .. end