Previous  Up  Next

Module Sundials_NonlinearSolver

module Sundials_NonlinearSolver: sig .. end

Generic nonlinear solvers.

Sundials provides generic nonlinear solvers of two main types: Sundials_NonlinearSolver.Newton and Sundials_NonlinearSolver.FixedPoint. An instance of a nonlinear solver may only be associated with at most one integrator session at a time.

This module supports calling both Sundials and custom OCaml nonlinear solvers from both Sundials integrators and OCaml applications.

This documentation is structured as follows.

  1. Core functions
  2. Set functions
  3. Get functions
  4. Nonlinear Solver Implementations
  5. Exceptions
type ('data, 'kind, 's, 'v) t = ('data, 'kind, 's, 'v) nonlinear_solver

A generic nonlinear solver. The type variables specify

module Senswrapper: sig .. end

A limited interface to arrays of Nvector.nvectors required to apply nonlinear solvers to sensitivity problems.

Core functions

type nonlinear_solver_type =
| RootFind (*

Solves $F(y) = 0$

*)
| FixedPoint (*

Solves $G(y) = y$

*)

The problem specification expected by a nonlinear solver.

val get_type : ('d, 'k, 's, 'v) t ->
       nonlinear_solver_type

Returns the type of a nonlinear solver.

val init : ('d, 'k, 's, 'v) t -> unit

Initializes a nonlinear solver.

val setup : ('d, 'k, 's, [ `Nvec ]) t ->
       y:('d, 'k) Nvector.t -> 's -> unit

Setup a nonlinear solver with an initial iteration value.

val solve : ('d, 'k, 's, [ `Nvec ]) t ->
       y0:('d, 'k) Nvector.t ->
       ycor:('d, 'k) Nvector.t ->
       w:('d, 'k) Nvector.t -> float -> bool -> 's -> unit

Solves a nonlinear system. The call solve ls ~y0 ~y ~w tol callLSetup s solves the nonlinear system $F(y) = 0$ or $G(y) = y$ , given the following arguments.

Set functions

type ('nv, 's) sysfn = 'nv -> 'nv -> 's -> unit

A function sysfn y fg mem to evaluate the nonlinear system $F(y)$ (for RootFind) or $G(y)$ (for FixedPoint). The contents of y must not be modified.

This function raises Sundials.RecoverableFailure to indicate a recoverable failure. Other exceptions signal unrecoverable failures.

val set_sys_fn : ('d, 'k, 's, [ `Nvec ]) t ->
       ('d, 's) sysfn -> unit

Specify a system function callback. The system function specifies the problem, either $F(y)$ or $G(y)$ .

type 's lsetupfn = bool -> 's -> bool

A function to setup linear solves. For direct linear solvers, sets up the system $Ax = b$ where $A = \frac{\partial F}{\partial y}$ is the linearization of the nonlinear residual function $F(y) = 0$ . For iterative linear solvers, calls a preconditioner setup function.

The call jcur = lsetupfn jbad mem has as arguments jbad, which indicates if the solver believes that $A$ has gone stale, and mem, a token passed by the function provider. A true return value (jcur) signals that the Jacobian $A$ has been updated.

This function raises Sundials.RecoverableFailure to indicate a recoverable failure. Other exceptions signal unrecoverable failures.

val set_lsetup_fn : ('d, 'k, 's, 'v) t ->
       's lsetupfn -> unit

Specify a linear solver setup callback.

type ('nv, 's) lsolvefn = 'nv -> 's -> unit

A function to solve linear systems. Solves the system $Ax = b$ where $A = \frac{\partial F}{\partial y}$ is the linearization of the nonlinear residual function $F(y)= 0$ .

The call lsolvefn b mem has as arguments

This function raises Sundials.RecoverableFailure to indicate a recoverable failure. Other exceptions signal unrecoverable failures.

val set_lsolve_fn : ('d, 'k, 's, [ `Nvec ]) t ->
       ('d, 's) lsolvefn -> unit

Specify a linear solver callback.

type convtest =
| Success (*

Converged (SUN_NLS_SUCCESS)

*)
| Continue (*

Not converged, keep iterating (SUN_NLS_CONTINUE)

*)
| Recover (*

Appears to diverge, try to recover (SUN_NLS_CONV_RECVR)

*)

Values returned by convergence tests.

type ('nv, 's) convtestfn' = 'nv -> 'nv -> float -> 'nv -> 's -> convtest

A function providing a convergence test. The call convtestfn y del tol ewt mem has as arguments

type 's convtest_callback = {
   f : 'd1 'k1 't2 'd2 'k2.
('d1, 'k1, 't2, [ `Nvec ]) t ->
(('d2, 'k2) Nvector.t, 's) convtestfn';
}

A convergence test callback provided by an integrator. Such callbacks require an additional first argument, the nonlinear solver invoking the function, and otherwise expect nvector arguments. They access the linear solver and nvector arguments using generic functions, which is why the type variables are universally quantified.

type 's convtest_callback_sens = {
   f : 'd1 'k1 't2 'd2 'k2.
('d1, 'k1, 't2, [ `Sens ]) t ->
(('d2, 'k2) Senswrapper.t, 's)
convtestfn';
}

A convergence test callback provided by an integrator with sensitivities. Such callbacks require an additional first argument, the nonlinear solver invoking the function, and otherwise expect senswrapper arguments. They access the linear solver and senswrapper arguments using generic functions, which is why the type variables are universally quantified.

type ('nv, 's, 'v) convtestfn =
| CConvTest : 's0 convtest_callback Sundials.cfun -> ('nv0, 's0, [ `Nvec ]) convtestfn
| CSensConvTest : 's1 convtest_callback_sens Sundials.cfun -> ('nv1, 's1, [ `Sens ]) convtestfn
| OConvTest of ('nv, 's) convtestfn'

A convergence test provided either by an integrator or a user program. The OCaml interface distinguishes callback functions set by the underlying library (CConvTest) from those supplied by user programs (OConvTest). This reflects the different underlying mechanisms used to create and invoke such functions. Callback functions provied by the underlying library can be invoked with any kind of linear solver and (homogeneous) nvectors since they manipulate these values generically.

val assert_not_oconvtestfn : ('nv1, 's, [ `Nvec ]) convtestfn ->
       ('nv2, 's, [ `Nvec ]) convtestfn

Ignore the nvector type argument in a convtestfn.

val set_convtest_fn : ('d, 'k, 's, [ `Nvec ]) t ->
       ('d, 's, [ `Nvec ]) convtestfn -> unit

Specify a convergence test callback for the nonlinear solver iteration.

module Sens: sig .. end

Support for nonlinear solvers with sensitivities.

val set_max_iters : ('d, 'k, 's, 'v) t -> int -> unit

Sets the maximum number of nonlinear solver iterations.

val set_info_file : ('d, 'k, 's, 'v) t ->
       ?print_level:bool -> Sundials.Logfile.t -> unit

Sets the output file for informative (non-error) messages. The default is to send such messages to stdout. The optional argument is a convenience for invoking Sundials_NonlinearSolver.set_print_level.

Sundials must be built with (SUNDIALS_BUILD_WITH_MONITORING) to use this function.

val set_print_level : ('d, 'k, 's, 'v) t -> bool -> unit

Sets the level of output verbosity. When false (the default) no information is printed, when true the residual norm is printed for each nonlinear iteration.

Sundials must be built with (SUNDIALS_BUILD_WITH_MONITORING) to use this function.

Get functions

val get_num_iters : ('d, 'k, 's, 'v) t -> int

Returns the number of nonlinear solver iterations in the most recent solve.

val get_cur_iter : ('d, 'k, 's, 'v) t -> int

Returns the iteration index of the current nonlinear solve.

val get_num_conv_fails : ('d, 'k, 's, 'v) t -> int

Returns the number of nonlinear solver convergence failures in the most recent solve.

Nonlinear Solver Implementations

module Newton: sig .. end

Generic nonlinear solver based on Newton's method.

module FixedPoint: sig .. end

Generic nonlinear solver for fixed-point (functional) iteration with optional Anderson acceleration.

module Custom: sig .. end

Custom nonlinear solvers.

Exceptions

exception VectorOpError

An error occurred in a vector operation.

exception IncorrectUse

Raised when a nonlinear solver is used incorrectly. For example, calling Sundials_NonlinearSolver.solve without having first called Sundials_NonlinearSolver.set_sys_fn (SUN_NLS_MEM_NULL).

exception ExtFail

Raised if an external library call fails.

exception NonlinearSolverInUse

Raised on an attempt to associate a nonlinear solver instance with more than one session.