diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 24f4fd3..897b91b 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -85,3 +85,53 @@ jobs: if [ -n "$unexpected" ]; then echo "unexpected skips:"; echo "$unexpected"; exit 1 fi + + one-extra: + # The leg above installs the core alone and then everything. These install + # one extra each, so the extras' boundaries are tested in both directions: + # the extra's own modules import without the others, and every test that + # needs another extra skips rather than erroring at collection. + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - {extra: spec, modules: "ymf.schema, ymf.compose, ymf.generated"} + - {extra: units, modules: "ymf.units"} + - {extra: symbolic, modules: "ymf.symbolic, ymf.schema"} + name: linux-64 / py3.12 / ymf[${{ matrix.extra }}] alone + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Build sdist + run: | + python -m pip install --upgrade pip build + python -m build --sdist + + - name: Install ymf[${{ matrix.extra }}] alone + shell: bash + run: | + python -m venv /tmp/one + /tmp/one/bin/pip install "$(ls dist/ymf-*.tar.gz)[${{ matrix.extra }}]" pytest + + - name: Its modules import without the other extras + shell: bash + run: | + cd /tmp + /tmp/one/bin/python -c "import ymf, ${{ matrix.modules }}; print('ymf', ymf.__version__, 'imports ${{ matrix.modules }}')" + + - name: Run test suite + shell: bash + run: | + # The tests that need another extra skip themselves; a collection + # error or a failure here is a test, or a module, that assumes an + # extra it does not declare. + export PATH=/tmp/one/bin:$PATH + python -c "import ymf; print(ymf.__file__)" | grep -v "/src/ymf/" + python -m pytest tests -q -rs -p no:cacheprovider diff --git a/README.md b/README.md index a4f613e..3e47fbc 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ ymf version that wrote it (`ymf:`), and a reader refuses one from a newer ymf. | Piece | State | |---|---| -| Archive data model, YAML I/O, structural checks (`ymf.archive`) | **Implemented.** Tested against real Proteus output; used by Proteus's `ymf_io` branch, aimed at Proteus 2.0 | +| Archive data model, YAML I/O, structural checks (`ymf.archive`) | **Implemented.** Tested against real Proteus output; used by Proteus 2.0 (its `main` line) | | `.ymf` → `.xmf` conversion (`ymf2xmf`, `ymf.xdmf`) | **Implemented.** Lossless round trip; output opens in ParaView. Reads XDMF from other tools too, refusing by name what the model can't hold ([docs/xdmf-model.yaml](docs/xdmf-model.yaml)) | | Self-contained archives: arrays inline, no HDF5 | **Implemented.** `data_item_for(array, inline=True)`; `write_archive.py --inline` | | Problem-spec schema v0.2 (`ymf.schema`) | **Implemented.** See the [known gaps](docs/problem-specification.md#known-gaps) | @@ -87,7 +87,7 @@ A specification, abridged from [examples/kovasznay_flow.ymf](examples/kovasznay_flow.ymf): ```yaml -Problem: +model: name: "Kovasznay flow, Re = 40" physical_model: provenance: llm_derived @@ -132,16 +132,16 @@ Writing an archive, from [examples/write_archive.py](examples/write_archive.py): ```python -from ymf.archive import (new_domain, add_uniform_step, topology, geometry, +from ymf.archive import (new_approximation, add_uniform_step, topology, geometry, attribute, data_item_for, write_ymf) -domain = new_domain("Mesh Spatial_Domain") +domain = new_approximation("Mesh Spatial_Domain") topo = topology("Triangle", len(elements), data_item_for(elements, "heat.h5:/elements")) geom = geometry(data_item_for(nodes, "heat.h5:/nodes")) for k, t in enumerate(times): add_uniform_step(domain, t, topo, geom, [attribute("T", data_item_for(T[k], "heat.h5:/T_t%d" % k))]) -write_ymf(domain, "heat.ymf", extra={"Problem": problem}) +write_ymf(domain, "heat.ymf", extra=problem) # the spec: model, solution_paths, ... ``` `data_item_for` reads shape, type and precision off the array, so the diff --git a/docs/README.md b/docs/README.md index d804224..854bc68 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,40 +1,46 @@ # YMF documentation -Start with the two guides. They describe what exists today. The rest are -design drafts and background research, kept for their reasoning. +Start with the two guides. They describe what exists today. Design notes say +what was decided and whether it is built. History and research are kept for +their reasoning, not as a description of the code. ## Guides (current) | Document | What it covers | |---|---| -| [problem-specification.md](problem-specification.md) | Writing and validating a problem spec: structure, branching, provenance, units, known gaps | +| [problem-specification.md](problem-specification.md) | Writing and validating a problem spec: structure, branching, composition, provenance, units, known gaps | | [archive-format.md](archive-format.md) | Archives: the archive of a spec (outputs keyed by their input, studies, reruns, `extends`), and the archive a solver writes: files on disk, the domain model, parallel output, XDMF conversion, use in Proteus | -| [xdmf-model.yaml](xdmf-model.yaml) | The archive model laid out in the order of XDMF's own [Model and Format](https://xdmf.org/index.php/XDMF_Model_and_Format.html) page: each XDMF element and attribute, the `.ymf` key that holds it, and whether it is supported. For readers who know XDMF. | +| [xdmf-model.yaml](xdmf-model.yaml) | The archive model laid out in the order of XDMF's own [Model and Format](https://xdmf.org/index.php/XDMF_Model_and_Format.html) page: each XDMF element and attribute, the `.ymf` key that holds it, and whether it is supported. For readers who know XDMF. Checked by `tests/test_xdmf_model.py`. | +| [changes.md](changes.md) | Gaps that have been closed, dated, with the commit that closed each. The guides describe the result; this says why it is that way. | -## Design drafts +## Design notes -| Document | Status | +A design note is written before the code, records the decisions taken on it, +and lands in `design/` with the code that implements it. + +| Note | Status | |---|---| -| [ymf-schema.md](ymf-schema.md) | The original v0.1 schema draft. Still the best statement of the design principles and of the intended `vvuq` shape. Its §4 "Archive Configuration" and §5 "XDMF Preservation" were superseded by the implemented [archive format](archive-format.md), and the title expands the old working name. | -| [ymf-schema-v0.2-delta.md](ymf-schema-v0.2-delta.md) | The v0.2 changes on top of v0.1, which `ymf.schema` implements. §7 lists what was deferred to v0.3. | +| [design/time-outside-space.md](design/time-outside-space.md) | **Implemented** 2026-10-26: archive format 2, one list of instants with the spaces inside each. | + +## History + +Superseded drafts, kept for the reasoning behind decisions still in force. +Each starts with a note saying what replaced it. -Both drafts use `strong_form.unknown_provenance`. That key has since been renamed to `strong_form.provenance`, matching every other block, and a structured unknown may now carry its own `provenance`. See [Provenance](problem-specification.md#provenance). +| Document | What it was | +|---|---| +| [history/schema-v0.1.md](history/schema-v0.1.md) | The original v0.1 schema draft. Its § 3 is still the only description of the intended `vvuq` shape. | +| [history/schema-v0.2-delta.md](history/schema-v0.2-delta.md) | The v0.2 changes on top of v0.1, which `ymf.schema` implements. | +| [history/session-2026-07-29.md](history/session-2026-07-29.md) | Notes from the session where YMF was designed, under its earlier name YDMF. | ## Background research -These were drafted with an LLM research agent, and have not all been -checked against their sources. Treat specific numbers and API names in -them as leads to verify, not facts. +Drafted with an LLM research agent, and not all checked against their +sources. Treat specific numbers and API names in them as leads to verify, +not facts. Each says so in its own header. | Document | Covers | Caution | |---|---|---| -| [ymf-units-report.md](ymf-units-report.md) | Unit libraries, dimensional analysis, non-dimensionalization | The basis for `ymf.units`. | -| [data-sources-report.md](data-sources-report.md) | Topography, bathymetry, land cover, roughness and forcing datasets | The basis for `ymf.data_sources`; dataset details not re-verified. | -| [csdms-bmi-report.md](csdms-bmi-report.md) | CSDMS Standard Names and the Basic Model Interface | **Contains known errors.** CSDMS is the *Community Surface Dynamics Modeling System*, not what §1 says. The registry fetched at the time listed 2,653 names, not "~4,000+". The real naming grammar is `object__quantity` (double underscore), not the pattern the report gives. Its "Registry API" section and example variable names were never confirmed against a source. | - -## History - -[session-summary-2026-07-29.md](session-summary-2026-07-29.md) is the notes -from the session where YMF was designed, under its earlier name YDMF. It -records the original intent, including ideas that have not been built (the -`ibvp`/sympy symbolic layer, multi-backend dispatch). +| [research/units.md](research/units.md) | Unit libraries, dimensional analysis, non-dimensionalization | The basis for `ymf.units`. | +| [research/data-sources.md](research/data-sources.md) | Topography, bathymetry, land cover, roughness and forcing datasets | The basis for `ymf.data_sources`; dataset details not re-verified. | +| [research/csdms-bmi.md](research/csdms-bmi.md) | CSDMS Standard Names and the Basic Model Interface | **Contains known errors**, listed in its header. | diff --git a/docs/archive-format.md b/docs/archive-format.md index 4af7884..5cddd67 100644 --- a/docs/archive-format.md +++ b/docs/archive-format.md @@ -4,7 +4,7 @@ A YMF archive is how a simulation records its output: the heavy arrays go in HDF5, and a small YAML document (`.ymf`) says what each array is — which mesh, which time, which field, what shape and type. This half of YMF is implemented, tested against real solver output, and is what Proteus writes -on its `ymf_io` branch. +on its 2.0 line (`main`). The code is `ymf.archive` (data model and YAML I/O), `ymf.xdmf` (conversion to XDMF), and the `ymf2xmf` command. All three depend on `pyyaml` alone. @@ -16,8 +16,10 @@ which parts a `.ymf` archive represents. An archive takes two forms. **The archive of a spec** is the problem specification as realized, followed by every output computed from it; `ymf.closure` reads and writes it, and Proteus's `ymf_run` produces it. -Its outputs each hold an approximation in **the solver's form**, the -`domain` tree a solver writes and the rest of this page describes. +Its outputs each hold an approximation in **the solver's form**: the +time/space/field tree a solver writes, which the rest of this page describes. +The same tree is called `domain` at the top of a solver's own document and +`approximation` inside an output of the archive of a spec. - [The archive of a spec](#the-archive-of-a-spec) - [Files on disk](#files-on-disk) @@ -39,7 +41,7 @@ was realized, then what was computed from it. ```yaml ymf: 0.2.1 # the ymf that wrote it; a newer one is refused on read -Problem: {...} # the spec, composed and as realized: no extends, +model: {...} # the spec, composed and as realized: no extends, solution_paths: {...} # every override listed under composition vvuq: {...} composition: {sources: [...], overrides: [...]} @@ -60,7 +62,7 @@ outputs: solve: {by: {ymf: ..., proteus_git: ..., numpy: ..., platform: ...}, created: ...} storage: poisson_2365d177bb1f.h5 # or: inline verification: {l2_errors: {u: 0.0105...}} - approximation: {times: [...]} # the solver's domain tree + approximation: {times: [...]} # the solver's time/space/field tree reproduced: [{created: ..., by: {...}}] # each rerun that matched, bitwise ``` @@ -164,7 +166,7 @@ ymf_archive_version: 2 # refused on read if it isn't a version this ymf k domain: # the time/space/field tree -- see below times: [...] extra: # optional: anything with no XDMF equivalent - Problem: {...} # typically the problem spec that produced the run + model: {...} # typically the problem spec that produced the run solution_paths: {...} ``` @@ -208,7 +210,7 @@ domain: - time: 10.0 ... extra: - Problem: + model: name: Transient heat conduction, unit square ... ``` @@ -218,6 +220,15 @@ only to keep the listing short.) ## The domain model +The functions that build and check this tree are named for what it is in +the archive of a spec, an *approximation*: `new_approximation`, +`validate_approximation`, `canonicalize_approximation`, +`select_approximation`, `inline_approximation`, `rebase_approximation`, +`approximation_arrays`. The names they had before 2026-11 (`new_domain`, +...) are aliases, kept for one release, so that `domain` can mean the region +a problem is posed on. The solver file's `domain:` key is unchanged: it is +part of `ymf_archive_version: 2`. + A domain is plain dicts and lists — no classes — so it costs nothing to build, gathers across MPI natively, and serializes directly. @@ -273,7 +284,7 @@ of a domain, `space_names(domain)` and `series(domain, name)`; (`transpose_collections`): steps of different spaces are joined on exact time, a repeated time pairs up by occurrence, and a space missing at a time is omitted from that instant. Nothing is rewritten on disk. Code that built -a domain with `new_domain(name)` / `add_collection` / `add_uniform_step(..., +a domain with `new_approximation(name)` / `add_collection` / `add_uniform_step(..., collection=)` keeps working and is upgraded when the domain is validated or written; `{"time_collection": {...}}` (singular) is accepted as before. @@ -289,7 +300,7 @@ is rejected when the archive is written: | `data_type` | `Float Int UInt Char UChar` | | `format` | `HDF XML Binary` | -**Defaults.** `canonicalize_domain()` fills every defaultable field +**Defaults.** `canonicalize_approximation()` fills every defaultable field explicitly, and the file on disk is always canonical. The one default worth knowing is that XDMF's default `Precision` is **4** bytes, which is wrong for `float64`. Use `data_item_for()`, which reads the precision off the @@ -304,10 +315,10 @@ disagree with what's in the file. ```python import h5py, numpy as np -from ymf.archive import (new_domain, add_instant, uniform_grid, topology, geometry, +from ymf.archive import (new_approximation, add_instant, uniform_grid, topology, geometry, attribute, data_item_for, write_ymf) -domain = new_domain() +domain = new_approximation() with h5py.File("heat.h5", "w") as h5: h5["nodes"], h5["elements"] = nodes, elements # mesh written once topo = topology("Triangle", len(elements), data_item_for(elements, "heat.h5:/elements")) @@ -318,7 +329,7 @@ with h5py.File("heat.h5", "w") as h5: attribute("T", data_item_for(T, "heat.h5:/T_t%d" % k)), ])}) -write_ymf(domain, "heat.ymf", extra={"Problem": problem}) +write_ymf(domain, "heat.ymf", extra=problem) # the spec: model, solution_paths, ... ``` [`examples/write_archive.py`](../examples/write_archive.py) is the @@ -398,7 +409,7 @@ YMF splits checking across a trust boundary: - A **solver** trusts the validated input and writes the archive. On that path the checks are only structural and cost O(1) per field. -`write_ymf()` runs `validate_domain()` by default. It checks required keys, +`write_ymf()` runs `validate_approximation()` by default. It checks required keys, the closed sets above, and that no grid has two fields with the same name and centering (viewers key fields by name within point data and within cell data, so a duplicate silently hides the first; the same name cell- @@ -439,7 +450,7 @@ wrote view.xmf `-c/--collection` (a name or part of one), `-f/--field` and `-s/--steps` (Python indices and slices: `-1`, `0:10`, `::5`) cherry-pick what the `.xmf` describes; the `.ymf` is never changed. In code the same selection is -`ymf.archive.select_domain(domain, collections=, fields=, steps=)`. +`ymf.archive.select_approximation(domain, collections=, fields=, steps=)`. ParaView and VisIt open the `.xmf` directly. `extra` is carried into it as a base64-encoded JSON `` element, a @@ -472,8 +483,8 @@ as they are written and the full document once, at close. ## Use in Proteus -Proteus's `ymf_io` branch (aimed at the 2.0 line) replaces its hand-built -XDMF XML with this model: +Proteus's 2.0 line (`main`, since the `ymf_io` branch merged) replaces its +hand-built XDMF XML with this model: - Every field goes through one `write_field` call, which builds its `Attribute` + `DataItem`. Fields beyond the solution itself are declared @@ -497,7 +508,7 @@ domain used to hold one temporal collection per function space, each with its own list of instants, because XDMF does; it now holds one list of instants with the spaces inside each. The reasons, the migration and the Proteus changes are in -[design-time-outside-space.md](design-time-outside-space.md). In short: +[design/time-outside-space.md](design/time-outside-space.md). In short: the Proteus writer already refused a space missing at an instant; an instant is now the unit of an appended record, so a killed run loses a whole instant and never one space of it; and `append_step` no longer names diff --git a/docs/changes.md b/docs/changes.md new file mode 100644 index 0000000..5bcd05e --- /dev/null +++ b/docs/changes.md @@ -0,0 +1,126 @@ +# Closed gaps and the decisions behind them + +The guides describe what YMF does. This page records the gaps that have been +closed, newest first, with the commit that closed each, so that nobody has to +rediscover why a thing is the way it is. Open gaps are in +[problem-specification.md § Known gaps](problem-specification.md#known-gaps). + +## 2026-11 + +- **2026-11-01: one name per thing: `model` and `approximation`.** The spec's + top-level key has been `model` since a66ea1c, and the archive of a spec + stores the realized spec under the key the spec uses, so it has written + `model` since then too. The README, the archive guide and several + docstrings still showed `Problem:`; they now say `model:`. `Problem:` and + `problem:` still read as `model:`. + The functions that build and check the tree a solver writes were named + for a *domain*, which is also the region a problem is posed on + (`model.strong_form.domain`, `ymf.domain`). They are now named for an + *approximation*, which is what the archive of a spec already called that + tree (`outputs[key].approximation`): `new_approximation`, + `validate_approximation`, `canonicalize_approximation`, + `select_approximation`, `rebase_approximation`, `inline_approximation`, + `approximation_arrays`. The old names are the same functions, kept for one + release; a release should warn before they go. The solver file's + `domain:` key and the functions' parameter names are unchanged: the key + is part of `ymf_archive_version: 2`. +- **2026-11-01: eight keys that nothing read are refused.** The schema + accepted them from the v0.1 and v0.2 drafts, and no code in ymf or + Proteus read or wrote them, so a document carrying one said something + nobody heard. A document that still carries one is now told which key: + - `strong_form.strong_form_expression`: superseded by `equations`, which + ymf.symbolic reads. + - `strong_form.known_analytical_solution`: superseded by + `solution_paths.analytical` and `vvuq.verification.reference`. + - `strong_form.dimensional_check`: the unit check is `ymf.units.check`, + run by whoever wants it; a switch in the document turned nothing on. + - `model.unit_systems`: nothing defined what a named system selects; units + are given on each unknown, coefficient and condition. + - `discretizations[].bmi_interface`: no BMI adapter exists. + - top-level `archive` and `xdmf` (and the v0.1 spelling `Xdmf`, which is + no longer folded): the archive is its own format, written by a solver + and by `ymf.closure`, not a block of the spec. + + `mesh_generation` and `roughness_source` stay for now: `ymf.data_sources` + reads them, and whether that module stays is a separate decision. + +## 2026-10 + +- **2026-10-27: a hot start repeating a time replaces.** The two open + questions of [design/time-outside-space.md](design/time-outside-space.md) + § 8 were answered on the Proteus side (cekees/proteus#121): a hot start + replaces the steps after the one it resumes from, and a space first + archived mid-run is covered by a writer-level test. +- **2026-10-26: time outside, space inside (archive format 2).** The domain + used to hold one temporal collection per function space, because XDMF + does; it now holds one list of instants with the spaces inside each. + Format 1 is still read and upgraded in memory. See + [design/time-outside-space.md](design/time-outside-space.md) + (proteustoolkit/ymf#22, #23; `a3eac96`). +- **2026-10-17: a boundary condition's units follow its type** (`54765f8`, + proteustoolkit/ymf#9). They used to be compared with the unknown's units + whatever the type, which is right only for `dirichlet`: a `neumann` flux in + W/m² failed and one in K passed. Each type now has its own rule (see + [Units](problem-specification.md#units-scales-and-dimensionless-numbers)). + What is left is in Known gaps. +- **2026-10-16: `piecewise_linear` domains are solved** (`54a9f8f`). Any + region that is not a box is meshed by `h`, the element size of an + unstructured mesh. Periodic conditions still need a box. +- **2026-10-15: a table is a value form, not a kind of condition** + (`6de07fe`). `hydrograph` used to be a `type`, which tangled the value + with the condition and made a Dirichlet stage hydrograph impossible to + write. `series:` is now orthogonal to `type`, as `value` and `formula` are. +- **2026-10-14: Neumann and Robin conditions run** (`600e38e`, `ad10e70`). + Robin needed a numerical flux written for Proteus + (`NumericalFlux.RobinFactory`), not wiring: the flux depends on the + solution's trace, and a Proteus flux boundary condition is a function of + `(x, t)` alone. That the *dependency set* of a boundary expression is the + thing to get right, rather than the list of condition types, is the point + taken up in the tag-propagation design notes. +- **2026-10-08: the reference graph is checked** (`e467ff1`). A + `from_weak_form` or `branch_ref` that named nothing used to validate. All + four edges are now checked, `branch_ref` became + `reference.analytical`, integer indices into `weak_forms` are gone, and a + single-valued reference may be omitted where the graph does not branch. +- **2026-10-08: numbers are numbers, and expressions are evaluated once** + (`487182b`, `c86adf1`). `coefficients` was untyped, so every scalar arrived + as a string, and a coefficient written as an expression was dropped from + formula scope. Numbers are now typed in the schema, and expressions are + evaluated by the one resolver `adr_problem` uses, so `ymf.units` and the + solver give the same answer for the same coefficient. `sympy` moved into + the `frontend` extra for this. The decision behind it (cekees): **numbers + and expressions are treated uniformly**, because a front-end that + evaluates expressions differently from the solver would report one thing + and run another, and a `markdown | tex -> ymf` path is an intended + direction. +- **2026-10-08: `1e-10` is a number to every reader** (`487182b`). It used + to be a string to PyYAML and a number to strictyaml, so a spec meant + different things read as a file and read inside an archive. The archive + reader resolves YAML 1.2 scientific notation, on a loader subclass so + pyyaml's own loaders are unchanged. +- **2026-10-08: `characteristic_scales` takes any name** (`487182b`). It + was a fixed set of six. The original six keep their aliases (`L`, `U`, + `rho`, `mu`, `T`) in formula scope. +- **2026-10-08: composition may remove** (`8452cd6`). Decided by cekees: + removal is a real modelling move (incompressible solved as compressible, + inviscid as viscous, dropping an unknown or replacing it with an + analytical expression), and it must be logged. `remove:` names paths and + is recorded in `composition.removals`. +- **2026-10-08: an error names the files behind it** (`d187db1`). An error + that no single file holds, such as a required key none of them sets, was + reported against a line of the merged document, which exists nowhere on + disk. The message now names the path and the files that write it. +- **2026-10-08: duplicates are found by value and dimension** (`08773b8`). + They were caught by name only. A scale whose value *and dimension* match a + coefficient's is now reported whatever either is called. Dimension is what + separates a duplicate from a coincidence: in a non-dimensionalized problem + half the quantities are 1.0. What is left is in Known gaps. +- **2026-10-08: SUPG/PSPG with equal-order P1 on Kovasznay flow is + pre-asymptotic, not wrong.** Investigated and closed: measured rates sit + below the a priori values on coarse meshes and climb towards them as the + mesh refines (1.88 for velocity at 512 cells). It is a resolution limit, + not a defect in `NavierStokesASGS_velocity_pressure`. Taylor-Hood on the + same problem reaches its rates sooner, so a side-by-side comparison at one + mesh size misleads. Reaching the asymptotic range needs an iterative + solver (512 cells is already 24 GB with MUMPS) or a lower-Reynolds + companion case. diff --git a/docs/design-time-outside-space.md b/docs/design/time-outside-space.md similarity index 97% rename from docs/design-time-outside-space.md rename to docs/design/time-outside-space.md index 4fc681f..b111491 100644 --- a/docs/design-time-outside-space.md +++ b/docs/design/time-outside-space.md @@ -1,7 +1,8 @@ # Design note: time outside, space inside -**Status: approved by cekees 2026-10-25 (all six recommendations); implemented in the ymf PR that follows this note. See § Implementation notes for what differs from the plan.** -Closes the open question at the end of [archive-format.md](archive-format.md) +**Status: implemented.** Approved by cekees 2026-10-25 (all six recommendations), implemented in proteustoolkit/ymf#22 and #23 (merged 2026-10-26), Proteus side in cekees/proteus#109 and #110. The two open questions in § 8 were answered on the Proteus side by cekees/proteus#121 (2026-10-27): a hot start *replaces* the steps after the one it resumes from, and a space first archived mid-run is covered by a writer-level test. See § Implementation notes for what differs from the plan. + +Closes the open question at the end of [archive-format.md](../archive-format.md) (recorded 2026-10-23). Drafted 2026-10-25. The Proteus writer is a separate PR, after the ymf one (§ 7). diff --git a/docs/ymf-schema.md b/docs/history/schema-v0.1.md similarity index 95% rename from docs/ymf-schema.md rename to docs/history/schema-v0.1.md index 9393492..f036b36 100644 --- a/docs/ymf-schema.md +++ b/docs/history/schema-v0.1.md @@ -1,6 +1,25 @@ # YMF — Yet Another Data Model for Physics # Draft Schema (v0.1) +> **Superseded draft, kept for its reasoning.** The schema as it is today is described in +> [problem-specification.md](../problem-specification.md) and implemented by `ymf.schema`. +> What replaced each part of this draft: +> +> - The title expands the old working name. The format is the YAML Modeling Format. +> - The top-level key `Problem:` is now `model:` (keys are `lower_case_with_underscores`). +> - The integer index of "two-tier referencing" is gone: a discretization names its weak +> form by label, because indices renumber when composition removes an entry. +> - `branch_ref` is now `vvuq.verification.reference.analytical`, one of four checked +> reference edges. +> - `unknown_provenance` is now `provenance`. +> - § 4 "Archive Configuration" and § 5 "XDMF Preservation" are superseded by +> [archive-format.md](../archive-format.md). The principle that every XDMF document is a +> valid YMF document under `Xdmf` was dropped: the archive is its own model, and +> [xdmf-model.yaml](../xdmf-model.yaml) says which parts of XDMF it holds. +> +> § 3 "VVUQ Results" is still the only description of the intended shape of `vvuq`. + + A structured, human- and LLM-editable format for describing physical models, numerical discretizations, and VVUQ results, with support for branching across formulations, solution paths, and solver backends. diff --git a/docs/ymf-schema-v0.2-delta.md b/docs/history/schema-v0.2-delta.md similarity index 97% rename from docs/ymf-schema-v0.2-delta.md rename to docs/history/schema-v0.2-delta.md index b30534c..239648b 100644 --- a/docs/ymf-schema-v0.2-delta.md +++ b/docs/history/schema-v0.2-delta.md @@ -1,5 +1,12 @@ # YMF Schema v0.2 — Consolidation Delta +> **Superseded draft, kept as a changelog.** `ymf.schema` implements the validators below and +> [problem-specification.md](../problem-specification.md) describes the result. +> `unknown_provenance` below has since been renamed `provenance`. Of § 7's items deferred to +> v0.3, the ones since done say so inline. The four documents it was synthesized from are now +> under [research/](../research/) and [history/](./). + + **Date**: 2026-08-12 **Status**: Draft — proposed additive/breaking changes to `ymf-schema.md` (v0.1), synthesized from four background reports: diff --git a/docs/session-summary-2026-07-29.md b/docs/history/session-2026-07-29.md similarity index 93% rename from docs/session-summary-2026-07-29.md rename to docs/history/session-2026-07-29.md index 73cf925..08b25da 100644 --- a/docs/session-summary-2026-07-29.md +++ b/docs/history/session-2026-07-29.md @@ -1,5 +1,13 @@ # YMF Session Summary — 2026-07-29 +> **History.** Notes from the session where YMF was designed, under its earlier name YDMF. +> Nothing here describes current behaviour; for that, see +> [problem-specification.md](../problem-specification.md). Some of its ideas were built +> differently (the symbolic layer is `ymf.symbolic`, on sympy, not ibvp; the top-level key +> is `model:`, not `Problem:`) and some not yet (multi-backend dispatch has one backend, +> Proteus). + + **Copy-paste this into a new session** to restore context and continue the work. --- diff --git a/docs/problem-specification.md b/docs/problem-specification.md index f290886..231f1f0 100644 --- a/docs/problem-specification.md +++ b/docs/problem-specification.md @@ -5,8 +5,9 @@ from its physics down to a solver configuration, so that a person, an LLM and a solver can all work from the same record. This guide covers the current schema (v0.2) as `ymf.schema` implements it, using the documents in [`examples/`](../examples/) to illustrate. For the design history and -rationale, see [ymf-schema.md](ymf-schema.md) (v0.1) and -[ymf-schema-v0.2-delta.md](ymf-schema-v0.2-delta.md). +rationale, see [history/schema-v0.1.md](history/schema-v0.1.md) and +[history/schema-v0.2-delta.md](history/schema-v0.2-delta.md); for the gaps +that have been closed and why, [changes.md](changes.md). - [The idea](#the-idea) - [Document structure](#document-structure) @@ -52,7 +53,6 @@ model: # required characteristic_scales: ... # optional: for non-dimensionalization dimensionless_numbers: ... # optional: formulas over the scales units: ... # optional: {convention: SI|CGS|US|dimensionless} - unit_systems: ... # optional mesh_generation: ... # optional: where a mesh comes from (DEM, filters) solution_paths: # required @@ -60,8 +60,6 @@ solution_paths: # required discretizations: [...] # stages 4-5, possibly empty vvuq: ... # optional, free-form: verification/validation plans and results -archive: ... # optional, free-form: reserved for output configuration -Xdmf: ... # optional, free-form: legacy, from the v0.1 draft extends: model.ymf # optional: the document this one builds on ymf_state: abstract # optional: abstract | well-posed | discretized | closed @@ -84,11 +82,10 @@ equations themselves, in the [notation](#writing-it-once-the-notation). Unknowns are either bare names (`[u, p]`) or structured entries with `units`, an optional `std_name`, `provenance`, and `rank` (1 for a vector). `ymf.normalize_unknowns()` turns either form into the structured one. -Optional: `initial_conditions`, `boundary_conditions`, `coefficients`, -`dimensional_check`. (`strong_form_expression` and -`known_analytical_solution` are accepted from older documents; they -duplicate `equations` and the analytical solution path, so new documents -leave them out.) +Optional: `initial_conditions`, `boundary_conditions`, `coefficients`. +(`strong_form_expression`, `known_analytical_solution` and +`dimensional_check` used to be accepted and are refused now; see +[changes.md](changes.md).) ```yaml initial_conditions: @@ -104,6 +101,30 @@ boundary_conditions: units: K ``` +**Boundary conditions** of all four types run. A `neumann` condition gives +the **outward** diffusive flux `q·n` with `q = -a∇u`, which is the sign +Proteus's `diffusiveFluxBoundaryConditions` wants; where no condition claims +a face, the natural condition applies, which for a diffusion term is zero +flux. A Neumann-only problem is detected as determined up to a constant, +like any other with no Dirichlet condition. A `robin` condition is +`αu + β q·n = g`, with `alpha` and `beta` beside the condition and `g` given +as `value` or `formula` like any other right-hand side. All three are +expressions, so they may vary along the boundary. It is one relation, so a +vector unknown wants one condition per component. `beta: 0` is refused: +that is a Dirichlet condition, and belongs where it can be imposed strongly. +`periodic` conditions need a box (see [The domain](#the-domain)). + +A value is given as a number (`value`), an expression (`formula`), or a +table, `series: [[t, value], ...]` with `t` ascending: a measured or design +record, which is the one thing an expression cannot be. A series is linear +between samples; outside its range the first and last values are held, +because extrapolating a record past its end is not something to do quietly. +It is a **value form**, not a kind of condition, orthogonal to `type` +exactly as `value` and `formula` are. Under `neumann` it is a discharge +hydrograph; under `dirichlet` a stage hydrograph, a gauge reading against +time, or a measured inlet temperature. A series is one number per time, so +it is refused on a vector unknown: give one condition per component. + **`weak_forms`**: each has a `label`, `provenance`, a `derivation`, the trial and test `solution_spaces`, and the `bilinear` and `linear` forms. Optional notes record inf-sup stability, existence, uniqueness and @@ -684,7 +705,7 @@ strong_form: `normalize_unknowns(unknowns, provenance=strong_form["provenance"])` fills in each unknown's effective provenance. -Earlier drafts, including [ymf-schema.md](ymf-schema.md), called the +Earlier drafts, including [schema v0.1](history/schema-v0.1.md), called the strong form's key `unknown_provenance`. It was renamed because it read as "the provenance is unknown", and the old key is now rejected. @@ -812,123 +833,36 @@ solver derives the weak form from the strong one (Proteus integrates the flux terms by parts), and the weak form's `stabilization_method` selects what the solver adds. -`vvuq`, `archive` and `Xdmf` are accepted with any content. The intended -shape of `vvuq` is in [ymf-schema.md §3](ymf-schema.md#3-vvuq-results). -`archive` is reserved for output configuration. The archive format itself -is implemented separately; see [archive-format.md](archive-format.md). +`vvuq` takes `verification` and `validation`, each with any content; the +reference graph checks `vvuq.verification.reference`. The intended shape of +the rest is in [schema v0.1 § 3](history/schema-v0.1.md#3-vvuq-results). The +top-level `archive` and `Xdmf` keys of the v0.1 draft are refused now: the +archive is its own format, [archive-format.md](archive-format.md). ## Known gaps These are real limitations of the current schema and code, recorded here so -nobody has to rediscover them: - -- *(Closed.)* Branch references were not resolved: a `from_weak_form` or a - `branch_ref` that named nothing still validated. All four edges of the - reference graph are now checked, `branch_ref` has become - `reference.analytical`, integer indices into `weak_forms` are gone, and a - single-valued reference may be omitted where the graph does not branch. - See [Branching](#branching-one-problem-several-solution-paths). -- *(Closed.)* `coefficients` was untyped, so every scalar arrived as a - string, and a coefficient written as an expression - (`λ: "ρ/(2μ) - sqrt(ρ²/(4μ²) + 4π²)"`, `Q: "π²"`) was dropped from - formula scope, silently taking any number that referred to it. Numbers - are now typed in the schema, and expressions are evaluated by the one - resolver `adr_problem` uses, so `ymf.units` and the solver give the same - answer for the same coefficient. `sympy` moved into the `frontend` extra - for this: a front-end that cannot evaluate an expression would report - different numbers from the solver reading the same file. A bare - `ymf[units]` install still works, and still sees only the coefficients - that are already numbers. -- *(Closed.)* A boundary condition's units were compared with its - unknown's whatever its type, which is right only for `dirichlet`: a - `neumann` flux in W/m² failed and one in K passed. Each type now has its - own rule (see [Units](#units-scales-and-dimensionless-numbers)). What is - left: `neumann` and `robin` see the diffusive flux only, and `t` has no - declared units anywhere, so an `α` or `β` that depends on time is never - decided. -- **Dirichlet, Neumann, Robin and periodic conditions run**, with values - given as a number, a formula or a table, and only on a box. - A `neumann` condition gives the **outward** diffusive flux `q·n` with - `q = -a∇u`, which is the sign Proteus's - `diffusiveFluxBoundaryConditions` wants; where no condition claims a - face, the natural condition applies, which for a diffusion term is zero - flux. A Neumann-only problem is detected as determined up to a constant, - like any other with no Dirichlet condition. -- **A value may be given as a table**, `series: [[t, value], ...]` with `t` - ascending — a measured or design record, which is the one thing an - expression cannot be. Linear between samples; outside the range the first - and last values are held, because extrapolating a record past its end is - not something to do quietly. - - This is a **value form**, not a kind of condition: it is orthogonal to - `type`, exactly as `value` and `formula` are. Under `neumann` it is a - discharge hydrograph; under `dirichlet` a stage hydrograph — a gauge - reading against time — or a measured inlet temperature. `hydrograph` used - to be a `type`, which tangled the two and made the Dirichlet case - impossible to write. A series is one number per time, so it is refused on - a vector unknown: give one condition per component. -- **`robin` runs too**, `αu + β q·n = g`, with `alpha` and `beta` beside - the condition and `g` given as `value` or `formula` like any other - right-hand side. All three are expressions, so they may vary along the - boundary. It is one relation, so a vector unknown wants one condition per - component. `beta: 0` is refused — that is a Dirichlet condition, and - belongs where it can be imposed strongly. - - This needed a numerical flux written for Proteus - (`NumericalFlux.RobinFactory`), not wiring: the flux depends on the - solution's trace, and a Proteus flux boundary condition is a function of - `(x, t)` alone. That the *dependency set* of a boundary expression is the - thing to get right, rather than the list of condition types, is the point - taken up in `YMF_TAG_PROPAGATION.md`. +nobody has to rediscover them. Gaps that have been closed, and how, are in +[changes.md](changes.md). + - **Only `box` and `piecewise_linear` domains are solved.** A domain of any - kind validates and is carried — see [The domain](#the-domain) — but + kind validates and is carried (see [The domain](#the-domain)), but `adr_problem` refuses `discrete` and `file`, saying which kind it was given rather than failing obscurely. -- **The notation's limits**, each of which now reports the fix as well as - the fault. Functions need parentheses — `sin πx` says to write `sin(x)`, - not `sin x`. There are no subscripts — `p₀` says to write `p0` and declare - it, since the superscripts `² ³ ⁴` *are* notation (powers) and a subscript - is a reasonable guess. And a multi-letter name must be declared to be a - name rather than a product — `Re` says to declare it, and that it is not - read as `R·e` because `R` and `e` are not names. -- **SUPG/PSPG with equal-order P1 on Kovasznay flow is pre-asymptotic at - reachable mesh sizes**, not wrong. Measured rates sit below the a priori - values on coarse meshes and climb towards them as the mesh refines (1.88 - for velocity at 512 cells). This was investigated and closed: it is a - resolution limit, not a defect in `NavierStokesASGS_velocity_pressure`. - Taylor-Hood on the same problem reaches its rates sooner, so a - side-by-side comparison at one mesh size misleads. Reaching the - asymptotic range needs an iterative solver (512 cells is already 24 GB - with MUMPS) or a lower-Reynolds companion case. -- *(Closed.)* `1e-10` used to be a string to PyYAML and a number to - strictyaml, so a spec meant different things read as a file and read - inside an archive. The archive reader now resolves YAML 1.2 scientific - notation, so `1e-10`, `1E-10`, `1e+10`, `-1e-10` and `1.5e3` are all - numbers to both. The resolver is registered on a subclass, so pyyaml's own - loaders are unchanged for anything else in the process. -- *(Closed.)* Composition could add and change but not remove, so dropping - an assumption or a field a model stated took a whole new model file. - `remove:` now does it, recorded in `composition.removals`. See - [Composing documents](#composing-documents-models-and-problems). -- *(Closed.)* An error that no single file holds -- a required key none of - them sets -- was reported against a line of the merged document, which - exists nowhere on disk. The message now also names the path and the files - that write it: *no file in the chain sets `equation_formulation` under - `model.strong_form`; `model.strong_form` is written by - `model.ymf`, `model.ymf`*. Where one file added an incomplete entry, - only that file is named. The path is the same shape `remove:` and the - override log use, so it can be pasted between them. -- *(Mostly closed.)* Duplicated values were caught by name only, so a - coefficient called `nu` or `eta`, or any scale outside the conventional - six, was invisible. A scale whose value *and dimension* match a - coefficient's is now reported whatever either is called. Dimension is what - separates a duplicate from a coincidence: in a non-dimensionalized problem - half the quantities are 1.0, and 1.0 kg/m3 beside 1.0 m is not one value - written twice. Where either side states no units, nothing is said, because - there is no way to tell. Still unchecked: a velocity scale that restates a - boundary speed, which would need the boundary condition's expression - evaluated. Derive scales from coefficients wherever possible. -- *(Closed.)* `characteristic_scales` was a fixed set of six, with no slot - for a diffusivity or a pressure scale. It now takes any name. The - original six keep their aliases (`L`, `U`, `rho`, `mu`, `T`) in formula - scope; any other name resolves under itself. +- **Periodic conditions only on a box.** A periodic region must name two + opposite faces of the box; on a `piecewise_linear` domain the condition is + refused. +- **The units of a flux condition are partly checked.** `neumann` and + `robin` see the diffusive flux only, and `t` has no declared units + anywhere, so an `α` or `β` that depends on time is never decided. +- **A duplicated value is found only between a scale and a coefficient.** A + velocity scale that restates a boundary speed is not caught, because that + would need the boundary condition's expression evaluated. Derive scales + from coefficients wherever possible. +- **The notation's limits**, each of which reports the fix as well as the + fault. Functions need parentheses: `sin πx` says to write `sin(x)`, not + `sin x`. There are no subscripts: `p₀` says to write `p0` and declare it, + since the superscripts `² ³ ⁴` *are* notation (powers) and a subscript is + a reasonable guess. And a multi-letter name must be declared to be a name + rather than a product: `Re` says to declare it, and that it is not read as + `R·e` because `R` and `e` are not names. diff --git a/docs/csdms-bmi-report.md b/docs/research/csdms-bmi.md similarity index 96% rename from docs/csdms-bmi-report.md rename to docs/research/csdms-bmi.md index ad05144..b622a39 100644 --- a/docs/csdms-bmi-report.md +++ b/docs/research/csdms-bmi.md @@ -1,5 +1,17 @@ # CSDMS Standard Names and BMI Integration for YMF +> **Background research.** Drafted with an LLM research agent and not all checked against its sources. Treat specific numbers and API names as leads to verify, not facts. +> +> **This report contains known errors.** +> +> - CSDMS is the *Community Surface Dynamics Modeling System*, not what § 1 says. +> - The registry fetched at the time listed 2,653 names, not "~4,000+". +> - The real naming grammar is `object__quantity` (double underscore), not the pattern given here. +> - Its "Registry API" section and example variable names were never confirmed against a source. +> +> Nothing in `src/` reads it. The `bmi_interface` schema key it proposed has no consumer. + + A report on integrating CSDMS Standard Names and the Basic Model Interface (BMI) into the YAML Modeling Format (YMF) for computational physics. --- diff --git a/docs/data-sources-report.md b/docs/research/data-sources.md similarity index 98% rename from docs/data-sources-report.md rename to docs/research/data-sources.md index c2fbabc..4217078 100644 --- a/docs/data-sources-report.md +++ b/docs/research/data-sources.md @@ -1,5 +1,8 @@ # Geospatial and Environmental Data Sources for Physical Modeling +> **Background research.** Drafted with an LLM research agent and not all checked against its sources. Treat specific numbers and API names as leads to verify, not facts. +> It is the basis for `ymf.data_sources`; the dataset details were not re-verified. + A report on available data sources for topography, bathymetry, vegetation, roughness, and remote sensing — both free and commercial — relevant to physical modeling workflows. --- diff --git a/docs/ymf-units-report.md b/docs/research/units.md similarity index 99% rename from docs/ymf-units-report.md rename to docs/research/units.md index 7135e7d..cd10b4f 100644 --- a/docs/ymf-units-report.md +++ b/docs/research/units.md @@ -1,5 +1,8 @@ # Physical Units Support for YMF +> **Background research.** Drafted with an LLM research agent and not all checked against its sources. Treat specific numbers and API names as leads to verify, not facts. +> It is the basis for `ymf.units`. + A report on adding physical unit support to YMF in a non-intrusive way that enables dimensional consistency checks and non-dimensionalization. --- diff --git a/examples/heat_equation.ymf b/examples/heat_equation.ymf index 247f724..1712360 100644 --- a/examples/heat_equation.ymf +++ b/examples/heat_equation.ymf @@ -54,9 +54,6 @@ model: units: K coefficients: κ: {value: 1.0e-3, units: m2/s} - dimensional_check: - enabled: true - method: automatic weak_forms: - label: "galerkin" diff --git a/examples/poisson_v02_enriched.ymf b/examples/poisson_v02_enriched.ymf index 1bb1570..3fce513 100644 --- a/examples/poisson_v02_enriched.ymf +++ b/examples/poisson_v02_enriched.ymf @@ -1,7 +1,7 @@ # ============================================================ # YMF Example: Poisson (heat conduction), v0.2 enriched # Demonstrates: structured unknowns with units/std_name, -# characteristic_scales, dimensional_check, boundary_conditions. +# characteristic_scales, boundary_conditions. # ============================================================ model: @@ -41,11 +41,6 @@ model: coefficients: k: "1.0" Q: "π²" - dimensional_check: - enabled: true - method: automatic - tolerance: 1e-10 - weak_forms: - label: "global" provenance: llm_derived @@ -72,4 +67,3 @@ solution_paths: type: linear linear_solver: petsc tolerance: 1e-12 - bmi_interface: true diff --git a/examples/read_archive.py b/examples/read_archive.py index a85473e..3b0f33b 100644 --- a/examples/read_archive.py +++ b/examples/read_archive.py @@ -33,7 +33,7 @@ import numpy as np -from ymf.archive import canonicalize_domain, read_ymf, series, space_names +from ymf.archive import canonicalize_approximation, read_ymf, series, space_names from ymf.xdmf import read_xdmf @@ -105,7 +105,7 @@ def main(argv=None) -> int: xmf_path = args.archive.with_suffix(".xmf") if xmf_path.exists(): xmf_domain, xmf_extra = read_xdmf(xmf_path) - same = (canonicalize_domain(xmf_domain) == canonicalize_domain(domain) + same = (canonicalize_approximation(xmf_domain) == canonicalize_approximation(domain) and xmf_extra == extra) print("\n%s holds the same domain and problem: %s" % (xmf_path.name, same)) if not same: diff --git a/examples/write_archive.py b/examples/write_archive.py index 26deb4f..7fada1d 100644 --- a/examples/write_archive.py +++ b/examples/write_archive.py @@ -48,7 +48,7 @@ data_item_for, geometry, grid, - new_domain, + new_approximation, topology, write_ymf, ) @@ -136,7 +136,7 @@ def open_store(outdir, stem, inline): def write_serial(outdir, nodes, elements, times, problem, inline=False): """One grid per time step. Returns the path of the .ymf written.""" store = open_store(outdir, "heat", inline) - domain = new_domain() + domain = new_approximation() # The mesh does not move, so it is stored once and every step refers # to the same arrays. topo = topology("Triangle", len(elements), store.item("elements", elements)) @@ -184,7 +184,7 @@ def write_split(outdir, nodes, elements, times, problem, inline=False): """Each step is a SpatialCollection of per-subdomain grids.""" store = open_store(outdir, "heat_split", inline) parts = split_mesh(nodes, elements) - domain = new_domain() + domain = new_approximation() meshes = [ (topology("Triangle", len(local_elements), store.item("elements_p%d" % rank, local_elements)), diff --git a/src/ymf/__init__.py b/src/ymf/__init__.py index a1c4791..7850b22 100644 --- a/src/ymf/__init__.py +++ b/src/ymf/__init__.py @@ -23,6 +23,7 @@ add_spatial_step, add_uniform_step, attribute, + canonicalize_approximation, canonicalize_domain, check_dimensions, data_item, @@ -31,10 +32,12 @@ geometry, grid, load_grid, + new_approximation, new_domain, read_ymf, require_libyaml, topology, + validate_approximation, validate_domain, write_ymf, ) @@ -71,7 +74,7 @@ # --- core: archive model and YAML I/O --- "ARCHIVE_FORMAT_VERSION", "YmfArchiveError", - "new_domain", + "new_approximation", "add_uniform_step", "add_spatial_step", "grid", @@ -80,14 +83,18 @@ "attribute", "data_item", "data_item_for", - "canonicalize_domain", - "validate_domain", + "canonicalize_approximation", + "validate_approximation", "check_dimensions", "write_ymf", "read_ymf", "dump_grid", "load_grid", "require_libyaml", + # the names before 2026-11, kept for one release + "new_domain", + "canonicalize_domain", + "validate_domain", # --- core: XDMF conversion --- "build_xdmf_tree", "write_xdmf", diff --git a/src/ymf/archive.py b/src/ymf/archive.py index 12c0eea..ffe9026 100644 --- a/src/ymf/archive.py +++ b/src/ymf/archive.py @@ -1,4 +1,4 @@ -"""The YMF archive core: the domain data model, plus YAML read/write. +"""The YMF archive core: the approximation data model, plus YAML read/write. This is the module simulation codes depend on. Its **only** third-party dependency is ``pyyaml`` -- deliberately, so that a solver like Proteus can @@ -48,6 +48,19 @@ worth knowing about, so :func:`require_libyaml` is provided for callers on a hot path to assert on it rather than silently degrade. +The approximation tree +---------------------- +The tree a solver writes is an *approximation*: the name the archive of a +spec gives it (``outputs[key].approximation``), and the name of the +functions that build and check it (:func:`new_approximation`, +:func:`validate_approximation`, ...). ``domain`` is left meaning the region +a problem is posed on, ``model.strong_form.domain`` (see ``ymf.domain``). +The older names (``new_domain``, ``validate_domain``, ...) are aliases of +the new ones, kept for one release. A solver's own ``.ymf`` file still +stores the tree under its ``domain:`` key; that is the file format, and it +changes only with ``ymf_archive_version``. Below, and in parameter names, +"domain" still means this tree. + The domain model ---------------- A *domain* is a plain dict -- no classes, no schema objects, so it costs @@ -65,8 +78,8 @@ Format 1 nested the other way, ``{"time_collections": [{"name": str, "data": [step, ...]}, ...]}``; it is still accepted everywhere and -:func:`canonicalize_domain` upgrades it. See -docs/design-time-outside-space.md. +:func:`canonicalize_approximation` upgrades it. See +docs/design/time-outside-space.md. A space at an instant takes exactly one of two forms: @@ -98,9 +111,9 @@ Build these with the constructor helpers below (:func:`data_item`, :func:`attribute`, :func:`topology`, :func:`geometry`, :func:`grid`, -:func:`new_domain`, :func:`add_uniform_step`, :func:`add_spatial_step`) +:func:`new_approximation`, :func:`add_uniform_step`, :func:`add_spatial_step`) rather than by hand -- they apply defaults consistently, which is what -makes :func:`canonicalize_domain` able to state a complete list of +makes :func:`canonicalize_approximation` able to state a complete list of defaultable fields instead of guessing. ``ymf.xdmf`` converts a domain built here into an ``.xmf`` file that @@ -144,7 +157,7 @@ "topology", "geometry", "grid", - "new_domain", + "new_approximation", "add_instant", "uniform_grid", "spatial_grid", @@ -155,9 +168,9 @@ "add_collection", "add_uniform_step", "add_spatial_step", - "canonicalize_domain", + "canonicalize_approximation", "fold_archive_keys", - "validate_domain", + "validate_approximation", "check_dimensions", "write_ymf", "is_archive_text", @@ -166,22 +179,30 @@ "check_version", "package_version", "load_array", - "inline_domain", - "domain_arrays", - "rebase_domain", - "select_domain", + "inline_approximation", + "approximation_arrays", + "rebase_approximation", + "select_approximation", "step_indices", "read_ymf", "dump_grid", "load_grid", "ARCHIVE_FORMAT_VERSION", + # the names before 2026-11, kept for one release (see the module docstring) + "new_domain", + "validate_domain", + "canonicalize_domain", + "select_domain", + "rebase_domain", + "inline_domain", + "domain_arrays", ] class YmfArchiveError(ValueError): """A YMF archive document is structurally invalid. - Raised by :func:`validate_domain` and :func:`check_dimensions`. The + Raised by :func:`validate_approximation` and :func:`check_dimensions`. The message always names the offending path within the document (e.g. ``TimeCollections[0].Data[3].Attributes[1].Center``) so a failure points at the field that caused it rather than at the serializer. @@ -198,7 +219,7 @@ class YmfArchiveError(ValueError): #: space (``time_collections``, one per space); format 2 nests space inside #: time (``times``, each instant holding its ``spaces``). A format 1 #: document is upgraded in memory on read and never written; see -#: docs/design-time-outside-space.md. +#: docs/design/time-outside-space.md. _READABLE_FORMAT_VERSIONS = (1, 2) #: Separators framing an appended step. The end marker is YAML's explicit @@ -294,7 +315,7 @@ def require_libyaml() -> None: # constructors # # These exist so that defaults are applied in exactly one place. That is -# what lets canonicalize_domain() enumerate every defaultable field rather +# what lets canonicalize_approximation() enumerate every defaultable field rather # than covering only the ones that happened to surface in a test. # --------------------------------------------------------------------------- @@ -544,13 +565,13 @@ def grid( return g -def new_domain(name: Optional[str] = None) -> Dict[str, Any]: +def new_approximation(name: Optional[str] = None) -> Dict[str, Any]: """Create an empty domain. The domain is ``{"times": []}``: add instants with :func:`add_instant`. ``name`` is the format 1 spelling, which started a domain with one named time collection; given, it still does, and :func:`add_uniform_step` and - friends then keep building format 1 (which :func:`canonicalize_domain` + friends then keep building format 1 (which :func:`canonicalize_approximation` upgrades). New code should not pass it. """ if name is None: @@ -585,7 +606,7 @@ def add_instant( if "time_collections" in domain: raise YmfArchiveError( "domain is in format 1 (time_collections); add_instant needs a " - "format 2 domain, from new_domain() with no name") + "format 2 domain, from new_approximation() with no name") instant = {"time": float(time), "spaces": dict(spaces)} domain.setdefault("times", []).append(instant) return instant @@ -615,7 +636,7 @@ def _resolve_collection(domain: Dict[str, Any], collection: Any) -> Dict[str, An collections = domain.get("time_collections") if not collections: raise YmfArchiveError( - "domain has no time collections; build it with new_domain(name)" + "domain has no time collections; build it with new_approximation(name)" ) if isinstance(collection, int): try: @@ -963,7 +984,7 @@ def fold_archive_keys(obj: Any) -> Any: return obj -def canonicalize_domain(domain: Dict[str, Any]) -> Dict[str, Any]: +def canonicalize_approximation(domain: Dict[str, Any]) -> Dict[str, Any]: """Return ``domain`` in format 2, with every defaultable field filled in. Accepts both shapes and always returns ``{"times": [...]}``: a format 1 @@ -1112,7 +1133,7 @@ def _validate_grid_like(g: Dict[str, Any], where: str) -> None: _validate_data_item(attr["data_item"], f"{at}.data_item") -def validate_domain(domain: Dict[str, Any]) -> Dict[str, Any]: +def validate_approximation(domain: Dict[str, Any]) -> Dict[str, Any]: """Check ``domain`` is structurally sound; return it canonicalized. This is the solver-side half of the trust boundary: it verifies @@ -1124,7 +1145,7 @@ def validate_domain(domain: Dict[str, Any]) -> Dict[str, Any]: Raises :class:`YmfArchiveError` naming the offending path. """ - canonical = canonicalize_domain(domain) + canonical = canonicalize_approximation(domain) for i, instant in enumerate(canonical.get("times", [])): for name, space in instant["spaces"].items(): where = f"times[{i}].spaces[{name}]" @@ -1266,15 +1287,15 @@ def write_ymf( The domain dict. Canonicalized on the way out, so the file always has every defaultable field explicit. extra: - Optional non-archive YMF content (``Problem``, ``solution_paths``, + Optional non-archive YMF content (``model``, ``solution_paths``, ``vvuq``, ...) to carry alongside. Unlike the XDMF path, which has to base64 it into an ```` element, YAML holds it directly and readably. validate: - Run :func:`validate_domain` first. Leave this on unless you are + Run :func:`validate_approximation` first. Leave this on unless you are deliberately writing a document you know to be partial. """ - checked = validate_domain(domain) if validate else canonicalize_domain(domain) + checked = validate_approximation(domain) if validate else canonicalize_approximation(domain) document: Dict[str, Any] = {"ymf_archive_version": ARCHIVE_FORMAT_VERSION, "domain": checked} if extra is not None: document["extra"] = extra @@ -1400,7 +1421,7 @@ def read_ymf(path: str | Path) -> Tuple[Dict[str, Any], Optional[Any]]: def _upgrade_domain(domain: Any) -> Dict[str, Any]: """A domain in format 2 shape, without canonicalizing it. - Cheaper than :func:`canonicalize_domain`, which :func:`read_ymf` leaves + Cheaper than :func:`canonicalize_approximation`, which :func:`read_ymf` leaves to the caller as it always has: this only moves format 1's steps into instants. """ @@ -1527,7 +1548,7 @@ def step_indices(spec: Any, n: int) -> List[int]: return chosen -def select_domain( +def select_approximation( domain: Dict[str, Any], *, collections: Optional[Sequence[str]] = None, @@ -1550,7 +1571,7 @@ def select_domain( """ import copy - domain = canonicalize_domain(domain) + domain = canonicalize_approximation(domain) names = space_names(domain) chosen_names = names if collections is not None: @@ -1606,24 +1627,24 @@ def grids_of(space: Dict[str, Any]): return dict(domain, times=new_times) -def inline_domain(domain: Dict[str, Any], base_dir: str | Path = ".") -> Dict[str, Any]: +def inline_approximation(domain: Dict[str, Any], base_dir: str | Path = ".") -> Dict[str, Any]: """A copy of ``domain`` with every referenced array copied in as ``Values``. The result needs no HDF5 file or sidecar: the ``.ymf`` (and the ``.xmf`` derived from it) is self-contained. """ import copy - out = copy.deepcopy(canonicalize_domain(domain)) + out = copy.deepcopy(canonicalize_approximation(domain)) for _, owner in _data_items(out): item = owner["data_item"] if "values" in item: continue array = load_array(item, base_dir) owner["data_item"] = data_item_for(array, inline=True, dimensions=item["dimensions"]) - return validate_domain(out) + return validate_approximation(out) -def rebase_domain(domain: Dict[str, Any], from_dir: str | Path, +def rebase_approximation(domain: Dict[str, Any], from_dir: str | Path, to_dir: str | Path) -> Dict[str, Any]: """A copy of ``domain`` whose HDF5 references resolve from ``to_dir``. @@ -1633,7 +1654,7 @@ def rebase_domain(domain: Dict[str, Any], from_dir: str | Path, """ import copy import os - out = copy.deepcopy(canonicalize_domain(domain)) + out = copy.deepcopy(canonicalize_approximation(domain)) if Path(from_dir).resolve() == Path(to_dir).resolve(): return out for _, owner in _data_items(out): @@ -1646,10 +1667,10 @@ def rebase_domain(domain: Dict[str, Any], from_dir: str | Path, return out -def domain_arrays(domain: Dict[str, Any], base_dir: str | Path = "."): +def approximation_arrays(domain: Dict[str, Any], base_dir: str | Path = "."): """{path: array} for every DataItem, however each is stored.""" return {where: load_array(owner["data_item"], base_dir) - for where, owner in _data_items(canonicalize_domain(domain))} + for where, owner in _data_items(canonicalize_approximation(domain))} # --------------------------------------------------------------------------- @@ -1740,7 +1761,7 @@ def _canonical_output(key: str, output: Dict[str, Any]) -> Dict[str, Any]: output = dict(output) if "approximation" in output: try: - output["approximation"] = validate_domain(output["approximation"]) + output["approximation"] = validate_approximation(output["approximation"]) except YmfArchiveError as exc: raise YmfArchiveError("outputs[%s].approximation: %s" % (key, exc)) from exc return output @@ -1759,3 +1780,17 @@ def dump_grid(g: Dict[str, Any]) -> str: def load_grid(text: str) -> Dict[str, Any]: """Inverse of :func:`dump_grid`.""" return _load(text) + + +# --------------------------------------------------------------------------- +# The names before 2026-11 (docs/changes.md), kept for one release. They are +# the same function objects, so a caller sees no difference, keyword +# arguments included; a release should warn before they go. +# --------------------------------------------------------------------------- +new_domain = new_approximation +validate_domain = validate_approximation +canonicalize_domain = canonicalize_approximation +select_domain = select_approximation +rebase_domain = rebase_approximation +inline_domain = inline_approximation +domain_arrays = approximation_arrays diff --git a/src/ymf/cli.py b/src/ymf/cli.py index f01748f..823f1f9 100644 --- a/src/ymf/cli.py +++ b/src/ymf/cli.py @@ -21,9 +21,9 @@ from pathlib import Path from typing import List, Optional, Sequence -from ymf.archive import (YmfArchiveError, canonicalize_domain, read_ymf, select_domain, +from ymf.archive import (YmfArchiveError, canonicalize_approximation, read_ymf, select_approximation, space_names, time_collections, - validate_domain) + validate_approximation) from ymf.xdmf import write_xdmf __all__ = ["archive2xmf", "describe", "ymf2xmf", "ymf2xmf_main"] @@ -56,12 +56,12 @@ def ymf2xmf( malformed archive is better reported here, with the offending field named, than as a file a viewer silently mis-draws. collections, fields, steps: - Convert only these: see :func:`ymf.archive.select_domain`. The + Convert only these: see :func:`ymf.archive.select_approximation`. The ``.xmf`` then describes a part of the archive, which is what a viewer opening one space, one field or one instant of a long run wants; the ``.ymf`` is untouched. - The archive's ``extra`` payload -- ``Problem``, ``solution_paths``, + The archive's ``extra`` payload -- ``model``, ``solution_paths``, ``vvuq`` and anything else with no XDMF equivalent -- is carried into the ``.xmf`` as the base64 ```` element that :func:`ymf.xdmf.read_xdmf` can recover. Generic XDMF consumers parse @@ -73,9 +73,9 @@ def ymf2xmf( if not domain: raise YmfArchiveError( "%s holds no domain, so there is nothing to convert" % (source,)) - domain = validate_domain(domain) if validate else canonicalize_domain(domain) + domain = validate_approximation(domain) if validate else canonicalize_approximation(domain) if collections is not None or fields is not None or steps is not None: - domain = select_domain(domain, collections=collections, fields=fields, steps=steps) + domain = select_approximation(domain, collections=collections, fields=fields, steps=steps) destination = Path(output) if output is not None else _default_output(source) write_xdmf(domain, destination, ymf_extra=extra) return destination @@ -113,7 +113,7 @@ def archive2xmf( domain = output.get("approximation") if not domain: continue - domain = validate_domain(domain) if validate else canonicalize_domain(domain) + domain = validate_approximation(domain) if validate else canonicalize_approximation(domain) record = {k: v for k, v in output.items() if k != "approximation"} destination = outdir / (file_stem(archive_stem(source), key) + ".xmf") write_xdmf(domain, destination, ymf_extra=dict(spec, output=key, record=record)) @@ -151,7 +151,7 @@ def describe(domain) -> List[str]: Each collection is numbered so the interactive prompt can refer to it. """ lines = [] - for i, collection in enumerate(time_collections(canonicalize_domain(domain)), start=1): + for i, collection in enumerate(time_collections(canonicalize_approximation(domain)), start=1): steps = collection["data"] times = [step["time"] for step in steps] span = ("no steps" if not times @@ -204,7 +204,7 @@ def interactive_selection(domain, ask=None): pass their own. """ ask = ask or input - collections = time_collections(canonicalize_domain(domain)) + collections = time_collections(canonicalize_approximation(domain)) names = [c["name"] for c in collections] print("Collections (blank for all):") chosen_names = _pick("collections> ", names, ask) @@ -272,7 +272,7 @@ def ymf2xmf_main(argv: Optional[Sequence[str]] = None) -> int: collections, fields, steps = args.collection, args.field, args.steps if args.verbose or args.show or args.interactive: domain, _ = read_ymf(source) - domain = canonicalize_domain(domain) + domain = canonicalize_approximation(domain) print("%s" % (source,)) if not args.interactive: times = [i["time"] for i in domain.get("times", [])] diff --git a/src/ymf/closure.py b/src/ymf/closure.py index 995bbff..f4a5aac 100644 --- a/src/ymf/closure.py +++ b/src/ymf/closure.py @@ -5,7 +5,7 @@ *realization*), and is keyed by what produced it:: ymf: 0.3.0 - Problem: ... + model: ... solution_paths: ... outputs: P1/cells=8/3f2a9c01d4e7: diff --git a/src/ymf/compose.py b/src/ymf/compose.py index e6b59cf..288e0fc 100644 --- a/src/ymf/compose.py +++ b/src/ymf/compose.py @@ -43,7 +43,7 @@ composition: sources: [navier_stokes_model.ymf, plane_poiseuille.ymf, ...] overrides: - - path: Problem.characteristic_scales.viscosity.value + - path: model.characteristic_scales.viscosity.value was: 1.0 now: 0.01 set_by: plane_poiseuille_re100.ymf @@ -383,15 +383,15 @@ def _dump(data: Any, **kwargs: Any) -> str: #: Spellings accepted on input and folded to the canonical one as the file is #: read. Keys are lower_case_with_underscores (see "Naming" in -#: docs/problem-specification.md); these two were capitalized before that rule -#: was written down. +#: docs/problem-specification.md). "Problem" was capitalized before that rule +#: was written down, and "problem" is the key's name before it became "model". #: #: Folding happens before anything is merged, deliberately. Composition pairs #: keys by exact match, so a model writing "Problem:" and a variant writing #: "problem:" would not merge -- they would become siblings, and the result #: would be a document with two problems. An alias eases a rename; it is not #: a standing second spelling. -_KEY_ALIASES = {"Problem": "model", "problem": "model", "Xdmf": "xdmf"} +_KEY_ALIASES = {"Problem": "model", "problem": "model"} def _read_text(path: Path) -> str: @@ -399,7 +399,7 @@ def _read_text(path: Path) -> str: text = path.read_text(encoding="utf-8") for old, new in _KEY_ALIASES.items(): # top level only: a nested key is indented, and a path inside a - # string value ("Problem.strong_form...") never starts a line + # string value ("model.strong_form...") never starts a line text = re.sub(r"^%s:" % old, "%s:" % new, text, flags=re.M) return text @@ -442,8 +442,8 @@ def _compose(path: Path, chain: Tuple[Path, ...]): data, outputs = _read(path) if outputs and chain: # an inherited output's files are relative to its own archive - from ymf.archive import rebase_domain - outputs = {k: dict(v, approximation=rebase_domain( + from ymf.archive import rebase_approximation + outputs = {k: dict(v, approximation=rebase_approximation( v["approximation"], path.parent, chain[0].parent)) if v.get("approximation") else v for k, v in outputs.items()} own = {k: v for k, v in data.items() if k not in _FILE_KEYS} diff --git a/src/ymf/data_sources.py b/src/ymf/data_sources.py index e4bfb7f..e6d5ccf 100644 --- a/src/ymf/data_sources.py +++ b/src/ymf/data_sources.py @@ -1,7 +1,7 @@ """Geospatial/environmental data-sourcing helpers for YMF. Implements the "short-term integration" items from -``docs/data-sources-report.md`` §7: +``docs/research/data-sources.md`` §7: - A land-cover -> Manning's n lookup table (Arcement & Schneider 1989 / Chow 1959 reference ranges, report §4.1), driving ``roughness_source`` @@ -179,7 +179,7 @@ class DataSourceInfo: license: str -# Catalog transcribed from data-sources-report.md so source names/URLs used +# Catalog transcribed from research/data-sources.md so source names/URLs used # in YMF ``source``/``source_url`` fields can be validated against a known # registry (report §7: "Add `url` field to reference data sources directly # in the YAML"). Not exhaustive relative to the report — covers every @@ -278,7 +278,7 @@ def validate_source_record(record: Dict[str, Any]) -> List[str]: if known is None: warnings.append( f"source {source!r} is not in the known data source catalog " - "(not an error — just unverified against docs/data-sources-report.md)" + "(not an error — just unverified against docs/research/data-sources.md)" ) return warnings diff --git a/src/ymf/normalize.py b/src/ymf/normalize.py index db9d660..9add8b0 100644 --- a/src/ymf/normalize.py +++ b/src/ymf/normalize.py @@ -1,6 +1,6 @@ """Normalization helpers for YMF's backward-compatible schema evolution. -See ``docs/ymf-schema-v0.2-delta.md`` §2 for the rationale: ``unknowns`` +See ``docs/history/schema-v0.2-delta.md`` §2 for the rationale: ``unknowns`` widened from ``Seq(Str())`` (v0.1) to accept either bare strings or structured maps with ``units``/``std_name``/``provenance`` (v0.2). Downstream code should call :func:`normalize_unknowns` immediately after parsing so it only ever diff --git a/src/ymf/schema.py b/src/ymf/schema.py index 92a126c..5d8e9c4 100644 --- a/src/ymf/schema.py +++ b/src/ymf/schema.py @@ -1,8 +1,8 @@ """strictyaml schema validators for YMF v0.2. This module implements the schema described in -``docs/ymf-schema-v0.2-delta.md``, merged on top of the v0.1 schema in -``docs/ymf-schema.md``. Relative to v0.1, ``unknowns`` widens its +``docs/history/schema-v0.2-delta.md``, merged on top of the v0.1 schema in +``docs/history/schema-v0.1.md``. Relative to v0.1, ``unknowns`` widens its accepted type (bare string OR structured map), and the strong form's ``unknown_provenance`` is replaced by ``provenance``, the key every other block uses; a structured unknown may carry its own ``provenance`` to @@ -27,6 +27,7 @@ Seq, Str, ) +from strictyaml.validators import OrValidator from ymf.discretizations import METHODS from ymf.state import STATES @@ -53,7 +54,6 @@ UnitConventionEnum = Enum(["SI", "CGS", "US", "dimensionless"]) -DimCheckMethodEnum = Enum(["automatic", "manual", "off"]) # --------------------------------------------------------------------------- # v0.1 building blocks (unchanged) @@ -139,7 +139,6 @@ Optional("discretization_details"): Str(), Optional("proteus_modules"): Map({"physics": Str(), "numerics": Str()}), # --- v0.2 additions --- - Optional("bmi_interface"): Bool(), # How the model is reduced to a computable problem, and so which of # the blocks below this entry needs: mesh (the default), neural, or # particle. See ymf.discretizations, which also says what each @@ -361,23 +360,6 @@ DimensionlessNumberDef = Map({"formula": Str(), Optional("value"): Float()}) -DimensionalCheckDef = Map( - { - Optional("enabled"): Bool(), - Optional("method"): DimCheckMethodEnum, - Optional("tolerance"): Float(), - } -) - -UnitSystemDef = Map( - { - Optional("length"): Str(), - Optional("mass"): Str(), - Optional("time"): Str(), - Optional("temperature"): Str(), - } -) - UnitsDef = Map( { Optional("convention"): UnitConventionEnum, @@ -405,7 +387,7 @@ ) # --------------------------------------------------------------------------- -# StrongFormDef (updated: widened unknowns + new IC/BC/dimensional_check) +# StrongFormDef (updated: widened unknowns + new IC/BC) # --------------------------------------------------------------------------- StrongFormDef = Map( @@ -415,9 +397,6 @@ "provenance": ProvenanceEnum, "unknowns": Seq(UnknownDef), # CHANGED in v0.2: was Seq(Str()) "equation_formulation": Str(), - # Superseded by ``equations``, which is written in the same notation - # and read by ymf.symbolic; kept so older documents still validate. - Optional("strong_form_expression"): Str(), # "Ω = [0, 1] × [0, 1]", optionally ", t ∈ (0, 50]" for the time # interval of a transient problem. "domain": DomainDef, @@ -429,11 +408,7 @@ "boundary_regions": Seq(Map({"name": Str(), "where": Str()})), Optional("initial_conditions"): Seq(InitialConditionDef), Optional("boundary_conditions"): Seq(BoundaryConditionDef), - Optional("known_analytical_solution"): Map( - {"formula": Str(), "reference": Str()} - ), Optional("coefficients"): MapPattern(Str(), CoefficientDef), - Optional("dimensional_check"): DimensionalCheckDef, # The equations, one string per (vector or scalar) equation, in the # notation of ymf.symbolic.notation -- "∂T/∂t = ∇·(κ∇T) in Ω", # "ρ ∂v/∂t + ∇·(ρ v⊗v) − μΔv + ∇p = f" -- ordered like the unknowns. @@ -442,7 +417,7 @@ ) # --------------------------------------------------------------------------- -# Problem (updated: + characteristic_scales, units, unit_systems, mesh_generation) +# model (updated: + characteristic_scales, units, mesh_generation) # --------------------------------------------------------------------------- ModelDef = Map( @@ -454,7 +429,6 @@ Optional("characteristic_scales"): CharacteristicScalesDef, Optional("dimensionless_numbers"): MapPattern(Str(), DimensionlessNumberDef), Optional("units"): UnitsDef, - Optional("unit_systems"): MapPattern(Str(), UnitSystemDef), Optional("mesh_generation"): MeshGenerationDef, } ) @@ -470,8 +444,6 @@ Optional("vvuq"): Map( {Optional("verification"): Any(), Optional("validation"): Any()} ), - Optional("archive"): Any(), - Optional("xdmf"): Any(), # File-level keys, see ymf.compose. "extends" names the document # this one builds on; "ymf_state" says how far the document has got # (abstract, well-posed, discretized, closed: see ymf.state), and is @@ -489,7 +461,7 @@ }), Optional("composition"): Any(), # "remove" lists paths this file drops from what it extends -- - # "Problem.physical_model.assumptions[incompressible]". Composition + # "model.physical_model.assumptions[incompressible]". Composition # could only add and change before, so dropping an assumption or a # field took a new model file even when the change was one line. Optional("remove"): Seq(Str()), @@ -506,7 +478,15 @@ def _partial(validator, keep=()): an inherited discretization by naming it and giving only that field. The composed document is validated in full, so an entry that is new and incomplete is still caught there. + + Both sides of an alternative are relaxed too: the domain is the notation + string or a mapping, and a file that tags an inherited region writes + ``boundary_tags`` without restating its ``kind``. The composed domain + is checked against its kind by ymf.domain. """ + if isinstance(validator, OrValidator): + return OrValidator(_partial(validator._validator_a, keep), + _partial(validator._validator_b, keep)) if isinstance(validator, Map): return Map({ (key if isinstance(key, Optional) or key in keep else Optional(key)): diff --git a/src/ymf/units.py b/src/ymf/units.py index f03a08a..b63559f 100644 --- a/src/ymf/units.py +++ b/src/ymf/units.py @@ -1,7 +1,7 @@ """Unit handling, dimensional consistency checking, and non-dimensionalization. Implements the "immediate"/"short-term" recommendations from -``docs/ymf-units-report.md``: +``docs/research/units.md``: - pint-backed unit string parsing (report §1.1, §6.2), tolerant of the bare-exponent (``m2/s``), unicode-superscript (``m²``), caret (``m^2``), @@ -15,11 +15,11 @@ documents with no units at all and simply reports "nothing to check" rather than raising. Units are an enhancement, never a requirement. -Symbolic parsing of ``strong_form_expression`` term-by-term (report §4.2) is -explicitly **out of scope** here — it needs a real expression parser and is -deferred to the ibvp/sympy language layer per the v0.2 delta doc §7. What -*is* implemented is everything checkable from unit strings already present -on the parsed document. +Reading the ``equations`` is ymf.symbolic's job, not this module's. With +ymf[symbolic] installed, the boundary-condition check uses it to find each +equation's diffusive flux; without it, those comparisons are reported as +not checked. Everything else here is checkable from the unit strings +already present on the parsed document. """ from __future__ import annotations @@ -722,7 +722,7 @@ def _eval_notation(formula: str, scope: Dict[str, float]) -> Optional[float]: def characteristic_scale_values(problem: Dict[str, Any]) -> Dict[str, float]: - """Resolve ``Problem.characteristic_scales`` to a flat ``{name: value}`` dict. + """Resolve ``model.characteristic_scales`` to a flat ``{name: value}`` dict. Direct (``value:``) scales are taken as-is. ``derived: true`` scales (e.g. ``time: {derived: true, formula: "L_char / U_char"}``, report @@ -831,7 +831,7 @@ def _coefficient_values(problem: Dict[str, Any]) -> Dict[str, float]: def compute_dimensionless_numbers(problem: Dict[str, Any]) -> Dict[str, float]: - """Evaluate ``Problem.dimensionless_numbers[].formula`` (report §5.2). + """Evaluate ``model.dimensionless_numbers[].formula`` (report §5.2). Formulas are evaluated against a scope built from :func:`characteristic_scale_values` (using bare names ``L``, ``U``, @@ -882,7 +882,7 @@ def compute_dimensionless_numbers(problem: Dict[str, Any]) -> Dict[str, float]: def non_dimensionalize(doc: Dict[str, Any]) -> Dict[str, Any]: """Build the non-dimensionalization block described in report §5.2/§5.3. - Given a document with ``Problem.characteristic_scales`` and + Given a document with ``model.characteristic_scales`` and units-annotated ``unknowns``, returns: - ``characteristic_scales``: resolved numeric values (incl. derived ones) @@ -892,7 +892,7 @@ def non_dimensionalize(doc: Dict[str, Any]) -> Dict[str, Any]: pressure), mirroring the report's worked examples (§5.4) This produces the substitution *relations*, not a symbolic substitution - into ``strong_form_expression`` — doing that requires a full sympy-based + into the ``equations`` — doing that requires a full sympy-based PDE parser and is explicitly deferred (v0.2 delta doc §7: "automatic non-dimensionalization pipeline"). """ diff --git a/src/ymf/xdmf.py b/src/ymf/xdmf.py index 5ab3fac..a43d19e 100644 --- a/src/ymf/xdmf.py +++ b/src/ymf/xdmf.py @@ -1,6 +1,6 @@ """Convert between a YMF data tree and an XDMF 2.0 XML document, round-trip. -Per ``docs/ymf-schema.md`` §5 ("XDMF Preservation") and the design +Per ``docs/history/schema-v0.1.md`` §5 ("XDMF Preservation") and the design principle that *XDMF is a consumer, not a dependency* of YMF: this module reads a plain Python dict describing a time-collection of grids (mesh topology + geometry, optionally HDF5-backed) and emits an ``.xmf`` file @@ -23,7 +23,7 @@ So: everything in a YMF document that *does* map onto XDMF concepts (``Domain``/``Grid``/``Topology``/``Geometry``/``DataItem`` — i.e. the mesh -archive) is written as real XDMF elements. Everything else (``Problem``, +archive) is written as real XDMF elements. Everything else (``model``, ``solution_paths``, ``vvuq``, and any ``archive``-level metadata XDMF has no concept of) is serialized to JSON, base64-encoded (safe inside an XML attribute value with no escaping headaches), and stashed in a single @@ -49,7 +49,7 @@ - Mesh/archive data (``Domain``) round-trips exactly (it *is* the native XDMF representation already). -- Everything under ``Problem``/``solution_paths``/``vvuq`` round-trips +- Everything under ``model``/``solution_paths``/``vvuq`` round-trips exactly *as long as it survives a YAML dump/load cycle* — which is true for everything currently in the schema (plain strings, numbers, nested maps/sequences). :func:`round_trip_equal` is provided to verify this for @@ -69,7 +69,7 @@ from xml.etree.ElementTree import (Element, ElementTree, ParseError, SubElement, fromstring, parse as et_parse) -from ymf.archive import (YmfArchiveError, canonicalize_domain, +from ymf.archive import (YmfArchiveError, canonicalize_approximation, time_collections, transpose_collections) XDMF_HEADER = b'\n\n' @@ -467,7 +467,7 @@ def build_xdmf_tree( ---------- domain: A plain dict shaped like the ``Domain`` block described in - ``docs/ymf-schema.md`` §5, e.g.:: + ``docs/history/schema-v0.1.md`` §5, e.g.:: { "time_collection": { @@ -516,7 +516,7 @@ def build_xdmf_tree( # Canonicalize up front so this function reads one well-defined shape # rather than re-deriving defaults inline at every use. - canonical = canonicalize_domain(domain) + canonical = canonicalize_approximation(domain) # XDMF nests the other way round -- a temporal collection per grid type -- # so the spaces inside each instant come back out as one collection each. for time_collection in time_collections(canonical): @@ -603,7 +603,7 @@ def _parse_step(step_elem: Element, where: str) -> Dict[str, Any]: raise YmfArchiveError( "%s: a spatial collection in a YMF archive holds uniform grids " "only, not further collections" % (at,)) - # Name goes first, matching the key order canonicalize_domain() + # Name goes first, matching the key order canonicalize_approximation() # produces, so a parsed document compares equal to a canonical one. sub: Dict[str, Any] = {} if "Name" in sub_elem.attrib: @@ -723,6 +723,6 @@ def round_trip_equal(domain: Dict[str, Any], ymf_extra: Optional[Any] = None) -> try: write_xdmf(domain, tmp_path, ymf_extra=ymf_extra) read_domain, read_extra = read_xdmf(tmp_path) - return read_domain == canonicalize_domain(domain) and read_extra == ymf_extra + return read_domain == canonicalize_approximation(domain) and read_extra == ymf_extra finally: Path(tmp_path).unlink(missing_ok=True) diff --git a/tests/test_archive.py b/tests/test_archive.py index 6159c74..e50e3bb 100644 --- a/tests/test_archive.py +++ b/tests/test_archive.py @@ -7,8 +7,8 @@ from ymf.archive import time_collections # noqa: E402 from ymf.archive import ( - domain_arrays, - inline_domain, + approximation_arrays, + inline_approximation, ARCHIVE_FORMAT_VERSION, HAVE_LIBYAML, YmfArchiveError, @@ -17,7 +17,7 @@ add_uniform_step, append_step, attribute, - canonicalize_domain, + canonicalize_approximation, check_dimensions, data_item, data_item_for, @@ -25,11 +25,11 @@ geometry, grid, load_grid, - new_domain, + new_approximation, read_ymf, require_libyaml, topology, - validate_domain, + validate_approximation, write_ymf, ) @@ -41,7 +41,7 @@ def make_uniform_domain(): """A single-grid archive -- what a serial run produces.""" - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") for t in (0.0, 1.0): add_uniform_step( domain, @@ -66,7 +66,7 @@ def make_uniform_domain(): def make_spatial_domain(n_ranks=3): """A subdomain-per-rank archive -- what a parallel run produces.""" - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") for t in (0.0, 0.5): grids = [] for r in range(n_ranks): @@ -205,13 +205,13 @@ def test_check_dimensions_rejects_a_mismatch_and_names_the_field(): def test_canonicalize_is_idempotent(): - once = canonicalize_domain(make_uniform_domain()) - assert canonicalize_domain(once) == once + once = canonicalize_approximation(make_uniform_domain()) + assert canonicalize_approximation(once) == once def test_canonicalize_is_idempotent_for_spatial_domains(): - once = canonicalize_domain(make_spatial_domain()) - assert canonicalize_domain(once) == once + once = canonicalize_approximation(make_spatial_domain()) + assert canonicalize_approximation(once) == once def test_canonicalize_fills_every_documented_default(): @@ -231,7 +231,7 @@ def test_canonicalize_fills_every_documented_default(): ] } } - c = canonicalize_domain(sparse) + c = canonicalize_approximation(sparse) # the singular format 1 input form is upgraded to format 2 assert list(c) == ["times"] assert len(time_collections(c)) == 1 @@ -248,17 +248,17 @@ def test_canonicalize_fills_every_documented_default(): def test_canonicalize_supplies_an_empty_attributes_list(): - domain = new_domain() + domain = new_approximation() add_uniform_step( domain, 0.0, topology("Triangle", 1, data_item([1, 3], "f.h5:/e")), geometry(data_item([3, 2], "f.h5:/n")), ) - assert time_collections(canonicalize_domain(domain))[0]["data"][0]["attributes"] == [] + assert time_collections(canonicalize_approximation(domain))[0]["data"][0]["attributes"] == [] def test_canonicalize_of_an_empty_domain_is_empty(): - assert canonicalize_domain({}) == {} + assert canonicalize_approximation({}) == {} def test_step_cannot_be_both_uniform_and_spatial(): @@ -275,12 +275,12 @@ def test_step_cannot_be_both_uniform_and_spatial(): } } with pytest.raises(YmfArchiveError, match="not both"): - canonicalize_domain(domain) + canonicalize_approximation(domain) def test_step_must_be_either_uniform_or_spatial(): with pytest.raises(YmfArchiveError, match="neither"): - canonicalize_domain({"time_collection": {"data": [{"time": 0.0}]}}) + canonicalize_approximation({"time_collection": {"data": [{"time": 0.0}]}}) @pytest.mark.parametrize("missing", ["type", "number_of_elements", "data_item"]) @@ -294,7 +294,7 @@ def test_canonicalize_reports_a_missing_topology_key_by_path(missing): } } with pytest.raises(YmfArchiveError, match=rf"time_collections\[0\]\.data\[0\]\.topology.*{missing}"): - canonicalize_domain(domain) + canonicalize_approximation(domain) # -------------------------------------------------------------------------- @@ -303,19 +303,19 @@ def test_canonicalize_reports_a_missing_topology_key_by_path(missing): def test_validate_accepts_the_uniform_and_spatial_fixtures(): - validate_domain(make_uniform_domain()) - validate_domain(make_spatial_domain()) + validate_approximation(make_uniform_domain()) + validate_approximation(make_spatial_domain()) def test_validate_returns_the_canonicalized_document(): - assert validate_domain(make_uniform_domain()) == canonicalize_domain(make_uniform_domain()) + assert validate_approximation(make_uniform_domain()) == canonicalize_approximation(make_uniform_domain()) def test_validate_rejects_an_unknown_topology_type(): domain = make_uniform_domain() time_collections(domain)[0]["data"][0]["topology"]["type"] = "Dodecahedron" with pytest.raises(YmfArchiveError, match="not a known XDMF topology type"): - validate_domain(domain) + validate_approximation(domain) def test_validate_accepts_every_topology_type_proteus_emits(): @@ -335,21 +335,21 @@ def test_validate_rejects_a_bad_centering(): domain = make_uniform_domain() time_collections(domain)[0]["data"][0]["attributes"][0]["center"] = "Vertex" with pytest.raises(YmfArchiveError, match=r"attributes\[0\]\.center"): - validate_domain(domain) + validate_approximation(domain) def test_validate_rejects_a_bad_attribute_type(): domain = make_uniform_domain() time_collections(domain)[0]["data"][0]["attributes"][0]["attribute_type"] = "Scalarr" with pytest.raises(YmfArchiveError, match=r"attributes\[0\]\.attribute_type"): - validate_domain(domain) + validate_approximation(domain) def test_validate_rejects_a_bad_data_type(): domain = make_uniform_domain() time_collections(domain)[0]["data"][0]["attributes"][0]["data_item"]["data_type"] = "Double" with pytest.raises(YmfArchiveError, match="data_type"): - validate_domain(domain) + validate_approximation(domain) def test_validate_rejects_duplicate_attribute_names_within_one_grid(): @@ -360,7 +360,7 @@ def test_validate_rejects_duplicate_attribute_names_within_one_grid(): attrs[1]["name"] = attrs[0]["name"] attrs[1]["center"] = attrs[0]["center"] with pytest.raises(YmfArchiveError, match="duplicate .*-centred attribute name"): - validate_domain(domain) + validate_approximation(domain) def test_validate_allows_the_same_name_on_different_centerings(): @@ -370,37 +370,37 @@ def test_validate_allows_the_same_name_on_different_centerings(): attrs = time_collections(domain)[0]["data"][0]["attributes"] attrs[1]["name"] = attrs[0]["name"] attrs[0]["center"], attrs[1]["center"] = "Cell", "Node" - validate_domain(domain) + validate_approximation(domain) def test_validate_allows_the_same_attribute_name_in_different_subdomains(): # Each rank writes its own 'p'; that is correct, not a duplicate. - validate_domain(make_spatial_domain(n_ranks=4)) + validate_approximation(make_spatial_domain(n_ranks=4)) def test_validate_rejects_an_empty_spatial_collection(): - domain = new_domain() + domain = new_approximation() add_spatial_step(domain, 0.0, []) with pytest.raises(YmfArchiveError, match="must not be empty"): - validate_domain(domain) + validate_approximation(domain) def test_validate_rejects_empty_dimensions(): domain = make_uniform_domain() time_collections(domain)[0]["data"][0]["attributes"][0]["data_item"]["dimensions"] = [] with pytest.raises(YmfArchiveError, match="must not be empty"): - validate_domain(domain) + validate_approximation(domain) def test_validate_rejects_a_negative_dimension(): domain = make_uniform_domain() time_collections(domain)[0]["data"][0]["attributes"][0]["data_item"]["dimensions"] = [-1] with pytest.raises(YmfArchiveError, match="non-negative"): - validate_domain(domain) + validate_approximation(domain) def test_validate_of_an_empty_domain_is_empty(): - assert validate_domain({}) == {} + assert validate_approximation({}) == {} # -------------------------------------------------------------------------- @@ -413,7 +413,7 @@ def test_uniform_domain_round_trips_through_yaml(tmp_path): path = tmp_path / "archive.ymf" write_ymf(domain, path) read_domain, extra = read_ymf(path) - assert read_domain == canonicalize_domain(domain) + assert read_domain == canonicalize_approximation(domain) assert extra is None @@ -422,11 +422,11 @@ def test_spatial_domain_round_trips_through_yaml(tmp_path): path = tmp_path / "archive.ymf" write_ymf(domain, path) read_domain, _ = read_ymf(path) - assert read_domain == canonicalize_domain(domain) + assert read_domain == canonicalize_approximation(domain) def test_text_include_data_items_round_trip_through_yaml(tmp_path): - domain = new_domain() + domain = new_approximation() add_uniform_step( domain, 0.0, topology("Triangle", 2, data_item([2, 3], include="./d/elements.txt", data_type="Int")), @@ -436,7 +436,7 @@ def test_text_include_data_items_round_trip_through_yaml(tmp_path): path = tmp_path / "archive.ymf" write_ymf(domain, path) read_domain, _ = read_ymf(path) - assert read_domain == canonicalize_domain(domain) + assert read_domain == canonicalize_approximation(domain) assert time_collections(read_domain)[0]["data"][0]["attributes"][0]["data_item"]["include"] == "./d/u.txt" @@ -516,11 +516,11 @@ def test_grid_fragments_reassemble_into_a_spatial_step(): fragments = [ dump_grid(g) for g in time_collections(original)[0]["data"][0]["spatial_collection"] ] - rebuilt = new_domain(time_collections(original)[0]["name"]) + rebuilt = new_approximation(time_collections(original)[0]["name"]) add_spatial_step(rebuilt, 0.0, [load_grid(f) for f in fragments]) assert ( - time_collections(canonicalize_domain(rebuilt))[0]["data"][0] - == time_collections(canonicalize_domain(original))[0]["data"][0] + time_collections(canonicalize_approximation(rebuilt))[0]["data"][0] + == time_collections(canonicalize_approximation(original))[0]["data"][0] ) @@ -547,7 +547,7 @@ def test_require_libyaml_raises_when_the_c_extension_is_missing(): # pragma: no def _two_space_domain(): """The shape a real Proteus archive has: linear mesh + quadratic space.""" - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") add_collection(domain, "Mesh_c0p2_Lagrange") for t in (0.0, 1.0): add_uniform_step( @@ -567,7 +567,7 @@ def _two_space_domain(): def test_new_domain_starts_with_one_named_collection(): - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") assert [c["name"] for c in time_collections(domain)] == ["Mesh Spatial_Domain"] @@ -579,7 +579,7 @@ def test_add_collection_appends_a_second_mesh(): def test_add_collection_rejects_a_duplicate_name(): - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") with pytest.raises(YmfArchiveError, match="already has a time collection"): add_collection(domain, "Mesh Spatial_Domain") @@ -619,16 +619,16 @@ def test_targeting_an_out_of_range_collection_index_reports_the_count(): def test_a_two_space_domain_validates_and_round_trips(tmp_path): domain = _two_space_domain() - validate_domain(domain) + validate_approximation(domain) path = tmp_path / "archive.ymf" write_ymf(domain, path) - assert read_ymf(path)[0] == canonicalize_domain(domain) + assert read_ymf(path)[0] == canonicalize_approximation(domain) def test_the_same_attribute_name_may_appear_in_different_collections(): # 'u' on the linear mesh and 'u' on the quadratic space are different # fields on different meshes, not a duplicate. - validate_domain(_two_space_domain()) + validate_approximation(_two_space_domain()) def test_duplicate_collection_names_are_rejected_at_canonicalization(): @@ -639,13 +639,13 @@ def test_duplicate_collection_names_are_rejected_at_canonicalization(): ] } with pytest.raises(YmfArchiveError, match="duplicate collection name"): - canonicalize_domain(domain) + canonicalize_approximation(domain) def test_singular_time_collection_is_accepted_as_input_sugar(): singular = {"time_collection": {"name": "Mesh", "data": []}} plural = {"time_collections": [{"name": "Mesh", "data": []}]} - assert canonicalize_domain(singular) == canonicalize_domain(plural) + assert canonicalize_approximation(singular) == canonicalize_approximation(plural) # --------------------------------------------------------------------------- @@ -690,18 +690,18 @@ def test_inline_values_are_checked(values, data_type, message): def test_validate_refuses_inline_values_under_another_format(): - domain = new_domain() + domain = new_approximation() add_uniform_step(domain, 0.0, topology("Polyvertex", 1, data_item([1], values=[0], data_type="Int"), nodes_per_element=1), geometry(data_item([1, 3], values=[0.0, 0.0, 0.0]))) time_collections(domain)[0]["data"][0]["geometry"]["data_item"]["format"] = "HDF" with pytest.raises(YmfArchiveError, match=r"geometry\.data_item: inline 'values' need format='XML'"): - validate_domain(domain) + validate_approximation(domain) def test_an_inline_archive_round_trips_and_writes_each_array_on_few_lines(tmp_path): - domain = new_domain("mesh") + domain = new_approximation("mesh") add_uniform_step( domain, 0.0, topology("Triangle", 2, data_item([2, 3], values=[0, 1, 3, 0, 3, 2], data_type="Int")), @@ -712,7 +712,7 @@ def test_an_inline_archive_round_trips_and_writes_each_array_on_few_lines(tmp_pa text = path.read_text() assert "values: [0, 1, 3, 0, 3, 2]" in text read_back, _ = read_ymf(path) - assert read_back == validate_domain(domain) + assert read_back == validate_approximation(domain) # --------------------------------------------------------------------------- @@ -721,7 +721,7 @@ def test_an_inline_archive_round_trips_and_writes_each_array_on_few_lines(tmp_pa def test_dimensions_are_written_on_one_line(tmp_path): - domain = new_domain("mesh") + domain = new_approximation("mesh") add_uniform_step(domain, 0.0, topology("Triangle", 8, data_item([8, 3], "m.h5:/e", data_type="Int")), geometry(data_item([9, 3], "m.h5:/n", precision=8))) @@ -738,14 +738,14 @@ def test_inline_domain_copies_hdf5_arrays_in_exactly(tmp_path): u = np.linspace(0, 1, 4, dtype=np.float32) with h5py.File(tmp_path / "m.h5", "w") as f: f["e"], f["n"], f["u"] = cells, nodes, u - domain = new_domain("mesh") + domain = new_approximation("mesh") add_uniform_step(domain, 0.0, topology("Triangle", 2, data_item_for(cells, "m.h5:/e")), geometry(data_item_for(nodes, "m.h5:/n")), [attribute("u", data_item_for(u, "m.h5:/u"))]) - referenced = domain_arrays(domain, tmp_path) - inline = inline_domain(domain, tmp_path) + referenced = approximation_arrays(domain, tmp_path) + inline = inline_approximation(domain, tmp_path) assert all("values" in a["data_item"] for a in time_collections(inline)[0]["data"][0]["attributes"]) - copied = domain_arrays(inline) # no base directory needed any more + copied = approximation_arrays(inline) # no base directory needed any more assert set(copied) == set(referenced) for key in referenced: assert copied[key].dtype == referenced[key].dtype @@ -759,7 +759,7 @@ def test_inline_domain_copies_hdf5_arrays_in_exactly(tmp_path): def _one_step(time): """A step dict, built the way a writer builds one.""" - domain = new_domain("scratch") + domain = new_approximation("scratch") add_uniform_step( domain, time, {"type": "Triangle", "number_of_elements": 4, @@ -771,7 +771,7 @@ def _one_step(time): def _archive(tmp_path, name="a.ymf"): path = tmp_path / name - write_ymf(new_domain("Mesh Spatial_Domain"), path) + write_ymf(new_approximation("Mesh Spatial_Domain"), path) return path @@ -812,7 +812,7 @@ def test_appending_matches_writing_the_whole_document(tmp_path): introduce. """ appended = _archive(tmp_path, "appended.ymf") - whole = new_domain("Mesh Spatial_Domain") + whole = new_approximation("Mesh Spatial_Domain") for t in (0.0, 0.5): step = _one_step(t) append_step(appended, "Mesh Spatial_Domain", step) @@ -904,3 +904,24 @@ def test_appending_is_constant_work_per_step(tmp_path): # magnitude above the first. assert max(sizes) - min(sizes) <= 8, sizes assert path.stat().st_size > 10 * max(sizes) # the file grew; the write did not + + +def test_the_archive_tree_functions_keep_their_old_names(): + """Renamed 2026-11 (``domain`` is the region); the old names stay a release.""" + import ymf + import ymf.archive as archive + + renamed = { + "new_domain": "new_approximation", + "validate_domain": "validate_approximation", + "canonicalize_domain": "canonicalize_approximation", + "select_domain": "select_approximation", + "rebase_domain": "rebase_approximation", + "inline_domain": "inline_approximation", + "domain_arrays": "approximation_arrays", + } + for old, new in renamed.items(): + assert getattr(archive, old) is getattr(archive, new) + assert old in archive.__all__ and new in archive.__all__ + for old in ("new_domain", "validate_domain", "canonicalize_domain"): + assert getattr(ymf, old) is getattr(ymf, renamed[old]) diff --git a/tests/test_cli.py b/tests/test_cli.py index 0ab2fdd..e6f78dd 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -15,7 +15,7 @@ data_item, geometry, grid, - new_domain, + new_approximation, read_ymf, topology, write_ymf, @@ -24,7 +24,7 @@ def make_domain(spatial=False, n_ranks=2): - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") for t in (0.0, 0.5): if spatial: add_spatial_step(domain, t, [ @@ -117,7 +117,7 @@ def test_a_per_subdomain_archive_converts_to_spatial_collections(tmp_path): def test_the_extra_payload_survives_the_conversion(tmp_path): - """Problem/vvuq metadata rides along in the element. + """model/vvuq metadata rides along in the element. So converting for a viewer does not discard the physics description, and read_xdmf can recover it. diff --git a/tests/test_closure.py b/tests/test_closure.py index 576597a..1aa784d 100644 --- a/tests/test_closure.py +++ b/tests/test_closure.py @@ -7,7 +7,7 @@ from ymf import closure from ymf.archive import time_collections # noqa: E402 from ymf.archive import (YmfArchiveError, add_uniform_step, data_item, geometry, - new_domain, read_document, topology) + new_approximation, read_document, topology) EXAMPLES = Path(__file__).parent.parent / "examples" MESH = " mesh: {cells: [4, 8], levels: 2}\n" @@ -15,6 +15,7 @@ def spec_with_mesh(tmp_path, mesh=MESH, name="poisson.ymf"): """examples/poisson.ymf with this mesh on P1_linear, and none on P2.""" + pytest.importorskip("strictyaml") # closure.load composes the spec: ymf[spec] text = "".join(line for line in (EXAMPLES / "poisson.ymf").read_text(encoding="utf-8").splitlines(True) if not line.lstrip().startswith("mesh:")) @@ -28,7 +29,7 @@ def spec_with_mesh(tmp_path, mesh=MESH, name="poisson.ymf"): def fake_output(realization): """An output holding one inline, two-point grid.""" - domain = new_domain() + domain = new_approximation() nodes = data_item([2, 2], values=[0.0, 0.0, 1.0, 1.0]) vertices = data_item([2], values=[0, 1], data_type="Int", precision=4) add_uniform_step(domain, 0.0, topology("Polyvertex", 2, vertices, nodes_per_element=1), @@ -110,7 +111,7 @@ def test_extending_an_archive_keeps_only_outputs_whose_input_is_unchanged(tmp_pa assert set(outputs) < set(planned) and len(planned) == 3 # changing the problem invalidates every inherited output - child.write_text("extends: poisson.archive.ymf\nProblem:\n name: Changed\n", + child.write_text("extends: poisson.archive.ymf\nmodel:\n name: Changed\n", encoding="utf-8") _, kept, dropped = closure.load(child) assert kept == {} and set(dropped) == set(outputs) @@ -128,7 +129,7 @@ def test_a_kept_differing_rerun_is_matched_by_its_base_key(tmp_path): def test_a_document_from_a_newer_ymf_is_refused(tmp_path): path = tmp_path / "future.ymf" - path.write_text("ymf: 999.0.0\nProblem: {name: x}\n", encoding="utf-8") + path.write_text("ymf: 999.0.0\nmodel: {name: x}\n", encoding="utf-8") with pytest.raises(YmfArchiveError, match="newer than this ymf"): read_document(path) @@ -149,13 +150,13 @@ def test_ymf2xmf_writes_one_xmf_per_output(tmp_path): def test_inherited_outputs_still_point_at_their_files(tmp_path): - from ymf.archive import canonicalize_domain + from ymf.archive import canonicalize_approximation base = tmp_path / "base" base.mkdir() spec, _, _ = closure.load(spec_with_mesh(base, mesh=" mesh: {cells: 4}\n")) (key, _, r), = closure.planned_outputs(spec) output = fake_output(r) - domain = canonicalize_domain(output["approximation"]) + domain = canonicalize_approximation(output["approximation"]) time_collections(domain)[0]["data"][0]["geometry"]["data_item"] = data_item( [2, 2], "poisson_x.h5:/nodes") output["approximation"] = domain diff --git a/tests/test_compose.py b/tests/test_compose.py index db3eb94..6ae5562 100644 --- a/tests/test_compose.py +++ b/tests/test_compose.py @@ -3,7 +3,8 @@ from pathlib import Path import pytest -import strictyaml + +strictyaml = pytest.importorskip("strictyaml") from ymf.compose import YmfCompositionError from ymf.schema import load_ymf @@ -22,7 +23,6 @@ - name: u units: m/s equation_formulation: "model" - strong_form_expression: "x" coefficients: mu: {units: Pa*s} """ @@ -184,7 +184,7 @@ def test_an_error_in_a_parent_is_reported_against_the_parent(tmp_path): def test_an_error_in_a_single_file_is_reported_against_it(tmp_path): path = tmp_path / "bad.ymf" - path.write_text("Problem:\n name: x\n nonsense: 1\nsolution_paths:\n" + path.write_text("model:\n name: x\n nonsense: 1\nsolution_paths:\n" " analytical: []\n discretizations: []\n", encoding="utf-8") with pytest.raises(strictyaml.YAMLValidationError, match=r"bad\.ymf"): load_ymf(path) @@ -313,3 +313,12 @@ def test_a_file_that_is_wrong_on_its_own_still_cites_itself(tmp_path): message = str(caught.value) assert "problem.ymf" in message assert "composed from" not in message + + +@pytest.mark.parametrize("old", ["Problem", "problem"]) +def test_the_old_top_level_key_still_reads_as_model(tmp_path, old): + """An archive written before the key was renamed keeps loading.""" + path = tmp_path / "old.ymf" + path.write_text(BASE.replace("model:", old + ":", 1), encoding="utf-8") + doc = load_ymf(path) + assert doc["model"]["name"] == "flow" and old not in doc diff --git a/tests/test_core_without_frontend.py b/tests/test_core_without_frontend.py index e9f3be6..3d71a30 100644 --- a/tests/test_core_without_frontend.py +++ b/tests/test_core_without_frontend.py @@ -81,7 +81,8 @@ def test_which_loader_a_file_needs_is_a_core_question(): def test_compose_still_offers_the_old_private_name(): - """Proteus imports ymf.compose._is_archive_text; it must keep working.""" + """Proteus imported ymf.compose._is_archive_text; it must keep working.""" + pytest.importorskip("strictyaml") # ymf.compose is ymf[spec] from ymf.archive import is_archive_text from ymf.compose import _is_archive_text assert _is_archive_text is is_archive_text diff --git a/tests/test_discretizations.py b/tests/test_discretizations.py index 282f762..6348815 100644 --- a/tests/test_discretizations.py +++ b/tests/test_discretizations.py @@ -62,13 +62,13 @@ def test_mesh_keys_read_as_they_always_have(): pytest.importorskip("strictyaml") -from ymf.archive import add_uniform_step, data_item, geometry, new_domain, topology # noqa: E402 +from ymf.archive import add_uniform_step, data_item, geometry, new_approximation, topology # noqa: E402 from ymf.compose import load_composed # noqa: E402 from ymf.state import branches, reached # noqa: E402 def _output(realization): - domain = new_domain() + domain = new_approximation() nodes = data_item([2, 2], values=[0.0, 0.0, 1.0, 1.0]) vertices = data_item([2], values=[0, 1], data_type="Int", precision=4) add_uniform_step(domain, 0.0, topology("Polyvertex", 2, vertices, nodes_per_element=1), diff --git a/tests/test_domain.py b/tests/test_domain.py index f27f37e..e7ddc9a 100644 --- a/tests/test_domain.py +++ b/tests/test_domain.py @@ -13,12 +13,15 @@ state of whatever object happens to hold it. """ +from pathlib import Path + import pytest +strictyaml = pytest.importorskip("strictyaml") + from ymf import load_ymf from ymf.domain import DOMAIN_KINDS, YmfDomainError, box_bounds, validate_domain_block -strictyaml = pytest.importorskip("strictyaml") def spec(domain): @@ -152,7 +155,7 @@ def test_the_two_box_forms_give_the_same_problem(): from ymf.symbolic.problem import adr_problem - doc = load_ymf("examples/poisson.ymf") + doc = load_ymf(Path(__file__).parent.parent / "examples" / "poisson.ymf") mapped = copy.deepcopy(doc) mapped["model"]["strong_form"]["domain"] = { "kind": "box", "lower": [0.0, 0.0], "upper": [1.0, 1.0]} @@ -171,6 +174,64 @@ def test_a_kind_nothing_solves_yet_says_so(tmp_path): adr_problem(doc) +# -------------------------------------------------------------------------- +# a domain composed across files +# -------------------------------------------------------------------------- + +PSLG_MODEL = spec(""" + kind: piecewise_linear + dimension: 2 + vertices: [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]] + segments: [[0, 1], [1, 2], [2, 3], [3, 0]]""") + + +def compose(tmp_path, child): + (tmp_path / "model.ymf").write_text(PSLG_MODEL, encoding="utf-8") + (tmp_path / "child.ymf").write_text( + "ymf_state: abstract\nextends: model.ymf\n" + child, encoding="utf-8") + return load_ymf(tmp_path / "child.ymf") + + +def test_a_child_may_tag_the_region_its_parent_states(tmp_path): + """The region in the model, the names of its boundaries in the problem.""" + doc = compose(tmp_path, """\ +model: + strong_form: + domain: + boundary_tags: {bottom: 1, right: 2, top: 3, left: 4} +""") + domain = doc["model"]["strong_form"]["domain"] + assert domain["kind"] == "piecewise_linear" and len(domain["vertices"]) == 4 + assert domain["boundary_tags"]["left"] == 4 + + +def test_a_child_that_changes_the_kind_keeps_the_parents_keys_and_is_refused(tmp_path): + """Mappings merge key by key, so a box over a PSLG still has vertices. + The composed domain is checked against its kind, which names them.""" + with pytest.raises(YmfDomainError, match="kind 'box' does not take segments, vertices"): + compose(tmp_path, """\ +model: + strong_form: + domain: {kind: box, lower: [0.0, 0.0], upper: [1.0, 2.0]} +""") + + +def test_a_child_replaces_the_region_by_removing_what_it_does_not_keep(tmp_path): + doc = compose(tmp_path, """\ +remove: + - "model.strong_form.domain.vertices" + - "model.strong_form.domain.segments" +model: + strong_form: + domain: {kind: box, lower: [0.0, 0.0], upper: [1.0, 2.0]} +""") + domain = doc["model"]["strong_form"]["domain"] + assert box_bounds(domain) == [[0.0, 0.0], [1.0, 2.0]] + assert "vertices" not in domain and "segments" not in domain + removed = [r["path"] for r in doc["composition"]["removals"]] + assert removed == ["model.strong_form.domain.vertices", "model.strong_form.domain.segments"] + + def test_every_kind_is_covered_by_the_tests_above(): """So a kind added later is not silently untested.""" assert set(DOMAIN_KINDS) == {"box", "piecewise_linear", "discrete", "file"} diff --git a/tests/test_examples.py b/tests/test_examples.py index 483c526..0d76b57 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -8,6 +8,7 @@ import pytest # the example scripts walk the unit checks, so they need the units extra +pytest.importorskip("strictyaml") pytest.importorskip("pint") from ymf.schema import load_ymf diff --git a/tests/test_nesting.py b/tests/test_nesting.py index 38e7b16..0a99c7f 100644 --- a/tests/test_nesting.py +++ b/tests/test_nesting.py @@ -1,6 +1,6 @@ """Time outside, space inside: format 2 of the archive domain. -See docs/design-time-outside-space.md. The format 1 fixture was written by +See docs/design/time-outside-space.md. The format 1 fixture was written by ymf before the change (two spaces, three instants), with the .xmf it gave. """ @@ -10,10 +10,10 @@ from ymf.archive import ( ARCHIVE_FORMAT_VERSION, YmfArchiveError, add_collection, add_instant, - add_uniform_step, append_step, attribute, canonicalize_domain, data_item, - geometry, new_domain, read_ymf, select_domain, series, space_names, + add_uniform_step, append_step, attribute, canonicalize_approximation, data_item, + geometry, new_approximation, read_ymf, select_approximation, series, space_names, spatial_grid, time_collections, topology, transpose_collections, - uniform_grid, validate_domain, write_ymf, + uniform_grid, validate_approximation, write_ymf, ) from ymf.xdmf import build_xdmf_tree, parse_xdmf_domain, write_xdmf @@ -85,7 +85,7 @@ def test_xmf_round_trips_through_the_transpose(tmp_path): write_xdmf(domain, tmp_path / "a.xmf") from ymf.xdmf import read_xdmf again, _ = read_xdmf(tmp_path / "a.xmf") - assert again == canonicalize_domain(domain) + assert again == canonicalize_approximation(domain) def test_write_then_read_is_format_2_and_equal(tmp_path): @@ -93,23 +93,23 @@ def test_write_then_read_is_format_2_and_equal(tmp_path): write_ymf(domain, tmp_path / "x.ymf") assert (tmp_path / "x.ymf").read_text().startswith("ymf_archive_version: 2\n") again, _ = read_ymf(tmp_path / "x.ymf") - assert again == canonicalize_domain(domain) + assert again == canonicalize_approximation(domain) def test_the_format_1_api_still_builds_something_that_upgrades(): - d = new_domain("A") + d = new_approximation("A") add_collection(d, "B") for t in (0.0, 1.0): for name in ("A", "B"): add_uniform_step(d, t, **{"topo": grid_at(name, t)["topology"], "geom": grid_at(name, t)["geometry"]}, collection=name) assert "time_collections" in d - c = canonicalize_domain(d) + c = canonicalize_approximation(d) assert [list(i["spaces"]) for i in c["times"]] == [["A", "B"], ["A", "B"]] def test_format_2_steps_join_the_instant_at_their_time(): - d = new_domain() + d = new_approximation() for t in (0.0, 1.0): for name in ("A", "B"): add_uniform_step(d, t, grid_at(name, t)["topology"], grid_at(name, t)["geometry"], @@ -119,21 +119,21 @@ def test_format_2_steps_join_the_instant_at_their_time(): def test_an_instant_with_no_spaces_is_refused(): with pytest.raises(YmfArchiveError, match=r"times\[0\]\.spaces"): - canonicalize_domain({"times": [{"time": 0.0, "spaces": {}}]}) + canonicalize_approximation({"times": [{"time": 0.0, "spaces": {}}]}) def test_errors_name_the_space_and_instant(): bad = grid_at("A", 0.0) bad["topology"]["type"] = "Dodecahedron" - d = new_domain() + d = new_approximation() add_instant(d, 0.0, {"A": bad}) with pytest.raises(YmfArchiveError, match=r"times\[0\]\.spaces\[A\]\.topology"): - validate_domain(d) + validate_approximation(d) def test_both_formats_in_one_domain_is_refused(): with pytest.raises(YmfArchiveError, match="both"): - canonicalize_domain({"times": [], "time_collections": []}) + canonicalize_approximation({"times": [], "time_collections": []}) # --- append_step --------------------------------------------------------- @@ -141,7 +141,7 @@ def test_both_formats_in_one_domain_is_refused(): def header(tmp_path): path = tmp_path / "run.ymf" - write_ymf(new_domain(), path) + write_ymf(new_approximation(), path) return path @@ -216,30 +216,30 @@ def test_a_future_format_is_refused(tmp_path): def three_by_two(): - d = new_domain() + d = new_approximation() for t in (0.0, 1.0, 2.0): add_instant(d, t, {"A": grid_at("A", t), "B": grid_at("B", t)}) return d def test_steps_index_instants_across_spaces(): - picked = select_domain(three_by_two(), steps="-1") + picked = select_approximation(three_by_two(), steps="-1") assert [i["time"] for i in picked["times"]] == [2.0] assert list(picked["times"][0]["spaces"]) == ["A", "B"] def test_collections_filter_spaces_and_keep_archive_order(): - picked = select_domain(three_by_two(), collections=["B", "A"]) + picked = select_approximation(three_by_two(), collections=["B", "A"]) assert space_names(picked) == ["A", "B"] - only = select_domain(three_by_two(), collections=["B"]) + only = select_approximation(three_by_two(), collections=["B"]) assert space_names(only) == ["B"] and len(only["times"]) == 3 def test_instants_without_a_chosen_space_are_dropped_before_steps_count(): - d = new_domain() + d = new_approximation() add_instant(d, 0.0, {"A": grid_at("A", 0.0)}) add_instant(d, 1.0, {"A": grid_at("A", 1.0), "B": grid_at("B", 1.0)}) - picked = select_domain(d, collections=["B"], steps="0") + picked = select_approximation(d, collections=["B"], steps="0") assert [i["time"] for i in picked["times"]] == [1.0] @@ -252,10 +252,10 @@ def test_series_and_the_format_1_view_agree(): def test_a_spatial_space_survives(): - d = new_domain() + d = new_approximation() g = grid_at("A", 0.0) add_instant(d, 0.0, {"A": spatial_grid([dict(g, name="r0"), dict(g, name="r1")])}) - c = validate_domain(d) + c = validate_approximation(d) assert len(c["times"][0]["spaces"]["A"]["spatial_collection"]) == 2 diff --git a/tests/test_proteus_archive.py b/tests/test_proteus_archive.py index e84e234..500e1cd 100644 --- a/tests/test_proteus_archive.py +++ b/tests/test_proteus_archive.py @@ -40,9 +40,9 @@ from ymf.archive import time_collections # noqa: E402 from ymf.archive import ( - canonicalize_domain, + canonicalize_approximation, read_ymf, - validate_domain, + validate_approximation, write_ymf, ) from ymf.xdmf import parse_xdmf_domain, write_xdmf @@ -99,7 +99,7 @@ def test_real_proteus_archive_parses_into_the_domain_model(path): def test_real_proteus_archive_passes_structural_validation(path): # If Proteus's own output fails YMF's structural checks, the checks are # wrong -- Proteus's archives are the ground truth here. - validate_domain(_parse(path)) + validate_approximation(_parse(path)) @pytest.mark.parametrize("path", FIXTURES, ids=lambda p: p.stem) @@ -107,7 +107,7 @@ def test_real_proteus_archive_round_trips_through_yaml(path, tmp_path): domain = _parse(path) ymf_path = tmp_path / "archive.ymf" write_ymf(domain, ymf_path) - assert read_ymf(ymf_path)[0] == canonicalize_domain(domain) + assert read_ymf(ymf_path)[0] == canonicalize_approximation(domain) @pytest.mark.parametrize("path", FIXTURES, ids=lambda p: p.stem) @@ -116,7 +116,7 @@ def test_real_proteus_archive_survives_the_full_pipeline(path, tmp_path): This is the Phase 0 exit criterion. """ - original = canonicalize_domain(_parse(path)) + original = canonicalize_approximation(_parse(path)) ymf_path = tmp_path / "archive.ymf" write_ymf(original, ymf_path) @@ -153,7 +153,7 @@ def references(domain): original = _parse(path) xmf_path = tmp_path / "reemitted.xmf" - write_xdmf(canonicalize_domain(original), xmf_path) + write_xdmf(canonicalize_approximation(original), xmf_path) assert references(_parse(xmf_path)) == references(original) @@ -170,7 +170,7 @@ def test_reemitted_xmf_differs_from_proteus_only_in_explicit_defaults(path, tmp_ elem.attrib for elem in et_parse(path).getroot().iter("DataItem") ] xmf_path = tmp_path / "reemitted.xmf" - write_xdmf(canonicalize_domain(_parse(path)), xmf_path) + write_xdmf(canonicalize_approximation(_parse(path)), xmf_path) reemitted_items = [ elem.attrib for elem in et_parse(xmf_path).getroot().iter("DataItem") ] diff --git a/tests/test_references.py b/tests/test_references.py index 5e886cd..b3cd657 100644 --- a/tests/test_references.py +++ b/tests/test_references.py @@ -15,10 +15,11 @@ import pytest +strictyaml = pytest.importorskip("strictyaml") + from ymf import load_ymf from ymf.references import YmfReferenceError -strictyaml = pytest.importorskip("strictyaml") def spec(weak_forms, discretizations, analytical="", vvuq="", extra=""): diff --git a/tests/test_removal.py b/tests/test_removal.py index 18618a4..4fe5806 100644 --- a/tests/test_removal.py +++ b/tests/test_removal.py @@ -16,10 +16,11 @@ import pytest +strictyaml = pytest.importorskip("strictyaml") + from ymf import load_ymf from ymf.compose import YmfRemovalError -strictyaml = pytest.importorskip("strictyaml") MODEL = """\ diff --git a/tests/test_schema.py b/tests/test_schema.py index 1cf3afd..b3c3b4d 100644 --- a/tests/test_schema.py +++ b/tests/test_schema.py @@ -1,7 +1,8 @@ from pathlib import Path import pytest -import strictyaml + +strictyaml = pytest.importorskip("strictyaml") from ymf.schema import load_ymf @@ -23,7 +24,6 @@ def test_load_v02_enriched_example(): assert unknowns[0]["std_name"] == "land_surface_temperature" bc = doc["model"]["strong_form"]["boundary_conditions"][0] assert bc["type"] == "dirichlet" - assert doc["solution_paths"]["discretizations"][0]["bmi_interface"] is True def test_rejects_unknown_bc_type(): @@ -34,7 +34,6 @@ def test_rejects_unknown_bc_type(): provenance: llm_derived unknowns: [u] equation_formulation: "x" - strong_form_expression: "x" domain: "x" boundary_regions: - name: "a" @@ -60,7 +59,6 @@ def test_rejects_unknown_bc_type(): {provenance} unknowns: - name: u {per_unknown} equation_formulation: "x" - strong_form_expression: "x" domain: "x" boundary_regions: - name: "a" @@ -145,3 +143,48 @@ def test_petsc_options_must_be_a_mapping(): linear_solver: petsc petsc_options: [ksp_type, cg] """)) + + +# Keys the schema accepted and nothing read, removed 2026-11-01 (docs/changes.md). +# Each is refused by name, so a document that carries one is told which. +_BASE = """ +model: + name: "p" +{model} strong_form: + provenance: llm_derived + unknowns: [u] + equation_formulation: "x" + domain: "x" + boundary_regions: + - {{name: "a", where: "b"}} +{strong_form}solution_paths: + analytical: [] + discretizations: + - name: "d" + provenance: human_specified + solver: {{type: linear}} +{discretization}{top}""" + + +@pytest.mark.parametrize("key, where, text", [ + ("strong_form_expression", "strong_form", ' strong_form_expression: "x"\n'), + ("known_analytical_solution", "strong_form", + ' known_analytical_solution: {formula: "x", reference: "y"}\n'), + ("dimensional_check", "strong_form", " dimensional_check: {enabled: true}\n"), + ("unit_systems", "model", " unit_systems: {si: {length: m}}\n"), + ("bmi_interface", "discretization", " bmi_interface: true\n"), + ("archive", "top", "archive: {}\n"), + ("xdmf", "top", "xdmf: {}\n"), + ("xdmf", "top", "Xdmf: {}\n"), # the v0.1 spelling is no longer folded +]) +def test_a_removed_key_is_refused_by_name(tmp_path, key, where, text): + """Loaded from a file, the path on which old spellings used to be folded.""" + parts = dict(model="", strong_form="", discretization="", top="") + path = tmp_path / "p.ymf" + path.write_text(_BASE.format(**parts), encoding="utf-8") + load_ymf(path) # the base is valid + parts[where] = text + path.write_text(_BASE.format(**parts), encoding="utf-8") + with pytest.raises(strictyaml.YAMLValidationError, + match="unexpected key not in schema '%s'" % text.split(":")[0].strip()): + load_ymf(path) diff --git a/tests/test_select.py b/tests/test_select.py index cb8c417..7ef7380 100644 --- a/tests/test_select.py +++ b/tests/test_select.py @@ -3,7 +3,7 @@ import pytest -from ymf.archive import canonicalize_domain, time_collections # noqa: E402 +from ymf.archive import canonicalize_approximation, time_collections # noqa: E402 from ymf.archive import ( YmfArchiveError, add_spatial_step, @@ -12,9 +12,9 @@ data_item, geometry, grid, - new_domain, + new_approximation, read_ymf, - select_domain, + select_approximation, step_indices, topology, write_ymf, @@ -24,7 +24,7 @@ def two_spaces(n_steps=4, spatial=False): """Two collections, several fields, n_steps instants; a Proteus-shaped archive.""" - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") quadratic = {"name": "Mesh_c0p2_Lagrange", "data": []} domain["time_collections"].append(quadratic) for i in range(n_steps): @@ -79,25 +79,25 @@ def test_a_step_the_archive_does_not_have_is_refused(): # -------------------------------------------------------------------------- -# select_domain +# select_approximation # -------------------------------------------------------------------------- def test_everything_is_kept_by_default(): domain = two_spaces() - assert select_domain(domain) == canonicalize_domain(domain) + assert select_approximation(domain) == canonicalize_approximation(domain) def test_a_collection_is_picked_by_name_or_part_of_it(): domain = two_spaces() - assert names_of(select_domain(domain, collections=["Mesh Spatial_Domain"])) == ["Mesh Spatial_Domain"] - assert names_of(select_domain(domain, collections=["c0p2"])) == ["Mesh_c0p2_Lagrange"] + assert names_of(select_approximation(domain, collections=["Mesh Spatial_Domain"])) == ["Mesh Spatial_Domain"] + assert names_of(select_approximation(domain, collections=["c0p2"])) == ["Mesh_c0p2_Lagrange"] with pytest.raises(YmfArchiveError, match="no collection matches 'dgp1'"): - select_domain(domain, collections=["dgp1"]) + select_approximation(domain, collections=["dgp1"]) def test_fields_are_picked_on_every_grid(): - picked = select_domain(two_spaces(), fields=["p"]) + picked = select_approximation(two_spaces(), fields=["p"]) base, quadratic = time_collections(picked) assert all(fields_of(step) == ["p"] for step in base["data"]) # the quadratic space has no p: its grids keep their mesh and lose their fields @@ -106,27 +106,27 @@ def test_fields_are_picked_on_every_grid(): def test_fields_are_picked_inside_spatial_collections(): - picked = select_domain(two_spaces(spatial=True), fields=["u"], collections=["Spatial"]) + picked = select_approximation(two_spaces(spatial=True), fields=["u"], collections=["Spatial"]) for step in time_collections(picked)[0]["data"]: assert [fields_of(g) for g in step["spatial_collection"]] == [["u"], ["u"]] def test_an_unknown_field_is_refused_with_what_there_is(): with pytest.raises(YmfArchiveError, match="no field named 'phi'.*'p', 'u', 'u2', 'vof'"): - select_domain(two_spaces(), fields=["phi"]) + select_approximation(two_spaces(), fields=["phi"]) def test_steps_apply_to_every_collection(): - picked = select_domain(two_spaces(), steps="-1") + picked = select_approximation(two_spaces(), steps="-1") for c in time_collections(picked): assert [s["time"] for s in c["data"]] == [pytest.approx(0.3)] - picked = select_domain(two_spaces(), steps="::2") + picked = select_approximation(two_spaces(), steps="::2") assert [s["time"] for s in time_collections(picked)[0]["data"]] == [0.0, pytest.approx(0.2)] def test_the_source_is_not_modified(): domain = two_spaces() - select_domain(domain, collections=["c0p2"], fields=["u2"], steps="0") + select_approximation(domain, collections=["c0p2"], fields=["u2"], steps="0") assert names_of(domain) == ["Mesh Spatial_Domain", "Mesh_c0p2_Lagrange"] assert fields_of(time_collections(domain)[0]["data"][3]) == ["u", "p", "vof"] diff --git a/tests/test_state.py b/tests/test_state.py index aac709b..331caf9 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -8,7 +8,7 @@ pytest.importorskip("strictyaml") from ymf import closure # noqa: E402 -from ymf.archive import add_uniform_step, data_item, geometry, new_domain, topology # noqa: E402 +from ymf.archive import add_uniform_step, data_item, geometry, new_approximation, topology # noqa: E402 from ymf.compose import YmfCompositionError, load_composed # noqa: E402 from ymf.state import STATES, YmfStateError, reached # noqa: E402 @@ -16,7 +16,7 @@ def _output(realization): - domain = new_domain() + domain = new_approximation() nodes = data_item([2, 2], values=[0.0, 0.0, 1.0, 1.0]) vertices = data_item([2], values=[0, 1], data_type="Int", precision=4) add_uniform_step(domain, 0.0, topology("Polyvertex", 2, vertices, nodes_per_element=1), diff --git a/tests/test_symbolic.py b/tests/test_symbolic.py index 5f62e9d..bb0386a 100644 --- a/tests/test_symbolic.py +++ b/tests/test_symbolic.py @@ -331,3 +331,74 @@ def test_strong_form_equations_are_what_adr_problem_classifies(): assert len(residuals) == 3 assert [e["component"] for e in adr_problem(doc)["adr"]["equations"]] == space.components assert to_notation(residuals[2]) == "∂v_0/∂x + ∂v_1/∂y" + + +# --- classify, directly, on a coupled system --------------------------------- +# +# adr_form exports plain data; classify is the step before it, still in sympy, +# and the one a model family (a level set advected by a flow, a density that +# depends on the level set) builds on. These pin down where each kind of +# coupling term lands, one scalar residual at a time. + + +def _classified(lines, unknowns, coefficients=None, dim=2, **kwargs): + from ymf.symbolic.adr import classify as classify_residual + space = Space(dim, unknowns, coefficients or {}) + residuals = [] + for line in lines: + residuals.extend(parse_equation(line, space)) + return space, [classify_residual(r, space, **kwargs) for r in residuals] + + +def _symbols(space): + """The space's own symbols, by component name (they carry assumptions, + so a bare sympy.Symbol of the same name is a different symbol).""" + return dict(zip(space.components, space.component_symbols)) + + +def test_classify_keys_cross_diffusion_by_the_other_unknown(): + """-div(phi grad phi) in u's equation is diffusion of phi, not of u.""" + space, (eq_u, eq_phi) = _classified( + ["dt(u) - div(k*grad(u)) - div(phi*grad(phi)) + u*phi = 0", + "dt(phi) + div(phi*(u, 0)) = 0"], + {"u": 0, "phi": 0}, {"k": 2.0}) + u, phi = _symbols(space)["u"], _symbols(space)["phi"] + assert eq_u.mass == u + assert set(eq_u.diffusion) == {"u", "phi"} + assert eq_u.diffusion["u"] == 2.0 * sympy.eye(2) + assert eq_u.diffusion["phi"] == phi * sympy.eye(2) + assert sympy.simplify(eq_u.reaction - u * phi) == 0 + assert eq_u.advection == [0, 0] and eq_u.hamiltonian == 0 + # phi advected by a flux that depends on u: advection, nothing else + assert eq_phi.mass == phi + assert eq_phi.advection == [phi * u, 0] + assert eq_phi.diffusion == {} and eq_phi.reaction == 0 and eq_phi.hamiltonian == 0 + + +def test_classify_puts_a_nonlinear_gradient_term_in_the_hamiltonian(): + """|grad phi|^2 is not a divergence: it cannot be a flux.""" + space, (eq,) = _classified(["dt(phi) + dx(phi)**2 + dy(phi)**2 = 1"], {"phi": 0}) + assert eq.mass == _symbols(space)["phi"] + assert eq.advection == [0, 0] and eq.diffusion == {} + assert eq.reaction == -1 + assert eq.hamiltonian != 0 + + +def test_classify_moves_a_named_gradient_from_the_flux_to_the_hamiltonian(): + """grad(p) is div(p I) or H = dp/dx_j: one strong form, two weak forms.""" + lines = ["rho*dt(v) + div(rho*outer(v, v)) - div(mu*grad(v)) + grad(p) = 0"] + unknowns, coefficients = {"v": 1, "p": 0}, {"rho": 1.0, "mu": 1.0} + space, as_flux = _classified(lines, unknowns, coefficients) + _, as_h = _classified(lines, unknowns, coefficients, hamiltonian_gradients=("p",)) + p = _symbols(space)["p"] + for axis, (flux, h) in enumerate(zip(as_flux, as_h)): + assert flux.advection[axis].has(p) and flux.hamiltonian == 0 + assert not any(f.has(p) for f in h.advection) + assert h.hamiltonian.has(p) + + +def test_classify_refuses_a_name_that_is_not_declared(): + from ymf.symbolic.adr import classify as classify_residual + space = Space(2, {"u": 0}, {}) + with pytest.raises(SymbolicError, match="undefined names q"): + classify_residual(sympy.Symbol("q") * _symbols(space)["u"], space) diff --git a/tests/test_units.py b/tests/test_units.py index f68ee2f..1a0ce50 100644 --- a/tests/test_units.py +++ b/tests/test_units.py @@ -1,4 +1,8 @@ +import importlib.util import math +import sys +from pathlib import Path + import pytest # The YMF core deliberately depends on pyyaml alone, so a solver writing @@ -209,13 +213,18 @@ def test_compute_dimensionless_numbers_uses_validated_coefficients(coefficients_ # Regression: coefficients are MapPattern(Str(), Any()) in the schema, so # strictyaml returns '1.0e-3' (a string) and formulas referencing kappa # used to be silently dropped. + pytest.importorskip("strictyaml") from ymf import validate_ymf doc = validate_ymf(_heat_doc_with_numbers(coefficients_yaml)) numbers = compute_dimensionless_numbers(doc["model"]) assert numbers["Peclet"] == pytest.approx(0.5 * 1.0 / 1.0e-3) - # the time scale is derived, 1/(2π²κ), so κ·time/L² is 1/(2π²) exactly - assert numbers["Fourier"] == pytest.approx(1.0 / (2.0 * math.pi ** 2)) + # the time scale is derived, 1/(2π²κ), so κ·time/L² is 1/(2π²) exactly; + # that formula is in the spec notation, which only ymf[symbolic] reads + if importlib.util.find_spec("sympy") is None: + assert "Fourier" not in numbers + else: + assert numbers["Fourier"] == pytest.approx(1.0 / (2.0 * math.pi ** 2)) def test_an_expression_coefficient_resolves_but_a_non_number_still_does_not(): @@ -225,6 +234,7 @@ def test_an_expression_coefficient_resolves_but_a_non_number_still_does_not(): expression-valued coefficient went silently missing while adr_problem resolved the same coefficient without difficulty. """ + pytest.importorskip("sympy") # evaluating "π²" is ymf.symbolic's job problem = { "characteristic_scales": {"length": {"value": 1.0, "units": "m"}}, "strong_form": {"coefficients": {"Q": "π²", "k": "nan", "flag": True}}, @@ -240,12 +250,13 @@ def test_an_expression_coefficient_resolves_but_a_non_number_still_does_not(): def test_units_and_the_solver_agree_on_a_coefficient(): """One spec, one answer -- the reason sympy is in the frontend extra.""" + pytest.importorskip("strictyaml") + pytest.importorskip("sympy") from ymf import load_ymf from ymf.symbolic.problem import coefficient_numbers from ymf.units import _coefficient_values - pytest.importorskip("sympy") - problem = load_ymf("examples/kovasznay_flow.ymf")["model"] + problem = load_ymf(Path(__file__).parent.parent / "examples" / "kovasznay_flow.ymf")["model"] by_units = _coefficient_values(problem) by_solver = coefficient_numbers(problem["strong_form"]["coefficients"]) assert by_units == by_solver @@ -573,3 +584,55 @@ def test_checking_twice_reuses_the_stand_in_units(): doc = _conduction({"type": "neumann", "value": 1.0}, unknown_units=None) first = [str(i) for i in check(doc, missing_units="warn")] assert first == [str(i) for i in check(doc, missing_units="warn")] + + +# --------------------------------------------------------------------------- +# a bare ymf[units] install, without ymf[symbolic] +# --------------------------------------------------------------------------- + + +def _without_symbolic(monkeypatch): + """Make sympy and ymf.symbolic unimportable for the rest of the test. + + The units-only CI leg runs this for real; here it runs in the full + environment too, so the fallback is guarded wherever the suite runs. + """ + for name in list(sys.modules): + if name in ("sympy", "ymf.symbolic") or name.startswith(("sympy.", "ymf.symbolic.")): + monkeypatch.delitem(sys.modules, name) + monkeypatch.setitem(sys.modules, "sympy", None) + monkeypatch.setitem(sys.modules, "ymf.symbolic", None) + + +def test_without_symbolic_numbers_resolve_and_expressions_are_left_out(monkeypatch): + """What problem-specification.md promises a bare ymf[units] install: + it still sees the coefficients that are already numbers.""" + _without_symbolic(monkeypatch) + problem = { + "characteristic_scales": {"length": {"value": 2.0, "units": "m"}}, + "strong_form": {"coefficients": {"k": 3.0, "c": {"value": "0.5"}, "Q": "π²"}}, + "dimensionless_numbers": { + "A": {"formula": "k * L"}, # a number: resolves + "B": {"formula": "c * L"}, # a quoted number: resolves + "C": {"formula": "Q * L"}, # an expression coefficient: left out + "D": {"formula": "2πL"}, # the spec notation: left out + }, + } + assert compute_dimensionless_numbers(problem) == { + "A": pytest.approx(6.0), "B": pytest.approx(1.0)} + + +def test_without_symbolic_a_flux_condition_is_undecided_not_wrong(monkeypatch): + """A neumann g is compared with [k][T]/[L], which needs the equation read: + without ymf[symbolic] the check says it did not check, and does not fail + a condition that may well be right.""" + _without_symbolic(monkeypatch) + bc = {"type": "neumann", "value": 5.0, "units": "W/m**2"} + assert check(_conduction(bc)).ok # skip: nothing to report + strict = check(_conduction(bc), missing_units="error") + assert not strict.ok + assert all("not checked" in e for e in _errors(strict)) + assert any("ymf[symbolic]" in e for e in _errors(strict)) + # a dirichlet condition needs no equation, so it is still decided + assert check(_conduction({"type": "dirichlet", "value": 300.0, "units": "K"}), + missing_units="error").ok diff --git a/tests/test_values.py b/tests/test_values.py index b11fa43..ebacef5 100644 --- a/tests/test_values.py +++ b/tests/test_values.py @@ -15,9 +15,10 @@ import pytest +strictyaml = pytest.importorskip("strictyaml") + from ymf import load_ymf -strictyaml = pytest.importorskip("strictyaml") SPEC = """\ diff --git a/tests/test_xdmf.py b/tests/test_xdmf.py index f25aa05..bde937e 100644 --- a/tests/test_xdmf.py +++ b/tests/test_xdmf.py @@ -4,7 +4,7 @@ from ymf.xdmf import ( build_xdmf_tree, - canonicalize_domain, + canonicalize_approximation, parse_xdmf_domain, parse_xdmf_extra, read_xdmf, @@ -88,26 +88,26 @@ def test_build_xdmf_tree_basic_structure(): def test_domain_round_trips_via_parse_xdmf_domain(): tree = build_xdmf_tree(SAMPLE_DOMAIN) parsed = parse_xdmf_domain(tree.getroot()) - assert parsed == canonicalize_domain(SAMPLE_DOMAIN) + assert parsed == canonicalize_approximation(SAMPLE_DOMAIN) def test_write_then_read_xdmf_domain_only(tmp_path): path = tmp_path / "test.xmf" write_xdmf(SAMPLE_DOMAIN, path) domain, ymf_extra = read_xdmf(path) - assert domain == canonicalize_domain(SAMPLE_DOMAIN) + assert domain == canonicalize_approximation(SAMPLE_DOMAIN) assert ymf_extra is None def test_canonicalize_domain_is_idempotent(): - once = canonicalize_domain(SAMPLE_DOMAIN) - twice = canonicalize_domain(once) + once = canonicalize_approximation(SAMPLE_DOMAIN) + twice = canonicalize_approximation(once) assert once == twice def test_canonicalize_domain_fills_precision_default(): # SAMPLE_DOMAIN's Topology DataItem has no explicit Precision. - canonical = canonicalize_domain(SAMPLE_DOMAIN) + canonical = canonicalize_approximation(SAMPLE_DOMAIN) topo_data_item = time_collections(canonical)[0]["data"][0]["topology"]["data_item"] assert topo_data_item["precision"] == 4 # XDMF default for Int @@ -176,7 +176,7 @@ def test_write_then_read_xdmf_with_ymf_extra(tmp_path): path = tmp_path / "test.xmf" write_xdmf(SAMPLE_DOMAIN, path, ymf_extra=SAMPLE_YMF_EXTRA) domain, ymf_extra = read_xdmf(path) - assert domain == canonicalize_domain(SAMPLE_DOMAIN) + assert domain == canonicalize_approximation(SAMPLE_DOMAIN) assert ymf_extra == SAMPLE_YMF_EXTRA @@ -222,8 +222,9 @@ def test_ymf_extra_with_special_xml_chars_survives_round_trip(tmp_path): def test_full_notebook_example_round_trips(tmp_path): - """End-to-end: the same Problem doc used in YMF-updated.ipynb, plus the + """End-to-end: the same spec used in YMF-updated.ipynb, plus the mesh archive, written and read back through write_xdmf/read_xdmf.""" + pytest.importorskip("strictyaml") from ymf import validate_ymf poisson_problem_yaml = """ @@ -237,8 +238,7 @@ def test_full_notebook_example_round_trips(tmp_path): provenance: llm_derived unknowns: [u] equation_formulation: "Poisson" - strong_form_expression: | - Delta u = f + equations: ["−Δu = f in Ω"] domain: | unit cube [0,1]^3 boundary_regions: @@ -264,7 +264,7 @@ def test_full_notebook_example_round_trips(tmp_path): write_xdmf(SAMPLE_DOMAIN, path, ymf_extra=problem_doc) domain, ymf_extra = read_xdmf(path) - assert domain == canonicalize_domain(SAMPLE_DOMAIN) + assert domain == canonicalize_approximation(SAMPLE_DOMAIN) assert ymf_extra == problem_doc assert ymf_extra["model"]["name"] == "Poisson 3D (unit cube, tetrahedral mesh)" @@ -283,13 +283,13 @@ def test_full_notebook_example_round_trips(tmp_path): data_item, geometry, grid, - new_domain, + new_approximation, topology, ) def _uniform_with_attributes(): - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") add_uniform_step( domain, 0.0, @@ -313,7 +313,7 @@ def _uniform_with_attributes(): def _spatial(n_ranks=3): - domain = new_domain("Mesh Spatial_Domain") + domain = new_approximation("Mesh Spatial_Domain") grids = [ grid( topology("Triangle", 10 + r, data_item([10 + r, 3], f"out.h5:/e_p{r}", data_type="Int")), @@ -341,7 +341,7 @@ def test_attributes_are_written_as_xdmf_attribute_elements(): def test_attributes_round_trip(): domain = _uniform_with_attributes() - assert parse_xdmf_domain(build_xdmf_tree(domain).getroot()) == canonicalize_domain(domain) + assert parse_xdmf_domain(build_xdmf_tree(domain).getroot()) == canonicalize_approximation(domain) def test_attributes_round_trip_through_a_file(): @@ -366,7 +366,7 @@ def test_spatial_collection_is_written_as_a_nested_collection_grid(): def test_spatial_collection_round_trips(): domain = _spatial() - assert parse_xdmf_domain(build_xdmf_tree(domain).getroot()) == canonicalize_domain(domain) + assert parse_xdmf_domain(build_xdmf_tree(domain).getroot()) == canonicalize_approximation(domain) def test_spatial_collection_round_trips_through_a_file(): @@ -374,7 +374,7 @@ def test_spatial_collection_round_trips_through_a_file(): def test_nodes_per_element_is_written_and_round_trips(): - domain = new_domain() + domain = new_approximation() add_uniform_step( domain, 0.0, @@ -384,11 +384,11 @@ def test_nodes_per_element_is_written_and_round_trips(): root = build_xdmf_tree(domain).getroot() topo_elem = root.find("Domain").find("Grid").find("Grid").find("Topology") assert topo_elem.attrib["NodesPerElement"] == "2" - assert parse_xdmf_domain(root) == canonicalize_domain(domain) + assert parse_xdmf_domain(root) == canonicalize_approximation(domain) def test_absent_nodes_per_element_stays_absent(): - domain = new_domain() + domain = new_approximation() add_uniform_step( domain, 0.0, @@ -402,7 +402,7 @@ def test_absent_nodes_per_element_stays_absent(): def _text_include_domain(): - domain = new_domain() + domain = new_approximation() add_uniform_step( domain, 0.0, @@ -450,7 +450,7 @@ def test_each_text_include_attaches_to_its_own_data_item(): def test_text_include_data_items_round_trip(): domain = _text_include_domain() - assert parse_xdmf_domain(build_xdmf_tree(domain).getroot()) == canonicalize_domain(domain) + assert parse_xdmf_domain(build_xdmf_tree(domain).getroot()) == canonicalize_approximation(domain) def test_text_include_round_trips_through_a_file(): @@ -458,7 +458,7 @@ def test_text_include_round_trips_through_a_file(): def test_mixed_hdf_and_text_data_items_in_one_grid_round_trip(): - domain = new_domain() + domain = new_approximation() add_uniform_step( domain, 0.0, @@ -476,7 +476,7 @@ def test_mixed_hdf_and_text_data_items_in_one_grid_round_trip(): from xml.etree.ElementTree import fromstring -from ymf.archive import YmfArchiveError, validate_domain +from ymf.archive import YmfArchiveError, validate_approximation #: An XDMF 3 file in the most basic layout: one uniform grid directly in the #: Domain, XDMF 3 attribute names, HDF5 data. @@ -527,7 +527,7 @@ def test_a_bare_uniform_grid_reads_as_a_one_step_collection(tmp_path): # XDMF defaults: Scalar, Float assert step["attributes"][0]["attribute_type"] == "Scalar" assert step["attributes"][0]["data_item"]["data_type"] == "Float" - validate_domain(domain) + validate_approximation(domain) def test_a_bare_uniform_grid_keeps_its_time(): @@ -540,7 +540,7 @@ def test_unnamed_top_level_grids_are_numbered_so_names_stay_unique(): "" + TRIANGLE + XYZ + "", "" + TRIANGLE + XYZ + "") domain = _read(text) assert [c["name"] for c in time_collections(domain)] == ["Grid 0", "Grid 1"] - validate_domain(domain) + validate_approximation(domain) def test_a_top_level_spatial_collection_reads_as_one_spatial_step(): @@ -591,7 +591,7 @@ def test_inline_values_must_be_numbers_of_the_declared_type(): def test_a_self_contained_domain_round_trips_through_xmf_exactly(): from ymf.archive import data_item as di - domain = new_domain("mesh") + domain = new_approximation("mesh") add_uniform_step( domain, 0.5, topology("Triangle", 2, di([2, 3], values=[[0, 1, 3], [0, 3, 2]], data_type="Int")), @@ -605,7 +605,7 @@ def test_a_self_contained_domain_round_trips_through_xmf_exactly(): def test_inline_values_are_written_as_rows(tmp_path): from ymf.archive import data_item as di - domain = new_domain("mesh") + domain = new_approximation("mesh") add_uniform_step( domain, 0.0, topology("Triangle", 2, di([2, 3], values=[0, 1, 3, 0, 3, 2], data_type="Int")),