docs: a tutorial solves one model once per scenario and then window by window

[FBumann]

Prompt: About the links used: Are there better targets for each box? Or is sth missing from the docs? Like a decomposition tutorial? And tables in/out? What should it show? Data contract? Preparing data? The archiving?

Note

The following content was generated by AI.

The user's follow-up was "Yes. Stacked PR for 2". This PR is stacked on #1743.

What this changes

A new tutorial, "Sweep a model" (docs/sweep.md), runs solve_over twice. First it solves once per scenario. Then it solves window by window, carrying storage state between windows. The home page card "Sweeps and rolling horizons built in" now links it, instead of the 3,000-word reference.

Method, gate output, alternatives

• docs/sweep.md, 458 words of prose. Every block runs at build time (markdown-exec), so each output is what the code printed.
  1. One solve per scenario: EachCoordinate('scenario') on examples/dispatch.yaml, with a low and a high load. Objectives 7500.0 and 16200.0, and the p schedule per scenario.
  2. Window by window:
     • EachWindow('hour', steps=3, lookahead=3, into='snapshot') on the cyclic examples/storage.yaml is refused before any window is solved. The page quotes the message whole.
     • examples/rolling/horizon.yaml with carry={'soc_initial': 'soc'} then solves 3 windows, and reads back one 8-hour schedule with original_index=True.
  3. Myopic pathways: one sentence, and a link to examples/myopic/run.py. That example needs about ten tables, too many to run on this page.
• mkdocs.yml: a nav entry under Tutorials.
• docs/lifecycle.md: "Fix, relax, remove" gets a "Where next" that chains to the next tutorial.
• README.md and docs/stylesheets/extra.css: the card links …/sweep/ and keeps its icon.
• Step 2 uses two models. No example model shows both the refusal and the windowed solve, and patching a spec on the page would add steps.
• Gates (pixi is not installable in this session; a Python 3.12 venv with the docs group's pins stood in):
  • python -m zensical build --strict: "No issues found". The build runs every block.
  • pytest tests/test_doc_examples.py tests/test_docs_site.py tests/test_models_gallery.py: 486 passed, 3 skipped.
  • ruff check ., ruff format --check . (0.16.1): clean.
  • Sentences: n 27, median 14, none over 25.
  • Not run: the full suite, pixi run check.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y

---

Generated by Claude Code

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/docs-sweep-tutorial (fe4a896) with claude/docs-readme-homepage (5303eeb)}

Footnotes

1. 82 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34755531 | 📁 Comparing fe4a896 against latest (53c3910)

  🔍 Preview build  

16 files changed · + 1 added · ± 15 modified

+ Added

• sweep/index.html

± Modified

• index.html
• interactive/index.html
• lifecycle/index.html
• about/architecture/index.html
• about/changelog/index.html
• examples/pypsa_ladder/index.html
• examples/walkthrough/index.html
• reference/api/index.html
• reference/glossary/index.html
• examples/pypsa_ladder/rung_11_ac_dc_meshed/index.html
• and 5 more...