From f4420e01821b2b33378c25d43fc221dfe481d104 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Tue, 10 Mar 2026 20:00:25 +0000 Subject: [PATCH] docs(analysis): add module-level docstrings to analysis package Add module-level docstrings to five modules in autolens/analysis/: - analysis/dataset.py: AnalysisDataset abstract base (shared imaging + interferometer base, positions likelihood, adapt images) - analysis/lens.py: AnalysisLens mixin (tracer construction, position penalty, use_jax flag) - positions.py: PositionsLH source-plane position penalty prior - result.py: Result / ResultDataset classes (best-fit tracer, source centre, image-plane multiple images) - model_util.py: convenience model construction utilities for workspace scripts Co-Authored-By: Claude Sonnet 4.6 --- autolens/analysis/analysis/dataset.py | 14 ++++++++++++++ autolens/analysis/analysis/lens.py | 16 ++++++++++++++++ autolens/analysis/model_util.py | 18 ++++++++++++++++++ autolens/analysis/positions.py | 18 ++++++++++++++++++ autolens/analysis/result.py | 17 +++++++++++++++++ 5 files changed, 83 insertions(+) diff --git a/autolens/analysis/analysis/dataset.py b/autolens/analysis/analysis/dataset.py index 92e92a85d..76224bb55 100644 --- a/autolens/analysis/analysis/dataset.py +++ b/autolens/analysis/analysis/dataset.py @@ -1,3 +1,17 @@ +""" +Abstract analysis class for fitting a ``Tracer`` to imaging or interferometer datasets. + +``AnalysisDataset`` is the common base class shared by ``AnalysisImaging`` and +``AnalysisInterferometer``. It combines the dataset-level machinery from the +``autogalaxy`` base class (``AgAnalysisDataset``) with the lensing-specific logic from +``AnalysisLens``: + +- Constructing a ``Tracer`` from a ``PyAutoFit`` model instance. +- Applying optional ``PositionsLH`` priors that penalise mass models where image positions + do not trace self-consistently to the source plane. +- Managing adaptive galaxy images (``AdaptImages``) for linear component fitting. +- Serialising results and running on-the-fly visualisation during the search. +""" import logging import numpy as np import os diff --git a/autolens/analysis/analysis/lens.py b/autolens/analysis/analysis/lens.py index 421a4578d..836dfb027 100644 --- a/autolens/analysis/analysis/lens.py +++ b/autolens/analysis/analysis/lens.py @@ -1,3 +1,19 @@ +""" +Lensing-specific mixin for all **PyAutoLens** ``Analysis`` classes. + +``AnalysisLens`` is a mixin that adds lensing-specific behaviour to any analysis class. +It is inherited (alongside dataset-specific base classes) by ``AnalysisDataset``, +``AnalysisPoint``, and ``AnalysisQuantity``. + +Key responsibilities: + +- ``tracer_via_instance_from`` — constructs a ``Tracer`` from a ``PyAutoFit`` model + instance, including automatic multi-plane ordering of galaxies by redshift. +- Position likelihood application — evaluates ``PositionsLH`` objects against the + current tracer and adds any penalty to the log likelihood. +- ``use_jax`` flag — forwarded to ``FitImaging`` / ``FitInterferometer`` to enable JAX + acceleration of the likelihood evaluation. +""" import logging import numpy as np from typing import List, Optional diff --git a/autolens/analysis/model_util.py b/autolens/analysis/model_util.py index 6f74189c4..b68e1a006 100644 --- a/autolens/analysis/model_util.py +++ b/autolens/analysis/model_util.py @@ -1,3 +1,21 @@ +""" +Model construction utilities for **PyAutoLens** example scripts and pipelines. + +This module provides convenience functions that build pre-configured ``af.Model`` +objects for common lens modeling scenarios. They are primarily intended for use in +the autolens_workspace ``start_here.py`` scripts and SLaM pipeline templates, where +a sensible default model is needed without the user having to specify every prior +explicitly. + +Key functions re-exported from ``autogalaxy``: +- ``mge_model_from`` — build an MGE (Multi-Gaussian Expansion) light profile model. +- ``mge_point_model_from`` — MGE model for point-source fitting. +- ``hilbert_pixels_from_pixel_scale`` — estimate Hilbert image-mesh pixel count. + +PyAutoLens-specific: +- ``simulator_start_here_model_from`` — builds a default imaging simulator model with + optional lens light and point-source components for start_here scripts. +""" import autofit as af import autolens as al diff --git a/autolens/analysis/positions.py b/autolens/analysis/positions.py index 41fd40968..2342a3803 100644 --- a/autolens/analysis/positions.py +++ b/autolens/analysis/positions.py @@ -1,3 +1,21 @@ +""" +Position-based likelihood penalties for strong lens model fitting. + +``PositionsLH`` objects add a penalty term to the log likelihood whenever the observed +image-plane positions of a lensed point source do not self-consistently trace back to the +same source-plane location in the current model. + +The check is performed by tracing each observed position through the tracer's deflection +map and computing the maximum pairwise separation in the source plane +(``SourceMaxSeparation``). If this separation exceeds the user-specified ``threshold``, +a large negative penalty is added to the log likelihood: + + penalty = -log_likelihood_penalty_factor × (max_separation − threshold) + +This forces the non-linear search to explore models where the image positions are +self-consistent, greatly improving convergence speed for systems with strong position +constraints (e.g. quad-lens quasars). +""" import numpy as np from typing import Optional from os import path diff --git a/autolens/analysis/result.py b/autolens/analysis/result.py index 97cf91909..957765b9e 100644 --- a/autolens/analysis/result.py +++ b/autolens/analysis/result.py @@ -1,3 +1,20 @@ +""" +Result classes for **PyAutoLens** model fits. + +This module defines the ``Result`` and ``ResultDataset`` classes that wrap the output of +a ``PyAutoFit`` non-linear search for lensing model fits. Key properties include: + +- ``max_log_likelihood_tracer`` — reconstructs the best-fit ``Tracer`` from the stored + model instance. +- ``source_plane_light_profile_centre_from`` — extracts the source-plane light-profile + centre, used by automatic position updating to seed position priors for the next + search in a SLaM pipeline. +- ``image_plane_multiple_image_positions_from`` — uses a ``PointSolver`` to compute the + image-plane multiple-image positions predicted by the best-fit tracer, optionally + filtered by a minimum flux threshold. + +These results feed directly into downstream pipeline stages and post-processing scripts. +""" import logging import os import numpy as np