Module Cvodes.Adjoint

module Adjoint: sig .. end
(Adjoint) Sensitivity analysis of ODEs with respect to their parameters.

Provides an alternative to forward sensitivity analysis, which can become prohibitively expensive. This technique does not calculate sensitivities, but rather gradients with respect to the parameters of a relatively few derived functionals of the solution, that is the gradient $\frac{\mathrm{d}G}{\mathrm{d}p}$ of $G(p) = \int_{t_0}^T \! g(t, y, p)\,\mathrm{d}t$. The gradients are evaluated by first calculating forward and checkpointing certain intermediate state values, and then integrating backward to $t_0$.

This documented interface is structured as follows.

  1. Forward solution
  2. Linear solvers
  3. Backward solutions (including Quadrature equations)
  4. Modifying the solver
  5. Querying the solver
  6. Exceptions

See sundials: Enhanced Skeleton for Adjoint Sensitivity Analysis
See sundials: Using CVODES for Adjoint Sensitivity Analysis
See sundials: Adjoint sensitivity analysis

type ('data, 'kind) bsession = ('data, 'kind) AdjointTypes.bsession 
A backward session with the CVODES solver. Multiple backward sessions may be associated with a single parent session.
See sundials: Backward problem initialization functions
type [> Nvector_serial.kind ] serial_bsession = (Nvector_serial.data, [> Nvector_serial.kind ] as 'a) bsession 
Alias for backward sessions based on serial nvectors.

Forward solution


type interpolation = 
| IPolynomial (*
(CV_POLYNOMIAL)
*)
| IHermite (*
(CV_HERMITE)
*)
Specifies the type of interpolation to use between checkpoints.
See sundials: Checkpointing scheme
val init : ('d, 'k) Cvode.session -> int -> interpolation -> unit
Activates the forward-backward problem. The arguments specify the number of integration steps between consecutive checkpoints, and the type of variable-degree interpolation.
See sundials: CVodeAdjInit
val forward_normal : ('d, 'k) Cvode.session ->
float -> ('d, 'k) Nvector.t -> float * int * Cvode.solver_result
Integrates the forward problem over an interval and saves checkpointing data. The arguments are the next time at which a solution is desired (tout) and a vector to receive the computed result (y). The function returns a triple tret, ncheck, sr: the time reached by the solver, the cumulative number of checkpoints stored, and whether tout was reached. The solver takes internal steps until it has reached or just passed the tout parameter (CV_NORMAL), it then interpolates to approximate y(tout).
Raises
See sundials: CVodeF
val forward_one_step : ('d, 'k) Cvode.session ->
float -> ('d, 'k) Nvector.t -> float * int * Cvode.solver_result
Integrates the forward problem over an interval and saves checkpointing data. The arguments are the next time at which a solution is desired (tout) and a vector to receive the computed result (yret). The function returns a triple tret, ncheck, sr: the time reached by the solver, the cumulative number of checkpoints stored, and whether tout was reached. The solver takes one step (CV_ONE_STEP) and returns the solution reached.
Raises
See sundials: CVodeF

Linear solvers


type ('data, 'kind) linear_solver = ('data, 'kind) AdjointTypes.linear_solver 
Linear solvers used in backward problems.
See sundials: Linear Solver Initialization Functions
type [> Nvector_serial.kind ] serial_linear_solver = (Nvector_serial.data, [> Nvector_serial.kind ] as 'a)
linear_solver
Alias for linear solvers that are restricted to serial nvectors.
type 'd triple = 'd * 'd * 'd 
Workspaces with three temporary vectors.
type ('t, 'd) jacobian_arg = ('t, 'd) AdjointTypes.jacobian_arg = {
   jac_t : float; (*
The independent variable.
*)
   jac_y : 'd; (*
The forward solution vector.
*)
   jac_yb : 'd; (*
The backward solution vector.
*)
   jac_fyb : 'd; (*
The backward right-hand side function fB.
*)
   jac_tmp : 't; (*
Temporary storage vectors.
*)
}
Arguments common to Jacobian callback functions.
See sundials: CVDlsDenseJacFnB
See sundials: CVDlsBandJacFnB
See sundials: CVSpilsJacTimesVecFnB
See sundials: CVSpilsPrecSolveFnB
See sundials: CVSpilsPrecSetupFnB
type bandrange = bandrange = {
   mupper : int; (*
The upper half-bandwidth.
*)
   mlower : int; (*
The lower half-bandwidth.
*)
}
The range of nonzero entries in a band matrix.
module Diag: sig .. end
Diagonal approximation of Jacobians by difference quotients.
module Dls: sig .. end
Direct Linear Solvers operating on dense and banded matrices.
module Sls: sig .. end
Sparse Linear Solvers.
module Spils: sig .. end
Scaled Preconditioned Iterative Linear Solvers.

Backward solutions


type 'd brhsfn_args = 'd AdjointTypes.brhsfn_args = {
   t : float; (*
The value of the independent variable.
*)
   y : 'd; (*
The vector of dependent-variable values $y(t)$.
*)
   yb : 'd; (*
The vector of backward dependent-variable values $y_B(t)$.
*)
}
Arguments common to Cvodes.Adjoint.brhsfn_no_sens and Cvodes.Adjoint.brhsfn_with_sens.
type 'd brhsfn_no_sens = 'd brhsfn_args -> 'd -> unit 
Backward functions without forward sensitivities. 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.

See sundials: CVRhsFnB
See sundials: Eq 2.19, Adjoint sensitivity analysis
type 'd brhsfn_with_sens = 'd brhsfn_args -> 'd array -> 'd -> unit 
Backward functions with forward sensitivities. 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.

See sundials: CVRhsFnBS
See sundials: Eq 2.21, Adjoint sensitivity analysis
type 'd brhsfn = 
| NoSens of 'd brhsfn_no_sens (*
No dependency on forward sensitivities.
*)
| WithSens of 'd brhsfn_with_sens (*
Dependency on forward sensitivities.
*)
Functions that evaluate the right-hand side of a backward ODE system with or without forward sensitivities.
type ('d, 'k) tolerance = 
| SStolerances of float * float (*
(rel, abs) : scalar relative and absolute tolerances.
*)
| SVtolerances of float * ('d, 'k) Nvector.t (*
(rel, abs) : scalar relative and vector absolute tolerances.
*)
Tolerance specifications.
type ('data, 'kind) iter = 
| Newton of ('data, 'kind) linear_solver (*
Newton iteration with a given linear solver
*)
| Functional (*
Functional iteration (non-stiff systems only)
*)
Choice of method for solving non-linear systems that arise in solver formulas.
See sundials: CVodeCreateB
val init_backward : ('d, 'k) Cvode.session ->
Cvode.lmm ->
('d, 'k) iter ->
('d, 'k) tolerance ->
'd brhsfn ->
float -> ('d, 'k) Nvector.t -> ('d, 'k) bsession
Creates and initializes a backward session attached to an existing (forward) session. The call
init_backward s lmm iter tol fb tb0 yb0
has as arguments: This function does everything necessary to initialize a backward session, i.e., it makes the calls referenced below. The Cvodes.Adjoint.backward_normal and Cvodes.Adjoint.backward_one_step functions may be called directly.
Raises
See sundials: CVodeCreateB
See sundials: CVodeInitB
See sundials: CVodeInitBS
See sundials: CVodeSStolerancesB
See sundials: CVodeSVtolerancesB
module Quadrature: sig .. end
Support for backward quadrature equations that may or may not depend on forward sensitivities.
val backward_normal : ('d, 'k) Cvode.session -> float -> unit
Integrates a backward ODE system over an interval. The solver takes internal steps until it has reached or just passed the specified value.
Raises
See sundials: CVodeB (CV_NORMAL)
val backward_one_step : ('d, 'k) Cvode.session -> float -> unit
Like Cvodes.Adjoint.backward_normal but returns after one internal solver step.
See sundials: CVodeB (CV_ONE_STEP)
val get : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> float
Fills the given vector with the solution of the backward ODE problem at the returned time, interpolating if necessary.
See sundials: CVodeGetB
val get_dky : ('d, 'k) bsession ->
('d, 'k) Nvector.t -> float -> int -> unit
Returns the interpolated solution or derivatives. get_dky s dkyb t k computes the kth derivative of the backward function at time t, i.e., $\frac{d^\mathtt{k}y_B(\mathtt{t})}{\mathit{dt}^\mathtt{k}}$, and stores it in dkyb. The arguments must satisfy $t_n - h_u \leq \mathtt{t} \leq t_n$—where $t_n$ denotes Cvodes.Adjoint.get_current_time and $h_u$ denotes Cvodes.Adjoint.get_last_step,— and $0 \leq \mathtt{k} \leq q_u$—where $q_u$ denotes Cvodes.Adjoint.get_last_order.

This function may only be called after a successful return from either Cvodes.Adjoint.backward_normal or Cvodes.Adjoint.backward_one_step.

Raises
See sundials: CVodeGetDky
See sundials: CVodeGetAdjIDABmem
val get_y : ('d, 'k) Cvode.session -> ('d, 'k) Nvector.t -> float -> unit
Fills the vector with the interpolated forward solution at the given time during a backward simulation.
See sundials: CVodeGetAdjY
val reinit : ('d, 'k) bsession ->
?iter_type:('d, 'k) iter ->
float -> ('d, 'k) Nvector.t -> unit
Reinitializes the backward problem with new parameters and state values. The values of the independent variable, i.e., the simulation time, and the state variables must be given. It is also possible to change the solution method (and linear solver).
Raises
See sundials: CVodeReInitB

Modifying the solver (optional input functions)


val set_no_sensitivity : ('d, 'k) Cvode.session -> unit
Cancels the storage of sensitivity checkpointing data during forward solution (with Cvodes.Adjoint.forward_normal or Cvodes.Adjoint.forward_one_step).
See sundials: CVodeAdjSetNoSensi
val set_tolerances : ('d, 'k) bsession -> ('d, 'k) tolerance -> unit
Sets the integration tolerances for the backward problem.
See sundials: CVodeSStolerancesB
See sundials: CVodeSVtolerancesB
val set_max_ord : ('d, 'k) bsession -> int -> unit
Specifies the maximum order of the linear multistep method.
See sundials: CVodeSetMaxOrdB
val set_max_num_steps : ('d, 'k) bsession -> int -> unit
Specifies the maximum number of steps taken in attempting to reach a given output time.
See sundials: CVodeSetMaxNumStepsB
val set_init_step : ('d, 'k) bsession -> float -> unit
Specifies the initial step size.
See sundials: CVodeSetInitStepB
val set_min_step : ('d, 'k) bsession -> float -> unit
Specifies a lower bound on the magnitude of the step size.
See sundials: CVodeSetMinStepB
val set_max_step : ('d, 'k) bsession -> float -> unit
Specifies an upper bound on the magnitude of the step size.
See sundials: CVodeSetMaxStepB
val set_stab_lim_det : ('d, 'k) bsession -> bool -> unit
Indicates whether the BDF stability limit detection algorithm should be used.
See sundials: CVodeSetStabLimDet

Querying the solver (optional output functions)


val get_work_space : ('d, 'k) bsession -> int * int
Returns the real and integer workspace sizes.
Returns (real_size, integer_size)
See sundials: CVodeGetWorkSpace
See sundials: CVodeGetAdjCVodeBmem
val get_num_steps : ('d, 'k) bsession -> int
Returns the cumulative number of internal steps taken by the solver.
See sundials: CVodeGetNumSteps
See sundials: CVodeGetAdjCVodeBmem
val get_num_rhs_evals : ('d, 'k) bsession -> int
Returns the number of calls to the backward right-hand side function.
See sundials: CVodeGetNumRhsEvals
See sundials: CVodeGetAdjCVodeBmem
val get_num_lin_solv_setups : ('d, 'k) bsession -> int
Returns the number of calls made to the linear solver's setup function.
See sundials: CVodeGetNumLinSolvSetups
See sundials: CVodeGetAdjCVodeBmem
val get_num_err_test_fails : ('d, 'k) bsession -> int
Returns the number of local error test failures that have occurred.
See sundials: CVodeGetNumErrTestFails
See sundials: CVodeGetAdjCVodeBmem
val get_last_order : ('d, 'k) bsession -> int
Returns the integration method order used during the last internal step.
See sundials: CVodeGetLastOrder
See sundials: CVodeGetAdjCVodeBmem
val get_current_order : ('d, 'k) bsession -> int
Returns the integration method order to be used on the next internal step.
See sundials: CVodeGetCurrentOrder
See sundials: CVodeGetAdjCVodeBmem
val get_last_step : ('d, 'k) bsession -> float
Returns the integration step size taken on the last internal step.
See sundials: CVodeGetLastStep
See sundials: CVodeGetAdjCVodeBmem
val get_current_step : ('d, 'k) bsession -> float
Returns the integration step size to be attempted on the next internal step.
See sundials: CVodeGetCurrentStep
See sundials: CVodeGetAdjCVodeBmem
val get_actual_init_step : ('d, 'k) bsession -> float
Returns the the value of the integration step size used on the first step.
See sundials: CVodeGetActualInitStep
See sundials: CVodeGetAdjCVodeBmem
val get_current_time : ('d, 'k) bsession -> float
Returns the the current internal time reached by the solver.
See sundials: CVodeGetCurrentTime
See sundials: CVodeGetAdjCVodeBmem
val get_num_stab_lim_order_reds : ('d, 'k) bsession -> int
Returns the number of order reductions dictated by the BDF stability limit detection algorithm.
See sundials: CVodeGetNumStabLimOrderReds
See sundials: CVodeGetAdjCVodeBmem
See sundials: BDF stability limit detection
val get_tol_scale_factor : ('d, 'k) bsession -> float
Returns a suggested factor by which the user's tolerances should be scaled when too much accuracy has been requested for some internal step.
See sundials: CVodeGetTolScaleFactor
See sundials: CVodeGetAdjCVodeBmem
val get_err_weights : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> unit
Returns the solution error weights at the current time.
See sundials: CVodeGetErrWeights
See sundials: CVodeGetAdjCVodeBmem
See sundials: IVP solution (W_i)
val get_est_local_errors : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> unit
Returns the vector of estimated local errors.
See sundials: CVodeGetEstLocalErrors
See sundials: CVodeGetAdjCVodeBmem
val get_integrator_stats : ('d, 'k) bsession -> Cvode.integrator_stats
Returns the integrator statistics as a group.
See sundials: CVodeGetIntegratorStats
See sundials: CVodeGetAdjCVodeBmem
val print_integrator_stats : ('d, 'k) bsession -> Pervasives.out_channel -> unit
Prints the integrator statistics on the given channel.
See sundials: CVodeGetIntegratorStats
See sundials: CVodeGetAdjCVodeBmem
val get_num_nonlin_solv_iters : ('d, 'k) bsession -> int
Returns the number of nonlinear (functional or Newton) iterations performed.
See sundials: CVodeGetNumNonlinSolvIters
See sundials: CVodeGetAdjCVodeBmem
val get_num_nonlin_solv_conv_fails : ('d, 'k) bsession -> int
Returns the number of nonlinear convergence failures that have occurred.
See sundials: CVodeGetNumNonlinSolvConvFails
See sundials: CVodeGetAdjCVodeBmem
val get_nonlin_solv_stats : ('d, 'k) bsession -> int * int
Returns both the numbers of nonlinear iterations performed nniters and nonlinear convergence failures nncfails.
Returns (nniters, nncfails)
See sundials: CVodeGetNonlinSolvStats
See sundials: CVodeGetAdjCVodeBmem

Exceptions


exception AdjointNotInitialized
Adjoint sensitivity analysis was not initialized.
See sundials: CV_NO_ADJ
exception NoForwardCall
Neither Cvodes.Adjoint.forward_normal nor Cvodes.Adjoint.forward_one_step has been called.
See sundials: CV_NO_FWD
exception ForwardReinitFailure
Reinitialization of the forward problem failed at the first checkpoint (corresponding to the initial time of the forward problem).
See sundials: CV_REIFWD_FAIL
exception ForwardFailure
An error occured when integrating the forward problem from a checkpoint.
See sundials: CV_FWD_FAIL
exception NoBackwardProblem
No backward problem has been created.
See sundials: CV_NO_BCK
exception BadFinalTime
The final time was outside the interval over which the forward problem was solved.
See sundials: CV_BAD_TB0