Module Cvodes.Quadrature

module Quadrature: sig .. end

Integration of pure quadrature equations.

Adds a vector $y_Q$ of $N_Q$ quadrature variables defined by $\frac{\mathrm{d} y_Q}{\mathrm{d}t} = f_Q(t, y, p)$. The values of these variables are calculated more efficiently since they are excluded from the nonlinear solution stage.


Initialization and access

type 'd quadrhsfn = float -> 'd -> 'd -> unit 

Functions defining quadrature variables. They are passed three arguments:

Within the function, raising a Sundials.RecoverableFailure exception indicates a recoverable error. Any other exception is treated as an unrecoverable error.

y and yQ' should not be accessed after the function returns.

val init : ('d, 'k) Cvode.session ->
'd quadrhsfn -> ('d, 'k) Nvector.t -> unit

Activates the integration of quadrature equations. The vector gives the initial value of $y_Q$.

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

Reinitializes the integration of quadrature equations. The vector gives a new value for $y_Q$.

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

Returns the quadrature solutions and time reached after a successful solver step. The given vector is filled with values calculated during either Cvode.solve_normal or Cvode.solve_one_step and the value of the independent variable is returned.

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

Returns the interpolated solution or derivatives of quadrature variables.

get_dky s dkyq t k computes the kth derivative at time t, i.e., $\frac{d^\mathtt{k}y_Q(\mathtt{t})}{\mathit{dt}^\mathtt{k}}$, and stores it in dkyq. The arguments must satisfy $t_n - h_u \leq \mathtt{t} \leq t_n$—where $t_n$ denotes Cvode.get_current_time and $h_u$ denotes Cvode.get_last_step,— and $0 \leq \mathtt{k} \leq q_u$—where $q_u$ denotes Cvode.get_last_order.

This function may only be called after a successful return from either Cvode.solve_normal or Cvode.solve_one_step.

Tolerances

type ('d, 'k) tolerance = 
| NoStepSizeControl (*

Do not use quadrature variables for step-size control (default).

*)
| SStolerances of float * float (*

(rel, abs) : scalar relative and absolute tolerances.

*)
| SVtolerances of float * ('d, 'k) Nvector.t (*

(rel, abs) : scalar relative and vector absolute tolerances.

*)

Tolerances for calculating quadrature variables.

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

Specify how to use quadrature variables in step size control.

Querying the solver (optional output functions)

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

Returns the number of calls to the quadrature function.

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

Returns the number of local error test failures that have occurred due to quadrature variables.

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

Returns the quadrature error weights at the current time.

val get_stats : ('d, 'k) Cvode.session -> int * int

Returns quadrature-related statistics. These are the number of calls to the quadrature function (nfqevals) and the number of error test failures due to quadrature variables (nqetfails).

Exceptions

exception QuadNotInitialized

Quadrature integration was not initialized.

exception QuadRhsFuncFailure

The quadrature function failed in an unrecoverable manner.

exception FirstQuadRhsFuncFailure

The quadrature function failed at the first call.

exception RepeatedQuadRhsFuncFailure

Convergence test failures occurred too many times due to repeated recoverable errors in the quadrature function. Also raised if the quadrature function had repeated recoverable errors during the estimation of an initial step size (if quadrature variables are included in error tests).

exception UnrecoverableQuadRhsFuncFailure

The quadrature function had a recoverable error, but no recovery was possible. This failure mode is rare, as it can occur only if the quadrature function fails recoverably after an error test failed while at order one.