docs(analysis): add module-level docstrings to analysis package

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

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

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
 

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

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