feat(language): a piecewise curve and an sos set name the dimension they run along

[FBumann]

Prompt: "Do we expose everything an engine (lpspec) has to act on? Simplifications?" — then: "Do the whole migration now" and "This branch should be based on 1697"

Note

The following content was generated by AI.

What this changes

energy-models/math-spec#569 renames the axis key on piecewise: and sos: from over: to along:. lpspec follows it: every model, example, fixture and documented model takes the new key, and curves.py, assembly.py and the linopy builder read along off the declarations. 3779 passing, 10 failing — the 10 are the gurobi and xpress extras, which are not installed here.

Draft, and it cannot merge yet. The pin points at a math-spec branch, because #569 is unreleased. Repin to the first tag carrying it before merge.

Rebuilt on #1697. This branch previously carried its own Walk → Direction relation migration and its own refusal of a where: comparing two expressions. #1696 did the first and #1697 the second, both better, so both were dropped rather than rebased — the stack is the base branch, and what is left is the #569 delta alone.

What was dropped, and why

• The relation migration. fix(language): an at that joins on a dimension it also consumes is refused, as a sum already was #1696 renamed Walk → Direction, gave Partition its own type and spelled the parameters direction throughout. This branch had renamed the type while leaving the parameters walk, and had not separated Partition. Replaying it would have reverted fix(language): an at that joins on a dimension it also consumes is refused, as a sum already was #1696's naming.
• The refusal of ExpressionComparisonNode. feat(language): a where may compare arithmetic over parameters on both lanes #1697 builds it on both lanes — a side compiles the way a constant side of a constraint does. Refusing what the stack below builds is a contradiction, so the refusal, its message in errors.py, its lanes.lowered check and its tests all went. test_both_lanes_refuse_the_same_where's p_max > cost case belongs to feat(language): a where may compare arithmetic over parameters on both lanes #1697's ACCEPTED now.

What is left

what moved
PiecewiseDeclaration, SosDeclaration, Increasing, Curved, AtLeastTwo	over → along
every model, fixture, example and documented model	over: → along: under piecewise: and sos:
Buildable	Mapping[str, object], which is what to_spec now takes

Two test expectations follow upstream wording rather than behaviour: the sos dim refusal now says along 'other' is not a dim, and a stray values dim is judged against its own link's row frame rather than against every link expression.

Why the key moved. The language already separated over=, which consumes a dimension, from along=, which keeps it and keeps it ordered. A breakpoint axis is ordered and survives into the weights, so it was on the wrong side; the expansion already wrote shift(seg, along=bp) for that same dimension. sos: moves with it, because method: sos2 hands one block's axis straight to the other's.

Why the diff is this small. #569 is large, but the surface it exposes to an engine is not: its whole program.py diff is 14 insertions and 10 deletions — the five renames above, and one new field, PiecewiseDeclaration.where. dims:, the link refinement, the per-link signs and the pin rule are all expansion and load-time validation inside math-spec, so a refined link reaches this package as an at(...) it already builds. Checked rather than assumed: math-spec's own examples/piecewise_coupling.yaml — a two-flow boiler and a three-flow CHP tied on one curve through converter_of — builds on both lanes with nothing here beyond this PR, and solves optimal on the relational lane.

Gates, and what could not be run

Gates ran from a uv environment on Python 3.13 with math-spec installed from the #569 branch at 057c56f, because this environment's egress proxy refuses pixi.sh — a departure from the pixi run check default. Every number below is measured on 395b996e, the current head.

gate	result
pytest, with [linopy] and pyarrow	3779 passed, 10 failed, 337 skipped, 1 xfailed
ruff check, ruff format --check	clean
pyrefly check	6 errors
pixi run check as a whole	not run
differential/, bench/, the docs build	not run
the gurobi and xpress extras	not installed — all 10 failures, each the package's own message saying so

The pyrefly number needs its comparison: the base branch with this same pin installed reports 15, the extra nine being exactly the .over reads this branch renames. The 6 that remain are the identical set the base reports on its own pin (api.py ×2, frames.py ×3, one unused-ignore in assembly.py), and pyrefly here is 1.3.1, newer than the pin.

docs/examples/*.md took the over: → along: rename in their hand-maintained model blocks. The generated math is untouched, #569 having changed no operator wording.

What this leaves

PiecewiseDeclaration.where is not consumed, so the feature does not work here yet. A block may now say which members have a curve at all. validate_curve_extent does not read that mask — its docstring states the premise that has become false, that "the λ it declares carries no mask" — so check() passes and the build then demands data for a curve the model said does not exist:

DataError: piecewise 'cost_curve': parameter 'bp_x' has no value at (generator='g2', bp=2)
— 3 of the 6 coordinates it needs. …  Or supply it …

It is not a patch to that function: validate_curve_extent is called from tidy_sources, the lane-agnostic data door, where no Scope exists, and a second mask walk in curves.py is what hard rule 3 exists to prevent. Its own issue, and a blocker for anyone using where: on a block.

Nothing was measured, so no performance number is claimed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hh3uK8SqVcXKuLnYHAjrVW

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34653282 | 📁 Comparing 395b996 against latest (049c48d)

  🔍 Preview build  

19 files changed · ± 19 modified

± Modified

• about/architecture/index.html
• examples/piecewise/index.html
• examples/piecewise_conversion/index.html
• examples/piecewise_lp/index.html
• examples/piecewise_ragged/index.html
• examples/pypsa_mixed_cycling/index.html
• examples/pypsa_spill/index.html
• examples/pypsa_storage/index.html
• examples/pypsa_store/index.html
• examples/pypsa_unit_commitment/index.html
• and 9 more...

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 58 skipped benchmarks¹

---

_{Comparing claude/mathspec-piecewise-api-7j0wpt (395b996) with claude/happy-maxwell-9ldgqa-where-expressions (f23d814)}

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

[FBumann]

Note

The following content was generated by AI.

Closing as superseded and stale.

• sos: → along: landed in feat(language): a special-ordered set names its dimension with along, the way math-spec 0.0.0-alpha.120 does #1720, following math-spec 0.0.0-alpha.120.
• piecewise: → along: has not shipped in math-spec: PiecewiseDeclaration.over is still the field at the pinned alpha.122 and on math-spec main (alpha.123), so main's over: bp is correct today.
• The base branch (feat(language): a where may compare arithmetic over parameters on both lanes #1697) was closed unmerged, curves.py left in refactor(data): the caller binds every parameter a piecewise curve reads, and no name the expansion invented #1711, and the package is now specsolve (refactor(api): the package is named specsolve, installed and imported under that name #1726). Almost nothing here would survive a rebase.

If math-spec releases the piecewise rename, the follow-up is a fresh PR from main: bump the pin, and rename the key in the piecewise examples, their docs/examples/*.md copies and the test fixtures.

---

Generated by Claude Code