DynamicBoundsBase.jl: An extensible abstraction layer for DynamicBounds

Current supported problem types and constructors:

DynamicBoundsBase.ODERelaxProbType
mutable struct ODERelaxProb{F, JX, JP, xType, K} <: AbstractODERelaxProblem

A structure used to hold a parametric ODEs problem.

  • f::Any

    Right-hand side function.

  • Jx!::Any

    Jacobian of rhs w.r.t x.

  • Jp!::Any

    Jacobian of rhs w.r.t p.

  • x0::Any

    Initial condition function.

  • xL::Vector{Float64}

    Lower constant state bound storage.

  • xU::Vector{Float64}

    Upper constant state bound storage.

  • tspan::Tuple{Float64, Float64}

    Time span of integration.

  • tsupports::Vector{Float64}

    Support points: Points 'x' values will be queried.

  • p::Vector{Float64}

    Point to relax/bound in over the decision space.

  • pL::Vector{Float64}

    Lower bounds of the decision space.

  • pU::Vector{Float64}

    Upper bounds of the decision space.

  • user_Jx::Bool

    Problem has a user-defined Jacobian of the rhs w.r.t x

  • user_Jp::Bool

    Problem has a user-defined Jacobian of the rhs w.r.t p

  • user_state_bnd::Bool

    Constant user state bounds have been set

  • variable_state_bnd::Bool

    Variable user state bounds have been set

  • nx::Int64

    State space dimension

  • np::Int64

    Decision space dimension

  • params::Vector{Float64}

    Optional keywork argument: Indicates the rhs function and the initial condition function take an additional argument param. For example, it is now f!(dx, x, p, param).

  • polyhedral_constraint::Union{Nothing, PolyhedralConstraint}

    Storage for polyhedral constraint, if any

  • constant_state_bounds::Union{Nothing, ConstantStateBounds}

    Storage for the constant state bounds, if any

  • support_set::SupportSet{Float64}

    The support set if used

  • kwargs::Any

    Additional keyword arguments

Problem attributes

DynamicBoundsBase.HasStateBoundsType
struct HasStateBounds <: AbstractRelaxProblemAttribute

A problem attribute used to check whether state bounds are defined.

DynamicBoundsBase.HasUserJacobianType
struct HasUserJacobian <: AbstractRelaxProblemAttribute

A problem attribute used to check whether a user-defined jacobian was specified.

DynamicBoundsBase.ConstantStateBoundsType
struct ConstantStateBounds <: AbstractRelaxProblemAttribute

A problem attribute used to store constant state bounds.

  • xL::Vector{Float64}

    Lower state variable bounds

  • xU::Vector{Float64}

    Upper state variable bounds

DynamicBoundsBase.VariableStateBoundsType
struct VariableStateBounds{F1<:Function, F2<:Function} <: AbstractRelaxProblemAttribute

A problem attribute used to store time-varying state bounds.

  • xL::Function

    Lower state variable bounds

  • xU::Function

    Upper state variable bounds

Abstract Integrator Types

DynamicBoundsBase.AbstractODERelaxIntegratorType
abstract type AbstractODERelaxIntegrator <: AbstractDERelaxIntegrator

Abstract supertype for any integrator that constructs relaxations of an ordinary differential equation problem.

Bound locations for use with attributes such as Relaxation, Bound, Gradient. For Gradient{T<:AbstractBoundLoc}, T = Lower indicates the gradient of the lower relaxation (that is the convex relaxation) should be returned, T = Upper indicates that the upper relaxation (the concave relaxation) should be returned, T = Nominal indicates that the gradient of the local evaluation of the relaxation should be returned at the present parameter value.

DynamicBoundsBase.LowerType
struct Lower <: AbstractBoundLoc

Indicates the lower bound, relaxation, or (sub)gradient should be returned.

DynamicBoundsBase.UpperType
struct Upper <: AbstractBoundLoc

Indicates the upper bound, relaxation, or (sub)gradient should be returned.

DynamicBoundsBase.NominalType
struct Nominal <: AbstractBoundLoc

Indicates the nominal value or (sub)gradient should be returned.

Integrator attributes

DynamicBoundsBase.IntegratorNameType
struct IntegratorName <: AbstractIntegratorAttribute

An integrator attribute for the string identifying the integration scheme.

DynamicBoundsBase.IsNumericType
struct IsNumeric <: AbstractIntegratorAttribute

An integrator attribute for indicating bounds/relaxations are of numeric solution.

DynamicBoundsBase.IsSolutionSetType
struct IsSolutionSet <: AbstractIntegratorAttribute

An integrator attribute for indicating bounds & relaxations are of exact solution.

DynamicBoundsBase.TerminationStatusType
struct TerminationStatus <: AbstractIntegratorAttribute

A integrator attribute used to query the TerminationStatusCode of the integrator on completion. Current termination status codes are:

  • COMPLETED: The algorithm terminate successfully with bounds and relaxations.
  • EMPTY: The algorithm terminated successfully but the solution set was empty for some points in tspan.
  • NAN: The algorithm terminated but some values are not a number (usually indicating a domain violation was encoutered when computing relaxations).
  • RELAXATION_NOT_CALLED: The relaxation has not yet been computed.
  • NUMERICAL_ERROR: A numerical error was encountered.
  • LIMIT_EXCEEDED: A preset limit was exceeded (number of steps and so on).
  • INVALID_OPTION: An invalid option was set.
  • OTHER_ERROR: Another error was encountered.
DynamicBoundsBase.ValueType
struct Value <: AbstractIntegratorAttribute

An integrator attribute for value of local solution bounds.

DynamicBoundsBase.SupportSetType
struct SupportSet{T<:AbstractFloat} <: AbstractIntegratorAttribute

A integrator attribute used to access independent variable support set.

DynamicBoundsBase.ParameterBoundType
struct ParameterBound{T<:AbstractBoundLoc} <: AbstractIntegratorAttribute

A integrator attribute used to access the current parameter value.

DynamicBoundsBase.BoundType
struct Bound{T<:AbstractBoundLoc} <: AbstractIntegratorAttribute

An integrator attribute for state bounds.

DynamicBoundsBase.RelaxationType
struct Relaxation{T<:AbstractBoundLoc} <: AbstractIntegratorAttribute

An integrator attribute for relaxations.

DynamicBoundsBase.GradientType
struct Gradient{T<:AbstractBoundLoc} <: AbstractIntegratorAttribute

An integrator attribute for the Gradient.

DynamicBoundsBase.SubgradientType
struct Subgradient{T<:AbstractBoundLoc} <: AbstractIntegratorAttribute

An integrator attribute for the Subgradient.

DynamicBoundsBase.LocalIntegratorType
struct LocalIntegrator <: AbstractIntegratorAttribute

Retreives the LocalIntegrator that corresponds to the integration method used by the integrator.

DynamicBoundsBase.LocalSensitivityOnType
struct LocalSensitivityOn <: AbstractIntegratorAttribute

Set to true if integrator should compute derivatives wrt p for the local ode integration.

The following constructors for integrator attributes are given below with T<:AbstractBoundLoc. The TimeIndex constructor is used to specify that the time point referenced using an integer (i.e. the first, second, or fifth time in the support set). The subgradient of the concave relaxation at the third point in the support set is then referenced using the command Subgradient{Upper}(TimeIndex(3)) whereas the subgradient of the concave relaxation at time 0.35 is referenced using Subgradient{Upper}(0.35). A full list of the AbstractIntegratorAttribute structures using this constructor are list below:

Gradient{T}(i::TimeIndex)
Gradient{T}(x::Float64)
Subgradient{T}(i::TimeIndex)
Subgradient{T}(x::Float64)
Bound{T}(i::TimeIndex)
Bound{T}(x::Float64)
Relaxation{T}(i::TimeIndex)
Relaxation{T}(x::Float64)

Access and Interface Functions:

DynamicBoundsBase.supportsFunction

supports

Return a Bool indicating whether ::AbstractDERelaxIntegrator supports the ::Union{AbstractDERelaxIntegrator, AbstractDERelaxProblem}.

Base.getFunction

get

Returns the value of attribute set for the ::Union{AbstractDERelaxIntegrator, AbstractDERelaxProblem}. May be vector valued.

DynamicBoundsBase.getallFunction

getall

An version of get which retreives all data asssociated with a particular integrator attribute.

DynamicBoundsBase.getall!Function

getall!

An in-place version of get! which retreives all data asssociated with a particular integrator attribute.

DynamicBoundsBase.set!Function

set!

Assigns a value to the attr attribute of the integrator, problem, or relaxation.

DynamicBoundsBase.setall!Function

setall!

An in-place version of set! which sets all data asssociated with a particular integrator attribute.

DynamicBoundsBase.relax!Function

relax!

Computes the relaxation at the current parameter value with the current parameter and state bounds.

General utilities:

DynamicBoundsBase.IntegratorStatesType
mutable struct IntegratorStates

A structure that holds the state of the integrator.

  • first_pnt_eval::Bool

    Has the first point been evaluated

  • new_decision_box::Bool

    Have the box-constraints changed since the last evaluation

  • new_decision_pnt::Bool

    Has the decision point changed since the last evaluation

  • set_lower_state::Bool

    The relaxed problem has been updated

  • set_upper_state::Bool

    The local problem has been updated

  • termination_status::TerminationStatusCode

    How did the integrator terminate

DynamicBoundsBase.NotAllowedErrorType

NotAllowedError <: Exception

Abstract type for error thrown when an operation is supported but cannot be applied in the current state of the integrator .

DynamicBoundsBase.UnsupportedRelaxAttributeType
struct UnsupportedRelaxAttribute{AttrType<:Union{AbstractIntegratorAttribute, AbstractRelaxProblemAttribute}} <: UnsupportedError

An error indicating that the attribute attr is unsupported.

DynamicBoundsBase.SetRelaxAttributeNotAllowedType
struct SetRelaxAttributeNotAllowed{AttrType<:Union{AbstractIntegratorAttribute, AbstractRelaxProblemAttribute}} <: NotAllowedError

An error indicating that the attribute attr is supported but cannot be set for some reason given in the error string.