Previous  Up  Next

Module Sundials.LinearSolver

module LinearSolver: Sundials_LinearSolver

Generic linear solvers.

Sundials provides a set of functions for instantiating linear solvers from two families: Sundials_LinearSolver.Direct and Sundials_LinearSolver.Iterative. Any instance may be associated with at most one solver session.

type ('matrix, 'data, 'kind, 'tag) t = ('matrix, 'data, 'kind, 'tag) linear_solver

A linear solver. The type variables specify the Jacobian matrix ('matrix), the Nvector.nvector data ('data) and kind ('kind), and a 'tag used to identify specific solver features (like the iterative method).

A linear solver of this type must be converted to session-specific form by Cvode.Dls.solver, Ida.Dls.solver, Cvode.Spils.solver, Ida.Spils.solver, etc., before being attached to a session via init or reinit.

type ('mat, [> Nvector_serial.kind ], 'tag) serial_t = ('mat, Nvector_serial.data, [> Nvector_serial.kind ] as 'kind, 'tag)
       t

Alias for linear solvers that are restricted to serial nvectors.

type linear_solver_type =
| Direct (*

Performs an exact computation based on a matrix.

*)
| Iterative (*

Computes an inexact approximation without a matrix.

*)
| MatrixIterative (*

Computes an inexact approximation using a matrix.

*)
| MatrixEmbedded (*

Computes without an explicit input matrix

*)

Broadly classifies the operations provided by a linear solver and its operating principle.

type linear_solver_id =
| Band
| Dense
| Klu
| LapackBand
| LapackDense
| Pcg
| Spbcgs
| Spfgmr
| Spgmr
| Sptfqmr
| Superludist
| Superlumt
| Custom

The identifier of a linear solver.

Callback Routines

type 'data atimesfn = 'data -> 'data -> unit

A function atimesfn v z computes the action of the system matrix on the vector v, storing the result in z. The matrix is represented implicitly by the effect of the function.

If a problem occurs the function raises Sundials_LinearSolver.ATimesFailure.

type psetupfn = unit -> unit

Functions that set up any problem data in preparation for calls to psolvefn.

If a problem occurs the function raises Sundials_LinearSolver.PSetFailure.

type 'data psolvefn = 'data -> 'data -> float -> bool -> unit

A function psolvefn r z tol lr that solves the preconditioner equation $Pz = r$ for the vector z such that $\left\lVert Pz - r \right\rVert_\mathrm{wrms} < \mathit{tol}$ . If lr is true then $P$ should be treated as a left preconditioner and otherwise as a right preconditioner.

If a problem occurs the function raises Sundials_LinearSolver.PSolveFailure.

Linear Solver Families

module Direct: sig .. end

Direct Linear Solvers

module Iterative: sig .. end

Iterative Linear Solvers

module Custom: sig .. end

Custom linear solvers.

Operations

val set_atimes : ('m, 'd, 'k, 't) t ->
       'd atimesfn -> unit

Set the linear solver's problem-specific Sundials_LinearSolver.atimesfn.

val set_preconditioner : ('m, 'd, 'k, 't) t ->
       psetupfn -> 'd psolvefn -> unit

Set the linear solver's preconditioner routines.

val set_scaling_vectors : ('m, 'd, 'k, 't) t ->
       ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> unit

Sets the linear solver's left/right scaling vectors for use in Sundials_LinearSolver.solve. The call set_scaling_vectors ls s1 s2 provides diagonal matrices of scale factors for solving the system $\tilde{A}\tilde{x} = \tilde{b}$ where $\tilde{A} = S_1 P_1^{-1} A P_2^{-1} S_2^{-1}$ , $\tilde{b} = S_1 P_1^{-1} b$ , and $\tilde{x} = S_2 P_2 x$ .

Note that the underlying data structures may be used directly by the linear solver, i.e., without a copy.

val set_zero_guess : ('m, 'd, 'k, 't) t -> bool -> unit

Indicates that the next call to Sundials_LinearSolver.solve will be made with a zero initial guess.

val init : ('m, 'd, 'k, 't) t -> unit

Initializes a linear solver.

val setup : ('m, 'd, 'k, 't) t ->
       ('a, 'm, 'd, 'k) Sundials.Matrix.t -> unit

Instruct the linear solver to prepare to solve using an updated system matrix.

val solve : ('m, 'd, 'k, 't) t ->
       ('a, 'm, 'd, 'k) Sundials.Matrix.t ->
       ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> float -> unit

Solve a linear system. The call solve ls a x b tol solves the linear system $Ax = b$ .

Direct solvers ignore tol. Matrix-free solvers ignore a, relying instead on the function passed to Sundials_LinearSolver.set_atimes. Iterative solvesr attempt to respect the weighted 2-norm tolerance, tol.

val get_num_iters : ('m, 'd, 'k, 't) t -> int

The number of linear iterations performed in the last Sundials_LinearSolver.solve call.

val get_res_norm : ('m, 'd, 'k, 't) t -> float

The final residual norm from the last Sundials_LinearSolver.solve call.

val get_res_id : ('m, 'd, 'k, 't) t -> 'd

The preconditioned initial residual vector. May be called when an iterative method computes the preconditioned initial residual and Sundials_LinearSolver.solve succeeds without performing any iterations, i.e., if the intial guess or the preconditioner is sufficiently accurate.

The linear solver may return a reference to its internal array, i.e., it may not return a copy.

val get_type : ('m, 'd, 'k, 't) t ->
       linear_solver_type

Returns the type of the linear solver.

val get_id : ('m, 'd, 'k, 't) t ->
       linear_solver_id

Returns the identifier of the linear solver.

val get_last_flag : ('m, 'd, 'k, 't) t -> int

Returns an indication of the last error encountered by a linear solver.

val get_work_space : ('m, 'd, 'k, 't) t -> int * int

The storage requirements of the linear solver. The result (lrw, liw) gives the number of words used for storing real values (lrw) and the number of words used for storing integer values (liw).

Exceptions

exception InvalidLinearSolver

Raised on invalid use of linear solver functions. For instance, initializing a session with Cvode.Diag and then calling Cvode.Spils.get_num_lin_iters, which rather requires a linear solver from Sundials_LinearSolver.Iterative.

exception UnrecoverableFailure of bool

Raised on an unrecoverable failure in a linear solver. The argument is true for a recoverable failure and false for an unrecoverable one.

exception MatrixNotSquare

Raised when creating a linear solver if the given matrix is not square.

exception MatrixVectorMismatch

Raised when creating a linear solver if the number of matrix rows and the vector length are not equal.

exception InsufficientStorageUpperBandwidth

Raised when the storage upper bandwidth (smu) of a Matrix.Band.t is insufficient for use in a particular linear solver.

exception LinearSolverInUse

Raised on an attempt to associate a linear solver instance with more than one session.

exception ATimesFailure of bool

Indicates failure of an atimes function. The argument is true for a recoverable failure and false for an unrecoverable one.

exception PSetFailure of bool

Indicates failure of a preconditioner setup routine. The argument is true for a recoverable failure and false for an unrecoverable one.

exception PSolveFailure of bool

Indicates failure of a preconditioner solver. The argument is true for a recoverable failure and false for an unrecoverable one.

exception GSFailure

Indicates failure of a Gram-Schmidt routine.

exception QRSolFailure

Indicates that the QR solution found a singular result.

exception VectorOpError

An error occurred in a vector operation.

exception ResReduced

Indicates that the residual is reduced but without convergence to the desired tolerance.

exception ConvFailure

Indicates that a solver failed to converge.

exception QRfactFailure

Indicates that QR factorization encountered a singular matrix.

exception LUfactFailure

Indicates that LU factorization encountered a singular matrix.

exception PackageFailure of bool

Indicates failure in an external linear solver package. The argument is true for a recoverable failure and false for an unrecoverable one.

exception IllegalPrecType

Raised by Sundials_LinearSolver.Iterative.set_prec_type if the given type is not allowed.

exception InternalFailure of (string * int)

Indicates that an internal callback, identified by the first argument, returned the given unknown error code.

exception ZeroInDiagonal of int

Setup failed due to a zero diagonal element during LU factorization. The argument indicates the column index numbered from one.