Previous  Up  

Module Kinsol.Spils

module Spils: sig .. end

Scaled Preconditioned Iterative Linear Solvers.

include Sundials_LinearSolver.Iterative

Preconditioners

type 'data solve_arg = {
   uscale : 'data; (*

Diagonal elements of the scaling matrix for u.

*)
   fscale : 'data; (*

Diagonal elements of the scaling matrix for fval.

*)
}

Arguments passed to the preconditioner solver function.

type 'd prec_solve_fn = (unit, 'd) Kinsol.jacobian_arg -> 'd solve_arg -> 'd -> unit

Callback functions that solve a linear system involving a preconditioner matrix. The call prec_solve_fn jarg sarg v must solve $Pz = r$, where jarg is a Kinsol.jacobian_arg with no work vectors, sarg is a Kinsol.Spils.solve_arg giving the scaling matrices, and v is initially the right-hand side vector $r$ and is later filled with the computed solution $z$. $P$ is a preconditioner matrix that approximates the system Jacobian $J = \frac{\partial F}{\partial u}$.

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

Neither the elements of jarg or sarg, nor z should be accessed after the function has returned.

type 'd prec_setup_fn = (unit, 'd) Kinsol.jacobian_arg -> 'd solve_arg -> unit

Callback functions that preprocess or evaluate Jacobian-related data need by Kinsol.Spils.prec_solve_fn. In the call prec_setup_fn jarg sarg, jarg is a Kinsol.jacobian_arg with no work vectors and sarg is a Kinsol.Spils.solve_arg giving the scaling matrices.

The callback should raise an exception if unsuccessful.

The elements of jarg and sarg 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 or right) and callback functions. The following functions and those in Kinsol_bbd construct preconditioners.

val prec_none : ('d, 'k) preconditioner

No preconditioning.

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

Right preconditioning. The Kinsol.Spils.prec_setup_fn should compute the right preconditioner matrix $P$ which is used to form the scaled preconditioned linear system $(D_F J(u) P^{-1} D_u^{-1} \cdot (D_u P x) = * -D_F F(u)$.

Solvers

type 'data jac_times_vec_fn = 'data -> 'data -> 'data -> bool -> bool

Callback functions that compute (an approximation to) the Jacobian times a vector. In the call jac_times_vec_fn v jv u new_u, v is the vector multiplying the Jacobian, jv is the vector in which to store the result—$\mathtt{jv} = J\mathtt{v}$—, u is the current value of the dependent variable vector, and new_u=true indicates that the Jacobian data should be recomputed. Returning false requests an update of the Jacobian data at the next call.

v, jv, and u should not be accessed after the function has returned.

val solver : ('m, 'd, 'k, [> `Iter ]) Sundials.LinearSolver.t ->
       ?jac_times_vec:'d jac_times_vec_fn ->
       ?jac_times_sys:'d Kinsol.sysfn ->
       ('d, 'k) preconditioner -> ('d, 'k) Kinsol.linear_solver

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

The jac_times_sys argument specifies an alternative system function for use in the internal Jacobian-vector product difference quotient approximation. It is incorrect to specify both this argument and jac_times_vec.

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

NB: a jac_times_sys function is not supported in Config.sundials_version < 5.3.0.

Solver statistics

val get_work_space : ('d, 'k) Kinsol.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) Kinsol.session -> int

Returns the cumulative number of linear iterations.

val get_num_lin_conv_fails : ('d, 'k) Kinsol.session -> int

Returns the cumulative number of linear convergence failures.

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

Returns the cumulative number of calls to the setup function.

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

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

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

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

val get_num_lin_func_evals : ('d, 'k) Kinsol.session -> int

Returns the number of calls to the system function for finite difference quotient Jacobian-vector product approximations. This counter is only updated if the default difference quotient function is used.

Low-level solver manipulation

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

Change the preconditioner functions.

val set_jac_times : ('d, 'k) Kinsol.session -> 'd jac_times_vec_fn -> unit

Change the Jacobian-times-vector function.

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

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