Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
34f34d1
feat(data): the unit and the meaning of each parameter, shown on the …
ocots Nov 19, 2026
ecabc40
feat(data): parameter info of beam
ocots Nov 19, 2026
1fa3cd1
feat(data): parameter info of bryson_denham
ocots Nov 19, 2026
9987f00
feat(data): parameter info of chain
ocots Nov 19, 2026
3c56c5a
feat(data): parameter info of vanderpol
ocots Nov 19, 2026
6c9aae3
feat(data): parameter info of robbins
ocots Nov 19, 2026
2b580ac
feat(data): parameter info of brachistochrone
ocots Nov 19, 2026
e13256e
feat(data): parameter info of double_oscillator
ocots Nov 19, 2026
d33c034
feat(data): parameter info of electric_vehicle
ocots Nov 19, 2026
83cf818
feat(data): parameter info of jackson
ocots Nov 19, 2026
6b7a84a
feat(data): parameter info of steering
ocots Nov 19, 2026
7799e6e
feat(data): parameter info of mountain_car
ocots Nov 19, 2026
7417bb1
feat(data): parameter info of dielectrophoretic_particle
ocots Nov 19, 2026
4fced4c
feat(data): parameter info of bioreactor
ocots Nov 19, 2026
332cf3e
feat(data): parameter info of cart_pendulum
ocots Nov 19, 2026
916a4bd
feat(data): parameter info of rocket
ocots Nov 19, 2026
ceec470
feat(data): parameter info of moonlander
ocots Nov 19, 2026
ff54ea8
feat(data): parameter info of glider
ocots Nov 19, 2026
eb027d2
feat(data): parameter info of robot
ocots Nov 19, 2026
2922d3f
feat(data): parameter info of ducted_fan
ocots Nov 19, 2026
4d0eddc
feat(data): parameter info of insurance
ocots Nov 19, 2026
6f673bc
feat(data): parameter info of balanced_field
ocots Nov 19, 2026
7481b4b
feat(data): parameter info of space_shuttle
ocots Nov 19, 2026
aca5b82
feat(data): parameter info required, the descriptions without paramet…
ocots Nov 19, 2026
8531c35
Merge remote-tracking branch 'origin/fix/t2-review' into feat/paramet…
ocots Nov 20, 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
18 changes: 15 additions & 3 deletions docs/problems.jl
Original file line number Diff line number Diff line change
Expand Up @@ -116,12 +116,24 @@ function parameters_section(problem::Symbol)
params = OCP.parameters_data(problem)
isnothing(params) &&
return "### [Parameters](@id $(anchor(problem, :parameters)))\n\nThe problem has no parameters.\n"
rows = join(("| `$(k)` | `$(v)` |" for (k, v) in pairs(params)), "\n")
info = get(OCP.problem_metadata(problem), :parameter_info, nothing)
unit(k) = (u = info[k].unit; isnothing(u) ? "–" : u)
rows = if isnothing(info)
join(("| `$(k)` | `$(v)` | | |" for (k, v) in pairs(params)), "\n")
else
join(
(
"| `$(k)` | `$(v)` | $(unit(k)) | $(info[k].meaning) |" for
(k, v) in pairs(params)
),
"\n",
)
end
return """
### [Parameters](@id $(anchor(problem, :parameters)))

| Parameter | Default value |
| :--- | :--- |
| Parameter | Default value | Unit | Meaning |
| :--- | :--- | :--- | :--- |
$(rows)

Every modeling takes other values with the keyword `parameters`, merged with these:
Expand Down
14 changes: 2 additions & 12 deletions ext/Descriptions/balanced_field.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
The **Aircraft Balanced Field Length Calculation** is a classic aeronautical engineering problem used to determine the minimum runway length required for a safe takeoff or a safe stop in the event of an engine failure.
This implementation focuses on the **takeoff climb** phase with one engine out, starting from the critical engine failure speed $V_1$.
This implementation focuses on the **takeoff climb** phase with one engine out, starting from the critical engine failure speed $V_1$.
The parameters are those of a mid-size jet aircraft, the nominal values of the Dymos example.

### Mathematical formulation

Expand All @@ -20,17 +21,6 @@ The state vector is $x(t) = (r(t), v(t), h(t), \gamma(t))$ and the control is th

The aerodynamic forces $L$ and $D$ depend on the angle of attack $\alpha$, velocity $v$, and altitude $h$ (ground effect).

### Parameters

The parameters are based on a mid-size jet aircraft (nominal values from Dymos):

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Mass | $m$ | 79015.8 kg |
| Surface | $S$ | 124.7 m² |
| Thrust (1 engine) | $T$ | 120102.0 N |
| Screen height | $h_{tf}$ | 10.668 m |

### Characteristics

- Nonlinear dynamics, with a ground effect in the drag model ($K$ coefficient).
Expand Down
14 changes: 0 additions & 14 deletions ext/Descriptions/bioreactor.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,20 +28,6 @@ The model components are:
- **Light model:** $\mu(t) = \mu_{\text{bar}} \,\max\!\big(0,\sin(\tau(t))\big)^2$, where $\tau(t)$ encodes the periodic day–night cycle,
- **Growth function (Monod law):** $\mu_2(s) = \mu_2^m \,\dfrac{s}{K_s + s}$.

### Parameter values

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Flow coupling between reactors | $\beta$ | 1 |
| Cost scaling | $c$ | 2 |
| Substrate–algae interaction | $\gamma$ | 1 |
| Half-period of light cycle | $\text{halfperiod}$ | 5 |
| Monod half-saturation constant | $K_s$ | 0.05 |
| Maximum biomass growth rate | $\mu_2^m$ | 0.1 |
| Maximum light intensity | $\mu_{\text{bar}}$ | 1 |
| Algal decay rate | $r$ | 0.005 |
| Time horizon | $T$ | 200 |

### Qualitative behaviour

The optimal solution exploits the **periodic light–dark structure**:
Expand Down
10 changes: 0 additions & 10 deletions ext/Descriptions/chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,6 @@ The problem can be stated as
\end{aligned}
```

### System parameters

| Parameter | Symbol | Value | Description |
|-----------|--------|-------|-------------|
| Horizontal start | $a$ | 1 | Initial $x_1$ position |
| Horizontal end | $b$ | 3 | Final $x_1$ position |
| Chain length | $L$ | 4 | Total length of the chain |
| Final time | $T$ | 1 | Duration of the motion |
| Control input | $u$ | — | Horizontal velocity of the chain |

### Qualitative behaviour

The optimal control trajectory exploits the nonlinear coupling between horizontal and vertical motion:
Expand Down
9 changes: 0 additions & 9 deletions ext/Descriptions/dielectrophoretic_particle.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,6 @@ t_f \ge 0,

where $x_0$ and $x_f$ are the initial and final particle positions, $\alpha$ is a coefficient representing nonlinear interaction with the field, and $c$ is a damping coefficient.

### System parameters

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Initial particle position | $x_0$ | 1 |
| Final particle position | $x_f$ | 2 |
| Nonlinear coefficient | $\alpha$ | -0.75 |
| Damping coefficient | $c$ | 1 |

### Qualitative behaviour

- The optimal control typically saturates at the bounds $u = \pm 1$, characteristic of **time-optimal problems**.
Expand Down
12 changes: 0 additions & 12 deletions ext/Descriptions/double_oscillator.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,18 +21,6 @@ The problem can be stated as

where $F(t) = \sin\left(\frac{2 \pi}{T} t\right)$ is a prescribed periodic forcing term.

### System parameters

| Parameter | Symbol | Value | Description |
|-----------|--------|-------|-------------|
| Mass 1 | $m_1$ | 100 kg | First mass directly affected by $F(t)$ |
| Mass 2 | $m_2$ | 2 kg | Second mass influenced by damping control |
| Spring stiffness 1 | $k_1$ | 100 N/m | Spring connecting first mass to reference |
| Spring stiffness 2 | $k_2$ | 3 N/m | Coupling spring between the two masses |
| Damping coefficient | $c$ | 0.5 Ns/m | Damping affecting second mass |
| Final time | $T$ | $2\pi$ | Duration of the motion |
| Control input | $u$ | — | Modulates the damping of the second mass |

### Qualitative behaviour

- The system exhibits coupled oscillatory dynamics due to interaction between the two masses through springs and damper.
Expand Down
13 changes: 0 additions & 13 deletions ext/Descriptions/electric_vehicle.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,6 @@ r(x) = \alpha_0 + \alpha_1 x + \alpha_2 x^2 + \alpha_3 x^3,

and the parameters $h_0$, $h_1$, $h_2$, $b_1$, $b_2$, and $\alpha_i$ define vehicle dynamics, drag, and slope effects.

### System parameters

| Parameter | Symbol | Value | Description |
|-----------|--------|-------|-------------|
| Trip distance | $D$ | 10 m | Total length of the trajectory |
| Friction term | $h_0$ | 0.1 | Constant resistance |
| Acceleration gain | $h_1$ | 1 | Input scaling for acceleration |
| Quadratic velocity damping | $h_2$ | 1e-3 | Air drag effect |
| Energy weight | $b_1$ | 1 | Linear contribution of input power |
| Control weight | $b_2$ | 1 | Quadratic penalty on control effort |
| Road profile | $\alpha_0,\dots,\alpha_3$ | 3, 0.4, -1, 0.1 | Cubic coefficients modelling road slope |
| Final time | $t_f$ | 1 s | Duration of the trajectory |

### Qualitative behaviour

- The optimal solution balances **traction and braking** to respect the velocity boundary conditions while minimising energy consumption.
Expand Down
14 changes: 0 additions & 14 deletions ext/Descriptions/glider.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,20 +36,6 @@ U_\text{updraft}(x) = u_c\, (1 - r) e^{-r}, \quad r = \left( \frac{x}{r_0} - 2.5

where $m, g, S, \rho, c_0, c_1, u_c, r_0$ are constants describing the glider and the thermal properties.

### System parameters

| Parameter | Symbol | Value | Description |
|-----------|--------|-------|-------------|
| Initial horizontal position | $x_0$ | 0 | m |
| Initial altitude | $y_0$ | 1000 | m |
| Final altitude | $y_f$ | 900 | m |
| Initial horizontal velocity | $v_{x0}$ | 13.23 | m/s |
| Final horizontal velocity | $v_{xf}$ | 13.23 | m/s |
| Initial vertical velocity | $v_{y0}$ | -1.288 | m/s |
| Final vertical velocity | $v_{yf}$ | -1.288 | m/s |
| Lift coefficient bounds | $c_L$ | [0, 1.4] | Control input |
| Final time | $t_f$ | free | s |

### Qualitative behaviour

- The optimal trajectory exploits the thermal updraft to maximise horizontal distance.
Expand Down
14 changes: 0 additions & 14 deletions ext/Descriptions/insurance.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,20 +71,6 @@ f_x(t) &= \lambda e^{-\lambda t} + \frac{e^{-\lambda t_f}}{t_f}, \\

These constraints encode **revenue balance**, **health evolution**, **utility computation**, and **auxiliary relationships**.

### System parameters

| Parameter | Symbol | Value | Description |
|-----------|--------|-------|-------------|
| Risk aversion | $\gamma$ | 0.2 | Health cost scaling |
| Illness rate | $\lambda$ | 0.25 | Hazard parameter |
| Baseline health | $h_0$ | 1.5 | Initial health level |
| Weight factor | $w$ | 1 | Revenue baseline |
| Sensitivity | $s$ | 10 | Utility sensitivity to revenue |
| Exponent | $\alpha$ | 4 | Expense nonlinearity |
| Expense rate | $k$ | 0 | Time-varying adjustment |
| Shock | $\sigma$ | 0 | Auxiliary multiplier |
| Final time | $t_f$ | 10 | s |

### Qualitative behaviour

- The optimal strategy balances **insurance coverage**, **health investment**, and **expenses** to maximise utility under constraints.
Expand Down
11 changes: 0 additions & 11 deletions ext/Descriptions/jackson.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,6 @@ The problem can be stated as

where $x_1, x_2, x_3$ are the state variables, $u$ is the control input, and $k_1, k_2, k_3$ are system parameters.

### System parameters

| Parameter | Symbol | Value | Description |
|-----------|--------|-------|-------------|
| Coupling coefficient | $k_1$ | 1 | Interaction between $x_1$ and $x_2$ |
| Coupling coefficient | $k_2$ | 10 | Interaction between $x_1$ and $x_2$ |
| Accumulation rate | $k_3$ | 1 | Growth of $x_3$ under complementary control |
| Final time | $t_f$ | fixed | Horizon of the control problem |
| Control bounds | $u$ | [0,1] | Single control input |
| State bounds | $x$ | $[0,1.1]^3$ | Box constraints for $x_1, x_2, x_3$ |

### Qualitative behaviour

- The first two states interact linearly under the effect of the control, while the third state accumulates according to $1-u(t)$.
Expand Down
10 changes: 0 additions & 10 deletions ext/Descriptions/moonlander.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,6 @@ p_1(t_f) = 5.0, \; p_2(t_f) = 5.0, \; dp_1(t_f) = dp_2(t_f) &= 0.

Here, $x(t) = (p_1, p_2, dp_1, dp_2, \theta, d\theta)$, and the total thrust in the lander frame $F_{\text{tot}}$ is obtained by rotating the engine thrusts according to the lander's orientation.

### Parameter values

- Mass: $m = 1$
- Lunar gravity: $g = 9.81$
- Moment of inertia: $I = 0.1$
- Distance between thrusters: $D = 1$
- Maximum thrust: $F_{\max} = 2g$
- Target position: $p_{\rm target} = [5.0, 5.0]$
- Final time bounds: $t_f \in [0.1, 1.0]$

### Qualitative behaviour

The optimal solution typically exhibits a **bang–bang structure**, where thrusts switch between minimum and maximum values, ensuring minimal landing time while satisfying position and velocity constraints.
Expand Down
10 changes: 0 additions & 10 deletions ext/Descriptions/mountain_car.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,6 @@ The problem can be stated as
\end{aligned}
```

### Parameters

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Power coefficient | $a$ | 0.001 |
| Gravity coefficient | $b$ | 0.0025 |
| Frequency coefficient | $c$ | 3.0 |
| Initial position | $x_0$ | -0.5 |
| Target position | $x_f$ | 0.5 |

### Qualitative behaviour

- The car must oscillate back and forth in the valley to build enough kinetic energy to climb the right hill.
Expand Down
7 changes: 0 additions & 7 deletions ext/Descriptions/robbins.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,6 @@ x(0) = (1, -2, 0), \qquad x(T) = (0,0,0),

and horizon $T=10$. In our simulations we use parameters $\alpha=3$, $\beta=0$, $\gamma=0.5$.

### Parameter values

- Weight on state $x_1$: $\alpha = 3$
- Weight on squared state: $\beta = 0$
- Weight on squared control: $\gamma = 0.5$
- Final time: $T = 10$

### Qualitative behaviour

The exact solution exhibits **infinitely many isolated contact points**, where the state constraint $x_1(t)=0$ is active.
Expand Down
13 changes: 0 additions & 13 deletions ext/Descriptions/robot.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,19 +28,6 @@ I_\phi(t) = (L-\rho(t))^3 + \rho(t)^3, \\[0.5em]

The horizon is **free**, as the total transfer time $T$ is optimised.

### Parameter values

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Total arm length | $L$ | 5 |
| Initial radial position | $\rho_0$ | 4.5 |
| Initial vertical angle | $\phi_0$ | $\pi/4$ |
| Final horizontal angle | $\theta_f$ | $2\pi/3$ |
| Maximum radial control | $u_\rho^{\max}$ | 1 |
| Maximum horizontal control | $u_\theta^{\max}$ | 1 |
| Maximum vertical control | $u_\phi^{\max}$ | 1 |
| Minimum final time | $T_{\min}$ | 0.1 |

### Qualitative behaviour

The optimal solution exploits the **degrees of freedom of the spherical coordinate system** to minimise the motion time.
Expand Down
15 changes: 0 additions & 15 deletions ext/Descriptions/rocket.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,21 +45,6 @@ c = \frac{1}{2} \sqrt{g_0 h_0}
T_{\max} = T_c m_0 g_0
```

### Parameters

| Parameter | Symbol | Value |
|----------------------------|--------|------------------------|
| Initial altitude | $h_0$ | 1 |
| Initial velocity | $v_0$ | 0 |
| Initial mass | $m_0$ | 1 |
| Gravitational constant | $g_0$ | 1 |
| Thrust coefficient | $T_c$ | 3.5 |
| Drag coefficient | $D_c$ | $\frac{1}{2} v_c \frac{m_0}{g_0}$ |
| Characteristic altitude | $h_c$ | 500 |
| Characteristic velocity | $v_c$ | 620 |
| Characteristic mass ratio | $m_c$ | 0.6 |
| Final mass | $m_f$ | $m_c m_0$ |

### Qualitative behaviour

The optimal trajectory often exhibits a **bang–singular–bang structure**, with thrust at maximum, then along a singular arc, and finally at minimum.
Expand Down
16 changes: 0 additions & 16 deletions ext/Descriptions/space_shuttle.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,22 +32,6 @@ v_{\min} \le v(t) \le v_{\max}, \\[0.5em]

The final time $T$ is free but bounded.

### Parameters

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Initial altitude | $h_s$ | $2.6 \times 10^5$ ft |
| Initial velocity | $v_s$ | $2.56 \times 10^4$ ft/s |
| Initial flight path angle | $\gamma_s$ | $-1^\circ$ |
| Initial azimuth | $\psi_s$ | $90^\circ$ |
| Final altitude | $h_t$ | $0.8 \times 10^5$ ft |
| Final velocity | $v_t$ | $0.25 \times 10^4$ ft/s |
| Final flight path angle | $\gamma_t$ | $-5^\circ$ |
| Mass | $m$ | $w/g_0$ |
| Reference area | $S$ | 2690 |
| Earth's radius | $R_e$ | 20902900 ft |
| Gravitational parameter | $\mu$ | $0.14076539 \cdot 10^{17}$ |

### Qualitative behaviour

- The optimal trajectory balances **lift** and **drag** to control heating and deceleration while extending crossrange.
Expand Down
10 changes: 0 additions & 10 deletions ext/Descriptions/steering.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,16 +27,6 @@ where
- the control $u$ is the steering control, bounded by $u_{\min} = -\pi/2$ and $u_{\max} = \pi/2$,
- the parameter $a$ is a constant scaling the acceleration.

### Parameter values

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Acceleration magnitude | $a$ | 100 |
| Control lower bound | $u_{\min}$ | $-\pi/2$ |
| Control upper bound | $u_{\max}$ | $\pi/2$ |
| Initial state | $x_s$ | $(0,0,0,0)$ |
| Final state | $x_f$ | $(\text{unspecified},5,45,0)$ |

### Qualitative behaviour

The optimal trajectory typically exhibits **bang–bang control**, where the steering input switches between its extreme values to minimise time.
Expand Down
8 changes: 0 additions & 8 deletions ext/Descriptions/vanderpol.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,6 @@ The problem can be stated as
\end{aligned}
```

### Parameters

| Parameter | Symbol | Value |
|-----------|--------|-------|
| Oscillator frequency | $\omega$ | 1 |
| Nonlinearity coefficient | $\varepsilon$ | 1 |
| Final time | $T$ | 2 |

### Qualitative behaviour

- The optimal control $u(t)$ regulates the nonlinear oscillations to minimise both state excursions and control effort.
Expand Down
38 changes: 38 additions & 0 deletions ext/MetaData/balanced_field.jl
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,44 @@ balanced_field_meta = OrderedDict(
α_min=-0.1745, # -10 degrees
α_max_ctrl=0.2618, # 15 degrees
),
:parameter_info => (
t0=(unit="s", meaning="initial time, at the speed V1"),
m=(unit="kg", meaning="mass of the aircraft"),
g=(unit="m/s²", meaning="gravitational acceleration"),
ρ=(unit="kg/m³", meaning="air density"),
S=(unit="m²", meaning="wing area"),
CD0=(unit=nothing, meaning="zero-lift drag coefficient"),
AR=(unit=nothing, meaning="aspect ratio of the wing"),
e=(unit=nothing, meaning="Oswald efficiency factor"),
CL0=(unit=nothing, meaning="lift coefficient at zero angle of attack"),
CL_max=(unit=nothing, meaning="maximum lift coefficient, reached at α_max"),
h_w=(
unit="m",
meaning="height of the wing above the centre of gravity, in the ground effect",
),
span=(unit="m", meaning="wingspan"),
α_max=(unit="rad", meaning="angle of attack at the maximum lift coefficient"),
T=(unit="N", meaning="thrust, one engine out"),
r_t0=(unit="m", meaning="initial range, at V1"),
v_t0=(unit="m/s", meaning="initial velocity, V1"),
h_t0=(unit="m", meaning="initial altitude"),
γ_t0=(unit="rad", meaning="initial flight path angle"),
h_tf=(unit="m", meaning="final altitude, the screen height of 35 ft"),
γ_tf=(unit="rad", meaning="final flight path angle, 5°"),
v_min=(
unit="m/s",
meaning="lower bound of the velocity (not used by the models yet, which use 1)",
),
v_max=(
unit="m/s",
meaning="upper bound of the velocity (not used by the models yet)",
),
α_min=(
unit="rad",
meaning="lower bound of the angle of attack (not used by the models yet, which use 0)",
),
α_max_ctrl=(unit="rad", meaning="upper bound of the angle of attack"),
),
:status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid),
# initial guess of every modeling (#377), from the parameters
:init =>
Expand Down
Loading
Loading