Module Cvodes.Sensitivity.Quadrature

module Quadrature: sig .. end

Support for quadrature sensitivity equations.

Adds an additional vector $s_\mathit{Q}$ of $N_\mathit{Q}$ quadrature sensitivities $\frac{\mathrm{d} s_\mathit{Q}}{\mathrm{d}t} = f_{\mathit{QS}}(t, y, s, \dot{y}_Q, p)$. This mechanism allows, in particular, the calculation of the sensitivities of the ‘pure’ Cvodes.Quadrature variables, $y_Q$.


Initialization

type 'd quadsensrhsfn_args = {
   t : float; (*

The value of the independent variable.

*)
   y : 'd; (*

The vector of dependent-variable values $y(t)$.

*)
   s : 'd array; (*

The array of sensitivity vectors.

*)
   yq' : 'd; (*

The value of the quadrature-right hand side $\dot{y}_Q$.

*)
   tmp : 'd Cvode.double; (*

Temporary storage vectors.

*)
}

Arguments to Cvodes.Sensitivity.Quadrature.quadsensrhsfn.

type 'd quadsensrhsfn = 'd quadsensrhsfn_args -> 'd array -> unit 

Functions defining quadrature sensitivities. They are passed the arguments:

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

The vectors in the function arguments should not be accessed after the function returns.

val init : ('d, 'k) Cvode.session ->
?fqs:'d quadsensrhsfn ->
('d, 'k) Nvector.t array -> unit

Activate the integration of quadrature sensitivities. The arguments are:

If ~fqs is not given, an internal difference quotient routine is used. In that case, Cvodes.Sensitivity.init must have been invoked with a sens_params whose pvals is non-None.

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

Reinitializes the quadrature sensitivity integration.

Tolerance specification

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

Quadrature variables are not used for step-size control (the default).

*)
| SStolerances of float * Sundials.RealArray.t (*

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

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

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

*)
| EEtolerances (*

Calculate the integration tolerances for the quadrature sensitivities from those provided for the pure quadrature variables.

*)

Tolerances for calculating quadrature sensitivities.

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

Specify how to use quadrature sensitivities in step size control.

Output functions

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

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

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

Returns a single quadrature sensitivity vector after a successful solver step. Like Cvodes.Sensitivity.Quadrature.get, but the argument i specifies a specific vector to return.

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

Returns the interpolated solution or derivatives of the quadrature sensitivity solution.

get_dky s dksq t k computes the kth derivative at time t, i.e., $\frac{d^\mathtt{k}s_\mathit{Q}(\mathtt{t})}{\mathit{dt}^\mathtt{k}}$, and stores it in dksq. 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.

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

Returns the interpolated solution or derivatives of a single quadrature sensitivity solution vector. get_dky s dksq t k i is like Cvodes.Sensitivity.Quadrature.get_dky but restricted to the ith sensitivity solution vector.

Querying the solver (optional output functions)

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

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

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

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

val get_err_weights : ('d, 'k) Cvode.session -> ('d, 'k) Nvector.t array -> 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 QuadSensNotInitialized

Quadrature integration was not initialized.

exception QuadSensRhsFuncFailure

The sensitivity quadrature function failed in an unrecoverable manner.

exception FirstQuadSensRhsFuncFailure

The sensitivity quadrature function failed at the first call.

exception RepeatedQuadSensRhsFuncFailure

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

exception UnrecoverableQuadSensRhsFuncFailure

The sensitivity 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.