Previous  Up  Next

Module Cvodes.Adjoint.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) Cvodes.Adjoint.jacobian_arg ->
       'd prec_solve_arg -> 'd -> unit

Callback functions that solve a linear system involving a preconditioner matrix without forward sensitivities. In the call prec_solve_fn jac arg z,

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_solve_fn_with_sens = (unit, 'd) Cvodes.Adjoint.jacobian_arg ->
       'd prec_solve_arg -> 'd array -> 'd -> unit

Callback functions that solve a linear system involving a preconditioner matrix with forward sensitivities. In the call prec_solve_fn jac arg s z,

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

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

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

Callback functions that preprocess or evaluate Jacobian-related data needed by Cvodes.Adjoint.Spils.prec_solve_fn without forward sensitivities. In the call prec_setup_fn jac s jok gamma,

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 prec_setup_fn_with_sens = (unit, 'd) Cvodes.Adjoint.jacobian_arg -> 'd array -> bool -> float -> bool

Callback functions that preprocess or evaluate Jacobian-related data needed by Cvodes.Adjoint.Spils.prec_solve_fn with forward sensitivities. In the call prec_setup_fn jac s jok gamma,

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) AdjointTypes.SpilsTypes.preconditioner

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

The Cvodes.Adjoint.Spils.prec_solve_fn is mandatory. The Cvodes.Adjoint.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 without forward sensitivities. $(P^{-1}A)x = P^{-1}b$ .

val prec_left_with_sens : ?setup:'d prec_setup_fn_with_sens ->
       'd prec_solve_fn_with_sens ->
       ('d, 'k) preconditioner

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

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

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

val prec_right_with_sens : ?setup:'d prec_setup_fn_with_sens ->
       'd prec_solve_fn_with_sens ->
       ('d, 'k) preconditioner

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

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

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

val prec_both_with_sens : ?setup:'d prec_setup_fn_with_sens ->
       'd prec_solve_fn_with_sens ->
       ('d, 'k) preconditioner

Left and right preconditioning without sensitivities. $(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_no_sens = (unit, 'd) Cvodes.Adjoint.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 Cvodes.Adjoint.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_setup_fn_with_sens = (unit, 'd) Cvodes.Adjoint.jacobian_arg -> 'd array -> 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 s, arg is a Cvodes.Adjoint.jacobian_arg with no work vectors and s is an array of forward sensitivity 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_no_sens = ('d, 'd) Cvodes.Adjoint.jacobian_arg -> 'd -> 'd -> unit

Callback functions that compute the Jacobian times a vector without forward sensitivities. In the call jac_times_vec_fn arg v jv,

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.

type 'd jac_times_vec_fn_with_sens = ('d, 'd) Cvodes.Adjoint.jacobian_arg -> 'd array -> 'd -> 'd -> unit

Callback functions that compute the Jacobian times a vector with forward sensitivities. In the call jac_times_vec_fn arg s v jv,

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

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

type 'd jac_times_vec_fn =
| NoSens of 'd jac_times_setup_fn_no_sens option
* 'd jac_times_vec_fn_no_sens		 (*

Does not depend on forward sensitivities.

*)
| WithSens of 'd jac_times_setup_fn_with_sens option
* 'd jac_times_vec_fn_with_sens		 (*

Depends on forward sensitivities.

*)

Callback functions that compute the Jacobian times a vector.

val solver : ('m, 'd, 'k, 'f) Sundials.LinearSolver.t ->
       ?jac_times_vec:'d jac_times_vec_fn ->
       ?jac_times_rhs:'d Cvode.rhsfn ->
       ('d, 'k) preconditioner ->
       ('d, 'k) Cvodes.Adjoint.linear_solver

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

The jac_times_rhs argument specifies an alternative right-hand-side 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: the jac_times_setup argument is not supported in Config.sundials_version < 3.0.0.

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

Solver parameters

val set_jac_eval_frequency : ('d, 'k) Cvodes.Adjoint.bsession -> int -> unit

Sets the maximum number of time steps to wait before recomputation of the Jacobian or recommendation to update the preconditioner. If the integer argument is less than or equal to 0, a default value of 50 is used.

val set_lsetup_frequency : ('d, 'k) Cvodes.Adjoint.bsession -> int -> unit

Specifies the frequency of calls to the linear solver setup routine. Positive values specify the number of time steps between setup calls, negative values force recomputation at each Newton step, and zero values reset to the default (20).

val set_eps_lin : ('d, 'k) Cvodes.Adjoint.bsession -> 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) Cvodes.Adjoint.bsession -> 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.

val set_linear_solution_scaling : ('d, 'k) Cvodes.Adjoint.bsession -> bool -> unit

Enables or disables scaling of the linear system solution to account for a change in $\gamma$ in the linear system. Linear solution scaling is enabled by default when a matrix-based linear solver is attached.

Solver statistics

val get_work_space : ('d, 'k) Cvodes.Adjoint.bsession -> int * int

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

val get_num_lin_iters : ('d, 'k) Cvodes.Adjoint.bsession -> int

Returns the cumulative number of linear iterations.

val get_num_lin_conv_fails : ('d, 'k) Cvodes.Adjoint.bsession -> int

Returns the cumulative number of linear convergence failures.

val get_num_prec_evals : ('d, 'k) Cvodes.Adjoint.bsession -> int

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

val get_num_prec_solves : ('d, 'k) Cvodes.Adjoint.bsession -> int

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

val get_num_jtsetup_evals : ('d, 'k) Cvodes.Adjoint.bsession -> int

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

val get_num_jtimes_evals : ('d, 'k) Cvodes.Adjoint.bsession -> int

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

val get_num_lin_rhs_evals : ('d, 'k) Cvodes.Adjoint.bsession -> 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 Cvodes.Adjoint.init and Cvodes.Adjoint.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) Cvodes.Adjoint.bsession ->
       ?setup:'d prec_setup_fn ->
       'd prec_solve_fn -> unit

Change the preconditioner functions without using forward sensitivities.

val set_preconditioner_with_sens : ('d, 'k) Cvodes.Adjoint.bsession ->
       ?setup:'d prec_setup_fn_with_sens ->
       'd prec_solve_fn_with_sens -> unit

Change the preconditioner functions using forward sensitivities.

val set_jac_times : ('d, 'k) Cvodes.Adjoint.bsession ->
       'd jac_times_vec_fn -> unit

Change the Jacobian-times-vector function.

val clear_jac_times : ('d, 'k) Cvodes.Adjoint.bsession -> unit

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