autolens.OperateDeflections#

class OperateDeflections[source]#

Bases: object

Packages methods which manipulate the 2D deflection angle map returned from the deflections_yx_2d_from function of a mass object (e.g. a MassProfile, Galaxy, Plane).

The majority of methods are those which from the 2D deflection angle map compute lensing quantities like a 2D shear field, magnification map or the Einstein Radius.

The methods in CalcLens are passed to the mass object to provide a concise API.

Parameters:

deflections_yx_2d_from – The function which returns the mass object’s 2D deflection angles.

Methods

area_within_curve_list_from

rtype:

List[float]

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):

convergence_2d_via_jacobian_from

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

deflections_yx_2d_from

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_list_from

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

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 Jacobian of the lensing object, which is computed by taking the gradient of the 2D deflection angle map in four direction (positive y, negative y, positive x, negative x).

magnification_2d_from

Returns the 2D magnification map of lensing object, which is computed as the inverse of the determinant of the jacobian.

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_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_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 (y,x) shear vectors of the lensing object, which are computed from the 2D deflection angle map via the Hessian using the expressions (see equation 57 https://inspirehep.net/literature/419263):

shear_yx_2d_via_jacobian_from

Returns the 2D (y,x) shear vectors of the lensing object, which are computed from the 2D deflection angle map via the Jacobian using the expression (see equation 58 https://inspirehep.net/literature/419263):

tangential_caustic_list_from

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

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_eigen_value_from

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

tangential_eigen_value_from(grid, jacobian=None)[source]#

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.

  • jacobian – A precomputed lensing jacobian, which is passed throughout the CalcLens functions for efficiency.

Return type:

Array2D

radial_eigen_value_from(grid, jacobian=None)[source]#

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.

  • jacobian – A precomputed lensing jacobian, which is passed throughout the CalcLens functions for efficiency.

Return type:

Array2D

magnification_2d_from(grid)[source]#

Returns the 2D magnification map of lensing object, which is computed as the inverse of the determinant of the jacobian.

Parameters:

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

Return type:

Array2D

hessian_from(grid, buffer=0.01, deflections_func=None)[source]#

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 computed by evaluating the 2D deflection angles around every (y,x) coordinate on the input 2D grid map in four directions (positive y, negative y, positive x, negative x), exploiting how the deflection angles are the derivative of the potential.

By using evaluating the deflection angles around each grid coordinate, the Hessian can therefore be computed using uniform or irregular 2D grids of (y,x). This can be slower, because x4 more deflection angle calculations are required, however it is more flexible in and therefore used throughout PyAutoLens by default.

The Hessian is returned as a 4 entry tuple, which reflect its structure as a 2x2 matrix.

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

  • buffer (float) – The spacing in the y and x directions around each grid coordinate where deflection angles are computed and used to estimate the derivative.

Return type:

Tuple

convergence_2d_via_hessian_from(grid, buffer=0.01)[source]#

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.

  • buffer (float) – The spacing in the y and x directions around each grid coordinate where deflection angles are computed and used to estimate the derivative.

Return type:

ArrayIrregular

shear_yx_2d_via_hessian_from(grid, buffer=0.01)[source]#

Returns the 2D (y,x) shear vectors of the lensing object, which are computed from the 2D deflection angle map via the Hessian using the expressions (see equation 57 https://inspirehep.net/literature/419263):

shear_y = hessian_{1,0} = hessian_{0,1} = hessian_yx = hessian_xy shear_x = 0.5 * (hessian_{0,0} - hessian_{1,1}) = 0.5 * (hessian_xx - hessian_yy)

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

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

The result is returned as a ShearYX2D dats structure, which has shape [total_shear_vectors, 2], where entries for [:,0] are the gamma_2 values and entries for [:,1] are the gamma_1 values.

Note therefore that this convention means the FIRST entries in the array are the gamma_2 values and the SECOND entries are the gamma_1 values.

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

  • buffer (float) – The spacing in the y and x directions around each grid coordinate where deflection angles are computed and used to estimate the derivative.

Return type:

ShearYX2DIrregular

magnification_2d_via_hessian_from(grid, buffer=0.01, deflections_func=None)[source]#

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.

Return type:

ArrayIrregular

tangential_critical_curve_list_from(grid, pixel_scale=0.05)[source]#

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.

Return type:

List[Grid2DIrregular]

radial_critical_curve_list_from(grid, pixel_scale=0.05)[source]#

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.

Return type:

List[Grid2DIrregular]

tangential_caustic_list_from(grid, pixel_scale=0.05)[source]#

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.

Return type:

List[Grid2DIrregular]

radial_caustic_list_from(grid, pixel_scale=0.05)[source]#

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.

Return type:

List[Grid2DIrregular]

radial_critical_curve_area_list_from(grid, pixel_scale)[source]#

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.

Return type:

List[float]

tangential_critical_curve_area_list_from(grid, pixel_scale=0.05)[source]#

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.

Return type:

List[float]

einstein_radius_list_from(grid, pixel_scale=0.05)[source]#

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)[source]#

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)[source]#

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.

Return type:

List[float]

einstein_mass_angular_from(grid, pixel_scale=0.05)[source]#

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.

Return type:

float

jacobian_from(grid)[source]#

Returns the Jacobian of the lensing object, which is computed by taking the gradient of the 2D deflection angle map in four direction (positive y, negative y, positive x, negative x).

By using the np.gradient method the Jacobian can therefore only be computed using uniform 2D grids of (y,x) coordinates, and does not support irregular grids. For this reason, calculations by default use the Hessian, which is slower to compute because more deflection angle calculations are necessary but more flexible in general.

The Jacobian is returned as a list of lists, which reflect its structure as a 2x2 matrix.

Parameters:

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

convergence_2d_via_jacobian_from(grid, jacobian=None)[source]#

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

convergence = 1.0 - 0.5 * (jacobian_{0,0} + jacobian_{1,1}) = 0.5 * (jacobian_xx + jacobian_yy)

By going via the Jacobian, the convergence must be calculated using 2D uniform grid.

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

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

  • jacobian – A precomputed lensing jacobian, which is passed throughout the CalcLens functions for efficiency.

Return type:

Array2D

shear_yx_2d_via_jacobian_from(grid, jacobian=None)[source]#

Returns the 2D (y,x) shear vectors of the lensing object, which are computed from the 2D deflection angle map via the Jacobian using the expression (see equation 58 https://inspirehep.net/literature/419263):

shear_y = -0.5 * (jacobian_{0,1} + jacobian_{1,0} = -0.5 * (jacobian_yx + jacobian_xy) shear_x = 0.5 * (jacobian_{1,1} + jacobian_{0,0} = 0.5 * (jacobian_yy + jacobian_xx)

By going via the Jacobian, the convergence must be calculated using 2D uniform grid.

This calculation of the shear vectors is independent of analytic calculations defined within MassProfile objects and the calculation via the Hessian. It can therefore be used as a cross-check.

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

  • jacobian – A precomputed lensing jacobian, which is passed throughout the CalcLens functions for efficiency.

Return type:

Union[ShearYX2D, ShearYX2DIrregular]