Repository navigation
docs: the last tutorial solves a horizon too large for one solve, and shows what windows cost - #1984
Merged
FBumann merged 5 commits intoOct 12, 2026
Conversation
… shows what windows cost The tutorial is motivated by size now. It prints how the model grows with the horizon, solves the horizon in windows that keep their size, shows that the windows cost 12% more because each one empties the battery, and that lookahead buys the gap back at the price of larger windows. The model is shown as a collapsed file rather than taught. Scenarios leave the page, as they are not about size; a how-to takes them in the next change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy
Documentation build overview
44 files changed ·
|
Merging this PR will not alter performance
Comparing 
Footnotes
|
…/quirky-fermat-n0zzum-docs-17-horizon # Conflicts: # docs/sweep.md
…/quirky-fermat-n0zzum-docs-17-horizon
…/quirky-fermat-n0zzum-docs-17-horizon
FBumann
added this pull request to stack #1979
October 12, 2026 07:08
FBumann
merged commit Oct 12, 2026
2d83747
into
claude/quirky-fermat-n0zzum-docs-4-reference
12 checks passed
FBumann
added a commit
that referenced
this pull request
Oct 12, 2026
…y scenarios (#1985) > **Prompt:** The decomposition is always motivated by solve time! So we should make the tutorial about solving models faster in various ways? And explain the downside or limitation of each approach...? > [!NOTE] > The following content was generated by AI. There are two new how-tos. "Making a solve faster" lists eight ways, each with whether it keeps the optimum and what it costs. "Solving many scenarios" takes in the scenario steps that the last tutorial dropped. <details><summary>What each page holds, what moved, and what ran</summary> **Making a solve faster** (`docs/howto/faster.md`). One table, and then one short section for each way. The ways that keep the answer come first: | Way | Keeps the optimum | What it costs | |---|---|---| | Keep the model loaded | yes | only data that moves no mask or label | | Start from an earlier answer | yes | can make a solve slower | | Build many small models faster | yes | only below 250,000 columns and rows | | Accept a gap (`mip_rel_gap`) | within the gap | the answer is close, not optimal | | Relax the integers | no, a bound | the schedule is fractional | | Solve in windows | no | the windows cannot see past their end; they run one after the other | | Decompose | within the gap | you write the loop; links the Benders example | | Make the model smaller | no | it answers a different question | Each section has a code block and links to the page that has the detail. The measurements for starting from an earlier answer (#1884, #815) stay on that page, and the new page links there instead of copying them. **Solving many scenarios** (`docs/howto/scenarios.md`). It puts the scenarios in one table with a `scenario` column and solves once for each label with `EachCoordinate`. It reads the answers with that column, varies a second table with the same column, and links the parallel how-to. The page uses `dispatch.yaml` and the tutorial data: mild 10500, cold 16530, and cold with gas at 80 costs 24540. **Moved.** `warm-start.md` is now "Starting from an earlier answer", which is what it covers. Its section "Build many small models faster" moves to the new page. The nav lists the three pages together. "Change it and solve again" and the last tutorial link the new titles. **Checked by hand, not by the suite.** The HiGHS option name `mip_rel_gap` (the solver accepts it, and the commitment model solves to 14000), and the relaxed commitment bound (10875 below 14000). The code blocks on the faster page do not run in the build, as on the warm-start page. **Tests.** `tests/test_tutorials.py` runs the scenarios page. It checks the two objectives, that gas covers the extra cold load, and that the second table changes only the cold scenario. **Gates.** - `zensical build --strict`: no issues. - `pytest tests/test_tutorials.py tests/test_docs_site.py tests/test_tutorial_models.py`: 35 passed. - `ruff check` and `ruff format --check`: clean. - The full suite was not run. **Stack:** … ← #1984 ← this PR. </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy --- _Generated by [Claude Code](https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
The following content was generated by AI.
The last tutorial is now "A horizon too large for one solve". It shows the model growing with the horizon, windows that keep their size, the 12% they cost, and lookahead buying that back with larger windows.
The steps, the numbers, and what ran
Scope. This PR uses the shape agreed in conversation: one path in the tutorial, and the other ways to go faster in a how-to (the next PR). Scenarios leave this page because they are not about size. The next PR adds them back as a how-to.
The steps. Each step ends in a result the page prints and the suite checks:
tutorial/storage.yamlin a collapsed block, and one day solved: 10850diagnostics()sizes for 1, 3, 30 and 365 days: 28 columns and 24 rows a day, 10220 columns for a yearEachWindowwithcarry, three-hour windows, no lookahead: 21 columns each, fromsweep.metricsThe page shows model size, not time. Timings in a docs build are noisy, and at tutorial scale they show no gain. Columns and rows are exact.
What went. The bullet list that explained the battery's YAML, the battery's charge and discharge table, and the two scenario sections.
A correction to what I said in conversation. I said windows could run in parallel. They cannot when they carry state:
carryexcludesexecutor(reference, "Carrying state between slices"). The "Next" table therefore links the warm-start how-to, because each window starts from the one before, and not the parallel how-to.Also. The nav title and the README link name the new title. "Change it and solve again" points to this page.
test_tutorial_models.pydescribes the two models by what uses them, now that they are not numbered steps.Tests.
tests/test_tutorials.pyreplaces the old page's tests with five. They check the one-day cost, the size per day, the size per window, that the battery is empty at every window end with the 12% gap, and the lookahead costs and window sizes. The scenario test goes with its section; the next PR adds it back.Gates.
zensical build --strict: no issues. I read the rendered outputs and the collapsed YAML block in the built HTML.pytest tests/test_tutorials.py tests/test_tutorial_models.py tests/test_docs_site.py: 33 passed.ruff checkandruff format --check: clean.Stack: … ← #1983 ← this PR.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy
Generated by Claude Code