feat(language): a where may read a predicate through a relation with at()

[FBumann]

Prompt: "It does mix curve and non curve converters!" … "Yes" (to: take option 1 of #258, at() in a where:, as its own PR, then stack the piecewise change on #630)

Note

The following content was generated by AI.

What this changes

A where: may read a predicate through a relation: at(<predicate>, by=, over=, into=). It is true where the relation has a row and the predicate holds at the coordinate that row maps to. Closes #258 with option 1.

variables:
  rate:
    dims: [flow, snapshot]
    where: "at(has_curve, by=converter_of, over=converter, into=flow)"

$$\mathit{rate}_{f,t} \in \mathbb{R} \qquad \forall, f \in \mathcal{F},\ t \in \mathcal{T} ,:, \mathrm{has_curve}_{\mathrm{converter_of}(f)}$$

The rules, and where each one lives

• It is the third operator that reads a predicate, beside shift and count. The grammar already parsed name(<predicate>, kw=…), so the grammar does not change. Resolution routes at to _pulled_back.
• It follows the expression at's rules, and uses its refusals. by, over and into must all be written and nothing else is taken. The read lands on the relation's key, and the predicate must carry every dimension the read consumes. The dims logic moved out of _at_dims into dimensions.pulled_back_dims, which the expression and the predicate share.
• It maps and never widens. The consumed dims go and the produced dims arrive, so the frame check applies unchanged. Its message names the relation: a where-predicate read through 'lk' reads dims ['g'] outside the frame ['h'].
• It is false where the relation has no row, which is what a missing row already means in a mask.
• What it adds over arithmetic. at(cap, by=…) > 0 already worked, because an arithmetic side of a comparison accepts at. The predicate form reads what arithmetic cannot: definedness, a bool, a variable's existence, and connectives over them.
• Program vocabulary: PulledBackPredicate(operand: Mask, direction: Direction, dims). names_read includes the relation. Lowering rebuilds the operand as it does for TranslatedPredicate.
• In a case when: it is refused as undecidable, as shift and count are. Which rows a relation maps is the data's to say.
• The typesetter re-indexes the leaf, as the expression at does: has\_curve_{converter\_of(f)}.

Guard table: each guard deleted in turn, whole suite run, tree restored

Guard	Caught by
at reads a predicate	29 tests, incl. …[under-a-read]
at takes by, over, into and nothing else	3, incl. …[a-read-naming-no-columns]
the read is held to the dims rules of at	…[a-read-through-a-dim-the-predicate-lacks], …[a-read-onto-a-dim-the-predicate-carries]
the edge= hint is only for shift	test_a_read_given_an_edge_is_not_told_about_translations
the frame check names the relation	test_a_read_landing_outside_the_frame_names_the_relation
the read is lowered	test_a_predicate_read_through_a_relation_is_lowered_and_keeps_the_relation_in_reach
the relation is in names_read	the same, and test_a_read_lands_on_the_dims_it_produces_and_reads_the_relation
the typesetter reads at the relation	the golden files (new zoned constraint) and the notation page
a read is undecidable in a case	test_a_read_through_a_relation_is_undecidable_in_a_case_when

Gates, and what was not run

Gate	Result
pytest -q -n auto	1564 passed, 6 skipped
ruff check, ruff format --check	clean
pyrefly check	12 errors, the same count as main in this venv (missing-import / untyped-import and their consequences)
prettier, typos, reuse lint	clean
mkdocs build	only the docs.python.org inventory fetch fails (proxy 403)
golden output, notation page, schema	regenerated and read; the schema does not change
compile-tex, taplo, zizmor, pixi run ci	not run: no pixi and no LaTeX here

The gates ran from a uv venv, not pixi run, because pixi.sh returns 403 here.

Deliberately not done

• all() and any() (option 2). count(p, over=d) > 0 is any and equality with the full count is all, so they would be a second spelling. brynpickering's comment on may a where: carry operators — relocation through a lookup, reduction over a dimension it does not span #258 says any is not needed here.
• The implicit form (option 3), where a where-parameter over a dim reachable by a relation would be mapped silently. It hides a join behind a bare name.
• Consumers. lpspec will have to take PulledBackPredicate in its mask evaluator at its next math-spec bump.
• The piecewise use. A stacked PR on feat(language): a piecewise block states its dims and names its links, and its where reaches links that walk a relation #630 drops the refusal of a block where: beside a walked link, using this.

Why

fluxopt mixes converters that run on a piecewise curve with converters that do not. A piecewise: block's rows for a converter's flows are over flow, and the mask saying which converters have a curve is over converter. Until a where: can read that mask through converter_of, the block has to build a curve for every converter. The same spelling is the one PyPSA's retired-asset port asked for in #258.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HxoXSQCyrcDs6vuRk3x6tz

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34704988 | 📁 Comparing af62b28 against latest (f9cb305)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

• reference/notation/index.html
• reference/reading/index.html
• reference/language/expressions/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/program/index.html