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$.

See Sundials: Integration of quadratures equations depending on forward sensitivities

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:

args, the current values of state and sensitivity variables, and,
sq', an array of vectors for storing the computed values of $\dot{s}_\mathit{Q} = f_\mathit{QS}(t, y, s, \dot{y}_Q)$.

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.

See Sundials: CVodeQuadSensRhsFn

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

Activate the integration of quadrature sensitivities. The arguments are:

~fqs, a function that computes the right-hand sides of the quadrature sensitivities, and
q0, an array of vectors specifying initial values for the quadrature sensitivities.

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.

Raises QuadNotInitialized Cvodes.Sensitivity.Quadrature.init has not been called.

See Sundials: CVodeQuadSensInit

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

Reinitializes the quadrature sensitivity integration.

See Sundials: CVodeQuadSensReInit

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.

See Sundials: CVodeGetQuadSens

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.

Raises BadIS The index is not in the allowed range.

See Sundials: CVodeGetQuadSens1

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.

Raises

BadIS The index is not in the allowed range.
BadK k is not in the range 0, 1, ..., qlast.
BadT t is not in the allowed range.

See Sundials: CVodeGetQuadSensDky

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.

Raises

BadK k is not in the range 0, 1, ..., qlast.
BadT t is not in the allowed range.

See Sundials: CVodeGetQuadSensDky1

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.

See Sundials: CVodeGetQuadSensNumRhsEvals

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

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

See Sundials: CVodeGetQuadSensNumErrTestFails

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

Returns the quadrature error weights at the current time.

See Sundials: CVodeGetQuadSensErrWeights

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).

Returns (nfqevals, nqetfails)
See Sundials: CVodeGetQuadSensStats

Exceptions

exception QuadSensNotInitialized

Quadrature integration was not initialized.

See Sundials: CV_NO_QUAD_SENS

exception QuadSensRhsFuncFailure

The sensitivity quadrature function failed in an unrecoverable manner.

See Sundials: CV_QSRHSFUNC_FAIL

exception FirstQuadSensRhsFuncFailure

The sensitivity quadrature function failed at the first call.

See Sundials: CV_FIRST_QSRHSFUNC_ERR

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).

See Sundials: CV_REPTD_QSRHSFUNC_ERR

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.

See Sundials: CV_UNREC_QSRHSFUNC_ERR