From cbb7ffbef0b44a46f35e0cb7da0de0a088fa1c36 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Tue, 10 Mar 2026 19:39:13 +0000 Subject: [PATCH] docs(lens): add module-level docstrings to lens package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add module-level docstrings to all five substantive modules in autolens/lens/: - tracer.py: core Tracer class — multi-plane ray tracing, lensed images, convergence/shear/magnification maps, critical curves, lens modeling role - tracer_util.py: plane redshift derivation and position propagation utilities - to_inversion.py: TracerToInversion — bridges Tracer to autoarray's linear algebra inversion for linear light profiles and pixelizations - sensitivity.py: SubhaloSensitivityResult — sensitivity mapping workflow for dark-matter subhalo detectability - subhalo.py: SubhaloGridSearchResult — grid-search detection pipeline for dark-matter subhalos Co-Authored-By: Claude Sonnet 4.6 --- autolens/lens/sensitivity.py | 16 ++++++++++++++++ autolens/lens/subhalo.py | 15 +++++++++++++++ autolens/lens/to_inversion.py | 18 ++++++++++++++++++ autolens/lens/tracer.py | 20 ++++++++++++++++++++ autolens/lens/tracer_util.py | 17 +++++++++++++++-- 5 files changed, 84 insertions(+), 2 deletions(-) diff --git a/autolens/lens/sensitivity.py b/autolens/lens/sensitivity.py index fd44f450e..0c2169c8c 100644 --- a/autolens/lens/sensitivity.py +++ b/autolens/lens/sensitivity.py @@ -1,3 +1,19 @@ +""" +Sensitivity mapping for dark-matter subhalo detection. + +Sensitivity mapping asks: *given a lens model, how detectable would a dark-matter subhalo +of mass M at position (y, x) be?* It works by: + +1. Fixing the smooth lens model to the best-fit result. +2. Simulating many lens datasets, each with a subhalo at a different position and mass, + using the smooth model plus a perturbation. +3. Fitting each simulated dataset with the smooth model (no subhalo) to measure the change + in log-evidence caused by the subhalo. + +``SubhaloSensitivityResult`` wraps the generic ``PyAutoFit`` ``SensitivityResult`` with +convenience properties for the subhalo grid positions (``y``, ``x``), the detection +significance map, and Matplotlib visualisation helpers. +""" import numpy as np from typing import Optional, List, Tuple diff --git a/autolens/lens/subhalo.py b/autolens/lens/subhalo.py index 6a7527b29..c916d8400 100644 --- a/autolens/lens/subhalo.py +++ b/autolens/lens/subhalo.py @@ -1,3 +1,18 @@ +""" +Dark-matter subhalo detection via grid searches of non-linear searches. + +This module provides result containers and visualisation helpers for a subhalo detection +workflow in which a grid of ``PyAutoFit`` non-linear searches is run. Each cell of the +grid confines the subhalo's (y, x) centre to a small sub-region of the image plane using +uniform priors and fits the lens model with a subhalo included. + +``SubhaloGridSearchResult`` wraps ``af.GridSearchResult`` with: + +- ``y`` / ``x`` — the physical centre coordinates of each grid cell. +- ``log_evidence_differences`` — the Bayesian evidence improvement from adding a subhalo + relative to a smooth-model fit, useful for building a detection significance map. +- Plotting helpers that overlay the detection map on the lens image. +""" import numpy as np from typing import List, Optional, Tuple diff --git a/autolens/lens/to_inversion.py b/autolens/lens/to_inversion.py index 8df5fe1c4..5e060901e 100644 --- a/autolens/lens/to_inversion.py +++ b/autolens/lens/to_inversion.py @@ -1,3 +1,21 @@ +""" +Interface between a ``Tracer`` and the linear-algebra inversion module. + +``TracerToInversion`` extends the ``autogalaxy`` ``GalaxiesToInversion`` pattern to the +multi-plane lensing setting. It is responsible for: + +- Extracting every ``LightProfileLinear`` and ``Pixelization`` from the tracer's galaxies. +- Ray-tracing each linear profile's grid to the correct source plane using the tracer's + multi-plane deflection calculations. +- Assembling the ``mapping_matrix`` that maps source-plane parameters (intensities, mesh + coefficients) to image-plane pixels. +- Passing the assembled objects to ``autoarray``'s ``inversion_from`` factory so that the + linear system ``F x = d`` can be solved for the best-fit intensities / reconstructed + image. + +This class is not used directly by the user; it is instantiated inside +``FitImaging`` / ``FitInterferometer`` whenever the tracer contains linear components. +""" from typing import Dict, List, Optional, Tuple, Type, Union import numpy as np diff --git a/autolens/lens/tracer.py b/autolens/lens/tracer.py index 2535ab5b9..0189c8cf7 100644 --- a/autolens/lens/tracer.py +++ b/autolens/lens/tracer.py @@ -1,3 +1,23 @@ +""" +The core gravitational-lensing ray-tracing module for **PyAutoLens**. + +The central class is ``Tracer``, which groups a list of ``Galaxy`` objects by redshift +into a series of *planes* and performs multi-plane gravitational lensing calculations. +Key capabilities: + +- **Multi-plane ray tracing** — images are traced from the source plane through + intermediate lens planes to the observer using the cosmology-dependent angular + diameter distances between each pair of planes. +- **Lensed images** — the light of each galaxy is ray-traced to its correct position + and the contributions from all planes are summed. +- **Lensing maps** — convergence, shear, magnification, deflection angles, and potential + maps can all be computed on arbitrary ``Grid2D`` grids. +- **Critical curves & caustics** — the image-plane loci where magnification diverges and + their source-plane counterparts. +- **Lens modeling** — the ``Tracer`` is the core object used by + ``FitImaging`` / ``FitInterferometer`` / ``FitPointDataset`` when performing a + Bayesian model fit via a ``PyAutoFit`` non-linear search. +""" from abc import ABC import numpy as np from scipy.interpolate import griddata diff --git a/autolens/lens/tracer_util.py b/autolens/lens/tracer_util.py index b2fe6556f..aabb2fbc7 100644 --- a/autolens/lens/tracer_util.py +++ b/autolens/lens/tracer_util.py @@ -1,3 +1,16 @@ +""" +Utility functions supporting the ``Tracer`` ray-tracing calculations. + +This module contains lower-level helpers that are called by ``Tracer`` but kept separate +to avoid cluttering the main class. Key functions: + +- ``plane_redshifts_from`` — derives the list of unique plane redshifts from a list of + galaxies, collapsing multiple galaxies at the same redshift into a single plane. +- ``ordered_plane_redshifts_with_slicing_from`` — extends the above with optional + redshift slicing for multi-plane calculations that include intermediate planes. +- ``positions_in_ordered_planes_from`` — distributes a set of image-plane positions + across the ordered plane list so that multi-plane tracing can propagate them. +""" import numpy as np from typing import List, Optional @@ -145,7 +158,7 @@ def traced_grid_2d_list_from( for plane_index, galaxies in enumerate(planes): - scaled_grid = grid.array + scaled_grid = xp.asarray(grid.array) if plane_index > 0: @@ -164,7 +177,7 @@ def traced_grid_2d_list_from( scaled_grid = scaled_grid - scaled_deflections scaled_grid = aa.Grid2DIrregular( - values=scaled_grid, + values=scaled_grid, xp=xp ) traced_grid_list.append(scaled_grid)