feat(api): a sweep can be cut by several axes at once, each carrying its own state, such as a rolling horizon per scenario or a pathway whose decades roll through their hours

[FBumann]

Prompt: Is our api and architecture suited to extend to solver multiple Axes at once? rolling horizon per scenario etc?

Prompt: If generalizing and refactoring the code makes for the better end result, we can do it!

Prompt: Not sure if this api is intuitive and flexible enough? WHat about slicing per scenario AND period? Or doing 2 Windows together?

Prompt: Can we combine them into one PR?

Note

The following content was generated by AI.

solve_over takes a tuple of axes, outer first, each with its own carry= (#1980), and any of them may be windows. A carry reaches its axis's next label; an executor runs independent chains concurrently. Each chain answers exactly as its own sweep would.

sweep = sps.solve_over('window.yaml', sources, (
    sps.EachCoordinate('scenario'),
    sps.EachWindow('snapshot', steps=24, lookahead=24, into='t', carry={'soc_initial': 'soc'}),
))
sweep.primal('soc')    # (scenario, snapshot, value)

pathway = sps.solve_over('pathway.yaml', sources, (
    sps.EachWindow('period', steps=1, lookahead=1, into='y', carry={'existing': 'capacity'}),
    sps.EachWindow('snapshot', steps=24, lookahead=24, into='t', carry={'soc_initial': 'soc'}),
))
pathway.primal('soc')  # (period, snapshot, value)

What changed

• A tuple of axes cuts with each in turn, outer first. Two axes over one dimension, two windows over one local index, a non-axis in the tuple, and key_name= with a tuple are refused before a slice is built.
• Each axis carries its own state. A carry reaches the slices of its axis's next label. Under an axis inside it, the value is the last inner slice's, and it reaches every inner slice of the next label: a period hands the next period the fleet its last window ended with. An inner carry restarts from its seed at each outer label. Two axes writing one parameter are refused. A window's carry reads its own axis's seam, so Slice.owns holds one count per axis.
• A chain is the slices that share the keys of every axis outside the outermost one that carries. Under an executor, where an axis carries, each chain is one task, run in order on one model, so 'previous' (refactor(api): keep= is gone, and a re-solve carries on from where the last solve ended unless start=None says otherwise #1884) carries on along it; otherwise each slice is one task. A sweep of one chain still refuses an executor with a carry.
• One stitch spans every window axis. The answer is over every windowed dimension and keeps only what every window owns: an hour the decade window solved only as lookahead is not in it. Per window, it keeps every key and every local index.
• The key is a tuple. Slice.key is a tuple of labels, KeyColumns carries the key columns and their types through the spill, the record and the archive. Sweep.key_names is new; Sweep.key_name is the last. Sweep.keys holds labels for one axis and tuples for several. On disk, slice_axis and slice join names and labels with /.
• A tuple is plain data too, as feat(api): an axis is written as plain data with to_dict, and solve_over takes that data in its place #1981 makes one axis: {'each': 'axes', 'axes': [each.to_dict(), ...]}. solve_over takes it in the tuple's place, and a nested sweep's axis.json is it. One axis writes exactly what main writes.
• Spill, resume, archive, keep_windows, per_window, start= an earlier sweep, and an undeclared expression off an archive all work over a tuple; load_archive and load_inputs give the tuple back as .axis. The archive's uncut sources drop every window's local index.
• ANSWER_LAYOUT rises from 4 to 5 (the spill manifest names key_names, and the stitch its locals, dims, keys and outer keys), once since 0.8.1. INPUTS_LAYOUT stays 1: one axis writes the axis.json main writes, so every 0.8.1 archive's spec and sources still read; a tuple's axis.json is new, and 0.8.1 cannot read it.
• Docs: a "Several axes" section in the sweeps reference, with the pathway example, and its rules on reading, carrying, starting and running; Chain in the glossary; the parallel how-to.

Merged with main: #1884, #1980 and #1981

• refactor(api): keep= is gone, and a re-solve carries on from where the last solve ended unless start=None says otherwise #1884 made 'previous' the default, carrying the solver on rather than matching the slice before by coordinate. Each slice passes its own start to Model.solve; a chain is one task only where an axis carries. The refusal of 'previous' with an executor on one chain went with its test and its mutation row.
• refactor(api): the carry is an argument of the axis rather than of solve_over, so an archive's axis holds its carry #1980 moved carry= onto the axis for one axis, which this PR had done for every axis. Main's version is taken; the tuple keeps each axis's own carry.
• feat(api): an axis is written as plain data with to_dict, and solve_over takes that data in its place #1981 made an axis plain data through to_dict and axis_from. The tuple form above extends it; the stack's own axis_manifest is gone.
• Main holds the stack's lower PRs as squash commits, so refactor(api): keep= is gone, and a re-solve carries on from where the last solve ended unless start=None says otherwise #1884's last head (c0f7071) was merged first and main recorded after it: at 8736754 this PR's diff against main was byte-identical to its diff against c0f7071.

Breaking, and coverage that moved

• Slice.key is a tuple, and Slice.owns one count per axis.
• A 0.8.1 spill or archive answer is refused by ANSWER_LAYOUT; load_inputs still reads a 0.8.1 archive's spec and sources.
• The windows-last refusal case window-outside became one-local-index-for-two-windows. The no-each refusal now lists axes among the kinds.

Tests

tests/test_nested_sweep.py. The oracle is the loop it replaces.

• Each scenario's answer and objectives equal its own carried sweep. The store is seeded at 50 and every window empties it, so a carry crossing chains would change the answer.
• Two carrying axes: a pathway of two periods, each a carried rolling horizon. Each period equals its own horizon with existing copied by hand from the previous period's last window; 2040's first window differs from 2030's, so the fleet did arrive.
• Windows inside windows: decades with a one-decade lookahead, hours rolling inside each. The answer holds each (period, snapshot) once, the lookahead decade dropped; per window it keeps both keys and both locals. With the fleet carried, each decade window equals its own hourly horizon over its decade and the next, existing set by hand; every window's objectives match.
• Thread and spawned process pools give the serial answer, each chain built once; an outer carry makes the whole pathway one chain, so an executor is refused.
• Spill and resume without a build; archive with windows, re-run from archive.axis, evaluate an undeclared expression; start= an earlier nested sweep gives each window its own rows. A nested axis.json is the tuple's plain data, reads back as the tuple, and solves to the same answer.
• Three axes, two coordinate axes, a parameter two axes carry, the tuple refusals, and two malformed tuple mappings.

Where a start is in play, tests compare objectives: this LP has several optimal vertices, and a start can end on another.

Mutation table

python -m tools.mutate for the deletions, scoped to tests/test_nested_sweep.py and tests/test_strategy.py; hand mutations by sed, restored with git checkout --, __pycache__ dropped on both sides. Rows 1–13 were taken on 1de4d33 and rows 14–16 on 507123e, before main was merged in, so their line numbers are those commits'; row 17 on e1a9ebb. Clean after every run.

guard	result
a tuple holding something other than an axis (axes.py:337-341)	caught
a window outside another axis (axes.py:342-347), since replaced by row 14	caught
two axes over one dimension (axes.py:349-353)	caught
carry with an executor on one chain (strategy.py:380-385)	caught
key_name= with a tuple of axes (strategy.py:962-966)	caught
a parameter two axes carry (strategy.py:197-201)	caught
an outer label change resets the inner carry (strategy.py:719)	caught
by hand: a chain is one task (every slice its own task); taken again on 8736754	caught (3 failed)
by hand: the stitch joins on the outer keys (on=keys)	caught (4 failed)
by hand: the archived record drops every key column	caught (2 failed)
by hand: an axis hands on only at the end of its label	caught (1 failed)
by hand: an outer carry reaches the next label (outer carries never hand on)	caught (1 failed)
by hand: a chain starts at the outermost carrying axis (always the last axis)	caught (1 failed)
two windows over one local index (axes.py:354-358)	caught
by hand: an inner coordinate is owned only under the outer window that owns its decade (join dropped)	caught (2 failed)
by hand: a window carry reads its own axis's seam (owns[-1])	caught (1 failed)
a tuple mapping that is not each and a list of axes (axes.py:524-528)	caught

Verification

• Full suite (pytest -n 4, HiGHS, Gurobi and Xpress) on 740bd8b, main through 9c13352 merged in, under polars 2.0.0: 5570 passed, 566 skipped, 4 xfailed. python -m tools.changelog check: releases nothing on merge.
• ruff check ., ruff format --check ., pyrefly check: 0 errors. zensical build --strict: pass.
• Not run: test-bench (nothing under bench/ changed). No benchmark: nothing claims a speed. CodSpeed's memory flag on an earlier head compared against a main older than chore(bench): an A/B of two git refs over a grid of models proves a change is faster and builds the same model #1940, and this PR touches nothing a benchmark builds.

Deliberately not done

• Renaming solve_over to solve_sweep: its own PR.
• Resuming part of a chain under an executor: a chain the spill holds only part of runs whole again; serially it resumes from the first unfinished slice.
• Reading one outer window as a whole. per_window=True returns the innermost windows, keyed by every window key.
• A number over two local indexes at once in an archive's uncut sources is spread over each window's dimension in turn, not over both; no test covers it.
• A tuple whose axes are themselves mappings. The tuple's plain data is one mapping; a Python tuple takes axes.

🤖 Generated with Claude Code

https://claude.ai/code/session_014wLrXpeSGDqoBFxyrs8NEz