feat(language): a piecewise curve applies to the members that have one, and ties as many expressions as the data says

[FBumann]

Prompt: "Let's work on the piecewise part of mathspec. I'm not fully satisfied with the api we buildt"

The scope was set later by: "fluxopt, a downstream user wants to add piecewise coupling power[flow], where a generator can have multiple flows connecting it to buses. A generator can have 1 up to 5 flows."

Prompt: "Please rebase 569 onto main"

Prompt: "Then discuss its api. Im not sure about points:" — "Lets do it!"

Prompt: "Rename the naming and complexity f the resulting piecewise code. Can it be simpler? Can we name classes or attributes better?"

Prompt: "Do a stacked PR trying to simplify the picewise feature as much as possible, removing all indirection. Also centralize the checks of whats allowed and what not."

Note

The following content was generated by AI.

What this changes

A piecewise: block says which members have a curve and how far each runs in one where:, one link ties as many expressions as the data says, and a curve may bound as many of its links as the model needs. Closes #77 and #82.

piecewise:
  operating_point:
    along: bp # renamed from `over:`
    dims: [converter, snapshot] # the curve's frame, declared rather than inferred
    where: has_curve AND bp_rate # which coordinates have a curve, and how far each runs
    links:
      - { expression: rate, values: bp_rate, into: carrier } # a tie per carrier
      - { expression: power, values: bp_power, by: converter_of, over: converter, into: flow }
      - [fuel, fuel_bp, ">="] # bounded by the curve, not pinned to it

points: is gone; where: may read the breakpoint dimension. Since #609 a points: was a predicate the rows read, not a parameter, so the two keys were one mask split by which dimension each was allowed to carry. Now a where: over the frame says which curves exist, one that also reads along says which breakpoints each runs through, and has_curve AND bp_x composes both. The rows over the frame and along take it as written; the edge rows shift it; the rows over the frame alone, which cannot read along, take count(where, over=bp) > 0. where: bp_x is the old points: bp_x, and a boolean mask is the old boolean mask.

A link's row is (frame − over) | into — the frame law #516 settled for relations, now the one rule for a link too. Two forms fall out of it:

written	the row	the weights
into: carrier	the frame, plus carrier	broadcast across it
by: converter_of, over: converter, into: flow	the frame, less converter, plus flow	read through the relation

Either way one link entry builds many rows sharing one set of weights, so λ stays invisible and every guard the block carries still applies. A sixth flow is a row in converter_of rather than an edit to the model.

Signs are per link, and at least one link is pinned. The old rule allowed one <=/>= and only in a block of exactly two links, so a curve needing a >= and a <= at once could not be written. Nothing in the emission needed that cap.

Five models that loaded clean and stated something else are now refused:

was	now
two links at different grains built one curve per fine coordinate	a link expression carries exactly its row's frame
a link coarser than its row pinned it to one operating point	same rule, other direction
an unmasked link row read rate == 0 where a member had no curve	where: reaches the link rows
every link bounded left the weights free, so only some point had to work	at least one link is pinned
method: lp with three links raised ValueError rather than a LanguageError	lp states its own two-link rule

Every check has one home (#623, merged into this branch). A block passes three layers in order: its own validators for arity, signs and which methods take a refinement or a gate; the file's cross-declaration validator, beside the sos: checks, for what it names by key and the names it writes; and piecewise.check, which returns a Curve of plain facts — the frame, each link's row, the mask, the gate rows, the names — from which four emitter functions write rows and decide nothing. The link expressions and the where are typed with the rest of the model, so the expansion no longer parses them. A refusal about a key or a collision is a SchemaError with the file's other cross-declaration refusals; PiecewiseExpansionError is left for a link that does not fit its row or a where outside the frame. Every message is unchanged.

The API, key by key

key
along:	the dimension each curve runs along. Renamed from over:, on sos: too
dims:	the curve's frame. Required once any link refines it
where:	which coordinates have a curve; reading along too, how far each runs
into:	on a link: what its row gains — a dimension it spans, or the columns a walk produces
by: / over:	on a link: the relation, and the columns the walk consumes
sign	on a link: bounded by the curve rather than pinned to it, any number per block

Why along:. The language already separates over=, which consumes a dimension, from along=, which keeps it and keeps it ordered. A breakpoint axis is ordered, it survives into the weights, and the expansion already wrote shift(seg, along=bp) for that same dimension. The reference page had to gloss the old key as "the dimension it runs along" in order to explain it. sos: moves with it, because method: sos2 hands one block's axis straight to the other's.

Why one where: and no points:. The only thing that kept them apart was a rule that where: may not carry the breakpoint dimension — a restriction this branch chose, not one the rows need. Every derived row and assumption already worked on a predicate: shift takes a where expression, so the neighbour, edge and interior predicates run on (where) in place of a name, and the _contiguous assumption wrote the first-of predicate that way already. What the split bought was a second key, a dtype check on it, a nomination rule, and a message telling the author to move a test from one key to the other.

One semantic shift comes with it: a coordinate whose mask admits no breakpoint has no curve, where points: refused it at data time. That is the reading where: already gave the frame.

Why the bare split is into: and not over:. With by: present, over: is what the row loses and into: what it gains. A split along a local dimension gains one and loses none, so it is into: with nothing consumed — the same law, entered from the other side. Spelling it over: would put two meanings on one key within one link. over: without by: is refused, and the message names into:.

A block whose links all refine the curve needs only one of them. Two links is what a curve needs when a link is one row; a refinement is one row per fine coordinate, so the data supplies the arity the second link otherwise would. One unrefined link is still a bound rather than a curve, and still refused.

What each refusal names, and why it is a refusal rather than a guess

• A link expression carries exactly its row's frame, the rule a constraint's own dims: already holds to. Finer multiplies the rows; coarser repeats one row across a dimension the curve varies over, pinning the expression to a single operating point. Both are viable-sounding models that nothing in the file distinguishes from a mistake. The message differs by whether the frame was declared or read off the links.
• At least one link is pinned. A pinned link fixes the operating point the bounded ones are read at. With every link bounded the weights are free and the block states only that some point on the curve satisfies the bounds — a different model, so it is refused rather than guessed. A refinement supplies arity, not a pin, so a lone bounded split or walk is refused too.
• convex and lp take exactly two links and refuse a refinement — for two different reasons, and each message says its own. lp writes a segment line, which is one quantity against another, so without a link for the abscissa there is no line to write; under a refinement, which of the rows plays the abscissa is data rather than declaration. convex is not like that: its rows are weights on the simplex plus one row per link, a formulation that would serve any number. What it cannot do past two links is certify that relaxing onto the hull is exact — the sign on the bounded link names the direction the curvature is checked in, and a third link leaves no single direction to check against. Under a refinement it loses the pair of values parameters it reads a shape from.
• where: beside a walked link is refused: the walk replaces the frame dimension the mask tests, so the row would read its weights as absent and pin its expression to zero. The message names the rewrite, a mask on the link's own variable. This lifts when may a where: carry operators — relocation through a lookup, reduction over a dimension it does not span #258 does. A split link keeps every frame dimension, so the mask reaches it and is allowed — a ragged one too, as the count of breakpoints its curve admits.
• where: reading a refined link's values is refused by the rule every mask holds to: those values carry the link's own frame, and a mask cannot add coordinates. Raggedness belongs to the curve.
• into: naming a dimension dims: already carries is refused: the curve builds one per coordinate of those, so they cannot also index a link's ties.

Guard table — every guard deleted in turn, suite run, tree restored clean

Twenty-eight guards. All caught.

guard	caught by
the link row mask	…reaches_every_row_the_block_emits[link0]
the convexity row mask	…[convexity]
the weights mask	…reaches_the_weights[lam]
_all_of's parenthesisation	…a_where_and_a_points_both_reach_the_weights
the breakpoint-dim and stray-dim refusals	…cannot_read_is_refused[…]
the mask on the declaration	…the_data_guards_are_read_under
chord / domain row masks	…segment_lines_carry_the_mask…
the declared frame replacing inference	…one_curve_per_coordinate_of_it
the walked link frame and its at emission	…one_curve_per_coordinate_of_it
values following the link frame	…one_curve_per_coordinate_of_it
dims: required for a refinement	…[refined-link-without-a-declared-frame]
by/over/into written together	…[a-walk-that-does-not-name-both-ends]
convex/lp refusing a refinement	…refuse_a_walked_link_for_their_own_reasons[convex]
points: refusing a refined values	…points_naming_a_refined_links_values_is_refused
the relation existing	…[a-walk-through-an-undeclared-relation]
the stray-dim arm	…[a-frame-a-link-expression-leaves]
the missing-dim arm	…links_that_disagree_on_their_dims…
the fit running on the inferred frame	…links_that_disagree_on_their_dims…
the span path in the link frame	…split_along_a_dimension_reads_the_curve_once…
produced dims appended for a split	…split_along_a_dimension_reads_the_curve_once…
the weights broadcasting rather than walking	…a_curve_holds_its_variables_through_the_rows_it_emits
into: refusing the breakpoint dim	…[splitting-along-the-breakpoint-dim]
into: refusing a dim the frame has	…[splitting-along-a-dim-the-frame-has]
over: requiring by: beside it	…[over-without-a-relation]
the mask reaching a split but not a walk	…a_block_mask_reaches_a_split_link
the pin rule (at least one ==)	…[every-link-bounded]
convex/lp's two-link rule	…take_exactly_two_links_for_their_own_reasons[convex]
lp's one-bounded-link rule	…[lp-with-both-links-pinned]

One guard initially survived: the link-expression frame check. Deleting it still refused the model, but with Constraint 'coupling_link0' in the message — which is what the upfront checks exist to replace. The assertion moved onto the message text, and the suite now fails without the guard (9f450b3).

Before implementing the link-frame law I checked every piecewise: block in examples/ and tests/typesetting/golden/ against it. All nine links were already exact, so it refuses nothing correct today.

Two tests were passing on the wrong sentence. Both convex and lp cases matched one shared message, so convex was asserting lp's reason. They are now parametrised over (method, match) with a note that neither reason may stand in for the other, so collapsing the messages again fails the suite.

Coverage moved, not dropped. Two tests asserted the old sign cap. The two-bounded-links case keeps its row in the refusal table under every-link-bounded, the reason that now refuses it; the lp three-link case keeps its row under lp-with-three-links.

This table was measured before the two merges with main, the points: fold and the check split described below, and was not re-measured after them. The fold's own guards each land with a test: the count on the frame rows (…reaches_the_weights_as_written_and_the_frame_rows_as_a_count), the parenthesisation an edge row's shift needs (…is_grouped_where_an_edge_row_shifts_it), a ragged mask on a split block (…a_split_block_is_ragged_on_the_curves_own_frame), and the stray-dim refusal reaching a refined link's values (…naming_a_refined_links_values_is_refused). Coverage of the old points: dtype and nomination checks is dropped, not moved: a float parameter in a where: reads as "has a row", which is the nomination. The check split moved no guard without its test; #623 lists each.

The base, and what carrying it took

The base was #566's branch. #566, #589, #592 and #602 are all on main now, as squashes, so not one of this branch's base commits is an ancestor of main. Merged, never rebased: the hard rule here is never to force-push.

A straight git merge main reads that squashed history as unrelated work and conflicts in 27 files, most of them on #566's own lines. The merge is resolved instead as this branch's own diff — three-way against the commit where it last took #566 in — replayed onto main, which leaves 13 files and 20 hunks to settle. main is an ancestor of the result, so the PR diff is this branch's work alone.

Earlier, #585 renamed the program's where vocabulary and expression nodes on main while this branch was building. The same rename was applied here first, as one commit, so that the #566 merge agreed line for line instead of conflicting on every one of them: merged straight it conflicted in 86 places.

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

• PiecewiseDeclaration.checks is gone; where: stays. feat(language): a model writes its formulations out on request, and states what each assumes of its data #602 retired program.Check — Increasing, Curved, AtLeastTwo, Contiguous — for assumptions: entries the block derives as where-text. The branch's mask keeps its job: it is PiecewiseDeclaration.where, and it is what the derived conditions are asked under.
• method: adjacency no longer writes its own binaries. feat(language): a model writes its formulations out on request, and states what each assumes of its data #602 states it as the sos: block sos2 states and writes that out, so the branch's hand-written pick and adjacency rows go. The set's row is sum(seg, over=bp) <= 1, which reads 0 <= 1 where no binary exists, so it needs no mask of its own — where the block's own rows would read 0 == 1 and do carry one. test_a_where_reaches_every_row_the_block_emits[pick] moved to test_the_row_the_set_states_needs_no_mask_of_its_own, which asserts both halves.
• Resolved.piecewise collided outright. feat(language): a model writes its formulations out on request, and states what each assumes of its data #602 keys it by declared block and holds the link expressions; this branch keys it by written-out block and holds the mask. Both are kept, the second as Resolved.expanded_piecewise. A block is in one mapping or the other, never both: writing it out is what moves it.
• The expansion record is a private attribute now, set after validation. So the pass that types a written-out block's where had nothing to read. expand_piecewise and expand_sets drop the cached resolved once the records are in place, and the pass runs again with them.
• _ExpandedSpec is gone; the records hang off Spec itself.
• sos:'s over: → along: had to reach the three curves feat(language): a model writes its formulations out on request, and states what each assumes of its data #602 added to the golden model, the see-an-expansion.md how-to, and sos.emit.
• big_m on sos: is gone — feat(language): a model writes its formulations out on request, and states what each assumes of its data #602 scales the linking rows by the member's own bounds — and the branch's two big_m refusal cases go with it.
• docs/howto/curve-by-hand.md is deleted here and its nav row with it; feat(language): a model writes its formulations out on request, and states what each assumes of its data #602's see-an-expansion.md stays.
• The convex and lp prose on the reference page was rewritten on both sides. The merged text keeps this branch's reason for the two-link rule and feat(language): a model writes its formulations out on request, and states what each assumes of its data #602's sentence on what the bounded link's sign decides.

A second merge (32ddc35) carries alpha.112 to alpha.116: #609, #612, #615 and #618. Four files conflicted, all on the lines #609 removed:

• A curve emits no parameter (fix(language): an expanded curve declares only the parameters the file declared #609). The branch's masked lp rows sat on the derived _starts/_ends parameters and recorded them on ExpandedPiecewise. They now sit on the edge predicates main writes, with the block's own where: conjoined by _all_of as before. The record of an expanded block is the block itself, so Resolved.expanded_piecewise types pw.where off it and declaration_of takes the block.
• A program is lowered from the model as it arrived (feat(lowering): a program is lowered from the model as it arrived, and a curve left as written is refused #618). Three of this branch's tests passed a model with a block to to_program; they expand first.
• along: reaches what main added: the twelve tests/expand/ fixtures from docs(expand): every formulation expands to a hand-written file the suite compares whole #611 and fix(typeset): a set prints under the name its sos: block declares #615's set-label test. The how-to page is regenerated from them.
• The chord row's unmasked where reads position(bp) > 0 rather than position(bp) != 0, the same rows.

The fold (d182f28) removes points: from the model, the schema and the expansion. Resolved.piecewise holds each declared block's links and its mask, so the typesetter prints a ragged mask on the breakpoint set and a frame mask on the quantifier; the latter was not printed before.

The cleanup (96eb703, named in 89a702c) puts the mask behind one class. piecewise.CurveMask answers each shape of row: text as written for the weights, frame for the position tests a non-ragged mask is conjoined onto, exists for the rows over the frame alone (which is also what PiecewiseDeclaration.where carries, so a consumer's conjunction stays over the frame), and neighbours(), edge() and interior() for the rows and assumptions that sit on a curve's edges. It is not a program.Mask, because the expansion writes text and hands it back to the loader, and nothing prints a resolved mask back into the where grammar; it is named for the curve because every declaration has a where:, and what a curve alone has is one mask read by three shapes of row.

The check split (#623, merge e4962e6) is described above and in that PR. It flips the load order in Spec._validate_expressions to resolve the file before expanding it, which is what lets the expansion read the typed links and mask instead of parsing them; a fault in a link is still named against the link the file wrote, by resolution's own context.

Gates, and what could not be run

Run on 89a702c, and on #623's head before its merge:

gate	result
pytest -q -n auto	1615 passed, 1 skipped; 1619 with #623's new test
ruff check	clean
ruff format --check	clean
pyrefly check	12 errors, all missing-import for pydantic and yaml stubs from the venv layout, the same count as main
mkdocs build --strict	aborts only on fetching docs.python.org/objects.inv through the proxy (403); no other warning
the schema, the golden output and the five page generators	regenerated and read: the schema drops points, the how-to's two assumption descriptions name where:
typos, reuse lint, taplo, zizmor, prettier, compile-tex	not run, for want of the tools; CI ran them green on 89a702c and on #623
pixi run ci as a whole	not run locally

Three defaults departed from, each deliberately:

1. "Every command runs under pixi run." This environment's egress proxy refuses pixi.sh 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.
2. "Run pixi run ci before pushing." Not possible for the reason above. CI will be the first to run compile-tex and the pinned toolchain.
3. "One issue, one PR." This carries piecewise: needs a where: #77 and piecewise: a link should be a row, and its sign a column #82 rather than stacking them, because the session was given one designated branch.

Deliberately not done

• An n-ary convex. Its rows would serve any number of links; only the exactness certificate stops at two. Shipping it uncertified would be a new silent-wrongness class, which is the thing the curvature assumption exists to prevent, so it stays refused — but the refusal is about the certificate, not the formulation.
• An explicit spelling for the two refused broadcasts. A link finer or coarser than its row may one day be wanted. The refusal is where that spelling would hang, and by then there will be a real model to design it against.
• A monotonicity check for a pinned link under adjacency/sos2. A pinned link fixes the operating point uniquely only where its values are strictly increasing; where they are not, the solver picks whichever consistent point suits the bounded links. That is unchanged by this PR — those methods never checked it — and widening it is a decision of its own.
• A ragged mask on a walked block. points: on a block with a walked link was allowed; a where: beside a walked link is refused, ragged or not, because the walked row cannot read a mask over the frame it has walked out of. It lifts with may a where: carry operators — relocation through a lookup, reduction over a dimension it does not span #258 like the rest of that refusal.
• docs/howto/curve-by-hand.md is deleted. Its premise — "a piecewise: block lists its links in the file, so it cannot say this" — is now false, and the form it taught drops every piecewise data guard. Its coverage moved to examples/piecewise_coupling.yaml and the reference page's refinement section.
• No assumptions: entry is derived for a refined link. feat(language): a model writes its formulations out on request, and states what each assumes of its data #602 derives a block's conditions from the two links a curve is read as; a refinement is one row per fine coordinate, and what the conditions should say there is a decision of its own. convex and lp, the two methods that state a shape, refuse a refinement already.
• lpspec. It follows on its next math-spec bump, which also has to take the Check retirement and the four predicate nodes added since alpha.108.

Why

fluxopt needs a curve tying however many flows a converter has, one to five, in one system. Written out by hand that works, but it loses every piecewise: data guard — lpspec measured a single dropped breakpoint row solving at 7096.25 instead of 5990.0, silently.

Trying it with the block instead exposed that the frame was inferred from the links, so a link carrying flow built one curve per flow rather than one per converter, and said so nowhere. That is the class this PR closes: the frame is something the file states, a link says how its row refines it, and everything that used to broadcast around it is refused with a named rewrite.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hh3uK8SqVcXKuLnYHAjrVW

https://claude.ai/code/session_01JPqtQuarRGDmX2WrNVuKDP

https://claude.ai/code/session_01EQHKbwGtpVBm6yKHzrjMx9

https://claude.ai/code/session_01GNZN57CR8oGTVpRmpXF8YZ

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34713017 | 📁 Comparing c9d1221 against latest (3317ecf)

  🔍 Preview build  

48 files changed · + 7 added · ± 40 modified · - 1 deleted

+ Added

• examples/piecewise/index.html
• examples/piecewise_adjacency/index.html
• examples/piecewise_lp/index.html
• examples/sos/index.html
• howto/see-an-expansion/index.html
• reference/language/assumptions/index.html
• reference/math_spec/sos/index.html

± Modified

• CHANGELOG/index.html
• contributing/index.html
• examples/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• and 30 more...

- Deleted

• howto/curve-by-hand/index.html

[FBumann]

Prompt: Keep #569's design and re-port #638's load-time checks onto it, which also reverts the points: language. … YOu can also close and redo the contents!

Note

The following content was generated by AI.

Closed as superseded by #630, which carries every commit of this branch and now has main merged in with this design kept. The points: language is reverted there, and #638's load-time checks are on the block's own lines.

---

Generated by Claude Code