Module Idas.Sensitivity.Quadrature

module Quadrature: sig .. end

Support for quadrature sensitivity equations.

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

See Sundials: Integration of quadrature equations depending on forward sensitivities
See Sundials: Quadratures 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)$.	`*)`
`y' : 'd;`	`(*`	The vector of dependent-variable derivatives $\dot{y}(t)$ .	`*)`
`s : 'd array;`	`(*`	The array of sensitivity vectors.	`*)`
`s' : 'd array;`	`(*`	The array of sensitivity derivative vectors.	`*)`
`q : 'd;`	`(*`	The current value of the quadrature right-hand side $q$.	`*)`
`tmp : 'd Ida.triple;`	`(*`	Temporary storage vectors.	`*)`

}

Arguments to Idas.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, sensitivity, and quadrature variables, and,
sq', an array of vectors for storing the computed values of $\dot{s}_\mathit{Q} = f_\mathit{QS}(t, y, \dot{y}, s, \dot{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: IDAQuadSensRhsFn

val init : ('d, 'k) Ida.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, Idas.Sensitivity.init must have been invoked with a sens_params whose pvals is non-None.

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

See Sundials: IDAQuadSensInit

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

Reinitializes the quadrature sensitivity integration.

See Sundials: IDAQuadSensReInit

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) Ida.session ->
       ('d, 'k) tolerance -> unit

Specify how to use quadrature sensitivities in step size control.

Output functions

val get : ('d, 'k) Ida.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 Ida.solve_normal or Ida.solve_one_step and the value of the independent variable is returned.

See Sundials: IDAGetQuadSens

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

Returns a single quadrature sensitivity vector after a successful solver step. Like Idas.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: IDAGetQuadSens1

val get_dky : ('d, 'k) Ida.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 Ida.get_current_time and $h_u$ denotes Ida.get_last_step,—and $0 \leq \mathtt{k} \leq q_u$—where $q_u$ denotes Ida.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: IDAGetQuadSensDky

val get_dky1 : ('d, 'k) Ida.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 Idas.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: IDAGetQuadSensDky1

Querying the solver (optional output functions)

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

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

See Sundials: IDAGetQuadSensNumRhsEvals

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

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

See Sundials: IDAGetQuadSensNumErrTestFails

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

Returns the quadrature error weights at the current time.

See Sundials: IDAGetQuadSensErrWeights

val get_stats : ('d, 'k) Ida.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: IDAGetQuadSensStats

Exceptions

exception QuadSensNotInitialized

Quadrature integration was not initialized.

See Sundials: IDA_NO_QUADSENS

exception QuadSensRhsFuncFailure

The sensitivity quadrature function failed in an unrecoverable manner.

See Sundials: IDA_QSRHS_FAIL

exception FirstQuadSensRhsFuncFailure

The sensitivity quadrature function failed at the first call.

See Sundials: IDA_FIRST_QSRHS_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: IDA_REP_QSRHS_ERR