docs: add multi_galaxy features/extra_galaxies example (phase 2a)

[Jammy2211]

Overview

Phase 2a of the extra-galaxies parity task (phase 1, point_source, shipped as autolens_workspace#374 / PR#376).

autogalaxy_workspace/scripts/multi_galaxy/ has no features/ folder at all — its README ends with a one-line "standard single-galaxy features apply per-galaxy here" pointer. This adds one, with a full extra_galaxies worked example in the style of imaging/features/extra_galaxies.

Phase 2 was split by repo: multi-galaxy-imaging-parity (autolens_workspace#370) is in flight and rewriting autolens_workspace/scripts/multi_galaxy/ wholesale, so the autolens half is deferred to phase 2b and written against that merged result. This repo has zero contention with it.

Plan

• Create scripts/multi_galaxy/features/ (README + __init__.py) — the folder does not exist yet.
• Add features/extra_galaxies/ with README.md, __init__.py, simulator.py, modeling.py, mirroring imaging/features/extra_galaxies.
• Show both levers, as the imaging example does: noise-scaling the companions out, and modeling their light with fixed centres (SersicSph Option A, MGE Option B commented).
• What is new versus imaging is the base model: two co-equal blended galaxies via the galaxy_0, galaxy_1, … loop, plus a lower tier of sub-dominant extra galaxies. That contrast is the point of the example.
• Add a # Folders section to scripts/multi_galaxy/README.md.

Detailed implementation plan

Affected Repositories

• autogalaxy_workspace (primary)

Branch Survey

Repository	Current Branch	Dirty?
./autogalaxy_workspace	main	clean

Suggested branch: feature/extra-galaxies-multi-galaxy

Implementation Steps

1. scripts/multi_galaxy/features/extra_galaxies/simulator.py — the co-equal pair from multi_galaxy/simulator.py (Sersic bulges at (0.0, -0.75) / (0.0, 0.75)) plus two faint companions further out. Writes data/psf/noise_map.fits, galaxies.json, galaxy_centres.json, extra_galaxies_centres.json and mask_extra_galaxies.fits to dataset/multi_galaxy/extra_galaxies/.

2. scripts/multi_galaxy/features/extra_galaxies/modeling.py — larger mask to admit the companions (the imaging example uses 6.0" against multi_galaxy/modeling.py's 3.0"), noise-scaling fit first, then the modeling fit with one mge_model_from per co-equal galaxy plus an extra_galaxies collection of fixed-centre lp_linear.SersicSph (Option A) / MGE (Option B, commented).

3. features/README.md + features/extra_galaxies/README.md + both __init__.py.

4. scripts/multi_galaxy/README.md — add # Folders.

5. smoke_tests.txt — add the new modeling.py (multi_galaxy scripts are smoke-enabled here).

6. Regenerate notebooks + navigator via generate.py autogalaxy.

Conventions (autogalaxy differs from autolens)

• Centres file is galaxy_centres.json, not main_lens_centres.json.
• Light-only: no mass model, so no IsothermalSph tier — companions are fitted or noise-scaled purely photometrically.
• features/README.md should carry the existing "Scaling Relations (not applicable in autogalaxy)" framing from imaging/features/extra_galaxies/README.md, so the autolens scaling-relation tier is not implied to transfer.

Known traps

• should_simulate tests directory existence only — rm -rf dataset/multi_galaxy/extra_galaxies before any validation run.
• PYAUTO_TEST_MODE=1 and =2 share the output/test_mode/ namespace, so a bypass run silently resumes a reduced-iterations run — rm -rf output/test_mode before trusting a bypass result. (Hit in phase 1.)
• Navigator root-name trap: check_navigator.py strips a leading <root.name>/ prefix and CI clones the workspace as workspace/, so a literal autogalaxy_workspace/scripts/... reference passes locally and fails in CI. Use the wildcard autogalaxy_workspace/*/... form; reproduce CI by cloning into a dir named workspace.
• Bulk-edit rule: never whole-file write a file not fully read; run scripts/check_sizes.sh.

Key Files

• scripts/multi_galaxy/features/extra_galaxies/** — new
• scripts/multi_galaxy/features/README.md, __init__.py — new folder
• scripts/multi_galaxy/README.md — # Folders
• smoke_tests.txt
• scripts/imaging/features/extra_galaxies/{README.md,modeling.py,simulator.py} — prose + API source
• scripts/multi_galaxy/{simulator,modeling}.py — co-equal pair conventions

Acceptance

• Simulator writes the dataset + all four metadata files from a clean folder.
• modeling.py runs under PYAUTO_TEST_MODE=2 / PYAUTO_SMALL_DATASETS=1; added to smoke_tests.txt.
• run_smoke.py green; check_sizes.sh clean; notebooks + navigator regenerated.
• cluster/ untouched.

Original Prompt

Click to expand starting prompt

Phase 2a — extra_galaxies feature: multi_galaxy (autogalaxy_workspace)

Type: docs
Target: autogalaxy_workspace
Repos:

• autogalaxy_workspace
  Difficulty: medium
  Autonomy: supervised
  Priority: normal
  Status: draft
  Parent: draft/docs/workspaces/extra_galaxies_feature_parity.md

Phase 2a of the extra-galaxies parity task. Phase 1 (point_source) shipped as
autolens_workspace#374 / PR#376.

Adopt same style and approach for documenting extra galaxies in multi_galaxy,
do same in autogalaxy_workspace.

Human decision 2026-07-29: full worked example (own simulator + own simulated dataset),
not a cross-link — matching autolens_workspace's sibling tier
multi_galaxy/features/scaling_galaxies/, which gets full-example treatment.

Split decision 2026-07-30: phase 2 was split by repo. multi-galaxy-imaging-parity
(autolens_workspace#370) is actively in flight in another session and rewrites
autolens_workspace/scripts/multi_galaxy/ wholesale — 2,959 insertions across
start_here/modeling/fit/simulator plus 3 new scripts, including adding a faint extra
galaxy + mask_extra_galaxies.fits to multi_galaxy/simulator.py and an
__Extra Galaxies Noise Scaling__ section to the core scripts. The autolens half of this
task must be written against that merged result, so it is deferred to phase 2b. The
autogalaxy half has zero contention (#370 does not touch autogalaxy_workspace) and runs
now.

Scope

autogalaxy_workspace/scripts/multi_galaxy/ has no features/ folder at all. Create:

• scripts/multi_galaxy/features/{README.md, __init__.py}
• scripts/multi_galaxy/features/extra_galaxies/{README.md, __init__.py, simulator.py, modeling.py}

Plus: add a # Folders section to scripts/multi_galaxy/README.md (it currently has none —
its last line is a one-liner pointing at imaging/features).

The shape of the example

Light-only. PyAutoGalaxy has no mass, so unlike the point-source phase (mass-only) and
like the autogalaxy imaging example, extra galaxies here are faint companions whose light
blends with the co-equal pair. Both levers exist and both should be shown, as
autogalaxy_workspace/scripts/imaging/features/extra_galaxies/modeling.py does:

1. Noise scaling — mask_extra_galaxies.fits + dataset.apply_noise_scaling(mask=...),
   then fit the pair without the extras in the model.
2. Modeling — extras in the model as ag.lp_linear.SersicSph with bulge.centre fixed
   to the loaded centre (Option A), with the ag.model_util.mge_model_from(centre_fixed=...)
   MGE variant shown commented-out as Option B. Both are the established autogalaxy
   convention — keep them.

What is new relative to the imaging example is the base model: two co-equal blended
galaxies via the galaxy_0, galaxy_1, ... loop over galaxy_centres.json
(multi_galaxy/modeling.py:109-122, one mge_model_from per galaxy), plus a lower tier of
extra galaxies at fixed centres. That contrast — co-equal subjects and sub-dominant
perturbers in one model — is the point of the example, and the prose should say so.

Conventions to match (autogalaxy differs from autolens)

• The main pair's centres file is galaxy_centres.json, not autolens's
  main_lens_centres.json (multi_galaxy/simulator.py:143-145).
• The main pair sits at (0.0, -0.75) / (0.0, 0.75) with Sersic bulges, and
  modeling.py uses mask_radius=3.0. A larger mask is needed to admit the extra galaxies —
  the imaging example uses 6.0" for exactly this reason.
• Imports are ag. / aplt.; scripts open with from autogalaxy import jax_wrapper then the
  commented setup_notebook line.
• Dataset path is Path("dataset", "multi_galaxy", <name>).
• The new features/README.md should carry the autogalaxy-specific
  "Scaling Relations (not applicable in autogalaxy)" framing already written in
  scripts/imaging/features/extra_galaxies/README.md:18-47 — do not imply the autolens
  scaling-relation tier transfers.

Constraints / known traps

• The new modeling.py should join smoke_tests.txt — multi_galaxy scripts are smoke-enabled
  in this repo (autogalaxy_workspace/smoke_tests.txt:6-7).
• should_simulate tests directory EXISTENCE only — rm -rf dataset/multi_galaxy/extra_galaxies
  before any validation run ([[feedback_should_simulate_existence_only]]).
• PYAUTO_TEST_MODE=1 and =2 share the output/test_mode/ namespace, so a bypass run
  silently resumes a reduced-iterations run. rm -rf output/test_mode before trusting a
  bypass result ([[feedback_autofit_cache_resume_pyauto_test_mode]]).
• Workspace bulk-edit rule: never whole-file Write a file not fully read; run
  scripts/check_sizes.sh before committing.
• Navigator root-name trap — check_navigator.py strips a leading <root.name>/ prefix
  and CI clones the workspace as workspace/, so a literal autogalaxy_workspace/scripts/...
  reference passes locally and fails in CI. Use the wildcard autogalaxy_workspace/*/...
  form. Reproduce CI by cloning into a dir named workspace and passing --root workspace
  ([[reference_docs_ci_gotchas_workspace_assistant]]).

Acceptance

• simulator.py writes its dataset + galaxy_centres.json + extra_galaxies_centres.json +
  mask_extra_galaxies.fits from a clean dataset folder.
• modeling.py runs under PYAUTO_TEST_MODE=2 / PYAUTO_SMALL_DATASETS=1 and is added to
  smoke_tests.txt.
• python .github/scripts/run_smoke.py green; scripts/check_sizes.sh clean.
• Every new folder has a README.md + __init__.py; multi_galaxy/README.md gains a
  # Folders section (README ref-drift is CI-gated).
• Notebooks + navigator catalogue regenerated via PyAutoHands generate.py autogalaxy.
• cluster/ untouched.

[Jammy2211]

PR opened: #184 (pending-release, head dfca793, CI 4/4 green)

scripts/multi_galaxy/features/ created (the folder did not exist) with extra_galaxies/{README,simulator,modeling}, plus a # Folders section on multi_galaxy/README.md and a new smoke_tests.txt entry.

The angle the example is built around: the multi-galaxy model becomes a two-tier model, and choosing the tier is the decision the feature exists to support — co-equal galaxies get a free light model and free centre because decomposing them is the science; extra galaxies get a restricted model with a fixed centre because they only need to stop contaminating it. The tiers describe intent, not brightness.

Two points the multi-galaxy setting forces which the single-galaxy example does not have to make:

• The choice tilts towards modeling over noise-scaling, because the deliverable is a decomposition and residual unmodelled flux is absorbed asymmetrically by the two free light models, biasing the flux ratio that is usually the measurement.
• Fixed centres matter more, because a wandering extra galaxy now has more than one bright thing to drift onto — including a galaxy of the pair, whose light it would begin absorbing.

On validation depth. No full non-linear fit was run, deliberately. Phase 1 warranted one — a mass-only extra-galaxies model on point-source data was new and identifiability was a real question at 12 data points against 10 parameters. This example composes two already-proven patterns, so bypass-mode smoke proves the only genuinely new thing: that the two-tier model composes and the script runs end-to-end.

Two traps hit and worth recording:

1. The capped smoke check (PYAUTO_SMALL_DATASETS=1) rewrote the dataset at 16×16, so a subsequent real fit trained on a 16-pixel image and was worthless — spotted via an IMAGING - Data masked, contains a total of 256 image-pixels line after ~19 minutes of CPU. Between any capped run and any real fit, purge the dataset and output and re-simulate, then confirm with a one-line fits.getdata(...).shape check.
2. ps | grep <script> | awk '{print $1}' returns the wrapper bash PID (0% CPU) ahead of the python PID (108%), which makes a healthy run look stalled.

Also fixed: the same PyAutoHands#213 navigator-gate fallout handled in autolens_workspace#376 — 5 pre-existing literal autogalaxy_workspace/scripts/... references in files this PR does not otherwise touch, switched to the wildcard form the gate tolerates.

Validation: smoke 13/13 (12 before), check_sizes.sh clean, navigator verified under the CI root layout, notebooks + catalogue regenerated, cluster/ untouched.

Shipped on an acknowledged Heart YELLOW (70): workspace validation not passing (0 failed, cloud#30516167217); release validation stale — source moved since rehearsal. Both pre-existing.

Next: phase 2b (autolens multi_galaxy), blocked on autolens_workspace#370 merging.

[Jammy2211]

Shipped. PR #184 merged as 78568683.

scripts/multi_galaxy/features/ now exists, with the extra_galaxies worked example, a # Folders section on multi_galaxy/README.md, and a smoke entry.

Merge-conflict note. The first merge attempt was rejected: docs: make README folder refs repo-relative (c2b47fd, PR #183) landed while this PR was open and fixed the same 5 navigator references exposed by PyAutoHands#213, independently and concurrently. Conflicts were resolved by taking main's version — it uses the repo-relative form (scripts/imaging/features/shapelets) rather than the wildcard form used here, and that is now the house convention. The catalogue was regenerated after the merge rather than hand-resolved, per the standing rule for generated artifacts.

Note the inconsistency this leaves across repos: autolens_workspace PR#376 fixed its equivalent refs with the wildcard form and is already merged. Both pass the gate, but the two workspaces now express the same idea differently — worth a follow-up sweep if the repo-relative form is the intended standard.

Final validation: smoke 13/13, check_sizes.sh clean, navigator verified under the CI root layout both before and after the merge, CI 4/4 green on the merged head 8395cff4. cluster/ untouched.

Deliberately no full non-linear fit — the example composes two already-proven patterns, so bypass-mode smoke proves the only new thing (that the two-tier model composes and runs end-to-end). Phase 1 warranted one because identifiability was genuinely in question there; this does not.

Next: phase 2b (autolens multi_galaxy) remains blocked on autolens_workspace#370.