module Spils:`sig`

..`end`

Scaled Preconditioned Iterative Linear Solvers.

`include Sundials_LinearSolver.Iterative`

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.- See Sundials: IDALsPrecSolveFn

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.

- See Sundials: IDALsPrecSetupFn

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.

- See Sundials: IDASetPreconditioner
- See Sundials: IDALsPrecSolveFn
- See Sundials: IDALsPrecSetupFn

`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}}$.

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.- See Sundials: IDALsJacTimesSetupFn

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}$.

`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.- See Sundials: IDALsJacTimesVecFn

`val solver : ``('m, 'd, 'k, [> `Iter ]) Sundials.LinearSolver.t ->`

?jac_times_vec:'d jac_times_setup_fn option *

'd jac_times_vec_fn ->

?jac_times_res:'d Ida.resfn ->

('d, 'k) preconditioner -> ('d, 'k) Ida.linear_solver

Create an Ida-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: a `jac_times_setup_fn`

is not supported in
Config.sundials_version < 3.0.0.

NB: a `jac_times_res`

function is not supported in
Config.sundials_version < 5.3.0.

- See Sundials: IDASetLinearSolver
- See Sundials: IDASetJacTimes
- See Sundials: IDASetJacTimesResFn

`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).

- See Sundials: IDASetEpsLin

`val set_ls_norm_factor : ``('d, 'k) Ida.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.

**Since**5.4.0- See Sundials: IDASetLSNormFactor

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

**Since**5.2.0- See Sundials: IDASetLinearSolutionScaling

`val set_increment_factor : ``('d, 'k) Ida.session -> float -> unit`

Sets the increment factor (`dqincfac`

) to use in the difference-quotient
approximation.

Specifically, the product $Jv$ is approximated by $Jv = \frac{1}{\sigma}\left( F(t, \tilde{y}, \tilde{y}') - F(t, y, y') \right)$ . where $\tilde{y} = y + \sigma v$ , $\tilde{y}' = y' + c_j \sigma v$ , $c_j$ is a BDF parameter proportional to the step size, $\sigma = \sqrt{N} \mathtt{dqincfac}$ , and $N$ is the number of equations in the DAE system.

- See Sundials: IDASetIncrementFactor

`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.

**Returns**(`real_size`

,`integer_size`

)- See Sundials: IDAGetLinWorkSpace

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

Returns the cumulative number of linear iterations.

- See Sundials: IDAGetNumLinIters

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

Returns the cumulative number of linear convergence failures.

- See Sundials: IDAGetNumLinConvFails

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

Returns the number of calls to the setup function.

- See Sundials: IDAGetNumPrecEvals

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

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

- See Sundials: IDAGetNumPrecSolves

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

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

**Since**3.0.0- See Sundials: IDAGetNumJTSetupEvals

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

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

- See Sundials: IDAGetNumJtimesEvals

`val get_num_lin_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.

- See Sundials: IDAGetNumLinResEvals

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.

- See Sundials: IDASetPreconditioner
- See Sundials: IDALsPrecSolveFn
- See Sundials: IDALsPrecSetupFn

`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.

- See Sundials: IDASetJacTimes
- See Sundials: IDALsJacTimesVecFn

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

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

- See Sundials: IDASetJacTimes
- See Sundials: IDAJacTimesVecFn