autogalaxy.LensCalc

class LensCalc

Bases: object

Computes lensing quantities from a deflection-angle callable and an optional potential callable.

The deflection callable is used to compute the Hessian, Jacobian, convergence, shear, magnification, critical curves, caustics, and Einstein radius/mass. If a potential callable is also supplied, fermat_potential_from is available as well.

Parameters:

• deflections_yx_2d_from – A callable with signature (grid, xp=np, **kwargs) that returns the 2D deflection angles on the given grid. Typically a bound method of a MassProfile, Galaxy, or Galaxies instance.

• potential_2d_from – Optional callable with signature (grid, xp=np, **kwargs) that returns the 2D lensing potential on the given grid. Required only for fermat_potential_from.

Methods

area_within_curve_list_from
contour_list_from
convergence_2d_via_hessian_from	Returns the convergence of the lensing object, which is computed from the 2D deflection angle map via the Hessian using the expression (see equation 56 https://inspirehep.net/literature/419263):
deflections_yx_scalar	Returns the deflection angles at a single (y, x) arc-second coordinate as a JAX array of shape (2,), where index 0 is the y-deflection and index 1 is the x-deflection.
einstein_mass_angular_from	Returns the Einstein radius corresponding to the area within the tangential critical curve.
einstein_mass_angular_list_from	Returns a list of the angular Einstein massses corresponding to the area within each tangential critical curve.
einstein_radius_from	Returns the Einstein radius corresponding to the area within the tangential critical curve.
einstein_radius_jit_from	JIT-friendly Einstein radius from the tangential critical curve.
einstein_radius_list_from	Returns a list of the Einstein radii corresponding to the area within each tangential critical curve.
einstein_radius_list_via_zero_contour_from	Returns a list of Einstein radii from the tangential critical curves traced via tangential_critical_curve_list_via_zero_contour_from.
einstein_radius_via_zero_contour_from	Returns the Einstein radius from the tangential critical curve traced via jax_zero_contour.
fermat_potential_from	Returns the Fermat potential for a given grid of image-plane positions.
from_mass_obj	Construct from any object that has a deflections_yx_2d_from method.
from_tracer	Construct from a PyAutoLens Tracer object.
hessian_from	Returns the Hessian of the lensing object, where the Hessian is the second partial derivatives of the potential (see equation 55 https://inspirehep.net/literature/419263):
jacobian_from	Returns the lensing Jacobian of the lensing object as a 2x2 list of lists.
magnification_2d_from	Returns the 2D magnification map of lensing object, which is computed as the inverse of the determinant of the lensing Jacobian, expressed via the Hessian components.
magnification_2d_via_hessian_from	Returns the 2D magnification map of lensing object, which is computed from the 2D deflection angle map via the Hessian using the expressions (see equation 60 https://inspirehep.net/literature/419263):
radial_caustic_list_from	Returns all radial caustics of the lensing system, which are computed as follows:
radial_caustic_list_via_zero_contour_from	Returns radial caustics by ray-tracing the radial critical curves computed via radial_critical_curve_list_via_zero_contour_from.
radial_critical_curve_area_list_from	Returns the surface area within each radial critical curve as a list, the calculation of which is described in the function radial_critical_curve_list_from().
radial_critical_curve_list_from	Returns all radial critical curves of the lensing system, which are computed as follows:
radial_critical_curve_list_via_zero_contour_from	Returns radial critical curves using the jax_zero_contour package.
radial_eigen_value_from	Returns the radial eigen values of lensing jacobian, which are given by the expression:
shear_yx_2d_via_hessian_from	Returns the 2D weak-lensing shear vector field of the lensing object, computed from the deflection-angle Hessian (see equation 57 of https://inspirehep.net/literature/419263):
tangential_caustic_list_from	Returns all tangential caustics of the lensing system, which are computed as follows:
tangential_caustic_list_via_zero_contour_from	Returns tangential caustics by ray-tracing the tangential critical curves computed via tangential_critical_curve_list_via_zero_contour_from.
tangential_critical_curve_area_list_from	Returns the surface area within each tangential critical curve as a list, the calculation of which is described in the function tangential_critical_curve_list_from().
tangential_critical_curve_list_from	Returns all tangential critical curves of the lensing system, which are computed as follows:
tangential_critical_curve_list_via_zero_contour_from	Returns tangential critical curves using the jax_zero_contour package.
tangential_eigen_value_from	Returns the tangential eigen values of lensing jacobian, which are given by the expression:
time_delay_geometry_term_from	Returns the geometric time delay term of the Fermat potential for a given grid of image-plane positions.

classmethod from_mass_obj(mass_obj)

Construct from any object that has a deflections_yx_2d_from method.

If the object also exposes potential_2d_from, it is captured so that fermat_potential_from is available on the returned instance.

classmethod from_tracer(tracer, use_multi_plane=True, plane_i=0, plane_j=-1)

Construct from a PyAutoLens Tracer object.

The Tracer type is deliberately left unannotated: autogalaxy does not depend on autolens, so no import of Tracer is performed here. Callers (which live inside autolens) are responsible for passing the correct object.

Parameters:

• tracer – A PyAutoLens Tracer instance. Must expose deflections_yx_2d_from and, when use_multi_plane=True, deflections_between_planes_from.

• use_multi_plane (bool) – If True the stored callable is tracer.deflections_between_planes_from with plane_i and plane_j bound via functools.partial, matching the multi-plane ray-tracing path. If False the stored callable is tracer.deflections_yx_2d_from, i.e. the standard two-plane path.

• plane_i (int) – Index of the first plane used by deflections_between_planes_from. Ignored when use_multi_plane=False. Defaults to 0 (image plane).

• plane_j (int) – Index of the second plane used by deflections_between_planes_from. Ignored when use_multi_plane=False. Defaults to -1 (source plane).

time_delay_geometry_term_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the geometric time delay term of the Fermat potential for a given grid of image-plane positions.

This term is given by:

\[\[ au_{ ext{geom}}(oldsymbol{ heta}) =\]

rac{1}{2} |oldsymbol{ heta} - oldsymbol{eta}|^2]

where: - ( oldsymbol{ heta} ) is the image-plane coordinate, - ( oldsymbol{eta} = oldsymbol{ heta} - oldsymbol{lpha}(oldsymbol{ heta}) ) is the source-plane coordinate, - ( oldsymbol{lpha} ) is the deflection angle at each image-plane coordinate.

Parameters:

grid

The 2D grid of (y,x) arc-second coordinates the deflection angles and time delay geometric term are computed on.

Returns:

The geometric time delay term at each grid position.

fermat_potential_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the Fermat potential for a given grid of image-plane positions.

This is the sum of the geometric time delay term and the gravitational (Shapiro) delay term (i.e. the lensing potential), and is given by:

\[\phi(\boldsymbol{\theta}) = \frac{1}{2} |\boldsymbol{\theta} - \boldsymbol{\beta}|^2 - \psi(\boldsymbol{\theta})\]

Requires that potential_2d_from was supplied at construction (e.g. via LensCalc.from_mass_obj or LensCalc.from_tracer).

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the Fermat potential is computed on.

• xp – The array module (numpy or jax.numpy).

tangential_eigen_value_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the tangential eigen values of lensing jacobian, which are given by the expression:

tangential_eigen_value = 1 - convergence - shear

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and tangential eigen values are computed on.

• xp – The array module (numpy or jax.numpy). Passed through to convergence_2d_via_hessian_from and shear_yx_2d_via_hessian_from. When xp is not numpy the result is a raw array rather than an aa.Array2D wrapper.

radial_eigen_value_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the radial eigen values of lensing jacobian, which are given by the expression:

radial_eigen_value = 1 - convergence + shear

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and radial eigen values are computed on.

• xp – The array module (numpy or jax.numpy). Passed through to convergence_2d_via_hessian_from and shear_yx_2d_via_hessian_from. When xp is not numpy the result is a raw array rather than an aa.Array2D wrapper.

magnification_2d_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the 2D magnification map of lensing object, which is computed as the inverse of the determinant of the lensing Jacobian, expressed via the Hessian components.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and magnification map are computed on.

• xp – The array module (numpy or jax.numpy). Passed through to hessian_from. When xp is not numpy the result is a raw array rather than an aa.Array2D wrapper.

deflections_yx_scalar(y, x, pixel_scales)

Returns the deflection angles at a single (y, x) arc-second coordinate as a JAX array of shape (2,), where index 0 is the y-deflection and index 1 is the x-deflection.

This is an internal method used by hessian_from to enable JAX auto-differentiation via jax.jacfwd. The function must accept y and x as two separate scalar inputs (rather than a single combined array) so that JAX treats the function as R² -> R² and computes a proper 2x2 Jacobian matrix.

Parameters:

• y – The y arc-second coordinate (scalar).

• x – The x arc-second coordinate (scalar).

• pixel_scales – The pixel scales used to construct the internal (1, 1) Mask2D.

hessian_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the Hessian of the lensing object, where the Hessian is the second partial derivatives of the potential (see equation 55 https://inspirehep.net/literature/419263):

hessian_{i,j} = d^2 / dtheta_i dtheta_j

The Hessian is returned as a 4-entry tuple reflecting its structure as a 2x2 matrix: (hessian_yy, hessian_xy, hessian_yx, hessian_xx).

Two computational paths are available, selected via the xp parameter:

• NumPy (xp=np, default): 2-point central finite-difference approximation, Richardson-extrapolated at step sizes h and h/2 and combined as (4 * H(h/2) - H(h)) / 3. This cancels the leading O(h^2) truncation term, giving O(h^4) accuracy and matching the JAX path to float64 precision. JAX is not imported.

• JAX (xp=jnp): exact derivatives via jax.jacfwd applied to deflections_yx_scalar, vectorised over the grid with jnp.vectorize.

Both paths support uniform Grid2D and irregular Grid2DIrregular grids.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the Hessian is computed on.

• xp – The array module (numpy or jax.numpy). Controls which computational path is used and the type of the returned arrays.

jacobian_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the lensing Jacobian of the lensing object as a 2x2 list of lists.

The Jacobian is the matrix A = I - H, where H is the Hessian matrix of the deflection angles:

A = [[1 - hessian_xx, -hessian_xy], [-hessian_yx, 1 - hessian_yy]]

It is computed from hessian_from, so it supports both uniform and irregular grids and accepts the same xp parameter for JAX acceleration.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the Jacobian is computed on.

• xp – The array module (numpy or jax.numpy). Passed through to hessian_from.

convergence_2d_via_hessian_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the convergence of the lensing object, which is computed from the 2D deflection angle map via the Hessian using the expression (see equation 56 https://inspirehep.net/literature/419263):

convergence = 0.5 * (hessian_{0,0} + hessian_{1,1}) = 0.5 * (hessian_xx + hessian_yy)

By going via the Hessian, the convergence can be calculated at any (y,x) coordinate therefore using either a 2D uniform or irregular grid.

This calculation of the convergence is independent of analytic calculations defined within MassProfile objects and can therefore be used as a cross-check.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and Hessian are computed on.

• xp – The array module to use for the computation (e.g. numpy or jax.numpy). Passed through to hessian_from. When xp is not numpy (e.g. inside a jax.jit trace) the result is returned as a raw array rather than an aa.ArrayIrregular wrapper.

shear_yx_2d_via_hessian_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the 2D weak-lensing shear vector field of the lensing object, computed from the deflection-angle Hessian (see equation 57 of https://inspirehep.net/literature/419263):

\[ \begin{align}\begin{aligned}\gamma_1 = \tfrac{1}{2} (\partial^2 \psi / \partial x^2 - \partial^2 \psi / \partial y^2) = 0.5 \, (H_{xx} - H_{yy})\\\gamma_2 = \partial^2 \psi / \partial x \partial y = H_{xy} = H_{yx}\end{aligned}\end{align} \]

where \(\psi(\theta)\) is the lensing potential and \(H_{ij}\) are its second partial derivatives, i.e. the components of the Hessian returned by hessian_from. The two components together encode the full distortion tensor of a background source: \(\gamma_1\) is the stretch along the x/y axes and \(\gamma_2\) is the stretch along the diagonals.

Because the Hessian is computed numerically (Richardson-extrapolated finite differences in NumPy, or jax.jacfwd in JAX), this routine works for any MassProfile, Galaxy, Galaxies or Tracer that exposes deflections_yx_2d_from — no per-profile analytic formula is required. It can therefore be used as a numerical cross-check of analytic shear methods such as Isothermal.shear_yx_2d_from (see test_isothermal.py). It also accepts both uniform Grid2D and irregular Grid2DIrregular grids, which makes it the natural choice for simulating a weak-lensing shear field on either a regular pixel grid or at the discrete positions of background source galaxies.

magnification_2d_via_hessian_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautogalaxy/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Returns the 2D magnification map of lensing object, which is computed from the 2D deflection angle map via the Hessian using the expressions (see equation 60 https://inspirehep.net/literature/419263):

magnification = 1.0 / det(Jacobian) = 1.0 / abs((1.0 - convergence)**2.0 - shear**2.0) magnification = (1.0 - hessian_{0,0}) * (1.0 - hessian_{1, 1)) - hessian_{0,1}*hessian_{1,0} magnification = (1.0 - hessian_xx) * (1.0 - hessian_yy)) - hessian_xy*hessian_yx

By going via the Hessian, the magnification can be calculated at any (y,x) coordinate, therefore using either a 2D uniform or irregular grid.

This calculation of the magnification is independent of calculations using the Jacobian and can therefore be used as a cross-check.

Parameters:

grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and magnification map are computed on.

contour_list_from(grid, contour_array)

tangential_critical_curve_list_from(grid, pixel_scale=0.05)

Returns all tangential critical curves of the lensing system, which are computed as follows:

1. Compute the tangential eigen values for every coordinate on the input grid via the Jacobian.

2. Find contours of all values in the tangential eigen values that are zero using a marching squares algorithm.

Due to the use of a marching squares algorithm that requires the zero values of the tangential eigen values to be computed, critical curves can only be calculated using the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and tangential eigen values are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the critical curve to be computed more accurately using a higher resolution grid.

radial_critical_curve_list_from(grid, pixel_scale=0.05)

Returns all radial critical curves of the lensing system, which are computed as follows:

1. Compute the radial eigen values for every coordinate on the input grid via the Jacobian.

2. Find contours of all values in the radial eigen values that are zero using a marching squares algorithm.

Due to the use of a marching squares algorithm that requires the zero values of the radial eigen values to be computed, this critical curves can only be calculated using the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and radial eigen values are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the critical curve to be computed more accurately using a higher resolution grid.

tangential_caustic_list_from(grid, pixel_scale=0.05)

Returns all tangential caustics of the lensing system, which are computed as follows:

1. Compute the tangential eigen values for every coordinate on the input grid via the Jacobian.

2. Find contours of all values in the tangential eigen values that are zero using a marching squares algorithm.

3. Compute the lensing system’s deflection angles at the (y,x) coordinates of the tangential critical curve contours and ray-trace it to the source-plane, therefore forming the tangential caustics.

Due to the use of a marching squares algorithm that requires the zero values of the tangential eigen values to be computed, caustics can only be calculated using the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and tangential eigen values are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

radial_caustic_list_from(grid, pixel_scale=0.05)

Returns all radial caustics of the lensing system, which are computed as follows:

1. Compute the radial eigen values for every coordinate on the input grid via the Jacobian.

2. Find contours of all values in the radial eigen values that are zero using a marching squares algorithm.

3. Compute the lensing system’s deflection angles at the (y,x) coordinates of the radial critical curve contours and ray-trace it to the source-plane, therefore forming the radial caustics.

Due to the use of a marching squares algorithm that requires the zero values of the radial eigen values to be computed, this caustics can only be calculated using the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles and radial eigen values are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

radial_critical_curve_area_list_from(grid, pixel_scale)

Returns the surface area within each radial critical curve as a list, the calculation of which is described in the function radial_critical_curve_list_from().

The area is computed via a line integral.

Due to the use of a marching squares algorithm to estimate the critical curve, this function can only use the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles used to calculate the radial critical curve are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

tangential_critical_curve_area_list_from(grid, pixel_scale=0.05)

Returns the surface area within each tangential critical curve as a list, the calculation of which is described in the function tangential_critical_curve_list_from().

The area is computed via a line integral.

Due to the use of a marching squares algorithm to estimate the critical curve, this function can only use the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles used to calculate the tangential critical curve are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

area_within_curve_list_from(curve_list)

einstein_radius_list_from(grid, pixel_scale=0.05)

Returns a list of the Einstein radii corresponding to the area within each tangential critical curve.

Each Einstein radius is defined as the radius of the circle which contains the same area as the area within each tangential critical curve.

This definition is sometimes referred to as the “effective Einstein radius” in the literature and is commonly adopted in studies, for example the SLACS series of papers.

The calculation of the tangential critical curves and their areas is described in the functions

tangential_critical_curve_list_from() and tangential_critical_curve_area_list_from().

Due to the use of a marching squares algorithm to estimate the critical curve, this function can only use the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles used to calculate the tangential critical curve are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

einstein_radius_from(grid, pixel_scale=0.05)

Returns the Einstein radius corresponding to the area within the tangential critical curve.

The Einstein radius is defined as the radius of the circle which contains the same area as the area within the tangential critical curve.

This definition is sometimes referred to as the “effective Einstein radius” in the literature and is commonly adopted in studies, for example the SLACS series of papers.

If there are multiple tangential critical curves (e.g. because the mass distribution is complex) this function raises an error, and the function einstein_radius_list_from() should be used instead.

The calculation of the tangential critical curves and their areas is described in the functions

tangential_critical_curve_list_from() and tangential_critical_curve_area_list_from().

Due to the use of a marching squares algorithm to estimate the critical curve, this function can only use the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles used to calculate the tangential critical curve are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

einstein_mass_angular_list_from(grid, pixel_scale=0.05)

Returns a list of the angular Einstein massses corresponding to the area within each tangential critical curve.

The angular Einstein mass is defined as: einstein_mass = pi * einstein_radius ** 2.0 where the Einstein radius is the radius of the circle which contains the same area as the area within the tangential critical curve.

The Einstein mass is returned in units of arcsecond**2.0 and requires division by the lensing critical surface density sigma_cr to be converted to physical units like solar masses (see autogalaxy.util.cosmology_util).

This definition of Eisntein radius (and therefore mass) is sometimes referred to as the “effective Einstein radius” in the literature and is commonly adopted in studies, for example the SLACS series of papers.

The calculation of the einstein radius is described in the function einstein_radius_from().

Due to the use of a marching squares algorithm to estimate the critical curve, this function can only use the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles used to calculate the tangential critical curve are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

einstein_mass_angular_from(grid, pixel_scale=0.05)

Returns the Einstein radius corresponding to the area within the tangential critical curve.

The angular Einstein mass is defined as: einstein_mass = pi * einstein_radius ** 2.0 where the Einstein radius is the radius of the circle which contains the same area as the area within the tangential critical curve.

The Einstein mass is returned in units of arcsecond**2.0 and requires division by the lensing critical surface density sigma_cr to be converted to physical units like solar masses (see autogalaxy.util.cosmology_util).

This definition of Eisntein radius (and therefore mass) is sometimes referred to as the “effective Einstein radius” in the literature and is commonly adopted in studies, for example the SLACS series of papers.

The calculation of the einstein radius is described in the function einstein_radius_from().

Due to the use of a marching squares algorithm to estimate the critical curve, this function can only use the Jacobian and a uniform 2D grid.

Parameters:

• grid – The 2D grid of (y,x) arc-second coordinates the deflection angles used to calculate the tangential critical curve are computed on.

• pixel_scale (Union[Tuple[float, float], float]) – If input, the evaluation_grid decorator creates the 2D grid at this resolution, therefore enabling the caustic to be computed more accurately using a higher resolution grid.

tangential_critical_curve_list_via_zero_contour_from(init_guess=None, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

Returns tangential critical curves using the jax_zero_contour package.

Unlike tangential_critical_curve_list_from, this method does not evaluate lensing quantities on a dense uniform grid. Instead it traces the zero contour of the tangential eigen value directly, evaluating the function only along the curve itself.

The algorithm (from jax_zero_contour.ZeroSolver):

1. Newton’s method projects each initial guess onto the exact zero contour of the tangential eigen value.

2. Euler-Lagrange (gradient-perpendicular) stepping traces the contour in both directions from each projected seed point.

3. Tracing stops when the path closes, hits an endpoint, or exhausts N steps.

Parameters:

• init_guess – JAX or NumPy array of shape (n, 2) with rough (y, x) positions near the tangential critical curve — one seed per distinct curve. If None a coarse 25 × 25 grid scan is used to find seed points automatically.

• delta (float) – Arc-second step size along the contour. Smaller values give denser, more accurate curves but require a larger N to trace the same total length.

• N (int) – Maximum number of steps in each direction from each seed point. The traced path has at most 2N + 1 points per seed.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar for its internal single-pixel mask.

• tol (float) – Newton’s method convergence tolerance (forwarded to ZeroSolver).

• max_newton (int) – Maximum Newton iterations per step (forwarded to ZeroSolver).

Returns:

One Grid2DIrregular per traced contour segment, matching the return type of tangential_critical_curve_list_from.

Return type:

List[aa.Grid2DIrregular]

radial_critical_curve_list_via_zero_contour_from(init_guess=None, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

Returns radial critical curves using the jax_zero_contour package.

Identical to tangential_critical_curve_list_via_zero_contour_from except the zero contour of the radial eigen value is traced.

Parameters:

• init_guess – JAX or NumPy array of shape (n, 2) with rough (y, x) positions near the radial critical curve. If None a coarse grid scan finds seed points automatically.

• delta (float) – Arc-second step size along the contour.

• N (int) – Maximum number of steps in each direction from each seed.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar.

• tol (float) – Newton’s method convergence tolerance.

• max_newton (int) – Maximum Newton iterations per step.

Return type:

List[aa.Grid2DIrregular]

tangential_caustic_list_via_zero_contour_from(init_guess=None, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

Returns tangential caustics by ray-tracing the tangential critical curves computed via tangential_critical_curve_list_via_zero_contour_from.

Parameters:

• init_guess – Forwarded to tangential_critical_curve_list_via_zero_contour_from.

• delta (float) – Arc-second step size along the contour.

• N (int) – Maximum steps per seed direction.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar.

• tol (float) – Newton’s method convergence tolerance.

• max_newton (int) – Maximum Newton iterations per step.

Return type:

List[aa.Grid2DIrregular]

radial_caustic_list_via_zero_contour_from(init_guess=None, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

Returns radial caustics by ray-tracing the radial critical curves computed via radial_critical_curve_list_via_zero_contour_from.

Parameters:

• init_guess – Forwarded to radial_critical_curve_list_via_zero_contour_from.

• delta (float) – Arc-second step size along the contour.

• N (int) – Maximum steps per seed direction.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar.

• tol (float) – Newton’s method convergence tolerance.

• max_newton (int) – Maximum Newton iterations per step.

Return type:

List[aa.Grid2DIrregular]

einstein_radius_list_via_zero_contour_from(init_guess=None, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

Returns a list of Einstein radii from the tangential critical curves traced via tangential_critical_curve_list_via_zero_contour_from.

Each Einstein radius is the radius of the circle with the same area as the corresponding tangential critical curve.

Parameters:

• init_guess – Forwarded to tangential_critical_curve_list_via_zero_contour_from.

• delta (float) – Arc-second step size along the contour.

• N (int) – Maximum steps per seed direction.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar.

• tol (float) – Newton’s method convergence tolerance.

• max_newton (int) – Maximum Newton iterations per step.

Return type:

List[float]

einstein_radius_via_zero_contour_from(init_guess=None, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

Returns the Einstein radius from the tangential critical curve traced via jax_zero_contour.

If there are multiple tangential critical curves the radii are summed, consistent with einstein_radius_from.

Parameters:

• init_guess – Forwarded to einstein_radius_list_via_zero_contour_from.

• delta (float) – Arc-second step size along the contour.

• N (int) – Maximum steps per seed direction.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar.

• tol (float) – Newton’s method convergence tolerance.

• max_newton (int) – Maximum Newton iterations per step.

Return type:

float

einstein_radius_jit_from(init_guess, delta=0.05, N=500, pixel_scales=(0.05, 0.05), tol=1e-06, max_newton=5)

JIT-friendly Einstein radius from the tangential critical curve.

Designed for use inside jax.jit(...) (e.g. the per-sample latent loop in autofit.Analysis.compute_latent_samples with LATENT_BATCH_MODE='jit'). Unlike einstein_radius_via_zero_contour_from, this method:

• Requires an explicit init_guess — no marching-squares seed search (which would require skimage and break the JAX trace).

• Skips ZeroSolver.path_reduce (variable-length output, not jit-able).

• Computes the enclosed area directly from the raw NaN-padded paths array via a JAX-vectorised shoelace formula.

• Returns a single scalar jax.Array (not a Python float).

Do NOT combine this with jax.vmap — the underlying jax_zero_contour.ZeroSolver.zero_contour_finder uses jax.lax.cond / jax.lax.while_loop for early termination, which upstream explicitly documents as incompatible with jax.vmap. For batched evaluation, wrap the caller in jax.jit and loop over samples in Python (see Analysis.LATENT_BATCH_MODE='jit').

Parameters:

• init_guess – JAX or NumPy array of shape (n_seeds, 2) — seed positions (y, x) near the expected critical curve. For typical galaxy-scale lenses centred on the image, a single seed at [[1.0, 0.0]] works; for clusters or off-centre lenses pass a small fan of seeds (e.g. four at cardinal positions).

• delta (float) – Arc-second step size along the contour. Forwarded to ZeroSolver.

• N (int) – Maximum steps per seed direction. Forwarded to ZeroSolver.

• pixel_scales (Tuple[float, float]) – Pixel scales passed to deflections_yx_scalar (used internally by _make_eigen_fn).

• tol (float) – Newton’s method convergence tolerance.

• max_newton (int) – Maximum Newton iterations per step.

Returns:

Scalar Einstein radius in arc-seconds (sqrt(area / pi) where area is the largest enclosed area across all seeds — robust to multiple seeds landing on the same critical curve).

Return type:

jax.Array