Skip to content

ymf C42 round 3: dispatch labels as ymf vocabulary, coefficient roles, linear_solver direct/iterative, φ inflow, three archive fixes (cekees/ymf#13) - #29

Merged
cekees merged 9 commits into
proteustoolkit:mainfrom
cekees:main
Nov 10, 2026

Conversation

@cekees

@cekees cekees commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

Round 3 of the ymf cleanup (C42): one reviewed PR from cekees/ymf (cekees#13), merged there commit by commit.

  • linear_solver: direct / iterative, shared by every solver path. Packages are requests of their kind (ymf.vocabulary.linear_solver_kind).
  • Vocabulary: the dispatch table's labels are ymf words, stated and checked: families, sub-problem roles, time integration, stabilization, schemes, step control, regularizations, binding meanings, inertia forms. Old words are accepted as aliases and not rewritten (vbdf→bdf2, SSP_RK3→ssp_rk3, shock_capturing→residual_shock_capturing, pressure_initial→pressure_spin_up, entropy_viscosity_cE→entropy_viscosity_coefficient).
  • Coefficient roles: a solver finds the density by its role, not its name; units are checked by ymf.units.
  • Phase indicator: a condition on an uncarried phase indicator is its level set's sign (CLSVOF gets the atmosphere's φ inflow).
  • Three fixes: an archive's spec part reads back as written (digest for a 1.0e6 hint is now the same both ways); a power of a sum keeps its decimals on sympy 1.13 and 1.14; extends pairs initial_conditions by field.
  • Docs: a docs/changes.md entry.

Proteus impact: none needed. With this branch on PYTHONPATH, proteus test/dispatch, test_pro_cli, test_domain_ymf and test_adr_problem gave 227 passed, 1 skipped, the same as with ymf main (the skip is argparse suggestions on Python below 3.14). That was on proteus main at 74d453d3; I haven't rerun it on current main.

Tests: ymf suite on macOS arm64: 959 passed, 2 skipped (sympy 1.14.0); 886 passed, 13 skipped (sympy 1.13.2). CI on the PR head passed on the legs I checked: Linux py3.10 to 3.14, aarch64, one extra per leg, and macOS Apple Silicon and Intel.

🤖 Generated with Claude Code

cekees and others added 9 commits November 8, 2026 04:27
C5 decision 19 (Q3): on proteus's TwoPhaseFlow path `superlu` means
useSuperlu (SuperLU serial, SuperLU_DIST parallel), SWFlow ignores the spec,
and the ADR path refuses superlu on > 1 rank. The spec now says what is asked
of the linear solve: `direct` (a factorization, the solver picks the package)
or `iterative` (Krylov + preconditioner, refined by petsc_options). Each path
maps the two words and refuses what it cannot honour. A package name is a
request of its kind: superlu, mumps, umfpack direct; petsc iterative unless
petsc_options give pc_type lu/cholesky with ksp_type preonly.

- schema: linear_solver takes direct, iterative (the packages stay).
- ymf.vocabulary (new): LINEAR_SOLVERS, linear_solver_kind.
- guide: the solver paragraph.

Measured (macOS arm64, petsc-dev env): ymf suite 866 -> 879 passed, 2
skipped (13 new in test_linear_solver). No spec changes meaning: the 17
examples and fixtures of main 3a3a061 plan the same output keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…cked

C5 decision 16 (F3): proteus's DispatchTable coined the words it matched
on: sub-problem roles, families, stabilization methods, time integration,
the SWE scheme. They live in ymf.vocabulary now; the spec states them, ymf
checks them on load (ymf.references), and the closed spec writes the
derived ones, so the table only maps them.

- FAMILIES + family_of: two_phase_level_set, shallow_water,
  dispersive_shallow_water. DSWE is identified by depth_averaged +
  dispersive; the table's `hyperbolic_relaxation` (GN_SW2DCV's
  discretization, not an assumption) is still recognized.
- ROLES + role_of: proteus's Dispatch.role_of rules, moved; `role:` on a
  sub-problem is checked against the structure. pressure_initial is
  pressure_spin_up (ymf's word is spin_up).
- TIME_INTEGRATION (backward_euler, bdf2, ssp_rk3, none), STABILIZATION
  (ASGS, SUPG, residual_shock_capturing, entropy_viscosity,
  graph_viscosity_smoothness, graph_viscosity_entropy_residual), SCHEMES
  (graph_viscosity_convex_limiting and its options), STEP_CONTROL,
  REGULARIZATIONS, BINDING_MEANINGS, WRITES_BACK, INERTIA_FORMS.
- Renamed, old word kept as an alias (ALIASES, canonical): vbdf -> bdf2,
  SSP_RK3 -> ssp_rk3, shock_capturing -> residual_shock_capturing,
  entropy_viscosity_cE -> entropy_viscosity_coefficient. Aliases are not
  rewritten on load or in the closed spec, so proteus's table keeps working
  until C5 step 3 maps the new words.
- schema: physical_model.family and a sub-problem's role (optional).
- explicit: the closed spec writes family and roles; without_derived drops
  them, so neither counts towards an output's key (stated or not).
- tests/fixtures/two_phase/dambreak_clsvof.ymf: RANS2P + CLSVOF.

Measured (petsc-dev): ymf suite 879 -> 930 passed, 2 skipped (51 new in
test_vocabulary, one per dispatch-table label among them). Main's 17
examples and fixtures, closed by main and by this branch: same output
keys, same closed spec without derived keys, same ADR and split plain data
(petsc-dev sympy 1.14 and proteus-bc-261025 sympy 1.13.2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
C5 decision 20 (Q4): proteus's realizer reads ρ, μ, g (two-phase) and g, n,
θ, α, β, Z (SWE) by name from the family file. A coefficient now states
what it means: `ρ: {formula: ..., role: density}`.

- ymf.vocabulary.COEFFICIENT_ROLES (density, dynamic_viscosity,
  kinematic_viscosity, gravity, phase_indicator, surface_tension,
  bed_elevation, manning_coefficient, porosity, linear_drag,
  quadratic_drag, bed_friction, canopy_drag, diffusivity), each with its SI
  dimension; coefficient_roles, coefficient_by_role. The table's
  mannings, bathymetry, drag_alpha, drag_beta are aliases.
- Checked on load: the role is known and used once per model.
  ymf.units.check refuses units of another dimension than the role's.
- Fixtures: the two-phase and shallow-water family files state their roles.

Measured (petsc-dev): ymf suite 930 -> 943 passed, 2 skipped. The two
family fixtures are new input (their keys change); main's specs without a
role close as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… sign

C5 decision 18 (Q2): with CLSVOF solving the level set alone (no VOF
carrying χ), split_problem dropped the atmosphere's χ inflow, the
two-condition signature matched no BC_RANS setter, and proteus refuses
level_set_clsvof there. ymf now states it: a condition on χ := heaviside(φ)
that no sub-problem carries goes to the sub-problem solving φ, as a
condition on φ's sign (heaviside(φ) = 1 says φ > 0 and no more):
{variable: φ, type: dirichlet, only: inflow, sign: 1,
 indicator: {variable: χ, value: 1.0}}, no value; a solver imposing one
picks it with that sign (Proteus's CLSVOF gets vof_air = 1). A formula or
a value other than 0, 1/2, 1 is refused.

Measured (petsc-dev): ymf suite 943 -> 949 passed, 2 skipped.
level_set_clsvof: clsvof gets φ inflow sign +1 on `top`, flow keeps p = 0
and the open velocity. level_set_five unchanged: VOF's χh inflow 1.0, ncls
and rdls none (as damBreakLevelSet.py). Proteus is unaffected until it maps
the new entry: its atmosphere signature still needs χ, so it keeps refusing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
C5 finding Y1: a free-form value `eb_penalty_constant: 1.0e6` under a
`proteus:` hint loads from the spec as '1.0e6'. The archive was read with
pyyaml (YAML 1.2 floats), re-dumped, and validated: '1000000.0'. Another
input digest, so `--check` found no record and planned a new output.
compose._read now reads an archive's specification part (up to the
top-level `outputs:`, which the writer puts last) with pyyaml's base loader,
every scalar the string it is written as, before strictyaml types it; the
typed read still supplies outputs and composition.

Measured: dambreak with hints {1.0e6, 1e-3, true, '0x10', 007}: input
digest ee257dfd -> cf8edbd4 across write+load before, 0848213f both ways
after, and the same after a second round trip. Typed values keep their
types. Archives already written with such a value now match their keys
again. ymf suite 949 -> 951 passed, 2 skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
C5 finding Y2: dam3bumps' bed `3 − 3 sqrt((x − 47.5)² + (y − 15)²)/10`
came out as `3 − 14.25 sqrt((0.0210526 x − 1)² + 0.000443 (y − 15)²)`.
Cause: sympy 1.13's Add._eval_power factors the largest coefficient out of
a power of a sum with any Float coefficient ((2.0 + 4x)**e -> 4**e (0.5 +
x)**e), so even (x − 47.5)² becomes 2256.25 (0.0210526 x − 1)². sympy 1.14
dropped it; proteus pins 1.13.2, so ymf cannot require 1.14. The notation
builds such a power unevaluated (sqrt, ², ^, norm), a no-op on 1.14.
Derivatives sympy takes later are its own; the guide says so (write 95/2
if those must match bitwise too).

Measured: Z of dam3bumps prints numpy.sqrt((x - 47.5)**2 + (y - 15)**2) on
sympy 1.13.2 and 1.14.0 (before: 14.25*sqrt(...) on 1.13.2). Main's 17
examples and fixtures: same ADR and split plain data on both. New test fails
4 of 6 on main's notation under 1.13.2, passes 6 of 6 here. ymf suite 951
-> 957 passed, 2 skipped (petsc-dev); 886 passed, 13 skipped under
proteus-bc-261025 (sympy 1.13.2, final branch).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
C5 finding Y3: an extending file's initial_conditions replaced the
parent's list whole, so dambreak_short.ymf restated all three to change φ.
initial_conditions now pair up by `field`: an entry for a field the parent
has replaces that entry whole (its type and value go together, so a
constant's value does not survive into a function), recorded as an
override; others are inherited in the parent's order; new ones are
appended; `remove: model.strong_form.initial_conditions[p]` works.

Measured: restating φ and p over dambreak.ymf gives [v, p, φ] with v
inherited (before: [φ, p]). Main's 17 examples and fixtures: same keys.
ymf suite 957 -> 959 passed, 2 skipped. proteus's dambreak_short.ymf, which
restates all three, composes as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The round's entry in docs/changes.md: the vocabulary, coefficient roles,
linear_solver direct/iterative, the uncarried phase indicator, and Y1-Y3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
C42 round 3: dispatch labels as ymf vocabulary, coefficient roles, linear_solver direct/iterative, φ inflow, Y1-Y3
@cekees
cekees merged commit 82b306a into proteustoolkit:main Nov 10, 2026
10 checks passed
cekees added a commit to cekees/proteus that referenced this pull request Nov 11, 2026
Step 2 wrote three decks around ymf defects that ymf round 3 fixed (proteustoolkit/ymf#29, items (e)).

* Y1 (dambreak.ymf): the hint `eb_penalty_constant: 1000000.0` is `1.0e6` again. ymf's archive writer used to turn a
  free-form `1.0e6` into '1000000.0', so reading an archive back gave another input digest and `--check` found no
  record.
* Y2 (dam3bumps.ymf): the bed's `95/2` is `47.5` again, with the comment that explained why it was not. On sympy
  1.13 a power of a sum with a decimal had its largest coefficient factored out (the same number, other
  arithmetic); ymf keeps the decimals now.
* Y3 (dambreak_short.ymf): `initial_conditions` of an `extends` pairs by `field`, so the short case restates φ0
  only (it restated v and p as well).

Evidence (macOS arm64, env proteus-bc-261025 with sympy 1.13.2, ymf main 82b306a, -n 4):
* dam3Bumps spec with 47.5 against dam3Bumps.py: every dataset bitwise equal on 1 and 2 ranks (test_dispatch_run.py);
  ymf's own measurement of Y2 on this sympy: 4 of 6 cases differ on the old notation, 6 of 6 agree with round 3.
* The archive rerun test (spec written, read back, rerun: "in the archive", `--check` reproduces bitwise) passes
  with `1.0e6` in the hints it hashes, which is what Y1 broke; dambreak_short.ymf and dambreak_short_clsvof.ymf
  run bitwise with φ0 as their only restated initial condition.
* test/dispatch: 65 passed, 1 failed on the first run and 66 passed on 4 later runs; the failure is the CLSVOF case on
  two ranks, which is not run-to-run reproducible with the deck alone (next commit).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
cekees added a commit to proteustoolkit/proteus that referenced this pull request Nov 11, 2026
The table coined its own words for what a spec says (vbdf, SSP_RK3, pressure_initial, shock_capturing as a
stabilization method, entropy_viscosity_cE, hyperbolic_relaxation); ymf round 3 (proteustoolkit/ymf#29) gives each a
word in ymf.vocabulary and keeps the old one as an alias.

* DispatchTable's cells are keyed on ymf's words: bdf2, ssp_rk3, pressure_spin_up, residual_shock_capturing,
  entropy_viscosity_coefficient. The table's own FAMILIES and ROLES are gone (ymf.vocabulary has them).
* Dispatch reads a spec's words through ymf.vocabulary.canonical (time integration, stabilization method, scheme
  name and options, binding meaning, step control type), so a spec that still says vbdf or SSP_RK3 dispatches as it
  did. A word ymf does not know is passed on and refused by the cell, with the message it had.
* family_of and role_of are ymf.vocabulary's (the same rules; a refusal is still a DispatchError with the table's
  message). The dispersive family is now `dispersive`, and `hyperbolic_relaxation` is still recognized.
* test/dispatch/*.ymf say bdf2, ssp_rk3, entropy_viscosity_coefficient.

Evidence (macOS arm64, env proteus-bc-261025, ymf main 82b306a with round 3, -n 4):
* 4 new tests (ymf words vs aliases dispatch alike: as_dict equal for the projection and the scheme block;
  `dispersive` and the older assumption; residual_shock_capturing and its alias = ARTIFICIAL_VISCOSITY 1) plus the
  dispersive test with the new assumption: 5 fail on the parent (DispatchError), 5 pass here.
* test/dispatch + test_pro_cli: 126 passed, 1 skipped, before (parent, ymf main) 32 + 94 as in the baseline run of
  test/dispatch (32 passed); the deck-vs-spec bitwise runs (damBreakLevelSet, dam3Bumps, 1 and 2 ranks) are
  unchanged.
* Decks changed: dambreak.ymf (vbdf -> bdf2), proteus_numerics.ymf (SSP_RK3 -> ssp_rk3,
  entropy_viscosity_cE -> entropy_viscosity_coefficient).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant