# Module Cvodes.Sensitivity

module Sensitivity: sig .. end

(Forward) Sensitivity analysis of ODEs with respect to their parameters.

Formalizes the dependency of a set of ODEs on $N_p$ parameters $p$ and calculates the sensitivities $s$ of the solution $y$ to a subset of $N_s \leq N_p$ of those parameters; $s(t) = \frac{\partial y(t)}{\partial p}$.

The solution sensitivity with respect to a single parameter $p_i$ satisfies the (forward) sensitivity equations $\dot{s}_i = \frac{\partial f}{\partial y}s_i + \frac{\partial f}{\partial p_i}$ and $s_i(t_0) = \frac{\partial y_0(p)}{\partial p_i}$, where $f$ and $y$ are from the $N$ equations of the original model.

This documented interface is structured as follows.

See sundials: Enhanced skeleton for sensitivity analysis
See sundials: Using CVODES for Forward Sensitivity Analysis
See sundials: Forward sensitivity analysis

### Initialization

type 'd sensrhsfn_args = {
    t : float; (* The value of the independent variable. *)    y : 'd; (* The vector of dependent-variable values $y(t)$. *)    y' : 'd; (* The value of the right-hand side of the state equations $\dot{y} = f(t, y, p)$. *)    tmp : 'd Cvode.double; (* Temporary storage vectors. *)
}

Common arguments to Cvodes.Sensitivity.sensrhsfn1 and Cvodes.Sensitivity.sensrhsfn_all.

type 'd sensrhsfn_all = 'd sensrhsfn_args -> 'd array -> 'd array -> unit

Sensitivity functions that calculate the right-hand sides of all sensitivity equations. They are passed the arguments:

• args, the current values of state variables (see Cvodes.Sensitivity.sensrhsfn_args),
• s, an array of vectors holding the current values of sensitivity variables, and,
• s', an array of vectors to be filled with the derivatives of the sensitivity variables.

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: CVSensRhsFn
type 'd sensrhsfn1 = int -> 'd sensrhsfn_args -> 'd -> 'd -> unit

Sensitivity functions that calculate the right-hand side of a single sensitivity equation. They are passed the arguments:

• i, the index of the sensitivity equation to compute,
• args, the current values of state variables (see Cvodes.Sensitivity.sensrhsfn_args),
• s, a vector holding the current value of the ith sensitivity variable, and
• s', a vector to be filled with the current value of the ith sensitivity variable's derivative.

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: CVSensRhs1Fn
type 'd sensrhsfn = 
 | AllAtOnce of 'd sensrhsfn_all option (* Calculate sensitivity functions all at once. The argument None specifies an internal difference quotient routine. See sundials: CVodeSensInitSee sundials: CVSensRhsFn *) | OneByOne of 'd sensrhsfn1 option (* Calculate sensitivity functions one parameter at a time. The argument None specifies an internal difference quotient routine. See sundials: CVodeSensInit1See sundials: CVSensRhs1Fn *)

Specify a sensitivity function.

type sens_method = 
 | Simultaneous (* Correct state and sensitivity variables at the same time. If Newton was selected as the nonlinear system solution method, this amounts to performing a modified Newton iteration on the combined nonlinear system. (CV_SIMULTANEOUS) *) | Staggered (* The correction step for the sensitivity variables takes place at the same time for all sensitivity equations, but only after the correction of the state variables has converged and the state variables have passed the local error test. (CV_STAGGERED) *) | Staggered1 (* All corrections are done sequentially, first for the state variables and then for the sensitivity variables, one parameter at a time. If the sensitivity variables are not included in the error control, this approach is equivalent to Staggered. Note that this approach can only be used if the user-provided sensitivity right-hand side function is of type OneByOne. (CV_STAGGERED1) *)

Specifies a sensitivity solution method.

See sundials: CVodeSensInit
See sundials: CVodeSensInit1
type sens_params = {
    pvals : Sundials.RealArray.t option; (* An array of $N_p$ parameters $p$ in $f(t, y, p)$. If specified, this array is updated by the solver to pass perturbed parameter values to the original right-hand side and root functions. Those functions must (re-)read parameter values from this array on every invocation. *)    pbar : Sundials.RealArray.t option; (* An array of $N_s$ positive scaling factors. These are needed when estimating tolerances or using the internal difference quotient function. *)    plist : int array option; (* An array of $N_s$ ($< N_p$) indices into pvals specifying the parameters to analyze. If not specified, the first $N_s$ parameters are analyzed. *)
}

Specifies problem parameter information for sensitivity calculations. Which fields are required varies as follows:

See sundials: CVodeSetSensParams
val no_sens_params : sens_params

Empty pvals, plist, and pbar fields.

type ('d, 'k) tolerance = 
 | 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 sensitivities from those for state variables and the scaling factors in pbar. *)

Tolerances for calculating sensitivities.

val init : ('d, 'k) Cvode.session ->       ('d, 'k) tolerance ->       sens_method ->       ?sens_params:sens_params ->       'd sensrhsfn -> ('d, 'k) Nvector.t array -> unit

Activates the calculation of forward sensitivities. The call init s tol sm sp fs ys0, has as arguments:

• s, a session created with Cvode.init,
• tol, the tolerances desired,
• sens_method, the solution method,
• ~sens_params, the parameter information (see Cvodes.Sensitivity.sens_params),
• ~fs, the sensitivity function, and,
• ys0, initial values of the sensitivities for each parameter.

If ~fs is not given, an internal difference quotient routine is used. In that case, or if the internal difference quotient routine will be specified in a subsequent call to Cvodes.Sensitivity.Quadrature.init, then sens_params must be given with pvals set to non-None.

See sundials: CVodeSensInit
See sundials: CVodeSensInit1
See sundials: CVodeSetSensParams
See sundials: CVodeSensSStolerances
See sundials: CVodeSensSVtolerances
See sundials: CVodeSensEEtolerances
val reinit : ('d, 'k) Cvode.session ->       sens_method -> ('d, 'k) Nvector.t array -> unit

Reinitializes the forward sensitivity computation.

See sundials: CVodeSensReInit
val toggle_off : ('d, 'k) Cvode.session -> unit

Deactivates forward sensitivity calculations without deallocating memory. Sensitivities can be reactivated with Cvodes.Sensitivity.reinit.

See sundials: CVodeSensToggleOff
module Quadrature: sig .. end

### Output functions

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

Returns the sensitivity solution vectors 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: CVodeGetSens
val get_dky : ('d, 'k) Cvode.session -> ('d, 'k) Nvector.t array -> float -> int -> unit

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

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

Raises
• BadT t is not in the interval $[t_n - h_u, t_n]$.
• BadK k is not in the range 0, 1, ..., $q_u$.
See sundials: CVodeGetSensDky
val get1 : ('d, 'k) Cvode.session -> ('d, 'k) Nvector.t -> int -> float

Returns a single sensitivity solution vector after a successful solver step. The given vector is filled with values calculated for the ith sensitivity vector during either Cvode.solve_normal or Cvode.solve_one_step and the value of the independent variable is returned.

Raises BadIS The index i is not in the allowed range.
See sundials: CVodeGetSens1
val get_dky1 : ('d, 'k) Cvode.session -> ('d, 'k) Nvector.t -> float -> int -> int -> unit

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

Raises
• BadIS The index i 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: CVodeGetSensDky1

### Modifying the solver (optional input functions)

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

Sets the integration tolerances for sensitivities.

NB: Unlike the other set_tolerances functions in Cvodes, this one does not call Cvodes.Sensitivity.set_err_con (which defaults to false).

See sundials: CVodeSensSStolerances
See sundials: CVodeSensSVtolerances
See sundials: CVodeSensEEtolerances
val set_err_con : ('d, 'k) Cvode.session -> bool -> unit

Sets whether sensitivity variables are used in the error control mechanism. The default is false.

See sundials: CVodeSetSensErrCon
type dq_method = 
 | DQCentered (* (CV_CENTERED) *) | DQForward (* (CV_FORWARD) *)

A difference quotient strategy. See Cvodes.Sensitivity.set_dq_method.

val set_dq_method : ('d, 'k) Cvode.session -> dq_method -> float -> unit

Sets the difference quotient strategy when sensitivity equations are computed internally by the solver rather than via callback. A method and dqrhomax value must be given. The latter determines when to switch between simultaneous or separate approximations of the two terms in the sensitivity right-hand side.

See sundials: CVodeSetSensDQMethod
See sundials: Forward Sensitivity Analysis
val set_max_nonlin_iters : ('d, 'k) Cvode.session -> int -> unit

Sets the maximum number of nonlinear solver iterations for sensitivity variables permitted per step.

See sundials: CVodeSetSensMaxNonlinIters

### Querying the solver (optional output functions)

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

Returns the number of calls to the sensitivity function.

See sundials: CVodeGetSensNumRhsEvals
val get_num_rhs_evals_sens : ('d, 'k) Cvode.session -> int

Returns the number of calls to the right-hand side function due to the internal finite difference approximation of the sensitivity equations.

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

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

See sundials: CVodeGetSensNumErrTestFails
val get_num_lin_solv_setups : ('d, 'k) Cvode.session -> int

Returns the number of calls made to the linear solver's setup function due to forward sensitivity calculations.

See sundials: CVodeGetSensNumLinSolvSetups
type sensitivity_stats = {
    num_sens_evals : int; (* Number of calls to the sensitivity function. *)    num_rhs_evals : int; (* Number of calls to the right-hand side function to calculate sensitivities. *)    num_err_test_fails : int; (* Number of local error test failures for sensitivity variables. *)    num_lin_solv_setups : int; (* Number of setups calls to the linear solver for sensitivity calculations. *)
}

Summaries of sensitivity stats.

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

Returns the sensitivity-related statistics as a group.

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

Returns the sensitivity error weights at the current time.

See sundials: CVodeGetSensErrWeights
See sundials: IVP solution (W_i, Eq. (2.7))
val get_num_nonlin_solv_iters : ('d, 'k) Cvode.session -> int

Returns the number of nonlinear iterations performed for sensitivity calculations.

See sundials: CVodeGetSensNumNonlinSolvIters
val get_num_nonlin_solv_conv_fails : ('d, 'k) Cvode.session -> int

Returns the number of nonlinear convergence failures that have occurred during sensitivity calculations.

See sundials: CVodeGetSensNumNonlinSolvConvFails
val get_nonlin_solv_stats : ('d, 'k) Cvode.session -> int * int

Returns both the numbers of nonlinear iterations performed nniters and nonlinear convergence failures nncfails during sensitivity calculations.

• Returns (nniters, nncfails)
• See sundials: CVodeGetSensNonlinSolvStats
val get_num_stgr_nonlin_solv_iters : ('d, 'k) Cvode.session -> Sundials.LintArray.t -> unit

Returns the number of nonlinear (functional or Newton) iterations performed for each sensitivity equation separately in the Staggered1 case.

See sundials: CVodeGetStgrSensNumNonlinSolvIters
val get_num_stgr_nonlin_solv_conv_fails : ('d, 'k) Cvode.session -> Sundials.LintArray.t -> unit

Returns the number of nonlinear convergence failures that have occurred for each sensitivity equation separately in the Staggered1 case.

See sundials: CVodeGetStgrSensNumNonlinSolvConvFails

### Exceptions

exception SensNotInitialized

Sensitivity analysis was not initialized.

See sundials: CV_NO_SENS
exception SensRhsFuncFailure

The sensitivity function failed in an unrecoverable manner.

See sundials: CV_SRHSFUNC_FAIL
exception FirstSensRhsFuncFailure

The sensitivity function had a recoverable error when first called.

See sundials: CV_FIRST_SRHSFUNC_ERR
exception RepeatedSensRhsFuncFailure

Too many convergence test failures, or unable to estimate the initial step size, due to repeated recoverable errors in the sensitivity function.

See sundials: CV_REPTD_SRHSFUNC_ERR
exception UnrecoverableSensRhsFuncFailure

The sensitivity function had a recoverable error, but no recovery was possible. This error can only occur after an error test failure at order one.

See sundials: CV_UNREC_SRHSFUNC_ERR
exception BadSensIdentifier

The index passed to identify a particular sensitivity is invalid.