Module Idas.Sensitivity

module Sensitivity: sig .. end

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

Formalizes the dependency of a set of DAEs on $N_p$ parameters $p$ and calculates the sensitivities $s$ and their derivatives $\dot{s}$ of the solutions $y$ and $\dot{y}$ relative to a subset of $N_s \leq N_p$ of those parameters such that the $i$th sensitivity satisfies the (forward) sensitivity equations: $\frac{\partial F}{\partial y}s_i(t) + \frac{\partial F}{\partial \dot{y}}\dot{s}_i(t) + \frac{\partial F}{\partial p_i} = 0$, $s_i(t_0) = \frac{\partial y_0(p)}{\partial p_i}$, and, $\dot{s_i}(t_0) = \frac{\partial \dot{y}_0(p)}{\partial p_i}$, where $F$, $y$, and $\dot{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 sensresfn_args = {
   t : float; (*

The value of the independent variable.

*)
   y : 'd; (*

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

*)
   y' : 'd; (*

The vector of derivatives of dependent variables $\dot{y}(t)$.

*)
   res : 'd; (*

The vector of current residuals.

*)
   s : 'd array; (*

The array of sensitivity vectors.

*)
   s' : 'd array; (*

The array of sensitivity derivative vectors.

*)
   tmp : 'd Ida.triple; (*

Temporary storage vectors.

*)
}

Arguments to Idas.Sensitivity.sensresfn.

type 'd sensresfn = 'd sensresfn_args -> 'd array -> unit 

Sensitivity functions that calculate the residuals 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 sens_method = 
| Simultaneous (*

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

*)
| Staggered (*

Correct sensitivity variables simultaneously, but only after the convergence of state variable corrections and when state variables pass the local error test. (IDA_STAGGERED)

*)

Specifies a sensitivity solution method.

type sens_params = {
   pvals : Sundials.RealArray.t option; (*

An array of $N_p$ parameters $p$ in $F(t, y, \dot{y}, p)$. If specified, this array is updated by the solver to pass perturbed parameter values to the original residual 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 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:

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 of state variables and the scaling factors in pbar.

*)

Tolerances for calculating sensitivities.

val init : ('d, 'k) Ida.session ->
('d, 'k) tolerance ->
sens_method ->
?sens_nlsolver:('d, 'k, ('d, 'k) Ida.session, [ `Sens ])
Sundials.NonlinearSolver.t ->
?sens_params:sens_params ->
?fs:'d sensresfn ->
('d, 'k) Nvector.t array -> ('d, 'k) Nvector.t array -> unit

Activates the calculation of forward sensitivities. The call

init s tol sm ~sens_nlsolver ~sens_params ~fs s0 s0'

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 Idas.Sensitivity.Quadrature.init, then sens_params must be given with pvals set to non-None.

val reinit : ('d, 'k) Ida.session ->
sens_method ->
?sens_nlsolver:('d, 'k, ('d, 'k) Ida.session, [ `Sens ])
Sundials.NonlinearSolver.t ->
('d, 'k) Nvector.t array -> ('d, 'k) Nvector.t array -> unit

Reinitializes the forward sensitivity computation.

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

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

module Quadrature: sig .. end

Support for quadrature sensitivity equations.

Initial Condition Calculation

val calc_ic_ya_yd' : ('d, 'k) Ida.session ->
?y:('d, 'k) Nvector.t ->
?y':('d, 'k) Nvector.t ->
?s:('d, 'k) Nvector.t array ->
?s':('d, 'k) Nvector.t array -> ?varid:('d, 'k) Nvector.t -> float -> unit

Identical to Ida.calc_ic_ya_yd', but with the possibility of filling s and s' with the corrected sensitivity and sensitivity derivative values.

val calc_ic_y : ('d, 'k) Ida.session ->
?y:('d, 'k) Nvector.t -> ?s:('d, 'k) Nvector.t array -> float -> unit

Identical to Ida.calc_ic_y, but with the possibility of filling s with the corrected sensitivity values.

Output functions

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

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

This function may only be called after a successful return from either Ida.solve_normal or Ida.solve_one_step.

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

val get_dky1 : ('d, 'k) Ida.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 Idas.Sensitivity.get_dky but restricted to the ith sensitivity solution vector.

Modifying the solver (optional input functions)

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

Specify the integration tolerances for sensitivities.

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

val set_err_con : ('d, 'k) Ida.session -> bool -> unit

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

type dq_method = 
| DQCentered (*

IDA_CENTERED

*)
| DQForward (*

IDA_FORWARD

*)

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

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

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

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

Querying the solver (optional output functions)

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

Returns the number of calls to the sensitivity residual function.

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

Returns the number of calls to the residual function due to the internal finite difference approximation of the sensitivity residual.

val get_num_err_test_fails : ('d, 'k) Ida.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) Ida.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_res_evals : int; (*

Number of calls to the residual 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) Ida.session -> sensitivity_stats

Returns the sensitivity-related statistics as a group.

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

Returns the sensitivity error weights at the current time.

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

Returns the cumulative number of nonlinear iterations for sensitivity calculations.

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

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

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

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

val get_current_y_sens : ('d, 'k) Idas.session -> 'd array

Returns the current sensitivity vector array. Its elements provide direct access to the data within the integrator.

val get_current_yp_sens : ('d, 'k) Idas.session -> 'd array

Returns the derivative of the current sensitivity vector array. Its elements provide direct access to the data within the integrator.

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

Independent variable value $t_n$ .

*)
   yyspred : 'd array; (*

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

*)
   ypspred : 'd array; (*

Predicted value of $\dot{y}S}_{i,\mathit{pred}}$ at $t_n$ for $i = 0,\ldots,N_s-1$ . This data must not be changed.

*)
   yysn : 'd array; (*

The vector $\mathit{yS}_{i,n}$ . This data may not be current and may need to be filled.

*)
   ypsn : 'd array; (*

The vector $\dot{y}S_{i,n}$ . This data may not be current and may need to be filled.

*)
   cj : float; (*

The scalar $c_j$ which is proportional to the inverse of the step size $\alpha$ .

*)
}

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

val get_nonlin_system_data : ('d, 'k) Idas.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 yysn and ypsn 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_y_sens : ('d, 'k) Idas.session ->
ycor:('d, 'k) Nvector.t array -> y:('d, 'k) Nvector.t array -> unit

Computes the sensitiviites from a correction vector.

val compute_yp_sens : ('d, 'k) Idas.session ->
ycor:('d, 'k) Nvector.t array -> yp:('d, 'k) Nvector.t array -> unit

Computes the sensitivity derivatives from a correction vector.

Exceptions

exception SensNotInitialized

Sensitivity analysis was not initialized.

exception SensResFuncFailure

The sensitivity residual function failed in an unrecoverable manner.

exception RepeatedSensResFuncFailure

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

exception BadSensIdentifier

The index passed to identify a particular sensitivity is invalid.