feat(language): a decided variable becomes a supplied number, so a subproblem is a call rather than a second file

[FBumann]

Prompt: "I really like both 2 AND 3 … Keep it simple and encapsulated, like the rest of the codebase"

Note

The following content was generated by AI.

What this changes

subproblem = fix(model, 'cap')            # `cap` is now a number somebody else chose
myopic     = fix(model, *already_built)   # a myopic step fixes many at once

A myopic pathway, a rolling horizon and a Benders subproblem share one move: a variable stops being a decision and becomes a supplied number. docs/about/decomposition.md says it outright — "that single change is the whole of the decomposition" — and written by hand it is a second file to keep in step with the first.

The name does not move, so every expression naming it goes on reading. Every name is given in one call and the model is revalidated once at the end of it, which is the shape the motivating workflows actually have: a myopic step fixes what earlier periods built, which is many.

Why it is not four lines in a driver

I originally proposed this as a Spec → Spec toolkit above, and demonstrated a four-line version. Testing it changed the answer: the four-line version is wrong twice, and once silently.

naive fix drops the mask. what did 'cap' become?
   dims=['g'] dtype='float' coverage='total'

the variable it replaced was masked: p_max > 0
so rows where p_max == 0 have NO value — but the parameter claims coverage: total

and a fixed binary became dtype: float — a float, where the values are 0/1

• A variable masked by where: has rows that do not exist. As a parameter those coordinates have no value, so it is coverage: masked. The obvious rewrite leaves it total, which claims a number everywhere and binds cleanly against data that has none — the exact class feat(language): a parameter says whether its table must cover every coordinate, so a row lost in preparation is not read as a mask #243 exists to prevent.
• A binary or integer variable becomes an int parameter, never a float. A bool would be a mask, and declarations.md is explicit that a mask is not something a constraint multiplies by.

Two drivers writing their own would each decide these, and differently. By "would two consumers answering separately be a bug?" that is one home, and the home is here.

Where the line falls

fix follows; it does not decide. That is why it is in the language and elastic relaxation is not: where slacks go and what they cost is a modelling choice, closer to a formulation than to a rename.

It is also not every half of a decomposition, which my first docstring overclaimed and the tests corrected. A Benders master has the dispatch gone, not fixed. Fixing every variable a constraint names leaves a row that decides nothing — and because fix revalidates, the language says so at the call:

Constraint 'k': neither side of the comparison carries a variable, so the row decides nothing.

Bounds are dropped, the one thing lost: they constrained a decision the model no longer makes, and whether the supplied numbers respect them is a question about data.

What lpspec removes or changes

Nothing. No verb changes and nothing binds differently.

What it gains is that examples/benders/, examples/myopic/ and examples/rolling/ currently ship a hand-written variant file each — sub.yaml beside monolith.yaml — and the subproblem ones become fix(monolith, 'cap'). That is a real reduction in files kept in step by hand, and it is the drift docs/about/decomposition.md warns about.

The masters stay files, because a master is the other move.

Verified

Toolchain at the versions pixi.toml pins: ruff format --check / ruff check (0.16.1) clean, pyrefly (1.2.0) 0 errors, pytest -q 915 passed (905 on the base — 10 new). reuse, typos, prettier and mkdocs build --strict were run on the top of the stack (#250), which contains this commit.

Not run: zizmor, taplo, and the tectonic half of compile-tex. mkdocs build --strict needed docs.python.org/objects.inv dropped from mkdocs.yml, which this environment's proxy refuses; that affects cross-links into CPython's docs and nothing in this diff.

Mutation table

Mutation	Result
a mask does not become a coverage claim	1 failed
every domain becomes a float	2 failed
the rewritten model is not revalidated (model_construct)	7 failed
restored	all green

The third needed care: my first attempt at it was a no-op that passed the whole suite, which would have recorded a catch that did not happen. tools/mutate.py cannot express "skip validation", so it was taken by hand through Spec.model_construct.

Deliberately not done

No relax. It belongs above, per the line drawn earlier — and shipping it here would blur the distinction this PR's argument rests on.

The description is carried, the bounds are not. A description describes the quantity, which the fix does not change; bounds describe a decision that is gone.

A name given twice raises rather than deduplicating. fix(m, 'cap', 'cap') refuses on the second, because after the first it genuinely is not a variable any more.

Changed in review. An earlier version of this description defended taking one name per call, on the grounds that a variadic form was an option nobody had asked for. Reading it back against the workflows the module docstring names, that was wrong the other way round — a myopic step fixes many, and composing calls costs a full revalidation each. fix(model, *names) is what the PR now ships; fix(fix(m, 'a'), 'b') still composes and is asserted to agree with fix(m, 'a', 'b').

Stack: eighth, on #248 → #247 → #246 → #245 → #244 → #243 → #242 → #168.

---

Generated by Claude Code

Closes #303

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34317538 | 📁 Comparing 3348d70 against latest (a9237ec)

  🔍 Preview build  

30 files changed · + 3 added · ± 27 modified

+ Added

• examples/commitment/index.html
• reference/math_spec/exclusivity/index.html
• reference/math_spec/transforms/index.html

± Modified

• CHANGELOG/index.html
• examples/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• examples/pypsa_losses/index.html
• examples/pypsa_multi_period/index.html
• examples/pypsa_quadratic/index.html
• examples/pypsa_stochastic/index.html
• reference/notation/index.html
• reference/language/declarations/index.html
• and 17 more...

[FBumann]

Note

The following content was generated by AI.

Closed at the author's request, in a sweep of the open PRs. Closed rather than retargeted, for the same reason as #244: the base branch never landed.

• The base is claude/parameter-coverage, which is feat(language): a parameter says whether its table must cover every coordinate, so a row lost in preparation is not read as a mask #243, closed unmerged on 2 September.
• Draft since 29 August, 17 files, conflicted against main.
• fix rewrites a variable into a parameter, so it reads coverage: and the declaration blocks — both of which have moved since. feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245 carries coverage:, and feat(language): a relation between dimensions, walked in the direction each call names #437 renamed lookups: to relations:.

#303 stays open. The finding this PR is built on is the durable part, and it is not in the diff: the four-line version in a driver is wrong twice, silently — a masked variable becomes a total parameter that claims a number everywhere, and a binary variable becomes a float. That is the argument for fix living in the language, and it should be re-made against current main.

---

Generated by Claude Code