feat(language): a piecewise block states its dims and names its links, and its where reaches links that walk a relation

[FBumann]

Prompt: "Review the PR about piecewise. Can you imagine a better or more capable api? #569" … "Do a stacked PR" … "It does mix curve and non curve converters!" … "Should we then combine 630 and 635?" — "Do it" … "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!" … "Lets try to simplify 630 as much as possible. Can we reuse existing things instead of adding new concepts, classes or methods?" … "sos: over → along rename is right / cone typesetting for a block with three or more links is also right" … "I think we should land the "along" change for sos on main independently!" … "Rebase 630" … "Rebase onto 661" … "Get #630 up to date" … "782 merged"

Note

The following content was generated by AI.

Based on main. #661's stack merged, and main is merged in up to #782.

What this changes

Every block states dims:. Links are keyed by name, and a link finer than the curve always walks a relation. The block's where: says which curves exist and how far each runs, and reaches walked links through their relation, so only converters with a curve get one. This PR carries #569, now closed in its favour, with main's points: reverted in favour of where:.

piecewise:
  operating_point:
    along: bp
    dims: [converter, snapshot] # required: one curve per coordinate of these
    where: has_curve # only some converters run on a curve
    links:
      rate: { expression: rate, values: bp_rate, by: converter_of, over: converter, into: flow } # row: operating_point_rate

The expansion writes this row:

operating_point_rate:
  dims: [flow, snapshot]
  where: at(has_curve, by=converter_of, over=converter, into=flow)
  expression: (rate) == sum(at(operating_point_lam, by=converter_of, over=converter, into=flow) * bp_rate, over=bp)

Breaking for the file language

• piecewise: blocks say along: and where:; main's points: (a bool parameter naming how far each curve runs) is gone, since where: says it.
• dims: is required on a block, and links: is a mapping: the emitted row is <block>_<link>.
• A sign on a link among three or more is admitted, and prints as a cone; main refused it.

The sos: over → along rename landed on its own in #646 and is no longer part of this diff.

What the program carries

A program mirrors the spec, so a piecewise: block still in the spec is a typed curve under program.piecewise. Here that curve is PiecewiseDeclaration(along, links, method, frame, where, activity), where frame is dims: as written and where the typed mask, with ragged saying whether it reads along. Each Link carries its name, its typed expression, its values, its sign, the walk (by, over, into) and two facts lowering decides: dims, the row the link builds, and reads, whether that row reads the where through the relation. The expansion and the typesetter read those and compute nothing of their own.

Where a rule lives	What it decides
validation.reference_errors (_piecewise_references, _piecewise_link_shape, _piecewise_walk_shape)	along, dims:, each values parameter, a walk's relation and columns, and the gate exist as the block needs them
lowering.lower → piecewise.declaration_of	each link's row; the expression carries exactly it; the values parameter varies along it and along only; the where tests dims: and along only; a walked row reads the where through its relation or not at all
validation.emitted_name_errors	no link names a row the block writes for itself, and no emitted name is one the file declares
piecewise.assumptions_of(name, curve, where)	what the method assumes, from the curve as lowered and the where as the file wrote it, since a typed mask has no text

What #638 and #643 decided at load, re-ported onto this design

Rule	Where it lives here
a breakpoint parameter is float or int	_piecewise_link_shape
an lp x-link carries a variable, or the domain rows decide nothing	piecewise.lp_domain_refusal, on the named link
an undeclared along: is one line, not one per link	_piecewise_references
a link, a gate or a where: outside the frame is refused on the block's line, never on an emitted row	declaration_of, as the spec loads
PiecewiseExpansionError no longer exists	a block is refused as a SchemaError or a DimensionError like any other declaration
an emitted name that collides names the block and the declaration	emitted_name_errors, shared with sos:

Each change, and the finding it answers

Change	Why
dims: required. A missing dims: is refused, and the message names the rewrite. The inferred frame, _frame, _widen and the second rewrite message go	#569 says "the frame is something the file states", but it still inferred the frame where no link was refined. Variables and constraints already require dims:
The gate may not add dims to dims:. A gate over fewer dims switches every curve it covers	activity: widened a declared dims: [snapshot] to [snapshot, generator] without a message
links: is a mapping. The emitted row is <block>_<key>, not _link<i>. A key that is not a name is refused, and so is a key whose row name the block already writes (convexity, lam, adjacency_below, …). Refusals name link 'power', not link 0	Positional names renamed constraints when links were reordered
The bare into: split is removed. A link row finer than dims: is a walk with by, over and into together; into: alone is refused	into had two meanings; in at and sum it only names produced columns. No example or known model used the split
Walk checks run at load. over must reach a dim of dims:, into must not reach a dim of dims: or along, and a column may not repeat	A walk into a dim of dims: was refused only by the emitted row, naming Constraint 'coupling_link0'. into: [flow, flow] loaded
A block where: reaches walked links. A walked row reads the mask through its relation, at(<where>, by, over, into), when the mask carries every dim the walk consumes or joins on. A ragged mask goes through as at(count(<where>, over=bp) > 0, …). A mask carrying none of them (e.g. snapshot only) reads as written. A mask carrying some and not the rest is refused, naming the missing dims. A walk into several columns reads it as at(…, into=[flow, effect]), which #782 lets a where string parse	#569 refused a block where: beside a walk. So a model with some converters on a curve built weights and binaries for every converter
A walked link checks its own breakpoints. <block>_<link>_complete asks for its values only at the rows it reads the curve at: under the mask read through the relation, or where the relation has a row. <block>_complete keeps the links on dims:. The per-link name is reserved	Asked with the other links, bp_rate was demanded at every flow, including flows of converters with no curve
Every derived assumption carries the where:. With a frame-only mask it goes on as written, or conjoined with the position test. With a ragged mask, the frame-level conditions take count(where, over=bp) > 0	The mask lived only on the program's curve record. After expand() → to_yaml() → load, _complete and _breakpoints were asked at generators with no curve
Typesetter: the quantifier is dims:. A walked link prints as a family, (rate_{f,t})_{f ∈ F : converter_of(f) = c}. A block with more than two links and a sign prints as (…) ∈ pwl(…) + {0} × ℝ≥0 × ℝ≤0, with three new operators: origin, nonnegative, nonpositive	pinned = links[1 - bounded] assumed two links: q ≤ pwl(…)(q) dropped p and c. The coupling example printed ∀ t, g, f, putting every flow on every curve
Canonical form: a block's links are a mapping, so the list form's expression is normalised per named link, and a walk's mapping is left as it is. Link order stays as written	main's canonical.py (#731) read links as a list, and indexed a walk's mapping with [0]
examples/piecewise_coupling.yaml is fluxopt's mixed system. A CHP on a curve sits beside a fixed-ratio boiler, and one has_curve is read both ways: the curve reads it, and fixed_ratio reads NOT at(has_curve, …)	fluxopt mixes converters on a curve with converters at a fixed ratio
Docs: the reference page, reading.md, the examples, the golden model (chp_curve, and bus_curve masked), the schema and the generated pages	The key table said "two or more links", and the refined-link table had two conflicting where: rows

History: the merges of main, the simplification, and the rebases

main at alpha.118 plus #626 through #643 was merged in, then alpha.119. Nine files conflicted, and each took main's side except the piecewise design. The thirteen tests #643 added for points:, list links and link 0 now speak where:, named links and link 'p'.

The simplification then folded what the branch had added beside a main counterpart back into it: Curve, check() and five module-level emitters into _Block; Names and ASSUMED into Emitted; CurveMask into the three mask helpers plus is_ragged; ResolvedPiecewise and Resolved.expanded_piecewise into one piecewise_where field; PiecewiseDeclaration.where, declaration_of(where) and the exists-mask resolution of written-out blocks are gone, since the assumptions carry the mask, so the program's curve record is main's.

After #646 merged, the branch was rebased onto main as one commit carrying the same tree: the 78 commits held two merges of main and would not replay one by one. After #654 merged, the commit was rebased again: the single-link and the four-element cases #654 added now write a mapping and meet the same messages, and the case refusing a sign among three links is dropped, since this PR admits it and the golden model's chp_curve covers it.

Onto #661's stack. That stack moved lowering into Spec.program, removed Resolved, and made the program carry a typed curve, so ten files conflicted and the piecewise design was re-ported onto its shapes rather than merged hunk by hunk. What moved: the reference rules from Spec's validators into validation.reference_errors, as the stack keeps every such rule; the fit rules from _Block.__init__ into declaration_of, which lowering calls to build the curve, so _Block only writes; Resolved.piecewise_where into PiecewiseDeclaration.where; is_ragged into PiecewiseDeclaration.ragged; walk_reads and through(reads=) into Link.reads; and the typesetter reads the program alone, as every other walk on the stack does. curve_frame, which the stack kept for main's design, is gone with the design.

Up to date with main at #780 (a merge commit, no force-push). main had renamed the package to mathspec and model.py to spec.py, renamed the test fixture override to varied, moved docstring links from Sphinx roles to [`name`][], and called a file a spec. Fourteen files conflicted. Each kept this branch's piecewise design and took main's names, links and wording around it. canonical.py and one case in test_canonical.py were taught the link mapping. docs/howto/curve-by-hand.md stays deleted, and the four curve pages sit beside main's component library in the examples index and nav. The PR's line is now under ## Upcoming version in CHANGELOG.md.

#782, and fluxopt's investment curve. A block where: beside a walk into: [flow, effect] failed the load on the assertion that what a method assumes is stated in the language: the where grammar could not parse the list the walk reads the mask through (#781). #782 fixed the grammar on main, and a second merge brings it in, with CHANGELOG.md the only conflict. test_a_block_mask_reaches_a_walk_into_several_columns loads fluxopt's investment cost curve (fluxopt/fluxopt#26), checks the where: on its cost row and on its breakpoint check, and loads the expansion again. With _where_parser.py from before #782 it fails on that assertion.

The generated files were regenerated after each rebase and merge.

Gates, and what was not run

On the head 21e31bd, in a uv venv (Python 3.12) with the pinned tool versions, since pixi cannot be installed here:

Gate	Result
pytest -q -n auto	2696 passed, 2 skipped, the docs tests included
ruff check, ruff format --check (0.16.1)	clean
pyrefly check (1.2.0)	0 errors
prettier --check on CHANGELOG.md, typos	clean
schema, golden output, generated pages	regenerated; no diff
zensical build --strict (0.0.63)	run on d97fb41, not rerun since: one issue, pathlib.Path unresolved, because the proxy refuses docs.python.org's inventory
compile-tex	not run: no tectonic here

Decided, and deliberately not done

• The cone typesetting for three or more links with a sign stays, as decided: it fixes a case main mis-prints, at the cost of three format operators and two walk methods.
• A where: per link. With the block mask reaching walked rows, and one relation per role for a subset of flows, no model needs one yet.
• n-ary convex/lp, and walks under them: unchanged from feat(language): a piecewise curve applies to the members that have one, and ties as many expressions as the data says #569.
• An activity: gate that walks a relation is accepted as a follow-up PR on top of this one, not added here.
• A link that adds a dimension to the curve waits for Piecewise investment effects fluxopt/fluxopt#26.

Why

It follows the review of #569: only the block decides the curves, a link that fans out walks a relation as at does, and rows are named rather than numbered. fluxopt mixes converters on a curve with converters at a fixed ratio, one to five flows each, and examples/piecewise_coupling.yaml now holds that system. main had meanwhile said how far a curve runs with points:; this design says it with where:, and the choice went to where:.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HxoXSQCyrcDs6vuRk3x6tz

https://claude.ai/code/session_015h57WkBDnpxrknuJ5zZy9F

https://claude.ai/code/session_015VUkQfE5dT7mEGoTQXSxN3

[read-the-docs-community]

Documentation build overview

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

  🔍 Preview build  

60 files changed · + 8 added · ± 29 modified · - 23 deleted

+ Added

• first-model/index.html
• examples/piecewise/index.html
• examples/piecewise_adjacency/index.html
• examples/piecewise_lp/index.html
• examples/sos/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/program/index.html

± Modified

• index.html
• CHANGELOG/index.html
• contributing/index.html
• examples/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• about/what-counts-as-public-api/index.html
• examples/dispatch/index.html
• examples/pypsa/index.html
• howto/check/index.html
• and 19 more...

- Deleted

• howto/curve-by-hand/index.html
• reference/math_spec/advice/index.html
• reference/math_spec/boundedness/index.html
• reference/math_spec/degree/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/exclusivity/index.html
• reference/math_spec/expansion/index.html
• reference/math_spec/lowering/index.html
• reference/math_spec/model/index.html
• and 13 more...

[FabianHofmann]

@FBumann I am seeing this PR and its where implemention for piecesewise as required for the completion of the pypsa yaml. So I guess we can focus on bringing in piecewise after the refactoring again.

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34831361 | 📁 Comparing 2b91913 against latest (fcb654d)

  🔍 Preview build  

17 files changed · + 4 added · ± 12 modified · - 1 deleted

+ Added

• examples/piecewise/index.html
• examples/piecewise_adjacency/index.html
• examples/piecewise_lp/index.html
• examples/sos/index.html

± Modified

• changelog/index.html
• examples/index.html
• examples/dispatch/index.html
• howto/see-an-expansion/index.html
• reference/notation/index.html
• reference/program/index.html
• reference/reading/index.html
• reference/language/absence/index.html
• reference/language/assumptions/index.html
• reference/language/declarations/index.html
• and 2 more...

- Deleted

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

[FBumann]

Prompt: "Discuss hs request with me" … "Do all 3"

Note

The following content was generated by AI.

Feedback from porting fluxopt: a walked activity: gate is accepted as a follow-up PR on this one. The where: crash is a main grammar gap, filed as #781. A link that adds a dimension waits for fluxopt/fluxopt#26.

Each ask, checked against the code

1. activity: reads its binary through a relation. Accepted, as a stacked follow-up.

A unit-commitment converter's on/off binary is running[status_entity, time, period]. The curve is on converter, and pw_status_of maps one to the other. _piecewise_references admits only a declared binary variable whose dims all lie in dims:, so fluxopt declares a copy, pw_on, and a constraint that only re-indexes it. The ask:

activity: {variable: running, by: pw_status_of, over: status_entity, into: converter}

• It uses the same keys and load checks a walked link already has.
• A converter with no row in pw_status_of stays ungated. The second gate row needs where: NOT at(running, by=pw_status_of, over=status_entity, into=converter), and that where: loads on this head today.
• It goes in its own PR on top of this one: one issue, one PR, and the workaround is correct in the meantime.

2. A block where: beside a walk into: [flow, effect] fails with an internal assertion. The cause is on main: #781.

Reproduced on this head: the block loads without where:, and with where: has_cost_curve the load fails with SchemaError: Assertion failed, what a method assumes is stated in the language. The mask is read through the walk as at(has_cost_curve, by=cost_of, over=cost_curve, into=[flow, effect]). On main, a plain constraint with that where: fails to parse too, and into=flow loads. Once #781 lands, this PR takes main and adds the block as a regression test. A refusal of its own goes in here only if this PR merges first.

3. A curve per flow whose cost link adds effect. Not on this PR.

The shape is dims: [flow, period] with a link over [flow, effect, period]. The loader cannot tell it from a link that carries time on a curve without time, which pins one operating point across every step. The ask is a walk whose over: consumes nothing, through a relation keyed [flow, effect]. That changes the language, and nothing needs it until fluxopt/fluxopt#26 is scheduled. The workaround today is a curve on its own cost_curve dimension, with two relations.

---

Generated by Claude Code