Module Kinsol

A session with the KINSOL solver.

An example session with Kinsol (kinsol_skel.ml):

open Sundials

(* 1. Define a system function. *)
let pi, e = 4. *. atan 1., exp 1.
let sysf u r =
  r.{0} <- 0.5 *. sin(u.{0}*.u.{1}) -. 0.25 *. u.{1} /. pi -. 0.5 *. u.{0};
  r.{1} <- (1. -. 0.25/.pi)*.(exp(2.*.u.{0})-.e) +. e*.u.{1}/.pi -. 2.*.e*.u.{0};
  r.{2} <- u.{2} -. u.{0} +. 0.25;
  r.{3} <- u.{3} -. u.{0} +. 1.0;
  r.{4} <- u.{4} -. u.{1} +. 1.5;
  r.{5} <- u.{5} -. u.{1} +. 2.0 *. pi

(* 2. Set vector with initial guess.
      The length of this vector determines the problem size. *)
let ud = RealArray.of_list [ 0.25; 1.5; 0.; -0.75; 0.; 1.5 -. 2. *.pi ]
let u = Nvector_serial.wrap ud

(* 3. Create and initialize a solver session.
      This will initialize a specific linear solver. *)
let m = Matrix.dense 6
let s = Kinsol.(init ~lsolver:(Dls.(solver (dense u m))) sysf u);;

(* 4. Set optional inputs, e.g.,
      call [set_*] functions to change solver parameters. *)
let c = RealArray.of_list [
   Constraint.unconstrained;
   Constraint.unconstrained;
   Constraint.geq_zero;
   Constraint.leq_zero;
   Constraint.geq_zero;
   Constraint.leq_zero ] in
Kinsol.set_constraints s (Nvector_serial.wrap c);
Kinsol.set_func_norm_tol s 1.0e-5;
Kinsol.set_scaled_step_tol s 1.0e-5;
Kinsol.set_max_setup_calls s 1;;

(* 5. Solve the problem. *)
let snv = Nvector_serial.make (RealArray.length ud) 1.0 in
ignore (Kinsol.(solve s u Newton snv snv));

Printf.printf "%8.5g %8.6g\n" ud.{0} ud.{1};;

(* 6. Get optional outputs,
      call the [get_*] functions to examine solver statistics. *)
let fnorm = Kinsol.get_func_norm s;;
    

Alias for sessions based on serial nvectors.

Linear solvers used by Kinsol.

Alias for linear solvers that are restricted to serial nvectors.

Workspaces with two temporary vectors.

Arguments common to Jacobian callback functions.

System function that defines nonlinear problem. The call sysfun u fval must calculate $F(u)$ into fval using the current value vector u.

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

Create a Kinsol-specific linear solver from a generic matrix embedded solver.

Orthogonalization routines of the QR factorization portion of Anderson acceleration.

Creates and initializes a session with the Kinsol solver. The call init ~max_lin_iters:mli ~maa:maa ~linsolv:ls f tmpl has as arguments:

• mli, the maximum number of nonlinear iterations allowed,
• maa, the size of the Anderson acceleration subspace for the Picard and FixedPoint strategies,
• orthaa, specifies the othogonalization routine to be used in the QR factorization portion of Anderson acceleration,
• ls, the linear solver to use (required for the Newton, LineSearch, and Picard strategies),
• f, the system function of the nonlinear problem, and,
• tmpl a template to initialize the session (e.g., the initial guess vector).

By default, the session is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

The orthaa argument is ignored in Sundials < 6.0.0.

Strategy used to solve the nonlinear system.

Results of nonlinear solution attempts.

Computes an approximate solution to a nonlinear system. The call solve s u strategy u_scale f_scale has arguments:

• s, a solver session,
• u, an initial guess that is replaced with an approximate solution for $F(u) = 0$,
• strategy, strategy used to solve the nonlinear system,
• u_scale, the diagonal elements of the scaling matrix $D_u$ for vector u chosen so that all $D_u u$ all have roughly the same magnitude when u is close to a root of $F(u)$, and,
• f_scale, the diagonal elements of the scaling matrix $D_f$ for $F(u)$ chosen so that all $D_f F(u)$ have roughtly the same magnitude when u is not near a root of $F(u)$.

The function either returns a Kinsol.result or raises one of the exceptions listed below.

Specifies that an initial call to the preconditioner setup function should not be made. This feature is useful when solving a sequence of problems where the final preconditioner values of one problem become the initial values for the next problem.

Specifies that an initial call to the preconditioner setup function should be made (the default).

Disables the nonlinear residual monitoring scheme that controls Jacobian updating. It only has an effect for the Dense and Band solvers.

Enables the nonlinear residual monitoring scheme that controls Jacobian updating. It only has an effect for the Dense and Band solvers.

Specifies the maximum number of nonlinear iterations between calls to the preconditioner setup function. Pass 0 to set the default (10).

Specifies the maximum number of nonlinear iterations between checks by the residual monitoring algorithm. Pass 0 to set the default (5). It only affects the Dense and Band solvers.

The parameters gamma and alpha in the formula for the Eisenstat and Walker Choice 2 for eta. Set either to None to specify its default value. The legal values are $0 < \mathtt{egamma} \leq 1.0 \wedge 1 < \mathtt{ealpha} \leq 2.0$.

The eta parameter in the stopping criteria for the linear system solver.

Specifies the method for computing the value of the eta coefficient used in the calculation of the linear solver convergence tolerance.

Specifies the constant value of omega when using residual monitoring. Pass 0.0 to specify the default value (0.9). The legal values are $0 < \mathtt{omega} < 1.0 $.

Specifies the minimum and maximum values in the formula for omega. The legal values are $0 < \mathtt{omegamin} < \mathtt{omegamax} < 1.0$.

Specifies that the scaled linear residual tolerance (epsilon) is not bounded from below.

Specifies that the scaled linear residual tolerance (epsilon) is bounded from below. That is, the positive minimum value $0.01\mathtt{fnormtol}$ is applied to epsilon.

Specifies the maximum allowable scaled length of the Newton step. Pass 0.0 to specify the default value $1000\lVert u_0 \rVert_{D_u}$, otherwise the given value must be greater than zero.

Specifies the maximum number of beta-condition failures in the line search algorithm. Pass 0.0 to specify the default (10).

Specifies the relative error in computing $F(u)$, which is used in the difference quotient approximation of the Jacobian-vector product. Pass 0.0 to specify the default value ($\sqrt{\mathtt{unit\_roundoff}}$).

Specifies the stopping tolerance on the scaled maximum norm. It must be greater than zero. Pass 0.0 to specify the default value ($\mathtt{unit\_roundoff}^\frac{1}{3}$).

Specifies the stopping tolerance on the minimum scaled step length, which must be greater than zero. Pass 0.0 to specify the default value ($\mathtt{unit\_roundoff}^\frac{1}{3}$).

Specifies a vector defining inequality constraints for each component of the solution vector u. See Sundials.Constraint.

Changes the system function. Allows solutions of several problems of the same size but with different functions.

Configure the default error handler to write messages to a file. By default it writes to Logfile.stderr.

Specifies a custom function for handling error messages. The handler must not fail: any exceptions are trapped and discarded.

Restores the default error handling function.

Increasing levels of verbosity for informational messages.

Sets the level of verbosity of informational messages.

Write informational (non-error) messages to the given file. By default they are written to Logfile.stdout. The optional argument is a convenience for invoking Kinsol.set_print_level.

Specifies a custom function for handling informational (non-error) messages. The error_code field of Util.error_details is 0 for such messages. The handler must not fail: any exceptions are trapped and discarded.

Restores the default information handling function.

Specifies whether fixed-point iteration should return the newest iteration or the iteration consistent with the last function evaluation. The default values is false.

Sets the damping parameter for the fixed point or Picard iteration.

To applying damping, the given beta value must be greater than 0 and less than 1. Damping is disabled if beta >= 1. The default value is 1.

Set the Anderson acceleration damping parameter.

To applying damping, the given beta value must be greater than 0 and less than 1. Damping is disabled if beta >= 1. The default value is 1.

Sets the number of iterations to delay the start of Anderson acceleration. The default value is 0.

Returns the sizes of the real and integer workspaces.

Returns the number of evaluations of the system function.

Returns the cumulative number of nonlinear iterations.

Returns the number of beta-condition failures.

Returns the number of backtrack operations (step length adjustments) performed by the line search algorithm.

Returns the scaled Euclidiean l2 norm of the nonlinear system function $F(u)$ evaluated at the current iterate.

Returns the scaled Euclidiean l2 norm of the step used during the previous iteration.

An input parameter was invalid.

Line search could not find an iterate sufficiently distinct from the current one, or an iterate satisfying the sufficient decrease condition. The latter could mean that the current iterate is “close” to an approximate solution, but that the difference approximation of the matrix-vector product is inaccurate, or that scsteptol (Kinsol.set_scaled_step_tol) is too large.

The maximum number of nonlinear iterations has been reached.

Five consecutive steps exceed the maximum newton step. That is, the five steps satisfy the inequality $\\|D_u p\\|_{L2} > 0.99 \mathtt{mxnewtstep}$, where $p$ denotes the current step and mxnewtstep is a scalar upper bound on the scaled step length (see Kinsol.set_max_newton_step). It could be that $\\| D_F F(u)\\|_{L2}$ is bounded from above by a positive value or that mxnewtstep is too small.

The line search algorithm could not satisfy the “beta-condition” for mxnbcf + 1 nonlinear iterations. The failures need not occur in consecutive iterations. They may indicate that the algorithm is making poor progress.

The Kinsol.Spils.prec_solve_fn callback raised Sundials.RecoverableFailure but the preconditioner is already current.

Linear solver initialization failed.

The Kinsol.Spils.prec_setup_fn callback failed unrecoverably. If possible, the exception in the underlying linear solver is specified. It is typically one of Sundials_LinearSolver.ZeroInDiagonal, Sundials_LinearSolver.PSetFailure, or Sundials_LinearSolver.PackageFailure.

Either Kinsol.Spils.prec_solve_fn failed unrecoverably or the linear solver encountered an error condition. If possible, the exception in the underlying linear solver is specified. It is typically one of Sundials_LinearSolver.ZeroInDiagonal, Sundials_LinearSolver.ATimesFailure, Sundials_LinearSolver.PSolveFailure, Sundials_LinearSolver.GSFailure, Sundials_LinearSolver.QRSolFailure, or Sundials_LinearSolver.PackageFailure.

The Kinsol.sysfn callback failed unrecoverably.

The Kinsol.sysfn callback raised Sundials.RecoverableFailure when first called.

The Kinsol.sysfn callback raised Sundials.RecoverableFailure repeatedly. No recovery is possible.

A linear solver is required but was not specified.

A fused vector operation failed.