Merge pull request #394 from Jammy2211/docs/imaging

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

Author: Jammy2211

autolens/imaging/fit_imaging.py

@@ -1,3 +1,23 @@
+"""
+Imaging fit class for strong gravitational lens modeling.
+
+``FitImaging`` extends the ``autogalaxy`` ``FitImaging`` base class to work with a
+``Tracer`` instead of a plain ``Galaxies`` collection.  The fit pipeline is the same
+six-step process as the base class, with the critical addition that light profiles from
+source galaxies are evaluated *after* ray-tracing their image-plane grid through the
+lens mass distribution:
+
+1. Evaluate all light profiles of the tracer galaxies on the (ray-traced) grid.
+2. Blur the summed image with the imaging PSF.
+3. Subtract the blurred image from the data to form the profile-subtracted image.
+4. If the tracer contains linear light profiles or pixelizations, solve for their
+   amplitudes / reconstructed source via an inversion of the profile-subtracted image.
+5. Combine blurred image and inversion reconstruction into the ``model_data``.
+6. Compute residuals, chi-squared, and log likelihood (or log evidence when an inversion
+   is present).
+
+The ``TracerToInversion`` helper is used to assemble the linear system in step 4.
+"""
 import copy
 import numpy as np
 from typing import Dict, List, Optional

autolens/imaging/model/analysis.py

@@ -1,3 +1,17 @@
+"""
+Analysis class for fitting a ``Tracer`` lens model to an imaging dataset.
+
+``AnalysisImaging`` implements the ``log_likelihood_function`` that a ``PyAutoFit``
+non-linear search calls on each iteration.  It:
+
+1. Constructs a ``Tracer`` from the current model instance.
+2. Optionally applies adaptive galaxy images to linear components.
+3. Calls ``FitImaging`` to evaluate the log likelihood.
+4. Returns the figure of merit (log likelihood or log evidence).
+
+It also manages result output (``ResultImaging``), on-the-fly visualisation
+(``VisualizerImaging``), and position-based priors via ``PositionLikelihood``.
+"""
 import logging
 
 import autofit as af

autolens/imaging/simulator.py

@@ -1,3 +1,17 @@
+"""
+Imaging simulator for strong gravitational lens observations.
+
+``SimulatorImaging`` extends ``aa.SimulatorImaging`` with a ``via_tracer_from`` method
+that accepts a ``Tracer`` object and:
+
+1. Uses the tracer's mass profiles to ray-trace the image-plane grid to the source plane.
+2. Evaluates the light profiles of all galaxies on the (traced) grid.
+3. Passes the result through the standard ``SimulatorImaging`` pipeline: PSF convolution,
+   background sky addition, and Poisson noise realisation.
+
+This is the primary entry point for generating synthetic lens datasets for testing,
+validation, and mock-data studies.
+"""
 import numpy as np
 from typing import List