Previous  Up  

Module Idas.Adjoint

module Adjoint: sig .. end

(Adjoint) Sensitivity analysis of DAEs 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
type ('d, 'k) bsession = ('d, 'k) AdjointTypes.bsession

A backward session with the IDAS solver. Multiple backward sessions may be associated with a single parent session.

type [> Nvector_serial.kind ] serial_bsession = (Sundials.RealArray.t, [> Nvector_serial.kind ] as 'a) bsession

Alias for backward sessions based on serial nvectors.

Forward solution

type interpolation =
| IPolynomial (*

(IDA_POLYNOMIAL)

*)
| IHermite (*

(IDA_HERMITE)

*)

Specifies the type of interpolation to use between checkpoints.

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

val forward_normal : ('d, 'k) Ida.session ->
       float ->
       ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> float * int * Ida.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 two vectors to receive the computed results (y and 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 (IDA_NORMAL), it then interpolates to approximate y(tout).

val forward_one_step : ('d, 'k) Ida.session ->
       float ->
       ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> float * int * Ida.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 two vectors to receive the computed results (y and 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 one step (IDA_ONE_STEP) and returns the solution reached.

Linear solvers

type ('data, 'kind) linear_solver = ('data, 'kind) AdjointTypes.linear_solver

Linear solvers used in backward problems.

type [> Nvector_serial.kind ] serial_linear_solver = (Sundials.RealArray.t, [> 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_y' : 'd; (*

The forward derivatives vector.

*)
   jac_yb : 'd; (*

The backward solution vector.

*)
   jac_yb' : 'd; (*

The backward derivatives vector.

*)
   jac_resb : 'd; (*

The current residual for the backward problem.

*)
   jac_coef : float; (*

The scalar $c_\mathit{jB}$ in the system Jacobian, proportional to the inverse of the step size.

*)
   jac_tmp : 't; (*

Workspace data.

*)
}

Arguments common to Jacobian callback functions.

module Dls: sig .. end

Direct Linear Solvers operating on dense, banded, and sparse matrices.

module Spils: sig .. end

Scaled Preconditioned Iterative Linear Solvers

val matrix_embedded_solver : (unit, 'data, 'kind, [> `MatE ]) Sundials.LinearSolver.t ->
       ('data, 'kind) linear_solver

Create an IDA-specific linear solver from a generic matrix embedded solver.

Backward solutions

type 'd bresfn_args = 'd AdjointTypes.bresfn_args = {
   t : float; (*

The value of the independent variable.

*)
   y : 'd; (*

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

*)
   y' : 'd; (*

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

*)
   yb : 'd; (*

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

*)
   yb' : 'd; (*

The vector of backward dependent-variable derivatives $\dot{y}_B(t)$ .

*)
}

Arguments for backward functions.

type 'd bresfn_no_sens = 'd bresfn_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.

Vectors held in this function's arguments should not be accessed after the function returns.

type 'd bresfn_with_sens = 'd bresfn_args -> 'd array -> '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.

Vectors held in this function's arguments should not be accessed after the function returns.

type 'd bresfn =
| NoSens of 'd bresfn_no_sens (*

No dependency on forward sensitivities.

*)
| WithSens of 'd bresfn_with_sens (*

Dependency on forward sensitivities.

*)

Functions that evaluate the right-hand side of a backward DAE 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.

val init_backward : ('d, 'k) Ida.session ->
       ('d, 'k) tolerance ->
       ?nlsolver:('d, 'k, ('d, 'k) Idas.session, [ `Nvec ])
                 Sundials.NonlinearSolver.t ->
       lsolver:('d, 'k) linear_solver ->
       'd bresfn ->
       ?varid:('d, 'k) Nvector.t ->
       float ->
       ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> ('d, 'k) bsession

Creates and initializes a backward session attached to an existing (forward) session. The call

init_backward s linsolv tol fb tb0 yb0 yb0'

has as arguments:

This function does everything necessary to initialize a backward session, i.e., it makes the calls referenced below. The Idas.Adjoint.backward_normal and Idas.Adjoint.backward_one_step functions may be called directly.

If an nlsolver is not specified, then the Newton module is used by default. The nlsolver must be of type RootFind, otherwise an Ida.IllInput exception is raised.

module Quadrature: sig .. end

Support for backward quadrature equations that may or may not depend on forward sensitivities.

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

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

Like Idas.Adjoint.backward_normal but returns after one internal solver step.

val get : ('d, 'k) bsession ->
       ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> float

Fills the given vectors, yb and yb', with the solution of the backward DAE problem at the returned time, interpolating if necessary.

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 Idas.Adjoint.get_current_time and $h_u$ denotes Idas.Adjoint.get_last_step,— and $0 \leq \mathtt{k} \leq q_u$—where $q_u$ denotes Idas.Adjoint.get_last_order.

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

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

Fills the vector with the interpolated forward solution and its derivative at the given time during a backward simulation.

val reinit : ('d, 'k) bsession ->
       ?nlsolver:('d, 'k, ('d, 'k) Idas.session, [ `Nvec ])
                 Sundials.NonlinearSolver.t ->
       ?lsolver:('d, 'k) linear_solver ->
       float -> ('d, 'k) Nvector.t -> ('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 and derivatives must be given. It is also possible to change the linear solver.

Initial Condition Calculation

val set_id : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> unit

Class components of the state vector as either algebraic or differential. These classifications are required by Idas.Adjoint.calc_ic, Idas.Adjoint.calc_ic_sens, and Idas.Adjoint.set_suppress_alg. See also Ida.VarId.

val set_suppress_alg : ('d, 'k) bsession -> ?varid:('d, 'k) Nvector.t -> bool -> unit

Indicates whether or not to ignore algebraic variables in the local error test. When ignoring algebraic variables (true), a varid vector must be specified either in the call or by a prior call to Idas.Adjoint.init or Idas.Adjoint.set_id. Suppressing local error tests for algebraic variables is discouraged for DAE systems of index 1 and encouraged for systems of index 2 or more.

val calc_ic : ('d, 'k) bsession ->
       ?yb:('d, 'k) Nvector.t ->
       ?yb':('d, 'k) Nvector.t ->
       float -> ('d, 'k) Nvector.t -> ('d, 'k) Nvector.t -> unit

Computes the algebraic components of the initial state and the differential components of the derivative vectors for certain index-one problems. The elements of $y_B$ marked algebraic and of $\dot{y}_B$ marked differential are computed from the differential components of $y_B$, to satisfy the constraint $F(t_0, y_0, \dot{y}_0, y_\mathit{B0}, \dot{y}_\mathit{B0}) = 0$. The variable ids must be given in ~varid or by a prior call to Idas.Adjoint.init or Idas.Adjoint.set_id. The call calc_ic s ~yb ~yb' tbout0 y0 dy0 gives the first value at which a solution will be requested tbout0, and the vectors of forward solutions y0 and forward derivatives dy0. If given, the ~yb and ~yb' vectors are filled with the corrected backward states and derivatives. A Idas.Adjoint.reinit is required before calling this function after Idas.Adjoint.forward_normal or Idas.Adjoint.forward_one_step.

val calc_ic_sens : ('d, 'k) bsession ->
       ?yb:('d, 'k) Nvector.t ->
       ?yb':('d, 'k) Nvector.t ->
       ?varid:('d, 'k) Nvector.t ->
       float ->
       ('d, 'k) Nvector.t ->
       ('d, 'k) Nvector.t ->
       ('d, 'k) Nvector.t array -> ('d, 'k) Nvector.t array -> unit

Computes the algebraic components of the initial state and the differential components of the derivative vectors for certain index-one problems. The elements of $y_B$ marked algebraic and of $\dot{y}_B$ marked differential are computed from the differential components of $y_B$, to satisfy the constraint $F(t_0, y_0, \dot{y}_0, y_\mathit{B0}, \dot{y}_\mathit{B0}, s0, \dot{s}0) = 0$. The variable ids must be given in ~varid or by a prior call to Idas.Adjoint.init or Idas.Adjoint.set_id. The call calc_ic s ~yb ~yb' tbout0 y0 dy0 s0 ds0 gives the first value at which a solution will be requested tbout0, the vectors of forward solutions y0 and forward derivatives dy0, and arrays of vectors of sensitivities and sensitivity derivatives. If given, the ~yb and ~yb' vectors are filled with the corrected backward states and derivatives. A Idas.Adjoint.reinit is required before calling this function after Idas.Adjoint.forward_normal or Idas.Adjoint.forward_one_step.

Modifying the solver (optional input functions)

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

Cancels the storage of sensitivity checkpointing data during forward solution (with Idas.Adjoint.forward_normal or Idas.Adjoint.forward_one_step).

val set_max_ord : ('d, 'k) bsession -> int -> unit

Specifies the maximum order of the linear multistep method.

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.

val set_init_step : ('d, 'k) bsession -> float -> unit

Specifies the initial step size.

val set_max_step : ('d, 'k) bsession -> float -> unit

Specifies an upper bound on the magnitude of the step size.

val set_constraints : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> unit

Specifies a vector defining inequality constraints for each component of the solution vector u. See Sundials.Constraint.

val clear_constraints : ('d, 'k) bsession -> unit

Disables constraint checking.

Querying the solver (optional output functions)

val get_work_space : ('d, 'k) bsession -> int * int

Returns the real and integer workspace sizes.

val get_num_steps : ('d, 'k) bsession -> int

Returns the cumulative number of internal steps taken by the solver.

val get_num_res_evals : ('d, 'k) bsession -> int

Returns the number of calls to the backward residual function.

val get_num_lin_solv_setups : ('d, 'k) bsession -> int

Returns the number of calls made to the linear solver's setup function.

val get_num_err_test_fails : ('d, 'k) bsession -> int

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

val get_last_order : ('d, 'k) bsession -> int

Returns the integration method order used during the last internal step.

val get_current_order : ('d, 'k) bsession -> int

Returns the integration method order to be used on the next internal step.

val get_last_step : ('d, 'k) bsession -> float

Returns the integration step size taken on the last internal step.

val get_current_step : ('d, 'k) bsession -> float

Returns the integration step size to be attempted on the next internal step.

val get_actual_init_step : ('d, 'k) bsession -> float

Returns the the value of the integration step size used on the first step.

val get_current_time : ('d, 'k) bsession -> float

Returns the the current internal time reached by the solver.

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.

val get_err_weights : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> unit

Returns the solution error weights at the current time.

val get_est_local_errors : ('d, 'k) bsession -> ('d, 'k) Nvector.t -> unit

Returns the vector of estimated local errors.

val get_integrator_stats : ('d, 'k) bsession -> Ida.integrator_stats

Returns the integrator statistics as a group.

val print_integrator_stats : ('d, 'k) bsession -> Stdlib.out_channel -> unit

Prints the integrator statistics on the given channel.

val get_num_nonlin_solv_iters : ('d, 'k) bsession -> int

Returns the cumulative number of nonlinear (functional or Newton) iterations performed.

val get_num_nonlin_solv_conv_fails : ('d, 'k) bsession -> int

Returns the cumulative number of nonlinear convergence failures.

val get_nonlin_solv_stats : ('d, 'k) bsession -> int * int

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

Exceptions

exception AdjointNotInitialized

Adjoint sensitivity analysis was not initialized.

exception NoForwardCall

Neither Idas.Adjoint.forward_normal nor Idas.Adjoint.forward_one_step has been called.

exception ForwardReinitFailure

Reinitialization of the forward problem failed at the first checkpoint (corresponding to the initial time of the forward problem).

exception ForwardFailure

An error occured during the integration of the forward problem.

exception NoBackwardProblem

No backward problem has been created.

exception BadFinalTime

The final time was outside the interval over which the forward problem was solved.