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

[FBumann]

Prompt: "Rebuild it as two PRs on #562. First a chore(language) that lands the one atom and the dispatch with no behaviour change […]. Then #469's semantics become one new branch in that dispatch plus its lowering, docs and tests." — "I'm wondering however if there is potential for more reuse and simplification" — "is the .of(schema) even sth desirable? Why not extract all the information at creation of the Namespace?"

Prompt: "WOuld it be more usefull together with #566?" — "all 3"

Prompt: "Review the stack of 602 and below" — "Do 1-3"

Note

The following content was generated by AI.

On main, now that #565 and #585 have landed. Either side of a where comparison may be arithmetic over parameters: p_min <= 0.5 * p_max, sum(p_max, over=generator) >= peak, a pullback, a translation with its edge, a macro, a named expression. This is #469's semantics on the one-atom grammar, and it replaces #469.

What this changes

• One new branch in the dispatch. _comparison sends a comparison to _expression_comparison where a side is not a plain leaf, or where a plain-looking side names a parameter or an expressions: entry against a value. There each side is expanded, typed, degree-checked and dim-checked as an expression is, and refused where it names a variable or a dual(). The transient "arithmetic on a side" refusal chore(language): a where comparison is one grammar rule over the expression grammar's arithmetic #565 introduced is gone, and so is the grammar-side arbitration feat(language): a where may compare arithmetic over parameters #469 needed (_reads_arithmetic as a parse condition, _is_plain, _nested over two vocabularies, the re-route inside _comparison).
• Two parameters compare as arithmetic. feat(language): a where may compare arithmetic over parameters #469 admitted c <= 0.5 * k and kept refusing c <= k with "compares two parameters, which is not in the language". Here c > k loads as a comparison of expressions, and that branch of _declared_rhs_error is deleted. A str or bool parameter on a side is refused by the message arithmetic already has for it.
• What is decided before data is refused at load. A comparison with a number on each side, 2 < 1, is refused and the message names the rewrite; it used to reach the program as an ExpressionComparison over two constants. A cases: block of one case whose when: compares expressions is refused as a pair is: the rule is on the case, since its otherwise is the negation and only the data says where that falls. The pairwise check reported it only from two cases up.
• Two vocabularies, as feat(language): a where may compare arithmetic over parameters #469 had them. The resolved tree holds ArithmeticComparison 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 ExpressionComparison over program expressions. names_read on a program mask includes the relation a grouping or a pullback reads through, the one a translation or window is partitioned by, the parameter a named offset or width is read from, and the masks that decide which region of a cased entry applies. The resolved form does not answer names_read: nothing asks a resolved mask that question, so its arm is the assertion the typesetter already carries for the lowered node rather than a second walk.
• A namespace is built from its schema and carries it. The where path needs expand, dims_of and the expressions: names, none of which the flat listing holds. feat(language): a where may compare arithmetic over parameters #469 hung the schema on Namespace behind an eight-argument constructor and a classmethod that was its only caller. Here Namespace(schema) reads every declaration at construction, and expression_of, _check_expression and _named, which took the schema beside a namespace built from that same schema, take the namespace alone.
• A relation column and a quoted label stay out of arithmetic. lk.h > 2 * k and 2 * k == 'x' are refused with the rewrite. The relation refusal no longer claims every other comparison tests a name against a literal.
• The Predicate union says which member a program never carries. It holds ArithmeticComparison, which lowering rewrites away, so a consumer walking a program meets every other member and never that one. The union's comment and the reading page say so. These eleven lines were written on chore(program): nothing left — this PR's work is in #585, #566 and #569 #580; they moved here because they are only true where these two nodes exist.
• The plain form and the arithmetic form overlap, and the reading page says so. p_max > 5 lowers to a ParameterComparison and 1 * p_max > 5 to an ExpressionComparison, though both mask the same coordinates. Routing prefers the plain path, so no file produces both for one text, but a consumer that handles only the new node misses the common case. Verified by lowering both against the dispatch fixture.
• Rendering. One branch in the walk. The golden model gains four constraints and one data-only named expression, and the notation page follows.
• Docs. The where BNF, the table, and a section on arithmetic in a comparison on expressions.md; three paragraphs on reading.md. The sentence "comparing two parameters is not in the language" is replaced.

The break

Predicate and TypedPredicate gain ExpressionComparison and ArithmeticComparison, and a consumer's mask walk meets the first. Namespace(schema) replaces Namespace.of(schema), and expression_of(text, ns, context) no longer takes the schema and has moved to tests/fixtures.py, its only caller. lpspec's mask evaluation gains an expression evaluator in its own PR, as #469 said. The node renames this branch carries are #585's, already on main, and lpspec owes them once rather than twice.

Measured against fluxopt/lpspec at fc91b4a, which pins v0.0.0-alpha.106: both of its mask walkers, linopy/where.py and the polars predicates.py, end in assert_never and have zero branches for either new node. assert_never is a static check, so each walker needs an ExpressionComparison branch or it stops type-checking — two branches, not one evaluator's worth of work each, but they are not optional.

Merged onto main at e6ae307, and what that took

Merged, not rebased: the hard rule here is never to force-push.

#585 renamed the program's where vocabulary and expression nodes on main while this branch was building, and this branch's own two comparison nodes carried the Node suffix the rule reserves for the core AST. The rename was applied here first, as one commit, so that the base merge agreed line for line instead of conflicting on every one of them: merged straight it conflicted in 40 places.

What the two sides genuinely disagreed about, resolved by hand:

• _check_where_dims keeps this branch's leaf form. main's noun form cannot name a comparison of expressions, which carries no single name.
• _declared_rhs_error keeps its three kinds. A parameter on the right-hand side is arithmetic here, not a refusal, so main's parameter branch has nothing left to fire on.
• Namespace keeps its schema-carrying form and builds a RelationDeclaration without the name main dropped from it.
• expression_of and where_of stay in tests/fixtures.py; main's copies in resolution.py go with the merge.
• Translate.along, WindowSum.along, Program.roots, Footprint.kinds and the relation records are main's.

Gates

pixi.sh is refused by this environment's egress proxy with a 403, so the gates ran from a uv environment on Python 3.12 with the pinned ruff==0.16.1 and pyrefly==1.2.0. That is a departure from the "every command runs under pixi run" default.

gate	result
pytest -q -n 4	1398 passed, 1 skipped (main: 1357 passed)
ruff check, ruff format --check	clean
pyrefly check	0 errors, 9 suppressed, as on the base
mkdocs build --strict	clean, with the docs.python.org inventory dropped for the run, which the proxy refuses with a 403
prettier --check on every Markdown	clean before the review commit; not run for it
typos, reuse lint	clean before the review commit; not run for it
the schema, the golden output and the four page generators	no diff
taplo, zizmor, compile-tex	not run, for want of the tools

The golden .out files and the notation page were regenerated and read; the four new constraints print as #469's did. The schema did not move. The YAML example on expressions.md was written to a file and loads with python -m math_spec check.

The reading-page paragraph was added in a later commit and gated on its own: pytest tests/test_docs.py tests/test_reading_page.py (34 passed), the full suite (1383 passed, 1 skipped), mkdocs build --strict and prettier --check clean. typos, reuse lint, taplo, zizmor and compile-tex were not run for it, for want of the tools. The page, by the measurement in the docs-writing skill: n 55, avg 14.6, median 13, over25 7 — every long sentence predates it, and the three added are 10, 20 and 9 words.

The review commit (84e3ec2) was written as four failing tests first: two-numbers and arithmetic-over-numbers-alone in test_a_bad_comparison_of_expressions_is_refused_at_load, test_a_lone_case_comparing_expressions_is_refused_too, and test_a_cased_side_reads_the_data_its_regions_are_decided_by. Two test_exclusivity cases now see one refusal per case rather than one per pair.

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.
• TestAWhereSideIsReadInResolution holds every case on what a where side may be: the position() shapes and the literal forms from chore(language): a where comparison is one grammar rule over the expression grammar's arithmetic #565, and the arithmetic cases, with two-parameters and a-literal-on-the-left as loading cases.
• where-against-a-parameter in TestRulesDecidedWithoutData asserted "compares two parameters"; it is a-flag-against-a-parameter, asserting the bool refusal.
• New: the two lowering tests, the typesetter test in every format, the undecidable-case test, and the refusals for a relation column, a quoted label and position() inside arithmetic.

Left alone

• 2 < c loads, where feat(language): a where may compare arithmetic over parameters #469 refused it at parse. Either side may be an expression, and a literal is one.
• c > c loads. It is unsatisfiable on finite data, but detecting it is tautology detection, which the fold does not attempt.
• position(g) + 1 == 0 is refused as an unknown operator, since position is a where atom and not an expression operator.
• position() stays out of the operator table: a row there also puts it in BUILTIN_NAMES, which the expression resolver, the unknown-operator message and the golden operator census read.
• Namespace keeps its flat fields. They are read in 24 places in the resolver, and reading them off the schema at each site would trade one dict lookup for a walk of a section.
• The overlap above is documented, not removed. Folding ParameterComparison into the arithmetic form would lose the literal's type check against the declared dtype, has no representation for the str case at all, and would cost lpspec the _certain_names optimisation, which reads the node's name field to choose an inner join over a left join.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EEeM2YoAk4Xr2uWB5qwMsH

https://claude.ai/code/session_01JPqtQuarRGDmX2WrNVuKDP

https://claude.ai/code/session_01JJfEUsCDtwXuXV8CANCHuR

https://claude.ai/code/session_019tCWoetBmjF1LpbTbjQY29

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34692199 | 📁 Comparing 84e3ec2 against latest (3317ecf)

  🔍 Preview build  

25 files changed · ± 25 modified

± Modified

• CHANGELOG/index.html
• contributing/index.html
• examples/commitment/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• howto/declare-a-column/index.html
• reference/notation/index.html
• reference/reading/index.html
• reference/language/expressions/index.html
• and 15 more...