Previous  Up  

Module Arkode.ARKStep.Mass.Spils

module Spils: sig .. end

Iterative mass matrix solvers

include Sundials_LinearSolver.Iterative

Preconditioners

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

Right-hand side vector of the linear system.

*)
   delta : float; (*

Input tolerance for iterative methods.

*)
   left : bool; (*

true for left preconditioning and false for right preconditioning.

*)
}

Arguments passed to the mass matrix preconditioner solver function.

type 'd prec_solve_fn = float -> 'd prec_solve_arg -> 'd -> unit

Callback functions that solve a linear mass matrix system involving a preconditioner matrix. In the call prec_solve_fn t arg z, t is the independent variable, arg is a Arkode.ARKStep.Mass.Spils.prec_solve_arg that specifies the linear system, and z is computed to solve $P\mathtt{z} = \mathtt{arg.rhs}$. $P$ is a left or right preconditioning matrix, if preconditioning is done on both sides, the product of the two preconditioner matrices should approximate $M$.

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

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

type 'd prec_setup_fn = float -> unit

Callback functions that preprocess or evaluate mass matrix-related data needed by Arkode.ARKStep.Mass.Spils.prec_solve_fn. The argument gives the independent variable t.

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

type ('d, 'k) preconditioner

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

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}M)x = P^{-1}b$ .

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

Right preconditioning. $(MP^{-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}MP_R^{-1})P_Rx = P_L^{-1}b$

Solvers

type mass_times_setup_fn = float -> unit

Callback functions that preprocess or evaluate Jacobian-related data needed by the mass_times_vec_fn. The argument gives the independent variable t.

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

type 'd mass_times_vec_fn = float -> 'd -> 'd -> unit

Callback functions that compute the mass matrix times a vector. In the call mass_times_vec_fn t v mv,

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

Neither the elements of v nor mv should be accessed after the function has returned.

val solver : ('m, 'd, 'k, [> `Iter ]) Sundials.LinearSolver.t ->
       ?mass_times_setup:mass_times_setup_fn ->
       'd mass_times_vec_fn ->
       bool ->
       ('d, 'k) preconditioner ->
       ('d, 'k) Arkode.ARKStep.Mass.solver

Create an Arkode-specific mass linear solver from a generic iterative linear solver. The boolean argument indicates whether the mass matrix depends on the independent variable t, if not it is only computed and factored once.

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

NB: The boolean argument is ignored in Config.sundials_version < 3.0.0.

Solver parameters

val set_eps_lin : ('d, 'k) Arkode.ARKStep.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).

val set_ls_norm_factor : ('d, 'k) Arkode.ARKStep.session -> float -> unit

Sets the factor for converting from the integrator tolerance (WRMS norm) to the linear solver tolerance (L2 norm). That is, $\mathit{tol}_{\mathsf{L2}} = \mathit{fact}\cdot\mathit{tol}_{\mathsf{WRMS}}$ . The given value is used directly if it is greater than zero. If it is zero (the default), then the square root of the state vector length is used. If it is less than zero, then the square root of the dot product of a state vector full of ones with itself is used.

Solver statistics

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

Returns the cumulative number of linear iterations.

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

Returns the cumulative number of linear convergence failures.

val get_num_mtsetups : ('d, 'k) Arkode.ARKStep.session -> int

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

val get_num_mass_mult : ('d, 'k) Arkode.ARKStep.session -> int

Returns the cumulative number of calls to the mass-matrix-vector product function (Arkode.ARKStep.Mass.Spils.mass_times_vec_fn).

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

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

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

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

Low-level solver manipulation

The Arkode.ARKStep.init and Arkode.ARKStep.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) Arkode.ARKStep.session ->
       ?setup:'d prec_setup_fn ->
       'd prec_solve_fn -> unit

Change the preconditioner functions.

val set_times : ('d, 'k) Arkode.ARKStep.session ->
       ?mass_times_setup:mass_times_setup_fn ->
       'd mass_times_vec_fn -> unit

Change the mass matrix-times-vector function.