Skip to content

docs: cluster lensing as mature + three-ways-to-learn guide #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Jul 9, 2026
Merged

docs: cluster lensing as mature + three-ways-to-learn guide #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,16 @@ https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026
Then checkout the [new user starting guide](https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) to navigate the
workspace for your science case.

## Three Ways to Learn PyAutoLens

There are three ways to learn how to use **PyAutoLens**, which you can freely mix and match:

1. **Manual navigation** — read the workspace guides yourself, starting from `start_here.ipynb` and the [new user starting guide](https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html), which organise the examples by lens scale and dataset type.
2. **AI chat assistant** — ask questions to a conversational AI assistant such as ChatGPT or Claude in the browser. Point it at the [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) repository and ask a question like *"How do I model a galaxy-scale strong lens observed with Hubble imaging?"*.
3. **Fully agentic AI** — drive **PyAutoLens** end-to-end with an agentic coding tool such as [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex) together with [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant). These can inspect your data, write and run scripts, and manage a lens-modeling project directly on your machine.

See [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) for more on the AI-assisted options (2 and 3).

## HowToLens

If the workspace examples move too quickly, **HowToLens** is a separate four-chapter tutorial lecture series that walks
Expand Down
6 changes: 0 additions & 6 deletions notebooks/cluster/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
The `cluster` folder contains example scripts showing how to analyse cluster scale strong lenses,
which are lenses where 10-100+ galaxies are responsible for the lensing of 3-50+ sources.

# IN DEVELOPMENT

Cluster strong lensing is an **IN DEVELOPMENT** feature with the examples in this folder incomplete and
subject to change. They are here so that experienced users can begin to explore cluster lensing
capabilities early, but new users and inexperience lens modelers may struggle to use them.

# Start Here

New users should read the `start_here` example, which gives an overview of all examples in the folder.
Expand Down
81 changes: 44 additions & 37 deletions notebooks/cluster/start_here.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@
" their own light and mass profiles.\n",
" - **Tens to hundreds of lower-mass member galaxies**, whose collective mass perturbs the deflection\n",
" field non-trivially but whose individual contributions are too weak to constrain on their own. These\n",
" are modelled jointly on a luminosity-mass scaling relation, so the entire population shares just two\n",
" free parameters regardless of how many members are in the catalogue.\n",
" are modelled jointly on a luminosity-mass scaling relation, so the entire population shares a single\n",
" free parameter regardless of how many members are in the catalogue.\n",
" - **One or more cluster-scale dark matter halos** (``10^14 \u2013 10^15`` M_sun), modelled with NFW-like\n",
" profiles and not tied to any individual galaxy.\n",
" - **Multiple background sources at different redshifts**, multiply imaged by the cluster \u2014 this makes\n",
Expand All @@ -31,7 +31,7 @@
"__Contents__\n",
"\n",
"- **JAX:** GPU/CPU acceleration; cluster fits take ~10 minutes on a GPU.\n",
"- **Beta Feature:** Cluster modeling is a beta feature \u2014 what works and what doesn't.\n",
"- **Capabilities:** What cluster modeling supports, and practical tips for using it.\n",
"- **Google Colab Setup:** Bootstraps the environment when running on Colab.\n",
"- **Imports:** The libraries we'll use.\n",
"- **Dataset:** Load the CCD image and the per-source point datasets.\n",
Expand Down Expand Up @@ -63,20 +63,17 @@
"shows the post-Phase-2 `PointSolver(use_jax=True)` +\n",
"`autolens.jax.register_tracer_classes(tracer)` pattern in action.\n",
"\n",
"__Beta Feature__\n",
"__Capabilities__\n",
"\n",
"Cluster modeling with **PyAutoLens** is in beta. Strengths:\n",
"Cluster modeling with **PyAutoLens** offers:\n",
"\n",
" - JAX-accelerated image-plane chi-squared is over 50\u00d7 faster than mainstream cluster modeling tools.\n",
" - Multi-plane ray tracing of arbitrary complexity is supported natively.\n",
" - Hand-editable CSV inputs (point datasets, scaling-galaxy catalogues) make iterating on a real cluster\n",
" straightforward.\n",
" - JAX-accelerated image-plane chi-squared, over 50\u00d7 faster than mainstream cluster modeling tools.\n",
" - Multi-plane ray tracing of arbitrary complexity, supported natively.\n",
" - Hand-editable CSV inputs (point datasets, scaling-galaxy catalogues) that make iterating on a real\n",
" cluster straightforward.\n",
"\n",
"Known limitations:\n",
"\n",
" - Default ``aplt`` visualization is tuned for galaxy-scale lenses; cluster-specific plotters are in\n",
" active development.\n",
" - Workspace documentation for cluster modeling is less comprehensive than for galaxy-scale features.\n",
"Practical tip: the default ``aplt`` visualization is tuned for galaxy-scale lenses, so when inspecting\n",
"cluster fits you may prefer to build custom figures of the multiple-image positions and source planes.\n",
"\n",
"__Google Colab Setup__\n",
"\n",
Expand Down Expand Up @@ -148,10 +145,12 @@
" - ``point_datasets.csv`` \u2014 one row per observed multiple image, grouped by source ``name``, with a\n",
" ``redshift`` column per source.\n",
" - ``scaling_galaxies.csv`` \u2014 one row per scaling-tier member with columns ``y, x, luminosity``.\n",
" - ``main_lens_centres.json`` \u2014 centres of the 2 individually-modelled main galaxies.\n",
" - ``host_halo_centre.json`` \u2014 centre of the host halo.\n",
" - ``mass.csv`` / ``light.csv`` / ``point.csv`` \u2014 named-galaxy CSVs carrying the full truth model,\n",
" including the centres of the main galaxies and host halo (see ``csv_api.py``).\n",
"\n",
"If the dataset is missing on disk, the corresponding simulator script runs automatically."
"If the dataset does not already exist on your system (per ``al.util.dataset.should_simulate``,\n",
"which also handles the smoke-mode ``PYAUTO_SMALL_DATASETS`` regeneration case), it is created\n",
"by running the corresponding simulator script."
]
},
{
Expand All @@ -161,11 +160,7 @@
"dataset_name = \"simple\"\n",
"dataset_path = Path(\"dataset\") / \"cluster\" / dataset_name\n",
"\n",
"if (\n",
" not (dataset_path / \"data.fits\").exists()\n",
" or not (dataset_path / \"scaling_galaxies.csv\").exists()\n",
" or not (dataset_path / \"mass.csv\").exists()\n",
"):\n",
"if al.util.dataset.should_simulate(str(dataset_path)):\n",
" subprocess.run(\n",
" [sys.executable, \"scripts/cluster/simulator.py\"],\n",
" check=True,\n",
Expand Down Expand Up @@ -311,10 +306,13 @@
" - **Main lens galaxies (2):** individually-modelled ``dPIEMassSph`` profiles with centre fixed to the\n",
" observed light centres and free ``ra``, ``rs``, ``b0``. **6 free parameters total.**\n",
"\n",
" - **Scaling-tier members (10):** ``dPIEMassSph`` profiles with centre fixed to the CSV centres,\n",
" ``ra`` and ``rs`` fixed at the simulator truth values (0.1\" and 10.0\"), and ``b0`` derived from the\n",
" *shared* relation ``b0 = scaling_factor * luminosity ** scaling_exponent`` plus the per-member\n",
" luminosity. **2 free parameters total for the whole tier \u2014 independent of the number of members.**\n",
" - **Scaling-tier members (10):** ``dPIEMassSph`` profiles with centre fixed to the CSV centres and\n",
" ``ra`` fixed (0.1\"). ``b0`` and ``rs`` derive from the reference-anchored relation used by Lenstool\n",
" and standard in published cluster analyses: ``b0 = b0_ref * (L / L_ref) ** 0.5`` and\n",
" ``rs = rs_ref * (L / L_ref) ** 0.5``, where the reference is the *brightest* member. The exponent is\n",
" fixed at the Faber-Jackson value (b0 \u221d sigma\u00b2 and sigma \u221d L^(1/4) give b0 \u221d L^(1/2)) \u2014 only the\n",
" normalization ``b0_ref``, the reference member's lens strength, is fitted.\n",
" **1 free parameter total for the whole tier \u2014 independent of the number of members.**\n",
"\n",
" - **Host dark matter halo:** a standalone ``Galaxy`` carrying an ``NFWMCRLudlowSph`` halo with\n",
" centre fixed and a free ``mass_at_200``. **1 free parameter.**\n",
Expand All @@ -323,8 +321,11 @@
" ``GaussianPrior`` centre priors initialised from the mean of each source's observed positions.\n",
" **4 free parameters total.**\n",
"\n",
"**Total: N = 13 free parameters.** Adding more rows to ``scaling_galaxies.csv`` does not grow N \u2014 that's\n",
"the defining feature of cluster-scale modeling on a scaling relation.\n",
"**Total: N = 12 free parameters.** Adding more rows to ``scaling_galaxies.csv`` does not grow N \u2014 that's\n",
"the defining feature of cluster-scale modeling on a scaling relation. See\n",
"``scripts/cluster/modeling.py`` for the full prose on the scaling-relation convention (why the\n",
"normalization anchors to a reference galaxy, why the exponent is fixed, and the kinematic calibrations\n",
"that refine it).\n",
"\n",
"__Redshifts__\n",
"\n",
Expand All @@ -337,8 +338,8 @@
"__Model__\n",
"\n",
"The model is composed below in four blocks: main-tier loop, host halo, source-tier loop, scaling-tier\n",
"loop (defining shared ``scaling_factor`` / ``scaling_exponent`` once outside the loop). The four\n",
"blocks are then bundled into a single ``af.Collection`` model that the analysis will receive."
"loop (defining the shared ``b0_ref`` normalization once outside the loop). The four blocks are then\n",
"bundled into a single ``af.Collection`` model that the analysis will receive."
]
},
{
Expand Down Expand Up @@ -378,23 +379,28 @@
" mean=float(np.mean(positions[:, 1])), sigma=3.0\n",
" )\n",
"\n",
"# Scaling Tier (shared scaling_factor + scaling_exponent; per-member b0 derived).\n",
"# Scaling Tier (reference-anchored: b0_ref is the single shared free parameter, the\n",
"# lens strength of the brightest member; per-member b0 and rs derive from it with\n",
"# the exponents fixed at the Faber-Jackson value 0.5 \u2014 the Lenstool convention).\n",
"\n",
"scaling_factor = af.UniformPrior(lower_limit=0.0, upper_limit=1.0)\n",
"scaling_exponent = af.UniformPrior(lower_limit=0.0, upper_limit=2.0)\n",
"scaling_b0_ref = af.UniformPrior(lower_limit=0.0, upper_limit=1.0)\n",
"scaling_exponent = 0.5\n",
"\n",
"scaling_luminosity_ref = max(scaling_galaxies_luminosity_list)\n",
"scaling_ra_fixed = 0.1\n",
"scaling_rs_fixed = 10.0\n",
"scaling_rs_ref_fixed = 10.0\n",
"\n",
"scaling_galaxies_list = []\n",
"for centre, luminosity in zip(\n",
" scaling_galaxies_centres, scaling_galaxies_luminosity_list\n",
"):\n",
" luminosity_ratio = luminosity / scaling_luminosity_ref\n",
"\n",
" mass = af.Model(al.mp.dPIEMassSph)\n",
" mass.centre = tuple(centre)\n",
" mass.ra = scaling_ra_fixed\n",
" mass.rs = scaling_rs_fixed\n",
" mass.b0 = scaling_factor * luminosity**scaling_exponent\n",
" mass.rs = scaling_rs_ref_fixed * luminosity_ratio**scaling_exponent\n",
" mass.b0 = scaling_b0_ref * luminosity_ratio**scaling_exponent\n",
"\n",
" scaling_galaxies_list.append(af.Model(al.Galaxy, redshift=redshift_lens, mass=mass))\n",
"\n",
Expand Down Expand Up @@ -576,7 +582,8 @@
"- ``data.fits`` / ``noise_map.fits`` / ``psf.fits`` \u2014 your imaging.\n",
"- ``point_datasets.csv`` \u2014 your measured multiple-image positions, with per-source redshifts.\n",
"- ``scaling_galaxies.csv`` \u2014 your scaling-tier members' centres and luminosities.\n",
"- ``main_lens_centres.json`` / ``host_halo_centre.json`` \u2014 your individually-modelled centres.\n",
"- ``mass.csv`` / ``point.csv`` \u2014 your individually-modelled galaxies (centres and profiles), in the\n",
" named-galaxy CSV schema (see ``csv_api.py``).\n",
"\n",
"Update ``dataset_name`` above to point at the new folder, and the rest of the script runs unchanged."
]
Expand Down
6 changes: 0 additions & 6 deletions scripts/cluster/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
The `cluster` folder contains example scripts showing how to analyse cluster scale strong lenses,
which are lenses where 10-100+ galaxies are responsible for the lensing of 3-50+ sources.

# IN DEVELOPMENT

Cluster strong lensing is an **IN DEVELOPMENT** feature with the examples in this folder incomplete and
subject to change. They are here so that experienced users can begin to explore cluster lensing
capabilities early, but new users and inexperience lens modelers may struggle to use them.

# Start Here

New users should read the `start_here` example, which gives an overview of all examples in the folder.
Expand Down
21 changes: 9 additions & 12 deletions scripts/cluster/start_here.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
__Contents__

- **JAX:** GPU/CPU acceleration; cluster fits take ~10 minutes on a GPU.
- **Beta Feature:** Cluster modeling is a beta feature — what works and what doesn't.
- **Capabilities:** What cluster modeling supports, and practical tips for using it.
- **Google Colab Setup:** Bootstraps the environment when running on Colab.
- **Imports:** The libraries we'll use.
- **Dataset:** Load the CCD image and the per-source point datasets.
Expand Down Expand Up @@ -58,20 +58,17 @@
shows the post-Phase-2 `PointSolver(use_jax=True)` +
`autolens.jax.register_tracer_classes(tracer)` pattern in action.

__Beta Feature__
__Capabilities__

Cluster modeling with **PyAutoLens** is in beta. Strengths:
Cluster modeling with **PyAutoLens** offers:

- JAX-accelerated image-plane chi-squared is over 50× faster than mainstream cluster modeling tools.
- Multi-plane ray tracing of arbitrary complexity is supported natively.
- Hand-editable CSV inputs (point datasets, scaling-galaxy catalogues) make iterating on a real cluster
straightforward.
- JAX-accelerated image-plane chi-squared, over 50× faster than mainstream cluster modeling tools.
- Multi-plane ray tracing of arbitrary complexity, supported natively.
- Hand-editable CSV inputs (point datasets, scaling-galaxy catalogues) that make iterating on a real
cluster straightforward.

Known limitations:

- Default ``aplt`` visualization is tuned for galaxy-scale lenses; cluster-specific plotters are in
active development.
- Workspace documentation for cluster modeling is less comprehensive than for galaxy-scale features.
Practical tip: the default ``aplt`` visualization is tuned for galaxy-scale lenses, so when inspecting
cluster fits you may prefer to build custom figures of the multiple-image positions and source planes.

__Google Colab Setup__

Expand Down
24 changes: 22 additions & 2 deletions start_here.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -561,8 +561,28 @@
"different types of data (e.g. imaging, interferometer, and point-source observations). Depending on the scientific \n",
"questions you are interested in, the analysis you perform may differ significantly.\n",
"\n",
"The autolens_workspace contains a suite of example Jupyter Notebooks, organised by lens scale and dataset type. \n",
"To help you find the most appropriate starting point, we begin by answering two simple questions.\n",
"The autolens_workspace contains a suite of example Jupyter Notebooks, organised by lens scale and dataset type.\n",
"\n",
"__Three Ways To Learn PyAutoLens__\n",
"\n",
"There are three ways to learn how to use **PyAutoLens**, which you are free to mix and match:\n",
"\n",
"1. **Manual Navigation**: Read the workspace guides yourself. To find the example notebook best suited to your science\n",
" case, work through the two questions below (\"What Scale Lens?\" and \"What Data Type?\"), which point you to the right\n",
" starting point. This is the traditional route, and the rest of this guide supports it.\n",
"\n",
"2. **AI Chat Assistant**: Ask questions to a conversational AI assistant such as ChatGPT or Claude in the browser.\n",
" Point it at the autolens_assistant repository (https://github.com/PyAutoLabs/autolens_assistant) and ask questions\n",
" like \"How do I model a galaxy-scale strong lens observed with Hubble imaging?\". This is ideal for learning the API,\n",
" working out how to perform a calculation, and interpreting or debugging errors.\n",
"\n",
"3. **Fully Agentic AI**: Use an agentic coding tool such as Claude Code (https://claude.com/claude-code) or Codex\n",
" (https://developers.openai.com/codex) together with autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant).\n",
" These can inspect your data, write and run scripts, and manage an end-to-end lens modeling project directly on your\n",
" machine. See the autolens_assistant repository for more information.\n",
"\n",
"The rest of this guide supports **manual navigation**: we begin by answering two simple questions to find your most\n",
"appropriate starting point.\n",
"\n",
"__What Scale Lens?__\n",
"\n",
Expand Down
24 changes: 22 additions & 2 deletions start_here.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -415,8 +415,28 @@ def simulate(tracer):
different types of data (e.g. imaging, interferometer, and point-source observations). Depending on the scientific
questions you are interested in, the analysis you perform may differ significantly.

The autolens_workspace contains a suite of example Jupyter Notebooks, organised by lens scale and dataset type.
To help you find the most appropriate starting point, we begin by answering two simple questions.
The autolens_workspace contains a suite of example Jupyter Notebooks, organised by lens scale and dataset type.

__Three Ways To Learn PyAutoLens__

There are three ways to learn how to use **PyAutoLens**, which you are free to mix and match:

1. **Manual Navigation**: Read the workspace guides yourself. To find the example notebook best suited to your science
case, work through the two questions below ("What Scale Lens?" and "What Data Type?"), which point you to the right
starting point. This is the traditional route, and the rest of this guide supports it.

2. **AI Chat Assistant**: Ask questions to a conversational AI assistant such as ChatGPT or Claude in the browser.
Point it at the autolens_assistant repository (https://github.com/PyAutoLabs/autolens_assistant) and ask questions
like "How do I model a galaxy-scale strong lens observed with Hubble imaging?". This is ideal for learning the API,
working out how to perform a calculation, and interpreting or debugging errors.

3. **Fully Agentic AI**: Use an agentic coding tool such as Claude Code (https://claude.com/claude-code) or Codex
(https://developers.openai.com/codex) together with autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant).
These can inspect your data, write and run scripts, and manage an end-to-end lens modeling project directly on your
machine. See the autolens_assistant repository for more information.

The rest of this guide supports **manual navigation**: we begin by answering two simple questions to find your most
appropriate starting point.

__What Scale Lens?__

Expand Down
Loading