autogalaxy.profiles.mass.ExternalShear#

class ExternalShear[source]#

Bases: MassProfile

Constant external shear term used in strong-lens mass models.

ExternalShear represents the line-of-sight contribution to the lensing potential from mass that is not part of the primary lens — typically nearby group/cluster members, large-scale structure, or unmodelled satellites. Because this contribution is approximately uniform across the small angular extent of a strong-lens system, it is parameterised as a constant shear with two components, \(\gamma_1\) and \(\gamma_2\), in the same convention as LensCalc.shear_yx_2d_via_hessian_from and ShearYX2DIrregular:

\(\gamma_1\) produces stretching along the x/y axes
\(\gamma_2\) produces stretching along the diagonals

The associated shear magnitude and position angle (degrees, anticlockwise from the +x axis) are:

\[|\gamma| = \sqrt{\gamma_1^2 + \gamma_2^2}, \qquad \phi = \tfrac{1}{2} \, \mathrm{arctan2}(\gamma_2, \gamma_1).\]

Note that the shear position angle lies in the direction of image stretching. An external mass located in the direction of compression therefore appears at an angle offset by 90 degrees from \(\phi\).

Parameters:

gamma_1 (float) – The \(\gamma_1\) shear component.
gamma_2 (float) – The \(\gamma_2\) shear component.

Methods

`angle`	Returns the shear position angle \(\phi = \tfrac{1}{2}\,\mathrm{arctan2}(\gamma_2, \gamma_1)\) in degrees, in the [0, 180) convention used elsewhere in the package.
`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`	A pure shear term has zero convergence at every 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 angles of the constant external shear at each `(y, x)` arc-second coordinate.
`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.
`has`	Returns True if any attribute of this profile is an instance of the input class cls, else False.
`magnitude`	Returns the shear magnitude \(\|\gamma\| = \sqrt{\gamma_1^2 + \gamma_2^2}\).
`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 constant external shear, given by:
`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.
`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.

magnitude(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 shear magnitude \(|\gamma| = \sqrt{\gamma_1^2 + \gamma_2^2}\).

angle(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 shear position angle \(\phi = \tfrac{1}{2}\,\mathrm{arctan2}(\gamma_2, \gamma_1)\) in degrees, in the [0, 180) convention used elsewhere in the package.

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]#: A pure shear term has zero convergence at every grid point.

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 constant external shear, given by:

\[\psi(\theta) = -\tfrac{1}{2} |\gamma| \, r^2 \, \cos\!\big(2\,(\varphi - \phi_\gamma)\big)\]

where \(r, \varphi\) are the polar coordinates of grid and \(\phi_\gamma\) is the shear position angle (offset by -90 deg to remain consistent with the deflection-angle convention used elsewhere in PyAutoLens).

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 angles of the constant external shear at each (y, x) arc-second coordinate.

In the profile’s rotated reference frame (where the shear position angle is aligned with the x-axis) the deflection reduces to:

\[\alpha_y(y, x) = -|\gamma| \, y, \qquad \alpha_x(y, x) = +|\gamma| \, x.\]

The @transform(rotate_back=True) decorator rotates the input grid into this aligned frame and rotates the resulting deflection vectors back into the original frame. Because the shear is a spin-2 field, the position angle \(\phi\) of the shear is encoded in the rotation of the grid and not as an extra factor in the deflection formula above.

Parameters:

grid (Union[ndarray, Grid2D, Grid2DIrregular]) – The grid of (y,x) arc-second coordinates the deflection angles are computed on.
xp – The array module (numpy or jax.numpy).