autogalaxy.profiles.mass.ExternalPotential#

class ExternalPotential[source]#

Bases: MassProfile

A line-of-sight external potential that generalises the constant external shear used in strong-lens models by adding the two next-order terms from Powell et al. 2022 (Eq. 4):

\[\psi(\mathbf{r}) = \tfrac{1}{2}\, r^2 \big(\gamma_1 \cos 2\theta + \gamma_2 \sin 2\theta\big) + \tfrac{1}{4}\, r^3 \big(\tau_1 \cos\theta + \tau_2 \sin\theta\big) + \tfrac{1}{6}\, r^3 \big(\delta_1 \cos 3\theta + \delta_2 \sin 3\theta\big)\]

where \((r, \theta)\) are polar coordinates centred on the profile’s centre.

Term-by-term:

\(\gamma_1, \gamma_2\) — the constant external shear contribution. With \(\tau_i = \delta_i = 0\) and centre = (0, 0) this reduces exactly to ExternalShear.
\(\tau_1, \tau_2\) — a linear gradient in the surface mass density (spin-1), giving a non-zero convergence \(\kappa(x, y) = \tau_1 x + \tau_2 y\).
\(\delta_1, \delta_2\) — a higher-order spin-3 generalised-shear term.

Unlike ExternalShear, where the deflection field is a constant in the lens plane and the source position is degenerate with centre, the \(\tau\) and \(\delta\) deflections have explicit radial dependence — so centre is a free parameter (typically tied to the primary lens centre when modelling).

Parameters:

centre (Tuple[float, float]) – The (y, x) arc-second coordinates of the profile centre.
gamma_1 (float) – The two components of the constant external shear (spin-2).
gamma_2 (float) – The two components of the constant external shear (spin-2).
tau_1 (float) – The two components of the linear surface-mass-density gradient (spin-1).
tau_2 (float) – The two components of the linear surface-mass-density gradient (spin-1).
delta_1 (float) – The two components of the higher-order spin-3 generalised shear.
delta_2 (float) – The two components of the higher-order spin-3 generalised shear.

Methods

`angle`	The position angle in degrees of the major-axis of the ellipse defined by profile, defined counter clockwise from the positive x-axis (0.0 > angle > 180.0).
`angle_radians`	The position angle in radians of the major-axis of the ellipse defined by profile, defined counter clockwise from the positive x-axis (0.0 > angle > 2pi).
`angle_to_profile_grid_from`	The angle between each angle theta on the grid and the profile, in radians.
`average_convergence_of_1_radius`	The radius a critical curve forms for this mass profile, e.g. where the mean convergence is equal to 1.0.
`axis_ratio`	The ratio of the minor-axis to major-axis (b/a) of the ellipse defined by profile (0.0 > q > 1.0).
`convergence_2d_from`	Returns the convergence \(\kappa = \tfrac{1}{2}\nabla^2 \psi\) at each grid point.
`convergence_func`	Returns the convergence of the mass profile as a function of the radial coordinate.
`deflections_2d_via_potential_2d_from`	Returns the 2D deflection angles of the mass profile by numerically differentiating the lensing potential on the input grid.
`deflections_yx_2d_from`	Returns the deflection vector \(\boldsymbol{\alpha} = \nabla \psi\) at each grid point.
`delta_angle`
`delta_magnitude`
`density_between_circular_annuli`	Calculate the mass between two circular annuli and compute the density by dividing by the annuli surface area.
`eccentric_radii_grid_from`	Convert a grid of (y,x) coordinates to an eccentric radius: :math: axis_ratio^0.5 (x^2 + (y^2/q))^0.5
`elliptical_radii_grid_from`	Convert a grid of (y,x) coordinates to their elliptical radii values: :math: (x^2 + (y^2/q))^0.5
`extract_attribute`	Returns an attribute of a class and its children profiles in the galaxy as a ValueIrregular or Grid2DIrregular object.
`from_magnitudes_and_angles`	Build an `ExternalPotential` from per-term magnitudes and position angles, matching the paper-style parameterisation.
`gamma_angle`
`gamma_magnitude`
`has`	Returns True if any attribute of this profile is an instance of the input class cls, else False.
`mass_angular_within_circle_from`	Integrate the mass profiles's convergence profile to compute the total mass within a circle of specified radius.
`mass_integral`	Integrand used by mass_angular_within_circle_from to compute the total projected mass within a circle.
`potential_2d_from`	Returns the lensing potential of the external potential at each grid point, following Powell et al. 2022 Eq.
`potential_func`	Returns the integrand of the lensing potential at a single point, used in numerical integration schemes for computing the potential from the mass profile's convergence.
`radial_deflection_from`
`radial_grid_from`	Convert a grid of (y, x) coordinates, to their radial distances from the profile centre (e.g. :math: r = sqrt(x2 + y2)).
`rotated_grid_from_reference_frame_from`	Rotate a grid of (y,x) coordinates which have been transformed to the elliptical reference frame of a profile back to the original unrotated coordinate grid reference frame.
`tau_angle`
`tau_magnitude`
`transformed_from_reference_frame_grid_from`	Transform a grid of (y,x) coordinates from the reference frame of the profile to the original observer reference frame.
`transformed_to_reference_frame_grid_from`	Transform a grid of (y,x) coordinates to the reference frame of the profile.
`vmapped_deflections_from`

Attributes

ellipticity_rescale

A rescaling factor applied to account for the ellipticity of the mass profile when computing the Einstein radius from the average convergence equals unity criterion.

classmethod from_magnitudes_and_angles(centre=(0.0, 0.0), gamma=0.0, theta_gamma=0.0, tau=0.0, theta_tau=0.0, delta=0.0, theta_delta=0.0)[source]#: Build an ExternalPotential from per-term magnitudes and position angles, matching the paper-style parameterisation. Angles are in degrees, anticlockwise from the +x axis.

gamma_magnitude(xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

gamma_angle(xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

tau_magnitude(xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

tau_angle(xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

delta_magnitude(xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

delta_angle(xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

convergence_func(grid_radius, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Returns the convergence of the mass profile as a function of the radial coordinate.

This is used to integrate the convergence profile to compute enclosed masses and the Einstein radius.

Parameters:: grid_radius (float) – The radial distance from the profile centre at which the convergence is evaluated.
Returns:: The convergence at the input radial distance.
Return type:: float

average_convergence_of_1_radius()[source]#

The radius a critical curve forms for this mass profile, e.g. where the mean convergence is equal to 1.0.

In case of ellipitical mass profiles, the ‘average’ critical curve is used, whereby the convergence is rescaled into a circle using the axis ratio.

This radius corresponds to the Einstein radius of the mass profile, and is a property of a number of mass profiles below.

convergence_2d_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>, **kwargs)[source]#

Returns the convergence \(\kappa = \tfrac{1}{2}\nabla^2 \psi\) at each grid point.

Only the \(\tau\) term contributes; the \(\gamma\) (spin-2 shear) and \(\delta\) (spin-3) terms are harmonic and yield zero convergence:

\[\kappa(x, y) = \tau_1 \, x + \tau_2 \, y\]

where \((x, y)\) are coordinates relative to centre.

potential_2d_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>, **kwargs)[source]#: Returns the lensing potential of the external potential at each grid point, following Powell et al. 2022 Eq. 4.

deflections_yx_2d_from(grid, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>, **kwargs)[source]#

Returns the deflection vector \(\boldsymbol{\alpha} = \nabla \psi\) at each grid point.

Computed in polar form (alpha_r = dpsi/dr, alpha_theta = (1/r),dpsi/dtheta) and then projected back to (y, x) Cartesian components. centre enters through the @transform decorator, which shifts the grid before the function body runs.