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.
problems [Function]
OptimalControlProblems.Catalogue.problems Function
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 requestedstatusin at least one modeling.problems(backend): problems available in that modeling with the requestedstatus.problems(backend1, backend2, ...): problems available in all the given modelings with the requestedstatus, which is the list to use to compare modelings.
Keyword arguments
status::Symbol=:valid::valid,:draftor:all.
Returns
Vector{Symbol}: A vector of problem names as symbols.
Example
julia> OptimalControlProblems.problems(JuMPBackend(), OptimalControlBackend())
[:balanced_field, :beam, ...]status [Function]
OptimalControlProblems.Catalogue.status Function
status(problem::Symbol) -> AnyReturn the status of problem in each modeling where it exists.
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.
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).
grid_size_data [Function]
OptimalControlProblems.Metadata.grid_size_data Function
grid_size_data(
problem::Symbol,
backend::OptimalControlProblems.Modelings.AbstractModelBackend
) -> AnyReturn 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> grid_size_data(:beam, JuMPBackend())
500initial_guess_data [Function]
OptimalControlProblems.Metadata.initial_guess_data Function
initial_guess_data(problem::Symbol) -> Any
initial_guess_data(
problem::Symbol,
parameters::Union{Nothing, NamedTuple}
) -> AnyReturn 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> OptimalControlProblems.initial_guess_data(:beam)
(state = [0.05, 0.1], control = 0.1)parameters_data [Function]
OptimalControlProblems.Metadata.parameters_data Function
parameters_data(problem::Symbol) -> AnyReturn 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, ornothingif none exist.
Example
julia> parameters_data(:beam)
(t0 = 0, tf = 1, ...)parameters_data(
problem::Symbol,
parameters::Union{Nothing, NamedTuple}
) -> AnyReturn 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. Ifnothing, returns the default parameters unchanged.
Returns
::Union{Nothing,NamedTuple}: the merged parameters. ThrowsCTBase.Exceptions.PreconditionErrorif parameters are given to a problem that has none.
Example
julia> parameters_data(:beam, (tf = 2,))
(t0 = 0, tf = 2, ...)problem_metadata [Function]
OptimalControlProblems.Metadata.problem_metadata Function
problem_metadata(
) -> OrderedCollections.OrderedDict{Symbol, OrderedCollections.OrderedDict}Return the dictionary containing the metadata of all available optimal control problems.
Example
julia> problem_metadata()problem_metadata(
problem::Symbol
) -> OrderedCollections.OrderedDictReturn 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 (seegrid_size_data). For example:
: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 (seegrid_size_data). For example:
:grid_sizes => (ModelingToolkit=100,),parameters::Union{Nothing,NamedTuple}: the list of parameters. For example:
: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 ofparameters;unitisnothingfor a dimensionless parameter. For example:
:parameter_info => (
t0 = (unit = "s", meaning = "initial time"),
x₁_u = (unit = nothing, meaning = "upper bound of the state x₁"),
...
),status: the status (:validor:draft) of the problem in each modeling.init: the initial guess of every modeling, a function of the parameters (seeOptimalControlProblems.initial_guess_data).reference_solution(optional): the analytic solution of the continuous problem, a function of the parameters; seeOptimalControlProblems.reference_solution_data.
Example
julia> data = problem_metadata(:beam)
julia> data[:grid_size]
500From 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.
AbstractReference [Abstract Type]
OptimalControlProblems.References.AbstractReference Type
abstract type AbstractReferenceA 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.
AnalyticReference [Struct]
OptimalControlProblems.References.AnalyticReference Type
struct AnalyticReference{S, U} <: OptimalControlProblems.References.AbstractReferenceThe 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).
NumericalReference [Struct]
OptimalControlProblems.References.NumericalReference Type
struct NumericalReference <: OptimalControlProblems.References.AbstractReferenceA 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),nothingfor 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, onplatform.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), orlocal.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.
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.
analytic_reference [Function]
OptimalControlProblems.References.analytic_reference Function
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.
best_reference [Function]
OptimalControlProblems.References.best_reference Function
best_reference(
problem::Symbol,
backend::OptimalControlProblems.Modelings.AbstractModelBackend;
grid_size,
scheme
) -> AnyThe 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).
reference_objective [Function]
OptimalControlProblems.References.reference_objective Function
reference_objective(
problem::Symbol,
backend::OptimalControlProblems.Modelings.AbstractModelBackend;
grid_size,
scheme
) -> AnyReturn 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> OptimalControlProblems.reference_objective(:beam, JuMPBackend())
8.889...reference_solution_data [Function]
OptimalControlProblems.References.reference_solution_data Function
reference_solution_data(problem::Symbol) -> Any
reference_solution_data(
problem::Symbol,
parameters::Union{Nothing, NamedTuple}
) -> AnyReturn 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> OptimalControlProblems.reference_solution_data(:beam).objective
8.88888888888889references [Function]
OptimalControlProblems.References.references Function
references(
problem::Symbol,
backend::OptimalControlProblems.Modelings.AbstractModelBackend;
grid_size,
scheme
) -> AnyThe 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> ref = first(OptimalControlProblems.references(:beam, JuMPBackend()))
julia> ref.solver, ref.options.tol, ref.statussolution_kind [Function]
OptimalControlProblems.References.solution_kind Function
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.
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.
sourceAbstractModelBackend [Abstract Type]
OptimalControlProblems.Modelings.AbstractModelBackend Type
abstract type AbstractModelBackendAbstract tag selecting an optimal control problem modeling.
sourceJuMPBackend [Struct]
ModelingToolkitBackend [Struct]
OptimalControlProblems.Modelings.ModelingToolkitBackend Type
Select the ModelingToolkit modeling.
sourceOptimalControlBackend [Struct]
OptimalControlProblems.Modelings.OptimalControlBackend Type
Select the OptimalControl modeling.
sourceOptimalControlScalarizedBackend [Struct]
OptimalControlProblems.Modelings.OptimalControlScalarizedBackend Type
Select the scalarized OptimalControl modeling.
sourceFrom 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.
Problem [Struct]
OptimalControlProblems.Problems.Problem Type
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, aNamedTuple(state=…, control=…, variable=…).metadata::OrderedCollections.OrderedDict{Symbol, Any}: Metadata of the problem, with the parameters this instance was built with.
Example
julia> using OptimalControl, OptimalControlProblems
julia> pb = beam(OptimalControlBackend())
julia> sol = solve(model(pb); init=initial_guess(pb), grid_size=500)features [Function]
OptimalControlProblems.Problems.features Function
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,:lagrangeor:bolza;initial_time,final_time::fixedor:free;constraints: the number of constraints of each kind,state_box,control_box,variable_box(box constraints),path(nonlinear path constraints) andboundary(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> using OptimalControl, OptimalControlProblems
julia> OptimalControlProblems.features(:beam).cost
:lagrangefeatures(
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)).
initial_guess [Function]
OptimalControlProblems.Problems.initial_guess Function
initial_guess(pb::Problem) -> NamedTupleReturn the initial guess of the problem, a NamedTuple (state=…, control=…, variable=…) to be given as init to OptimalControl.solve.
model [Function]
OptimalControlProblems.Problems.model Function
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.AbstractModelReturn the model of the optimal control problem.
sourcemodel(pb::Problem) -> AnyReturn the continuous optimal control problem, to be given to OptimalControl.solve or OptimalControl.discretize, as model(sol) returns the problem of a solution.
solution [Function]
OptimalControlProblems.Problems.solution Function
solution(model, pb::Problem) -> CTModels.SolutionBuild 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.