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.

Initialization (including Quadrature equations)
Output functions
Modifying the solver
Querying the solver
Exceptions

See Sundials: Using IDAS for Forward Sensitivity Analysis
See Sundials: Enhanced skeleton for sensitivity analysis
See Sundials: Forward sensitivity analysis

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:

args, which summarizes current values of state and sensitivty variables, and
rs an array of vectors for storing the calculated sensitivity residual values, $\mathit{rs}_i = \frac{\partial F}{\partial y}s_i(t) + \frac{\partial F}{\partial \dot{y}}\dot{s}_i(t) + \frac{\partial F}{\partial p_i}$

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: IDASensResFn

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.

See Sundials: IDASensInit

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:

pvals is mandatory if Idas.Sensitivity.init and/or Idas.Sensitivity.Quadrature.init is not given a user-defined callback. Otherwise, it is ignored.
plist is optional if pvals is given. Otherwise, it is ignored.
pbar is always meaningful and optional.

See Sundials: IDASetSensParams

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:

s, a session created with Ida.init,
tol, the tolerances desired,
sm, the solution method,
sens_nlsolver, the solver to use to calculate integration steps,
sens_params, the parameter information (see Idas.Sensitivity.sens_params),
fs, the sensitivity function,
s0, initial values of the sensitivities for each parameter, and,
s0', initial values of the sensitivity derivatives 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 Idas.Sensitivity.Quadrature.init, then sens_params must be given with pvals set to non-None.

See Sundials: IDASensInit
See Sundials: IDASetSensParams
See Sundials: IDASensSStolerances
See Sundials: IDASensSVtolerances
See Sundials: IDASensEEtolerances
See Sundials: IDASetNonlinearSolverSensSim
See Sundials: IDASetNonlinearSolverSensStg

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.

See Sundials: IDASensReInit

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

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

See Sundials: IDASensToggleOff

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.

See Sundials: IDACalcIC
See Sundials: IDAGetConsistentIC
See Sundials: IDAGetSensConsistentIC

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.

See Sundials: IDACalcIC
See Sundials: IDAGetConsistentIC
See Sundials: IDAGetSensConsistentIC

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.

See Sundials: IDAGetSens

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.

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: IDAGetSensDky

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.

Raises BadIS The index i is not in the allowed range.

See Sundials: IDAGetSens1

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.

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: IDAGetSensDky1

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

See Sundials: IDASensSStolerances
See Sundials: IDASensSVtolerances
See Sundials: IDASensEEtolerances

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.

See Sundials: IDASetSensErrCon

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.

See Sundials: IDASetSensDQMethod

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.

See Sundials: IDASetSensMaxNonlinIters

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.

See Sundials: IDAGetSensNumResEvals

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.

See Sundials: IDAGetNumResEvalsSens

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.

See Sundials: IDAGetSensNumErrTestFails

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.

See Sundials: IDAGetSensNumLinSolvSetups

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.

See Sundials: IDAGetSensStats

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

Returns the sensitivity error weights at the current time.

See Sundials: IDAGetSensErrWeights
See Sundials: IVP solution (W_i)

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

Returns the cumulative number of nonlinear iterations for sensitivity calculations.

See Sundials: IDAGetSensNumNonlinSolvIters

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

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

See Sundials: IDAGetSensNumNonlinSolvConvFails

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.

Returns (nniters, nncfails)
See Sundials: IDAGetSensNonlinSolvStats

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.

Since 5.0.0
See Sundials: IDAGetCurrentYSens

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.

Since 5.0.0
See Sundials: IDAGetCurrentYpSens

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.

Since 5.4.0
See Sundials: IDAGetNonlinearSystemData

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.

Since 5.0.0
See Sundials: IDAComputeYSens

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.

Since 5.0.0
See Sundials: IDAComputeYpSens

Exceptions

exception SensNotInitialized

Sensitivity analysis was not initialized.

See Sundials: IDA_NO_SENS

exception SensResFuncFailure

The sensitivity residual function failed in an unrecoverable manner.

See Sundials: IDA_SRES_FAIL

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.

See Sundials: IDA_REP_SRES_ERR

exception BadSensIdentifier

The index passed to identify a particular sensitivity is invalid.

See Sundials: IDA_BAD_IS