Skip to content

Commit e5abf40

Browse files
shawn-tao01shawn-tao01
committed
Updated the examples and the about page
1 parent 46063cc commit e5abf40

5 files changed

Lines changed: 120 additions & 92 deletions

File tree

‎About.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
@def title = "About"
2+
@def hascode = true
3+
@def tags = ["about"]
4+
5+
# About JuDO
6+
7+
For an overview of the project motivation and design philosophy, see the [home page](/).
8+
9+
---
10+
11+
## The packages
12+
13+
| Package | Role | Status |
14+
|---------|------|--------|
15+
| [JuDO.jl](https://github.com/JuDO-dev/JuDO.jl) | User-facing modelling language | Active development |
16+
| [DynOptInterface.jl](https://github.com/JuDO-dev/DynOptInterface.jl) | Mathematical abstraction layer (DOI) | v0.3.0 |
17+
| [Interesso.jl](https://github.com/JuDO-dev/Interesso.jl) | Integrated Residuals solver via Ipopt | Active development |
18+
19+
See the [Packages](/Packages/) page for full descriptions, API references, and installation instructions.
20+
21+
---
22+
23+
## Contributors
24+
25+
**Team owner:** Professor Eric Kerrigan ([@erickerrigan](https://github.com/erickerrigan))
26+
27+
**JuDO:** Haochen Tao ([@shawn-tao01](https://github.com/shawn-tao01)), Eduardo Vila ([@e-duar-do](https://github.com/e-duar-do))
28+
29+
**DynOptInterface:** Haochen Tao ([@shawn-tao01](https://github.com/shawn-tao01)), Eduardo Vila ([@e-duar-do](https://github.com/e-duar-do))
30+
31+
**Interesso:** Lucian Nita ([@LucianNita](https://github.com/LucianNita)), Eduardo Vila ([@e-duar-do](https://github.com/e-duar-do)), Lester ([@Kailai-Shi](https://github.com/Kailai-Shi)), Haochen Tao ([@shawn-tao01](https://github.com/shawn-tao01))
32+
33+
---
34+
35+
## Organisation
36+
37+
JuDO is developed and maintained by the [JuDO-dev](https://github.com/JuDO-dev) organisation on GitHub.
38+
39+
---
40+
41+
## Contributing
42+
43+
All packages are open to contributions. The best starting points are:
44+
45+
- **Bug reports and feature requests**: open an issue on the relevant GitHub repository
46+
- **New solvers**: implement your solver with a wrapper compatible to the [DynOptInterface](https://github.com/JuDO-dev/DynOptInterface.jl) to make your solver accessible from JuDO
47+
- **Documentation**: improvements to any of the package docs are always welcome

‎Examples.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ display(plot(p1, p2, p3; layout=(3,1), size=(600, 700)))
152152

153153
## Space Shuttle Reentry \{#space_shuttle_reentry\}
154154

155-
This benchmark problem, due to Betts (2010), optimises the reentry trajectory of a space shuttle to **maximise the crossrange** (final latitude $\theta(t_f)$), subject to full six-state atmospheric flight dynamics and terminal boundary conditions. The reference optimal crossrange is approximately **34.14°**.
155+
This benchmark problem, optimizes the reentry trajectory of a space shuttle to **maximise the crossrange** (final latitude $\theta(t_f)$), subject to full six-state atmospheric flight dynamics and terminal boundary conditions. The reference optimal crossrange is approximately **34.14°**.
156156

157157
### Problem formulation
158158

‎Packages.md‎

Lines changed: 31 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,44 @@
44

55
# JuDO Packages
66

7-
The JuDO ecosystem consists of three main packages arranged in a layered architecture modelled after JuMP / MathOptInterface.
7+
The JuDO ecosystem consists of two main packages arranged in a layered architecture.
8+
9+
---
10+
11+
## Design philosophy
12+
13+
JuDO has a layered architecture modelled on JuMP / MathOptInterface:
14+
15+
```
16+
User code (JuDO macros — @phase, @variable, @constraint, @objective...)
17+
│
18+
▼
19+
JuDO.jl
20+
│
21+
▼
22+
DynOptInterface.jl (DOI)
23+
/ \
24+
/ \
25+
▼ ▼
26+
Interesso.jl Other DOI-compatible
27+
│ solvers...
28+
▼
29+
NLP solver (Ipopt)
30+
831
932
---
1033
1134
## JuDO.jl
1235
1336
**The user-facing modelling layer.**
1437
15-
JuDO.jl extends [JuMP](https://jump.dev) with constructs for continuous-time dynamic optimisation: time phases, trajectory variables, derivatives, boundary operators, and integral objectives. Problems are formulated in a solver-agnostic syntax and translated automatically into the DynOptInterface (DOI) standard representation.
38+
JuDO.jl extends [JuMP](https://jump.dev) with constructs for dynamic optimization: time phases, trajectory variables, derivatives, boundary operators, and integral objectives. Problems are formulated in a solver-agnostic syntax and translated automatically into the DynOptInterface (DOI) standard representation.
1639
1740
Key modelling constructs:
1841
1942
| Macro / Function | Purpose |
2043
|-----------------|---------|
21-
| `DynModel(optimizer)` | Create a dynamic optimisation model |
44+
| `DynModel(optimizer)` | Create a dynamic optimization model |
2245
| `@phase(model, t)` | Declare the independent variable (time) |
2346
| `@variable(model, bounds, DefinedOn(t))` | Declare a trajectory variable |
2447
| `initial(x)`, `final(x)` | Access trajectory endpoints in constraints |
@@ -38,7 +61,7 @@ Key modelling constructs:
3861
3962
**The mathematical abstraction layer (DOI).**
4063
41-
DynOptInterface.jl (DOI) is to dynamic optimisation what MathOptInterface (MOI) is to static mathematical programming. It defines a standard intermediate representation for Dynamic Optimisation Problems (DOPs) that solvers can attach to.
64+
DynOptInterface.jl (DOI) is to dynamic optimization what MathOptInterface (MOI) is to static mathematical programming. It defines a standard intermediate representation for Dynamic optimization Problems (DOPs) that solvers can attach to.
4265
4366
The general problem form DOI represents:
4467
@@ -53,7 +76,7 @@ Key abstractions:
5376
| Type | Purpose |
5477
|------|---------|
5578
| `Phase` | A time interval $[t_0, t_f]$ with variable boundaries |
56-
| `DynamicVariable` | An optimisable trajectory $y(t)$ |
79+
| `DynamicVariable` | An optimizable trajectory $y(t)$ |
5780
| `Derivative` | Time derivative $\dot y(t)$ |
5881
| `Initial`, `Final` | Boundary-value operators |
5982
| `Integral`, `MultiPhaseIntegral` | Lagrange cost terms |
@@ -68,12 +91,12 @@ Key abstractions:
6891
6992
## Interesso.jl
7093
71-
**The dynamic optimisation solver.**
94+
**The dynamic optimization solver.**
7295
73-
Interesso.jl is a concrete solver implementing the DynOptInterface. It transcribes continuous-time DOPs into large-scale Nonlinear Programs (NLPs) using an **Integrated Residuals Method** (IRM) — collocation at Gaussian quadrature nodes — and dispatches them to [Ipopt](https://coin-or.github.io/Ipopt/).
96+
Interesso.jl is a solver we develop that could attach to the DynOptInterface. It transcribes continuous-time DOPs into large-scale Nonlinear Programs (NLPs) using an **Integrated Residuals Method** (IRM) and dispatches them to [Ipopt](https://coin-or.github.io/Ipopt/).
7497
7598
Features:
76-
- Multi-phase dynamic optimisation
99+
- Multi-phase dynamic optimization
77100
- Explicit and implicit ODE dynamics
78101
- Free final time
79102
- NLP warm-starting via `JuDO.warmstart!`
@@ -99,15 +122,4 @@ Features:
99122
100123
---
101124
102-
## Installation
103-
104-
All packages are under active development and not yet registered in the Julia General registry. Install from GitHub:
105-
106-
```julia
107-
using Pkg
108-
Pkg.add(url="https://github.com/JuDO-dev/DynOptInterface.jl", rev="dev")
109-
Pkg.add(url="https://github.com/JuDO-dev/Interesso.jl")
110-
Pkg.add(url="https://github.com/JuDO-dev/JuDO.jl", rev="dev")
111-
```
112-
113125
Julia 1.12 or later is required.

‎_layout/header.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
</div>
1010
<nav>
1111
<ul>
12-
<li><a href="/">Home</a></li>
12+
<li><a href="/index/">Home</a></li>
1313
<li><a href="/Examples/">Examples</a></li>
1414
<li><a href="/Packages/">Packages</a></li>
1515
<li><a href="/About/">About</a></li>

‎index.md‎

Lines changed: 40 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,14 @@
33
@def hascode = true
44
@def hasmath = true
55

6-
**JuDO.jl** is a Julia package for formulating and solving dynamic optimisation problems (optimal control, trajectory optimisation, and more). It extends the [JuMP](https://jump.dev) modelling language with continuous-time variables, differential equations, and integral objectives — keeping solver details out of your model code.
6+
# About JuDO
7+
8+
**JuDO** (Julia for Dynamic optimization) is an open-source modeling language developing a modern, solver-agnostic ecosystem for packages for dynamic optimization in Julia.
9+
10+
Dynamic optimization problems arises across engineering fields (spacecraft trajectory design, robot motion planning, process control, etc.).
11+
JuDO provides a simple formulation layer for users to define their problems mathematically, and an underlying abstracton layer DynOptInterface that provides necessary transformations to fit the dynamic-optimization solver.
12+
13+
---
714

815
# As easy as one-two-three
916

@@ -22,87 +29,49 @@ Julia 1.12 or later is required.
2229

2330
## 2. Define your problem
2431

25-
The example below solves the classic **cart-pole swing-up**: a pendulum on a cart must be swung from hanging ($\theta=0$) to upright ($\theta=\pi$) by a horizontal force, while minimising total control effort $\int_0^{t_f} u^2 \, dt$.
32+
The example below solves a classic LQR problem formulation.
2633

2734
```julia
28-
using JuDO, Interesso
29-
30-
const g = 9.81; const l = 0.5; const m_1 = 1.0; const m_2 = 0.3
31-
const u_max = 20.0; const r_max = 2.0
32-
33-
dop = DynModel(Interesso.Optimizer)
34-
35-
# Independent variable (time phase)
36-
@phase(dop, t)
37-
@constraint(dop, initial(t) == 0)
38-
@constraint(dop, final(t) == 2)
39-
40-
# States
41-
@variable(dop, 0 <= r <= r_max, DefinedOn(t)) # cart position (m)
42-
@variable(dop, ν, DefinedOn(t)) # cart velocity (m/s)
43-
@variable(dop, θ, DefinedOn(t)) # pole angle (rad)
44-
@variable(dop, ω, DefinedOn(t)) # pole angular velocity (rad/s)
45-
46-
# Control
47-
@variable(dop, -u_max <= u <= u_max, DefinedOn(t)) # horizontal force (N)
48-
49-
# Boundary conditions: hanging → upright
50-
@constraint(dop, initial(r) == 0); @constraint(dop, final(r) == 1)
51-
@constraint(dop, initial(ν) == 0); @constraint(dop, final(ν) == 0)
52-
@constraint(dop, initial(θ) == 0); @constraint(dop, final(θ) == pi)
53-
@constraint(dop, initial(ω) == 0); @constraint(dop, final(ω) == 0)
54-
55-
# Equations of motion (Lagrangian dynamics)
56-
@constraint(dop, derivative(r) == ν)
57-
@constraint(dop, derivative(ν) == (l*m_2*sin(θ)*ω^2 + u + m_2*g*cos(θ)*sin(θ)) /
58-
(m_1 + m_2*sin(θ)^2))
59-
@constraint(dop, derivative(θ) == ω)
60-
@constraint(dop, derivative(ω) == (-l*m_2*cos(θ)*sin(θ)*ω^2 - u*cos(θ) - (m_1 + m_2)*g*sin(θ)) /
61-
(l*(m_1 + m_2*sin(θ)^2)))
62-
63-
# Minimise control effort
64-
@objective(dop, Min, integral(u^2))
65-
```
66-
67-
## 3. Solve and extract the solution
35+
using Interesso, JuMP, JuDO, DynOptInterface
36+
using Plots
6837

69-
```julia
70-
using DynOptInterface
7138

72-
# Warm-start with linear guesses between boundary values
73-
struct LinearInterpolant <: DynOptInterface.AbstractDynamicSolution
74-
y_a::Float64; y_b::Float64
75-
end
76-
(li::LinearInterpolant)(t::Real) = li.y_a + t * (li.y_b - li.y_a) / 2.0
39+
model = DynModel(Interesso.Optimizer)
7740

78-
JuDO.warmstart!(dop, LinearInterpolant(0.0, 1.0), r)
79-
JuDO.warmstart!(dop, LinearInterpolant(0.0, pi), θ)
41+
@phase(model, t, 0.0, 10.0)
8042

81-
JuDO.optimize!(dop)
43+
## Dynamic Variables
44+
@variable(model, -1.0 <= u <= 1.0, DefinedOn(t))
45+
@variable(model, x, DefinedOn(t))
46+
@variable(model, v, DefinedOn(t))
8247

83-
# Solution trajectories are callable functions of time
84-
r_sol = dyn_value(dop, r)
85-
θ_sol = dyn_value(dop, θ)
86-
u_sol = dyn_value(dop, u)
48+
## Boundary Conditions
49+
@constraint(model, initial(x) == 0.0)
50+
@constraint(model, initial(v) == 0.0)
51+
@constraint(model, final(x) == 20.0)
52+
@constraint(model, final(v) == 0.0)
8753

88-
using Plots
89-
ts = range(0, 2; length=200)
90-
plot(ts, θ_sol.(ts); xlabel="Time (s)", ylabel="Pole angle θ (rad)", legend=false)
91-
```
54+
## Differential Equations
55+
@constraint(model, derivative(v) == u)
56+
@constraint(model, derivative(x) == v)
9257

93-
See the [Examples](/Examples/) page for the full annotated code and the aerospace [Space Shuttle Reentry](/Examples/#space_shuttle_reentry) benchmark (maximising crossrange; reference solution ≈ 34.14°).
58+
## Objective
59+
@objective(model, Min, integral(2*x^2 + 2*v^2))
9460

95-
---
61+
JuDO.optimize!(model)
9662

97-
# The JuDO ecosystem
63+
## Extract solutions
64+
t_0 = phase_initial(t).value
65+
t_f = 10.0
9866

99-
JuDO follows the same layered architecture as JuMP / MathOptInterface:
67+
x_sol = dyn_value(model, x)
68+
v_sol = dyn_value(model, v)
69+
u_sol = dyn_value(model, u)
10070

101-
| Layer | Package | Role |
102-
|-------|---------|------|
103-
| **Modelling** | [JuDO.jl](https://github.com/JuDO-dev/JuDO.jl) | Solver-agnostic problem formulation |
104-
| **Interface** | [DynOptInterface.jl](https://github.com/shawn-tao01/DynOptInterface.jl) | Standard intermediate representation for dynamic optimisation |
105-
| **Solver** | [Interesso.jl](https://github.com/Kailai-Shi/Interesso.jl) | Collocation-based NLP transcription via Ipopt |
71+
## Plot
72+
p1 = plot(τ -> x_sol(τ), t_0, t_f; label="x(t)", ylabel="Position")
73+
p2 = plot(τ -> v_sol(τ), t_0, t_f; label="v(t)", ylabel="Velocity")
74+
p3 = plot(τ -> u_sol(τ), t_0, t_f; label="u(t)", ylabel="Control", xlabel="t")
10675

107-
A problem written in JuDO can in principle be solved by any solver that implements the DynOptInterface (DOI) standard — with no changes to the model code.
108-
See the [Packages](/Packages/) page for details on each package.
76+
display(plot(p1, p2, p3; layout=(3, 1), size=(600, 700), legend=:topright))
77+
```

0 commit comments

Comments
 (0)