Skip to content

Commit a981559

Browse files
Jammy2211claude
authored andcommitted
docs: add module docstrings and fill missing method docstrings in operate package
- Add module-level docstring to image.py explaining the OperateImage / OperateImageList / OperateImageGalaxies mixin hierarchy - Add module-level docstring to lens_calc.py listing all the lensing quantities that LensCalc can derive from a deflection callable - Add docstrings to OperateImage.image_2d_from and OperateImage.has (previously only raised NotImplementedError without documentation) - Add docstring to _blurred_image_2d_from explaining its role as the internal PSF convolution helper Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent d99d74b commit a981559

2 files changed

Lines changed: 71 additions & 0 deletions

File tree

autogalaxy/operate/image.py

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
1+
"""
2+
Mixin classes that add image-operation methods (PSF convolution, Fourier transform) to light objects.
3+
4+
The three mixin classes here are arranged in a hierarchy:
5+
6+
- `OperateImage` — methods that operate on a **single** image from a light object
7+
(e.g. a `LightProfile` or `Galaxy`).
8+
- `OperateImageList` — extends `OperateImage` with methods that operate on a **list** of images,
9+
one per light profile component.
10+
- `OperateImageGalaxies` — extends `OperateImageList` with methods that operate on a **dict** mapping
11+
each `Galaxy` to its image, preserving galaxy identity through the pipeline.
12+
13+
All three classes are mixins — they are not instantiated directly but are inherited by light objects
14+
(`LightProfile`, `Galaxy`, `Galaxies`, `Tracer`) to expose a consistent API for blurring and Fourier
15+
transforming images.
16+
"""
117
from __future__ import annotations
218
import numpy as np
319
from typing import TYPE_CHECKING, Dict, List, Optional
@@ -24,9 +40,31 @@ class OperateImage:
2440
def image_2d_from(
2541
self, grid: aa.Grid2D, xp=np, operated_only: Optional[bool] = None
2642
) -> aa.Array2D:
43+
"""
44+
Abstract method — return the 2D image of this light object at every coordinate on `grid`.
45+
46+
Subclasses (e.g. `LightProfile`, `Galaxy`) implement this method to evaluate their surface
47+
brightness at each (y, x) coordinate.
48+
49+
Parameters
50+
----------
51+
grid
52+
The 2D (y, x) coordinates where the image is evaluated.
53+
operated_only
54+
Controls which light profiles contribute. `None` (default) returns all profiles;
55+
`True` returns only `LightProfileOperated` images; `False` excludes them.
56+
"""
2757
raise NotImplementedError
2858

2959
def has(self, cls) -> bool:
60+
"""
61+
Returns `True` if any attribute of this object is an instance of `cls`, else `False`.
62+
63+
Parameters
64+
----------
65+
cls
66+
The class type to search for.
67+
"""
3068
raise NotImplementedError
3169

3270
def _blurred_image_2d_from(
@@ -36,6 +74,21 @@ def _blurred_image_2d_from(
3674
psf: aa.Convolver,
3775
xp=np,
3876
) -> aa.Array2D:
77+
"""
78+
Convolve a 2D image with a PSF using the supplied `Convolver`.
79+
80+
This is the internal helper used by `blurred_image_2d_from`. It does not handle the
81+
`LightProfileOperated` logic — the caller must do that separately.
82+
83+
Parameters
84+
----------
85+
image_2d
86+
The 2D image of the masked pixels to be convolved.
87+
blurring_image_2d
88+
The 2D image of the pixels just outside the mask whose light blurs into the masked region.
89+
psf
90+
The PSF convolver that performs the 2D convolution.
91+
"""
3992

4093
values = psf.convolved_image_from(
4194
image=image_2d, blurring_image=blurring_image_2d, xp=xp

autogalaxy/operate/lens_calc.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
"""
2+
`LensCalc` — a calculator that derives all secondary lensing quantities from a deflection callable.
3+
4+
Given any object that exposes `deflections_yx_2d_from` (a `MassProfile`, `Galaxy`, `Galaxies`, or
5+
`Tracer`), `LensCalc` computes:
6+
7+
- **Hessian** (four components: H_yy, H_xy, H_yx, H_xx) — the matrix of second derivatives of the
8+
lensing potential, computed by finite differences (NumPy) or automatic differentiation (JAX).
9+
- **Convergence via Hessian** — κ = 0.5 (H_yy + H_xx), independent of the analytic profile formula.
10+
- **Shear** — γ₁ = 0.5 (H_xx − H_yy), γ₂ = H_xy.
11+
- **Magnification** — μ = 1 / det(I − H).
12+
- **Critical curves** — image-plane loci where det(I − H) = 0, found via marching squares.
13+
- **Caustics** — source-plane images of the critical curves.
14+
- **Einstein radius** — the effective radius from the area enclosed by the tangential critical curve.
15+
- **Fermat potential** — φ(θ) = ½|θ − β|² − ψ(θ), using the optional potential callable.
16+
17+
The class is constructed with `LensCalc.from_mass_obj(mass)` or `LensCalc.from_tracer(tracer)`.
18+
"""
119
from functools import wraps
220
import logging
321
import numpy as np

0 commit comments

Comments
 (0)