diff --git a/docs/problems.jl b/docs/problems.jl index cb979dd3a..1d5bee536 100644 --- a/docs/problems.jl +++ b/docs/problems.jl @@ -392,11 +392,30 @@ end # ----------------------------------- # Page # ----------------------------------- +# A description without a qualitative behaviour gets one that points to the figures of the +# modeling tabs (#449, T2): the outline of every page stays the same. +function with_behaviour(description::AbstractString) + occursin(r"^### Qualitative behaviour"m, description) && return description + placeholder = """ + ### Qualitative behaviour + + Not described yet: the solution is plotted in the tab of each modeling, under *Solution*. + + """ + return replace( + description, + "\n### Characteristics" => "\n" * placeholder * "### Characteristics"; + count=1, + ) +end + function problem_page(problem::Symbol) mods = modelings(problem) refs = references(problem) statuses = OCP.status(problem) - description = read(joinpath(ROOT, "ext", "Descriptions", "$(problem).md"), String) + description = with_behaviour( + read(joinpath(ROOT, "ext", "Descriptions", "$(problem).md"), String) + ) views = Any[(id="problem", label="Problem", kind="problem")] for (spec, adapter) in mods diff --git a/ext/Descriptions/balanced_field.md b/ext/Descriptions/balanced_field.md index 8da31b5bf..bf4905120 100644 --- a/ext/Descriptions/balanced_field.md +++ b/ext/Descriptions/balanced_field.md @@ -9,11 +9,11 @@ The state vector is $x(t) = (r(t), v(t), h(t), \gamma(t))$ and the control is th ```math \begin{aligned} \min_{\alpha, t_f} \quad & r(t_f) \\ - \text{s.t.} \quad & \dot{r}(t) = v(t) \cos \gamma(t), \\ +\text{s.t.} \quad & \dot{r}(t) = v(t) \cos \gamma(t), \\ & \dot{v}(t) = \frac{T \cos \alpha(t) - D}{m} - g \sin \gamma(t), \\ & \dot{h}(t) = v(t) \sin \gamma(t), \\ & \dot{\gamma}(t) = \frac{T \sin \alpha(t) + L}{m v(t)} - \frac{g \cos \gamma(t)}{v(t)}, \\ -& h(t_f) = 10.668 ext{ m (35 ft)}, \\ +& h(t_f) = 10.668 \text{ m (35 ft)}, \\ & \gamma(t_f) = 5^\circ. \end{aligned} ``` @@ -33,11 +33,8 @@ The parameters are based on a mid-size jet aircraft (nominal values from Dymos): ### Characteristics -- Multi-state nonlinear dynamics, -- Free final time $t_f$, -- Ground effect inclusion in the drag model ($K$ coefficient), -- Control bounds on the angle of attack $\alpha$, -- Boundary conditions representing $V_1$ conditions and final climb requirements. +- Nonlinear dynamics, with a ground effect in the drag model ($K$ coefficient). +- Boundary conditions representing the $V_1$ conditions and the final climb requirements. ### References diff --git a/ext/Descriptions/bioreactor.md b/ext/Descriptions/bioreactor.md index cf9adb95b..17b4ff5bb 100644 --- a/ext/Descriptions/bioreactor.md +++ b/ext/Descriptions/bioreactor.md @@ -51,9 +51,8 @@ The positivity constraint on biomass $b(t)$ is usually active at the beginning o ### Characteristics -- Nonlinear coupled dynamics with periodic forcing, -- Control and state constraints ensuring feasibility, -- Bang–bang and singular arc structures in the optimal control, +- Nonlinear coupled dynamics with periodic forcing. +- Bang–bang and singular arc structures in the optimal control. - Serves as a benchmark for optimal control methods with periodic and constrained systems. ### References diff --git a/ext/Descriptions/brachistochrone.md b/ext/Descriptions/brachistochrone.md index da388cf95..89764a796 100644 --- a/ext/Descriptions/brachistochrone.md +++ b/ext/Descriptions/brachistochrone.md @@ -37,7 +37,6 @@ The control $u(t)$ is continuous and varies smoothly to trace the cycloidal arc. ### Characteristics - **Nonlinear dynamics** involving trigonometric functions of the control. -- **Free final time** problem (time-optimal). - Analytical solution is a **Cycloid**. - Historically significant as the first problem solved using techniques that evolved into the Calculus of Variations. diff --git a/ext/Descriptions/cart_pendulum.md b/ext/Descriptions/cart_pendulum.md index f1a54f47f..188cd934b 100644 --- a/ext/Descriptions/cart_pendulum.md +++ b/ext/Descriptions/cart_pendulum.md @@ -63,8 +63,7 @@ Underactuation makes the problem challenging because the pendulum cannot be actu ### Characteristics -- Nonlinear, underactuated dynamics. -- Minimum-time objective with state and control constraints. +- Nonlinear, underactuated dynamics. - Serves as a benchmark for trajectory optimisation and control of underactuated systems. ### References diff --git a/ext/Descriptions/chain.md b/ext/Descriptions/chain.md index 842da9720..efaa276df 100644 --- a/ext/Descriptions/chain.md +++ b/ext/Descriptions/chain.md @@ -40,8 +40,8 @@ The control typically balances horizontal movement to minimise the vertical disp ### Characteristics -- Nonlinear dynamics with three states and one control. -- Minimum vertical displacement objective with boundary constraints. +- Nonlinear dynamics. +- Minimum vertical displacement objective. - Serves as a benchmark for trajectory optimisation and direct transcription methods in nonlinear optimal control. ### References diff --git a/ext/Descriptions/dielectrophoretic_particle.md b/ext/Descriptions/dielectrophoretic_particle.md index e9480c315..fb23a54ba 100644 --- a/ext/Descriptions/dielectrophoretic_particle.md +++ b/ext/Descriptions/dielectrophoretic_particle.md @@ -51,9 +51,8 @@ where $x_0$ and $x_f$ are the initial and final particle positions, $\alpha$ is ### Characteristics -- Nonlinear dynamics with **bilinear and quadratic terms** in the control. -- **Time-optimal objective** with control bounds. -- Free end-time formulation. +- Nonlinear dynamics with **bilinear and quadratic terms** in the control. +- **Time-optimal objective**. - Widely used as a benchmark in numerical optimal control for **microfluidic particle manipulation**. ### References diff --git a/ext/Descriptions/double_oscillator.md b/ext/Descriptions/double_oscillator.md index 05761d793..67114c004 100644 --- a/ext/Descriptions/double_oscillator.md +++ b/ext/Descriptions/double_oscillator.md @@ -42,10 +42,9 @@ where $F(t) = \sin\left(\frac{2 \pi}{T} t\right)$ is a prescribed periodic forci ### Characteristics -- Coupled linear–nonlinear dynamics with external periodic forcing. -- Control input enters through a damping term, introducing nonlinearity in the system response. -- Bounded control with symmetric limits. -- Widely used to benchmark numerical methods for constrained optimal control in mechanical systems. +- Coupled linear–nonlinear dynamics with external periodic forcing. +- Control input enters through a damping term, introducing nonlinearity in the system response. +- Widely used to benchmark numerical methods for constrained optimal control in mechanical systems. - Serves as a testbed for averaging methods and bang–bang control design. ### References diff --git a/ext/Descriptions/ducted_fan.md b/ext/Descriptions/ducted_fan.md index 41aeef0ec..0c54f1fd3 100644 --- a/ext/Descriptions/ducted_fan.md +++ b/ext/Descriptions/ducted_fan.md @@ -37,9 +37,7 @@ The weight $\mu > 0$ balances control effort and transition time. ### Characteristics -- Nonlinear six-dimensional dynamics. -- Free final time. -- Multiple input and state inequality constraints. +- Nonlinear dynamics. - Benchmark for testing constrained nonlinear OCP solvers. ### References diff --git a/ext/Descriptions/electric_vehicle.md b/ext/Descriptions/electric_vehicle.md index 568b5ea08..26c2633da 100644 --- a/ext/Descriptions/electric_vehicle.md +++ b/ext/Descriptions/electric_vehicle.md @@ -5,8 +5,6 @@ The objective is to **minimise a combination of mechanical energy consumption an Here, we denote the final time as $t_f$, with $t_f = 1$ s. ---- - ### Mathematical formulation ```math @@ -27,8 +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 | @@ -42,25 +38,19 @@ and the parameters $h_0$, $h_1$, $h_2$, $b_1$, $b_2$, and $\alpha_i$ define vehi | 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. - Road slope variations $r(x)$ introduce nonlinearities, strongly influencing the structure of the optimal control. - For flat roads, the solution often exhibits a **bang–singular–bang profile**, while slopes lead to asymmetric trajectories. ---- - ### Characteristics -- Nonlinear second-order dynamics including drag, gravity, and slope effects. -- Mixed linear–quadratic cost reflecting energy and smoothness trade-offs. -- Fixed-time ($t_f = 1$ s), fixed-distance trip with zero final velocity. +- Nonlinear second-order dynamics including drag, gravity, and slope effects. +- Mixed linear–quadratic cost reflecting energy and smoothness trade-offs. +- Fixed-distance trip with zero final velocity. - Benchmark for testing energy-optimal trajectory generation and direct transcription methods in electric vehicles. ---- - ### References - **Petit, N., & Sciarretta, A. (2011).** *Optimal drive of electric vehicles using an inversion-based trajectory generation approach*. IFAC Proceedings Volumes, 44(1), 14519–14526. diff --git a/ext/Descriptions/glider.md b/ext/Descriptions/glider.md index 66a35e9ee..55074758f 100644 --- a/ext/Descriptions/glider.md +++ b/ext/Descriptions/glider.md @@ -36,8 +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 | @@ -52,8 +50,6 @@ where $m, g, S, \rho, c_0, c_1, u_c, r_0$ are constants describing the glider an | 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. @@ -61,17 +57,11 @@ where $m, g, S, \rho, c_0, c_1, u_c, r_0$ are constants describing the glider an - The dynamics are nonlinear due to the coupling of lift, drag, and relative velocity in the thermal. - Horizontal velocity is maintained positive, and the trajectory respects the control and state constraints. ---- - ### Characteristics -- Nonlinear four-dimensional dynamics with one control input. -- Free final time. -- Mixed state and control constraints. +- Nonlinear dynamics. - Widely used as a benchmark for trajectory optimisation and direct transcription methods in nonlinear optimal control. ---- - ### References - **Dolan, E. D., & More, J. J. (2004).** *Benchmarking Optimization Software with COPS 3.0*. Argonne National Laboratory. diff --git a/ext/Descriptions/insurance.md b/ext/Descriptions/insurance.md index feab2242c..587e487f6 100644 --- a/ext/Descriptions/insurance.md +++ b/ext/Descriptions/insurance.md @@ -3,8 +3,6 @@ It consists of controlling insurance coverage, expenses, revenue, health, and ut The system dynamics model the evolution of insurance participation, expenses, and auxiliary variables, while respecting bounds on all state and control variables. The controls represent health investments, insurance revenue, health outcomes, and utility contributions. ---- - ### Mathematical formulation The **objective** is to maximise expected utility: @@ -16,8 +14,6 @@ The **objective** is to maximise expected utility: where $f_x(t)$ is the probability density of illness events. ---- - #### State, control, and auxiliary bounds The variables are subject to: @@ -30,8 +26,6 @@ The variables are subject to: \end{aligned} ``` ---- - #### Initial and terminal conditions ```math @@ -39,8 +33,6 @@ The variables are subject to: P - x_3(t_f) = 0 ``` ---- - #### Dynamics ```math @@ -64,8 +56,6 @@ v = \frac{m(t)^{\alpha/2}}{1 + m(t)^{\alpha/2}}, \quad v' = \frac{\alpha}{2} \frac{m(t)^{\alpha/2 - 1}}{(1 + m(t)^{\alpha/2})^2}. ``` ---- - #### Algebraic / auxiliary constraints ```math @@ -81,8 +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 | @@ -97,8 +85,6 @@ These constraints encode **revenue balance**, **health evolution**, **utility co | 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. @@ -106,17 +92,12 @@ These constraints encode **revenue balance**, **health evolution**, **utility co - The dynamics incorporate moral hazard effects and diminishing returns on expenses. - Auxiliary variables track utility and revenue derivatives, ensuring consistent constraints. ---- - ### Characteristics -- Nonlinear three-dimensional state dynamics with five control variables and one auxiliary. -- Fixed final time with state and control bounds. -- Models health insurance optimisation under ex post moral hazard and risk-sensitive utility. +- Nonlinear dynamics, with an auxiliary control. +- Models health insurance optimisation under ex post moral hazard and risk-sensitive utility. - Serves as a benchmark for testing constrained nonlinear OCP solvers. ---- - ### References - **Martinon, P., Picard, P., & Raj, A. (2018).** *On the design of optimal health insurance contracts under ex post moral hazard*. diff --git a/ext/Descriptions/jackson.md b/ext/Descriptions/jackson.md index ea6fc10ea..d8f8cdf81 100644 --- a/ext/Descriptions/jackson.md +++ b/ext/Descriptions/jackson.md @@ -3,8 +3,6 @@ It consists of controlling a three-dimensional system in which the first two sta The objective is to **minimise the third state at the final time**, while satisfying bounds on states and control, as well as initial and terminal conditions. The problem exhibits **singular arcs**, making it a useful benchmark for testing direct transcription and nonlinear programming methods. ---- - ### Mathematical formulation The problem can be stated as @@ -24,8 +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 | @@ -37,8 +33,6 @@ where $x_1, x_2, x_3$ are the state variables, $u$ is the control input, and $k_ | 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)$. @@ -46,17 +40,12 @@ where $x_1, x_2, x_3$ are the state variables, $u$ is the control input, and $k_ - Optimal trajectories typically include **bang–bang segments** interleaved with singular arcs. - State and control constraints are respected at all times, and the final cost depends only on $x_3(t_f)$. ---- - ### Characteristics -- Linear–nonlinear three-dimensional dynamics with **one control input**. -- State and control bounds. -- Terminal cost depends on a single state. +- Linear–nonlinear dynamics. +- Terminal cost depends on a single state. - Serves as a benchmark for testing solvers handling singular arcs and constrained optimal control. ---- - ### References - **Jackson, E. A. (1968).** *The existence of singular extremals*. Journal of Optimization Theory and Applications. diff --git a/ext/Descriptions/moonlander.md b/ext/Descriptions/moonlander.md index ffe96fc01..85ced3fe5 100644 --- a/ext/Descriptions/moonlander.md +++ b/ext/Descriptions/moonlander.md @@ -38,9 +38,8 @@ Orientation dynamics $\theta(t)$ and $d\theta(t)$ play a critical role in direct ### Characteristics -- Nonlinear coupled dynamics with orientation-dependent thrust, -- Control constraints and bounded final time ensuring feasibility, -- Terminal position and velocity constraints for a soft landing, +- Nonlinear coupled dynamics with orientation-dependent thrust. +- Terminal position and velocity constraints for a soft landing. - Benchmark problem for testing direct transcription and NLP solvers. ### References diff --git a/ext/Descriptions/mountain_car.md b/ext/Descriptions/mountain_car.md index e5b00397e..e567f5707 100644 --- a/ext/Descriptions/mountain_car.md +++ b/ext/Descriptions/mountain_car.md @@ -10,7 +10,7 @@ The problem can be stated as ```math \begin{aligned} \min_{x,v,u,t_f} \quad & J = t_f \\ - \text{s.t.} \quad & \dot{x}(t) = v(t), \\ +\text{s.t.} \quad & \dot{x}(t) = v(t), \\ & \dot{v}(t) = a \, u(t) - b \, \cos(c \, x(t)), \\ & x(0) = -0.5, \quad v(0) = 0.0, \\ & x(t_f) = 0.5, \quad v(t_f) \ge 0.0, \\ @@ -39,11 +39,7 @@ The problem can be stated as ### Characteristics -- Two-dimensional state space (position and velocity), -- Scalar control (effort/acceleration), -- **Free final time** with minimum time objective, -- State constraints (position and velocity bounds), -- Control constraints (bounds on acceleration). +- Serves as a benchmark for minimum-time problems whose solution first moves away from the goal. ### References diff --git a/ext/Descriptions/robbins.md b/ext/Descriptions/robbins.md index 3227b35f3..df371cd9c 100644 --- a/ext/Descriptions/robbins.md +++ b/ext/Descriptions/robbins.md @@ -1,4 +1,8 @@ -The **Robbins benchmark problem** is a classical optimal control problem introduced by Robbins (1980), involving a **third-order state constraint**: +The **Robbins benchmark problem** is a classical optimal control problem introduced by Robbins (1980), involving a **third-order state constraint**. + +### Mathematical formulation + +The state $x_1$ is driven through its third derivative and must stay nonnegative: ```math x_1^{(3)}(t) = u(t), \qquad x_1(t) \ge 0, diff --git a/ext/Descriptions/robot.md b/ext/Descriptions/robot.md index 1a3191f49..f3bee986c 100644 --- a/ext/Descriptions/robot.md +++ b/ext/Descriptions/robot.md @@ -49,9 +49,8 @@ The dynamics are nonlinear due to the dependence of the moments of inertia $I_\t ### Characteristics -- Nonlinear, second-order dynamics in spherical coordinates, -- Free final time with state and control constraints, -- Bang–bang control structure in the time-optimal solution, +- Nonlinear, second-order dynamics in spherical coordinates. +- Bang–bang control structure in the time-optimal solution. - Serves as a benchmark for direct transcription and NLP solvers in robotic motion planning. ### References diff --git a/ext/Descriptions/rocket.md b/ext/Descriptions/rocket.md index 0a87d62e5..b5e923411 100644 --- a/ext/Descriptions/rocket.md +++ b/ext/Descriptions/rocket.md @@ -68,9 +68,8 @@ This behaviour illustrates the complexity of the problem and the challenges in n ### Characteristics -- Nonlinear coupled dynamics with drag and gravity, -- Singular arcs in the optimal control, -- State and control constraints, +- Nonlinear coupled dynamics with drag and gravity. +- Singular arcs in the optimal control. - Classical benchmark for testing optimal control algorithms, especially in aerospace applications. ### References diff --git a/ext/Descriptions/space_shuttle.md b/ext/Descriptions/space_shuttle.md index 8837af3dd..2fba4dbc4 100644 --- a/ext/Descriptions/space_shuttle.md +++ b/ext/Descriptions/space_shuttle.md @@ -56,13 +56,10 @@ The final time $T$ is free but bounded. ### Characteristics -- Nonlinear, six–state dynamics with two controls. -- Strongly nonlinear aerodynamic coefficients. -- Free final time with bounded range. -- Path constraints on states and controls. +- Nonlinear dynamics with strongly nonlinear aerodynamic coefficients. - Widely used as a benchmark in optimal control and trajectory optimisation. -### References and relevance +### References - **Betts, J.T. (2010)**. *Practical Methods for Optimal Control and Estimation Using Nonlinear Programming*. SIAM. Provides a comprehensive discussion of trajectory optimisation for aerospace vehicles, including space shuttle reentry problems. It details numerical methods applicable to nonlinear, constrained, free-final-time problems. diff --git a/ext/Descriptions/steering.md b/ext/Descriptions/steering.md index f8903e111..65c28a634 100644 --- a/ext/Descriptions/steering.md +++ b/ext/Descriptions/steering.md @@ -45,10 +45,8 @@ Analytical solutions exist for simplified cases, while numerical methods are req ### Characteristics -- Four-dimensional state with single scalar control, -- Time-optimal objective, -- Control constraints and boundary conditions, -- Bang–bang control structure with possible singular arcs, +- Time-optimal objective. +- Bang–bang control structure with possible singular arcs. - Serves as a benchmark for time-optimal control methods. ### References diff --git a/ext/Descriptions/vanderpol.md b/ext/Descriptions/vanderpol.md index 885a0c96a..078bab392 100644 --- a/ext/Descriptions/vanderpol.md +++ b/ext/Descriptions/vanderpol.md @@ -34,10 +34,8 @@ The problem can be stated as ### Characteristics -- Two-dimensional nonlinear dynamics with cubic damping, -- Quadratic cost on both states and control, -- Fixed final time, -- Unconstrained control (extensions may include bounds), +- Nonlinear dynamics with cubic damping. +- Quadratic cost on both states and control. - Useful benchmark for testing optimal control algorithms and integration schemes. ### References diff --git a/ext/MetaData/mountain_car.jl b/ext/MetaData/mountain_car.jl index 73e074797..251d285f2 100644 --- a/ext/MetaData/mountain_car.jl +++ b/ext/MetaData/mountain_car.jl @@ -19,7 +19,7 @@ mountain_car_meta = OrderedDict( c=3.0, ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid, ModelingToolkit=:valid), - :notes => "On the default grid, the scalarized model solved with MadNLP gives the objective 102.381 instead of 102.398 (JuMP and OptimalControl), a relative gap of 1.6e-4: a convergence gap, reported by the convergence tests (#360); the models are equivalent at the initial guess.", + :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 :init => p -> (state=[p.pos_t0, p.vel_t0], control=0.0, variable=p.tf_start), ) diff --git a/test/suite/core/test_consistency.jl b/test/suite/core/test_consistency.jl index 6840ffe3f..e13070094 100644 --- a/test/suite/core/test_consistency.jl +++ b/test/suite/core/test_consistency.jl @@ -115,8 +115,11 @@ function test_reference_objectives() Test.@test first(entry.solutions) == entry.value Test.@test issorted(entry.solutions) Test.@test entry.agreement == (length(entry.solutions) == 1) - kind(x) = - OCP.solution_kind(problem, x; grid_size=entry.grid_size, scheme=scheme) + function kind(x) + return OCP.solution_kind( + problem, x; grid_size=entry.grid_size, scheme=scheme + ) + end Test.@test kind(entry.value) === :best Test.@test all(s -> kind(s) in (:best, :local), entry.solutions) Test.@test all(s -> kind(s) === :local, entry.solutions[2:end]) @@ -174,7 +177,7 @@ function test_no_handwritten_list() in_docstring = false for (i, line) in enumerate(eachline(file)) # docstrings may show a problem as an example; code may not name one - isodd(count("\"\"\"", line)) && (in_docstring=(!in_docstring); continue) + isodd(count("\"\"\"", line)) && (in_docstring = (!in_docstring); continue) in_docstring && continue m = match(pattern, line) isnothing(m) && continue @@ -196,6 +199,56 @@ function cites_sources(text::AbstractString) return !isnothing(m) && occursin(r"^\s*[-*] \S"m, m[1]) 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`). +""" +const OUTLINE = ( + "Mathematical formulation", + "Parameters", + "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)) + ] + all(in(OUTLINE), headings) || return false + issorted(headings; by=h -> findfirst(==(h), OUTLINE)) || return false + allunique(headings) || return false + return all(in(headings), REQUIRED_HEADINGS) +end + +"""Every description has the same outline.""" +function test_outline() + Test.@testset "outline" verbose = VERBOSE begin + for problem in OCP.problems(; status=:all) + 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" + Test.@test follows_outline(complete) + Test.@test follows_outline( + "### Mathematical formulation\n### Characteristics\n### References\n" + ) + Test.@test !follows_outline("### Characteristics\n### References\n") + Test.@test !follows_outline( + "### Mathematical formulation\n### References\n### Characteristics\n" + ) + Test.@test !follows_outline( + "### Mathematical formulation\n### Characteristics\n### References and relevance\n", + ) + end +end + """Every description cites its sources (#379).""" function test_sources() Test.@testset "sources" verbose = VERBOSE begin @@ -244,6 +297,7 @@ function test_consistency() test_reference_objectives() test_no_handwritten_list() test_sources() + test_outline() test_reference_solutions() end end