docs: chapter 1 tutorial 4/6 review feedback

[Jammy2211]

Summary

Acts on a read-through of chapter 1 tutorials 4, 5 and 6.

Tutorial 4

• Backticks log_likelihood_function and model_data in the Analysis prose, which the surrounding paragraphs already backtick.
• Adds the six figures the tutorial has always embedded but which were never committed. scripts/chapter_1_introduction/images/ did not exist in this repo, so all six <img> tags rendered broken, and the prose that follows leans on them directly ("This ideal scenario is illustrated in the good_fit.png image above").
• Rounds the log likelihood in all 9 plot titles to 2dp. At full float precision (= 134.2557227848585) the title overflows a square figure and clips for every reader.
• .gitignore: excepts this images/ directory from the blanket **/images/ rule, which silently hid the six PNGs from git add.

Tutorial 6

• Drops the search.summary / Resampling Info block: tutorial 7's __NaN Diagnostics__ already covers that same file and both NaN counters, so it was premature and duplicated.
• Replaces the extended ball-rolling analogy for Hamiltonian Monte Carlo with a plain statement that NUTS is MCMC in which the walker knows which way to step, keeping only as much trajectory as the No-U-Turn name requires. The wrap-up recap ("rolls a ball across the landscape") is brought into line.
• Moves the Hamiltonian diagnostics out to tutorial 7.
• Rewords the wrap-up's opening sentence.

Tutorial 7

• New __Hamiltonian Diagnostics__ section carrying n_divergent, ess_min and mean_acceptance, with its own short BlackJAXNUTS fit so the numbers come from a live result.

How the six figures were generated

The tutorial's own 15-parameter fit (af.Collection of five Gaussians, af.DynestyStatic(sample="rwalk")) run 25 times against one fixed gaussian_x5 realisation, using the tutorial's own plotting blocks verbatim at figsize=(5,5), dpi=100. Log likelihoods were recomputed from each reported max_log_likelihood_instance rather than taken from result.log_likelihood (max disagreement across all 25: 0.0).

role	logL	max |norm resid|	px > 3σ
bad	−3189.38	21.57	68
okay	132.98	3.97	4
good	183.63	2.61	0

The okay case is the one that matters: the tutorial asserts "for the okay fit there are residuals above 3.0 sigma", and that is now literally true of the committed image, while the good fit breaches it nowhere. The good fit reaches the global maximum (183.63 against the generating profiles' own 180.91).

The 25 trials split into the three families the tutorial describes — 9 failed local maxima, 13 near-misses that look plausible but breach 3σ, 3 near-global solutions — so the figures illustrate a real property of this fit, not a hand-picked artefact.

Note on the markdown diff size

markdown/chapter_1_introduction/tutorial_4_why_modeling_is_hard.md was last rendered on 2026-07-27 (1505794), and four script commits have landed since (c157131, 9e1b165, cd9efd8, b599b4c). Re-rendering it to pick up the backtick fix therefore also catches the mirror up on that drift, which is why the markdown diff is larger than the prose change and the image set grows 10 → 14 files. Verified: no other tutorial's mirror changed, and no absolute or worktree path leaked into the rendered output.

API Changes

None — documentation and tutorial prose only.

Test Plan

• All three tutorials parse (ast.parse).
• .github/scripts/check_tutorials_complete.py → 16 tutorials checked, none truncated.
• Tutorial 6 carries no residual ball / search.summary / Resampling Info / n_divergent reference.
• Tutorial 7 section order: Clipping → NaN Diagnostics → Hamiltonian Diagnostics → Unit Cube Vs Physical → Summary.
• af.BlackJAXNUTS, af.Collection, af.Model, af.UniformPrior all present in the installed stack; the new section's Gaussian / analysis_x1_jax / time references resolve earlier in the file.
• Notebooks regenerated (generate.py howtofit); only tutorials 4, 6 and 7 changed.
• Markdown mirror re-rendered (generate_markdown.py howtofit --only tutorial_4), PASS in 527s; backtick fix confirmed present, unbackticked form absent, six images/ references intact, zero /home/jammy leaks.
• Six PNGs confirmed staged (they are invisible to git status without the .gitignore exception).

Smoke CI impact of the added NUTS fit is minimal: config/build/profile_smoke.yaml runs at PYAUTO_TEST_MODE=2 (sampler skipped), and tutorial 7 already carries a PYAUTO_DISABLE_JAX: "0" override. The three samples_info.get(...) lines already ran in tutorial 6 under this identical profile.

Independent of PyAutoLabs/PyAutoNerves#166; no library-first gate applies.

Closes #61

🤖 Generated with Claude Code

https://claude.ai/code/session_011DMhAYrJ6m2spkTVEWcSKg