Skip to content

Restructure the lecture series: chaining into chapter 2, pixelizations as chapter 3 with a Bayesian formalism lecture, new Scaling Up Galaxies chapter 4 - #62

Merged
Jammy2211 merged 15 commits into
mainfrom
claude/howtolens-tutorial-restructure-f19y9d
Aug 6, 2026
Merged

Restructure the lecture series: chaining into chapter 2, pixelizations as chapter 3 with a Bayesian formalism lecture, new Scaling Up Galaxies chapter 4#62
Jammy2211 merged 15 commits into
mainfrom
claude/howtolens-tutorial-restructure-f19y9d

Conversation

@Jammy2211

@Jammy2211 Jammy2211 commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

Mirror of the HowToLens restructure (PyAutoLabs/HowToLens#68), scaled to HowToGalaxy:

Chapter 1 — Introduction

  • tutorial_2_data gains a one-block interferometer section (visibilities, uv-plane fitting, dirty images) backed by a new plain-galaxy interferometer simulator, stating HowToGalaxy covers interferometry no further.

Chapter 2 — Modeling

  • tutorial_8_need_for_speed rewritten for the JAX era (JIT compilation, use_jax=True default, GPU, VRAM checking, galaxy-specific cost-per-evaluation breakdown), replacing the numba-centric story.
  • Old chapter 3's search chaining and prior passing move in as tutorials 9–10, reframed as the chapter's closing arc; the x2-galaxies chaining tutorial is deleted (superseded by chapter 4's multi-galaxy tutorial). Tutorial 9's first model now actually applies the simplifications its prose promised.

Chapter 3 — Pixelizations (was chapter 4)

  • New tutorial_5_bayesian_formalism: the equations lecture for pixelized reconstruction in the galaxy context (mesh over the galaxy's own image — no ray tracing/borders, stated explicitly), mirroring the workspace's pixelization likelihood_function.py with all matrices and evidence terms computed live. Model-fit renumbered to tutorial 6 with corrected model descriptions; prose cleanup throughout (including removal of a false "star-forming clumps" dataset claim).

Chapter 4 — Scaling Up Galaxies (new)
Three tutorials: extra galaxies (noise scaling vs explicit modeling — light contamination only, no lensing framing), multi-galaxy blends (joint fitting of overlapping galaxies, MGE parameter economics, flux-split degeneracy), and cluster fields (BCG + catalogue-driven member population, two-tier model, per-member results). Backed by new extra_galaxy and cluster simulators. No scaling-relation or weak-lensing tutorials — those are lensing concepts with no autogalaxy workspace grounding.

Cleanup found by adversarial review: leftover HowToLens titles and lensing vocabulary scrubbed across chapters 1–2; a results-tutorial light profile literally named mass renamed; false stack claims corrected against the installed configs; chapter_optional/tutorial_searches no longer composes a leftover lens+source model; a cluster member that sat outside the tutorial's own mask moved inside; ~45 typos.

READMEs, introductions, the navigator catalogue and notebooks are regenerated (notebooks now activate setup_notebook, via PyAutoLabs/PyAutoHands#231).

Validation

  • Full smoke suite (every script, clean dataset state): green — runner exit 0, all entries [PASS].
  • check_tutorials_complete.py: 26/26 pass; check_navigator.py: paths + banner lint OK.
  • All content verified against the installed stack (autogalaxy 2026.7.23.1 + the PyAutoGalaxy#552 centre_fixed fix) by execution/introspection.

Merge coordination

CI runs the PyAuto* libraries and PyAutoHands from same-named branches. Merge after PyAutoLabs/PyAutoGalaxy#552 and PyAutoLabs/PyAutoHands#231 (or together). Colab links pin tag 2026.8.4.1 per convention and resolve for new paths after the next release's bump_colab_urls.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU

Generated by Claude Code

claude added 15 commits August 6, 2026 14:29
@claude
refactor: restructure chapters — search chaining folds into chapter 2…
bec91aa 
…, pixelizations become chapter 3

Mirrors the HowToLens restructure: chapter 3 (search chaining) is
dissolved — tutorials 1 and 2 move to the end of chapter 2 as tutorials
9 (search chaining) and 10 (prior passing); the x2-galaxies chaining
tutorial is deleted (superseded by the new scaling-up chapter's
multi-galaxy tutorial). Chapter 4 (pixelizations) is renamed chapter 3
with model_fit renumbered 5->6 to make room for a new tutorial 5
(bayesian_formalism, added next). An empty chapter_4_scaling_up_galaxies
is scaffolded; the chapter 2 summary file moves past the new tutorials.

File moves only; content updates land in follow-up commits.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: update top-level chapter maps for the restructure
363794f 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: teach interferometer data in the chapter 1 data tutorial
f33295f 
One docstring + code block loading and plotting an interferometer
dataset (visibilities, uv-plane fitting, dirty images), stating
HowToGalaxy will not cover interferometry further and pointing readers
to the workspace. Backed by a new plain-galaxy interferometer simulator
with a small synthetic uv-baseline set, wired in with the standard
auto-simulate guard.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: rewrite need for speed for the JAX era
91c28e1 
Replaces the outdated numba-centric story with the current stack:
JAX JIT compilation of the likelihood (use_jax=True default), CPU vs
GPU, VRAM checking, run-time arithmetic tied to tutorial 2's real
numbers, and the galaxy-specific cost-per-evaluation breakdown (light
profiles, over-sampling, PSF convolution, inversion linear algebra).
Framing hands off to the new end-of-chapter search chaining tutorials.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: write chapter 4 tutorial 2 — multi-galaxy blends
1a9c320 
The co-dominant blend regime: why fitting overlapping galaxies
separately biases both, joint composition of the sersic_x2 pair with
MGE light and centres fixed to the observed light, runtime-verified
parameter accounting (14 -> 4 free parameters across the model
choices), per-galaxy decomposition and photometry, and the flux-split
degeneracy. The sersic_x2 simulator header now names its real chapter.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: write chapter 4 tutorial 3 — cluster fields
643d112 
Closes the scaling-up chapter and the series: what a cluster field looks
like (BCG + members + intra-cluster light), why composition becomes
catalogue-driven at this scale, the two-tier model (free MGE BCG,
catalogue members sharing one intensity-scale parameter), fitting and
per-member results access, and the closing ladder recap handing off to
the workspace and HowToLens. Backed by a new cluster simulator
mirroring the workspace's product set including the member CSV.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: write chapter 4 tutorial 1 — extra galaxies
4adaeb7 
Opens the scaling-up chapter with the crowded-fields ladder framing,
then the two ways to handle an interloper galaxy in the field: noise
scaling its light out of the fit, or modeling it explicitly through the
extra_galaxies model interface with its centre fixed to the observed
light. The decision framing is purely light contamination — no lensing.
Backed by a new extra_galaxy simulator mirroring the workspace's
product set (mask + centres artifacts included).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: rehome search chaining and prior passing as chapter 2 tutorials…
8e41c0b 
… 9-10

Retitled and reframed as the closing arc of the modeling chapter,
motivated by tutorial 8's run-time discussion; output paths and search
names move to chapter_2 with the tutorial 9 -> 10 result reload verified
by identifier equality; references to the deleted x2-galaxies tutorial
reroute to chapter 4 and the workspace chaining guide; lensing leaks in
the copied prose fixed; tutorial 9's first model now actually applies
the simplifications its prose promises (prior_count 4, was 6); stale
chapter references in tutorials 3-6 and the chapter summary updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: chapter 3 pixelizations — renumber, clean up, add the Bayesian …
c2d5556 
…formalism lecture

New tutorial_5_bayesian_formalism collects the pixelized-reconstruction
linear algebra for the galaxy context (mesh laid over the galaxy's own
image — no ray tracing or borders, stated explicitly): mapping and
blurred mapping matrices, data vector, curvature and regularization
matrices, the solve and the five evidence terms, computed live. The
other tutorials get chapter-3 framing, algebraic deferrals to tutorial
5, corrected model descriptions in the renamed tutorial 6 (model fit,
path_prefix now chapter_3), a false 'star forming clumps' dataset claim
removed, and README/introduction updates.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: update chapter READMEs and top-level overviews for the new stru…
05a6e93 
…cture

Chapter 2's index gains tutorials 9-10; a chapter 4 index is added; the
top-level scripts/notebooks READMEs replace the old chaining/pixelization
chapter overviews with the real chapter 3 (pixelizations + Bayesian
formalism) and chapter 4 (scaling up galaxies) maps; notebooks copies
synced.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: update llms.txt learning path to the new chapter map
4e0f539 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: chapters 3-4 review fixes — cluster geometry, claims and structure
d3304b8 
Adversarial review: the cluster member that sat outside the tutorial's
own mask moves inside it (simulator + prose aligned, dataset re-verified
end-to-end); per-member parameter arithmetic corrected (5 per free
SersicSph); inversions tutorial reordered so the file ends on its wrap
up; contents/section bijections restored across chapters 3-4; the
formalism lecture's contents mirror its section markers; narrative
back-references added where tutorial 2 re-taught tutorial 1's
fixed-centres rationale; stale workspace boilerplate and wrong-repo
dataset paths cleaned from the simulators.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: chapters 1-2 review fixes — titles, lensing leaks, stack claims
732d88d 
Adversarial review of the mirrored chapters: leftover HowToLens titles
fixed (summary and results tutorials); a results-tutorial model
component literally named mass with a light profile becomes bulge;
lensing vocabulary scrubbed from prose across both chapters; false
stack claims corrected against the installed configs (Nautilus n_live
default, prior widths and limits, plot-function signatures, removed
references to deleted MatPlot2D/Visuals2D objects); Contents lists
match bodies; parameter counts match composed models; ~45 typos fixed;
chapter_optional path_prefixes and dataset descriptions corrected; the
chapter 2 summary file converts to LF and points at chapter 4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
docs: chapter_optional models a galaxy, not a leftover lens+source sy…
9a18932 
…stem

The searches tutorial's model compositions were HowToLens leftovers
(lens with Isothermal mass + shear, background source). Both are now a
single bulge galaxy matching the simple__sersic dataset, with the MCMC
starting-point priors centred on the simulator truth. Runs green under
the smoke profile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@claude
build: regenerate notebooks and navigator catalogue for the restructure
2f55ed8 
Notebooks rebuilt from the restructured scripts via PyAutoHands
generate.py (new chapter 3/4 trees, updated chapters 1-2, simulator
notebooks, setup_notebook now active via the PyAutoHands fix);
llms-full.txt and workspace_index.json regenerated. check_navigator
passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxKfSZisjnEn91LRGkN4SU
@Jammy2211
Jammy2211 merged commit 2967439 into main Aug 6, 2026
7 checks passed
This was referenced Aug 6, 2026
Merged
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Jammy2211 @claude