feat(data): what a file assumes of its data is checked at the door, and a where may compare two parameters

[FBumann]

Prompt: Lets implement the new mathspec features in lpspec. Do two stacked PRs in lpspec pinning the head of the mathspec feature branches. Pull the latest lpspec first!

Note

The following content was generated by AI.

A file's assumptions: block is checked at the door, once for both lanes, and the data refused in the language's own sentence with the failing coordinates; a where may compare two parameters coordinate by coordinate, false where either has no row.

Stacked on #1636. Follows math-spec to eeb38f6, the head of energy-models/math-spec#471, itself stacked on #469. The regenerated gallery pages pick up the typesetter's new Assumptions section on the three piecewise models — the piecewise checks the language already made, now printed.

How the check works

assumptions.py, called from tidy_sources after every parameter, dimension and lookup is read. Each entry's holds is evaluated by the relational lane's predicate compiler — the one reader of a mask this package has that needs no model built first, and the reader every where: goes through — over the product of the dims both masks name, restricted by where. The failing coordinates are the admitted product less the rows holds keeps, not the rows it drops: a mask certain of a parameter inner-joins it, so a coordinate with no row is gone from the carrier before the predicate is read, and that coordinate is exactly the one a missing row has to count as failing. The sentence is assumption_message's, then the count and the first five coordinates in the dimensions' own label order:

assumption 'floor' does not hold for the data bound to 'p_max', 'p_min' at 2 coordinates: (generator=wind), (generator=gas)

Both lanes pass through tidy_sources, so both_lanes_refuse holds them to one sentence. attach is paid only by a program that declares an assumption.

ParameterPairComparisonNode: the relational lane joins both parameters onto the carrier and compares the columns, both names certain under the AND spine; the linopy lane compares the two arrays and masks by both being present, since NaN != x is true in numpy. p_max > cost, refused before, moves from the refused list to the accepted sweep in test_resolution_parity.py.

Mutation table

Taken by hand, tree restored through git checkout -- and __pycache__ dropped on both sides, clean each time. Suite: tests/test_assumptions.py tests/test_resolution_parity.py at 4eda453e; the re-run adds tests/test_where_arithmetic.py at 6894e2d8.

guard	mutation	result
door: the check runs	validate_assumptions call dropped	caught
door: where narrows the product	frame(dims, None)	caught
door: a missing row counts as failing	failing rows read off the carrier instead of the anti-join	caught
door: the count is in the sentence	count dropped	caught
linopy: the pair masked by both rows present	& left.notnull() & right.notnull() dropped	still green, then caught by the second commit's extra != cost probe
linopy: the sides in order	swapped	caught
polars: the sides in order	swapped	caught

Verified

Same uv venv as #1636, math-spec editable at eeb38f6:

• ruff check ., ruff format --check .: clean.
• pyrefly check --python-interpreter-path <venv>: 0 errors.
• pytest -n 8 at 4eda453e before the gallery regeneration: 3764 passed, 328 skipped, 1 xfailed; 11 failed — 10 [gurobi]/[xpress] cases with neither extra installed here, and test_the_gallery_math_is_current, which python -m tools.gallery_math then refreshed (the diff is the three piecewise pages' Assumptions sections). The docs tests and the touched files re-run green after.
• python -m tools.gallery_math --check passes.

Not run: pixi run check as such, the docs build, test-bench.

Not done

• lps.check says nothing about assumptions: it has no data, and the language already refuses an unresolvable holds at load.
• diagnostics() does not report which assumptions were checked.
• A wording for the refusal lives in assumptions.py rather than errors.py: one module raises it.

🤖 Generated with Claude Code

https://claude.ai/code/session_013HceuCYNepeQX8SdZtiMf1

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34579817 | 📁 Comparing ef1a6c9 against latest (ecd351f)

  🔍 Preview build  

80 files changed · ± 80 modified

± Modified

• index.html
• examples/index.html
• guide/index.html
• interactive/index.html
• lifecycle/index.html
• about/architecture/index.html
• about/benchmarks/index.html
• about/changelog/index.html
• about/decomposition/index.html
• about/linopy/index.html
• and 70 more...

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 58 skipped benchmarks¹

---

_{Comparing claude/zealous-archimedes-k13bq7-assumptions (ef1a6c9) with claude/zealous-archimedes-k13bq7 (fc49e24)}

Footnotes

1. 58 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩