module Sundials_LinearSolver:`sig`

..`end`

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.

**Version:**6.1.0**Since**3.0.0- See Sundials: The SUNLinearSolver API
- See Sundials: Linear Algebraic Solvers

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`

.

- See Sundials: SUNLinearSolver

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.

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`

.

module Direct:`sig`

..`end`

Direct Linear Solvers

module Iterative:`sig`

..`end`

Iterative Linear Solvers

module Custom:`sig`

..`end`

Custom linear solvers.

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

'd atimesfn -> unit

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

.

- See Sundials: SUNLinSolSetATimes

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

psetupfn -> 'd psolvefn -> unit

Set the linear solver's preconditioner routines.

- See Sundials: SUNLinSolSetPreconditioner

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

- See Sundials: SUNLinSolSetScalingVectors

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

**Since**5.8.0- See Sundials: SUNLinSolSetZeroGuess

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

Initializes a linear solver.

- See Sundials: SUNLinSolInitialize

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

- See Sundials: SUNLinSolSetup

`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`

.

- See Sundials: SUNLinSolSolve

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

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

call.

- See Sundials: SUNLinSolNumIters

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

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

call.

- See Sundials: SUNLinSolResNorm

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

- See Sundials: SUNLinSolResNorm

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

linear_solver_type

Returns the type of the linear solver.

- See Sundials: SUNLinSolGetType

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

linear_solver_id

Returns the identifier of the linear solver.

**Since**5.0.0- See Sundials: SUNLinSolGetID

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

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

**Since**5.0.0- See Sundials: SUNLinSolGetLastFlag

`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`

).

- See Sundials: SUNLinSolSpace

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

- See Sundials: SUNLS_PACKAGE_FAIL_REC
- See Sundials: SUNLS_PACKAGE_FAIL_UNREC

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

- See Sundials: SUNLS_ATIMES_FAIL_REC
- See Sundials: SUNLS_ATIMES_FAIL_UNREC

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

- See Sundials: SUNLS_PSET_FAIL_REC
- See Sundials: SUNLS_PSET_FAIL_UNREC

`exception PSolveFailure of ``bool`

Indicates failure of a preconditioner solver. The argument is `true`

for a
recoverable failure and `false`

for an unrecoverable one.

- See Sundials: SUNLS_PSOLVE_FAIL_REC
- See Sundials: SUNLS_PSOLVE_FAIL_UNREC

`exception GSFailure`

Indicates failure of a Gram-Schmidt routine.

- See Sundials: SUNLS_GS_FAIL

`exception QRSolFailure`

Indicates that the QR solution found a singular result.

- See Sundials: SUNLS_QRSOL_FAIL

`exception VectorOpError`

An error occurred in a vector operation.

- See Sundials: SUNLS_VECTOROP_ERR

`exception ResReduced`

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

- See Sundials: SUNLS_RES_REDUCED

`exception ConvFailure`

Indicates that a solver failed to converge.

- See Sundials: SUNLS_CONV_FAIL

`exception QRfactFailure`

Indicates that QR factorization encountered a singular matrix.

- See Sundials: SUNLS_QRFACT_FAIL

`exception LUfactFailure`

Indicates that LU factorization encountered a singular matrix.

- See Sundials: SUNLS_LUFACT_FAIL

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

- See Sundials: SUNLS_PACKAGE_FAIL_REC
- See Sundials: SUNLS_PACKAGE_FAIL_UNREC

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