diff --git a/docs/problems.jl b/docs/problems.jl index 1d5bee536..3c2f0bb66 100644 --- a/docs/problems.jl +++ b/docs/problems.jl @@ -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: diff --git a/ext/Descriptions/balanced_field.md b/ext/Descriptions/balanced_field.md index bf4905120..9f8462f41 100644 --- a/ext/Descriptions/balanced_field.md +++ b/ext/Descriptions/balanced_field.md @@ -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 @@ -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). diff --git a/ext/Descriptions/bioreactor.md b/ext/Descriptions/bioreactor.md index 17b4ff5bb..089298644 100644 --- a/ext/Descriptions/bioreactor.md +++ b/ext/Descriptions/bioreactor.md @@ -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**: diff --git a/ext/Descriptions/chain.md b/ext/Descriptions/chain.md index efaa276df..b83ca3e11 100644 --- a/ext/Descriptions/chain.md +++ b/ext/Descriptions/chain.md @@ -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: diff --git a/ext/Descriptions/dielectrophoretic_particle.md b/ext/Descriptions/dielectrophoretic_particle.md index fb23a54ba..d11eaaf23 100644 --- a/ext/Descriptions/dielectrophoretic_particle.md +++ b/ext/Descriptions/dielectrophoretic_particle.md @@ -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**. diff --git a/ext/Descriptions/double_oscillator.md b/ext/Descriptions/double_oscillator.md index 67114c004..61b9b2d44 100644 --- a/ext/Descriptions/double_oscillator.md +++ b/ext/Descriptions/double_oscillator.md @@ -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. diff --git a/ext/Descriptions/electric_vehicle.md b/ext/Descriptions/electric_vehicle.md index 26c2633da..d8b4f2068 100644 --- a/ext/Descriptions/electric_vehicle.md +++ b/ext/Descriptions/electric_vehicle.md @@ -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. diff --git a/ext/Descriptions/glider.md b/ext/Descriptions/glider.md index 55074758f..aa298f9c9 100644 --- a/ext/Descriptions/glider.md +++ b/ext/Descriptions/glider.md @@ -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. diff --git a/ext/Descriptions/insurance.md b/ext/Descriptions/insurance.md index 587e487f6..dce1e7fb2 100644 --- a/ext/Descriptions/insurance.md +++ b/ext/Descriptions/insurance.md @@ -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. diff --git a/ext/Descriptions/jackson.md b/ext/Descriptions/jackson.md index d8f8cdf81..d8b516178 100644 --- a/ext/Descriptions/jackson.md +++ b/ext/Descriptions/jackson.md @@ -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)$. diff --git a/ext/Descriptions/moonlander.md b/ext/Descriptions/moonlander.md index 85ced3fe5..b37448d34 100644 --- a/ext/Descriptions/moonlander.md +++ b/ext/Descriptions/moonlander.md @@ -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. diff --git a/ext/Descriptions/mountain_car.md b/ext/Descriptions/mountain_car.md index e567f5707..162a757c3 100644 --- a/ext/Descriptions/mountain_car.md +++ b/ext/Descriptions/mountain_car.md @@ -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. diff --git a/ext/Descriptions/robbins.md b/ext/Descriptions/robbins.md index df371cd9c..f8e218d9c 100644 --- a/ext/Descriptions/robbins.md +++ b/ext/Descriptions/robbins.md @@ -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. diff --git a/ext/Descriptions/robot.md b/ext/Descriptions/robot.md index f3bee986c..dd7a61d13 100644 --- a/ext/Descriptions/robot.md +++ b/ext/Descriptions/robot.md @@ -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. diff --git a/ext/Descriptions/rocket.md b/ext/Descriptions/rocket.md index b5e923411..08ae2bdae 100644 --- a/ext/Descriptions/rocket.md +++ b/ext/Descriptions/rocket.md @@ -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. diff --git a/ext/Descriptions/space_shuttle.md b/ext/Descriptions/space_shuttle.md index 2fba4dbc4..c91b23c98 100644 --- a/ext/Descriptions/space_shuttle.md +++ b/ext/Descriptions/space_shuttle.md @@ -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. diff --git a/ext/Descriptions/steering.md b/ext/Descriptions/steering.md index 65c28a634..791404417 100644 --- a/ext/Descriptions/steering.md +++ b/ext/Descriptions/steering.md @@ -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. diff --git a/ext/Descriptions/vanderpol.md b/ext/Descriptions/vanderpol.md index 078bab392..fc5be6cf2 100644 --- a/ext/Descriptions/vanderpol.md +++ b/ext/Descriptions/vanderpol.md @@ -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. diff --git a/ext/MetaData/balanced_field.jl b/ext/MetaData/balanced_field.jl index 1856e72af..66989b79d 100644 --- a/ext/MetaData/balanced_field.jl +++ b/ext/MetaData/balanced_field.jl @@ -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 => diff --git a/ext/MetaData/beam.jl b/ext/MetaData/beam.jl index 8694db393..c531c933d 100644 --- a/ext/MetaData/beam.jl +++ b/ext/MetaData/beam.jl @@ -1,7 +1,25 @@ beam_meta = OrderedDict( :grid_size => 500, :parameters => (t0=0, tf=1, x₁_l=0, x₁_u=0.1, x₁_t0=0, x₂_t0=1, x₁_tf=0, x₂_tf=-1), - :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid, ModelingToolkit=:valid), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + x₁_l=(unit=nothing, meaning="lower bound of the position x₁"), + x₁_u=( + unit=nothing, + meaning="upper bound of the position x₁ (the state constraint)", + ), + x₁_t0=(unit=nothing, meaning="initial position x₁"), + x₂_t0=(unit=nothing, meaning="initial velocity x₂"), + x₁_tf=(unit=nothing, meaning="final position x₁"), + x₂_tf=(unit=nothing, meaning="final velocity x₂"), + ), + :status => ( + OptimalControl=:valid, + OptimalControlScalarized=:valid, + JuMP=:valid, + ModelingToolkit=:valid, + ), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.05, 0.1], control=0.1), :reference_solution => diff --git a/ext/MetaData/bioreactor.jl b/ext/MetaData/bioreactor.jl index d0ced5ea5..7bbfc5f54 100644 --- a/ext/MetaData/bioreactor.jl +++ b/ext/MetaData/bioreactor.jl @@ -23,6 +23,32 @@ bioreactor_meta = OrderedDict( b_t0_l=0.5, b_t0_u=3, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time, 20 light cycles"), + β=(unit=nothing, meaning="coupling of the flow u between the two units"), + c=(unit=nothing, meaning="scaling of the methane production in the cost"), + γ=(unit=nothing, meaning="conversion of algae into substrate"), + halfperiod=(unit=nothing, meaning="half of the period of the light cycle"), + Ks=( + unit=nothing, + meaning="half-saturation constant of the Monod growth of the biomass", + ), + μ2m=(unit=nothing, meaning="maximum growth rate of the biomass"), + μbar=(unit=nothing, meaning="maximum growth rate of the algae, at full light"), + r=(unit=nothing, meaning="decay rate of the algae"), + y_l=(unit=nothing, meaning="lower bound of the algae concentration y"), + s_l=(unit=nothing, meaning="lower bound of the substrate concentration s"), + b_l=(unit=nothing, meaning="lower bound of the biomass concentration b"), + u_l=(unit=nothing, meaning="lower bound of the flow u"), + u_u=(unit=nothing, meaning="upper bound of the flow u"), + y_t0_l=(unit=nothing, meaning="lower bound of the initial algae concentration"), + y_t0_u=(unit=nothing, meaning="upper bound of the initial algae concentration"), + s_t0_l=(unit=nothing, meaning="lower bound of the initial substrate concentration"), + s_t0_u=(unit=nothing, meaning="upper bound of the initial substrate concentration"), + b_t0_l=(unit=nothing, meaning="lower bound of the initial biomass concentration"), + b_t0_u=(unit=nothing, meaning="upper bound of the initial biomass concentration"), + ), :status => (OptimalControl=:valid, JuMP=:valid, ModelingToolkit=:valid), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[50, 50, 50], control=0.5), diff --git a/ext/MetaData/brachistochrone.jl b/ext/MetaData/brachistochrone.jl index de97f204a..09b2ecce3 100644 --- a/ext/MetaData/brachistochrone.jl +++ b/ext/MetaData/brachistochrone.jl @@ -11,6 +11,23 @@ brachistochrone_meta = OrderedDict( u_min=(-pi), u_max=pi, ), + :parameter_info => ( + g=(unit="m/s²", meaning="gravitational acceleration"), + t0=(unit="s", meaning="initial time"), + x0=(unit="m", meaning="initial horizontal position px"), + y0=(unit="m", meaning="initial vertical position py"), + v0=(unit="m/s", meaning="initial speed"), + xf=(unit="m", meaning="final horizontal position px"), + yf=(unit="m", meaning="final vertical position py"), + u_min=( + unit="rad", + meaning="lower bound of the angle u (not read by the models yet, which use −1.57)", + ), + u_max=( + unit="rad", + meaning="upper bound of the angle u (not read by the models yet, which use 1.57)", + ), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => diff --git a/ext/MetaData/bryson_denham.jl b/ext/MetaData/bryson_denham.jl index 798507738..af1bac456 100644 --- a/ext/MetaData/bryson_denham.jl +++ b/ext/MetaData/bryson_denham.jl @@ -9,6 +9,18 @@ bryson_denham_meta = OrderedDict( x2_tf=-1.0, # Final velocity x1_max=1 / 9, # State constraint: x1(t) <= x1_max ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + x1_t0=(unit=nothing, meaning="initial position x₁"), + x2_t0=(unit=nothing, meaning="initial velocity x₂"), + x1_tf=(unit=nothing, meaning="final position x₁"), + x2_tf=(unit=nothing, meaning="final velocity x₂"), + x1_max=( + unit=nothing, + meaning="upper bound of the position x₁ (the state constraint)", + ), + ), :status => ( OptimalControl=:valid, OptimalControlScalarized=:valid, diff --git a/ext/MetaData/cart_pendulum.jl b/ext/MetaData/cart_pendulum.jl index 5bdf5f553..a68d5bf87 100644 --- a/ext/MetaData/cart_pendulum.jl +++ b/ext/MetaData/cart_pendulum.jl @@ -19,6 +19,25 @@ cart_pendulum_meta = OrderedDict( θ_tf=π, ω_tf=0, ), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + g=(unit="m/s²", meaning="gravitational acceleration"), + L=(unit="m", meaning="length of the pendulum"), + m=(unit="kg", meaning="mass of the pendulum"), + mcart=(unit="kg", meaning="mass of the cart"), + Fex_l=(unit="N", meaning="lower bound of the force Fex on the cart"), + Fex_u=(unit="N", meaning="upper bound of the force Fex on the cart"), + x_l=(unit="m", meaning="lower bound of the position of the cart"), + x_u=(unit="m", meaning="upper bound of the position of the cart"), + v_l=(unit="m/s", meaning="lower bound of the velocity of the cart"), + v_u=(unit="m/s", meaning="upper bound of the velocity of the cart"), + tf_l=(unit="s", meaning="lower bound of the final time"), + x_t0=(unit="m", meaning="initial position of the cart"), + θ_t0=(unit="rad", meaning="initial angle of the pendulum"), + ω_t0=(unit="rad/s", meaning="initial angular velocity of the pendulum"), + θ_tf=(unit="rad", meaning="final angle of the pendulum (upright)"), + ω_tf=(unit="rad/s", meaning="final angular velocity of the pendulum"), + ), :status => (OptimalControl=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.1, 0.1, 0.1, 0.1], control=0.1, variable=[1.0, 0.1]), diff --git a/ext/MetaData/chain.jl b/ext/MetaData/chain.jl index 4cc47aa8a..429978d61 100644 --- a/ext/MetaData/chain.jl +++ b/ext/MetaData/chain.jl @@ -1,7 +1,21 @@ chain_meta = OrderedDict( :grid_size => 500, :parameters => (t0=0, tf=1, L=4, a=1, b=3, x₂_t0=0, x₃_t0=0), - :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid, ModelingToolkit=:valid), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + L=(unit=nothing, meaning="length of the chain, the final value of x₃"), + a=(unit=nothing, meaning="initial value of x₁"), + b=(unit=nothing, meaning="final value of x₁"), + x₂_t0=(unit=nothing, meaning="initial value of x₂"), + x₃_t0=(unit=nothing, meaning="initial value of x₃"), + ), + :status => ( + OptimalControl=:valid, + OptimalControlScalarized=:valid, + JuMP=:valid, + ModelingToolkit=:valid, + ), # initial guess of every modeling (#377), from the parameters :init => p -> begin (; t0, tf, a, b) = p diff --git a/ext/MetaData/dielectrophoretic_particle.jl b/ext/MetaData/dielectrophoretic_particle.jl index 2d09f9671..990c28d2a 100644 --- a/ext/MetaData/dielectrophoretic_particle.jl +++ b/ext/MetaData/dielectrophoretic_particle.jl @@ -1,6 +1,20 @@ dielectrophoretic_particle_meta = OrderedDict( :grid_size => 500, :parameters => (t0=0, x_t0=1, y_t0=0, x_tf=2, α=-0.75, c=1, u_l=-1, u_u=1, tf_l=0.1), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + x_t0=(unit=nothing, meaning="initial position x of the particle"), + y_t0=(unit=nothing, meaning="initial value of y"), + x_tf=(unit=nothing, meaning="final position x of the particle"), + α=( + unit=nothing, + meaning="coefficient of the quadratic term α u² in the dynamics of x", + ), + c=(unit=nothing, meaning="damping coefficient in the dynamics of y"), + u_l=(unit=nothing, meaning="lower bound of the control u"), + u_u=(unit=nothing, meaning="upper bound of the control u"), + tf_l=(unit=nothing, meaning="lower bound of the final time"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[1, 0.5], control=0.5, variable=8), diff --git a/ext/MetaData/double_oscillator.jl b/ext/MetaData/double_oscillator.jl index b9ca27586..47c38532d 100644 --- a/ext/MetaData/double_oscillator.jl +++ b/ext/MetaData/double_oscillator.jl @@ -13,7 +13,28 @@ double_oscillator_meta = OrderedDict( x₁_t0=0, x₂_t0=0, ), - :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid, ModelingToolkit=:valid), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + tf=(unit="s", meaning="final time, one period of the force F"), + m1=(unit="kg", meaning="mass of the first body, driven by the force F"), + m2=(unit="kg", meaning="mass of the second body, damped by the control"), + c=(unit="N·s/m", meaning="damping coefficient of the second body"), + k1=( + unit="N/m", + meaning="stiffness of the spring between the first body and the frame", + ), + k2=(unit="N/m", meaning="stiffness of the spring between the two bodies"), + u_l=(unit=nothing, meaning="lower bound of the control u"), + u_u=(unit=nothing, meaning="upper bound of the control u"), + x₁_t0=(unit="m", meaning="initial position x₁ of the first body"), + x₂_t0=(unit="m", meaning="initial position x₂ of the second body"), + ), + :status => ( + OptimalControl=:valid, + OptimalControlScalarized=:valid, + JuMP=:valid, + ModelingToolkit=:valid, + ), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.1, 0.1, 0.1, 0.1], control=0.1), ) diff --git a/ext/MetaData/ducted_fan.jl b/ext/MetaData/ducted_fan.jl index 62349951b..c7a55d643 100644 --- a/ext/MetaData/ducted_fan.jl +++ b/ext/MetaData/ducted_fan.jl @@ -27,6 +27,36 @@ ducted_fan_meta = OrderedDict( α_tf=0, vα_tf=0, ), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + r=( + unit="m", + meaning="distance from the centre of mass to the point where the force u₁ applies", + ), + J=(unit="kg·m²", meaning="moment of inertia"), + m=(unit="kg", meaning="mass"), + mg=(unit="N", meaning="weight"), + μ=(unit=nothing, meaning="weight of the final time in the cost"), + α_l=(unit="rad", meaning="lower bound of the angle α"), + α_u=(unit="rad", meaning="upper bound of the angle α"), + u₁_l=(unit="N", meaning="lower bound of the force u₁"), + u₁_u=(unit="N", meaning="upper bound of the force u₁"), + u₂_l=(unit="N", meaning="lower bound of the force u₂"), + u₂_u=(unit="N", meaning="upper bound of the force u₂"), + tf_l=(unit="s", meaning="lower bound of the final time"), + x₁_t0=(unit="m", meaning="initial horizontal position"), + v₁_t0=(unit="m/s", meaning="initial horizontal velocity"), + x₂_t0=(unit="m", meaning="initial vertical position"), + v₂_t0=(unit="m/s", meaning="initial vertical velocity"), + α_t0=(unit="rad", meaning="initial angle"), + vα_t0=(unit="rad/s", meaning="initial angular velocity"), + x₁_tf=(unit="m", meaning="final horizontal position"), + v₁_tf=(unit="m/s", meaning="final horizontal velocity"), + x₂_tf=(unit="m", meaning="final vertical position"), + v₂_tf=(unit="m/s", meaning="final vertical velocity"), + α_tf=(unit="rad", meaning="final angle"), + vα_tf=(unit="rad/s", meaning="final angular velocity"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.1, 0.1, -0.1, 0.1, 0.1, 0.1], control=[0.1, 1], variable=1.5), diff --git a/ext/MetaData/electric_vehicle.jl b/ext/MetaData/electric_vehicle.jl index 713415848..4bbcf32cc 100644 --- a/ext/MetaData/electric_vehicle.jl +++ b/ext/MetaData/electric_vehicle.jl @@ -17,7 +17,32 @@ electric_vehicle_meta = OrderedDict( x_tf=10, v_tf=0, ), - :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid, ModelingToolkit=:valid), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + tf=(unit="s", meaning="final time"), + b1=(unit=nothing, meaning="weight of the power u·v in the cost"), + b2=(unit=nothing, meaning="weight of u² in the cost"), + h0=(unit=nothing, meaning="constant resistance in the dynamics of v"), + h1=(unit=nothing, meaning="gain of the control u in the dynamics of v"), + h2=(unit=nothing, meaning="coefficient of the quadratic drag v²"), + α0=( + unit=nothing, + meaning="coefficient of degree 0 of the road profile, a cubic in x", + ), + α1=(unit=nothing, meaning="coefficient of degree 1 of the road profile"), + α2=(unit=nothing, meaning="coefficient of degree 2 of the road profile"), + α3=(unit=nothing, meaning="coefficient of degree 3 of the road profile"), + x_t0=(unit="m", meaning="initial position"), + v_t0=(unit="m/s", meaning="initial velocity"), + x_tf=(unit="m", meaning="final position, the length of the trip"), + v_tf=(unit="m/s", meaning="final velocity"), + ), + :status => ( + OptimalControl=:valid, + OptimalControlScalarized=:valid, + JuMP=:valid, + ModelingToolkit=:valid, + ), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.1, 0.1], control=0.1), ) diff --git a/ext/MetaData/glider.jl b/ext/MetaData/glider.jl index ec22386a7..ca93e3c68 100644 --- a/ext/MetaData/glider.jl +++ b/ext/MetaData/glider.jl @@ -23,6 +23,29 @@ glider_meta = OrderedDict( x_l=0, vx_l=0, ), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + x_t0=(unit="m", meaning="initial horizontal position"), + y_t0=(unit="m", meaning="initial altitude"), + y_tf=(unit="m", meaning="final altitude"), + vx_t0=(unit="m/s", meaning="initial horizontal velocity"), + vx_tf=(unit="m/s", meaning="final horizontal velocity"), + vy_t0=(unit="m/s", meaning="initial vertical velocity"), + vy_tf=(unit="m/s", meaning="final vertical velocity"), + u_c=(unit="m/s", meaning="maximum velocity of the updraft of the thermal"), + r_t0=(unit="m", meaning="radius of the thermal"), + m=(unit="kg", meaning="mass of the glider"), + g=(unit="m/s²", meaning="gravitational acceleration"), + c0=(unit=nothing, meaning="zero-lift drag coefficient"), + c1=(unit=nothing, meaning="induced drag coefficient, D ∝ c0 + c1 cL²"), + S=(unit="m²", meaning="wing area"), + ρ=(unit="kg/m³", meaning="air density"), + cL_min=(unit=nothing, meaning="lower bound of the lift coefficient cL"), + cL_max=(unit=nothing, meaning="upper bound of the lift coefficient cL"), + tf_l=(unit="s", meaning="lower bound of the final time"), + x_l=(unit="m", meaning="lower bound of the horizontal position"), + vx_l=(unit="m/s", meaning="lower bound of the horizontal velocity"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => diff --git a/ext/MetaData/insurance.jl b/ext/MetaData/insurance.jl index 34539d80c..c63ccac67 100644 --- a/ext/MetaData/insurance.jl +++ b/ext/MetaData/insurance.jl @@ -26,6 +26,50 @@ insurance_meta = OrderedDict( m_t0=0.001, x₃_t0=0, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + γ=( + unit=nothing, + meaning="rate at which the health H deteriorates, H = h0 − γ (t − t0)(1 − v(m))", + ), + λ=( + unit=nothing, + meaning="rate of the exponential law of the time of illness, in the density fx", + ), + h0=(unit=nothing, meaning="initial health level"), + w=(unit=nothing, meaning="wealth in the revenue R = w − P + I − m − ε"), + s=( + unit=nothing, + meaning="sensitivity of the utility to the revenue, U = 1 − exp(−s R) + H", + ), + k=(unit=nothing, meaning="coefficient of the loss ε = k (t − t0) / (tf − t + 1)"), + σ=( + unit=nothing, + meaning="loading of the premium, P = x₃(tf) with ẋ₃ = (1 + σ) I fx", + ), + α=( + unit=nothing, + meaning="exponent of the efficacy v(m) = m^(α/2) / (1 + m^(α/2)) of the expenses", + ), + I_l=(unit=nothing, meaning="lower bound of the indemnity I"), + I_u=(unit=nothing, meaning="upper bound of the indemnity I"), + m_l=(unit=nothing, meaning="lower bound of the medical expenses m"), + m_u=(unit=nothing, meaning="upper bound of the medical expenses m"), + h_l=(unit=nothing, meaning="lower bound of the control h"), + h_u=(unit=nothing, meaning="upper bound of the control h"), + R_l=(unit=nothing, meaning="lower bound of the revenue R"), + H_l=(unit=nothing, meaning="lower bound of the health H"), + U_l=(unit=nothing, meaning="lower bound of the utility U"), + dUdR_l=(unit=nothing, meaning="lower bound of the marginal utility dU/dR"), + P_l=(unit=nothing, meaning="lower bound of the premium P"), + I_t0=(unit=nothing, meaning="initial indemnity"), + m_t0=(unit=nothing, meaning="initial medical expenses"), + x₃_t0=( + unit=nothing, + meaning="initial value of x₃, the accumulated cost of the indemnity", + ), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.1, 0.1, 0.1], control=[0.1, 0.1, 0.1, 0.1, 0.1], variable=0.1), diff --git a/ext/MetaData/jackson.jl b/ext/MetaData/jackson.jl index a972e75d7..60215197f 100644 --- a/ext/MetaData/jackson.jl +++ b/ext/MetaData/jackson.jl @@ -18,6 +18,27 @@ jackson_meta = OrderedDict( b_t0=0, x₃_t0=0, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + k1=(unit=nothing, meaning="rate of the reaction from a to b"), + k2=(unit=nothing, meaning="rate of the reverse reaction from b to a"), + k3=(unit=nothing, meaning="rate of the reaction from b to x₃"), + a_l=(unit=nothing, meaning="lower bound of the concentration a"), + a_u=(unit=nothing, meaning="upper bound of the concentration a"), + b_l=(unit=nothing, meaning="lower bound of the concentration b"), + b_u=(unit=nothing, meaning="upper bound of the concentration b"), + x₃_l=(unit=nothing, meaning="lower bound of x₃"), + x₃_u=(unit=nothing, meaning="upper bound of x₃"), + u_l=( + unit=nothing, + meaning="lower bound of the control u, the fraction of the first catalyst", + ), + u_u=(unit=nothing, meaning="upper bound of the control u"), + a_t0=(unit=nothing, meaning="initial concentration a"), + b_t0=(unit=nothing, meaning="initial concentration b"), + x₃_t0=(unit=nothing, meaning="initial value of x₃"), + ), :status => ( OptimalControl=:valid, OptimalControlScalarized=:valid, diff --git a/ext/MetaData/moonlander.jl b/ext/MetaData/moonlander.jl index 47be7846d..446be1102 100644 --- a/ext/MetaData/moonlander.jl +++ b/ext/MetaData/moonlander.jl @@ -22,6 +22,28 @@ moonlander_meta = OrderedDict( dp₁_tf=0, dp₂_tf=0, ), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + m=(unit="kg", meaning="mass of the lander"), + g=(unit="m/s²", meaning="gravitational acceleration"), + I=(unit="kg·m²", meaning="moment of inertia of the lander"), + D=(unit="m", meaning="distance between the two thrusters"), + max_thrust=(unit="N", meaning="upper bound of each thrust F₁, F₂"), + tf_l=(unit="s", meaning="lower bound of the final time"), + tf_u=(unit="s", meaning="upper bound of the final time"), + F₁_l=(unit="N", meaning="lower bound of the thrust F₁"), + F₂_l=(unit="N", meaning="lower bound of the thrust F₂"), + p₁_t0=(unit="m", meaning="initial horizontal position"), + p₂_t0=(unit="m", meaning="initial vertical position"), + dp₁_t0=(unit="m/s", meaning="initial horizontal velocity"), + dp₂_t0=(unit="m/s", meaning="initial vertical velocity"), + θ_t0=(unit="rad", meaning="initial orientation"), + dθ_t0=(unit="rad/s", meaning="initial angular velocity"), + p₁_tf=(unit="m", meaning="final horizontal position, the target"), + p₂_tf=(unit="m", meaning="final vertical position, the target"), + dp₁_tf=(unit="m/s", meaning="final horizontal velocity"), + dp₂_tf=(unit="m/s", meaning="final vertical velocity"), + ), :status => (OptimalControl=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => p -> (state=[0.1, 0.1, 0.1, 0.1, 0.1, 0.1], control=[5.0, 5.0], variable=0.5), diff --git a/ext/MetaData/mountain_car.jl b/ext/MetaData/mountain_car.jl index 251d285f2..db712c035 100644 --- a/ext/MetaData/mountain_car.jl +++ b/ext/MetaData/mountain_car.jl @@ -18,6 +18,24 @@ mountain_car_meta = OrderedDict( b=0.0025, c=3.0, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf_start=(unit=nothing, meaning="final time of the initial guess"), + tf_min=(unit=nothing, meaning="lower bound of the final time"), + pos_t0=(unit=nothing, meaning="initial position"), + vel_t0=(unit=nothing, meaning="initial velocity"), + pos_tf=(unit=nothing, meaning="final position, the top of the hill"), + vel_tf_min=(unit=nothing, meaning="lower bound of the final velocity"), + pos_min=(unit=nothing, meaning="lower bound of the position"), + pos_max=(unit=nothing, meaning="upper bound of the position"), + vel_min=(unit=nothing, meaning="lower bound of the velocity"), + vel_max=(unit=nothing, meaning="upper bound of the velocity"), + u_min=(unit=nothing, meaning="lower bound of the control u"), + u_max=(unit=nothing, meaning="upper bound of the control u"), + a=(unit=nothing, meaning="gain of the control (engine power)"), + b=(unit=nothing, meaning="coefficient of the gravity term b cos(c pos)"), + c=(unit=nothing, meaning="frequency of the hill profile"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid, ModelingToolkit=:valid), :notes => "On the default grid, the configuration modeler=exa solver=madnlp reaches the objective 102.381 in both OptimalControl modelings, against 102.398 with Ipopt in JuMP and both OptimalControl modelings, a relative gap of 1.6e-4: a convergence gap of this configuration, reported by the convergence tests (#360); the models are equivalent at the initial guess.", # initial guess of every modeling (#377), from the parameters diff --git a/ext/MetaData/robbins.jl b/ext/MetaData/robbins.jl index 53de25e99..b37aadc75 100644 --- a/ext/MetaData/robbins.jl +++ b/ext/MetaData/robbins.jl @@ -14,6 +14,20 @@ robbins_meta = OrderedDict( x₂_tf=0, x₃_tf=0, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + α=(unit=nothing, meaning="weight of x₁ in the cost"), + β=(unit=nothing, meaning="weight of x₁² in the cost"), + γ=(unit=nothing, meaning="weight of u² in the cost"), + x₁_l=(unit=nothing, meaning="lower bound of x₁ (the third-order state constraint)"), + x₁_t0=(unit=nothing, meaning="initial value of x₁"), + x₂_t0=(unit=nothing, meaning="initial value of x₂"), + x₃_t0=(unit=nothing, meaning="initial value of x₃"), + x₁_tf=(unit=nothing, meaning="final value of x₁"), + x₂_tf=(unit=nothing, meaning="final value of x₂"), + x₃_tf=(unit=nothing, meaning="final value of x₃"), + ), :status => ( OptimalControl=:valid, OptimalControlScalarized=:valid, diff --git a/ext/MetaData/robot.jl b/ext/MetaData/robot.jl index 4807dc096..c168d4a3f 100644 --- a/ext/MetaData/robot.jl +++ b/ext/MetaData/robot.jl @@ -32,6 +32,34 @@ robot_meta = OrderedDict( ϕ_u=π, tf_l=0.1, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + L=(unit=nothing, meaning="length of the arm, and upper bound of ρ"), + uρ_l=(unit=nothing, meaning="lower bound of the control uρ"), + uρ_u=(unit=nothing, meaning="upper bound of the control uρ"), + uθ_l=(unit=nothing, meaning="lower bound of the control uθ"), + uθ_u=(unit=nothing, meaning="upper bound of the control uθ"), + uϕ_l=(unit=nothing, meaning="lower bound of the control uϕ"), + uϕ_u=(unit=nothing, meaning="upper bound of the control uϕ"), + ρ_t0=(unit=nothing, meaning="initial length ρ"), + θ_t0=(unit="rad", meaning="initial horizontal angle θ"), + ϕ_t0=(unit="rad", meaning="initial vertical angle ϕ"), + dρ_t0=(unit=nothing, meaning="initial derivative of ρ"), + dθ_t0=(unit="rad", meaning="initial derivative of θ, per unit of time"), + dϕ_t0=(unit="rad", meaning="initial derivative of ϕ, per unit of time"), + ρ_tf=(unit=nothing, meaning="final length ρ"), + θ_tf=(unit="rad", meaning="final horizontal angle θ"), + ϕ_tf=(unit="rad", meaning="final vertical angle ϕ"), + dρ_tf=(unit=nothing, meaning="final derivative of ρ"), + dθ_tf=(unit="rad", meaning="final derivative of θ, per unit of time"), + dϕ_tf=(unit="rad", meaning="final derivative of ϕ, per unit of time"), + ρ_l=(unit=nothing, meaning="lower bound of the length ρ"), + θ_l=(unit="rad", meaning="lower bound of the angle θ"), + θ_u=(unit="rad", meaning="upper bound of the angle θ"), + ϕ_l=(unit="rad", meaning="lower bound of the angle ϕ"), + ϕ_u=(unit="rad", meaning="upper bound of the angle ϕ"), + tf_l=(unit=nothing, meaning="lower bound of the final time"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => diff --git a/ext/MetaData/rocket.jl b/ext/MetaData/rocket.jl index 4b6e80d6e..e37882fe8 100644 --- a/ext/MetaData/rocket.jl +++ b/ext/MetaData/rocket.jl @@ -2,6 +2,22 @@ rocket_meta = OrderedDict( :grid_size => 500, :parameters => (t0=0, h_t0=1, v_t0=0, m_t0=1, g0=1, Tc=3.5, hc=500, vc=620, mc=0.6, T_l=0, tf_l=0), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + h_t0=(unit=nothing, meaning="initial altitude, and lower bound of the altitude"), + v_t0=(unit=nothing, meaning="initial velocity, and lower bound of the velocity"), + m_t0=(unit=nothing, meaning="initial mass, and upper bound of the mass"), + g0=(unit=nothing, meaning="gravitational acceleration at the initial altitude"), + Tc=(unit=nothing, meaning="maximum thrust, in units of the initial weight m_t0 g0"), + hc=( + unit=nothing, + meaning="decay rate of the air density with the altitude, exp(−hc (h − h_t0) / h_t0)", + ), + vc=(unit=nothing, meaning="drag coefficient factor, Dc = vc m_t0 / (2 g0)"), + mc=(unit=nothing, meaning="final mass, as a fraction of the initial mass"), + T_l=(unit=nothing, meaning="lower bound of the thrust T"), + tf_l=(unit=nothing, meaning="lower bound of the final time"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => diff --git a/ext/MetaData/space_shuttle.jl b/ext/MetaData/space_shuttle.jl index 3d2b9b899..b5c70411b 100644 --- a/ext/MetaData/space_shuttle.jl +++ b/ext/MetaData/space_shuttle.jl @@ -49,6 +49,61 @@ space_shuttle_meta = OrderedDict( β_l=deg2rad(-89), β_u=deg2rad(1), ), + :parameter_info => ( + t0=(unit="s", meaning="initial time"), + w=(unit="lb", meaning="weight of the shuttle"), + g₀=(unit="ft/s²", meaning="gravitational acceleration at sea level"), + ρ₀=(unit="slug/ft³", meaning="air density at sea level"), + hᵣ=(unit="ft", meaning="scale height of the atmosphere"), + Rₑ=(unit="ft", meaning="radius of the Earth"), + μ=(unit="ft³/s²", meaning="gravitational parameter of the Earth"), + S=(unit="ft²", meaning="reference area"), + a₀=( + unit=nothing, + meaning="lift coefficient, constant term: c_L = a₀ + a₁ α (α in degrees)", + ), + a₁=(unit="1/deg", meaning="lift coefficient, linear term"), + b₀=( + unit=nothing, + meaning="drag coefficient, constant term: c_D = b₀ + b₁ α + b₂ α² (α in degrees)", + ), + b₁=(unit="1/deg", meaning="drag coefficient, linear term"), + b₂=(unit="1/deg²", meaning="drag coefficient, quadratic term"), + tf_l=(unit="s", meaning="lower bound of the final time"), + tf_u=(unit="s", meaning="upper bound of the final time"), + h_t0=(unit="10⁵ ft", meaning="initial altitude"), + ϕ_t0=(unit="rad", meaning="initial longitude"), + θ_t0=(unit="rad", meaning="initial latitude"), + v_t0=(unit="10⁴ ft/s", meaning="initial velocity"), + γ_t0=(unit="rad", meaning="initial flight path angle"), + ψ_t0=(unit="rad", meaning="initial azimuth"), + α_t0=( + unit="rad", + meaning="initial angle of attack (not used by the models nor the initial guess)", + ), + α_s=(unit="rad", meaning="angle of attack of the initial guess"), + β_s=(unit="rad", meaning="bank angle of the initial guess"), + h_tf=( + unit="10⁵ ft", + meaning="final altitude, at the Terminal Area Energy Management interface", + ), + v_tf=(unit="10⁴ ft/s", meaning="final velocity"), + γ_tf=(unit="rad", meaning="final flight path angle"), + h_l=(unit="10⁵ ft", meaning="lower bound of the altitude"), + ϕ_l=(unit="rad", meaning="lower bound of the longitude"), + ϕ_u=(unit="rad", meaning="upper bound of the longitude"), + θ_l=(unit="rad", meaning="lower bound of the latitude"), + θ_u=(unit="rad", meaning="upper bound of the latitude"), + v_l=(unit="10⁴ ft/s", meaning="lower bound of the velocity"), + γ_l=(unit="rad", meaning="lower bound of the flight path angle"), + γ_u=(unit="rad", meaning="upper bound of the flight path angle"), + ψ_l=(unit="rad", meaning="lower bound of the azimuth"), + ψ_u=(unit="rad", meaning="upper bound of the azimuth"), + α_l=(unit="rad", meaning="lower bound of the angle of attack"), + α_u=(unit="rad", meaning="upper bound of the angle of attack"), + β_l=(unit="rad", meaning="lower bound of the bank angle"), + β_u=(unit="rad", meaning="upper bound of the bank angle"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => diff --git a/ext/MetaData/steering.jl b/ext/MetaData/steering.jl index 8547a44e1..ec791f283 100644 --- a/ext/MetaData/steering.jl +++ b/ext/MetaData/steering.jl @@ -14,6 +14,20 @@ steering_meta = OrderedDict( x₃_tf=45, x₄_tf=0, ), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + a=(unit=nothing, meaning="magnitude of the acceleration"), + u_min=(unit="rad", meaning="lower bound of the steering angle u"), + u_max=(unit="rad", meaning="upper bound of the steering angle u"), + tf_l=(unit=nothing, meaning="lower bound of the final time"), + x₁_t0=(unit=nothing, meaning="initial position x₁"), + x₂_t0=(unit=nothing, meaning="initial position x₂"), + x₃_t0=(unit=nothing, meaning="initial velocity x₃"), + x₄_t0=(unit=nothing, meaning="initial velocity x₄"), + x₂_tf=(unit=nothing, meaning="final position x₂"), + x₃_tf=(unit=nothing, meaning="final velocity x₃"), + x₄_tf=(unit=nothing, meaning="final velocity x₄"), + ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters :init => diff --git a/ext/MetaData/vanderpol.jl b/ext/MetaData/vanderpol.jl index da72a9dc5..a3cb99974 100644 --- a/ext/MetaData/vanderpol.jl +++ b/ext/MetaData/vanderpol.jl @@ -1,6 +1,14 @@ vanderpol_meta = OrderedDict( :grid_size => 500, :parameters => (t0=0, tf=2, ω=1, ε=1, x₁_t0=1, x₂_t0=0), + :parameter_info => ( + t0=(unit=nothing, meaning="initial time"), + tf=(unit=nothing, meaning="final time"), + ω=(unit=nothing, meaning="frequency of the oscillator"), + ε=(unit=nothing, meaning="coefficient of the nonlinear damping"), + x₁_t0=(unit=nothing, meaning="initial value of x₁"), + x₂_t0=(unit=nothing, meaning="initial value of x₂"), + ), :status => ( OptimalControl=:valid, OptimalControlScalarized=:valid, diff --git a/src/Metadata/access.jl b/src/Metadata/access.jl index 3b8644330..c12c9eb4d 100644 --- a/src/Metadata/access.jl +++ b/src/Metadata/access.jl @@ -36,6 +36,15 @@ The following keys are valid: 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`). diff --git a/src/Metadata/loading.jl b/src/Metadata/loading.jl index 8fd91969b..70bfd1b49 100644 --- a/src/Metadata/loading.jl +++ b/src/Metadata/loading.jl @@ -10,6 +10,7 @@ const METADATA_SCHEMA = ( required=( grid_size=Int, parameters=Union{Nothing,NamedTuple}, + parameter_info=NamedTuple, status=NamedTuple, init=Function, ), diff --git a/test/suite/core/test_consistency.jl b/test/suite/core/test_consistency.jl index e13070094..16867c849 100644 --- a/test/suite/core/test_consistency.jl +++ b/test/suite/core/test_consistency.jl @@ -75,6 +75,27 @@ function test_schema() end end +""" +The unit and the meaning of every parameter (`:parameter_info`), in the order of the +parameters: the page of a problem shows them, so they are written once, in the metadata. +""" +function test_parameter_info() + Test.@testset "parameter info" verbose = VERBOSE begin + for problem in OCP.problems(; status=:all) + data = OCP.problem_metadata(problem) + info = data[:parameter_info] + parameters = data[:parameters] + Test.@test keys(info) == (isnothing(parameters) ? () : keys(parameters)) + for entry in values(info) + Test.@test entry isa NamedTuple + Test.@test keys(entry) == (:unit, :meaning) + Test.@test entry.unit isa Union{Nothing,String} + Test.@test entry.meaning isa String && !isempty(entry.meaning) + end + end + end +end + """ Every problem `:valid` somewhere has a reference: another modeling where it is `:valid`, or a reference objective at its default grid (#375). @@ -200,27 +221,19 @@ function cites_sources(text::AbstractString) end """ -The outline of a description (#449, T2): its `###` headings, in this order. The parameters -section is optional and has one of the names of `PARAMETER_HEADINGS`; the qualitative -behaviour is optional too: a page whose description has none gets a placeholder -(`with_behaviour` in `docs/problems.jl`). +The outline of a description (#449, T2): its `###` headings, in this order. The qualitative +behaviour is optional: a page whose description has none gets a placeholder +(`with_behaviour` in `docs/problems.jl`). There is no parameters section: the page generates +it from the metadata (`:parameters`, `:parameter_info`). """ const OUTLINE = ( - "Mathematical formulation", - "Parameters", - "Qualitative behaviour", - "Characteristics", - "References", + "Mathematical formulation", "Qualitative behaviour", "Characteristics", "References" ) const REQUIRED_HEADINGS = ("Mathematical formulation", "Characteristics", "References") -const PARAMETER_HEADINGS = ("Parameters", "Parameter values", "System parameters") """Whether the `###` headings of `text` follow `OUTLINE`, with every required heading.""" function follows_outline(text::AbstractString) - headings = [ - h in PARAMETER_HEADINGS ? "Parameters" : h for - h in (m[1] for m in eachmatch(r"^### (.+?)\s*$"m, text)) - ] + headings = [m[1] for m in eachmatch(r"^### (.+?)\s*$"m, text)] all(in(OUTLINE), headings) || return false issorted(headings; by=h -> findfirst(==(h), OUTLINE)) || return false allunique(headings) || return false @@ -234,12 +247,16 @@ function test_outline() text = read(joinpath(EXT, "Descriptions", "$problem.md"), String) Test.@test follows_outline(text) end - complete = "### Mathematical formulation\n### Parameter values\n### Qualitative behaviour\n### Characteristics\n### References\n" + complete = "### Mathematical formulation\n### Qualitative behaviour\n### Characteristics\n### References\n" Test.@test follows_outline(complete) Test.@test follows_outline( "### Mathematical formulation\n### Characteristics\n### References\n" ) Test.@test !follows_outline("### Characteristics\n### References\n") + # the parameters section is generated: a description has none + Test.@test !follows_outline( + "### Mathematical formulation\n### Parameters\n### Characteristics\n### References\n", + ) Test.@test !follows_outline( "### Mathematical formulation\n### References\n### Characteristics\n" ) @@ -297,6 +314,7 @@ function test_consistency() test_reference_objectives() test_no_handwritten_list() test_sources() + test_parameter_info() test_outline() test_reference_solutions() end