Previous  Up  

Module Sundials_LinearSolver.Custom

module Custom: sig .. end

Custom linear solvers.

type ('data, 'kind) atimesfn = ('data, 'kind) Nvector.t -> ('data, 'kind) Nvector.t -> unit

A function atimesfn v z computes the action of the system matrix on the vector v, storing the result in z. The matrix is represented implicitly by the effect of the function.

If a problem occurs the function raises Sundials_LinearSolver.ATimesFailure.

type psetupfn = unit -> unit

Functions that set up any problem data in preparation for calls to psolvefn.

If a problem occurs the function raises Sundials_LinearSolver.PSetFailure.

type ('data, 'kind) psolvefn = ('data, 'kind) Nvector.t -> ('data, 'kind) Nvector.t -> float -> bool -> unit

A function psolvefn r z tol lr that solves the preconditioner equation $Pz = r$ for the vector z such that $\left\lVert Pz - r \right\rVert_\mathrm{wrms} < \mathit{tol}$ . If lr is true then $P$ should be treated as a left preconditioner and otherwise as a right preconditioner.

If a problem occurs the function raises Sundials_LinearSolver.PSolveFailure.

type ('matrix, 'data, 'kind, 'lsolver) ops = {
   solver_type : Sundials_LinearSolver.linear_solver_type; (*

Broadly classifies the operations provided by a linear solver and its operating principle.

*)
   solver_id : Sundials_LinearSolver.linear_solver_id; (*

Identifies the linear solver. This value should normally be set to Custom.

*)
   init : ('lsolver -> unit) option; (*

Performs linear solver initalization.

*)
   setup : ('lsolver -> 'matrix -> unit) option; (*

Performs linear solver setup.

*)
   solve : 'lsolver -> 'matrix -> 'data -> 'data -> float -> unit; (*

The call solve ls a x b tol should solve the linear system $Ax = b$ .

Direct solvers can ignore tol. Matrix-free solvers can ignore a (relying instead on the atimes function). Iterative solvesr should attempt to solve to within the weighted 2-norm tolerance, tol.

*)
   set_atimes : ('lsolver -> ('data, 'kind) atimesfn -> unit)
option;		 (*

Provides the linear solver with a problem-specific Sundials_LinearSolver.Custom.atimesfn. The given function may only be used within init, setup, and solve.

*)
   set_preconditioner : ('lsolver ->
psetupfn option ->
('data, 'kind) psolvefn option -> unit)
option;		 (*

Provides the linear solver with preconditioner routines. The given functions may only be used within init, setup, and solve.

*)
   set_scaling_vectors : ('lsolver -> 'data option -> 'data option -> unit) option; (*

Passes the left/right scaling vectors for use in solve. The call set_scaling_vectors ls s1 s2 provides diagonal matrices of scale factors for solving the system $\tilde{A}\tilde{x} = \tilde{b}$ where $\tilde{A} = S_1 P_1^{-1} A P_2^{-1} S_2^{-1}$ , $\tilde{b} = S_1 P_1^{-1} b$ , and $\tilde{x} = S_2 P_2 x$ . A None argument indicates an identity scaling matrix.

*)
   set_zero_guess : ('lsolver -> bool -> unit) option; (*

Used to indicate whether the next call to the solve function will be made with a zero initial guess.

*)
   get_num_iters : ('lsolver -> int) option; (*

The number of linear iterations performed in the last solve call.

*)
   get_res_norm : ('lsolver -> float) option; (*

The final residual norm from the last solve call.

*)
   get_res_id : ('lsolver -> ('data, 'kind) Nvector.t) option; (*

The preconditioned initial residual vector. This vector may be requested if the iterative method computes the preconditioned initial residual and returns from solve successfully without performing any iterations (i.e., either the initial guess or the preconditioner is sufficiently accurate).

*)
   get_last_flag : ('lsolver -> int) option; (*

Use to indicate the last error encountered by the linear solver.

*)
   get_work_space : ('lsolver -> int * int) option; (*

Return the storage requirements for the linear solver. The result (lrw, liw) gives the number of words used for storing real values (lrw) and the number of words used for storing integer values (liw).

*)
   set_prec_type : ('lsolver -> Sundials_LinearSolver.Iterative.preconditioning_type -> unit)
option;		 (*

Called by Iterative.set_prec_type and when a linear solver is associated with an integrator.

*)
}

The operations required to implement an iterative linear solver. Failure should be indicated by raising an exception (preferably one of the exceptions in this package). Raising Sundials.RecoverableFailure indicates a generic recoverable failure.

val make_ops : ?solver_id:Sundials_LinearSolver.linear_solver_id ->
       ?init:('lsolver -> unit) ->
       ?setup:('lsolver -> 'matrix -> unit) ->
       ?set_atimes:('lsolver ->
                    ('data, 'kind) atimesfn -> unit) ->
       ?set_preconditioner:('lsolver ->
                            psetupfn option ->
                            ('data, 'kind) psolvefn
                            option -> unit) ->
       ?set_scaling_vectors:('lsolver -> 'data option -> 'data option -> unit) ->
       ?set_zero_guess:('lsolver -> bool -> unit) ->
       ?get_num_iters:('lsolver -> int) ->
       ?get_res_norm:('lsolver -> float) ->
       ?get_res_id:('lsolver -> ('data, 'kind) Nvector.t) ->
       ?get_last_flag:('lsolver -> int) ->
       ?get_work_space:('lsolver -> int * int) ->
       ?set_prec_type:('lsolver ->
                       Sundials_LinearSolver.Iterative.preconditioning_type -> unit) ->
       solver_type:Sundials_LinearSolver.linear_solver_type ->
       solve:('lsolver -> 'matrix -> 'data -> 'data -> float -> unit) ->
       unit -> ('matrix, 'data, 'kind, 'lsolver) ops

Convenience function for constructing a Sundials_LinearSolver.Custom.ops value.

val make_with_matrix : ('matrix, 'data, 'kind, 'lsolver) ops ->
       ?context:Sundials.Context.t ->
       'lsolver ->
       ('matrixkind, 'matrix, 'data, 'kind) Sundials.Matrix.t ->
       ('matrix, 'data, 'kind, [ `Custom of 'lsolver | `Dls | `Iter ])
       Sundials_LinearSolver.t

Create a linear solver given a set of operations and an internal state. The resulting solver is tagged with both `Dls and `Iter, although its suitability depends on which operations are defined. Use a type cast to filter inappropriate tags.

The solver_type may not be MatrixEmbedded.

NB: This feature is only available for Config.sundials_version >= 3.0.0.

val make_without_matrix : (unit, 'data, 'kind, 'lsolver) ops ->
       ?context:Sundials.Context.t ->
       'lsolver ->
       (unit, 'data, 'kind, [ `Custom of 'lsolver | `Iter | `MatE ])
       Sundials_LinearSolver.t

Create a linear solver given a set of operations and an internal state. The resulting solver is tagged with both `Dls and `Iter, although its suitability depends on which operations are defined. Use a type cast to filter inappropriate tags.

The solver_type may not be Direct.

This feature is only available for Config.sundials_version >= 3.0.0.

The MatrixEmbedded solver_type is only available for Config.sundials_version >= 5.8.0.

val unwrap : ('m, 'data, 'kind, [> `Custom of 'lsolver ]) Sundials_LinearSolver.t ->
       'lsolver

Return the internal state from an custom iterative linear solver.

Wrapper for making custom Direct linear solvers.

type ('matrix, 'data, 'kind, 'lsolver) dls_ops = {
   init : ('lsolver -> unit) option; (*

Performs linear solver initalization.

*)
   setup : ('lsolver -> 'matrix -> unit) option; (*

Performs linear solver setup based on an updated matrix.

*)
   solve : 'lsolver -> 'matrix -> 'data -> 'data -> float -> unit; (*

The call solve ls A x b tols should solve the linear system $Ax = b$ to the requested tolerance.

*)
   space : ('lsolver -> int * int) option; (*

Return the storage requirements for the linear solver. The result (lrw, liw) gives the number of words used for storing real values (lrw) and the number of words used for storing integer values (liw).

*)
}

The operations required to implement a direct linear solver. Failure should be indicated by raising an exception (preferably one of the exceptions in this package). Raising Sundials.RecoverableFailure indicates a generic recoverable failure.

val make_dls : ('matrix, 'data, 'kind, 'lsolver) dls_ops ->
       ?context:Sundials.Context.t ->
       'lsolver ->
       ('matrixkind, 'matrix, 'data, 'kind) Sundials.Matrix.t ->
       ('matrix, 'data, 'kind, [ `Custom of 'lsolver | `Dls ])
       Sundials_LinearSolver.t

Create a direct linear solver given a set of operations and an internal state.

NB: This feature is only available for Config.sundials_version >= 3.0.0.