feat(language): a where may compare arithmetic over parameters

[FBumann]

Prompt: Does this enable more coplex where in other places too? […] THen this should probably be directly to main!

Note

The following content was generated by AI.

Either side of a comparison in a where string may now be arithmetic over parameters: p_min <= 0.5 * p_max, sum(p_max, over=generator) >= peak, p_max <= at(bus_cap, by=bus_of), a macro, a named expression. It applies to every where: a variable's, a constraint's, and the assumptions: block of #465, which now stacks on this. Replaces #466.

What this changes

Grammar, resolution, the two vocabularies, rendering

Grammar. The where grammar's comparison atom gains expression COMPARATOR expression, with the expression parser's arithmetic element (ARITHMETIC, now exposed) on each side. The three comparison forms are matched longest-first, so p > 2 * q is not cut short at p > 2; the expression form stands aside for the plain shapes and for position(...), so p > 0 keeps the node its dtype rule is written for. A side is held to the same nesting depth as an expression, measured on the where text.

Resolution. A side is expanded (macros, named expressions), typed, degree-checked and dim-checked exactly as an expression is; the dims stamped on the node are every dim either side carries. Two things an expression may carry are refused here: a variable and a dual(). Namespace now carries the schema, which those checks need. A plain-form comparison that names an expressions: entry on either side takes the expression path.

Two vocabularies. The resolved tree holds ArithmeticComparisonNode over the core syntax tree, which the typesetter, the dim rules and the exclusivity check read. lower_program rebuilds every mask, on variables, constraints and case regions, with ExpressionComparisonNode over program expressions in its place, so a program's masks are program vocabulary throughout. Both are in the closed WhereNode union; the docstring on the first says a program never carries it.

Meaning. A comparison of expressions holds at every coordinate of the dims either side carries, and is held to the frame it sits in like any mask. A side with no value at a coordinate compares false, as a null does in every other comparison; under a summing operator the absent term is one fewer. A shift names its edge= as it does everywhere, and a position() term keeps the vacated row out (the reference shows the example).

Not decided. A case when: that compares expressions is refused as undecidable before the data arrives, with the rewrite, the way an ordered lookup pair is.

Rendering. One branch in the walk, since it already renders arithmetic. names_read on a mask now includes the lookup a grouping or pullback joins through and the parameter a named offset or width is read from, which an engine has to bind.

Not done here. max, min and count are new primitives, taxed as limits.md says. lpspec's mask evaluation gains an expression evaluator in its own PR.

Verified

uv venv, Python 3.12, since pixi is not installable in this environment:

• pytest -n auto: 1233 passed, 10 skipped; the five test_docs.py hook tests that need mkdocs deselected, as they fail on main here too.
• ruff check, ruff format --check, pyrefly check, prettier --check docs: clean.
• Golden output, notation page and gallery regenerated and read; the Typst golden compiles with the typst package.
• Not run: compile-tex, docs-build --strict, reuse, typos, taplo, zizmor. The same change on feat(language): a where may compare arithmetic over parameters, so an assumption can say what a formula has to satisfy #466's stacked branch passed all of CI, including those.

Mutation table

Taken on the stacked branch of #466, which carries this change verbatim on top of #465; each guard deleted in turn, the suite run, the file restored from a copy and the tree checked clean.

Guard	Caught by
the expression form standing aside for the plain shapes	test_a_where_is_one_resolved_predicate_with_every_literal_folded[…], the gallery pages, the parser tests
the variable refusal on a side	[a-variable-inside-arithmetic], test_a_bound_or_where_cannot_name_an_expression[where]
the dual refusal on a side	[a-dual-inside-arithmetic]
a named expression on a side of the plain form	[a-named-expression-on-the-left], […-right]
the dims stamped on a comparison of expressions	test_a_comparison_of_expressions_lowers_to_program_expressions_on_both_sides, the notation page
a case comparing expressions is undecidable	test_a_case_comparing_expressions_is_refused_as_undecidable
lowering rebuilds a comparison of expressions	test_a_comparison_of_expressions_lowers_to_program_expressions_on_both_sides

Coverage moved

• test_a_bound_or_where_cannot_name_an_expression[where] asserted that a where naming an expressions: entry fails to resolve; the entry is now read as arithmetic, and the case asserts the variable refusal that body earns instead.
• The golden fixture gains four constraints whose masks compare expressions (arithmetic; a translation with its edge, a pullback and a position guard; a reduction on a scalar mask; a named expression) and one data-only named expression, so the node censuses see every new arm. ExpressionComparisonNode joins the census's list of nodes the walk never meets, with the walk's guard on it exempted from the line census.

🤖 Generated with Claude Code

https://claude.ai/code/session_013HceuCYNepeQX8SdZtiMf1

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34579368 | 📁 Comparing 5c1a67a against latest (78b0ce1)

  🔍 Preview build  

35 files changed · ± 35 modified

± Modified

• index.html
• CHANGELOG/index.html
• about/limits/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• examples/pypsa_losses/index.html
• examples/pypsa_multi_period/index.html
• and 25 more...

[brynpickering]

Thanks for opening this. Definitely needed!

[brynpickering]

and other expressions (at least insofar as those other expressions include variables or duals)?

[brynpickering]

I don't really understand this sentence at all.

[FBumann]

when is the thing that Cases operates on.

So each when separates an expression.

To enable static analysis of the when separations, we disallow complex expressions in when.

This might be feasible, but im not sure if it is.

[FBumann]

Superseeded by #566