docs: two how-tos say how to make a solve faster and how to solve many scenarios by FBumann · Pull Request #1985 · fluxopt/specsolve

FBumann · 2026-10-12T06:21:47Z

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.

What each page holds, what moved, and what ran

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.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy

Generated by Claude Code

…y scenarios "Making a solve faster" lists each way with what it costs: keeping the model loaded, starting from an earlier answer, many small models, a MIP gap, relaxing integers, windows, decomposition and a smaller model. "Solving many scenarios" takes the scenario steps the last tutorial no longer has. The warm-start page becomes "Starting from an earlier answer", and its section on many small models moves to the new page. 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

read-the-docs-community · 2026-10-12T06:22:41Z

Documentation build overview

📚 specsolve | 🛠️ Build #35085445 | 📁 Comparing ce49770 against latest (990de2a)

🔍 Preview build

46 files changed · + 5 added · ± 33 modified · - 8 deleted

+ Added

± Modified

- Deleted

codspeed · 2026-10-12T06:26:38Z

Merging this PR will not alter performance

✅ 93 untouched benchmarks
⏩ 307 skipped benchmarks¹

_{Comparing claude/quirky-fermat-n0zzum-docs-18-faster (ce49770) with claude/quirky-fermat-n0zzum-docs-17-horizon (694cd1d)²}

307 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. ↩
No successful run was found on claude/quirky-fermat-n0zzum-docs-17-horizon (af9b36b) during the generation of this report, so b00985e was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

…e/quirky-fermat-n0zzum-docs-18-faster

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy

…e/quirky-fermat-n0zzum-docs-18-faster

…ge instead (#1987) > **Prompt:** The language also should go. Reference overall should not duplicate tutorials/how to! Its the lookup! > > **Prompt:** The language (mathspec) should instead be linked right on the homepage i think! > [!NOTE] > The following content was generated by AI. The language moves from the Reference sidebar to the home page, as a hero button and a sentence above the model file. The API, data and sweeps pages lose the examples that repeated the tutorials and how-tos. <details><summary>What went, what stayed, and what ran</summary> **The language, on the home page.** It has a third hero button, "The language", beside "Your first model" and "Browse the examples". It also has one sentence above the model file: the file is written in mathspec, and its reference lists everything a file may hold. **Cut from Reference:** | Page | What | Where a reader finds it now | |---|---|---| | nav | "The language" link to mathspec | the home page; the API page's first line; every construct link | | `reference/api.md` | the check / solve / primal / dual example | Your first model | | `reference/data.md` | the `sps.solve(...)` example with three sources | Your data, Preparing the data | | `reference/sweeps.md` | the opening scenario sweep | Solving many scenarios (now linked) | | `reference/sweeps.md` | the first of three identical carried `EachWindow` blocks | Carrying state between slices, on the same page | **Fixed:** the glossary's link to the warm-start how-to used its old title. **Kept on purpose:** each code line that shows one keyword's spelling (`steps` as a sequence, `axis.slices`, `to_dict`, `per_window`, `spill_to`, `archive=`, `start=`). The rule tables. The sink table. The `executor` table. These are what a reader looks up. I left the Examples group under Reference, where the nav already had it. **Not done:** the how-tos still repeat some reference rules. For example, "Starting from an earlier answer" has a sweep section beside the reference's "Starting slices", and the parallel how-to repeats "N × peak". That is the other direction, so I left it. **Gates.** - `zensical build --strict`: no issues. - `pytest tests/test_docs_site.py tests/test_doc_examples.py`: passed. - `ruff format --check`: clean. - The full suite was not run. **Stack:** … ← #1985 ← this PR. </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy --------- Co-authored-by: Claude <noreply@anthropic.com>

claude added 2 commits October 12, 2026 06:21

docs: add the changelog line

042707e

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy

claude added 4 commits October 12, 2026 06:39

Merge branch 'claude/quirky-fermat-n0zzum-docs-17-horizon' into claud…

3c94daf

…e/quirky-fermat-n0zzum-docs-18-faster

docs: pass the carry on the axis, as main now spells it

db286c5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wrzfzr2yLiZFMv19fzokoy

Merge branch 'claude/quirky-fermat-n0zzum-docs-17-horizon' into claud…

95ee08b

…e/quirky-fermat-n0zzum-docs-18-faster

Merge branch 'claude/quirky-fermat-n0zzum-docs-17-horizon' into claud…

ce49770

…e/quirky-fermat-n0zzum-docs-18-faster

FBumann mentioned this pull request Oct 12, 2026

docs: the reference is for lookup, and the home page links the language instead #1987

Merged

FBumann added this pull request to stack #1979 October 12, 2026 07:08

FBumann merged commit 0e759ab into claude/quirky-fermat-n0zzum-docs-4-reference Oct 12, 2026
12 checks passed

FBumann deleted the claude/quirky-fermat-n0zzum-docs-18-faster branch October 12, 2026 07:21

Navigation Menu

Repository navigation

docs: two how-tos say how to make a solve faster and how to solve many scenarios - #1985

docs: two how-tos say how to make a solve faster and how to solve many scenarios#1985
FBumann merged 6 commits into
claude/quirky-fermat-n0zzum-docs-17-horizonfrom
claude/quirky-fermat-n0zzum-docs-18-faster

FBumann commented Oct 12, 2026

Uh oh!

read-the-docs-community Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

codspeed Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

FBumann commented Oct 12, 2026

Uh oh!

read-the-docs-community Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

codspeed Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

read-the-docs-community Bot commented Oct 12, 2026 •

edited

Loading

codspeed Bot commented Oct 12, 2026 •

edited

Loading