Skip to content

Public API ​

This page lists exported symbols of OptimalControlProblems.Catalogue, OptimalControlProblems, OptimalControlProblems.Metadata, OptimalControlProblems.References, OptimalControlProblems.Modelings, OptimalControlProblems.Problems.


From OptimalControlProblems.Catalogue ​

OptimalControlProblems.Catalogue [Module] ​

OptimalControlProblems.Catalogue Module

The catalogue: one function per problem (beam, chain, …), whose methods for each modeling are defined by the extensions, the list of the problems available in some modelings with some status (problems), and the status of a problem in each modeling (status).

Depends on Modelings and Metadata.

source

problems [Function] ​

OptimalControlProblems.Catalogue.problems Function
julia
problems(; status) -> Vector{Symbol}

Returns the sorted list of optimal control problems.

Availability comes from the model files present in ext/<modeling>Models/; the status (:valid or :draft) of each problem in each modeling comes from its metadata.

  • problems(): problems having the requested status in at least one modeling.

  • problems(backend): problems available in that modeling with the requested status.

  • problems(backend1, backend2, ...): problems available in all the given modelings with the requested status, which is the list to use to compare modelings.

Keyword arguments

  • status::Symbol=:valid: :valid, :draft or :all.

Returns

  • Vector{Symbol}: A vector of problem names as symbols.

Example

julia
julia> OptimalControlProblems.problems(JuMPBackend(), OptimalControlBackend())
[:balanced_field, :beam, ...]
source

status [Function] ​

OptimalControlProblems.Catalogue.status Function
julia
status(problem::Symbol) -> Any

Return the status of problem in each modeling where it exists.

source

From OptimalControlProblems ​

OptimalControlProblems [Module] ​

OptimalControlProblems Module

A collection of optimal control problems, each available in one or more modelings (OptimalControl, its scalarized form, JuMP, ModelingToolkit), loaded by the extensions.

The code is split into submodules (ct-conventions MOD1, MOD2), in dependency order: Modelings, Metadata, References, Catalogue, Problems. The package re-exports their public API, which is the API of the package; what a submodule does not export is reached through it, e.g. OptimalControlProblems.Metadata.METADATA_SCHEMA. See src/README.md.

source

From OptimalControlProblems.Metadata ​

OptimalControlProblems.Metadata [Module] ​

OptimalControlProblems.Metadata Module

The metadata of the problems: the list of the problems (one file per problem in ext/MetaData/), the schema of a metadata file, loading and checking every file, and reading them: problem_metadata, grid_size_data, parameters_data, initial_guess_data. The analytic solutions used by some metadata files (reference_solution) are defined here too.

Depends on Modelings: the grid of a problem depends on the modeling (grid_size_data).

source

grid_size_data [Function] ​

OptimalControlProblems.Metadata.grid_size_data Function
julia
grid_size_data(
    problem::Symbol,
    backend::OptimalControlProblems.Modelings.AbstractModelBackend
) -> Any

Return the default number of steps of problem in the modeling of backend: the entry of the modeling in the field :grid_sizes of the metadata when there is one, otherwise the default of the modeling, the grid of the problem (the field :grid_size) but for ModelingToolkit, solved by shooting on a coarser grid (MODELING_TOOLKIT_GRID_SIZE).

The grid depends on the modeling: the modelings are independent (#435), so there is no grid of a problem without a modeling.

Example

julia
julia> grid_size_data(:beam, JuMPBackend())
500
source

initial_guess_data [Function] ​

OptimalControlProblems.Metadata.initial_guess_data Function
julia
initial_guess_data(problem::Symbol) -> Any
initial_guess_data(
    problem::Symbol,
    parameters::Union{Nothing, NamedTuple}
) -> Any

Return the initial guess of problem for its default parameters, merged with parameters if given: (state=…, control=…, variable=…), each component a constant, a vector, or a function of the time t.

The initial guess is shared by every modeling (#377): it is a function of the parameters in the metadata of the problem (ext/MetaData/<problem>.jl). The OptimalControl modelings pass it as is; JuMP evaluates it at the nodes of the scheme. Every modeling takes another one with the keyword init when the problem is built.

Example

julia
julia> OptimalControlProblems.initial_guess_data(:beam)
(state = [0.05, 0.1], control = 0.1)
source

parameters_data [Function] ​

OptimalControlProblems.Metadata.parameters_data Function
julia
parameters_data(problem::Symbol) -> Any

Return the parameter set associated with a given problem.

Arguments

  • problem::Symbol: the name of the problem whose parameters are requested.

Returns

  • ::Union{Nothing,NamedTuple}: the parameters of the problem, or nothing if none exist.

Example

julia
julia> parameters_data(:beam)
(t0 = 0, tf = 1, ...)
source
julia
parameters_data(
    problem::Symbol,
    parameters::Union{Nothing, NamedTuple}
) -> Any

Return the parameter set associated with a given problem, optionally merged with user-supplied parameters.

Arguments

  • problem::Symbol: the name of the problem.

  • parameters::Union{Nothing,NamedTuple}: user-supplied parameters to override or extend the defaults. If nothing, returns the default parameters unchanged.

Returns

  • ::Union{Nothing,NamedTuple}: the merged parameters. Throws CTBase.Exceptions.PreconditionError if parameters are given to a problem that has none.

Example

julia
julia> parameters_data(:beam, (tf = 2,))
(t0 = 0, tf = 2, ...)
source

problem_metadata [Function] ​

OptimalControlProblems.Metadata.problem_metadata Function
julia
problem_metadata(

) -> OrderedCollections.OrderedDict{Symbol, OrderedCollections.OrderedDict}

Return the dictionary containing the metadata of all available optimal control problems.

Example

julia
julia> problem_metadata()
source
julia
problem_metadata(
    problem::Symbol
) -> OrderedCollections.OrderedDict

Return a dictionary containing the metadata of problem, without building it.

The metadata of a built problem is read with metadata(pb) on the Problem. The following keys are valid:

  • grid_size::Int: the default number of steps of the problem, the grid of the modelings but for ModelingToolkit (see grid_size_data). For example:
julia
:grid_size => 500,
  • grid_sizes::NamedTuple (optional): the number of steps of the problem in some modelings, where it differs from the default of the modeling (see grid_size_data). For example:
julia
:grid_sizes => (ModelingToolkit=100,),
  • parameters::Union{Nothing,NamedTuple}: the list of parameters. For example:
julia
:parameters => (
    t0 = 0,
    tf = 1,
    x₁_l = 0,
    x₁_u = 0.1,
    x₁_t0 = 0,
    x₂_t0 = 1,
    x₁_tf = 0,
    x₂_tf = -1,
),
  • parameter_info: the unit and the meaning of each parameter, in the order of parameters; unit is nothing for a dimensionless parameter. For example:
julia
:parameter_info => (
    t0 = (unit = "s", meaning = "initial time"),
    x₁_u = (unit = nothing, meaning = "upper bound of the state x₁"),
    ...
),
  • status: the status (:valid or :draft) of the problem in each modeling.

  • init: the initial guess of every modeling, a function of the parameters (see OptimalControlProblems.initial_guess_data).

  • reference_solution (optional): the analytic solution of the continuous problem, a function of the parameters; see OptimalControlProblems.reference_solution_data.

Example

julia
julia> data = problem_metadata(:beam)
julia> data[:grid_size]
500
source

From OptimalControlProblems.References ​

OptimalControlProblems.References [Module] ​

OptimalControlProblems.References Module

The references of the problems: the reference objectives and the known solutions of each problem, read from ext/MetaData/references/<problem>.toml (generated by tools/references/update.jl), and the analytic solutions of the continuous problems: reference_objective, solution_kind, reference_solution_data, SAME_SOLUTION. Each known solution says how it was obtained, as a NumericalReference; an analytic solution is an AnalyticReference (#409): references, best_reference, analytic_reference, and objective(ref).

Depends on Modelings (the references of each modeling are independent) and Metadata, whose metadata it completes with the field :reference_objective.

source

AbstractReference [Abstract Type] ​

OptimalControlProblems.References.AbstractReference Type
julia
abstract type AbstractReference

A reference solution of a problem: its objective, read with objective(ref).

Two kinds, with different data: AnalyticReference, the solution of the continuous problem, and NumericalReference, a solve of the discretized problem.

source

AnalyticReference [Struct] ​

OptimalControlProblems.References.AnalyticReference Type
julia
struct AnalyticReference{S, U} <: OptimalControlProblems.References.AbstractReference

The analytic solution of the continuous problem problem for parameters (#379): state and control, functions of the time, the objective, and the source it comes from. The objective of a discretized problem differs from it by the discretization error.

Fields

  • problem::Symbol: Name of the problem.

  • parameters::Union{Nothing, NamedTuple}: Parameters of the problem the solution is for.

  • objective::Float64: Objective of the continuous problem.

  • state::Any: State, a function of the time.

  • control::Any: Control, a function of the time.

  • source::String: Where the solution comes from (a publication).

source

NumericalReference [Struct] ​

OptimalControlProblems.References.NumericalReference Type
julia
struct NumericalReference <: OptimalControlProblems.References.AbstractReference

A known solution of the problem problem discretized on grid_size steps with scheme (#378), and how it was obtained (#409): one of the solves that reached it, chosen to represent it (a strict convergence before an acceptable one, then the smallest constraint violation), with its modeling, modeler, solver and every option of the solver, its exit status, iterations, time and constraint violation, and the environment of its run.

Generated by tools/references/update.jl from the convergence and robustness tests. The trajectories are not kept: the configuration is enough to solve again.

Fields

  • problem::Symbol: Name of the problem.

  • scheme::Symbol: Discretization scheme, e.g. :trapeze.

  • grid_size::Int64: Number of steps of the grid.

  • objective::Float64: Objective of the solve.

  • solves::Int64: Number of solves, every modeling, configuration and platform, that reached the solution.

  • configurations::Vector{String}: The configurations that reached it, "<modeling> <configuration>".

  • modeling::Symbol: Modeling of the solve, e.g. :OptimalControl.

  • configuration::String: Configuration of the solve, as the tests name it.

  • modeler::Union{Nothing, Symbol}: Modeler of the solve (:adnlp, :exa), nothing for JuMP.

  • solver::Symbol: Solver of the solve, e.g. :ipopt.

  • options::NamedTuple: Every option given to the solver, defaults included.

  • status::Symbol: Exit status of the solver, e.g. :first_order, :LOCALLY_SOLVED, :acceptable.

  • iterations::Int64: Number of iterations.

  • time::Float64: Solve time in seconds, on platform.

  • violation::Float64: Largest violation of the constraints, as the modeling measures it.

  • platform::String: Platform of the run, e.g. cron-OptimalControl-1.13-ubuntu-latest.

  • run::String: The run that solved it (a GitHub Actions run), or local.

  • commit::String: Commit of the package.

  • julia::VersionNumber: Julia version.

  • machine::@NamedTuple{os::String, arch::String, cpu::String}: Operating system, architecture and processor of the platform.

  • versions::NamedTuple: Versions of the packages that modeled, discretized and solved it.

source

SAME_SOLUTION [Constant] ​

OptimalControlProblems.References.SAME_SOLUTION Constant

Relative gap below which two objectives are the same solution (#378): above the accuracy of the solvers at the tolerance of the tests (about 1e-6 at tol = 1e-8), below the gap between the known local solutions (1.6e-4 on mountain_car). Used to group the solutions reached, to say whether the configurations agree, and to say which solution a solve reached.

source

analytic_reference [Function] ​

OptimalControlProblems.References.analytic_reference Function
julia
analytic_reference(
    problem::Symbol
) -> Union{Nothing, OptimalControlProblems.References.AnalyticReference}
analytic_reference(
    problem::Symbol,
    parameters::Union{Nothing, NamedTuple}
) -> Union{Nothing, OptimalControlProblems.References.AnalyticReference}

The analytic solution of the continuous problem for parameters (merged with the default ones) as an AnalyticReference, or nothing when none is known for them.

source

best_reference [Function] ​

OptimalControlProblems.References.best_reference Function
julia
best_reference(
    problem::Symbol,
    backend::OptimalControlProblems.Modelings.AbstractModelBackend;
    grid_size,
    scheme
) -> Any

The best known solution of problem in the modeling of backend, discretized on grid_size steps with scheme, with how it was obtained, or nothing: its objective is reference_objective(problem, backend).

source

reference_objective [Function] ​

OptimalControlProblems.References.reference_objective Function
julia
reference_objective(
    problem::Symbol,
    backend::OptimalControlProblems.Modelings.AbstractModelBackend;
    grid_size,
    scheme
) -> Any

Return the reference objective of problem in the modeling of backend, discretized on grid_size steps with scheme, or nothing when it has none for this discretization.

The modelings are independent: each has its reference objectives, computed from its own convergence tests by tools/references/update.jl, the best objective among the solves that converged. They are stored in problem_metadata(problem)[:reference_objective], with how they were obtained. The defaults are the grid of the problem in the modeling (grid_size_data(problem, backend)) and its discretization (the trapezoidal rule, single shooting for ModelingToolkit).

Example

julia
julia> OptimalControlProblems.reference_objective(:beam, JuMPBackend())
8.889...
source

reference_solution_data [Function] ​

OptimalControlProblems.References.reference_solution_data Function
julia
reference_solution_data(problem::Symbol) -> Any
reference_solution_data(
    problem::Symbol,
    parameters::Union{Nothing, NamedTuple}
) -> Any

Return the analytic solution of the continuous problem for parameters (merged with the default ones), or nothing when none is known for them: a named tuple with state and control, functions of the time, the objective, and its source.

It is the solution of the continuous problem: the objective of a discretized problem differs from it by the discretization error, which the reference objective includes.

Example

julia
julia> OptimalControlProblems.reference_solution_data(:beam).objective
8.88888888888889
source

references [Function] ​

OptimalControlProblems.References.references Function
julia
references(
    problem::Symbol,
    backend::OptimalControlProblems.Modelings.AbstractModelBackend;
    grid_size,
    scheme
) -> Any

The known solutions of problem in the modeling of backend, discretized on grid_size steps with scheme, best first, each with how it was obtained (#409); empty when it has no reference for this discretization. The first one is the reference objective.

Example

julia
julia> ref = first(OptimalControlProblems.references(:beam, JuMPBackend()))
julia> ref.solver, ref.options.tol, ref.status
source

solution_kind [Function] ​

OptimalControlProblems.References.solution_kind Function
julia
solution_kind(
    problem::Symbol,
    backend::OptimalControlProblems.Modelings.AbstractModelBackend,
    objective::Real;
    grid_size,
    scheme
) -> Union{Nothing, Symbol}

Which known solution of problem in the modeling of backend the objective objective is, for the discretization on grid_size steps with scheme (#378): :best (the reference objective), :local (another known solution), :new (none of them), or nothing when it has no reference for this discretization. Two objectives are the same solution within a relative OptimalControlProblems.SAME_SOLUTION.

source

From OptimalControlProblems.Modelings ​

OptimalControlProblems.Modelings [Module] ​

OptimalControlProblems.Modelings Module

The modelings of the collection: the backend types that select one (JuMPBackend, ModelingToolkitBackend, OptimalControlBackend, OptimalControlScalarizedBackend) and the modeling table, the single place where a modeling is declared (its name, its backend, the directory of its models in ext/, the weak dependency that loads them).

Depends on no other submodule.

source

AbstractModelBackend [Abstract Type] ​

OptimalControlProblems.Modelings.AbstractModelBackend Type
julia
abstract type AbstractModelBackend

Abstract tag selecting an optimal control problem modeling.

source

JuMPBackend [Struct] ​

OptimalControlProblems.Modelings.JuMPBackend Type

Select the JuMP modeling.

source

ModelingToolkitBackend [Struct] ​

OptimalControlProblems.Modelings.ModelingToolkitBackend Type

Select the ModelingToolkit modeling.

source

OptimalControlBackend [Struct] ​

OptimalControlProblems.Modelings.OptimalControlBackend Type

Select the OptimalControl modeling.

source

OptimalControlScalarizedBackend [Struct] ​

OptimalControlProblems.Modelings.OptimalControlScalarizedBackend Type

Select the scalarized OptimalControl modeling.

source

From OptimalControlProblems.Problems ​

OptimalControlProblems.Problems [Module] ​

OptimalControlProblems.Problems Module

A problem as the OptimalControl modelings return it (Problem, read with model, initial_guess and metadata), its computed features, the solution of a solved model of another modeling, and the accessors shared with OptimalControl (state, control, objective, …).

Depends on Modelings, Metadata and Catalogue.

source

Problem [Struct] ​

OptimalControlProblems.Problems.Problem Type
julia
struct Problem{M, I<:NamedTuple}

An optimal control problem of the collection: the continuous model, as written with OptimalControl, and its initial guess. Discretizing and solving it is left to OptimalControl.solve, where the scheme, the grid, the modeler and the solver are chosen.

A Problem is returned by a problem function for the OptimalControl modelings. Read it through model(pb), initial_guess and metadata(pb).

Fields

  • name::Symbol: Name of the problem.

  • modeling::Symbol: Modeling the problem is written in, e.g. :OptimalControl.

  • ocp::Any: Continuous optimal control problem.

  • init::NamedTuple: Initial guess, a NamedTuple (state=…, control=…, variable=…).

  • metadata::OrderedCollections.OrderedDict{Symbol, Any}: Metadata of the problem, with the parameters this instance was built with.

Example

julia
julia> using OptimalControl, OptimalControlProblems
julia> pb = beam(OptimalControlBackend())
julia> sol = solve(model(pb); init=initial_guess(pb), grid_size=500)
source

features [Function] ​

OptimalControlProblems.Problems.features Function
julia
features(
    problem::Symbol
) -> NamedTuple{(:state_dimension, :control_dimension, :variable_dimension, :cost, :initial_time, :final_time, :constraints), <:Tuple{Any, Any, Any, Symbol, Symbol, Symbol, @NamedTuple{state_box::Int64, control_box::Int64, variable_box::Int64, path::Int64, boundary::Int64}}}

Features of problem, computed from its OptimalControl model, never written by hand:

  • state_dimension, control_dimension, variable_dimension;

  • cost: :mayer, :lagrange or :bolza;

  • initial_time, final_time: :fixed or :free;

  • constraints: the number of constraints of each kind, state_box, control_box, variable_box (box constraints), path (nonlinear path constraints) and boundary (nonlinear boundary constraints).

The problem is built with its default parameters, which needs the OptimalControlModels extension: load OptimalControl. A problem without an OptimalControl model has no features yet.

Example

julia
julia> using OptimalControl, OptimalControlProblems

julia> OptimalControlProblems.features(:beam).cost
:lagrange
source
julia
features(
    pb::Problem
) -> NamedTuple{(:state_dimension, :control_dimension, :variable_dimension, :cost, :initial_time, :final_time, :constraints), <:Tuple{Any, Any, Any, Symbol, Symbol, Symbol, @NamedTuple{state_box::Int64, control_box::Int64, variable_box::Int64, path::Int64, boundary::Int64}}}

Features of the Problem pb, computed from its model (see features(problem::Symbol)).

source

initial_guess [Function] ​

OptimalControlProblems.Problems.initial_guess Function
julia
initial_guess(pb::Problem) -> NamedTuple

Return the initial guess of the problem, a NamedTuple (state=…, control=…, variable=…) to be given as init to OptimalControl.solve.

source

model [Function] ​

OptimalControlProblems.Problems.model Function
julia
model(
    sol::CTModels.Solutions.Solution{<:CTModels.Solutions.AbstractTimeGridModel, <:CTModels.Components.AbstractTimesModel, <:CTModels.Components.AbstractStateModel, <:CTModels.Components.AbstractControlModel, <:CTModels.Components.AbstractVariableModel, M<:CTModels.Models.AbstractModel}
) -> CTModels.Models.AbstractModel

Return the model of the optimal control problem.

source
julia
model(pb::Problem) -> Any

Return the continuous optimal control problem, to be given to OptimalControl.solve or OptimalControl.discretize, as model(sol) returns the problem of a solution.

source

solution [Function] ​

OptimalControlProblems.Problems.solution Function
julia
solution(model, pb::Problem) -> CTModels.Solution

Build the CTModels.Solution of a solved model of the same problem as pb, to show and plot it as an OptimalControl solution: state(sol), control(sol), costate(sol), objective(sol), iterations(sol) and plot(sol) work on it, and model(sol) === model(pb).

The method for a JuMP model is defined by the JuMPModels extension: load JuMP. The model and pb must have the same state, control and variable dimensions.

source