perf: split nb06 into CI (fast) + research (full-fidelity) versions

[jonathanhhb]

NOTE: This is a more ambitious version of #233. May not be needed immediately and represents a direction @JSchripsema-IDM has discussed. Needs more discussion before one-off-ing a single "science version" notebook.

Replaces #230 with the minimum change needed for the split.

Why

The Build Combined Doc workflow takes ~40 min today; ~16 min of that is executing docs/tutorials/notebooks/06_SIR_wbirths_natural_periodicity.ipynb (the 10-sim × 100-year parameter sweep from #188 plus a 6-CBR regime-robustness sweep). That's roughly 40% of the entire pipeline.

What changes (5 files)

• docs/tutorials/notebooks/06_SIR_wbirths_natural_periodicity.ipynb — slimmed for CI:

  • single-run sanity check: nticks 100y → 30y
  • main sweep: nsims 10 → 5, nticks 100y → 40y, np.random.seed(42) added so CI runs are reproducible
  • regime sweep: 6 CBRs → 4 (span both regimes: 15, 30, 60, 100), nticks 100y → 40y
  • peak-finder/autocorr cutoff default 18250 (50y) → 3650 (10y) so trimmed windows still leave a usable post-transient chunk

• docs/tutorials/notebooks/research/06_SIR_wbirths_natural_periodicity.ipynb (new) — verbatim copy of the pre-split notebook, preserved for research use at the original 100y × 10-sim × 6-CBR fidelity.

• docs/tutorials/notebooks/research/README.md (new) — documents the pattern for future maintainers.

• Makefile — NB_EXCLUDE adds research/ so docs/execute_notebooks.py skips anything under any research/ subtree.

• mkdocs.yml — mkdocs-exclude glob adds tutorials/notebooks/research/* so the research copy is invisible to the rendered mkdocs site and nav.

Verified

• Build Combined Doc on a branch containing these changes: 31m 16s total, nb06 alone dropped from 16m 05s → 3m 39s (run 28832818248).
• jenner-generic-mcp alpha test suite against the resulting corpus: 20/21 pass (a1: 12, a2: 7, a3: 1, never: 1 — same p09 as before). No RAG-quality regression from the parameter cuts or the exclusion.

Superseded PR

#230 contained the same nb06-split changes plus the entire PR #204 plot-description sweep (150 files diff). This PR is scoped to just the nb06 split (5 files); #204 remains its own PR.

Caveat

Cached outputs in the CI nb06 are from a pre-split 100-year run — code shows 30y/40y but plot images still show 100y until the next release-publish build regenerates them (that workflow sets MKDOCS_EXECUTE_NOTEBOOKS=true). Nothing crashes; the qualitative shape of every plot is unchanged.

[jonathanhhb]

Closing — superseded by the combination of #233 (merged) and #237 (open). The nb06 wall-clock problem this PR was designed to fix is now solved twice over, without needing to split the notebook into separate CI/research files.

Final resolution

#233 (merged) — @YeChen-IDM's env-var toggle: a single nb06 file that runs a lightweight variant in CI (GITHUB_ACTIONS=true → n_years=20, nsims=2) and the full 100y × 10-sim variant locally. One file, one heading structure, no per-fidelity drift.

#237 (open) — default docs-jenner no longer re-executes notebooks at all. Reads the committed notebook outputs directly, cutting the doc build from ~40 min to ~1 min. Notebook runtime becomes irrelevant to CI wall-clock.

Together those cover every case this PR was addressing:

Case	Resolution
Default doc build wall-clock (CI)	#237 skips execution entirely
Opt-in docs-jenner-execute full validation	#233's env-var kicks nb06 into 1-min mode in CI
Local dev iteration on nb06	#233's env-var defaults to full fidelity locally, GITHUB_ACTIONS=true for fast re-execute
Full-fidelity outputs preserved for research	#233's local branch of the toggle produces them; committed outputs are canonical

What this PR uniquely offered

Only one thing this PR added that #233 + #237 don't:

• The docs/tutorials/notebooks/research/ folder + NB_EXCLUDE + mkdocs-exclude wiring as generic infrastructure for preserving multiple flavors of a notebook side-by-side.

That's genuinely nice-to-have — if a future notebook has a "quick tutorial" version AND a "deep exploration" version that we want to keep in the repo but distinguish for CI, this wiring is the paved path. But nothing else needs it today, and it costs perpetual maintenance to keep two nb06 files in sync. Better to add the research/ mechanism if/when a second notebook actually needs it, rather than carrying the scaffolding for one use case that turned out to be solvable differently.

Diagnostic thread (for the record)

The empirical benchmarking that ran alongside this PR revealed several unrelated things worth capturing here:

• Re-export get_default_parameters at laser.generic top level #228 (get_default_parameters top-level re-export, merged) fixes ~7/21 prompts that were failing with runtime ImportError because the LLM guesses from laser.generic import get_default_parameters.
• concat_mkdocs: broaden tqdm strip to catch all tqdm variants #229 (tqdm-strip broadening, merged) reduced corpus size from ~98k lines back to ~65k by catching all tqdm variants — recovers +6 passes and +5-7 a1 on the jenner-generic-mcp alpha suite. See concat_mkdocs: broaden tqdm strip to catch all tqdm variants #229's confirmation comment for the data table.
• concat_mkdocs: demote notebook headings + warn on oversize sections (RAG-quality) #236 (concat demote + oversize warning, open) further improves RAG retrieval by structuring the combined markdown so the header splitter catches more section boundaries, and warns authors when specific notebook sections need subheadings.

On the current shipping config (yechen's stripped main_generic.py, #228 merged, #229 merged, main-tip corpus), the alpha suite lands at 18-19/21 with 5-8 a1 across runs. That's essentially back to the pre-regression baseline and doesn't require a nb06 split.

Preserving the branch perf/split-nb06-ci-only on the fork for reference; if someone wants to revive the research/ folder pattern for a different notebook later, it's a working template.