From dae19557cfe033a514bfdc03804e433b177019ec Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Thu, 9 Jul 2026 16:31:52 +0100 Subject: [PATCH] docs: present cluster lensing as mature + three-ways-to-learn guide Phase B: remove the 'IN DEVELOPMENT' / 'Beta Feature' framing from the cluster examples (README + start_here) now that cluster modeling is a supported feature; keep the genuine capability notes. Weak lensing already carried no dev flags. Phase C: add a 'Three Ways to Learn PyAutoLens' subsection (manual navigation / AI chat assistant / fully agentic AI) to start_here.py and the README. Notebooks regenerated for the two edited scripts. Issue PyAutoLabs/PyAutoLens#592. Co-Authored-By: Claude Opus 4.8 --- README.md | 10 ++++ notebooks/cluster/README.md | 6 --- notebooks/cluster/start_here.ipynb | 81 ++++++++++++++++-------------- scripts/cluster/README.md | 6 --- scripts/cluster/start_here.py | 21 ++++---- start_here.ipynb | 24 ++++++++- start_here.py | 24 ++++++++- 7 files changed, 107 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 80bbc5ddb..dabc90dc1 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/notebooks/cluster/README.md b/notebooks/cluster/README.md index cefc9b41f..9826c7919 100644 --- a/notebooks/cluster/README.md +++ b/notebooks/cluster/README.md @@ -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. diff --git a/notebooks/cluster/start_here.ipynb b/notebooks/cluster/start_here.ipynb index c6303abca..7ad397023 100644 --- a/notebooks/cluster/start_here.ipynb +++ b/notebooks/cluster/start_here.ipynb @@ -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", @@ -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", @@ -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", @@ -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." ] }, { @@ -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", @@ -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", @@ -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", @@ -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." ] }, { @@ -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", @@ -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." ] diff --git a/scripts/cluster/README.md b/scripts/cluster/README.md index cefc9b41f..9826c7919 100644 --- a/scripts/cluster/README.md +++ b/scripts/cluster/README.md @@ -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. diff --git a/scripts/cluster/start_here.py b/scripts/cluster/start_here.py index d2f1a0df1..a058ee46c 100644 --- a/scripts/cluster/start_here.py +++ b/scripts/cluster/start_here.py @@ -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. @@ -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__ diff --git a/start_here.ipynb b/start_here.ipynb index e3c28c694..7caa1e3e5 100644 --- a/start_here.ipynb +++ b/start_here.ipynb @@ -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", diff --git a/start_here.py b/start_here.py index 82bc01929..2d3aa76db 100644 --- a/start_here.py +++ b/start_here.py @@ -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?__