Address review of #32: shared recipe constants, assert_unit_consistency, units in the repr

[hdrake]

Addresses the five review comments on #32 (two GitHub, three ReviewNB). Targets
units-handling so it merges into that PR rather than main.

Review comment	Resolution
GH: "Adding these lines a dozen times throughout the recipe is tedious... can we just add a constants entry at root level?"	New top-level constants key
GH: "Rename this throughout to assert_unit_consistency or something similarly descriptive but more concise."	strict → assert_unit_consistency
RNB: "The recipe's __repr__ should include the units, maybe in square brackets after the term's name?"	Every node annotated [units]
RNB: "Are there any var: null left? This might be a legacy comment."	Correct — comment rewritten
RNB: "# to-do: add comparable chunking inside the difference and convergence routines — either do this or remove the comment."	Done, not removed

Shared constants at the recipe root

constants:
  seawater_density:
    value: 1035.
    units: "kg m-3"

mass:
  lhs:
    sum:
      Eulerian_tendency:
        product:
          thickness_tendency: "dhdt"
          density: "seawater_density"   # -> 1035. kg m-3
          area: "areacello"

Entries take the same two forms an inline constant does (a bare number, or a
{value:, units:} mapping). References are substituted while parsing, so the
typed tree still holds only Constant nodes and nothing downstream — evaluator,
query, display — knows the table existed. A string operand resolves against the
table first and otherwise stays a diagnostic name, so a constant sharing a name
with a dataset variable shadows it; the shipped recipes name theirs distinctly,
and a test pins that every declared constant is actually referenced (a rename
that missed a use would otherwise degrade quietly into a diagnostic never found).

constants is the one top-level key that is not a budget. This removed 36
repeated blocks from ECCOV4r4_native.yaml, 11 from MOM6.yaml, 9 from
MOM6_3Donly.yaml, 2 from MOM6_surface.yaml.

strict → assert_unit_consistency

Straight rename across collect_budgets, evaluate_budgets, the error text,
the tests, the docs, and the notebooks. Not deprecated — strict never shipped.

Units in the repr

Each node now carries its units in square brackets, in both the HTML tree and
the ASCII one:

heat  units=W, lambda=thetao, surface_lambda=tos
├─ lhs [Σ] [W]
│  ├─ Eulerian_tendency [×] [W]
│  │  ├─ tracer_content_tendency_per_unit_area: opottemptend [W m-2]
│  │  └─ area: areacello [m2]
│  └─ surface_ocean_flux_advective_negative_lhs [×] [W]
│     ├─ sign: -1.
│     ├─ specific_heat_capacity: 3992. [J kg-1 K-1]
│     ├─ lambda_mass: tos [degC]
│     ├─ thickness_tendency: boundary_forcing_h_tendency [m s-1]
│     ├─ density: 1035. [kg m-3]
│     └─ area: areacello [m2]

Units enter at the leaves, so show_recipe takes an optional third argument —
the grid/dataset to read raw diagnostics' units from — and the whole tree then
resolves. Reading it top-down shows exactly where a unit stops being
inferable, which is the useful diagnostic when assert_unit_consistency fails.
Without it, only the recipe's declared constants are annotated. A BudgetQuery
displayed in a notebook prefers the units its run actually stamped and falls
back to inference, so it is annotated before and after collect_budgets.

This is backed by a new units.infer_units(node, lookup), which runs the
evaluator's arithmetic statically over the typed tree. A test pins that it
agrees with what the evaluator stamps.

Bare numbers (sign: -1.) are deliberately left unannotated: they are
dimensionless by default rather than by declaration, and a [1] on every sign
would be noise.

var: null — a genuinely legacy comment

MOM6.yaml has no var: null entries left (0.7.0 made the placeholders
optional), so the markdown above collect_budgets was describing something the
cell above it no longer shows. Rewritten to explain what the tree does show —
the operator badges, the new units, and that a term without a var of its own
is one reconstructed from the diagnostics beneath it.

The chunking to-do: done, not deleted

lateral_divergence now gets the same allow_rechunk treatment difference
has always had — the differenced dimensions in a single chunk while xgcm works,
the caller's chunking restored afterwards. The two paths now share three helpers
(_dataset_chunks / _single_chunk_along / _restore_chunks) rather than one
having the logic inline and the other not at all.

Verified on the real ECCO V4r4 LLC90 budgets: numerically identical (all
three budgets, byte for byte) and roughly half the wall clock — graph build
16.6 s → 3.4 s, closure compute 44.2 s → 23.5 s. The notebook still chunks its
dataset, but for memory sizing, which xbudget cannot guess; the comment now says
so.

The chunking wrapper is _Evaluator._lateral_divergence (renamed from
_divergence per review); it wraps the bare collect.lateral_divergence, which
does the xgcm work.

lateral_divergence also gains its first CI test, on a two-tile face-connected
synthetic grid — a miniature of the LLC topology it exists for. It previously
ran only against the data-gated ECCO notebooks, so nothing in CI touched it.

Verified

• Full suite green, 136 → 157 tests. Run locally with the MOM6 example
  dataset present, so the characterization golden is included rather than
  skipped — it still matches, unchanged.
• assert_unit_consistency=True passes on the real MOM6 dataset (all six
  sides) and on the real ECCO V4r4 (LLC90) dataset; ECCO budgets still close
  to the same residuals (mass 2.6e-4, heat 5.1e-6, salt 1.2e-4, relative).
• All three affected notebooks re-executed against the real datasets.
• Docs build clean under python -m sphinx -b html -W --keep-going.

Note that GitHub Actions does not run on this PR: ci.yml triggers only on pull
requests targeting main, so a stacked PR into units-handling gets no test
job. The Actions matrix (Python 3.11-3.14) will cover this once #32 itself is
merged into main. Read the Docs does build it.

Review follow-ups

• Root-level constants table (GH review)
• strict -> assert_unit_consistency (GH review)
• Units in the recipe repr, in square brackets after the term name (ReviewNB)
• Stale var: null markdown in the MOM6 notebook (ReviewNB)
• The ECCO notebook's chunking to-do — implemented, not deleted (ReviewNB)
• _divergence -> _lateral_divergence (GH review on this PR)

🤖 Generated with Claude Code

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB