feat(program): a model says whether a horizon may be solved a window at a time, before a driver cuts one

[FBumann]

Prompt: "I really like both 2 AND 3 … Keep it simple and encapsulated, like the rest of the codebase" — and, on the shape it took, "Why does separability not live on program? … I think it should" and "Why not a dict with each dim as a key?"

Note

The following content was generated by AI.

What this changes

One dataclass and one attribute, beside the Footprint the program already answers.

program.separability['snapshot'].windowable   # True
program.separability['snapshot'].halo         # 1 — two windows overlap by a row
program.separability['snapshot'].coupled      # {} — nothing ties the axis together

A rolling-horizon or myopic driver asks one thing of a model before it starts: would windowing change the answer? Storage carried over a snapshot survives being cut into overlapping windows. An annual budget does not — and both window into pieces that solve, so nothing else says so.

pointwise only                     windowable=True  halo=0
storage carried over one row       windowable=True  halo=1
cyclic storage                     windowable=False constraint 'carry': wraps around snapshot,
                                                    so its first row reads its last
an annual budget                   windowable=False constraint 'annual': sums over snapshot

Why it belongs here, and in this shape

It is the locality ceiling.md already argues in — pointwise, bounded halo, global — asked about a dimension rather than about an operator. The language owns those words and never answered the question with them.

Derived, not declared. Not a PiecewiseDeclaration: nothing writes it, and a separable: key would let a file claim what the compiler can check. The precedent is Footprint.

On the Program, not the Spec. Locality lives in Translate, Window and Sum — lowered nodes. A Spec holds expression strings, so answering there means parsing twice.

Two arguments in this section were wrong, and the review corrected both. I first put it in a module beside boundedness.py and defended that on dependency direction; where_parser imports only errors and expression_parser, so there was no direction to protect, and Program.dimension(name) already shows a parameterised accessor is idiomatic here. Then I defended a function over a cached_property on the grounds that a property would have to walk every axis eagerly — and dismissed the cost with a measurement of ten walks read as one. Measured properly, on the shipped example: one walk answering every axis is 831 µs against 844 µs for a single axis, because every construct that ties an axis names the axis it ties. So the walk is per-program, not per-dimension, and the shape is a cached_property returning a mapping keyed by dimension.

The crux

A reduction means opposite things by position. In a constraint, a sum over the axis ties every window to every other. In the objective it is additively separable — an objective is a sum, so summing the windows' objectives is summing the model's. A verdict treating the two alike would refuse every windowable model there is; the mutation table below shows it fails six tests.

Two bugs the tests caught, and one was the motivating case

A cases: mask did not reach the walk. The first version reported a cases: block seeded with position(h) == 0 as windowable. It is not: the seed fires once over a horizon and once per window. children(Cases) returns a region's value and not its when, so no expression walk reaches a mask written inside cases: — and a rolling horizon seeding its opening state is exactly that shape. The masks a block is judged on are now collected during the walk rather than read off the declaration alone. Worth knowing for any future analysis pass: that is a trapdoor in children, not in this module.

Converting to a mapping introduced a second one. Sum.over is a tuple, and the per-axis version had only ever been asked about one axis at a time. A mutation coupling only the first axis of a multi-axis reduction survived all 902 tests — a hole the conversion opened and nothing existing could see. test_a_reduction_over_several_axes_couples_every_one_of_them is that hole closed.

What it does not decide

Whether the modeller wanted the window. A position(t) == 0 seed is a horizon's start or a window's start depending on intent, and both are models somebody means. This reports that windowing changes which rows it selects and stops.

What lpspec removes or changes

Nothing today; one thing worth having. solve_over already sweeps an axis, and strategy.py already drives a build a slice at a time — neither asks whether slicing is sound, because nothing could answer. A driver can now refuse, or warn, before solving windows whose answer is wrong.

That is the whole of it: no verb changes, nothing binds differently, and a consumer that ignores this is exactly as correct as it is today.

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 905 passed, 0 skipped (885 on the base — 20 new). reuse, typos, prettier --check, render_tex (27 models) and mkdocs build --strict were run on the top of the stack (#250), which contains these commits.

The reading.md section is executed — that page's Python blocks run against a real model and every # value line is checked. Its own example is the page's own model, which separates along neither axis, and the report names the three constraints the piecewise: block emitted — a coupling introduced by an expansion, named under the name the expansion gave it.

Method for the 831 µs / 844 µs above: timeit on the shipped reading.md model, _separabilities(program) against the single-axis version at the same base commit, best of five, cache bypassed each call. It is the whole reason the walk is not held per dimension, so it is quoted here rather than left in the tree.

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.

Mutation table

Mutation	Result
the objective is treated like a constraint	6 failed
a wrapped shift reports a halo instead of coupling	1 failed
a parameter offset is treated as a literal	3 failed
cased regions stop contributing their masks	1 failed
a sum_back halo is the width rather than width − 1	1 failed
only the first axis of a multi-axis reduction couples	1 failed (0 before the test above was added)
restored	all green

Deliberately not done

No public where-walker. A where tree is not an expression tree, so this needed a small recursion of its own. It is private, with one caller; it belongs beside children in where_parser the day there are two, and the docstring says so.

halo is a plain int, never int | None. It is how far the program reads across the axis, which is true whether or not anything couples — overlap alone is only enough where nothing does. The two questions are already separate (windowable, then halo), and a None a caller must check twice is worse than one they read after the verdict. An earlier version of this description, and of the docstring, said halo was "meaningful only where nothing is coupled"; that was wrong about what the number is, and the review fixed both.

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

---

Generated by Claude Code

Closes #298

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34348505 | 📁 Comparing 76338ab against latest (a9237ec)

  🔍 Preview build  

39 files changed · + 2 added · ± 36 modified · - 1 deleted

+ Added

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

± Modified

• index.html
• CHANGELOG/index.html
• examples/index.html
• about/ceiling/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
• and 26 more...

- Deleted

• reference/math_spec/where_parser/index.html

[FBumann]

Superseeded by #374