Module Arkode.ERKStep

module ERKStep: sig .. end

ERKStep Time-Stepping Module for nonstiff initial value problems.

This module solves problems of the form $\dot{y} = f(t, y)$, $y(t_0) = y_0$.

Its interface is structured as follows.

  1. Solver initialization and use
  2. Modifying the solver
  3. Querying the solver
  4. Additional root finding functions

include Arkode.Common
type ('d, 'k) session = ('d, 'k, Arkode.erkstep) session 

A session with the ERKStep time-stepping solver.

An example session with ERKStep (arkode_erk_skel.ml):

open Sundials
module ERKStep = Arkode.ERKStep

(* 1. Define right-hand-side functions. *)
let f _t y yd = yd.{0} <- y.{1};
                yd.{1} <- -9.81

(* 2. Optionally define a root function. *)
let g _t y gout = gout.{0} <- 1.0 -. y.{0}

(* 3. Set vector of initial values.
      The length of this vector determines the problem size. *)
let yd = RealArray.of_list [ 10.0; 0.0 ]
let y = Nvector_serial.wrap yd

(* 4. Create and initialize a solver session. *)
let s = ERKStep.(init (SStolerances (1e-4, 1e-9)) f ~roots:(1, g) 0.0 y);;

(* 5. Set optional inputs, e.g.,
      call [set_*] functions to change solver parameters. *)
ERKStep.set_stop_time s 10.0;;
ERKStep.set_all_root_directions s RootDirs.Increasing;;

(* 6. Advance the solution in time,
      by repeatedly calling [evolve_normal] or [evolve_one_step]. *)
let rec go (t, r) =
  Printf.printf "% .10e\t% .10e\t% .10e\n" t yd.{0} yd.{1};
  match r with
  | ERKStep.Success -> go (ERKStep.evolve_normal s (t +. 0.5) y)
  | ERKStep.RootsFound -> begin
        yd.{1} <- -0.8 *. yd.{1};
        ERKStep.reinit s t y;
        go (t, ERKStep.Success)
      end
  | ERKStep.StopTimeReached -> ();;

Printf.printf "time\ty\ty'\n";;
go (0.0, ERKStep.Success);;

(* 7. Get optional outputs,
      call the [get_*] functions to examine solver statistics. *)
let ns = ERKStep.get_num_steps s
      

Solver initialization and use

val init : ?context:Sundials.Context.t ->
('data, 'kind) tolerance ->
?order:int ->
'data rhsfn ->
?roots:int * 'data rootsfn ->
float -> ('data, 'kind) Nvector.t -> ('data, 'kind) session

Creates and initializes a session with the solver. The call

init tol ~order f ~roots:(nroots, g) t0 y0

has as arguments:

This function does everything necessary to initialize a session, i.e., it makes the calls referenced below. The Arkode.ERKStep.evolve_normal and Arkode.ERKStep.evolve_one_step functions may be called directly.

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.

val evolve_normal : ('d, 'k) session ->
float -> ('d, 'k) Nvector.t -> float * solver_result

Integrates an ODE system over an interval. The call tret, r = evolve_normal s tout yout has as arguments

It returns tret, the time reached by the solver, which will be equal to tout if no errors occur, and, r, a Arkode.Common.solver_result.

val evolve_one_step : ('d, 'k) session ->
float -> ('d, 'k) Nvector.t -> float * solver_result

Like Arkode.ERKStep.evolve_normal but returns after one internal solver step.

val get_dky : ('d, 'k) session -> ('d, 'k) Nvector.t -> float -> int -> unit

Returns the interpolated solution or derivatives. get_dky s dky t k computes the kth derivative of the function at time t, i.e., $\frac{d^\mathtt{k}}{\mathit{dt}^\mathtt{k}}y(\mathtt{t})$, and stores it in dky. The arguments must satisfy $t_n - h_n \leq \mathtt{t} \leq t_n$—where $t_n$ denotes Arkode.ERKStep.get_current_time and $h_n$ denotes Arkode.ERKStep.get_last_step,— and $0 \leq \mathtt{k} \leq 3$.

This function may only be called after a successful return from either Arkode.ERKStep.evolve_normal or Arkode.ERKStep.evolve_one_step.

val reinit : ('d, 'k) session ->
?order:int -> ?roots:int * 'd rootsfn -> float -> ('d, 'k) Nvector.t -> unit

Reinitializes the solver with new parameters and state values. The values of the independent variable, i.e., the simulation time, and the state variables must be given. If given, order changes the order of accuracy, and roots specifies a new root finding function. The new problem must have the same size as the previous one.

The allowed values for order are as for Arkode.ERKStep.init.

val reset : ('d, 'k) session -> float -> ('d, 'k) Nvector.t

Resets the state to the given independent variable value and dependent variable vector. All previously set options, internal counter values, and step-size/error histories are retained.

val resize : ('d, 'k) session ->
?resize_nvec:'d resize_fn ->
('d, 'k) tolerance -> float -> ('d, 'k) Nvector.t -> float -> unit

Change the number of equations and unknowns between integrator steps. The call resize s ~resize_nvec:rfn tol hscale ynew t0 has as arguments:

A call to this function disables inequality constraint checking. It can be reenabled by calling Arkode.ERKStep.set_constraints.

Modifying the solver (optional input functions)

val set_tolerances : ('d, 'k) session -> ('d, 'k) tolerance -> unit

Sets the integration tolerances.

val set_defaults : ('d, 'k) session -> unit

Resets all optional input parameters to their default values. Neither the problem-defining functions nor the root-finding functions are changed.

val set_diagnostics : ?logfile:Sundials.Logfile.t -> ('d, 'k) session -> unit

Write step adaptivity and solver diagnostics on the standard output (or given file).

val set_interpolant_type : ('d, 'k) session -> interpolant_type -> unit

Specifies the interpolation module used for output value interpolation and implicit method predictors.

val set_interpolant_degree : ('d, 'k) session -> int -> unit

Specifies the degree of the polynomial interpolant used for output values and implicit method predictors.

val clear_diagnostics : ('d, 'k) session -> unit

Do not write step adaptivity or solver diagnostics of a file.

val set_error_file : ('d, 'k) session -> Sundials.Logfile.t -> unit

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

val set_err_handler_fn : ('d, 'k) session ->
(Sundials.Util.error_details -> unit) -> unit

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

val clear_err_handler_fn : ('d, 'k) session -> unit

Restores the default error handling function.

val set_init_step : ('d, 'k) session -> float -> unit

Specifies the initial step size.

val set_fixed_step : ('d, 'k) session -> float option -> unit

Disables time step adaptivity and fix the step size for all internal steps. Pass None to restore time step adaptivity. This function is not recommended since there is no assurance of the validity of the computed solutions. It is provided primarily for code-to-code verification testing. Use in conjunction with Arkode.ERKStep.set_min_step or Arkode.ERKStep.set_max_step.

val set_max_num_constr_fails : ('d, 'k) session -> int -> unit

Specifies the maximum number of constraint failures in a step before an error is signalled.

val set_max_hnil_warns : ('d, 'k) session -> int -> unit

Specifies the maximum number of messages warning that t + h = t on the next internal step.

val set_max_num_steps : ('d, 'k) session -> int -> unit

Specifies the maximum number of steps taken in attempting to reach a given output time.

val set_max_err_test_fails : ('d, 'k) session -> int -> unit

Specifies the maximum number of error test failures permitted in attempting one step.

val set_min_step : ('d, 'k) session -> float -> unit

Specifies a lower bound on the magnitude of the step size.

val set_max_step : ('d, 'k) session -> float -> unit

Specifies an upper bound on the magnitude of the step size.

val set_stop_time : ('d, 'k) session -> float -> unit

Limits the value of the independent variable t when solving. By default no stop time is imposed.

Optional inputs for IVP method selection

val set_table : ('d, 'k) session -> Arkode.ButcherTable.t -> unit

Specifies a customized Butcher table.

val set_table_num : ('d, 'k) session -> Arkode.ButcherTable.erk_table -> unit

Use a specific built-in Butcher table for integration.

Optional inputs for time step adaptivity

val set_adaptivity_method : ('d, 'k) session -> 'd adaptivity_method -> unit

Specifies the method and associated parameters used for time step adaptivity.

val set_cfl_fraction : ('d, 'k) session -> float -> unit

Specifies the fraction of the estimated explicitly stable step to use. Any non-positive argument resets to the default value (0.5).

val set_error_bias : ('d, 'k) session -> float -> unit

Specifies the bias to apply to the error estimates within accuracy-based adaptivity strategies.

val set_fixed_step_bounds : ('d, 'k) session -> float -> float -> unit

Specifies the step growth interval in which the step size will remain unchanged. In the call set_fixed_step_bounds s lb ub, lb specifies a lower bound on the window to leave the step size fixed and ub specifies an upper bound. Any interval not containing 1.0 resets to default values.

val set_max_efail_growth : ('d, 'k) session -> float -> unit

Specifies the maximum step size growth factor upon multiple successive accuracy-based error failures in the solver. Any value outside the interval $(0, 1]$ resets to the default value.

val set_max_first_growth : ('d, 'k) session -> float -> unit

Specifies the maximum allowed step size change following the very first integration step. Any value $\le 1$ resets to the default value.

val set_max_growth : ('d, 'k) session -> float -> unit

Specifies the maximum growth of the step size between consecutive time steps. Any value $\le 1$ resets to the default value.

val set_min_reduction : ('d, 'k) session -> float -> unit

Specifies the minimum allowed reduction factor in step size between step attempts that result from a temporal error failure in the integration process.

val set_safety_factor : ('d, 'k) session -> float -> unit

Specifies the safety factor to be applied to the accuracy-based estimated step. Any non-positive value resets to the default value.

val set_small_num_efails : ('d, 'k) session -> float -> unit

Specifies the threshold for “multiple” successive error failures before the factor from Arkode.ERKStep.set_max_efail_growth is applied. Any non-positive value resets to the default value.

val set_stability_fn : ('d, 'k) session -> 'd stability_fn -> unit

Sets a problem-dependent function to estimate a stable time step size for the explicit portion of the ODE system.

val clear_stability_fn : ('d, 'k) session -> unit

Clears the problem-dependent function that estimates a stable time step size for the explicit portion of the ODE system.

val set_postprocess_step_fn : ('d, 'k) session -> 'd postprocess_step_fn -> unit

Set a post processing step function.

val clear_postprocess_step_fn : ('d, 'k) session -> unit

Clear the post processing step function.

val set_constraints : ('d, 'k) session -> ('d, 'k) Nvector.t -> unit

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

Querying the solver (optional output functions)

val get_work_space : ('d, 'k) session -> int * int

Returns the real and integer workspace sizes.

val get_num_steps : ('d, 'k) session -> int

Returns the cumulative number of internal steps taken by the solver.

val get_num_exp_steps : ('d, 'k) session -> int

Returns the cumulative number of stability-limited steps taken by the solver.

val get_num_acc_steps : ('d, 'k) session -> int

Returns the cumulative number of accuracy-limited steps taken by the solver.

val get_num_step_attempts : ('d, 'k) session -> int

Returns the cumulative number of steps attempted by the solver.

val get_num_rhs_evals : ('d, 'k) session -> int

Returns the number of calls to the right-hand side function.

val get_num_err_test_fails : ('d, 'k) session -> int

Returns the number of local error test failures that have occurred.

val get_last_step : ('d, 'k) session -> float

Returns the integration step size taken on the last successful internal step.

val get_current_step : ('d, 'k) session -> float

Returns the integration step size to be attempted on the next internal step.

val get_actual_init_step : ('d, 'k) session -> float

Returns the the value of the integration step size used on the first step.

val get_current_time : ('d, 'k) session -> float

Returns the the current internal time reached by the solver.

val get_current_butcher_table : ('d, 'k) session -> Arkode.ButcherTable.t

Returns the Butcher table in use by the solver.

val get_tol_scale_factor : ('d, 'k) session -> float

Returns a suggested factor by which the user's tolerances should be scaled when too much accuracy has been requested for some internal step.

val get_err_weights : ('d, 'k) session -> ('d, 'k) Nvector.t -> unit

Returns the solution error weights at the current time.

val get_est_local_errors : ('d, 'k) session -> ('d, 'k) Nvector.t -> unit

Returns the vector of estimated local errors.

type timestepper_stats = {
   exp_steps : int; (*

Cumulative number of stability-limited solver steps.

*)
   acc_steps : int; (*

Cumulative number of accuracy-limited solver steps.

*)
   step_attempts : int; (*

Cumulative number of steps attempted by the solver.

*)
   num_nf_evals : int; (*

Number of calls to the right-hand side function.

*)
   num_err_test_fails : int; (*

Number of error test failures.

*)
}

Summaries of time-stepper statistics.

val get_timestepper_stats : ('d, 'k) session -> timestepper_stats

Returns a grouped set of time-stepper statistics.

val get_step_stats : ('d, 'k) session -> step_stats

Returns a grouped set of integrator statistics.

val print_timestepper_stats : ('d, 'k) session -> Stdlib.out_channel -> unit

Prints time-stepper statistics on the given channel.

val print_step_stats : ('d, 'k) session -> Stdlib.out_channel -> unit

Prints integrator statistics on the given channel.

val write_session : ?logfile:Sundials.Logfile.t -> ('d, 'k) session -> unit

Summarize the session on the standard output (or given file).

Additional root-finding functions

val set_root_direction : ('d, 'k) session -> Sundials.RootDirs.d array -> unit

set_root_direction s dir specifies the direction of zero-crossings to be located and returned. dir may contain one entry for each root function.

val set_all_root_directions : ('d, 'k) session -> Sundials.RootDirs.d -> unit

Like Arkode.ERKStep.set_root_direction but specifies a single direction for all root functions.

val set_no_inactive_root_warn : ('d, 'k) session -> unit

Disables issuing a warning if some root function appears to be identically zero at the beginning of the integration.

val get_num_roots : ('d, 'k) session -> int

Returns the number of root functions.

val get_root_info : ('d, 'k) session -> Sundials.Roots.t -> unit

Fills an array showing which functions were found to have a root.

val get_num_g_evals : ('d, 'k) session -> int

Returns the cumulative number of calls made to the user-supplied root function g.

val get_num_constr_fails : ('d, 'k) session -> int

Returns the cumulative number of test failures.

val write_parameters : ?logfile:Sundials.Logfile.t -> ('d, 'k) session -> unit

Outputs all the solver parameters on the standard output (or given file).

val write_butcher : ?logfile:Sundials.Logfile.t -> ('d, 'k) session -> unit

Outputs the current butcher table on the standard output (or given file).