diff --git a/AGENTS.md b/AGENTS.md index 90a2eb196..db8f5cd16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ A collection of optimal control problems, each available in one or more modeling src/ # Module: problem registry and model backends (AbstractModelBackend) ext/ # Weak-dependency extensions, one per modeling: # OptimalControlModels, OptimalControlScalarizedModels, JuMPModels, - # MetaData, Descriptions + # MetaData (the metadata and the description of each problem) test/ # Test suite: one file per modeling plus shared checks (aqua, init, solution) docs/ # Documentation site (Documenter) .ct-conventions/ # ct-conventions, cloned at the pinned tag (git-ignored) diff --git a/docs/problems.jl b/docs/problems.jl index 3c2f0bb66..c16830b97 100644 --- a/docs/problems.jl +++ b/docs/problems.jl @@ -426,7 +426,7 @@ function problem_page(problem::Symbol) refs = references(problem) statuses = OCP.status(problem) description = with_behaviour( - read(joinpath(ROOT, "ext", "Descriptions", "$(problem).md"), String) + read(joinpath(ROOT, "ext", "MetaData", "$(problem).md"), String) ) views = Any[(id="problem", label="Problem", kind="problem")] diff --git a/docs/src/problems-overview.md b/docs/src/problems-overview.md index 61df4ee3f..0ed9410ce 100644 --- a/docs/src/problems-overview.md +++ b/docs/src/problems-overview.md @@ -28,7 +28,7 @@ the latest convergence reports. | :--- | :--- | | Modelings | the files of the problem: a problem exists in a modeling when its file does | | Status | the metadata, `valid` or `draft` per modeling | -| Description | `ext/Descriptions/.md` | +| Description | `ext/MetaData/.md`, next to the metadata | | Parameters, default grid, initial guess | the metadata, `ext/MetaData/.jl` | | Features | computed from the OptimalControl model | | Reference objective | computed from the convergence and robustness crons, per scheme, on the default grid | diff --git a/ext/Descriptions/balanced_field.md b/ext/MetaData/balanced_field.md similarity index 100% rename from ext/Descriptions/balanced_field.md rename to ext/MetaData/balanced_field.md diff --git a/ext/Descriptions/beam.md b/ext/MetaData/beam.md similarity index 100% rename from ext/Descriptions/beam.md rename to ext/MetaData/beam.md diff --git a/ext/Descriptions/bioreactor.md b/ext/MetaData/bioreactor.md similarity index 100% rename from ext/Descriptions/bioreactor.md rename to ext/MetaData/bioreactor.md diff --git a/ext/Descriptions/brachistochrone.md b/ext/MetaData/brachistochrone.md similarity index 100% rename from ext/Descriptions/brachistochrone.md rename to ext/MetaData/brachistochrone.md diff --git a/ext/Descriptions/bryson_denham.md b/ext/MetaData/bryson_denham.md similarity index 100% rename from ext/Descriptions/bryson_denham.md rename to ext/MetaData/bryson_denham.md diff --git a/ext/Descriptions/cart_pendulum.md b/ext/MetaData/cart_pendulum.md similarity index 100% rename from ext/Descriptions/cart_pendulum.md rename to ext/MetaData/cart_pendulum.md diff --git a/ext/Descriptions/chain.md b/ext/MetaData/chain.md similarity index 100% rename from ext/Descriptions/chain.md rename to ext/MetaData/chain.md diff --git a/ext/Descriptions/dielectrophoretic_particle.md b/ext/MetaData/dielectrophoretic_particle.md similarity index 100% rename from ext/Descriptions/dielectrophoretic_particle.md rename to ext/MetaData/dielectrophoretic_particle.md diff --git a/ext/Descriptions/double_oscillator.md b/ext/MetaData/double_oscillator.md similarity index 100% rename from ext/Descriptions/double_oscillator.md rename to ext/MetaData/double_oscillator.md diff --git a/ext/Descriptions/ducted_fan.md b/ext/MetaData/ducted_fan.md similarity index 100% rename from ext/Descriptions/ducted_fan.md rename to ext/MetaData/ducted_fan.md diff --git a/ext/Descriptions/electric_vehicle.md b/ext/MetaData/electric_vehicle.md similarity index 100% rename from ext/Descriptions/electric_vehicle.md rename to ext/MetaData/electric_vehicle.md diff --git a/ext/Descriptions/glider.md b/ext/MetaData/glider.md similarity index 100% rename from ext/Descriptions/glider.md rename to ext/MetaData/glider.md diff --git a/ext/Descriptions/insurance.md b/ext/MetaData/insurance.md similarity index 100% rename from ext/Descriptions/insurance.md rename to ext/MetaData/insurance.md diff --git a/ext/Descriptions/jackson.md b/ext/MetaData/jackson.md similarity index 100% rename from ext/Descriptions/jackson.md rename to ext/MetaData/jackson.md diff --git a/ext/Descriptions/moonlander.md b/ext/MetaData/moonlander.md similarity index 100% rename from ext/Descriptions/moonlander.md rename to ext/MetaData/moonlander.md diff --git a/ext/Descriptions/mountain_car.md b/ext/MetaData/mountain_car.md similarity index 100% rename from ext/Descriptions/mountain_car.md rename to ext/MetaData/mountain_car.md diff --git a/ext/Descriptions/robbins.md b/ext/MetaData/robbins.md similarity index 100% rename from ext/Descriptions/robbins.md rename to ext/MetaData/robbins.md diff --git a/ext/Descriptions/robot.md b/ext/MetaData/robot.md similarity index 100% rename from ext/Descriptions/robot.md rename to ext/MetaData/robot.md diff --git a/ext/Descriptions/rocket.md b/ext/MetaData/rocket.md similarity index 100% rename from ext/Descriptions/rocket.md rename to ext/MetaData/rocket.md diff --git a/ext/Descriptions/space_shuttle.md b/ext/MetaData/space_shuttle.md similarity index 100% rename from ext/Descriptions/space_shuttle.md rename to ext/MetaData/space_shuttle.md diff --git a/ext/Descriptions/steering.md b/ext/MetaData/steering.md similarity index 100% rename from ext/Descriptions/steering.md rename to ext/MetaData/steering.md diff --git a/ext/Descriptions/vanderpol.md b/ext/MetaData/vanderpol.md similarity index 100% rename from ext/Descriptions/vanderpol.md rename to ext/MetaData/vanderpol.md diff --git a/ext/README.md b/ext/README.md index fcccf96d9..41d719c40 100644 --- a/ext/README.md +++ b/ext/README.md @@ -8,8 +8,8 @@ problems: the lists are computed from the files. ```text ext/ ├── MetaData/.jl # metadata of every problem: one file each +├── MetaData/.md # description of every problem, next to its metadata ├── MetaData/references/.toml # reference objectives, generated (tools/references) -├── Descriptions/.md # description of every problem: one file each ├── Models/.jl # the problem in a modeling, one directory per modeling ├── JuMPModels.jl # extension of the JuMP modeling ├── ModelingToolkitModels.jl # extension of the ModelingToolkit modeling @@ -37,7 +37,7 @@ ext/ The schema is `METADATA_SCHEMA` in `src/Metadata/loading.jl`, checked when the package loads. -2. **Description**, `Descriptions/.md`: the problem in words and its mathematical +2. **Description**, `MetaData/.md`, next to the metadata: the problem in words and its mathematical formulation, and a `### References` section with at least one entry (checked). 3. **Models**: one file per modeling, `Models/.jl`. Copy the file of a problem with the same features (kind of cost, free times, constraints) in the same modeling: diff --git a/src/Catalogue/fingerprint.jl b/src/Catalogue/fingerprint.jl index ee60c5bb8..544fa0e21 100644 --- a/src/Catalogue/fingerprint.jl +++ b/src/Catalogue/fingerprint.jl @@ -4,7 +4,7 @@ function _problem_files(problem::Symbol) files = [ joinpath(Modelings.EXT_PATH, "MetaData", "$(problem).jl"), - joinpath(Modelings.EXT_PATH, "Descriptions", "$(problem).md"), + joinpath(Modelings.EXT_PATH, "MetaData", "$(problem).md"), ] for spec in Modelings.MODELING_SPECS Modelings._problem_exists(problem, spec) && diff --git a/test/README.md b/test/README.md index 317a0c46d..ceb1cf8f2 100644 --- a/test/README.md +++ b/test/README.md @@ -228,7 +228,7 @@ modelings change different problems). The rules are read from the repository: | `ext/Models/

.jl`, a problem of a modeling | `M`, `comparison` | `p` | | another file of `ext/Models/` (e.g. `schemes/`) | `M`, `comparison` | all | | `ext/.jl`, an extension | those whose `Project.toml` holds its triggers | all | -| a file of `ext/MetaData/` or `ext/Descriptions/` named after a problem | all | `p` | +| a file of `ext/MetaData/` named after a problem (metadata, description) | all | `p` | | `test/suite//**` | `env` (none for `core` and the opt-in ones) | all | | `test/common/.jl` | those whose tests include it, directly or not; all if `test/runtests.jl` names it | all | | `test/cron/**`, `test/robustness/**`, `tools/**`, `docs/**`, Markdown outside `ext/` | none: `core` only | — | diff --git a/test/suite/core/test_consistency.jl b/test/suite/core/test_consistency.jl index 16867c849..64c737622 100644 --- a/test/suite/core/test_consistency.jl +++ b/test/suite/core/test_consistency.jl @@ -10,8 +10,9 @@ const OCP = OptimalControlProblems const ROOT = pkgdir(OptimalControlProblems) const EXT = joinpath(ROOT, "ext") -# Directories of ext/ that hold one file per problem, and the extension of their files. -const DATA_DIRECTORIES = ("MetaData" => ".jl", "Descriptions" => ".md") +# The hand-written data of a problem, in ext/MetaData/: its metadata and its description, +# one file each, side by side. +const DATA_FILES = (".jl", ".md") function names_in(dir, extension) return sort!([ @@ -24,8 +25,8 @@ function test_files() Test.@testset "files" verbose = VERBOSE begin problems = OCP.problems(; status=:all) # metadata and descriptions: one file each per problem, and nothing else - for (dir, extension) in DATA_DIRECTORIES - Test.@test names_in(joinpath(EXT, dir), extension) == problems + for extension in DATA_FILES + Test.@test names_in(joinpath(EXT, "MetaData"), extension) == problems end # model directories: exactly the directories of the modeling table model_dirs = sort!([ @@ -244,7 +245,7 @@ end function test_outline() Test.@testset "outline" verbose = VERBOSE begin for problem in OCP.problems(; status=:all) - text = read(joinpath(EXT, "Descriptions", "$problem.md"), String) + text = read(joinpath(EXT, "MetaData", "$problem.md"), String) Test.@test follows_outline(text) end complete = "### Mathematical formulation\n### Qualitative behaviour\n### Characteristics\n### References\n" @@ -270,7 +271,7 @@ end function test_sources() Test.@testset "sources" verbose = VERBOSE begin for problem in OCP.problems(; status=:all) - text = read(joinpath(EXT, "Descriptions", "$problem.md"), String) + text = read(joinpath(EXT, "MetaData", "$problem.md"), String) Test.@test cites_sources(text) end Test.@test cites_sources("text\n\n### References\n\n- **A. (2000)**. *Title*.\n") diff --git a/tools/ci/scope.py b/tools/ci/scope.py index 9b333c2f7..3cb86aa81 100755 --- a/tools/ci/scope.py +++ b/tools/ci/scope.py @@ -12,7 +12,7 @@ schemes): the same environments, every problem; - ``ext/.jl``, the entry point of an extension: the environments whose ``Project.toml`` holds every trigger of ``E`` (``[extensions]`` of the package's ``Project.toml``); -- ``ext/MetaData/**`` and ``ext/Descriptions/**``, a file named after a problem: every +- ``ext/MetaData/**``, a file named after a problem (its metadata, its description): every environment, for that problem; - ``test/suite//**``: the environment ``env``; - ``test/common/.jl``: the environments whose tests name ``.jl`` (an ``include``), @@ -152,7 +152,7 @@ def classify(row, repo): needed = set(repo.triggers[stem]) envs = {e for e in repo.environments if needed <= repo.deps[e]} return envs, ALL, f"extension `{stem}`" - if parts[0] == "ext" and len(parts) > 2 and parts[1] in ("MetaData", "Descriptions"): + if parts[0] == "ext" and len(parts) > 2 and parts[1] == "MetaData": if stem in repo.problems: return ALL, {stem}, f"problem `{stem}`" return everything("not the file of a problem") diff --git a/tools/ci/test/test_scope.py b/tools/ci/test/test_scope.py index aaf6f9f8e..5fde1db44 100644 --- a/tools/ci/test/test_scope.py +++ b/tools/ci/test/test_scope.py @@ -116,7 +116,7 @@ def test_extension_entry_point(self): def test_metadata_and_description(self): self.assertEqual("problem=beam", self.scope("ext/MetaData/beam.jl")) - self.assertEqual("problem=robot", self.scope("ext/Descriptions/robot.md")) + self.assertEqual("problem=robot", self.scope("ext/MetaData/robot.md")) self.assertEqual("problem=beam", self.scope("ext/MetaData/references/beam.toml")) def test_metadata_file_not_a_problem(self): @@ -285,11 +285,11 @@ def test_null_labels(self): class TestSummary(unittest.TestCase): def test_narrowed(self): - md = run_summary(changed(["ext/JuMPModels/beam.jl", "ext/Descriptions/robot.md"])) + md = run_summary(changed(["ext/JuMPModels/beam.jl", "ext/MetaData/robot.md"])) self.assertIn("**Problems**: `beam`, `robot`", md) self.assertIn("**Environments**: all", md) self.assertIn("| modified | `ext/JuMPModels/beam.jl` | `JuMP`, `comparison` | `beam` |", md) - self.assertIn("| modified | `ext/Descriptions/robot.md` | all | `robot` |", md) + self.assertIn("| modified | `ext/MetaData/robot.md` | all | `robot` |", md) def test_core_only(self): md = run_summary(changed(["docs/make.jl"]))