Skip to content

Restore fit-problem motivation and adaptive reconstruction in Chapter 3 - #102

Merged
Jammy2211 merged 1 commit into
mainfrom
feature/howtogalaxy-ch3-parity
Nov 4, 2026
Merged

Jammy2211 merged 1 commit into
mainfrom
feature/howtogalaxy-ch3-parity

Conversation

@Jammy2211

Copy link
Copy Markdown
Collaborator

HowToGalaxy Chapter 3 previously jumped from Bayesian regularization straight to the combined MGE/pixelization search. It now explains why an evidence-preferred reconstruction can still leave residuals, then teaches brightness-guided mesh placement and adaptive smoothing before the combined model fit.

The five-lesson sequence is Pixelizations → Bayesian Regularization → Fit Problems → Adaptive Reconstruction → Model Fit. The evidence explanation uses the Goldilocks analogy and explicitly chooses the largest natural-log evidence. The new experiments use directly observed galaxies and their PSF/noise model. The original combined-model lesson's executable AST is unchanged; it moves from Tutorial 3 to Tutorial 5.

Scripts Changed

  • tutorial_1_pixelizations.py: preserve the original walkthrough; add non-negativity, mapping-support and resolution caveats; complete the contents.
  • tutorial_2_bayesian_regularization.py: clarify evidence selection, coefficient comparisons and feature reliability; complete the contents and onward links.
  • tutorial_3_fit_problems.py: compare three increasingly compact galaxies with separately optimized constant regularization, motivating mesh resolution and spatially varying smoothing.
  • tutorial_4_adaptive_reconstruction.py: combine Delaunay/Overlay, Hilbert sampling, ConstantSplit and AdaptSplitPower in one lesson, with bounded-memory evidence scans and explicit limits on interpretation.
  • tutorial_5_model_fit.py: preserve the three original chained searches and add a bridge explaining the distinction between whole-galaxy adaptation and residual-component decomposition.

All scripts are under scripts/chapter_3_pixelizations/. Regenerated notebooks, READMEs and navigation/catalogues accompany the source. The two new compact-galaxy experiments declare full_datasets in their developer Env blocks.

Test Plan

  • Independent review CLEAN at 5d98c61, with dispositions for the review surface's claims.
  • All 30 generated notebooks validate; Chapter 3 narrative parity, exact contents lists and terminal sections pass. Navigation, catalogue determinism, API audit, strict environment declarations and search-memory checks pass.
  • Full-size Tutorials 1, 3, 4 and 5 pass, including all new coefficient scans. The inherited full-size Tutorial 2 fine-mesh comparison was terminated with exit 143 after the revised evidence-selection section completed; this is recorded as incomplete, not a full-size pass. Its complete capped CI run passes.
  • The nonlinear searches use PYAUTO_TEST_MODE=2: their likelihood and chaining paths execute, but posterior convergence is not assessed.
  • Canonical repository smoke: all 30 executable scripts pass (zero failures, timeouts or skips). New Tutorials 3 and 4 execute at full size in 150.5s and 197.5s respectively. Heart’s smoke launcher has no HowToGalaxy entry, so the repository-owned CI runner was used in an isolated Python 3.12 environment with the declared optional dependencies.
  • No unit-test directory exists in this teaching repository; script execution and generated-artifact checks are the relevant test surface.

Autonomous ship decision

The user explicitly requested autonomous adaptation. This docs task is supervised / judge: prepare the complete reviewable PR and leave merging to the human. The rejected alternative was stopping midway for repeated prose/ship approvals. To revert the complete source and generated change after merging, run git revert 5d98c61491cd7f03486731a855089e1b11d87d06.

Validation checklist (autonomous run)

  • Effective level: supervised (large tutorial/docs adaptation); consequence: judge.
  • Plan: recorded on issue docs: port Chapter 3 evidence and adaptive reconstruction teaching #101 and in the active Mind prompt.
  • Gate: tests: generated/artifact/API checks pass (no pytest suite); smoke: 30/30 pass; independent review: CLEAN with claim dispositions; Heart: YELLOW, limited to the same-conversation acknowledged AutoFit workspace timeout. A missing current release rehearsal is recorded as a stale evidence gap; this is not a release.
  • Human: plan sound in hindsight?
  • Human: diff matches the requested Galaxy adaptation?
  • Human: merge, amend or reject.

Closes #101.

@Jammy2211
Jammy2211 merged commit 2d873b8 into main Nov 4, 2026
8 checks passed
@Jammy2211
Jammy2211 deleted the feature/howtogalaxy-ch3-parity branch November 4, 2026 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: port Chapter 3 evidence and adaptive reconstruction teaching

1 participant