module Spils:sig..end
Scaled Preconditioned Iterative Linear Solvers
include Sundials_LinearSolver.Iterative
type'dprec_solve_fn =(unit, 'd) Idas.Adjoint.jacobian_arg -> 'd -> 'd -> float -> unit
Callback functions that solve a linear system involving a
preconditioner matrix without forward sensitivities.
In the call prec_solve_fn jac r z delta,
jac is a Idas.Adjoint.jacobian_arg with no work vectors,r is the right-hand side vector,z is computed to solve $Pz = r$, anddelta 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
Idas.Adjoint.get_err_weights.Raising Sundials.RecoverableFailure indicates a recoverable
error. Any other exception is treated as an unrecoverable error.
jac, r, and z should not
be accessed after the function has returned.type'dprec_solve_fn_with_sens =(unit, 'd) Idas.Adjoint.jacobian_arg ->
'd array -> 'd array -> 'd -> 'd -> float -> unit
Callback functions that solve a linear system involving a
preconditioner matrix with forward sensitivities.
In the call prec_solve_fn jac ys yps r z delta,
jac is a Idas.Adjoint.jacobian_arg with no work vectors,ys contains the sensitivities of the forward solution,yps contains the derivatives of the forward solution
sensitivities,r is the right-hand side vector,z is computed to solve $Pz = r$, anddelta 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
Idas.Adjoint.get_err_weights.Raising Sundials.RecoverableFailure indicates a recoverable
error. Any other exception is treated as an unrecoverable error.
jac, ys, yps, r, and z should not
be accessed after the function has returned.type'dprec_setup_fn =(unit, 'd) Idas.Adjoint.jacobian_arg -> unit
Callback functions that preprocess or evaluate Jacobian-related data
need by Idas.Adjoint.Spils.prec_solve_fn without forward sensitivities.
The only argument is a Idas.Adjoint.jacobian_arg with no work vectors.
Raising Sundials.RecoverableFailure indicates a recoverable
error. Any other exception is treated as an unrecoverable error.
type'dprec_setup_fn_with_sens =(unit, 'd) Idas.Adjoint.jacobian_arg -> 'd array -> 'd array -> unit
Callback functions that preprocess or evaluate Jacobian-related data
need by Idas.Adjoint.Spils.prec_solve_fn with forward sensitivities.
In the call prec_setup_fn jac ys yps,
jac is a Idas.Adjoint.jacobian_arg with no work vectors,ys contains the sensitivities of the forward solution, andyps contains the derivatives of the forward solution
sensitivities.Raising Sundials.RecoverableFailure indicates a recoverable
error. Any other exception is treated as an unrecoverable error.
type('d, 'k)preconditioner =('d, 'k) AdjointTypes.SpilsTypes.preconditioner
Specifies a preconditioner and its callback functions.
The following functions and those in Idas_bbd construct
preconditioners.
The Idas.Adjoint.Spils.prec_solve_fn is mandatory. The Idas.Adjoint.Spils.prec_setup_fn can be
omitted if not needed.
val prec_none : ('d, 'k) preconditionerNo preconditioning.
val prec_left : ?setup:'d prec_setup_fn ->
'd prec_solve_fn ->
('d, 'k) preconditionerLeft preconditioning without forward sensitivities. $Pz = r$, where $P$ approximates, perhaps crudely, $J = \frac{\partial F}{\partial y} + c_j\frac{\partial F}{\partial\dot{y}}$.
val prec_left_with_sens : ?setup:'d prec_setup_fn_with_sens ->
'd prec_solve_fn_with_sens ->
('d, 'k) preconditionerLeft preconditioning with forward sensitivities. $Pz = r$, where $P$ approximates, perhaps crudely, $J = \frac{\partial F}{\partial y} + c_j\frac{\partial F}{\partial\dot{y}}$.
type'djac_times_setup_fn_no_sens =(unit, 'd) Idas.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 Idas.Adjoint.jacobian_arg with no
work vectors.
Raising Sundials.RecoverableFailure indicates a recoverable
error. Any other exception is treated as an unrecoverable error.
arg should not be accessed after the
function has returned.type'djac_times_setup_fn_with_sens =(unit, 'd) Idas.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 Idas.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.
arg should not be accessed after the
function has returned.type'djac_times_vec_fn_no_sens =('d, 'd) Idas.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,
arg is a Idas.Adjoint.jacobian_arg with two work vectors,v is the vector multiplying the Jacobian, andjv 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.
arg nor v or jv should be
accessed after the function has returned.type'djac_times_vec_fn_with_sens =('d, 'd) Idas.Adjoint.jacobian_arg ->
'd array -> '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 ys yps v jv,
arg is a Idas.Adjoint.jacobian_arg with two work vectors,ys contains the sensitivities of the forward solution,yps contains the derivatives of the forward solution
sensitivities.v is the vector multiplying the Jacobian, andjv 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.
arg, ys, yps, v nor jv
should be accessed after the function has returned.type 'd jac_times_vec_fn =
| |
NoSens of |
(* | Does not depend on forward sensitivities. | *) |
| |
WithSens of |
(* | Depends on forward sensitivities. | *) |
Callback functions that compute the Jacobian times a vector.
Depends on forward sensitivities.
val solver : ('m, 'd, 'k, 'f) Sundials.LinearSolver.t ->
?jac_times_vec:'d jac_times_vec_fn ->
?jac_times_res:'d Ida.resfn ->
('d, 'k) preconditioner ->
('d, 'k) Idas.Adjoint.linear_solverCreate a Idas-specific linear solver from a generic iterative linear solver.
The jac_times_res argument specifies an alternative DAE residual
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.
val set_eps_lin : ('d, 'k) Idas.Adjoint.bsession -> float -> unitSets 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) Idas.Adjoint.bsession -> float -> unitSets 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) Idas.Adjoint.bsession -> bool -> unitEnables 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.
val set_increment_factor : ('d, 'k) Idas.Adjoint.bsession -> float -> unitSets the increment factor (dqincfac) to use in the difference-quotient
approximation for the backward problem.
val get_work_space : ('d, 'k) Idas.Adjoint.bsession -> int * intReturns the sizes of the real and integer workspaces used by the linear solver.
real_size, integer_size)val get_num_lin_iters : ('d, 'k) Idas.Adjoint.bsession -> intReturns the cumulative number of linear iterations.
val get_num_lin_conv_fails : ('d, 'k) Idas.Adjoint.bsession -> intReturns the cumulative number of linear convergence failures.
val get_num_prec_evals : ('d, 'k) Idas.Adjoint.bsession -> intReturns the number of calls to the setup function.
val get_num_prec_solves : ('d, 'k) Idas.Adjoint.bsession -> intReturns the cumulative number of calls to the preconditioner solve function.
val get_num_jtsetup_evals : ('d, 'k) Idas.Adjoint.bsession -> intReturns the cumulative number of calls to the Jacobian-vector setup function.
val get_num_jtimes_evals : ('d, 'k) Idas.Adjoint.bsession -> intReturns the cumulative number of calls to the Jacobian-vector function.
val get_num_lin_res_evals : ('d, 'k) Idas.Adjoint.bsession -> intReturns 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.
The Idas.Adjoint.init and Idas.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) Idas.Adjoint.bsession ->
?setup:'d prec_setup_fn ->
'd prec_solve_fn -> unitChange the preconditioner functions without using forward sensitivities.
val set_preconditioner_with_sens : ('d, 'k) Idas.Adjoint.bsession ->
?setup:'d prec_setup_fn_with_sens ->
'd prec_solve_fn_with_sens -> unitChange the preconditioner functions using forward sensitivities.
val set_jac_times : ('d, 'k) Idas.Adjoint.bsession ->
'd jac_times_vec_fn -> unitChange the Jacobian-times-vector function.
val clear_jac_times : ('d, 'k) Idas.Adjoint.bsession -> unitRemove a Jacobian-times-vector function and use the default implementation.