Module Cvode.Spils

module Spils: sig .. end

Scaled Preconditioned Iterative Linear Solvers.


include Sundials_LinearSolver.Iterative

Preconditioners

type 'd prec_solve_arg = {
   rhs : 'd; (*

Right-hand side vector of the linear system.

*)
   gamma : float; (*

Scalar $\gamma$ in the Newton matrix given by $M = I - \gamma J$.

*)
   delta : float; (*

Input tolerance for iterative methods.

*)
   left : bool; (*

true for left preconditioning and false for right preconditioning.

*)
}

Arguments passed to the preconditioner solver function.

type 'd prec_solve_fn = (unit, 'd) Cvode.jacobian_arg -> 'd prec_solve_arg -> 'd -> unit 

Callback functions that solve a linear system involving a preconditioner matrix. In the call prec_solve_fn jac arg z, jac is a Cvode.jacobian_arg with no work vectors, arg is a Cvode.Spils.prec_solve_arg that specifies the linear system, and z is computed to solve $P\mathtt{z} = \mathtt{arg.rhs}$. $P$ is a preconditioner matrix, which approximates, however crudely, the Newton matrix $M = I - \gamma J$ where $J = \frac{\partial f}{\partial y}$.

Raising Sundials.RecoverableFailure indicates a recoverable error. Any other exception is treated as an unrecoverable error.

The elements of jac, arg, and z should not be accessed after the function has returned.

type 'd prec_setup_fn = (unit, 'd) Cvode.jacobian_arg -> bool -> float -> bool 

Callback functions that preprocess or evaluate Jacobian-related data needed by Cvode.Spils.prec_solve_fn. In the call prec_setup_fn jac jok gamma, jac is a Cvode.jacobian_arg with no work vectors, jok indicates whether any saved Jacobian-related data can be reused with the current value of gamma, and gamma is the scalar $\gamma$ in the Newton matrix $M = I - \gamma J$ where $J$ is the Jacobian matrix. A function should return true if Jacobian-related data was updated and false if saved data was reused.

Raising Sundials.RecoverableFailure indicates a recoverable error. Any other exception is treated as an unrecoverable error.

The elements of jac should not be accessed after the function has returned.

type ('d, 'k) preconditioner = ('d, 'k) SpilsTypes.preconditioner 

Specifies a preconditioner, including the type of preconditioning (none, left, right, or both) and callback functions. The following functions and those in Cvode.Spils.Banded and Cvode_bbd construct preconditioners.

The Cvode.Spils.prec_solve_fn is mandatory. The Cvode.Spils.prec_setup_fn can be omitted if not needed.

val prec_none : ('d, 'k) preconditioner

No preconditioning.

val prec_left : ?setup:'d prec_setup_fn ->
'd prec_solve_fn -> ('d, 'k) preconditioner

Left preconditioning. $(P^{-1}A)x = P^{-1}b$ .

val prec_right : ?setup:'d prec_setup_fn ->
'd prec_solve_fn -> ('d, 'k) preconditioner

Right preconditioning. $(AP^{-1})Px = b$ .

val prec_both : ?setup:'d prec_setup_fn ->
'd prec_solve_fn -> ('d, 'k) preconditioner

Left and right preconditioning. $(P_L^{-1}AP_R^{-1})P_Rx = P_L^{-1}b$

module Banded: sig .. end

Banded preconditioners.

Solvers

type 'd jac_times_setup_fn = (unit, 'd) Cvode.jacobian_arg -> unit 

Callback functions that preprocess or evaluate Jacobian-related data needed by the jac_times_vec_fn. In the call jac_times_setup_fn arg, arg is a Cvode.jacobian_arg with no work vectors.

Raising Sundials.RecoverableFailure indicates a recoverable error. Any other exception is treated as an unrecoverable error.

The elements of arg should not be accessed after the function has returned.

type 'd jac_times_vec_fn = ('d, 'd) Cvode.jacobian_arg -> 'd -> 'd -> unit 

Callback functions that compute the Jacobian times a vector. In the call jac_times_vec_fn arg v jv, arg is a Cvode.jacobian_arg with one work vector, v is the vector multiplying the Jacobian, and jv is the vector in which to store the result—$\mathtt{jv} = J\mathtt{v}$.

Raising Sundials.RecoverableFailure indicates a recoverable error. Any other exception is treated as an unrecoverable error.

Neither the elements of arg nor v or jv should be accessed after the function has returned.

val solver : ('d, 'k, 'f) Sundials.LinearSolver.Iterative.linear_solver ->
?jac_times_vec:'d jac_times_setup_fn option *
'd jac_times_vec_fn ->
('d, 'k) preconditioner -> ('d, 'k) Cvode.session_linear_solver

Create a Cvode-specific linear solver from a generic iterative linear solver.

NB: a jac_times_setup_fn is not supported in Config.sundials_version < 3.0.0.

Solver parameters

val set_eps_lin : ('d, 'k) Cvode.session -> float -> unit

Sets the factor by which the Krylov linear solver's convergence test constant is reduced from the Newton iteration test constant. This factor must be >= 0; passing 0 specifies the default (0.05).

Solver statistics

val get_work_space : ('d, 'k) Cvode.session -> int * int

Returns the sizes of the real and integer workspaces used by the spils linear solver.

val get_num_lin_iters : ('d, 'k) Cvode.session -> int

Returns the cumulative number of linear iterations.

val get_num_conv_fails : ('d, 'k) Cvode.session -> int

Returns the cumulative number of linear convergence failures.

val get_num_prec_evals : ('d, 'k) Cvode.session -> int

Returns the cumulative number of calls to the setup function with jok=false.

val get_num_prec_solves : ('d, 'k) Cvode.session -> int

Returns the cumulative number of calls to the preconditioner solve function.

val get_num_jtsetup_evals : ('d, 'k) Cvode.session -> int

Returns the cumulative number of calls to the Jacobian-vector setup function.

val get_num_jtimes_evals : ('d, 'k) Cvode.session -> int

Returns the cumulative number of calls to the Jacobian-vector function.

val get_num_rhs_evals : ('d, 'k) Cvode.session -> int

Returns the number of calls to the right-hand side callback for finite difference Jacobian-vector product approximation. This counter is only updated if the default difference quotient function is used.

Low-level solver manipulation

The Cvode.init and Cvode.reinit functions are the preferred way to set or change preconditioner functions. These low-level functions are provided for experts who want to avoid resetting internal counters and other associated side-effects.

val set_preconditioner : ('d, 'k) Cvode.session ->
?setup:'d prec_setup_fn -> 'd prec_solve_fn -> unit

Change the preconditioner functions.

val set_jac_times : ('d, 'k) Cvode.session ->
?jac_times_setup:'d jac_times_setup_fn ->
'd jac_times_vec_fn -> unit

Change the Jacobian-times-vector function.

NB: the jac_times_setup argument is not supported in Config.sundials_version < 3.0.0.

val clear_jac_times : ('d, 'k) Cvode.session -> unit

Remove a Jacobian-times-vector function and use the default implementation.