diff --git a/draft/docs/autolens/docs_three_regime_restructure.md b/draft/docs/autolens/docs_three_regime_restructure.md new file mode 100644 index 00000000..16676e67 --- /dev/null +++ b/draft/docs/autolens/docs_three_regime_restructure.md @@ -0,0 +1,63 @@ +# PyAutoLens RTD docs: three-regime restructure (multi_galaxy / group / cluster) + +Type: docs +Target: PyAutoLens +Repos: +- PyAutoLens +Difficulty: medium +Autonomy: supervised +Priority: high +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +Restructure the PyAutoLens Sphinx/RTD documentation (`PyAutoLens/docs/`) around +the three above-galaxy-scale regimes defined in the parent plan: `multi_galaxy`, +`group`, `cluster` — each presented as its own section with its own tutorials, +example links, API pointers and modelling philosophy. + +## Landed (2026-07-25, this task branch) + +- `docs/overview/overview_2_new_user_guide.md`: the multi_galaxy rung and the + four-step ladder routing with the analysis-split prose landed (PyAutoLens + `c086863` + review fixes). The remaining items below are still open. + +## Changes + +- ~~`docs/overview/overview_2_new_user_guide.md`~~ LANDED (see above). For + reference, the rung decision rules used: + - multi_galaxy: ≥2 co-dominant deflectors, no host halo, standard extended + source. + - group: optional host halo (explicit modelling choice), truncated members + on scaling relations, one dominant extended source. + - cluster: same mass framework as group; many sources at many redshifts → + point-source/multi-image-position workflow by default. + Include the taxonomy sentence: all groups and clusters are multi-galaxy + systems, but not vice versa. +- `docs/overview/overview_1_start_here.md` + `overview_3_features.md`: add the + regime split where scales are enumerated; link the three start_here Colab + notebooks. +- `docs/api/`: ensure the mass/galaxy/point API pages surface the + regime-relevant surfaces where users will look for them — dPIE profiles, + `al.sr` scaling relations, `galaxy_table_from_csv` / + `galaxies_from_csv_tables` / `galaxy_models_from_csv` CSV APIs, and the + point-source/`PointSolver` machinery — grouped or cross-referenced by + regime (a short "which regime uses this" note per surface is enough; do not + fork the API reference into three copies). +- `docs/general/model_cookbook.md`: add multi_galaxy, group (both + with/without-halo compositions) and cluster model recipes. +- Scientific grounding: each regime section cites 2–3 flagship + systems/surveys from the parent plan's literature research (e.g. the + multi_galaxy flagship, SL2S/CASSOWARY groups, HFF/A2744 clusters) so the + docs point at real, recognisable science. + +## Ordering + +Land after (or alongside) the `multi_galaxy` workspace package so notebook +links resolve; the group/cluster narrative edits can reference the workspace +tasks' outcomes but must not block on them. + +## Acceptance + +- Sphinx build clean against `sphinx_warning_baseline.txt`. +- Every notebook link resolves to an existing notebook on the release branch + convention used by the docs. diff --git a/draft/docs/autolens/multi_galaxy_package.md b/draft/docs/autolens/multi_galaxy_package.md new file mode 100644 index 00000000..00a39519 --- /dev/null +++ b/draft/docs/autolens/multi_galaxy_package.md @@ -0,0 +1,108 @@ +# multi_galaxy package: new regime package in autolens_workspace + +Type: docs +Target: autolens_workspace +Repos: +- autolens_workspace +- autolens_workspace_test +Difficulty: large +Autonomy: supervised +Priority: high +Status: in progress — core landed on branch claude/pyautolens-doc-reorganization-w6a1l5 (2026-07-25) +Parent: draft/docs/autolens/split_lensing_regimes.md + +## Landed (2026-07-25, this task branch) + +- autolens_workspace: scripts/multi_galaxy/ with start_here.py, simulator.py + (J1011+0143-like merging pair — 0.9" separation, ~1.8" Einstein cross + verified with 4 bright images + central image), modeling.py, + README.md (regime-ladder + analysis-split table), features/README.md; + top-level README ladder section; group/cluster README + start_here + pointers; smoke registration (both fit scripts validated green under + PYAUTO_TEST_MODE=2 from a clean slate); notebooks + navigator regenerated. +- autolens_workspace_test: scripts/multi_galaxy/model_fit.py (end-to-end, + structural assertions locking the regime) + imaging/multi_galaxy_mge.py + relocated to multi_galaxy/composition_mge.py; smoke updated; validated. +- PyAutoLens docs: New User Guide four-rung ladder + multi_galaxy links + (full RTD restructure remains with docs_three_regime_restructure.md). + +## Remaining + +- features/ scripts (extra_galaxies, scaling_galaxies with untruncated + isothermals, pixelization) — currently README cross-links only. +- Swap start_here to the REAL SDSS J1011+0143 HST data (F555W/F814W via + MAST) once frames are prepared; the simulated look-alike is the interim. +- likelihood_function.py / fit.py mirrors of the group package equivalents. +- autolens_workspace_test multi_galaxy/jax_likelihood/ variant (only + model_fit + the relocated composition test landed). + +Create the new `scripts/multi_galaxy/` package in @autolens_workspace — the first +of the three above-galaxy-scale regimes (see the parent plan for the full design +and literature research). The name is **`multi_galaxy`**, NOT `multi_galaxy_lens` +— concise, and mirrors the `multi_galaxy` package planned for +@autogalaxy_workspace. No collision with the existing `multi/` package (which is +multi-*dataset*/wavelength and keeps its name). + +## Regime definition (from the parent plan) + +Galaxy-scale strong lenses where two or more galaxies contribute significantly +(co-dominantly) to the lensing potential, with NO dominant group/cluster dark +matter halo. Individual halos ~10^11–10^13 M_sun. Mass model = one EPL/SIE per +significant deflector + external shear where appropriate; deflectors are +co-dominant lenses, not satellites in a host halo. Source modelling is the +standard extended-source workflow (parametric Sersic/MGE or pixelized +Delaunay/adaptive meshes) — unchanged from `imaging/`. + +Taxonomy note for all narrative prose: all group- and cluster-scale lenses are +multi-galaxy systems, but not vice versa. `multi_galaxy` is the base rung of the +three-regime ladder; group adds the (optional) host halo + truncated members; +cluster keeps that mass framework and changes the source strategy. + +## Contents + +- `start_here.py` — modeled on `group/start_here.py`'s structure (JAX section, + Colab setup, centre-input JSON/GUI, live visual update). Two co-dominant lens + galaxies, one extended source, standard `AnalysisImaging` fit. Use REAL data: + **SDSS J1011+0143** (arXiv:1602.02927, Shu et al. 2016) — a merging PAIR of + lens galaxies (~4.2 kpc separation, z=0.331) lensing a z=2.701 Lya emitter + into a theta_E ~ 1.84" cross/arc; published model is exactly two SIEs + + shear; public archival HST F555W/F814W via MAST (pin down the program ID at + implementation time; simulate a look-alike if the frames prove unsuitable). + Science hook for the prose: the ~1.7 kpc mass/light offsets a single-SIE + model cannot produce. Runner-up if J1011+0143 falls through: B1608+656 + (see plan — advanced-example caveats). +- `simulator.py` — simulate a two/three-deflector lens (also used to generate + the bundled example dataset if real data cannot be redistributed). +- `modeling.py` — detailed modeling walkthrough (compose N main galaxies, + centres from JSON, priors, MGE lens light per galaxy). +- `likelihood_function.py`, `fit.py` — mirror the group package equivalents. +- `features/` — extra_galaxies and scaling_galaxies as EXTENSIONS (not in the + default model), plus pixelization, MGE, no_lens_light, following + `group/features/` layout. Scaling galaxies here use UNTRUNCATED isothermals + (no dPIE/truncation — truncation is physically motivated by a host halo's + tidal field, which this regime lacks) and the prose must say that at this + scale scaling galaxies are just "a load of galaxies far from the lens". +- `README.md` — regime definition, file inventory, pointers up the ladder to + `group/` and `cluster/`. + +## Cross-cutting edits (same PR) + +- Top-level `autolens_workspace` `README.md`, root `start_here.py` and any + "which regime am I?" prose: introduce the three-regime ladder and link + `multi_galaxy/start_here.ipynb`. +- `group/README.md` + `group/start_here.py` opening prose: point down to + `multi_galaxy/` for systems without a host halo (currently they point only + to `imaging/` and up to `cluster/`). +- `smoke_tests.txt` + `config/build/profile_smoke.yaml`: register the new + scripts; regenerate notebooks + navigator catalogue via PyAutoHands. + +## autolens_workspace_test (same-named branch, second PR) + +Mirror the taxonomy: add `scripts/multi_galaxy/` integration tests (model_fit + +jax_likelihood variant) following the existing per-dataset subfolder pattern. + +## Acceptance + +- `python .github/scripts/run_smoke.py` green with the new entries. +- Notebooks + navigator catalogue regenerated. +- No use of the string `multi_galaxy_lens` anywhere. diff --git a/draft/docs/autolens/split_lensing_regimes.md b/draft/docs/autolens/split_lensing_regimes.md new file mode 100644 index 00000000..99bdf10c --- /dev/null +++ b/draft/docs/autolens/split_lensing_regimes.md @@ -0,0 +1,332 @@ +# Split lensing regimes: multi_galaxy / group / cluster (epic plan) + +Type: docs +Target: PyAutoLens +Repos: +- PyAutoLens +- PyAutoGalaxy +- autolens_workspace +- autolens_workspace_test +- autogalaxy_workspace +- autogalaxy_workspace_test +- autolens_assistant +Difficulty: too-large +Autonomy: supervised +Priority: high +Status: planned (epic — execute via the child prompts below) + +Reorganize the PyAutoLens (and mirrored PyAutoGalaxy) documentation and example +library by splitting systems above the standard single-galaxy strong-lens +regime into THREE distinct categories, each with its own tutorials, example +scripts, API documentation and modelling philosophy: + + 1. `multi_galaxy` (NOT `multi_galaxy_lens` — concise, and mirrors the + autogalaxy package name; no collision with `multi/`, which stays + multi-dataset/wavelength) + 2. `group` + 3. `cluster` + +This file is the coordinating plan: the regime design, the literature research +grounding each regime's examples, the current-state audit, the technical +conventions checklist, and the index of PR-sized child prompts. It was +re-planned in Fable from the original intake on 2026-07-25. + +## The taxonomy (applies to all narrative prose) + +All group- and cluster-scale lenses are multi-galaxy systems, but not vice +versa. The three regimes form a ladder, not three islands: + +- `multi_galaxy` — ≥2 co-dominant galaxy-scale deflectors (individual halos + ~10^11–10^13 M_sun), NO dominant host halo. Mass = one EPL/SIE per + significant deflector (+ external shear). Source = standard extended-source + workflow (Sersic/MGE or Delaunay/adaptive pixelizations), unchanged from + `imaging/`. +- `group` — adds a DOMINANT group-scale dark halo (~10^13–10^14 M_sun) as an + EXPLICIT, OPTIONAL modelling choice, and represents member galaxies as + tidally truncated subhalos (dPIE / truncated isothermal) tied by luminosity + scaling relations. Typically ONE dominant extended source, so the + source-modelling philosophy is UNCHANGED — the sophistication moves into + the mass model. Every group tutorial teaches BOTH compositions + (members-only vs members+halo) and when a halo is scientifically motivated. +- `cluster` — the SAME mass framework as group (host halo(s) >10^14 M_sun, + many truncated members, scaling relations). What changes is the + observational regime and therefore the SOURCE STRATEGY: dozens–hundreds of + members lens many independent sources over a wide redshift range, so the + default workflow is multiple-image positions / point-source constraints + with per-source redshifts and joint optimization of one mass model + (multi-plane). Extended-source reconstruction is a specialised follow-up of + individual systems, never the default. + +Key design principle: group and cluster share the mass-modelling framework; +the regime boundary PyAutoLens draws between them is the source-modelling +strategy, not the mass parameterization. + +Three-tier galaxy API: the main_galaxies / extra_galaxies / scaling_galaxies +tiers are retained across ALL regimes. Basic multi_galaxy examples use just +main_galaxies (extra/scaling as feature extensions); group and cluster +defaults use all three tiers. Scaling galaxies at galaxy/multi_galaxy scale +use UNTRUNCATED isothermals — truncation encodes tidal stripping by a host +halo, which those regimes lack by definition; truncated dPIE members appear +at group scale. This physical thread ties the ladder together. + +## Literature research (grounding for examples and citations) + +Researched via web search 2026-07-25; all arXiv IDs verified against arxiv.org. + +### Cluster regime + +Flagship `start_here`: **Abell 2744** on the Bergamini et al. 2023 (A&A 670, +A60; arXiv:2207.09416) spectroscopic gold subset — CONFIRMED as the right +choice (already implemented). Two caveats for the docs: (i) state explicitly +that the tutorial uses the pre-JWST spectroscopic gold subset by design +(speed + robustness) — JWST-era models of the same cluster now use ~135–150 +images (Bergamini et al. GLASS-JWST, arXiv:2303.10210; Furtak et al. 2023, +arXiv:2212.04381/UNCOVER); (ii) A2744 is a merging multi-halo system — good +for teaching "one or more host halos", but point to AS1063 (Caminha et al., +arXiv:1512.04555) as the "simplest relaxed real cluster" counterpoint. + +Secondary systems for feature examples (public constraint catalogues): + +- **MACS J0416** — Bergamini et al. 2023 (arXiv:2208.14020): 237 + spectroscopic images from 88 sources (z=0.94–6.63), the largest secure + sample for any cluster; team inputs public. The "scaling-up" example. +- **SMACS J0723** (JWST First Deep Field) — Mahler et al. 2023 + (arXiv:2207.07101), Caminha et al. 2022 (arXiv:2207.07567); compact, + iconic, modest constraint count — the mid-size example. +- **MACS J1149 + SN Refsdal** — Grillo et al. 2016 (arXiv:1511.04093), + Kelly et al. 2023 Science (arXiv:2305.06367, H0 from the reappearance), + Grillo et al. 2024 (arXiv:2401.10980) — the time-delay-cosmography + feature example (point sources + delays + multi-plane). +- **Abell 370** — Lagattuta et al. 2019 (arXiv:1904.02158), BUFFALO + strong+weak Niemiec et al. 2023 (arXiv:2307.03778) — a second HFF cluster + with a very different (bimodal giant-arc) configuration. +- **SDSS J1004+4112** — genuinely cluster-scale (~10^14 M_sun) 5-image + lensed quasar, longest measured delay (6.73 yr); Forés-Toribio et al. + 2022 (arXiv:2206.09856). Bridges galaxy-scale point-source users to the + cluster machinery. + +Benchmark programs to cite: HFF (Lotz et al. 2017, arXiv:1605.06567; public +lens models from ~8 teams at MAST, incl. LensTool .par files — feeds the +lenstool/ interop example), CLASH (arXiv:1106.3328), RELICS +(arXiv:1903.02002), BUFFALO (arXiv:2001.09999), JWST UNCOVER +(arXiv:2212.04026), SGAS (Sharon et al. 2020, arXiv:1904.05940 — LensTool +models for 37 clusters, the volume source for interop testing), MUSE atlas +(Richard et al. 2021, arXiv:2009.09784 — public redshifts + LensTool models +for 12 clusters). + +Methodology reading list: Kassiola & Kovner 1993 ApJ 417,450 (PIEMD; +pre-arXiv — cite journal); Elíasdóttir et al. 2007 (arXiv:0710.5636, dPIE +defined in the appendix); Jullo et al. 2007 (arXiv:0706.0048, Lenstool +Bayesian MCMC); Broadhurst et al. 2005 (astro-ph/0409132, first ~100-image +cluster, A1689); Bergamini et al. 2019 (arXiv:1905.13236, kinematically +calibrated scaling relations); Meneghetti et al. 2017 (arXiv:1606.04548, HFF +model-comparison project); Meneghetti et al. 2020 Science (arXiv:2009.04471, +GGSL substructure excess — the science case for r_cut_ref); Natarajan et al. +2024 review (arXiv:2403.06245 — the modern overview). Other codes to name: +GLEE (Suyu & Halkola 2010), GLAFIC (Oguri 2010, arXiv:1005.3103), free-form +GRALE / WSLAP+ / SWUnited. + +### Group regime + +Flagship recommendation: **CASSOWARY 19 (SDSS J0900+2234)** — extended bright +arc + counter-images from a single dominant source (z=2.03, a merging pair), +lens group z~0.49, theta_E ~ 7", M(~2" implies +environmental mass); Verdugo (halo suffices) vs Suyu & Halkola (member +subhalo individually constrained) as the two poles; Foëx et al. 2014 +(arXiv:1409.5905, lensing selection bias toward concentrated groups — why +tutorial systems are not "typical" groups). + +Samples/surveys to cite: SL2S groups (Limousin et al. 2009, arXiv:0812.1033 +— 13 systems framed exactly as the 1e13–1e14 M_sun gap), SARCS (More et al. +2012 arXiv:1109.1821; Foëx et al. 2013 arXiv:1308.4674 — 80 secure groups), +CASSOWARY (Belokurov et al. 2009 arXiv:0806.4188; Stark et al. 2013 +arXiv:1302.2663), AGEL DR2 (arXiv:2503.08041), Euclid Q1 discovery engine +(arXiv:2503.15324) — which operationally defines group-scale as ">1 and <25 +member galaxies", a definition worth quoting in the docs. + +### Multi-galaxy regime + +Flagship `start_here`: **SDSS J1011+0143** — the system of the user-suggested +arXiv:1602.02927 (Shu et al. 2016, ApJ 820, 43), which holds up as the best +verified match. A close MERGING PAIR of lens galaxies (projected sep ~4.2 kpc) +at z=0.331 lensing a Lya emitter at z=2.701 into a wide (theta_E ~ 1.84") +cross/arc with three resolvable knots; the published model is exactly the +regime's default (two SIEs + shear); public archival HST F555W/F814W (MAST); +science hook: mass/light offsets up to ~1.7 kpc — a result a single-SIE model +physically cannot produce, which motivates the whole regime. Discovery paper: +Bolton et al. 2006 (astro-ph/0606210). Runner-up: B1608+656 (richer extended +ring, deeper public ACS, but dust + AGN images + group environment make it an +advanced example, not a start_here). Implementation note: pin down the HST +program ID in MAST when building the dataset; simulate a look-alike if the +real frames prove unsuitable for redistribution. + +Secondary systems for feature examples: + +- **B1608+656** — two INTERACTING deflectors + extended dusty host ring; + Suyu et al. 2009 (arXiv:0804.2827) potential reconstruction and Suyu et + al. 2010 (arXiv:0910.2773) H0 — the canonical two-deflector cosmography. +- **PS J0630-1201** — five-image quasar from a dual-SIE lens with a host + arc; Lemon et al. 2018 (arXiv:1803.07601) — image-multiplicity feature. +- **2M1310-1714** — galaxy pair inside a ~2.9" Einstein ring, public + HST/WFC3; Lucey et al. 2018 (arXiv:1711.02674). +- **HE0230-2130** — two same-redshift deflectors and a missing fifth image + constraining cored profiles; Ertl et al. 2024 (arXiv:2308.05181). +- **J1721+8842** — the "Einstein zigzag": two deflectors at DIFFERENT + redshifts (z=0.184, 1.885), six images; Dux et al. 2025 + (arXiv:2411.04177) — the bridge to multi-plane features. Pair with + **J0946+1006** (the Jackpot, Gavazzi et al. 2008 arXiv:0801.1555) while + stating explicitly that the Jackpot is a SINGLE deflector with multiple + source planes — i.e. multi-plane, NOT multi-galaxy; a useful taxonomy + clarification for the docs. + +Statistics/context: no clean literature number exists for "what fraction of +galaxy-scale lenses have co-dominant secondary deflectors" — the literature +splits into satellite-incidence statistics (Jackson et al. 2010 +arXiv:0912.0614; Nierenberg et al. 2011 arXiv:1102.1426) and per-sample +modelling choices (Shajib et al. 2019 arXiv:1807.09278; STRIDES 30-quad +sample Shajib et al. 2022 arXiv:2206.04696) — state that gap honestly in the +docs. Theory anchor: Möller et al. 2001 (astro-ph/0103093). Forward-looking +motivation: Euclid Q1 discovery engines (arXiv:2503.15324, 2503.15327 — +~500 candidates in 63 deg^2, >100k forecast full-survey). PyAutoLens +precedent to cite: Etherington et al. 2022 (arXiv:2202.09201, 59 automated +HST lens fits) and Ding et al. 2025 (arXiv:2504.11445, CSWA 19 modelled at +pixel level with PyAutoLens through a Sersic-to-adaptive-mesh chain). + +## Current-state audit (2026-07-25) + +Already in place (do not rebuild): + +- `autolens_workspace/scripts/cluster/` — real Abell 2744 `start_here` (7 gold + systems / 25 images from the Bergamini et al. 2023 model inputs, 2 BCGs, 188 + scaling members, NFW host, multi-plane, JAX point solver), `csv_api.py` + (mass/light/point + scaling_galaxies CSVs), `lenstool/` interop, + `mass_parameterizations.py` (+ `_pyautolens.py`) with the expert-reviewed + Lenstool-convention models. +- `autolens_workspace/scripts/group/` — real Euclid dataset `start_here` + (2 main lens galaxies, MGE light, centre-GUI JSON), `features/` + (scaling_relation, pixelization, MGE, …), SLaM. Gaps: `start_here` fits + main_galaxies only (no scaling/extra tiers); NO host-halo example — the + halo-choice tutorial does not exist; README still frames groups only by + galaxy count. +- `autolens_workspace/scripts/imaging/features/` — `extra_galaxies/` and + `scaling_relation/` exist; regime-caveat prose and + interferometer/point_source parity need auditing. +- PyAutoGalaxy library — multiple-galaxy composition, `sr` scaling-relation + namespace, and the CSV APIs (`galaxy_table_from_csv`, + `galaxies_from_csv_tables`, `galaxy_models_from_csv`) already exist and + re-export through autolens. The library side of this epic is docs, not API. +- PyAutoLens `docs/overview/overview_2_new_user_guide.md` — routes + galaxy/group/cluster; needs the multi_galaxy rung and the ladder rewrite. + +Missing entirely: `multi_galaxy` packages (both workspaces), autogalaxy +`cluster` package, group halo-choice tutorial, cluster extended-source +follow-up feature, regime restructure of both RTD doc trees. + +## The galaxy/lens divergence (record once, state everywhere relevant) + +autogalaxy mirrors the regime split with `multi_galaxy` and `cluster` +packages of its own (light-only: no mass, no sources). Deliberate divergence: +the autogalaxy cluster workflow MODELS the foreground galaxies' light (that is +its entire subject), while the autolens cluster default workflow does NOT +model foreground lens light (point-source constraints only; lens-light +modelling arrives later as an autolens feature). This is the first significant +structural departure between the galaxy and lens doc trees — both New User +Guides must state it so users moving between libraries are not surprised. + +## Technical conventions checklist (from expert review, 2026-07 Slack) + +Verify these hold everywhere the group/cluster mass framework is documented. +STATUS 2026-07-25: applied to `cluster/mass_parameterizations.py` and +`cluster/mass_parameterizations_pyautolens.py` (the expert-reviewed guides) +and to the dPIE library docstrings (sigma_LT/sigma_0 attribution corrected +per the H. Ding derivation note) on this task branch. STILL DATED: +`cluster/start_here.py`, `cluster/simulator.py`, `cluster/modeling.py` (and +the bundled `cluster/simple` dataset simulated from the old truths — +r_core scaled with L, radius exponent 0.5, r_cut_ref 15.8") — swept by the +cluster_regime_narrative child prompt, which must re-run the simulator to +regenerate the dataset alongside the convention change. + +- Members: r_core fixed to a negligibly small value and NOT scaled with + luminosity (r_a = 0 is safe — handled analytically, no division-by-zero). +- Scaling relation: Bergamini et al. 2019 form — dispersion exponent alpha + and truncation exponent beta tied via 2*alpha + beta = 1 + gamma, with + gamma = 0.2 fixed (the old Lenstool-paper slopes are dated); exponents + free-able in detailed modelling, and beta_a vs beta_s need not be equal + unless r_a/r_s is assumed constant. +- r_cut_ref: reference member truncation ~5", not 20" (lensing-constrained + typical values; scientifically interesting via the Meneghetti et al. + substructure-lensing excess). +- Host halo: dPIE with fixed r_cut is the Lenstool-literature default and + stays the default example; the (G)NFW alternative is documented as the + physically preferred choice ("beyond the LensTool default" guide). +- sigma vs b0: dPIEMass takes velocity dispersion (dPIEMassB0 keeps the + angular parameterization); the sigma_LT-vs-sigma_0 convention mismatch + (Elíasdóttir et al. 2007 vs Kassiola & Kovner 1993) is documented per the + contributed derivation note — b0 != Einstein radius for finite r_s. + +## Child prompts (one prompt = one task = one PR) and execution order + +1. `draft/docs/autolens/multi_galaxy_package.md` — new + `autolens_workspace/scripts/multi_galaxy/` package (+ workspace_test + mirror). Unblocks everything user-facing; do first. +2. `draft/docs/workspaces/group_halo_explicit_choice.md` — group start_here + gains all three tiers; new `features/group_halo/` halo-choice tutorial. +3. `draft/docs/workspaces/cluster_regime_narrative.md` — cluster narrative + alignment + `features/extended_source/` follow-up example + conventions + cross-check. +4. `draft/docs/autolens/docs_three_regime_restructure.md` — PyAutoLens RTD + docs ladder rewrite (after 1, so links resolve). +5. `draft/docs/workspaces/galaxy_scale_scaling_extra_features.md` — + imaging/interferometer/point_source extra_galaxies + scaling_galaxies + feature parity with regime caveats. +6. `draft/docs/workspaces/autogalaxy_multi_galaxy_package.md` — autogalaxy + multi_galaxy package (+ test mirror). +7. `draft/docs/workspaces/autogalaxy_cluster_package.md` — autogalaxy cluster + package (+ test mirror). +8. `draft/docs/libraries/autogalaxy_docs_regime_guides.md` — PyAutoGalaxy RTD + New User Guide (after 6+7). +9. `draft/docs/workspaces/assistants_regime_extension.md` — assistants + follow-up (deferred until 1–8 ship). + +1–4 are the PyAutoLens-facing core (Priority: high); 5–8 are the mirror and +parity passes (normal); 9 is deferred. 1, 6 and 7 are independent of each +other and parallelizable; 2 and 3 touch disjoint packages and can run in +parallel with 1. diff --git a/draft/docs/autolens/split_lensing_regimes_into_multi_galaxy_lens.md b/draft/docs/autolens/split_lensing_regimes_into_multi_galaxy_lens.md deleted file mode 100644 index e15ccddf..00000000 --- a/draft/docs/autolens/split_lensing_regimes_into_multi_galaxy_lens.md +++ /dev/null @@ -1,110 +0,0 @@ -# Split lensing regimes into multi_galaxy_lens, group and cluster - -Type: docs -Target: PyAutoLens -Repos: -- PyAutoLens -- autolens_workspace -- autolens_workspace_test -- workspaces -Difficulty: too-large -Autonomy: supervised -Priority: high -Status: formalised - -Reorganize the PyAutoLens documentation and example library by splitting systems -above the standard single-galaxy strong-lens regime into THREE distinct categories, -applied throughout the PyAutoLens docs, autolens_workspace, autolens_workspace_test, -and profiling (developer) workspaces: - - 1. multi_galaxy_lens - 2. group - 3. cluster - -This is primarily a documentation and workflow decision intended to help users -understand the different modelling regimes they are likely to encounter. The final -documentation should present these as three separate sections, each with its own -tutorials, example scripts, API documentation, and modelling philosophy. - -For each regime, research representative example lenses, well-known papers, and -observational samples (e.g. SLACS, BELLS, HST Frontier Fields, etc.) to motivate the -examples we include. Use Fable (or equivalent literature research) to identify the -best examples rather than relying on prior knowledge. Recommend the most appropriate -real lens systems, surveys, papers, and benchmark datasets to accompany each section -so tutorials are grounded in widely used literature examples. - -## 1. Multi-galaxy lenses -Galaxy-scale strong lenses where two or more galaxies contribute significantly to the -lensing potential, but there is NO dominant group or cluster dark matter halo. -Host halo masses ~10^11-10^13 M_sun; no separate group-scale halo required. Mass model -= multiple galaxy-scale mass profiles (EPL, SIE), one per significant deflector, plus -external shear where appropriate. These galaxies are co-dominant lenses, not satellites -embedded in a larger host halo. Source modelling = standard PyAutoLens workflow, either -parametric source light (Sersic) or pixelized source reconstructions (Delaunay, adaptive -meshes). - -## 2. Group-scale lenses -Dominant group-scale dark matter halo, total masses ~10^13-10^14 M_sun. Lens galaxies -represented as tidally truncated subhalos (Pseudo-Jaffe or truncated isothermal) whose -parameters are usually tied through scaling relations. IMPORTANT: every group-scale -tutorial and example should present the inclusion of the group dark matter halo as an -EXPLICIT modelling choice. Some systems genuinely require a group halo; others may be -adequately described by the galaxy members alone. Users should learn BOTH workflows and -understand when introducing a host halo is scientifically motivated; the docs must -explain this decision rather than assuming the host halo is always present. Source -modelling: typically ONE dominant extended lensed source, a natural extension of the -existing source reconstruction framework (Sersic, multi-Gaussian, pixelized Delaunay, -adaptive meshes). Mass model more sophisticated than galaxy-scale, but source-modelling -philosophy largely unchanged. - -## 3. Cluster-scale lenses -NOT fundamentally different from group lenses in mass parameterization. Halo masses -> 10^14 M_sun (often 10^15). Mass model still = one or more extended host halos + many -truncated member galaxies + scaling relations for the galaxy population. PyAutoLens -should distinguish cluster-scale lenses through the SOURCE MODELLING STRATEGY. Clusters -commonly contain dozens-to-hundreds of member galaxies and simultaneously lens many -independent background galaxies over a wide redshift range; modern cluster models include -tens-to-hundreds of multiply-imaged systems. Reconstructing every source as extended -Sersic/pixelized is generally not practical or necessary. Standard strategy becomes: -multiple image positions; point-source constraints; individual source redshifts; joint -optimization of a common cluster mass model. Extended source reconstructions should be -presented as specialised follow-up analyses of individual systems, not the default -cluster workflow. - -## Documentation structure (three regimes) -- Multi-galaxy: multiple co-dominant galaxy halos; no explicit host halo; standard - extended source reconstruction. -- Group: optional host halo (user decides); truncated member galaxies; single extended - source via parametric or pixelized methods. -- Cluster: one or more host halos; large populations of truncated member galaxies - (typically >20, often hundreds); many background sources at different redshifts; - default workflow based on point-source constraints rather than extended reconstruction. - -Key design principle: group- and cluster-scale lenses share essentially the SAME mass -modelling framework; the distinction in PyAutoLens is driven by the observational regime -and therefore the source modelling strategy. - -## Additional key requirements -1. Retain the main_galaxies / extra_galaxies / scaling_galaxies API for ALL three - regimes; all 3 tiers are used across all 3 examples. Basic MGL examples use just - main_galaxies, but include extra_galaxies and scaling_galaxies as extensions in - features (analogous to imaging / interferometer / point_source single-galaxy examples). - Group-scale default start_here and simulator/modeling examples should include scaling - galaxies and extra galaxies; cluster obviously should too. -2. For galaxy-scale examples (imaging, interferometer, point_source) in features, include - examples with extra_galaxies and scaling_galaxies, but make clear that while - extra_galaxies are expected to be used, scaling_galaxies would just be a load of - galaxies far from the lens. -3. The scaling_galaxies in the galaxy-scale and multi-galaxy-lens examples should NOT - include truncation, and thus use mass profiles like isothermals (untruncated) — which - follows how scaling galaxies are currently implemented in the group package, consistent - with the discussion above. - -## Execution note -Documentation + workflow + example-library reorganization spanning PyAutoLens docs, -autolens_workspace, autolens_workspace_test, and profiling/developer workspaces. The -actual implementation will be re-planned in Fable (including the literature research); -this intake only needs to capture and formalize the requirement, classified and sized, -ready to go. - - diff --git a/draft/docs/libraries/autogalaxy_docs_regime_guides.md b/draft/docs/libraries/autogalaxy_docs_regime_guides.md new file mode 100644 index 00000000..b607dc83 --- /dev/null +++ b/draft/docs/libraries/autogalaxy_docs_regime_guides.md @@ -0,0 +1,39 @@ +# PyAutoGalaxy RTD docs: multi_galaxy + cluster in New User Guide and overviews + +Type: docs +Target: PyAutoGalaxy +Repos: +- PyAutoGalaxy +Difficulty: small +Autonomy: supervised +Priority: normal +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +Surface the new autogalaxy_workspace `multi_galaxy` and `cluster` packages in +the PyAutoGalaxy Sphinx/RTD documentation (`PyAutoGalaxy/docs/`), mirroring the +three-regime restructure landing in PyAutoLens docs (parent plan). + +## Changes + +- `docs/overview/overview_2_new_user_guide.md`: add the routing rungs — single + galaxy → multi_galaxy (2+ blended galaxies' light) → cluster (BCG + a member + population from a catalogue) — with links to the new start_here notebooks. +- `docs/overview/overview_1_start_here.md` / `overview_3_features.md`: mention + the multiple-galaxy composition API and the galaxy CSV-loading API + (`galaxy_table_from_csv`, `galaxies_from_csv_tables`, + `galaxy_models_from_csv`) where features are enumerated. +- State the deliberate galaxy/lens divergence where the cluster workflow is + introduced: autogalaxy cluster examples model the foreground galaxies' + light (that is the whole task); autolens cluster examples do not (point + source constraints only, lens light later) — one sentence each side, so + users moving between libraries are not surprised. + +## Ordering + +Land after the autogalaxy_workspace multi_galaxy and cluster packages exist, +so links resolve. + +## Acceptance + +- Sphinx build clean; links resolve. diff --git a/draft/docs/workspaces/assistants_regime_extension.md b/draft/docs/workspaces/assistants_regime_extension.md new file mode 100644 index 00000000..59e2c452 --- /dev/null +++ b/draft/docs/workspaces/assistants_regime_extension.md @@ -0,0 +1,36 @@ +# Assistants: regime-aware routing for multi_galaxy / group / cluster (follow-up) + +Type: docs +Target: autolens_assistant +Repos: +- autolens_assistant +Difficulty: medium +Autonomy: supervised +Priority: low +Status: draft (deferred — land after the workspace/doc reorganization ships) +Parent: draft/docs/autolens/split_lensing_regimes.md + +Once the three-regime reorganization (parent plan) has landed in +autolens_workspace, autogalaxy_workspace and the RTD docs, extend the +assistants so a user describing their system is routed to the right regime +workflow. + +## Scope + +- @autolens_assistant: add/extend skills so "I have a lens with two lens + galaxies / a group / a cluster" routes to the multi_galaxy, group or + cluster workflow respectively; teach the regime decision rules (co-dominant + deflectors vs host halo vs many-source point workflow; all groups/clusters + are multi-galaxy systems but not vice versa); refresh `wiki/core/` regime + pages via `al_update_wiki`; add the parent plan's flagship literature + systems to `wiki/literature/` following its schema. +- Galaxy-side assistant: the autogalaxy assistant does not exist yet as a + repo; when it is seeded (via the Clone/Mitosis machinery), its seed should + inherit the multi_galaxy + cluster (light) workflows. Record the + requirement here; do not create the repo as part of this task. + +## Ordering + +Blocked on: multi_galaxy_package, group_halo_explicit_choice, +cluster_regime_narrative, autogalaxy packages. Do not start before those +merge — the assistant must document the shipped surface, not the plan. diff --git a/draft/docs/workspaces/autogalaxy_cluster_package.md b/draft/docs/workspaces/autogalaxy_cluster_package.md new file mode 100644 index 00000000..28c916fb --- /dev/null +++ b/draft/docs/workspaces/autogalaxy_cluster_package.md @@ -0,0 +1,50 @@ +# autogalaxy_workspace: new cluster package (many-galaxy light modelling) + +Type: docs +Target: autogalaxy_workspace +Repos: +- autogalaxy_workspace +- autogalaxy_workspace_test +Difficulty: large +Autonomy: supervised +Priority: normal +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +Create the `scripts/cluster/` package in @autogalaxy_workspace: modelling the +LIGHT of a cluster's galaxy population — BCG(s) modelled individually plus tens +to hundreds of member galaxies loaded from catalogues. PyAutoGalaxy deals in +neither mass models nor lensed sources, so this package is the photometric +counterpart of the autolens cluster package: the same population-scale +composition machinery, applied to light. + +## Contents + +- `start_here.py` — a cluster field image; BCG with individual MGE light + model; member population loaded from a CSV catalogue via the galaxy + CSV-loading API (`galaxy_table_from_csv`, `galaxies_from_csv_tables`, + `galaxy_models_from_csv`); simultaneous or iterative fit of the population's + light. IMPORTANT: unlike the autolens cluster start_here, this workflow's + entire point IS the foreground galaxies' light — make that contrast explicit + (parent plan records it as the first significant galaxy/lens divergence). +- `simulator.py` — simulate a cluster field (BCG + N members from a catalogue). +- `modeling.py`, `csv_api.py` — the CSV surface for light profiles, mirroring + `autolens_workspace/scripts/cluster/csv_api.py` (which covers mass + points; + here it is light + population catalogues). +- `features/` — e.g. scaling the population fit (linear light profiles across + many galaxies), masking/segmentation of members, intracluster light as an + advanced note if the API supports it. +- `README.md` — regime framing + pointer to the autolens cluster package for + the lensing side of the same objects. + +## Cross-cutting + +- Register smoke entries; regenerate notebooks + navigator catalogue. +- autogalaxy_workspace_test: mirror integration scripts. +- If any gap surfaces in the PyAutoGalaxy CSV/light API while writing the + examples, file it as a separate library prompt rather than working around + it in workspace prose. + +## Acceptance + +- Smoke suite green; notebooks + navigator regenerated. diff --git a/draft/docs/workspaces/autogalaxy_multi_galaxy_package.md b/draft/docs/workspaces/autogalaxy_multi_galaxy_package.md new file mode 100644 index 00000000..8ff4649b --- /dev/null +++ b/draft/docs/workspaces/autogalaxy_multi_galaxy_package.md @@ -0,0 +1,57 @@ +# autogalaxy_workspace: new multi_galaxy package + +Type: docs +Target: autogalaxy_workspace +Repos: +- autogalaxy_workspace +- autogalaxy_workspace_test +Difficulty: large +Autonomy: supervised +Priority: normal +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +Create the `scripts/multi_galaxy/` package in @autogalaxy_workspace, mirroring +the regime split being introduced in @autolens_workspace (parent plan). This is +the light-only counterpart: simultaneous modelling of the LIGHT of two or more +galaxies in one image (blended/overlapping systems, pairs, compact groups) — +PyAutoGalaxy deals in neither mass models nor source galaxies, so the regime +here is purely "how do I compose and fit N galaxies' light at once". + +The name `multi_galaxy` is shared deliberately with autolens (the autolens name +was chosen to mirror this package). No collision with `multi/` +(multi-wavelength), which keeps its name. + +## Contents + +- `start_here.py` — two overlapping galaxies (e.g. a close pair with blended + light), composing two `ag.Galaxy` models with MGE/linear light profiles, + centres from JSON (reuse the centre-GUI convention from the autolens group + package), `AnalysisImaging` fit. +- `simulator.py`, `modeling.py`, `features/` (linear light profiles, MGE, + sky subtraction, ellipse variants where sensible), `README.md`. +- Uses the multiple-galaxy model-composition API and the galaxy CSV-loading + API already in PyAutoGalaxy (`galaxy_table_from_csv`, + `galaxies_from_csv_tables`, `galaxy_models_from_csv`) — a features example + demonstrates loading many galaxies from CSV. + +## Cross-cutting + +- Top-level README + any new-user routing prose: introduce the two-package + extension (multi_galaxy, cluster) of the workspace taxonomy. +- Register smoke entries; regenerate notebooks + navigator catalogue. +- autogalaxy_workspace_test: mirror integration scripts (model_fit + + jax_likelihood) under the same package name. + +## Key divergence to document (from the parent plan) + +In autogalaxy, multi-galaxy and cluster examples ARE about the foreground +galaxies' light — the default workflow models it. In autolens, the cluster +default workflow does NOT model foreground lens light (point-source +constraints only; lens-light features later). This is the first significant +deliberate divergence between the galaxy and lens doc trees — state it in the +README so users moving between the two libraries aren't surprised. + +## Acceptance + +- Smoke suite green; notebooks + navigator regenerated. diff --git a/draft/docs/workspaces/cluster_regime_narrative.md b/draft/docs/workspaces/cluster_regime_narrative.md new file mode 100644 index 00000000..09d0dd23 --- /dev/null +++ b/draft/docs/workspaces/cluster_regime_narrative.md @@ -0,0 +1,89 @@ +# Cluster package: point-source-default narrative + extended-source follow-up feature + +Type: docs +Target: autolens_workspace +Repos: +- autolens_workspace +- autolens_workspace_test +Difficulty: medium +Autonomy: supervised +Priority: high +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +Align the `scripts/cluster/` package of @autolens_workspace with the +three-regime design (see parent plan). The mass framework (host halo(s) + +truncated members + scaling relations) is intentionally SHARED with the group +regime — the cluster regime is distinguished by the observational setting and +therefore the SOURCE MODELLING STRATEGY: dozens–hundreds of members, many +multiply-imaged sources across a wide redshift range, so the default workflow +is multiple-image positions / point-source constraints with individual source +redshifts, jointly optimizing one cluster mass model (multi-plane). Extended +source reconstruction is a specialised follow-up analysis of individual +systems, NOT the default. + +Much of this package already exists (real Abell 2744 start_here on the +Bergamini et al. 2023 gold sample, dPIE + scaling relations, CSV API, +LensTool interop, mass_parameterizations guide). This task is narrative +alignment + gap-filling, not a rebuild. + +## Changes + +- `README.md` + `start_here.py` prose: state the regime-ladder design + explicitly — same mass framework as `group/`, different source strategy; + all clusters are multi-galaxy systems but not vice versa; link down the + ladder to `group/` and `multi_galaxy/`. +- New `features/extended_source/` follow-up example: take one system from the + cluster fit (e.g. one A2744 arc) and do a targeted extended-source + reconstruction (imaging + pixelized source) with the cluster mass model as + the starting point — framed explicitly as the specialised follow-up, and as + the bridge back to the group/galaxy-scale source machinery. Note the + foreground lens light is NOT modelled in the default cluster workflow (a + deliberate divergence from @autogalaxy_workspace's cluster package, which + is *about* the galaxies' light); an autolens lens-light cluster feature is + future work, out of scope here. +- Conventions sweep — the guides (`mass_parameterizations.py`, + `mass_parameterizations_pyautolens.py`) and the dPIE library docstrings + were corrected on 2026-07-25 (Bergamini et al. 2019 tied exponents with + gamma=0.2, vanishing unscaled member cores, r_cut_ref ~5", sigma_LT vs + sigma_0 attribution per the H. Ding derivation note). STILL TO SWEEP here: + `start_here.py` (scaling_radius_exponent=0.5, r_core scaled with L, + r_cut_ref 15.8"), `simulator.py` (same dated truths) and `modeling.py` + (refs fixed at those truths). The simulator truths and the bundled + `cluster/simple` dataset must change TOGETHER — re-run the simulator and + commit the regenerated dataset in the same PR, then re-validate modeling + and start_here end-to-end (this is why the sweep was deferred to this + child task rather than done alongside the guides). +- gNFW guidance: ensure the "beyond the LensTool default" prose (dPIE host → + (G)NFW host) is present and linked from start_here, per the expert feedback + recorded in the parent plan. +- Ground the narrative in the parent plan's cluster literature section + (HFF/CLASH/JWST-era benchmarks, model-comparison projects) with citations. + Specifics from the research: state that start_here uses the PRE-JWST + spectroscopic gold subset of Bergamini et al. 2023 by design (JWST-era + models of A2744 now use ~135–150 images); name AS1063 as the "simplest + relaxed cluster" counterpoint to merging A2744; candidate future feature + systems — MACS J0416 (largest spec sample, scaling-up), SMACS J0723 + (mid-size, JWST-iconic), MACS J1149/SN Refsdal (time-delay cosmography), + SDSS J1004+4112 (cluster-lensed quasar bridge from point_source users). + +## Conventions-sweep validation note (2026-07-25) + +The sweep of simulator.py/modeling.py/start_here.py + regenerated +cluster/simple dataset landed on the task branch. modeling.py validated +green end-to-end (PYAUTO_TEST_MODE=2) against the regenerated data. +start_here.py (real a2744, 188 members, multi-plane) did NOT complete a +45-minute bypass-mode run on the dev container's CPU — the JAX compile of +the point solver dominates and is unchanged by the sweep (constants only; +2 fewer free parameters). It is not smoke-gated. First GPU session should +run it once to confirm end-to-end (expected ~10 min). + +## autolens_workspace_test + +Add/extend a cluster extended-source follow-up integration script. + +## Acceptance + +- Smoke suite green; notebooks + navigator regenerated. +- A new user reading cluster/README understands why cluster examples fit + positions not pixels, and where the extended-source path lives. diff --git a/draft/docs/workspaces/galaxy_scale_scaling_extra_features.md b/draft/docs/workspaces/galaxy_scale_scaling_extra_features.md new file mode 100644 index 00000000..f47214d2 --- /dev/null +++ b/draft/docs/workspaces/galaxy_scale_scaling_extra_features.md @@ -0,0 +1,47 @@ +# Galaxy-scale features: extra_galaxies + scaling_galaxies extensions with regime caveats + +Type: docs +Target: autolens_workspace +Repos: +- autolens_workspace +Difficulty: medium +Autonomy: supervised +Priority: normal +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +Ensure the single-galaxy-scale example trees (`imaging/`, `interferometer/`, +`point_source/`) each expose `extra_galaxies` and `scaling_galaxies` as +FEATURES, with prose calibrated to the regime ladder (parent plan): the +main_galaxies / extra_galaxies / scaling_galaxies three-tier API is available +in ALL regimes, but at galaxy scale the tiers mean different things than at +group/cluster scale. + +## Current state + +`imaging/features/` already has `extra_galaxies/` and `scaling_relation/`. +Audit these against the requirements below and replicate/cross-link for +`interferometer/` and `point_source/` (cross-linking to the imaging feature is +acceptable where the physics is identical — do not fork near-identical prose). + +## Requirements + +- extra_galaxies at galaxy scale: expected, common practice (nearby + perturbers with fixed centres, SIS/SIE mass) — say so. +- scaling_galaxies at galaxy scale: supported but explicitly framed as "a + load of galaxies far from the lens" — usually a weak correction, not a + co-dominant component. The example must say when this is and is not worth + the complexity. +- Scaling galaxies at galaxy scale and multi_galaxy scale use UNTRUNCATED + mass profiles (isothermals): truncation encodes tidal stripping by a host + halo, which these regimes lack by definition. Truncated dPIE members are + introduced at group scale. This physical reasoning must appear in the + feature prose (it is the thread that ties the three regimes together). +- Each feature's wrap-up points up the ladder: "if your extra galaxies are + co-dominant → multi_galaxy/; if they sit in a common halo → group/". + +## Acceptance + +- Smoke suite green; notebooks + navigator regenerated. +- Feature prose consistent across imaging/interferometer/point_source (one + canonical text, cross-linked). diff --git a/draft/docs/workspaces/group_halo_explicit_choice.md b/draft/docs/workspaces/group_halo_explicit_choice.md new file mode 100644 index 00000000..d8fee34b --- /dev/null +++ b/draft/docs/workspaces/group_halo_explicit_choice.md @@ -0,0 +1,90 @@ +# Group package: host halo as an explicit modelling choice + default scaling/extra tiers + +Type: docs +Target: autolens_workspace +Repos: +- autolens_workspace +- autolens_workspace_test +Difficulty: large +Autonomy: supervised +Priority: high +Status: in progress — signature tutorial landed on branch claude/pyautolens-doc-reorganization-w6a1l5 (2026-07-25) +Parent: draft/docs/autolens/split_lensing_regimes.md + +## Landed (2026-07-25, this task branch) + +- `group/features/group_halo/` (simulator + modeling + README): fits the + same dataset members-only vs members+halo with an identical truncated-dPIE + member tier (Bergamini+19 tied exponents, vanishing cores), the + radius/evidence/external-information decision framework, and an + `include_group_halo` simulator switch to invert the verdict. Registered in + smoke (validated green from a clean slate); notebooks regenerated; + features README + regime-ladder README edits landed with the multi_galaxy + package commit. + +## Remaining + +- `start_here.py` default model gains the extra_galaxies + scaling_galaxies + tiers (currently main_galaxies only) — needs scaling-galaxy + centres/luminosities prepared for the real Euclid dataset. +- `modeling.py`/`simulator.py` halo-narrative threading; CSWA 19 as the + possible future real-data flagship for this feature (public HST + + published PyAutoLens model, arXiv:2504.11445). + +Rework the `scripts/group/` package of @autolens_workspace to match the +three-regime design (see parent plan): a group-scale lens has a DOMINANT +group-scale dark matter halo (~10^13–10^14 M_sun) as a *candidate* model +component, member galaxies as tidally truncated subhalos (dPIE/truncated +isothermal) tied by luminosity scaling relations, and typically ONE dominant +extended lensed source — so the source-modelling philosophy is unchanged from +galaxy scale (Sersic, MGE, Delaunay/adaptive pixelizations). + +## The central documentation requirement + +Every group-scale tutorial and example must present the inclusion of the group +dark matter halo as an EXPLICIT modelling choice, never an assumption. Some +systems genuinely require a host halo; others are adequately described by the +member galaxies alone. Users must learn BOTH workflows and when a host halo is +scientifically motivated (evidence: image configurations/arc curvature not +reproducible by members alone, mass-to-light offsets, X-ray/dynamical priors — +ground this in the parent plan's literature section, e.g. the SL2S/CASSOWARY +group-modeling papers). + +## Changes + +- `start_here.py`: add the scaling-galaxies and extra-galaxies tiers to the + DEFAULT model (currently it fits only the 2 main lens galaxies). The default + start_here composition becomes: main_galaxies + extra_galaxies + + scaling_galaxies — all three tiers, as at cluster scale. Keep the current + real Euclid dataset unless the parent plan's literature section motivates a + better public flagship (one dominant arc, 2–5 members, host-halo evidence). +- New `features/group_halo/` example (name it `group_halo`, not `host_halo`, + to match regime vocabulary): compose the SAME system twice — (a) + members-only, (b) members + group-scale halo (dPIE per Lenstool convention, + with a gNFW variant shown) — fit both, and walk through Bayesian model + comparison (evidence difference) plus the physical arguments for/against + the halo. This is the regime's signature tutorial. Preferred system per the + parent plan's research: **CASSOWARY 19 (SDSS J0900+2234)** — public HST, + theta_E ~ 7", one dominant z=2.03 source, and a published PyAutoLens model + (Ding et al. 2025, arXiv:2504.11445: dPIE group halo + 16 dPIE members + + shear) the tutorial can reproduce; model the 3–5 brightest members + explicitly and put the rest on the scaling relation. +- `modeling.py` / `simulator.py`: thread the halo-choice narrative through; + simulator gains a with-halo variant so both feature workflows have data. +- Scaling-relation prose: align with the conventions checklist in the parent + plan (Bergamini et al. 2019-style relation; members' r_core fixed small and + NOT scaled with luminosity; truncation exponent tied to the dispersion + exponent; r_cut_ref ~5" scale, not 20"). +- `README.md`: regime ladder (down to `multi_galaxy/`, up to `cluster/`), + "is my lens a group?" guidance, literature pointers from the parent plan. + +## autolens_workspace_test + +Extend `scripts/group/` (or add) integration scripts covering members-only vs +members+halo model composition, so both compositions stay green in CI. + +## Acceptance + +- Smoke suite green; notebooks + navigator regenerated. +- No group example presents the host halo as mandatory; the halo-choice + tutorial fits both compositions end-to-end under PYAUTO_TEST_MODE. diff --git a/draft/feature/autogalaxy/dpie_sigma0_parameterization.md b/draft/feature/autogalaxy/dpie_sigma0_parameterization.md new file mode 100644 index 00000000..b22afb14 --- /dev/null +++ b/draft/feature/autogalaxy/dpie_sigma0_parameterization.md @@ -0,0 +1,39 @@ +# dPIE: optional central-dispersion (sigma_0) parameterization + +Type: feature +Target: PyAutoGalaxy +Repos: +- PyAutoGalaxy +- autolens_workspace +Difficulty: small +Autonomy: supervised +Priority: low +Status: draft +Parent: draft/docs/autolens/split_lensing_regimes.md + +The contributed derivation note (H. Ding 2026, "On the definitions of b0 and +velocity dispersion in Lenstool / dPIE") establishes that Lenstool's fiducial +dispersion sigma_LT is a bookkeeping convention (E07-style b0 coefficient +paired with the K93/L05 deflection amplitude), and recommends the physical +central dispersion sigma_0 — with b0 = 4 * pia_c2 * sigma_0^2 — as the +cleaner parameter for scientific interpretation, unless exact Lenstool +parameter parity is required. + +`dPIEMass` deliberately keeps sigma_LT so fitted posteriors read like +Lenstool results tables (docstrings corrected on the doc-reorganization +branch, 2026-07-25). This prompt proposes ADDING the sigma_0 option without +disturbing that default: + +- Either a `dPIEMassSigma0` sibling class (constructor takes `sigma_0`, + internal b0 = 4*648000*(sigma_0/c)^2*(D_LS/D_S)) or a + `sigma_convention="lenstool"|"central"` constructor switch — pick + whichever composes more cleanly with af.Model priors and the CSV API. +- Docstrings cross-reference the two conventions and the sqrt(3/2) mapping. +- Unit tests: sigma_0 = sqrt(3/2)*sigma_LT inputs produce identical + deflections; Lenstool parity tests untouched. +- One workspace example line in `cluster/mass_parameterizations.py` showing + the physical-convention alternative. + +Motivation for prioritising later: no behaviour is wrong today; this is an +interpretability convenience for users comparing fitted dispersions with +measured stellar kinematics.