From 17f3889c79350f05b346c88b425e82cc325c5532 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Jul 2026 11:31:53 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20RTD=20three-regime=20remainder=20?= =?UTF-8?q?=E2=80=94=20api=20regime=20notes,=20cookbook=20recipes,=20flags?= =?UTF-8?q?hips?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes the RTD leg of the regime split (single-copy API reference with per-surface regime notes, per the plan): - overview_1_start_here.md: regime enumerations spell out the four-rung ladder (galaxy-scale, multi-galaxy, group-scale, cluster-scale). - overview_2_new_user_guide.md: the ladder now cites flagship systems per rung (SDSS J1011+0143 / B1608+656; CSWA 19 / SL2S; HFF Abell 2744). - api/mass.rst: Total section notes untruncated Isothermal/PowerLaw for galaxy/multi-galaxy vs tidally truncated dPIE members for group/cluster (sigma_lt vs b0 parameterizations named). - api/point.rst: point sources are also the standard source strategy at cluster scale (per-source redshifts, multi-plane). - api/galaxy.rst: new Galaxy Catalogues (CSV) section documenting galaxy_table_from_csv / galaxies_from_csv_tables / galaxy_af_models_from_csv_tables (previously absent from the API docs). - general/model_cookbook.md: new Multi Galaxy, Group and Cluster Models section — per-deflector loop recipe, shared-prior scaling-relation tie, cluster point-source framing, links to the regime notebooks. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_012Eacj9naBWSKrevsqnVJWR --- docs/api/galaxy.rst | 18 ++++++++- docs/api/mass.rst | 7 ++++ docs/api/point.rst | 4 ++ docs/general/model_cookbook.md | 46 ++++++++++++++++++++++ docs/overview/overview_1_start_here.md | 11 +++--- docs/overview/overview_2_new_user_guide.md | 6 +++ 6 files changed, 86 insertions(+), 6 deletions(-) diff --git a/docs/api/galaxy.rst b/docs/api/galaxy.rst index 311be2180..48cd03e86 100644 --- a/docs/api/galaxy.rst +++ b/docs/api/galaxy.rst @@ -33,4 +33,20 @@ The ``Redshift`` object does not need to be used for general **PyAutoGalaxy** us :template: custom-class-template.rst :recursive: - Redshift \ No newline at end of file + Redshift + +Galaxy Catalogues (CSV) +----------------------- + +Load many galaxies from a ``y, x, luminosity`` CSV catalogue — the input format of the +scaling-relation galaxy tier used at multi-galaxy, group and cluster scale (see the +``multi_galaxy``, ``group`` and ``cluster`` packages of the ``autolens_workspace``). +``galaxy_table_from_csv`` reads the catalogue; the two ``*_from_csv_tables`` functions +build instances or model components from it. + +.. autosummary:: + :toctree: _autosummary + + galaxy_table_from_csv + galaxies_from_csv_tables + galaxy_af_models_from_csv_tables \ No newline at end of file diff --git a/docs/api/mass.rst b/docs/api/mass.rst index cccfab6ce..0f52e918c 100644 --- a/docs/api/mass.rst +++ b/docs/api/mass.rst @@ -5,6 +5,13 @@ Mass Profiles Total [ag.mp] ------------- +The ``Isothermal`` / ``PowerLaw`` family are the standard **untruncated** profiles for +galaxy-scale and multi-galaxy lenses (no host halo, so no tidal truncation). The ``dPIE`` +family are **tidally truncated** profiles for the member galaxies of group- and +cluster-scale lenses, whose ``r_cut`` encodes stripping by the host halo's potential +(``dPIEMass`` is parameterized by Lenstool's native ``sigma`` — the fiducial dispersion +sigma_LT; ``dPIEMassB0`` by the deflection normalization ``b0``). + .. currentmodule:: autogalaxy.profiles.mass .. autosummary:: diff --git a/docs/api/point.rst b/docs/api/point.rst index f53ab3b67..d1b8a1c54 100644 --- a/docs/api/point.rst +++ b/docs/api/point.rst @@ -6,6 +6,10 @@ Point sources arise when the background object is compact (e.g. a quasar, supern compact radio source) and is modelled by its image-plane positions, flux ratios, and/or time delays rather than by a resolved surface-brightness distribution. +They are also the standard source strategy of **cluster-scale** lens modeling, where each +of many background sources contributes its multiple-image positions (each at its own +redshift, ray-traced multi-plane) — see the ``cluster`` package of the ``autolens_workspace``. + Dataset ------- diff --git a/docs/general/model_cookbook.md b/docs/general/model_cookbook.md index bc5184376..610a17a49 100644 --- a/docs/general/model_cookbook.md +++ b/docs/general/model_cookbook.md @@ -365,6 +365,52 @@ as manually customize it in the .json file directory. This is used for composing complex models of group scale lenses. +## Multi Galaxy, Group and Cluster Models + +Above galaxy scale, models are composed for three regimes (see the New User Guide's "What Scale +System?" ladder — all groups and clusters are multi-galaxy systems, but not vice versa): + +**Multi-galaxy lenses** (2+ co-dominant deflectors, no host halo): one free light + mass model per +deflector, composed in a loop with **untruncated** isothermals (no host halo means no tidal +truncation): + +```python +lens_dict = {} + +for i, centre in enumerate(main_lens_centres): + mass = af.Model(al.mp.Isothermal) + mass.centre = (centre[0], centre[1]) + + lens_dict[f"lens_{i}"] = af.Model(al.Galaxy, redshift=0.5, mass=mass) + +model = af.Collection(galaxies=af.Collection(**lens_dict, source=source)) +``` + +**Group-scale lenses** add two things as explicit modelling choices: an optional dark-matter +**group halo**, and faint members whose masses are tied to their luminosities through a shared +scaling relation, so N galaxies cost one free parameter (composed via prior arithmetic on a +shared prior): + +```python +einstein_radius_ref = af.UniformPrior(lower_limit=0.0, upper_limit=1.0) + +for i, (centre, luminosity) in enumerate(zip(centres, luminosities)): + mass = af.Model(al.mp.IsothermalSph) + mass.centre = (centre[0], centre[1]) + mass.einstein_radius = einstein_radius_ref * (luminosity / reference_luminosity) ** 0.5 +``` + +**Cluster-scale lenses** keep the group mass framework (halo + tidally truncated ``dPIE`` +members on scaling relations) but change the source strategy: many point-source multiple-image +position datasets, each at its own redshift, fitted via ``AnalysisPoint``. + +The following example notebooks show each regime's full model composition: + + + + + + ## Many Profile Models (Advanced) Features such as the Multi Gaussian Expansion (MGE) and shapelets compose models consisting of 50 - 500+ light diff --git a/docs/overview/overview_1_start_here.md b/docs/overview/overview_1_start_here.md index 2a50e35d6..53ea7fbbb 100644 --- a/docs/overview/overview_1_start_here.md +++ b/docs/overview/overview_1_start_here.md @@ -352,8 +352,8 @@ progressively improving the quality of the fit until the model closely reproduce **Credit: Amy Etherington** -The next documentation page guides you through lens modeling for a variety of lensing regimes (e.g. galaxy–galaxy lenses, -cluster-scale lenses) and data types (e.g. CCD imaging, interferometer data). +The next documentation page guides you through lens modeling for a variety of lensing regimes (galaxy-scale, +multi-galaxy, group-scale and cluster-scale lenses) and data types (e.g. CCD imaging, interferometer data). ## Simulations @@ -364,15 +364,16 @@ Simulating strong lenses is often essential, for example to: - Test lensing theory in a fully controlled environment. The next documentation page guides you through how to simulate lenses for different types of strong -lenses (e.g. galaxy–galaxy lenses, cluster-scale lenses) and different types of data (e.g. CCD imaging, interferometer data). +lenses (galaxy-scale, multi-galaxy, group-scale and cluster-scale) and different types of data (e.g. CCD imaging, +interferometer data). ## Wrap Up This completes the introduction to **PyAutoLens**, including a brief overview of the core API for lensing calculations, lens modeling, and data simulation. -Different users will be interested in strong lenses across different lensing regimes (e.g. galaxy-scale or -cluster-scale lenses) and using different data types (e.g. CCD imaging or interferometer data). +Different users will be interested in strong lenses across different lensing regimes (galaxy-scale, multi-galaxy, +group-scale or cluster-scale lenses) and using different data types (e.g. CCD imaging or interferometer data). The autolens_workspace repository contains a wide range of examples and tutorials covering these use cases. The next documentation page helps new users identify the most appropriate starting point based on their scientific goals. diff --git a/docs/overview/overview_2_new_user_guide.md b/docs/overview/overview_2_new_user_guide.md index 13c500a2e..f972340c3 100644 --- a/docs/overview/overview_2_new_user_guide.md +++ b/docs/overview/overview_2_new_user_guide.md @@ -39,6 +39,12 @@ but not vice versa. What changes as you climb is first the mass model, then the reconstructing extended sources, and the lens galaxies' light is not modeled. If you are interested in clusters, go to the [cluster/start_here.ipynb](https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/cluster/start_here.ipynb) notebook. +For a sense of the real science each rung anchors to: multi-galaxy lenses include merging-pair systems like +SDSS J1011+0143 (two SIEs + shear; Shu et al. 2016) and the famous time-delay lens B1608+656; group-scale +lenses include CSWA 19 (Ding et al. 2025, modeled with **PyAutoLens**) and the SL2S group sample; cluster-scale +lenses include the Hubble Frontier Fields clusters, most notably Abell 2744 (Bergamini et al. 2023) — the +system the workspace's cluster `start_here` models. + ## What Dataset Type? If you are interested in galaxy-scale strong lenses, you now need to decide what type of strong lens data you are