feat(language): a boundary clause names a position, not the label at one

[FBumann]

Prompt: "I want to update the repo to the latest changes in mathspec. Look at the 3 open draft PRs. Do PRs adopting the fixes and features. Stacked. Pin the hash in them."

Note

The following content was generated by AI.

First of two. Adopts energy-models/math-spec#31 — index(dim, i) is retired for position(dim), which converts on the left.

#31 is merged and released, so the pin is an ordinary tag again — v0.0.0-alpha.9 — and the commit-pin rationale this PR carried while #31 was in flight is gone from pyproject.toml. That also removes the blocker this PR was drafted behind, so it is out of draft.

Both lanes already compared positions, so the language change is a surface migration and not a semantics change. snapshot > index(snapshot, 0) was ambiguous in the language — a coordinate comparison or a position comparison, and the two part company on an axis whose coordinates do not arrive sorted — but this engine only ever built the position reading: _position_ordinal normalises to an ordinal and compares against arange, relationally and eagerly alike.

What changed

• The pin moves from v0.0.0-alpha.4 to v0.0.0-alpha.9. That is five releases, not one feature: it carries A bound cannot be an expression, so a bidirectional flow ships a negated copy of its capacity as data #31, plus #34 (to_markdown printed TeX's --- ligature rather than an em dash), #41 (the notation page is generated again) and #44, below.
• Every where: in the corpus — 5 port models, 6 doc pages, the tests — rewrites dim OP index(dim, i) to position(dim) OP i and the grouped form to position(dim, by=lookup) OP i.
• The two lanes' bind-time refusals name the surface the model was written in: where: position(snapshot) == 3 names position 3 of 'snapshot', which has 3 coordinate(s).
• tests/test_index_of_dim.py → tests/test_position_of_dim.py.

The gallery moved twice, and most of the diff is that

Both refreshes are generated output — tools.gallery_math, nothing hand-edited.

#31's own page work. Six pages gained a legend for the operator they print, a negative position prints against the set's size rather than as a bare -1, and a dimension whose labels are numbers says so:

-…  \thinspace:\thinspace \mathrm{pos}(b) = -1
+…  \thinspace:\thinspace \mathrm{pos}(b) = \lvert \mathcal{B} \rvert - 1
-| $\mathcal{T}$ | index $t$ — `snapshot` — dispatch periods |
+| $\mathcal{T}$ | index $t$ — `snapshot` (`int` coordinates) — dispatch periods |

#44 — upright is what the model is given, italic is what the solver chooses. This touched 40 pages and is the larger half of the diff:

-| $\mathit{marginal\_cost}$ | `marginal_cost` over $\mathcal{G}$ — cost of one unit of output |
+| $\mathrm{marginal\_cost}$ | `marginal_cost` over $\mathcal{G}$ — cost of one unit of output |

Four lpspec tests asserted the old spelling for parameters and were updated with it — test_power.py (LaTeX and typst: italic("growth") → upright("growth")) and test_sum_back.py's window condition. Variables were left alone, which is the point: the same assertions still read \mathit{started}, \mathit{on}.

Coverage that moved

• test_two_different_dimensions_cannot_be_compared_by_position is gone, because what it asserted is gone: A bound cannot be an expression, so a bidirectional flow ships a negated copy of its capacity as data #31 drops resolution's same-dimension check, since position(dim) yields an integer and there is no pair of coordinates left to compare across label spaces. Replaced by test_a_position_along_a_dimension_the_frame_lacks_is_refused, which pins the rule that now speaks instead — the ordinary dim-algebra one.
• Added test_the_retired_index_spelling_names_its_rewrite: every seeding clause in this tree used index() until today, so the migration message is what stands between a stale model and Expected end of text, found '('.

Verified

Full suite on Python 3.12, HiGHS: 2965 passed, 323 skipped, 1 xfailed. ruff check, ruff format --check and pyrefly check over src/ clean.

Not checked: the gurobi and xpress sinks — neither wheel is installed here, so their 10 tests fail identically before and after and are the entire delta from a green run. The typst golden tests skip for want of the binary. Nothing was measured; this PR makes no performance claim.

Deliberately not done

No example was added for the construct; it is a rename of one already in the corpus. cases: is the PR above this one, and still blocked on math-spec#36.

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34195515 | 📁 Comparing 4d9d38d against latest (e292dc8)

  🔍 Preview build  

48 files changed · ± 48 modified

± Modified

• index.html
• interactive/index.html
• examples/dispatch/index.html
• examples/facility_location/index.html
• examples/genx_piecewise_fuel/index.html
• examples/monthly_budget/index.html
• examples/multi_period/index.html
• examples/osemosys_utopia/index.html
• examples/piecewise/index.html
• examples/piecewise_conversion/index.html
• and 38 more...

[codspeed]

Merging this PR will not alter performance

✅ 16 untouched benchmarks
⏩ 42 skipped benchmarks¹

---

_{Comparing feat/position-operator (4d9d38d) with main (ffbbee6)²}

Footnotes

1. 42 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. ↩

2. No successful run was found on main (e292dc8) during the generation of this report, so ffbbee6 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩