Module Ida.Spils

module Spils: sig .. end

Scaled Preconditioned Iterative Linear Solvers.


include Sundials_LinearSolver.Iterative

Preconditioners

type 'd prec_solve_fn = (unit, 'd) Ida.jacobian_arg -> 'd -> 'd -> float -> unit 

Callback functions that solve a linear system involving a preconditioner matrix. In the call prec_solve_fn jac r z delta, jac is a Ida.jacobian_arg with no work vectors, r is the right-hand side vector, z is computed to solve $Pz = r$, and delta is the input tolerance. $P$ is a preconditioner matrix, which approximates, however crudely, the Jacobian matrix $\frac{\partial F}{\partial y} + \mathtt{arg.jac\_coef}\frac{\partial F}{\partial\dot{y}}$. If the solution is found via an iterative method, it must satisfy $\sqrt{\sum_i (\mathit{Res}_i \cdot \mathit{ewt}_i)^2} < \mathtt{delta}$, where $\mathit{Res} = r - Pz$ and $\mathit{ewt}$ comes from Ida.get_err_weights.

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

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

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

Callback functions that preprocess or evaluate Jacobian-related data need by Ida.Spils.prec_solve_fn. The sole argument is a Ida.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 the argument should not be accessed after the function has returned.

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

Specifies a preconditioner and its callback functions. The following functions and those in Ida_bbd construct preconditioners.

The Ida.Spils.prec_solve_fn is mandatory. The Ida.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. $Pz = r$, where $P$ approximates, perhaps crudely, $J = \frac{\partial F}{\partial y} + c_j\frac{\partial F}{\partial\dot{y}}$.

Solvers

type 'd jac_times_setup_fn = (unit, 'd) Ida.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 Ida.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 Ida.double, 'd) Ida.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 Ida.jacobian_arg with two work vectors, 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) Ida.session_linear_solver

Create an Ida-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) Ida.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) Ida.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) Ida.session -> int

Returns the cumulative number of linear iterations.

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

Returns the cumulative number of linear convergence failures.

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

Returns the number of calls to the setup function.

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

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

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

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

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

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

val get_num_res_evals : ('d, 'k) Ida.session -> int

Returns the number of calls to the residual 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 Ida.init and Ida.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) Ida.session ->
?setup:'d prec_setup_fn -> 'd prec_solve_fn -> unit

Change the preconditioner functions.

val set_jac_times : ('d, 'k) Ida.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) Ida.session -> unit

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