Skip to content
Merged
19 changes: 19 additions & 0 deletions docs/changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,25 @@ rediscover why a thing is the way it is. Open gaps are in

## 2026-11

- **2026-11-08: C42 round 3, the words a dispatcher maps (C5 decisions
16, 18-21 of 2026-11-06).** proteus's DispatchTable coined the labels it
matched on; they are `ymf.vocabulary` now, stated by the spec, checked on
load, and the derived ones (a model's `family`, each sub-problem's
`role`) written by closure without counting towards a key. Renamed where
ymf had a better word, the old one kept as an alias: `vbdf` -> `bdf2`,
`SSP_RK3` -> `ssp_rk3`, `shock_capturing` -> `residual_shock_capturing`,
`pressure_initial` -> `pressure_spin_up`, `entropy_viscosity_cE` ->
`entropy_viscosity_coefficient`. Coefficients carry a `role` (`density`,
`gravity`, `bed_elevation`, ...), so a solver stops looking them up by
name. `linear_solver: direct | iterative`, shared by every solver path. A
condition on a phase indicator no sub-problem carries (χ with no VOF) is a
condition on its level set's sign, so CLSVOF gets the atmosphere's air
inflow. Three fixes: an archive's spec part reads back as written (`1.0e6`
had come back `'1000000.0'`, another input digest: `--check` broke); a
power of a sum keeps its decimals on sympy 1.13 (`(x − 47.5)²` had become
`2256.25 (0.0210526 x − 1)²`); `extends` pairs `initial_conditions` by
`field`.

- **2026-11-06: `hypot(a, b)` in the notation.** C5 step 2 (proteus runs a
split discretization from the spec and compares it bitwise with the deck):
the dam break's initial signed distance written `sqrt(max(x − 1.2, 0)² +
Expand Down
97 changes: 93 additions & 4 deletions docs/problem-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,8 @@ may be omitted when the document has only one — see
`fields`, or `velocity` and `pressure` for mixed problems, each as
`{family: CG|DG|RT|BDM|RTF|N1curl, order: n}`. The `solver` block takes
`type` (`linear | nonlinear | time_marching | saddle_point`),
`linear_solver` (`petsc | mumps | umfpack | superlu`), `petsc_options`,
`linear_solver` (`direct | iterative`, or a package: `petsc | mumps | umfpack
| superlu`), `petsc_options`,
`nonlinear_solver` (`newton | broyden | line_search`), `tolerance` and
`max_iterations`. `petsc_options` are PETSc options without the leading
dash, as strings (`{ksp_type: cg, pc_type: gamg, ksp_rtol: "1e-10"}`; an
Expand All @@ -243,6 +244,15 @@ serial LU, `mumps` a direct solve through PETSc, and `petsc` a PETSc
Krylov solve set by `petsc_options` (PETSc's defaults without them);
`umfpack` is refused, as it has no Proteus solver. Omitted, Proteus picks
its serial LU, or MUMPS when the operator has a null space.
`direct` and `iterative` say what is asked of the linear solve rather than
which package does it: a direct factorization (serial or distributed, the
solver's choice), or a Krylov method with a preconditioner that
`petsc_options` refine. Every solver path of a solver reads the same two
words and maps them to its own options, and refuses what it cannot honour
instead of overriding the spec. A package name is a request of its kind
(`superlu`, `mumps` and `umfpack` direct; `petsc` iterative, unless
`petsc_options` give `pc_type: lu` or `cholesky` with `ksp_type: preonly`):
`ymf.vocabulary.linear_solver_kind` says which.
`mesh: {cells, levels}` gives the meshes: cells along each side of the
domain's box, and levels of uniform refinement (the solution is on the
finest). A region that is not a box (`kind: piecewise_linear`) gives
Expand Down Expand Up @@ -364,6 +374,18 @@ solution_paths:
| `y = 0 or x = 0 and y = H` | a boundary region; `∂Ω` is the whole boundary |
| `Ω = [a, b] × [c, d], t ∈ (t0, t1]` | the domain, a box, and the time interval of a transient problem |

**Decimals are kept as written.** A numeral is an IEEE double, and a
formula that must match code computing the same thing should compute it the
same way. sympy before 1.14 rewrites a power of a sum with a decimal in it
by factoring out the largest coefficient (`(x − 47.5)²` as
`2256.25 (0.0210526 x − 1)²`, `sqrt` of a sum of such squares as `47.5
sqrt(...)`): the same number, other arithmetic. The notation builds such a
power as written, so `sqrt((x − 47.5)² + (y − 15)²)` prints as itself
whichever sympy runs (Proteus pins 1.13). What sympy derives from it later,
a derivative in an ADR form for example, it evaluates itself, so on sympy
1.13 a derivative of such a power may still be factored; a spec that needs
those bitwise as well writes the decimal as a ratio (`95/2`).

Names are the coordinates `x y z`, time `t`, `π`, the unknowns and the
coefficients. A coefficient may be any name, Greek or not (`κ`, `ρ`, `μ`,
`G`), and a coefficient's value may itself be a formula in the others and
Expand Down Expand Up @@ -843,8 +865,71 @@ regularizations it used, an introduced unknown's initial condition, its
effective solver, and its **boundary conditions**: those on the unknowns it
solves for, and those on a coefficient its introduced unknown carries
(atmosphere's `χ` inflow is VOF's `χh` inflow), with condition sets
expanded. A condition on a field a sub-problem only reads is another's. A solver maps a sub-problem onto its own modules (a
dispatcher); `proteus:` blocks are interim hints for it, carried as text.
expanded. A condition on a field a sub-problem only reads is another's.
A condition on a **phase indicator no sub-problem carries** (`χ :=
heaviside(φ)` with no VOF, as when CLSVOF solves the level set alone) is a
condition on the sign of the level set, given to the sub-problem that
solves it: `heaviside(φ) = 1` says `φ > 0` and no more. Its entry has
`variable: φ`, `sign` (`1` for χ = 1, `-1` for 0, `0` for 1/2), the
indicator's own `{variable, value}` and no `value`; a solver that imposes a
Dirichlet value picks one with that sign. So the atmosphere's `χ` inflow
of 1 (what enters is air) is VOF's `χh` inflow in `level_set_five` and the
positive `φ` inflow of CLSVOF in `level_set_clsvof`
([`dambreak_clsvof.ymf`](../tests/fixtures/two_phase/dambreak_clsvof.ymf)).
Anything else on such an indicator (a formula, another value) is refused.
A solver maps a sub-problem onto its own modules (a dispatcher); `proteus:`
blocks are interim hints for it, carried as text.

### The words a dispatcher maps

A solver's dispatcher maps the spec onto its modules by the words the spec
states, and those words are ymf's ([`ymf.vocabulary`](../src/ymf/vocabulary.py)),
checked on load, so that a second solver reads the same ones:

| kind | words |
|---|---|
| model family (`physical_model.family`) | `two_phase_level_set`, `shallow_water`, `dispersive_shallow_water` |
| sub-problem role (`role`) | two-phase: `velocity_pressure`, `velocity`, `pressure_increment`, `pressure`, `pressure_spin_up`, `volume_fraction`, `level_set`, `level_set_redistanced`, `redistancing`, `mass_correction`; shallow water: `shallow_water` |
| `time_integration` | `backward_euler`, `bdf2`, `ssp_rk3`, `none` |
| `stabilization.method` | `ASGS`, `SUPG`, `residual_shock_capturing`, `entropy_viscosity`, `graph_viscosity_smoothness`, `graph_viscosity_entropy_residual` |
| `discretization.scheme` and its options | `graph_viscosity_convex_limiting`: `entropy_viscosity_coefficient`, `lumped_mass`, `bounds_relaxation` (and `time_integration`, `outputs`, `dt` for every scheme) |
| `step_control.type` | `min_cfl`, `fixed` |
| `regularize.*.by` | `smoothed_heaviside`, `smoothed_sign`, `wet_dry_cutoff` |
| `binds.*.meaning` | `element_size`, `dry_depth` |
| `writes_back` | `replace`, `add`, `mass_quadrature` |
| `linear_solver` | `direct`, `iterative`; `superlu`, `mumps`, `umfpack`, `petsc` |
| coefficient `role` | `density`, `dynamic_viscosity`, `kinematic_viscosity`, `gravity`, `phase_indicator`, `surface_tension`, `bed_elevation`, `manning_coefficient`, `porosity`, `linear_drag`, `quadratic_drag`, `bed_friction`, `canopy_drag`, `diffusivity` |

A family is identified by the processes and assumptions of
`physical_model` (two-phase: `incompressible_flow`, `two_phase_flow`,
`interface_transport`; shallow water: `hydrostatic`, `depth_averaged`,
`nondispersive`; dispersive: `depth_averaged`, `dispersive`). A role is
read from the sub-problem's structure: what it solves (the unknowns its
equations are for), enforces, introduces and spins up. Both may be stated
(`family:`, `role:`), and are then checked against what the model and the
structure say; a closed spec writes both out (`ymf.explicit`), and neither
counts towards an output's key, since each follows from what does.

A **coefficient role** says what a coefficient means whatever the model
calls it: `ρ: {formula: "ρw (1 − χ) + ρa χ", units: kg/m3, role: density}`.
A solver that needs the density, the gravity or the bed finds it by its
role (`ymf.vocabulary.coefficient_by_role(doc, "density")`), not by the
name the family file happens to use. A role is used by one coefficient of
a model, and `ymf.units.check` refuses units of another dimension than the
role's.

Some words were first the dispatch table's, named after a solver's class
or flag; ymf's word replaces them and the old one is still read as an
alias (`ymf.vocabulary.ALIASES`, `canonical`): `vbdf` is `bdf2`, `SSP_RK3`
is `ssp_rk3`, `shock_capturing` (the method) is `residual_shock_capturing`,
`pressure_initial` is `pressure_spin_up`, `entropy_viscosity_cE` is
`entropy_viscosity_coefficient`, and the coefficient roles `mannings`,
`bathymetry`, `drag_alpha`, `drag_beta` are `manning_coefficient`,
`bed_elevation`, `linear_drag`, `quadratic_drag`. A spec using an alias
loads, and is not rewritten: a reader keyed on the old word keeps working
until it maps the new one. `dispersive_shallow_water` was identified by
the assumption `hyperbolic_relaxation`, which is how GN_SW2DCV discretizes
the model, not an assumption of it; that is still recognized.

## Document state

Expand Down Expand Up @@ -949,7 +1034,11 @@ solution_paths: {...}

**Merge rules.** Mappings merge key by key. Lists of entries with a
`label` or `name` (unknowns, weak forms, discretizations, boundary regions)
merge entry by entry on it, and new entries are appended. Lists of strings
merge entry by entry on it, and new entries are appended. Initial
conditions pair up by `field`: an extending file that states the initial
condition of one field replaces that entry whole (its type and value go
together) and leaves the others as inherited, and `remove:` can name one
(`model.strong_form.initial_conditions[φ]`). Lists of strings
(`processes`, `assumptions`) are unioned. Anything else the child sets
replaces the parent's value. Every file in a chain is checked against the
partial schema as it is read, so an error is reported against the file and
Expand Down
42 changes: 38 additions & 4 deletions src/ymf/compose.py
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,13 @@ def _refuse_old_kind(text: str, path: Path) -> None:
"'ymf_state: abstract' for 'kind: model', and drop 'kind: problem' "
"(or write 'ymf_state: well-posed'). See ymf.state." % (path,))
#: Keys that identify an entry in a list of mappings, in order of preference.
_IDENTITY_KEYS = ("label", "name")
_IDENTITY_KEYS = ("label", "name", "field")

#: identity keys whose entries an extending file replaces whole rather than
#: merges key by key: an initial condition is one statement, and merging
#: {type: function, formula} onto {type: constant, value} would keep a value
#: that no longer means anything
_REPLACED_WHOLE = ("field",)


class YmfCompositionError(ValueError):
Expand Down Expand Up @@ -257,7 +263,14 @@ def _merge(parent: Any, child: Any, path: str, source: str,
key = _identity(entry)[1]
where = "%s[%s]" % (path, key)
_note_writer(provenance, where, source)
if key in index:
if key in index and _identity(entry)[0] in _REPLACED_WHOLE:
i = index[key]
if parent[i] != entry:
overrides.append({"path": where, "was": parent[i], "now": entry,
"set_by": source})
merged[i] = entry
_record_paths(entry, where, source, provenance)
elif key in index:
i = index[key]
merged[i] = _merge(parent[i], entry, where, source,
overrides, provenance)
Expand Down Expand Up @@ -404,6 +417,20 @@ def _read_text(path: Path) -> str:
return text


_OUTPUTS_LINE = re.compile(r"^outputs:", re.M)


def _as_written(text: str) -> Dict[str, Any]:
"""An archive's mappings and lists with every scalar the string it is
written as (pyyaml's base loader), up to its top-level ``outputs:``: the
writer puts them last, and they hold the arrays."""
m = _OUTPUTS_LINE.search(text)
head = text[:m.start()] if m else text
loader = getattr(yaml, "CBaseLoader", yaml.BaseLoader)
data = yaml.load(head, Loader=loader)
return data if isinstance(data, dict) else {}


def _read(path: Path) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
"""Validate one file against the partial schema; return (data, outputs).

Expand All @@ -421,8 +448,15 @@ def _read(path: Path) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
document = read_document(path)
outputs = document.pop("outputs", None)
document.pop("ymf", None)
spec_text = _dump(document, allow_unicode=True, sort_keys=False,
default_flow_style=False, width=1000)
# The specification part as written, every scalar a string: strictyaml
# types what the schema types, and a free-form (Any) value stays the text
# it was in the spec. Re-dumping pyyaml's typed values instead gave
# "1.0e6" back as "1000000.0", another input digest (C5 finding Y1).
spec_part = _as_written(text)
spec_part.pop("ymf", None)
spec_part.pop("outputs", None)
spec_text = _dump(spec_part, allow_unicode=True, sort_keys=False,
default_flow_style=False, width=1000)
data = strictyaml.dirty_load(spec_text, PARTIAL_YMF_SCHEMA, label=str(path),
allow_flow_style=_ALLOW_FLOW_STYLE).data
if "composition" in document:
Expand Down
61 changes: 57 additions & 4 deletions src/ymf/explicit.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,11 @@
refined by its own), its regularization (the entry's, function by
function replaced by its own), and each lag as ``{at, via, of,
carried_by}``, where ``carried_by`` names the introduced unknown that
carries a lagged coefficient (``χ`` via VOF is read as ``χh``).
carries a lagged coefficient (``χ`` via VOF is read as ``χh``);
* the model's **family** (``physical_model.family``) when its processes and
assumptions identify one, and each sub-problem's **role** in it
(ymf.vocabulary), so a dispatcher maps the words the spec states instead
of reading them off the structure itself.

Applying it twice changes nothing, and a spec with none of the shorthand
(no aliases, no coefficients of the state, no sub-problems) is returned
Expand All @@ -42,6 +46,11 @@
#: do not count towards an output's key (ymf.closure.input_slice)
DERIVED_KEYS = ("depends_on",)

#: the same, on a sub-problem; and the model's family when its processes and
#: assumptions identify exactly one (a family stated to choose between
#: several is input)
DERIVED_SUBPROBLEM_KEYS = ("role",)


def _strong(doc: Dict[str, Any]) -> Dict[str, Any]:
return ((doc.get("model") or {}).get("strong_form") or {})
Expand Down Expand Up @@ -142,19 +151,63 @@ def explicit(doc: Dict[str, Any]) -> Dict[str, Any]:
paths["discretizations"] = [split_out(e) if isinstance(e, dict) else e
for e in entries]
doc["solution_paths"] = paths
return _name_roles(doc)


def _name_roles(doc: Dict[str, Any]) -> Dict[str, Any]:
"""The model's family and each sub-problem's role, written out."""
from ymf.vocabulary import VocabularyError, family_of, role_of
try:
family = family_of(doc)
except VocabularyError:
return doc # several: refused on load, or stated
if family is None:
return doc
doc = dict(doc)
model = dict(doc["model"])
model["physical_model"] = dict(model.get("physical_model") or {}, family=family)
doc["model"] = model
entries = (doc.get("solution_paths") or {}).get("discretizations") or []
if any(isinstance(e, dict) and e.get("subproblems") for e in entries):
out = []
for entry in entries:
if isinstance(entry, dict) and entry.get("subproblems"):
entry = dict(entry)
subs = []
for sub in entry["subproblems"]:
role = role_of(sub, doc, family)
subs.append(dict(sub, role=role) if role else sub)
entry["subproblems"] = subs
out.append(entry)
doc["solution_paths"] = dict(doc["solution_paths"], discretizations=out)
return doc


def without_derived(doc: Dict[str, Any]) -> Dict[str, Any]:
"""``doc`` with the keys :func:`explicit` derives from the rest removed."""
from ymf.vocabulary import families_of
strong = _strong(doc)
coefficients = strong.get("coefficients") or {}
if not any(isinstance(e, dict) and any(k in e for k in DERIVED_KEYS)
for e in coefficients.values()):
physical = (doc.get("model") or {}).get("physical_model") or {}
family = physical.get("family") is not None and len(families_of(doc)) == 1
entries = (doc.get("solution_paths") or {}).get("discretizations") or []
roles = any(isinstance(s, dict) and any(k in s for k in DERIVED_SUBPROBLEM_KEYS)
for e in entries if isinstance(e, dict) for s in e.get("subproblems") or [])
if not family and not roles and not any(
isinstance(e, dict) and any(k in e for k in DERIVED_KEYS)
for e in coefficients.values()):
return doc
doc = copy.deepcopy(doc)
for entry in doc["model"]["strong_form"]["coefficients"].values():
for entry in ((doc["model"].get("strong_form") or {}).get("coefficients") or {}).values():
if isinstance(entry, dict):
for key in DERIVED_KEYS:
entry.pop(key, None)
if family:
doc["model"]["physical_model"].pop("family")
for entry in (doc.get("solution_paths") or {}).get("discretizations") or []:
if isinstance(entry, dict):
for sub in entry.get("subproblems") or []:
if isinstance(sub, dict):
for key in DERIVED_SUBPROBLEM_KEYS:
sub.pop(key, None)
return doc
5 changes: 5 additions & 0 deletions src/ymf/references.py
Original file line number Diff line number Diff line change
Expand Up @@ -463,6 +463,11 @@ def resolve(doc: Dict[str, Any]) -> None:
for entry in _paths(doc).get("discretizations") or []:
if isinstance(entry, dict):
_check_split(doc, entry)
from ymf.vocabulary import VocabularyError, check as check_vocabulary
try:
check_vocabulary(doc)
except VocabularyError as exc:
raise YmfReferenceError(str(exc)) from None
labels = weak_form_labels(doc)
discretizations = discretization_names(doc)

Expand Down
Loading
Loading