Previous  Up  Next

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.

  1. Initialization (including Quadrature equations)
  2. Output functions
  3. Modifying the solver
  4. Querying the solver
  5. Exceptions

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:

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.

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:

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.

type 'd sensrhsfn =
| AllAtOnce of 'd sensrhsfn_all option (*

Calculate sensitivity functions all at once. The argument None specifies an internal difference quotient routine.

*)
| OneByOne of 'd sensrhsfn1 option (*

Calculate sensitivity functions one parameter at a time. The argument None specifies an internal difference quotient routine.

*)

Specify a sensitivity function.

type ('d, 'k) sens_method =
| Simultaneous of ('d, 'k, ('d, 'k) Cvode.session, [ `Sens ]) Sundials.NonlinearSolver.t option (*

Correct state and sensitivity variables at the same time. (CV_SIMULTANEOUS)

*)
| Staggered of ('d, 'k, ('d, 'k) Cvode.session, [ `Sens ]) Sundials.NonlinearSolver.t option (*

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 of ('d, 'k, ('d, 'k) Cvode.session, [ `Nvec ]) Sundials.NonlinearSolver.t option (*

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. The method specification may optionally include the nonlinear solver to be used for corrections.

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:

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 ->
       ('d, 'k) 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 sens_method ~sens_params fs ys0, has as arguments:

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.

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

Reinitializes the forward sensitivity computation.

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

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

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

Deactivates forward sensitivity calculations with memory deallocation.

module Quadrature: sig .. end

Support for quadrature sensitivity equations.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

Returns the sensitivity error weights at the current time.

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

Returns the cumulative number of nonlinear iterations performed for sensitivity calculations.

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

Returns the cumulative number of nonlinear convergence failures during sensitivity calculations.

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.

val get_num_stgr_nonlin_solv_iters : ('d, 'k) Cvode.session -> Sundials.LintArray.t -> unit

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

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

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

val get_current_state_sens : ('d, 'k) Cvodes.session -> 'd array

Returns the current sensitivity state vector array. The vectors in the returned array provide direct access to the data within the integrator.

type 'd nonlin_system_data = {
   tn : float; (*

Independent variable value $t_n$ .

*)
   yspred : 'd array; (*

Predicted state vectors $\mathit{yS}_{i,\mathit{pred}}$ at $t_n$ for $i = 0,\ldots,N_s-1$ . This data must not be changed.

*)
   ysn : 'd array; (*

State vectors $\mathit{yS}^n_i$ for $i = 0,\ldots,N_s-1$ . This data may not be current and may need to be filled.

*)
   gamma : float; (*

Current value of $\gamma$ .

*)
   rls1 : float; (*

A scaling factor used to compute $\tilde{a}_n = \mathtt{rls1}\cdot\mathtt{zns1}$ .

*)
   zns1 : 'd array; (*

Vectors used to compute $\tilde{a}_n = \mathtt{rl1}\cdot\mathtt{zn1}$ .

*)
}

Internal data required to construct the current nonlinear implicit system within a nonlinear solver.

val get_nonlin_system_data : ('d, 'k) Cvodes.session -> 'd nonlin_system_data

Gives direct access to the internal data required to construct the current nonlinear system within a nonlinear solver. This function should be called inside the nonlinear system function. The vectors ysn are provided as additional workspace and do not need to be filled in. They are only current after an evaluation of the nonlinear system function.

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

Computes the current sensitivity vector for all sensitivities using the stored prediction and the supplied correction vectors from the nonlinear solver. The call compute_state s i yscor ysn computes $\mathit{yS}^n = \mathit{yS}_{\mathit{pred}} + \mathit{yS}_{\mathit{cor}}$ .

val compute_state1 : ('d, 'k) Cvodes.session ->
       int -> ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> unit

Computes the current sensitivity vector for the sensitivity at the given index using the stored prediction and the supplied correction vector from the nonlinear solver. The call compute_state s i yscor1 ysn1 computes $\mathit{yS}^n_i = \mathit{yS}_{i,\mathit{pred}} + \mathit{yS}_{i,\mathit{cor}}$ .

val get_current_sens_solve_index : ('d, 'k) Cvodes.session -> int

Returns the index of the current sensitivity solve when using the Staggered1 method.

Exceptions

exception SensNotInitialized

Sensitivity analysis was not initialized.

exception SensRhsFuncFailure

The sensitivity function failed in an unrecoverable manner.

exception FirstSensRhsFuncFailure

The sensitivity function had a recoverable error when first called.

exception RepeatedSensRhsFuncFailure

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

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.

exception BadSensIdentifier

The index passed to identify a particular sensitivity is invalid.