Skip to content

Update documentation for control-free problems #743

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ocots merged 6 commits into from
Apr 6, 2026
Merged

Update documentation for control-free problems #743

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
78ddba5
Update documentation and add private API docs
ocots Apr 5, 2026
f7d47f7
Update control-free documentation with augment=true feature
ocots Apr 6, 2026
1807948
Update v2.0 documentation with augment=true and Flow(ocp) features
ocots Apr 6, 2026
90f3626
Add augment=true documentation and improve mathematical notation
ocots Apr 6, 2026
8120478
Remove redundant Flow declarations in control-free examples
ocots Apr 6, 2026
0846150
Add Flow(ocp) and augment=true tests to CTFlows reexports
ocots Apr 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions BREAKING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ Version 2.0.0 represents a major architectural redesign of OptimalControl.jl, in
- **GPU/CPU parameter system** for heterogeneous computing
- **Advanced option routing** with introspection and disambiguation tools
- **New solver integrations** (Uno, MadNCL)
- **Control-free problems** support
- **Control-free problems** support with augmented Hamiltonian approach
- **CTFlows enhancements** with `augment=true` and direct OCP flow creation
- **Modernized reexport system** using `@reexport import`

## Removed Functions
Expand Down Expand Up @@ -172,7 +173,7 @@ The old functional approach is no longer supported.

These features are new in v2.0.0 but don't break existing code:

### Control-Free Problems
### Control-Free Problems Support

Support for optimal control problems without control variables:

Expand Down Expand Up @@ -220,6 +221,45 @@ using CUDA, MadNLPGPU
sol = solve(ocp, :collocation, :exa, :madnlp, :gpu)
```

## CTFlows Features

### Control-Free Problems

v2.0.0 introduces comprehensive support for control-free problems (optimal control without control variables) with enhanced CTFlows integration:

**Augmented Hamiltonian approach:**

```julia
# v1.1.6: Manual augmented Hamiltonian construction
function H_aug(t, x_, p_)
x, λ = x_
p, _ = p_
return H(t, x, p, λ)
end
f = Flow(Hamiltonian(H_aug))

# v2.0.0: Direct OCP flow creation
f = Flow(ocp)
```

**Automatic costate computation:**

```julia
# v2.0.0: augment=true automatically computes p_λ(tf)
function shoot!(s, p0, λ)
_, px_tf, pλ_tf = f(t0, x0, p0, tf, λ; augment=true)
s[1] = px_tf # p(tf) = 0
s[2] = pλ_tf # p_λ(tf) = 0
end
```

**Mathematical framework:**

- Complete augmented system dynamics with proper transversality conditions
- Automatic handling of Lagrange costs: $p_\lambda(t_f) = 0$
- Automatic handling of Mayer costs: $p_\omega(t_f) = -2\omega$
- Initial conditions: $p_\lambda(t_0) = 0$ by construction

## Dependency Updates

v2.0.0 requires updated versions of CTX packages:
Expand Down
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
- Optimal control problems without control variables
- Optimization of constant parameters in dynamical systems
- Full integration with solve pipeline
- **Augmented Hamiltonian approach**: `augment=true` feature in CTFlows for automatic costate computation
- **Simplified flow creation**: `Flow(ocp)` directly creates Hamiltonian flow from control-free problems
- **Mathematical framework**: Complete transversality conditions for variable parameters
- **Documentation**: Comprehensive examples with exponential growth and harmonic oscillator

- **New solvers**:
- **Uno**: CPU-only nonlinear optimization solver (methods with `:uno`)
Expand All @@ -78,6 +82,12 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
- Organized by source package (ctbase.jl, ctdirect.jl, ctflows.jl, ctmodels.jl, ctparser.jl, ctsolvers.jl)
- Cleaner separation between imported and exported symbols

- **CTFlows enhancements**:
- **Augmented Hamiltonian computation**: `augment=true` automatically computes costates for variable parameters
- **Direct OCP flow creation**: `Flow(ocp)` creates Hamiltonian flow without manual Hamiltonian definition
- **Transversality conditions**: Automatic handling of $p_\lambda(t_f) = 0$ for Lagrange costs and $p_\omega(t_f) = -2\omega$ for Mayer costs
- **Mathematical rigor**: Complete augmented system dynamics with proper initial conditions

- **Strategy registry system**:
- `StrategyRegistry` with metadata for all strategies
- `StrategyMetadata` with id, options, and parameter support
Expand Down
73 changes: 41 additions & 32 deletions docs/src/assets/Manifest.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,19 +232,19 @@ version = "1.0.6"

[[deps.CTFlows]]
deps = ["CTBase", "CTModels", "DocStringExtensions", "ForwardDiff", "LinearAlgebra", "MLStyle", "MacroTools"]
git-tree-sha1 = "536c34374ab27f3d4d6a51d9e92ed89f146ca989"
git-tree-sha1 = "c4a9adf514aca4e006131a5e39792bcf01b449b4"
uuid = "1c39547c-7794-42f7-af83-d98194f657c2"
version = "0.8.20"
version = "0.8.22-beta"
weakdeps = ["OrdinaryDiffEq"]

[deps.CTFlows.extensions]
CTFlowsODE = "OrdinaryDiffEq"

[[deps.CTModels]]
deps = ["CTBase", "DocStringExtensions", "LinearAlgebra", "MLStyle", "MacroTools", "OrderedCollections", "Parameters", "RecipesBase"]
git-tree-sha1 = "3e9df6b6cb96ccb05051ded9a5d4f76f649f6d0c"
git-tree-sha1 = "791bcfa3cc9b39d2c1b5bc66581d1739bd8c96c0"
uuid = "34c4fa32-2049-4079-8329-de33c2a22e2d"
version = "0.9.12-beta"
version = "0.9.13"
weakdeps = ["JLD2", "JSON3", "Plots"]

[deps.CTModels.extensions]
Expand All @@ -254,9 +254,9 @@ weakdeps = ["JLD2", "JSON3", "Plots"]

[[deps.CTParser]]
deps = ["CTBase", "DocStringExtensions", "MLStyle", "OrderedCollections", "Parameters", "Unicode"]
git-tree-sha1 = "1a7445af1c937c291371e0f7c0a51a80f5b5d0eb"
git-tree-sha1 = "0a57111b2d95d6272bb76f4f6f7c4fee1e40ce82"
uuid = "32681960-a1b1-40db-9bff-a1ca817385d1"
version = "0.8.12-beta"
version = "0.8.13"

[[deps.CTSolvers]]
deps = ["ADNLPModels", "CTBase", "CTModels", "CommonSolve", "DocStringExtensions", "ExaModels", "KernelAbstractions", "NLPModels", "SolverCore"]
Expand Down Expand Up @@ -921,9 +921,16 @@ version = "1.1.3"

[[deps.FunctionWrappersWrappers]]
deps = ["FunctionWrappers", "PrecompileTools", "TruncatedStacktraces"]
git-tree-sha1 = "6874da243fb93e34201d7d4587ffa0e920682f64"
git-tree-sha1 = "5201523536a43bf8aef3914b7f60b552b098ef8e"
uuid = "77dc65aa-8811-40c2-897b-53d922fa7daf"
version = "1.0.0"
version = "1.1.0"

[deps.FunctionWrappersWrappers.extensions]
FunctionWrappersWrappersEnzymeExt = ["Enzyme", "EnzymeCore"]

[deps.FunctionWrappersWrappers.weakdeps]
Enzyme = "7da242da-08ed-463a-9acd-ee780be4f1d9"
EnzymeCore = "f151be2c-9106-41f4-ab19-57ee4f262869"

[[deps.Future]]
deps = ["Random"]
Expand Down Expand Up @@ -1696,21 +1703,21 @@ version = "0.21.12"

[[deps.NLPModelsIpopt]]
deps = ["Ipopt", "NLPModels", "NLPModelsModifiers", "SolverCore"]
git-tree-sha1 = "37a2187dc5f1291f6a6cb592acaa59cee685b5fb"
git-tree-sha1 = "260a33809f49f7ccb011fdc1d9ebcf8879bc9757"
uuid = "f4238b75-b362-5c4c-b852-0801c9a21d71"
version = "0.11.2"
version = "0.11.3"

[[deps.NLPModelsKnitro]]
deps = ["KNITRO", "NLPModels", "NLPModelsModifiers", "SolverCore"]
git-tree-sha1 = "90e9e12bf859aa3b9453a852015a552592b8ea95"
git-tree-sha1 = "763bda401fa32460dae1caa48f6ab3c195d3bf3e"
uuid = "bec4dd0d-7755-52d5-9a02-22f0ffc7efcb"
version = "0.10.2"
version = "0.10.3"

[[deps.NLPModelsModifiers]]
deps = ["FastClosures", "LinearAlgebra", "LinearOperators", "NLPModels", "Printf", "SparseArrays"]
git-tree-sha1 = "15bd5325aaa45090019f43b49cb3cb938b195f04"
git-tree-sha1 = "3a6ec5add6f5a95d598648432ac06126157ba11c"
uuid = "e01155f1-5c6f-4375-a9d8-616dd036575f"
version = "0.7.4"
version = "0.8.0"

[[deps.NLSolversBase]]
deps = ["ADTypes", "DifferentiationInterface", "FiniteDiff", "LinearAlgebra"]
Expand Down Expand Up @@ -1779,9 +1786,9 @@ version = "4.17.0"

[[deps.NonlinearSolveBase]]
deps = ["ADTypes", "Adapt", "ArrayInterface", "CommonSolve", "Compat", "ConcreteStructs", "DifferentiationInterface", "EnzymeCore", "FastClosures", "FunctionWrappers", "FunctionWrappersWrappers", "LinearAlgebra", "LogExpFunctions", "Markdown", "MaybeInplace", "PreallocationTools", "PrecompileTools", "Preferences", "Printf", "RecursiveArrayTools", "SciMLBase", "SciMLJacobianOperators", "SciMLLogging", "SciMLOperators", "SciMLStructures", "Setfield", "StaticArraysCore", "SymbolicIndexingInterface", "TimerOutputs"]
git-tree-sha1 = "7deb924291e30ef27e8823e9d048ffb98ca6ffce"
git-tree-sha1 = "e9bad06173df78880b8c0fd51ad9cd940547a195"
uuid = "be0214bd-f91f-a760-ac4e-3421ce2b2da0"
version = "2.20.0"
version = "2.21.0"

[deps.NonlinearSolveBase.extensions]
NonlinearSolveBaseBandedMatricesExt = "BandedMatrices"
Expand Down Expand Up @@ -1811,25 +1818,25 @@ version = "2.20.0"

[[deps.NonlinearSolveFirstOrder]]
deps = ["ADTypes", "ArrayInterface", "CommonSolve", "ConcreteStructs", "FiniteDiff", "ForwardDiff", "LineSearch", "LinearAlgebra", "LinearSolve", "MaybeInplace", "NonlinearSolveBase", "PrecompileTools", "Reexport", "SciMLBase", "SciMLJacobianOperators", "Setfield", "StaticArraysCore"]
git-tree-sha1 = "eea7cbe389b168c77df7ff779fb7277019c685c8"
git-tree-sha1 = "ae36a13005343aed5e731f146637f61a54702444"
uuid = "5959db7a-ea39-4486-b5fe-2dd0bf03d60d"
version = "2.0.0"
version = "2.1.0"

[[deps.NonlinearSolveQuasiNewton]]
deps = ["ArrayInterface", "CommonSolve", "ConcreteStructs", "LinearAlgebra", "LinearSolve", "MaybeInplace", "NonlinearSolveBase", "PrecompileTools", "Reexport", "SciMLBase", "SciMLOperators", "StaticArraysCore"]
git-tree-sha1 = "ade27e8e9566b6cec63ee62f6a6650a11cf9a2eb"
git-tree-sha1 = "2ada8e9892fd60b3f01a4984704d66fca682bd50"
uuid = "9a2c21bd-3a47-402d-9113-8faf9a0ee114"
version = "1.12.0"
version = "1.13.0"
weakdeps = ["ForwardDiff"]

[deps.NonlinearSolveQuasiNewton.extensions]
NonlinearSolveQuasiNewtonForwardDiffExt = "ForwardDiff"

[[deps.NonlinearSolveSpectralMethods]]
deps = ["CommonSolve", "ConcreteStructs", "LineSearch", "MaybeInplace", "NonlinearSolveBase", "PrecompileTools", "Reexport", "SciMLBase"]
git-tree-sha1 = "eafd027b5cd768f19bb5de76c0e908a9065ddd36"
git-tree-sha1 = "e3e8be34968ad07be8734c3d6e42b3f14218b694"
uuid = "26075421-4e9a-44e1-8bd1-420ed7ad02b2"
version = "1.6.0"
version = "1.7.0"
weakdeps = ["ForwardDiff"]

[deps.NonlinearSolveSpectralMethods.extensions]
Expand Down Expand Up @@ -1931,9 +1938,9 @@ version = "1.14.0"

[[deps.OrdinaryDiffEqDifferentiation]]
deps = ["ADTypes", "ArrayInterface", "ConcreteStructs", "ConstructionBase", "DiffEqBase", "DifferentiationInterface", "FastBroadcast", "FiniteDiff", "ForwardDiff", "FunctionWrappersWrappers", "LinearAlgebra", "LinearSolve", "OrdinaryDiffEqCore", "SciMLBase", "SciMLOperators", "SparseMatrixColorings", "StaticArrays"]
git-tree-sha1 = "c7d06493d3327cc45f0d8d7e641203d28779e837"
git-tree-sha1 = "8b18ce8ab49cd04a1443fd63eb569d270a07090c"
uuid = "4302a76b-040a-498a-8c04-15b101fed76b"
version = "2.6.0"
version = "2.7.0"
weakdeps = ["SparseArrays"]

[deps.OrdinaryDiffEqDifferentiation.extensions]
Expand Down Expand Up @@ -2007,9 +2014,9 @@ version = "1.14.0"

[[deps.OrdinaryDiffEqNonlinearSolve]]
deps = ["ADTypes", "ArrayInterface", "DiffEqBase", "FastBroadcast", "FastClosures", "ForwardDiff", "LinearAlgebra", "LinearSolve", "MuladdMacro", "NonlinearSolve", "OrdinaryDiffEqCore", "OrdinaryDiffEqDifferentiation", "PreallocationTools", "RecursiveArrayTools", "SciMLBase", "SciMLOperators", "SciMLStructures", "SimpleNonlinearSolve", "SparseArrays", "StaticArrays"]
git-tree-sha1 = "f6722d6a96c27263ac3ea6159a3174914567a807"
git-tree-sha1 = "7eabb9877144d3cfc894fee899a76439ee2070de"
uuid = "127b3ac7-2247-4354-8eb6-78cf4e7c58e8"
version = "1.25.0"
version = "1.26.0"

[[deps.OrdinaryDiffEqNordsieck]]
deps = ["DiffEqBase", "FastBroadcast", "LinearAlgebra", "MuladdMacro", "OrdinaryDiffEqCore", "OrdinaryDiffEqTsit5", "Polyester", "RecursiveArrayTools", "Reexport", "SciMLBase", "Static"]
Expand Down Expand Up @@ -2043,9 +2050,9 @@ version = "1.12.0"

[[deps.OrdinaryDiffEqRosenbrock]]
deps = ["ADTypes", "DiffEqBase", "DifferentiationInterface", "FastBroadcast", "FiniteDiff", "ForwardDiff", "LinearAlgebra", "LinearSolve", "MacroTools", "MuladdMacro", "OrdinaryDiffEqCore", "OrdinaryDiffEqDifferentiation", "Polyester", "PrecompileTools", "Preferences", "RecursiveArrayTools", "Reexport", "SciMLBase", "Static"]
git-tree-sha1 = "88f722a74df3dadaf5f31c454a280f1201a1b368"
git-tree-sha1 = "25e5043968c80e0addead2d7533d30a608478842"
uuid = "43230ef6-c299-4910-a778-202eb28ce4ce"
version = "1.28.0"
version = "1.29.0"

[[deps.OrdinaryDiffEqSDIRK]]
deps = ["ADTypes", "DiffEqBase", "FastBroadcast", "LinearAlgebra", "MacroTools", "MuladdMacro", "OrdinaryDiffEqCore", "OrdinaryDiffEqDifferentiation", "OrdinaryDiffEqNonlinearSolve", "PrecompileTools", "Preferences", "RecursiveArrayTools", "Reexport", "SciMLBase", "TruncatedStacktraces"]
Expand Down Expand Up @@ -2289,12 +2296,13 @@ version = "0.6.12"

[[deps.RecursiveArrayTools]]
deps = ["Adapt", "ArrayInterface", "DocStringExtensions", "GPUArraysCore", "LinearAlgebra", "PrecompileTools", "RecipesBase", "StaticArraysCore", "SymbolicIndexingInterface"]
git-tree-sha1 = "e4fd3369c78666a65ccec25dba28a0b181434ab2"
git-tree-sha1 = "d0282d612f22dcad7b81cf487b746e63aa2a6709"
uuid = "731186ca-8d62-57ce-b412-fbd966d074cd"
version = "3.52.0"
version = "3.54.0"

[deps.RecursiveArrayTools.extensions]
RecursiveArrayToolsFastBroadcastExt = "FastBroadcast"
RecursiveArrayToolsFastBroadcastPolyesterExt = ["FastBroadcast", "Polyester"]
RecursiveArrayToolsForwardDiffExt = "ForwardDiff"
RecursiveArrayToolsKernelAbstractionsExt = "KernelAbstractions"
RecursiveArrayToolsMeasurementsExt = "Measurements"
Expand All @@ -2313,6 +2321,7 @@ version = "3.52.0"
KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7"
MonteCarloMeasurements = "0987c9cc-fe09-11e8-30f0-b96dd679fdca"
Polyester = "f517fe37-dbe3-4b94-8317-1923a5111588"
ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
Expand Down Expand Up @@ -2434,9 +2443,9 @@ weakdeps = ["Tracy"]

[[deps.SciMLOperators]]
deps = ["Accessors", "ArrayInterface", "DocStringExtensions", "LinearAlgebra"]
git-tree-sha1 = "794c760e6aafe9f40dcd7dd30526ea33f0adc8b7"
git-tree-sha1 = "234869cf9fee9258a95464b7a7065cc7be84db00"
uuid = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
version = "1.15.1"
version = "1.16.0"
weakdeps = ["SparseArrays", "StaticArraysCore"]

[deps.SciMLOperators.extensions]
Expand Down
Loading
Loading