caustics.lenses package

Subpackages

• caustics.lenses.func package
  • Submodules
  • caustics.lenses.func.base module
    • forward_raytrace()
    • forward_raytrace_rootfind()
    • physical_from_reduced_deflection_angle()
    • reduced_from_physical_deflection_angle()
    • remove_duplicate_points()
    • remove_triangle_duplicates()
    • time_delay_arcsec2_to_days()
    • triangle_area()
    • triangle_contains()
    • triangle_equals()
    • triangle_neighbors()
    • triangle_upsample()
  • caustics.lenses.func.enclosed_mass module
    • convergence_enclosed_mass()
    • physical_deflection_angle_enclosed_mass()
  • caustics.lenses.func.epl module
    • convergence_epl()
    • potential_epl()
    • reduced_deflection_angle_epl()
  • caustics.lenses.func.external_shear module
    • gamma_phi_to_gamma1()
    • gamma_phi_to_gamma2()
    • potential_external_shear()
    • reduced_deflection_angle_external_shear()
  • caustics.lenses.func.mass_sheet module
    • convergence_mass_sheet()
    • potential_mass_sheet()
    • reduced_deflection_angle_mass_sheet()
  • caustics.lenses.func.multipole module
    • convergence_multipole()
    • potential_multipole()
    • reduced_deflection_angle_multipole()
  • caustics.lenses.func.nfw module
    • convergence_nfw()
    • convergence_s_nfw()
    • physical_deflection_angle_nfw()
    • potential_nfw()
    • scale_density_nfw()
    • scale_radius_nfw()
  • caustics.lenses.func.pixelated_convergence module
    • build_kernels_pixelated_convergence()
    • build_window_pixelated_convergence()
    • potential_pixelated_convergence()
    • reduced_deflection_angle_pixelated_convergence()
  • caustics.lenses.func.point module
    • convergence_point()
    • mass_to_rein_point()
    • potential_point()
    • reduced_deflection_angle_point()
    • rein_to_mass_point()
  • caustics.lenses.func.pseudo_jaffe module
    • convergence_0_pseudo_jaffe()
    • convergence_pseudo_jaffe()
    • mass_enclosed_2d_pseudo_jaffe()
    • potential_pseudo_jaffe()
    • reduced_deflection_angle_pseudo_jaffe()
  • caustics.lenses.func.sie module
    • convergence_sie()
    • potential_sie()
    • reduced_deflection_angle_sie()
    • sigma_v_to_rein_sie()
  • caustics.lenses.func.sis module
    • convergence_sis()
    • potential_sis()
    • reduced_deflection_angle_sis()
  • caustics.lenses.func.tnfw module
    • M0_scalemass_tnfw()
    • M0_totmass_tnfw()
    • concentration_tnfw()
    • convergence_tnfw()
    • mass_enclosed_2d_tnfw()
    • physical_deflection_angle_tnfw()
    • potential_tnfw()
    • scale_density_tnfw()
  • Module contents
    • M0_scalemass_tnfw()
    • M0_totmass_tnfw()
    • build_kernels_pixelated_convergence()
    • build_window_pixelated_convergence()
    • concentration_tnfw()
    • convergence_0_pseudo_jaffe()
    • convergence_enclosed_mass()
    • convergence_epl()
    • convergence_mass_sheet()
    • convergence_multipole()
    • convergence_nfw()
    • convergence_point()
    • convergence_pseudo_jaffe()
    • convergence_sie()
    • convergence_sis()
    • convergence_tnfw()
    • forward_raytrace()
    • forward_raytrace_rootfind()
    • gamma_phi_to_gamma1()
    • gamma_phi_to_gamma2()
    • mass_enclosed_2d_pseudo_jaffe()
    • mass_enclosed_2d_tnfw()
    • mass_to_rein_point()
    • physical_deflection_angle_enclosed_mass()
    • physical_deflection_angle_nfw()
    • physical_deflection_angle_tnfw()
    • physical_from_reduced_deflection_angle()
    • potential_epl()
    • potential_external_shear()
    • potential_mass_sheet()
    • potential_multipole()
    • potential_nfw()
    • potential_pixelated_convergence()
    • potential_point()
    • potential_pseudo_jaffe()
    • potential_sie()
    • potential_sis()
    • potential_tnfw()
    • reduced_deflection_angle_epl()
    • reduced_deflection_angle_external_shear()
    • reduced_deflection_angle_mass_sheet()
    • reduced_deflection_angle_multipole()
    • reduced_deflection_angle_pixelated_convergence()
    • reduced_deflection_angle_point()
    • reduced_deflection_angle_pseudo_jaffe()
    • reduced_deflection_angle_sie()
    • reduced_deflection_angle_sis()
    • reduced_from_physical_deflection_angle()
    • rein_to_mass_point()
    • remove_triangle_duplicates()
    • scale_density_nfw()
    • scale_density_tnfw()
    • scale_radius_nfw()
    • sigma_v_to_rein_sie()
    • time_delay_arcsec2_to_days()
    • triangle_area()
    • triangle_contains()
    • triangle_equals()
    • triangle_neighbors()
    • triangle_upsample()

Submodules

caustics.lenses.base module

class caustics.lenses.base.ThickLens(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], name: Annotated[str | None, 'Name of the lens model'] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None)

Bases: Lens

Base class for modeling gravitational lenses that cannot be treated using the thin lens approximation. It is an abstract class and should be subclassed for different types of lens models.

cosmology

An instance of a Cosmology class that describes the cosmological parameters of the model.

Type:

Cosmology

effective_convergence_curl(x: ArrayLike, y: ArrayLike, **kwargs) → ArrayLike

Use the curl of the effective reduced deflection angle vector field to compute an effective convergence which derives specifically from the curl of the deflection field. This field is purely a result of multiplane lensing and cannot occur in single plane lensing.

See: https://arxiv.org/pdf/2006.07383.pdf

effective_convergence_div(x: ArrayLike, y: ArrayLike, **kwargs) → ArrayLike

Using the divergence of the effective reduced delfection angle we can compute the divergence component of the effective convergence field. This field produces a single plane convergence field which reproduces as much of the deflection field as possible for a single plane.

See: https://arxiv.org/pdf/2006.07383.pdf see also the effective_convergence_curl method.

effective_reduced_deflection_angle(x: ArrayLike, y: ArrayLike, **kwargs) → tuple[ArrayLike, ArrayLike]

ThickLens objects do not have a reduced deflection angle since the distance D_ls is undefined. Instead we define an effective reduced deflection angle by simply assuming the relation $lpha = heta - eta$ holds, where $lpha$ is the effective reduced deflection angle, $ heta$ are the observed angular coordinates, and $eta$ are the angular coordinates to the source plane.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

jacobian_effective_deflection_angle(x: ArrayLike, y: ArrayLike, method='autograd', pixelscale=None, **kwargs) → tuple[tuple[ArrayLike, ArrayLike], tuple[ArrayLike, ArrayLike]]

Return the jacobian of the effective reduced deflection angle vector field. This equates to a (2,2) matrix at each (x,y) point.

method: autograd or fft

physical_deflection_angle(x: ArrayLike, y: ArrayLike, *args, **kwargs) → tuple[ArrayLike, ArrayLike]

Physical deflection angles are computed with respect to a lensing plane. ThickLens objects have no unique definition of a lens plane and so cannot compute a physical_deflection_angle

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y direction.

  Unit: arcsec

abstract raytrace(x: ArrayLike, y: ArrayLike, *args, **kwargs) → tuple[ArrayLike, ArrayLike]

Performs ray tracing by computing the angular position on the source plance associated with a given input observed angular coordinate x,y.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x (ArrayLike) – x coordinate ArrayLike of the ray-traced light rays

  Unit: arcsec

• y (ArrayLike) – y coordinate ArrayLike of the ray-traced light rays

  Unit: arcsec

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, **kwargs) → tuple[ArrayLike, ArrayLike]

ThickLens objects do not have a reduced deflection angle since the distance D_ls is undefined

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: unitless

abstract surface_density(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the projected mass density at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

The projected mass density at the given coordinates in units of solar masses per square Mpc.

Unit: Msun/Mpc^2

Return type:

ArrayLike

abstract time_delay(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the gravitational time delay at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

The gravitational time delay at the given coordinates.

Unit: seconds

Return type:

ArrayLike

class caustics.lenses.base.ThinLens(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: Lens

Base class for thin gravitational lenses.

This class provides an interface for thin gravitational lenses, i.e., lenses that can be modeled using the thin lens approximation. The class provides methods to compute several lensing quantities such as the deflection angle, convergence, potential, surface mass density, and gravitational time delay.

name

Name of the lens model.

Type:

string

cosmology

Cosmology object that encapsulates cosmological parameters and distances.

Type:

Cosmology

z_l

Redshift of the lens. Defaults to None.

Unit: unitless

Type:

(Optional[ArrayLike], optional)

abstract convergence(x: ArrayLike, y: ArrayLike, chunk_size: int | None = None, *args, **kwargs) → ArrayLike

Computes the convergence of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

Dimensionless convergence, normalized by the critical surface density at the lens plane

Unit: unitless

Return type:

ArrayLike

jacobian_deflection_angle(x: ArrayLike, y: ArrayLike, method='autograd', pixelscale=None, chunk_size: int | None = None) → tuple[tuple[ArrayLike, ArrayLike], tuple[ArrayLike, ArrayLike]]

Return the jacobian of the deflection angle vector. This equates to a (2,2) matrix at each (x,y) point.

method: autograd or fft

physical_deflection_angle(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Computes the physical deflection angle immediately after passing through this lens’s plane.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

abstract potential(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

raytrace(x: ArrayLike, y: ArrayLike, **kwargs) → tuple[ArrayLike, ArrayLike]

Perform a ray-tracing operation by subtracting the deflection angles from the input coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y direction.

  Unit: arcsec

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, chunk_size: int | None = None) → tuple[ArrayLike, ArrayLike]

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

surface_density(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → ArrayLike

Computes the surface mass density of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Surface mass density at the given coordinates in solar masses per Mpc^2.

Unit: Msun/Mpc^2

Return type:

ArrayLike

time_delay(x: ArrayLike, y: ArrayLike, shapiro_time_delay: bool = True, geometric_time_delay: bool = True) → ArrayLike

Computes the gravitational time delay for light passing through the lens at given coordinates.

This time delay is induced by the photons traveling through a gravitational potential well (Shapiro time delay) plus the effect of the increased path length that the photons must traverse (geometric time delay). The main equation involved here is the following:

\[\Delta t = \frac{1 + z_l}{c} \frac{D_s}{D_l D_{ls}} \left[ \frac{1}{2}|\vec{\alpha}(\vec{\theta})|^2 - \psi(\vec{\theta}) \right]\]

where \(\vec{\alpha}(\vec{\theta})\) is the deflection angle, \(\psi(\vec{\theta})\) is the lensing potential, \(D_l\) is the comoving distance to the lens, \(D_s\) is the comoving distance to the source, and \(D_{ls}\) is the comoving distance between the lens and the source. In the above equation, the first term is the geometric time delay and the second term is the gravitational time delay.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• shapiro_time_delay (bool) – Whether to include the Shapiro time delay component.

• geometric_time_delay (bool) – Whether to include the geometric time delay component.

Returns:

Time delay at the given coordinates.

Unit: days

Return type:

ArrayLike

References

1. Irwin I. Shapiro (1964). “Fourth Test of General Relativity”. Physical Review Letters. 13 (26): 789-791

2. Refsdal, S. (1964). “On the possibility of determining Hubble’s parameter and the masses of galaxies from the gravitational lens effect”. Monthly Notices of the Royal Astronomical Society. 128 (4): 307-310.

caustics.lenses.batchedplane module

class caustics.lenses.batchedplane.BatchedPlane(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], lens: ThinLens, name: Annotated[str | None, 'Name of the lens model'] = None, z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, chunk_size: int | None = None)

Bases: ThinLens

A class for combining multiple thin lenses into a single lensing plane. It is assumed that the lens parameters will have a batch dimension, internally this class will vmap over the batch dimension and return the combined lensing quantity. This class can only handle a single lens type, if you want to combine different lens types, use the SinglePlane class.

name

The name of the single plane lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

lens

A ThinLens object that will be vmapped over into a single lensing plane.

Type:

ThinLens

convergence(x: ArrayLike, y: ArrayLike, lens_params, lens_dims) → ArrayLike

Calculate the total projected mass density by summing the mass densities of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total projected mass density.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, lens_params, lens_dims) → ArrayLike

Compute the total lensing potential by summing the lensing potentials of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, lens_params, lens_dims) → tuple[ArrayLike, ArrayLike]

Calculate the total deflection angle by summing the deflection angles of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the deflection angle.

  Unit: arcsec

caustics.lenses.enclosed_mass module

class caustics.lenses.enclosed_mass.EnclosedMass(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], enclosed_mass: Callable, z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, q: Annotated[ArrayLike | float | None, 'The axis ratio of the lens', True] = None, phi: Annotated[ArrayLike | float | None, 'The position angle of the lens', True] = None, p: Annotated[ArrayLike | list[float] | None, 'parameters for the enclosed mass function', True] = None, s: Annotated[float, 'Softening parameter to prevent numerical instabilities'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: ThinLens

A class for representing a lens with an enclosed mass profile. This generic lens profile can represent any lens with a mass distribution that can be described by a function that returns the enclosed mass as a function of radius.

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], p: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the dimensionless convergence of the lens at a given position.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

• The dimensionless convergence at the given position. [ArrayLike]

• *Unit (unitless*)

physical_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], p: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the physical deflection angle of the lens at a given position.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

• The physical deflection angle at the given position. [ArrayLike, ArrayLike]

• *Unit (arcsec*)

potential(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

reduced_deflection_angle(x, y, z_s, z_l)

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

caustics.lenses.epl module

class caustics.lenses.epl.EPL(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the lens center', True] = None, q: Annotated[ArrayLike | float | None, 'Axis ratio of the lens', True] = None, phi: Annotated[ArrayLike | float | None, 'Position angle of the lens', True] = None, Rein: Annotated[ArrayLike | float | None, 'Einstein radius of the lens', True] = None, t: Annotated[ArrayLike | float | None, 'Power law slope (`gamma-1`) of the lens', True] = None, angle_system: str = 'q_phi', e1: ArrayLike | float | None = None, e2: ArrayLike | float | None = None, c1: ArrayLike | float | None = None, c2: ArrayLike | float | None = None, s: Annotated[float, 'Softening length for the elliptical power-law profile'] = 0.0, n_iter: Annotated[int, 'Number of iterations for the iterative solver'] = 18, chunk_size: Annotated[int | None, 'Number of chunks for the iterative solver'] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: Angle_Mixin, ThinLens

Elliptical power law (EPL, aka singular power-law ellipsoid) profile.

This class represents a thin gravitational lens model with an elliptical power law profile. The lensing equations are solved iteratively using an approach based on Tessore et al. 2015.

n_iter

Number of iterations for the iterative solver.

Type:

int

chunk_size

Number of iterations to do in parallel for the iterative solver.

Type:

int

s

Softening length for the elliptical power-law profile.

Type:

float

Unit: arcsec

Parameters:

• z_l (Optional[Union[ArrayLike, float]]) –

  This is the redshift of the lens. In the context of gravitational lensing, the lens is the galaxy or other mass distribution that is bending the light from a more distant source.

  Unit: unitless

• y0 (x0 and) –

  These are the coordinates of the lens center in the lens plane. The lens plane is the plane perpendicular to the line of sight in which the deflection of light by the lens is considered.

  Unit: arcsec

• q (Optional[Union[ArrayLike, float]]) –

  This is the axis ratio of the lens, i.e., the ratio of the minor axis to the major axis of the elliptical lens.

  Unit: unitless

• phi (Optional[Union[ArrayLike, float]]) –

  This is the orientation of the lens on the sky, typically given as an angle measured counter-clockwise from some reference direction.

  Unit: radians

• Rein (Optional[Union[ArrayLike, float]]) –

  The Einstein radius of the lens, exact at q=1.0.

  Unit: arcsec

• t (Optional[Union[ArrayLike, float]]) –

  This is the power-law slope parameter of the lens model. In the context of the EPL model, t is equivalent to the gamma parameter minus one, where gamma is the power-law index of the radial mass distribution of the lens.

  Unit: unitless

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param'], t: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence of the lens, which describes the local density of the lens.

Parameters:

• x (ArrayLike) –

  X coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  Y coordinates in the lens plane.

  Unit: arcsec

Returns:

The convergence of the lens.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param'], t: Annotated[ArrayLike, 'Param'])

Compute the lensing potential of the lens.

Parameters:

• x (ArrayLike) –

  X coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  Y coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param'], t: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the reduced deflection angles of the lens.

Parameters:

• x (ArrayLike) –

  X coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  Y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle

  Unit: arcsec

caustics.lenses.external_shear module

class caustics.lenses.external_shear.ExternalShear(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'x-coordinate of the shear center in the lens plane', True] = None, y0: Annotated[ArrayLike | float | None, 'y-coordinate of the shear center in the lens plane', True] = None, gamma_1: Annotated[ArrayLike | float | None, 'Shear component in the x-direction', True] = None, gamma_2: Annotated[ArrayLike | float | None, 'Shear component in the y-direction', True] = None, parametrization: Literal['cartesian', 'angular'] = 'cartesian', s: Annotated[float, 'Softening length for the elliptical power-law profile'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: ThinLens

Represents an external shear effect in a gravitational lensing system.

name

Identifier for the lens instance.

Type:

str

cosmology

The cosmological model used for lensing calculations.

Type:

Cosmology

z_l

The redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0, y0

Coordinates of the shear center in the lens plane.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

gamma_1, gamma_2

Shear components.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

Notes

The shear components gamma_1 and gamma_2 represent an external shear, a gravitational distortion that can be caused by nearby structures outside of the main lens galaxy.

convergence(x: ArrayLike, y: ArrayLike) → ArrayLike

The convergence is undefined for an external shear.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

Convergence for an external shear.

Unit: unitless

Return type:

ArrayLike

Raises:

NotImplementedError – This method is not implemented as the convergence is not defined for an external shear.

property parametrization: str

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], gamma_1: Annotated[ArrayLike, 'Param'], gamma_2: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculates the lensing potential.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], gamma_1: Annotated[ArrayLike, 'Param'], gamma_2: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculates the reduced deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

caustics.lenses.mass_sheet module

class caustics.lenses.mass_sheet.MassSheet(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'x-coordinate of the shear center in the lens plane', True] = None, y0: Annotated[ArrayLike | float | None, 'y-coordinate of the shear center in the lens plane', True] = None, kappa: Annotated[ArrayLike | float | None, 'Surface density', True] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Represents an external shear effect in a gravitational lensing system.

name

Identifier for the lens instance.

Type:

string

cosmology

The cosmological model used for lensing calculations.

Type:

Cosmology

z_l

The redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

x-coordinate of the shear center in the lens plane.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

y-coordinate of the shear center in the lens plane.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

kappa

Convergence. Surface density normalized by the critical surface density.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

convergence(x: ArrayLike, y: ArrayLike, kappa: Annotated[ArrayLike, 'Param']) → ArrayLike

Computes the convergence of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

Dimensionless convergence, normalized by the critical surface density at the lens plane

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], kappa: Annotated[ArrayLike, 'Param']) → ArrayLike

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], kappa: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculates the reduced deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

caustics.lenses.multiplane module

class caustics.lenses.multiplane.Multiplane(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], lenses: Tuple[ThinLens], name: Annotated[str | None, 'Name of the lens model'] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None)

Bases: ThickLens

Class for handling gravitational lensing with multiple lens planes.

lenses list of ThinLens

List of thin lenses.

Parameters:

• name (string) – Name of the lens.

• cosmology (Cosmology) – Cosmological parameters used for calculations.

• lenses (list[ThinLens]) – List of thin lenses.

• z_s (ZType) – Redshift of the source.

effective_reduced_deflection_angle(x: ArrayLike, y: ArrayLike) → tuple[ArrayLike, ArrayLike]

ThickLens objects do not have a reduced deflection angle since the distance D_ls is undefined. Instead we define an effective reduced deflection angle by simply assuming the relation $lpha = heta - eta$ holds, where $lpha$ is the effective reduced deflection angle, $ heta$ are the observed angular coordinates, and $eta$ are the angular coordinates to the source plane.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

get_z_ls() → list[ArrayLike]

Get the redshifts of each lens in the multiplane.

Returns:

Redshifts of the lenses.

Unit: unitless

Return type:

List[ArrayLike]

raytrace(x: ArrayLike, y: ArrayLike) → tuple[ArrayLike, ArrayLike]

Calculate the angular source positions corresponding to the observer positions x,y. See Margarita et al. 2013 for the formalism from the GLAMER -II code: https://ui.adsabs.harvard.edu/abs/2014MNRAS.445.1954P/abstract

The primary equation used here is equation 18. With a slight correction it reads:

\[\vec{x}^{i+1} = \vec{x}^i + D_{i+1,i}\left[\vec{\theta} - \sum_{j=1}^{i}\bf{\alpha}^j(\vec{x}^j)\right]\]

As an initialization we set the physical positions at the first lensing plane to be \(\vec{\theta}D_{1,0}\) which is just propagation through regular space to the first plane. Note that \(\vec{\alpha}\) is a physical deflection angle. The equation above converts straightforwardly into a recursion formula:

\[\vec{x}^{i+1} = \vec{x}^i + D_{i+1,i}\vec{ heta}^{i} \vec{\theta}^{i+1} = \vec{\theta}^{i} - \alpha^i(\vec{x}^{i+1})\]

Here we set as initialization \(\vec{ heta}^0 = theta\) the observation angular coordinates and \(\vec{x}^0 = 0\) the initial physical coordinates (i.e. the observation rays come from a point at the observer). The indexing of \(\vec{x}^i\) and \(\vec{\theta}^i\) indicates the properties at the plane \(i\), and 0 means the observer, 1 is the first lensing plane (infinitesimally after the plane since the deflection has been applied), and so on. Note that in the actual implementation we start at \(\vec{x}^1\) and \(\vec{\theta}^0\) and begin at the second step in the recursion formula.

Parameters:

• x (ArrayLike) –

  angular x-coordinates in the image plane.

  Unit: arcsec

• y (ArrayLike) –

  angular y-coordinates in the image plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Reduced deflection angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Reduced deflection angle in the y-direction.

  Unit: arcsec

References

1. Margarita Petkova, R. Benton Metcalf, and Carlo Giocoli. 2014. GLAMER II: multiple-plane lensing. MNRAS 445, 1954-1966. DOI:https://doi.org/10.1093/mnras/stu1860

surface_density(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Calculate the projected mass density.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

Projected mass density.

Unit: Msun/Mpc^2

Return type:

ArrayLike

Raises:

NotImplementedError – This method is not yet implemented.

time_delay(x: ArrayLike, y: ArrayLike, shapiro_time_delay: bool = True, geometric_time_delay: bool = True) → ArrayLike

Compute the time delay of light caused by the lensing. This is based on equation 6.22 in Petters et al. 2001. For the time delay of a light path from the observer to the source, the following equation is used:

\Delta t = \sum_{i=1}^{N-1} \tau_{i,i+1} \left[ \frac{1}{2} \left( \vec{\alpha}^i \right)^2 - \beta_{i,i+1} \psi^i \right] \\
\tau_{i,j} = (1 + z_i) \frac{D_i D_{j}}{D_{i,j} c} \\
\beta_{i,j} = \frac{D_{i,j} D_s}{D_{j} D_{i,s}} \\

where \(\vec{\alpha}^i\) is the deflection angle at the i-th lens plane, \(\psi^i\) is the lensing potential at the i-th lens plane, \(D_i\) is the comoving distance to the i-th lens plane, \(D_{i,j}\) is the comoving distance between the i-th and j-th lens plane, \(D_s\) is the comoving distance to the source, and \(D_{i,s}\) is the comoving distance between the i-th lens plane and the source.

This performs the same ray tracing as the raytrace() method, but computes the time delay along the way.

Parameters:

• x (ArrayLike) –

  x-coordinates in the image plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the image plane.

  Unit: arcsec

• shapiro_time_delay (bool) – Whether to include the Shapiro time delay component.

• geometric_time_delay (bool) – Whether to include the geometric time delay component.

Returns:

Time delay caused by the lensing.

Unit: days

Return type:

ArrayLike

References

1. Petters A. O., Levine H., Wambsganss J., 2001, Singularity Theory and Gravitational Lensing. Birkhauser, Boston

2. McCully et al. 2014, A new hybrid framework to efficiently model lines of sight to gravitational lenses

caustics.lenses.multipole module

class caustics.lenses.multipole.Multipole(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], m: Annotated[ArrayLike | int | tuple[int], 'The Multipole moment(s) m'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, a_m: Annotated[ArrayLike | float | None, 'The amplitude of the multipole', True] = None, phi_m: Annotated[ArrayLike | float | None, 'The orientation angle of the multipole', True] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Represents a multipole effect in a gravitational lensing system.

name

Identifier for the lens instance.

Type:

str

cosmology

The cosmological model used for lensing calculations.

Type:

Cosmology

m

Order of multipole(s).

Type:

Union[ArrayLike, int, tuple[int]]

z_l

The redshift of the lens.

Type:

Optional[Union[ArrayLike, float]]

x0, y0

Coordinates of the shear center in the lens plane.

Type:

Optional[Union[ArrayLike, float]]

a_m

Strength of multipole.

Type:

Optional[Union[ArrayLike, float]]

phi_m

Orientation of multipole.

Type:

Optional[Union[ArrayLike, float]]

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], a_m: Annotated[ArrayLike, 'Param'], phi_m: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density of the multipole.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• ArrayLike – The projected mass density.

  Unit: unitless

• Equation (B10) and (B3) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], a_m: Annotated[ArrayLike, 'Param'], phi_m: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential of the multiplane.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• ArrayLike – The lensing potential.

  Unit: arcsec^2

• Equation (B11) and (B3) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], a_m: Annotated[ArrayLike, 'Param'], phi_m: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the deflection angle of the multipole.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• Equation (B11) and (B12) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

to(device=None, dtype=None)

Move the lens to the specified device.

Parameters:

• device (optional) – The device to move the lens to.

• dtype (optional) – The data type to cast the lens to.

Returns:

The lens object.

Return type:

Multipole

caustics.lenses.nfw module

class caustics.lenses.nfw.NFW(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the lens center', True] = None, mass: Annotated[ArrayLike | float | None, 'Mass of the lens', True] = None, c: Annotated[ArrayLike | float | None, 'Concentration parameter of the lens', True] = None, s: Annotated[float, 'Softening parameter to avoid singularities at the center of the lens'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

NFW lens class. This class models a lens using the Navarro-Frenk-White (NFW) profile. The NFW profile is a spatial density profile of dark matter halo that arises in cosmological simulations.

z_l

Redshift of the lens. Default is None.

Unit: unitless

Type:

Optional[ArrayLike]

z_s

Redshift of the source. Default is None.

Unit: unitless

Type:

Optional[ArrayLike]

x0

x-coordinate of the lens center in the lens plane. Default is None.

Unit: arcsec

Type:

Optional[ArrayLike]

y0

y-coordinate of the lens center in the lens plane. Default is None.

Unit: arcsec

Type:

Optional[ArrayLike]

mass

Mass of the lens. Default is None.

Unit: Msun

Type:

Optional[ArrayLike]

c

Concentration parameter of the lens. Default is None.

Unit: unitless

Type:

Optional[ArrayLike]

s

Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

Unit: arcsec

Type:

float

get_scale_radius()

Returns the scale radius of the lens.

get_scale_density()

Returns the scale density of the lens.

get_convergence_s()

Returns the dimensionless surface mass density of the lens.

deflection_angle()

Computes the deflection angle.

convergence()

Computes the convergence (dimensionless surface mass density).

potential()

Computes the lensing potential.

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence (dimensionless surface mass density).

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The convergence (dimensionless surface mass density).

Unit: unitless

Return type:

ArrayLike

get_scale_density(z_l: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the scale density of the lens.

Parameters:

• z_l (ArrayLike) –

  Redshift of the lens.

  Unit: unitless

• c (ArrayLike) –

  Concentration parameter of the lens.

  Unit: unitless

Returns:

The scale density of the lens in solar masses per Mpc cubed.

Unit: Msun/Mpc^3

Return type:

ArrayLike

get_scale_radius(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the scale radius of the lens.

Parameters:

• z_l (ArrayLike) –

  Redshift of the lens.

  Unit: unitless

• mass (ArrayLike) –

  Mass of the lens.

  Unit: Msun

• c (ArrayLike) –

  Concentration parameter of the lens.

  Unit: unitless

Returns:

The scale radius of the lens in Mpc.

Unit: Mpc

Return type:

ArrayLike

physical_deflection_angle(x: ArrayLike, y: ArrayLike, z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the physical deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the reduced deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the reduced deflection angle.

  Unit: arcsec

potential(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x, y, z_s, z_l)

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

caustics.lenses.pixelated_convergence module

class caustics.lenses.pixelated_convergence.PixelatedConvergence(pixelscale: Annotated[float, 'pixelscale'], cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the center of the grid', True] = tensor(0.), y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the center of the grid', True] = tensor(0.), convergence_map: Annotated[ArrayLike | None, 'A 2D tensor representing the convergence map', True] = None, scale: Annotated[ArrayLike | None, 'A scale factor to multiply by the convergence map', True] = 1.0, shape: Annotated[tuple[int | None, ...], 'The shape of the convergence map'] = (None, None), convolution_mode: Annotated[Literal['fft', 'conv2d'], 'The convolution mode for calculating deflection angles and lensing potential'] = 'fft', use_next_fast_len: Annotated[bool, 'If True, adds additional padding to speed up the FFT by calling `scipy.fft.next_fast_len`'] = True, padding: Annotated[Literal['zero', 'circular', 'reflect', 'tile'], 'Specifies the type of padding'] = 'zero', window_kernel: Annotated[float, 'Amount of kernel to be windowed'] = 0.125, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], convergence_map: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence at the specified positions.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the convergence for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the convergence for.

  Unit: arcsec

Returns:

The convergence at the specified positions.

Unit: unitless

Return type:

ArrayLike

property convolution_mode

Get the convolution mode of the ConvergenceGrid object.

Returns:

The convolution mode, either “fft” or “conv2d”.

Return type:

string

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], convergence_map: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

Returns:

The lensing potential at the specified positions.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], convergence_map: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection angles at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

to(device=None, dtype=None)

Move the ConvergenceGrid object and all its tensors to the specified device and dtype.

Parameters:

• device (optional) – The target device to move the tensors to.

• dtype (optional) – The target data type to cast the tensors to.

caustics.lenses.pixelated_deflection module

class caustics.lenses.pixelated_deflection.PixelatedDeflection(pixelscale: Annotated[float, 'pixelscale', True], cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the center of the grid', True] = tensor(0.), y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the center of the grid', True] = tensor(0.), deflection_map: Annotated[ArrayLike | None, 'A 3D tensor (2, nx, ny) representing the reduced deflection angle map', True] = None, shape: Annotated[tuple[int | None, ...], 'The shape of the deflection map'] = (2, None, None), name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

convergence(x, y, **kwargs)

Computes the convergence of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

Dimensionless convergence, normalized by the critical surface density at the lens plane

Unit: unitless

Return type:

ArrayLike

potential(x, y, **kwargs)

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], deflection_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection at the specified positions.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the convergence for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the convergence for.

  Unit: arcsec

Returns:

The deflection at the specified positions.

Unit: unitless

Return type:

ArrayLike

caustics.lenses.pixelated_potential module

class caustics.lenses.pixelated_potential.PixelatedPotential(pixelscale: Annotated[float, 'pixelscale', True], cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the center of the grid', True] = tensor(0.), y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the center of the grid', True] = tensor(0.), potential_map: Annotated[ArrayLike | None, 'A 2D tensor representing the potential map', True] = None, shape: Annotated[tuple[int | None, ...], 'The shape of the potential map'] = (None, None), name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], potential_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence at the specified positions.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the convergence for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the convergence for.

  Unit: arcsec

Returns:

The convergence at the specified positions.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], potential_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

Returns:

The lensing potential at the specified positions.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], potential_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection angles at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

caustics.lenses.point module

class caustics.lenses.point.Point(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the center of the lens', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the center of the lens', True] = None, Rein: Annotated[ArrayLike | float | None, 'Einstein radius of the lens', True] = None, parametrization: Literal['Rein', 'mass'] = 'Rein', s: Annotated[float, 'Softening parameter to prevent numerical instabilities'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: ThinLens

Class representing a point mass lens in strong gravitational lensing.

name

The name of the point lens.

Type:

str

cosmology

The cosmology used for calculations.

Type:

Cosmology

z_l

Redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

x-coordinate of the center of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

y-coordinate of the center of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

Rein

Einstein radius of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

Softening parameter to prevent numerical instabilities.

Unit: arcsec

Type:

float

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence (dimensionless surface mass density).

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The convergence (dimensionless surface mass density).

Unit: unitless

Return type:

ArrayLike

mass_to_rein(mass: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → ArrayLike

Convert mass to the Einstein radius.

Parameters:

mass (ArrayLike) –

The mass of the lens

Unit: solar mass

Returns:

The Einstein radius.

Unit: arcsec

Return type:

ArrayLike

property parametrization

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection angles.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

rein_to_mass(r: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → ArrayLike

Convert Einstein radius to mass.

Parameters:

r (ArrayLike) –

The Einstein radius.

Unit: arcsec

Returns:

The mass of the lens

Unit: solar mass

Return type:

ArrayLike

caustics.lenses.pseudo_jaffe module

class caustics.lenses.pseudo_jaffe.PseudoJaffe(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the center of the lens', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the center of the lens', True] = None, mass: Annotated[ArrayLike | float | None, 'Total mass of the lens', True, 'Msol'] = None, Rc: Annotated[ArrayLike | float | None, 'Core radius of the lens', True, 'arcsec'] = None, Rs: Annotated[ArrayLike | float | None, 'Scaling radius of the lens', True, 'arcsec'] = None, s: Annotated[float, 'Softening parameter to prevent numerical instabilities'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Class representing a Pseudo Jaffe lens in strong gravitational lensing, based on Eliasdottir et al 2007 and the lenstronomy source code.

name

The name of the Pseudo Jaffe lens.

Type:

string

cosmology

The cosmology used for calculations.

Type:

Cosmology

z_l

Redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

Redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

x-coordinate of the center of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

y-coordinate of the center of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

mass

Total mass of the lens (Msun).

Unit: Msun

Type:

Optional[Union[ArrayLike, float]]

Rc

Core radius of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

Rs

Scaling radius of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

Softening parameter to prevent numerical instabilities.

Unit: arcsec

Type:

float

static central_convergence(rho_0, Rc, Rs, critical_surface_density)

Compute the central convergence.

Parameters:

• rho_0 (ArrayLike) –

  Central mass density.

  Unit: Msun/Mpc^3

• Rc (ArrayLike) –

  Core radius of the lens (must be in Mpc).

  Unit: Mpc

• Rs (ArrayLike) –

  Scaling radius of the lens (must be in Mpc).

  Unit: Mpc

• cosmology (Cosmology) – The cosmology used for calculations.

Returns:

The central convergence.

Unit: unitless

Return type:

ArrayLike

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density, based on equation A6.

Parameters:

• x (ArrayLike) –

  x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate of the lens.

  Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

get_convergence_0(z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'])

mass_enclosed_2d(theta, mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'])

Calculate the mass enclosed within a two-dimensional radius. Using equation A10 from Eliasdottir et al 2007.

Parameters:

theta (ArrayLike) –

Radius at which to calculate enclosed mass (arcsec).

Unit: arcsec

Returns:

The mass enclosed within the given radius.

Unit: Msun

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential. This calculation is based on equation A18 from Eliasdottir et al 2007.

Parameters:

• x (ArrayLike) –

  x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate of the lens.

  Unit: arcsec

Returns:

The lensing potential (arcsec^2).

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – y-component of the deflection angle.

  Unit: arcsec

caustics.lenses.sie module

class caustics.lenses.sie.SIE(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, q: Annotated[ArrayLike | float | None, 'The axis ratio of the lens convergence', True] = None, phi: Annotated[ArrayLike | float | None, 'The orientation angle of the lens (position angle)', True] = None, Rein: Annotated[ArrayLike | float | None, 'The Einstein radius of the lens', True] = None, parametrization: Literal['Rein', 'velocity_dispersion'] = 'Rein', sigma_v: ArrayLike | float | None = None, angle_system: str = 'q_phi', e1: ArrayLike | float | None = None, e2: ArrayLike | float | None = None, c1: ArrayLike | float | None = None, c2: ArrayLike | float | None = None, s: Annotated[float, 'The core radius of the lens'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: Angle_Mixin, ThinLens

A class representing a Singular Isothermal Ellipsoid (SIE) strong gravitational lens model. This model is based on Keeton 2001, which can be found at https://arxiv.org/abs/astro-ph/0102341.

name

The name of the lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

z_l

The redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

The x-coordinate of the lens center.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

The y-coordinate of the lens center.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

q

The axis ratio of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

phi

The orientation angle of the lens (position angle).

Unit: radians

Type:

Optional[Union[ArrayLike, float]]

Rein

The Einstein radius of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

The core radius of the lens (defaults to 0.0).

Unit: arcsec

Type:

float

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

property parametrization: str

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the physical deflection angle.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the deflection angle.

  Unit: arcsec

caustics.lenses.singleplane module

class caustics.lenses.singleplane.SinglePlane(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], lenses: Tuple[ThinLens], name: Annotated[str | None, 'Name of the lens model'] = None, z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None)

Bases: ThinLens

A class for combining multiple thin lenses into a single lensing plane. This model inherits from the base ThinLens class.

name

The name of the single plane lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

lenses

A list of ThinLens objects that are being combined into a single lensing plane.

Type:

List[ThinLens]

convergence(x: ArrayLike, y: ArrayLike) → ArrayLike

Calculate the total projected mass density by summing the mass densities of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total projected mass density.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike) → ArrayLike

Compute the total lensing potential by summing the lensing potentials of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike) → tuple[ArrayLike, ArrayLike]

Calculate the total deflection angle by summing the deflection angles of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the deflection angle.

  Unit: arcsec

caustics.lenses.sis module

class caustics.lenses.sis.SIS(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, Rein: Annotated[ArrayLike | float | None, 'The Einstein radius of the lens', True] = None, s: Annotated[float, 'A smoothing factor'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

A class representing the Singular Isothermal Sphere (SIS) model. This model inherits from the base ThinLens class.

name

The name of the SIS lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

z_l

The lens redshift.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The source redshift.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

The x-coordinate of the lens center.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

The y-coordinate of the lens center.

Type:

Optional[Union[ArrayLike, float]]

Rein

The Einstein radius of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

A smoothing factor, default is 0.0.

Unit: arcsec

Type:

float

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density of the SIS lens.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential of the SIS lens.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the deflection angle of the SIS lens.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle

  Unit: arcsec

caustics.lenses.tnfw module

class caustics.lenses.tnfw.TNFW(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'Center of lens position on x-axis', True, 'arcsec'] = None, y0: Annotated[ArrayLike | float | None, 'Center of lens position on y-axis', True, 'arcsec'] = None, mass: Annotated[ArrayLike | float | None, 'Mass of the lens', True, 'Msol'] = None, Rs: Annotated[ArrayLike | float | None, 'Scale radius of the TNFW lens', True, 'arcsec'] = None, tau: Annotated[ArrayLike | float | None, 'Truncation scale. Ratio of truncation radius to scale radius', True, 'rt/rs'] = None, s: Annotated[float, 'Softening parameter to avoid singularities at the center of the lens'] = 0.0, interpret_m_total_mass: Annotated[bool, "Indicates how to interpret the mass variable 'm'"] = True, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Truncated Navaro-Frenk-White profile

TNFW lens class. This class models a lens using the truncated Navarro-Frenk-White (NFW) profile. The NFW profile is a spatial density profile of dark matter halo that arises in cosmological simulations. It is truncated with an extra scaling term which smoothly reduces the density such that it does not diverge to infinity. This is based off the paper by Baltz et al. 2009:

https://arxiv.org/abs/0705.0682

https://ui.adsabs.harvard.edu/abs/2009JCAP…01..015B/abstract

Notes

The mass m in the TNFW profile corresponds to the total mass of the lens. This is different from the NFW profile where the mass m parameter corresponds to the mass within R200. If you prefer the “mass within R200” version you can set: interpret_m_total_mass = False on initialization of the object. However, the mass within R200 will be computed for an NFW profile, not a TNFW profile. This is in line with how lenstronomy interprets the mass parameter.

Parameters:

• name (string) – Name of the lens instance.

• cosmology (Cosmology) – An instance of the Cosmology class which contains information about the cosmological model and parameters.

• z_l (Optional[ArrayLike]) –

  Redshift of the lens.

  Unit: unitless

• z_s (Optional[ArrayLike]) –

  Redshift of the source.

  Unit: unitless

• x0 (Optional[ArrayLike]) –

  Center of lens position on x-axis.

  Unit: arcsec

• y0 (Optional[ArrayLike]) –

  Center of lens position on y-axis.

  Unit: arcsec

• mass (Optional[ArrayLike]) –

  Mass of the lens.

  Unit: Msun

• Rs (Optional[ArrayLike]) –

  Scale radius of the TNFW lens.

  Unit: arcsec

• tau (Optional[ArrayLike]) –

  Truncation scale. Ratio of truncation radius to scale radius.

  Unit: unitless

• s (float) –

  Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

  Unit: arcsec

• interpret_m_total_mass (boolean) – Indicates how to interpret the mass variable “m”. If true the mass is interpreted as the total mass of the halo (good because it makes sense). If false it is interpreted as what the mass would have been within R200 of a an NFW that isn’t truncated (good because it is easily compared with an NFW).

M0(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the reference mass. This is an abstract reference mass used internally in the equations from Baltz et al. 2009.

Returns:

The reference mass of the lens in Msun.

Unit: Msun

Return type:

ArrayLike

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

TNFW convergence as given in Baltz et al. 2009. This is unitless since it is Sigma(x) / Sigma_crit.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

Convergence at requested position.

Unit: unitless

Return type:

ArrayLike

get_concentration(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the concentration parameter “c” for a TNFW profile.

Parameters:

• z_l (ArrayLike) –

  Redshift of the lens.

  Unit: unitless

• x0 (ArrayLike) –

  Center of lens position on x-axis.

  Unit: arcsec

• y0 (ArrayLike) –

  Center of lens position on y-axis.

  Unit: arcsec

• mass (Optional[ArrayLike]) –

  Mass of the lens.

  Unit: Msun

• Rs (Optional[ArrayLike]) –

  Scale radius of the TNFW lens.

  Unit: arcsec

• tau (Optional[ArrayLike]) –

  Truncation scale. Ratio of truncation radius to scale radius.

  Unit: unitless

Returns:

The concentration parameter “c” for a TNFW profile.

Unit: unitless

Return type:

ArrayLike

get_scale_density(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the scale density of the lens.

Returns:

The scale density of the lens.

Unit: Msun/Mpc^3

Return type:

ArrayLike

get_truncation_radius(Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the truncation radius of the TNFW lens.

Returns:

The truncation radius of the lens.

Unit: arcsec

Return type:

ArrayLike

mass_enclosed_2d(r: ArrayLike, Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Total projected mass (Msun) within a radius r (arcsec).

Parameters:

r (ArrayLike) –

Radius within which to calculate the mass.

Unit: arcsec

Returns:

Integrated mass projected in infinite cylinder within radius r.

Unit: Msun

Return type:

ArrayLike

physical_deflection_angle(x: ArrayLike, y: ArrayLike, z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the physical deflection angle (arcsec) for this lens at the requested position. Note that the NFW/TNFW profile is more naturally represented as a physical deflection angle, this is easily internally converted to a reduced deflection angle.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

potential(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential. Note that this is not a unitless potential! This is the potential as given in Baltz et al. 2009.

TODO: convert to dimensionless potential.

Parameters:

• x (ArrayLike) –

  x-coordinate in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x, y, z_s, z_l)

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

caustics.lenses.utils module

caustics.lenses.utils.magnification(raytrace, x, y) → ArrayLike

Computes the magnification over a grid on the lensing plane. This is done by calling pixel_magnification for each point on the grid.

Parameters:

• raytrace (function) – A function that maps the lensing plane coordinates to the source plane coordinates.

• x (ArrayLike) –

  The x-coordinates on the lensing plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates on the lensing plane.

  Unit: arcsec

Returns:

A tensor representing the magnification at each point on the grid.

Unit: unitless

Return type:

ArrayLike

caustics.lenses.utils.pixel_jacobian(raytrace, x, y) → Tuple[Tuple[ArrayLike, ArrayLike], Tuple[ArrayLike, ArrayLike]]

Computes the Jacobian matrix of the partial derivatives of the image position with respect to the source position (\(\partial eta / \partial heta\)). This is done at a single point on the lensing plane.

Parameters:

• raytrace (function) – A function that maps the lensing plane coordinates to the source plane coordinates.

• x (ArrayLike) –

  The x-coordinate on the lensing plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lensing plane.

  Unit: arcsec

Returns:

• The Jacobian matrix of the image position with respect

• to the source position at the given point. – Unit: unitless

caustics.lenses.utils.pixel_magnification(raytrace, x, y) → ArrayLike

Computes the magnification at a single point on the lensing plane. The magnification is derived from the determinant of the Jacobian matrix of the image position with respect to the source position.

Parameters:

• raytrace (function) – A function that maps the lensing plane coordinates to the source plane coordinates.

• x (ArrayLike) –

  The x-coordinate on the lensing plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lensing plane.

  Unit: arcsec

Returns:

The magnification at the given point on the lensing plane.

Unit: unitless

Return type:

ArrayLike

Module contents

class caustics.lenses.BatchedPlane(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], lens: ThinLens, name: Annotated[str | None, 'Name of the lens model'] = None, z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, chunk_size: int | None = None)

Bases: ThinLens

A class for combining multiple thin lenses into a single lensing plane. It is assumed that the lens parameters will have a batch dimension, internally this class will vmap over the batch dimension and return the combined lensing quantity. This class can only handle a single lens type, if you want to combine different lens types, use the SinglePlane class.

name

The name of the single plane lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

lens

A ThinLens object that will be vmapped over into a single lensing plane.

Type:

ThinLens

convergence(x: ArrayLike, y: ArrayLike, lens_params, lens_dims) → ArrayLike

Calculate the total projected mass density by summing the mass densities of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total projected mass density.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, lens_params, lens_dims) → ArrayLike

Compute the total lensing potential by summing the lensing potentials of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, lens_params, lens_dims) → tuple[ArrayLike, ArrayLike]

Calculate the total deflection angle by summing the deflection angles of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the deflection angle.

  Unit: arcsec

class caustics.lenses.EPL(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the lens center', True] = None, q: Annotated[ArrayLike | float | None, 'Axis ratio of the lens', True] = None, phi: Annotated[ArrayLike | float | None, 'Position angle of the lens', True] = None, Rein: Annotated[ArrayLike | float | None, 'Einstein radius of the lens', True] = None, t: Annotated[ArrayLike | float | None, 'Power law slope (`gamma-1`) of the lens', True] = None, angle_system: str = 'q_phi', e1: ArrayLike | float | None = None, e2: ArrayLike | float | None = None, c1: ArrayLike | float | None = None, c2: ArrayLike | float | None = None, s: Annotated[float, 'Softening length for the elliptical power-law profile'] = 0.0, n_iter: Annotated[int, 'Number of iterations for the iterative solver'] = 18, chunk_size: Annotated[int | None, 'Number of chunks for the iterative solver'] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: Angle_Mixin, ThinLens

Elliptical power law (EPL, aka singular power-law ellipsoid) profile.

This class represents a thin gravitational lens model with an elliptical power law profile. The lensing equations are solved iteratively using an approach based on Tessore et al. 2015.

n_iter

Number of iterations for the iterative solver.

Type:

int

chunk_size

Number of iterations to do in parallel for the iterative solver.

Type:

int

s

Softening length for the elliptical power-law profile.

Type:

float

Unit: arcsec

Parameters:

• z_l (Optional[Union[ArrayLike, float]]) –

  This is the redshift of the lens. In the context of gravitational lensing, the lens is the galaxy or other mass distribution that is bending the light from a more distant source.

  Unit: unitless

• y0 (x0 and) –

  These are the coordinates of the lens center in the lens plane. The lens plane is the plane perpendicular to the line of sight in which the deflection of light by the lens is considered.

  Unit: arcsec

• q (Optional[Union[ArrayLike, float]]) –

  This is the axis ratio of the lens, i.e., the ratio of the minor axis to the major axis of the elliptical lens.

  Unit: unitless

• phi (Optional[Union[ArrayLike, float]]) –

  This is the orientation of the lens on the sky, typically given as an angle measured counter-clockwise from some reference direction.

  Unit: radians

• Rein (Optional[Union[ArrayLike, float]]) –

  The Einstein radius of the lens, exact at q=1.0.

  Unit: arcsec

• t (Optional[Union[ArrayLike, float]]) –

  This is the power-law slope parameter of the lens model. In the context of the EPL model, t is equivalent to the gamma parameter minus one, where gamma is the power-law index of the radial mass distribution of the lens.

  Unit: unitless

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param'], t: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence of the lens, which describes the local density of the lens.

Parameters:

• x (ArrayLike) –

  X coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  Y coordinates in the lens plane.

  Unit: arcsec

Returns:

The convergence of the lens.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param'], t: Annotated[ArrayLike, 'Param'])

Compute the lensing potential of the lens.

Parameters:

• x (ArrayLike) –

  X coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  Y coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param'], t: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the reduced deflection angles of the lens.

Parameters:

• x (ArrayLike) –

  X coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  Y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle

  Unit: arcsec

class caustics.lenses.EnclosedMass(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], enclosed_mass: Callable, z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, q: Annotated[ArrayLike | float | None, 'The axis ratio of the lens', True] = None, phi: Annotated[ArrayLike | float | None, 'The position angle of the lens', True] = None, p: Annotated[ArrayLike | list[float] | None, 'parameters for the enclosed mass function', True] = None, s: Annotated[float, 'Softening parameter to prevent numerical instabilities'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: ThinLens

A class for representing a lens with an enclosed mass profile. This generic lens profile can represent any lens with a mass distribution that can be described by a function that returns the enclosed mass as a function of radius.

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], p: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the dimensionless convergence of the lens at a given position.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

• The dimensionless convergence at the given position. [ArrayLike]

• *Unit (unitless*)

physical_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], p: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the physical deflection angle of the lens at a given position.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

• The physical deflection angle at the given position. [ArrayLike, ArrayLike]

• *Unit (arcsec*)

potential(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

reduced_deflection_angle(x, y, z_s, z_l)

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

class caustics.lenses.ExternalShear(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'x-coordinate of the shear center in the lens plane', True] = None, y0: Annotated[ArrayLike | float | None, 'y-coordinate of the shear center in the lens plane', True] = None, gamma_1: Annotated[ArrayLike | float | None, 'Shear component in the x-direction', True] = None, gamma_2: Annotated[ArrayLike | float | None, 'Shear component in the y-direction', True] = None, parametrization: Literal['cartesian', 'angular'] = 'cartesian', s: Annotated[float, 'Softening length for the elliptical power-law profile'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: ThinLens

Represents an external shear effect in a gravitational lensing system.

name

Identifier for the lens instance.

Type:

str

cosmology

The cosmological model used for lensing calculations.

Type:

Cosmology

z_l

The redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0, y0

Coordinates of the shear center in the lens plane.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

gamma_1, gamma_2

Shear components.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

Notes

The shear components gamma_1 and gamma_2 represent an external shear, a gravitational distortion that can be caused by nearby structures outside of the main lens galaxy.

convergence(x: ArrayLike, y: ArrayLike) → ArrayLike

The convergence is undefined for an external shear.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

Convergence for an external shear.

Unit: unitless

Return type:

ArrayLike

Raises:

NotImplementedError – This method is not implemented as the convergence is not defined for an external shear.

property parametrization: str

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], gamma_1: Annotated[ArrayLike, 'Param'], gamma_2: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculates the lensing potential.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], gamma_1: Annotated[ArrayLike, 'Param'], gamma_2: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculates the reduced deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

class caustics.lenses.MassSheet(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'x-coordinate of the shear center in the lens plane', True] = None, y0: Annotated[ArrayLike | float | None, 'y-coordinate of the shear center in the lens plane', True] = None, kappa: Annotated[ArrayLike | float | None, 'Surface density', True] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Represents an external shear effect in a gravitational lensing system.

name

Identifier for the lens instance.

Type:

string

cosmology

The cosmological model used for lensing calculations.

Type:

Cosmology

z_l

The redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

x-coordinate of the shear center in the lens plane.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

y-coordinate of the shear center in the lens plane.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

kappa

Convergence. Surface density normalized by the critical surface density.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

convergence(x: ArrayLike, y: ArrayLike, kappa: Annotated[ArrayLike, 'Param']) → ArrayLike

Computes the convergence of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

Dimensionless convergence, normalized by the critical surface density at the lens plane

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], kappa: Annotated[ArrayLike, 'Param']) → ArrayLike

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], kappa: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculates the reduced deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

class caustics.lenses.Multiplane(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], lenses: Tuple[ThinLens], name: Annotated[str | None, 'Name of the lens model'] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None)

Bases: ThickLens

Class for handling gravitational lensing with multiple lens planes.

lenses list of ThinLens

List of thin lenses.

Parameters:

• name (string) – Name of the lens.

• cosmology (Cosmology) – Cosmological parameters used for calculations.

• lenses (list[ThinLens]) – List of thin lenses.

• z_s (ZType) – Redshift of the source.

effective_reduced_deflection_angle(x: ArrayLike, y: ArrayLike) → tuple[ArrayLike, ArrayLike]

ThickLens objects do not have a reduced deflection angle since the distance D_ls is undefined. Instead we define an effective reduced deflection angle by simply assuming the relation $lpha = heta - eta$ holds, where $lpha$ is the effective reduced deflection angle, $ heta$ are the observed angular coordinates, and $eta$ are the angular coordinates to the source plane.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

get_z_ls() → list[ArrayLike]

Get the redshifts of each lens in the multiplane.

Returns:

Redshifts of the lenses.

Unit: unitless

Return type:

List[ArrayLike]

raytrace(x: ArrayLike, y: ArrayLike) → tuple[ArrayLike, ArrayLike]

Calculate the angular source positions corresponding to the observer positions x,y. See Margarita et al. 2013 for the formalism from the GLAMER -II code: https://ui.adsabs.harvard.edu/abs/2014MNRAS.445.1954P/abstract

The primary equation used here is equation 18. With a slight correction it reads:

\[\vec{x}^{i+1} = \vec{x}^i + D_{i+1,i}\left[\vec{\theta} - \sum_{j=1}^{i}\bf{\alpha}^j(\vec{x}^j)\right]\]

As an initialization we set the physical positions at the first lensing plane to be \(\vec{\theta}D_{1,0}\) which is just propagation through regular space to the first plane. Note that \(\vec{\alpha}\) is a physical deflection angle. The equation above converts straightforwardly into a recursion formula:

\[\vec{x}^{i+1} = \vec{x}^i + D_{i+1,i}\vec{ heta}^{i} \vec{\theta}^{i+1} = \vec{\theta}^{i} - \alpha^i(\vec{x}^{i+1})\]

Here we set as initialization \(\vec{ heta}^0 = theta\) the observation angular coordinates and \(\vec{x}^0 = 0\) the initial physical coordinates (i.e. the observation rays come from a point at the observer). The indexing of \(\vec{x}^i\) and \(\vec{\theta}^i\) indicates the properties at the plane \(i\), and 0 means the observer, 1 is the first lensing plane (infinitesimally after the plane since the deflection has been applied), and so on. Note that in the actual implementation we start at \(\vec{x}^1\) and \(\vec{\theta}^0\) and begin at the second step in the recursion formula.

Parameters:

• x (ArrayLike) –

  angular x-coordinates in the image plane.

  Unit: arcsec

• y (ArrayLike) –

  angular y-coordinates in the image plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Reduced deflection angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Reduced deflection angle in the y-direction.

  Unit: arcsec

References

1. Margarita Petkova, R. Benton Metcalf, and Carlo Giocoli. 2014. GLAMER II: multiple-plane lensing. MNRAS 445, 1954-1966. DOI:https://doi.org/10.1093/mnras/stu1860

surface_density(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Calculate the projected mass density.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

Projected mass density.

Unit: Msun/Mpc^2

Return type:

ArrayLike

Raises:

NotImplementedError – This method is not yet implemented.

time_delay(x: ArrayLike, y: ArrayLike, shapiro_time_delay: bool = True, geometric_time_delay: bool = True) → ArrayLike

Compute the time delay of light caused by the lensing. This is based on equation 6.22 in Petters et al. 2001. For the time delay of a light path from the observer to the source, the following equation is used:

\Delta t = \sum_{i=1}^{N-1} \tau_{i,i+1} \left[ \frac{1}{2} \left( \vec{\alpha}^i \right)^2 - \beta_{i,i+1} \psi^i \right] \\
\tau_{i,j} = (1 + z_i) \frac{D_i D_{j}}{D_{i,j} c} \\
\beta_{i,j} = \frac{D_{i,j} D_s}{D_{j} D_{i,s}} \\

where \(\vec{\alpha}^i\) is the deflection angle at the i-th lens plane, \(\psi^i\) is the lensing potential at the i-th lens plane, \(D_i\) is the comoving distance to the i-th lens plane, \(D_{i,j}\) is the comoving distance between the i-th and j-th lens plane, \(D_s\) is the comoving distance to the source, and \(D_{i,s}\) is the comoving distance between the i-th lens plane and the source.

This performs the same ray tracing as the raytrace() method, but computes the time delay along the way.

Parameters:

• x (ArrayLike) –

  x-coordinates in the image plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the image plane.

  Unit: arcsec

• shapiro_time_delay (bool) – Whether to include the Shapiro time delay component.

• geometric_time_delay (bool) – Whether to include the geometric time delay component.

Returns:

Time delay caused by the lensing.

Unit: days

Return type:

ArrayLike

References

1. Petters A. O., Levine H., Wambsganss J., 2001, Singularity Theory and Gravitational Lensing. Birkhauser, Boston

2. McCully et al. 2014, A new hybrid framework to efficiently model lines of sight to gravitational lenses

class caustics.lenses.Multipole(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], m: Annotated[ArrayLike | int | tuple[int], 'The Multipole moment(s) m'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, a_m: Annotated[ArrayLike | float | None, 'The amplitude of the multipole', True] = None, phi_m: Annotated[ArrayLike | float | None, 'The orientation angle of the multipole', True] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Represents a multipole effect in a gravitational lensing system.

name

Identifier for the lens instance.

Type:

str

cosmology

The cosmological model used for lensing calculations.

Type:

Cosmology

m

Order of multipole(s).

Type:

Union[ArrayLike, int, tuple[int]]

z_l

The redshift of the lens.

Type:

Optional[Union[ArrayLike, float]]

x0, y0

Coordinates of the shear center in the lens plane.

Type:

Optional[Union[ArrayLike, float]]

a_m

Strength of multipole.

Type:

Optional[Union[ArrayLike, float]]

phi_m

Orientation of multipole.

Type:

Optional[Union[ArrayLike, float]]

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], a_m: Annotated[ArrayLike, 'Param'], phi_m: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density of the multipole.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• ArrayLike – The projected mass density.

  Unit: unitless

• Equation (B10) and (B3) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], a_m: Annotated[ArrayLike, 'Param'], phi_m: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential of the multiplane.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• ArrayLike – The lensing potential.

  Unit: arcsec^2

• Equation (B11) and (B3) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], a_m: Annotated[ArrayLike, 'Param'], phi_m: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the deflection angle of the multipole.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• Equation (B11) and (B12) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

to(device=None, dtype=None)

Move the lens to the specified device.

Parameters:

• device (optional) – The device to move the lens to.

• dtype (optional) – The data type to cast the lens to.

Returns:

The lens object.

Return type:

Multipole

class caustics.lenses.NFW(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the lens center', True] = None, mass: Annotated[ArrayLike | float | None, 'Mass of the lens', True] = None, c: Annotated[ArrayLike | float | None, 'Concentration parameter of the lens', True] = None, s: Annotated[float, 'Softening parameter to avoid singularities at the center of the lens'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

NFW lens class. This class models a lens using the Navarro-Frenk-White (NFW) profile. The NFW profile is a spatial density profile of dark matter halo that arises in cosmological simulations.

z_l

Redshift of the lens. Default is None.

Unit: unitless

Type:

Optional[ArrayLike]

z_s

Redshift of the source. Default is None.

Unit: unitless

Type:

Optional[ArrayLike]

x0

x-coordinate of the lens center in the lens plane. Default is None.

Unit: arcsec

Type:

Optional[ArrayLike]

y0

y-coordinate of the lens center in the lens plane. Default is None.

Unit: arcsec

Type:

Optional[ArrayLike]

mass

Mass of the lens. Default is None.

Unit: Msun

Type:

Optional[ArrayLike]

c

Concentration parameter of the lens. Default is None.

Unit: unitless

Type:

Optional[ArrayLike]

s

Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

Unit: arcsec

Type:

float

get_scale_radius()

Returns the scale radius of the lens.

get_scale_density()

Returns the scale density of the lens.

get_convergence_s()

Returns the dimensionless surface mass density of the lens.

deflection_angle()

Computes the deflection angle.

convergence()

Computes the convergence (dimensionless surface mass density).

potential()

Computes the lensing potential.

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence (dimensionless surface mass density).

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The convergence (dimensionless surface mass density).

Unit: unitless

Return type:

ArrayLike

get_scale_density(z_l: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the scale density of the lens.

Parameters:

• z_l (ArrayLike) –

  Redshift of the lens.

  Unit: unitless

• c (ArrayLike) –

  Concentration parameter of the lens.

  Unit: unitless

Returns:

The scale density of the lens in solar masses per Mpc cubed.

Unit: Msun/Mpc^3

Return type:

ArrayLike

get_scale_radius(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the scale radius of the lens.

Parameters:

• z_l (ArrayLike) –

  Redshift of the lens.

  Unit: unitless

• mass (ArrayLike) –

  Mass of the lens.

  Unit: Msun

• c (ArrayLike) –

  Concentration parameter of the lens.

  Unit: unitless

Returns:

The scale radius of the lens in Mpc.

Unit: Mpc

Return type:

ArrayLike

physical_deflection_angle(x: ArrayLike, y: ArrayLike, z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the physical deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the reduced deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the reduced deflection angle.

  Unit: arcsec

potential(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], c: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x, y, z_s, z_l)

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

class caustics.lenses.PixelatedConvergence(pixelscale: Annotated[float, 'pixelscale'], cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the center of the grid', True] = tensor(0.), y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the center of the grid', True] = tensor(0.), convergence_map: Annotated[ArrayLike | None, 'A 2D tensor representing the convergence map', True] = None, scale: Annotated[ArrayLike | None, 'A scale factor to multiply by the convergence map', True] = 1.0, shape: Annotated[tuple[int | None, ...], 'The shape of the convergence map'] = (None, None), convolution_mode: Annotated[Literal['fft', 'conv2d'], 'The convolution mode for calculating deflection angles and lensing potential'] = 'fft', use_next_fast_len: Annotated[bool, 'If True, adds additional padding to speed up the FFT by calling `scipy.fft.next_fast_len`'] = True, padding: Annotated[Literal['zero', 'circular', 'reflect', 'tile'], 'Specifies the type of padding'] = 'zero', window_kernel: Annotated[float, 'Amount of kernel to be windowed'] = 0.125, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], convergence_map: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence at the specified positions.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the convergence for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the convergence for.

  Unit: arcsec

Returns:

The convergence at the specified positions.

Unit: unitless

Return type:

ArrayLike

property convolution_mode

Get the convolution mode of the ConvergenceGrid object.

Returns:

The convolution mode, either “fft” or “conv2d”.

Return type:

string

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], convergence_map: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

Returns:

The lensing potential at the specified positions.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], convergence_map: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection angles at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

to(device=None, dtype=None)

Move the ConvergenceGrid object and all its tensors to the specified device and dtype.

Parameters:

• device (optional) – The target device to move the tensors to.

• dtype (optional) – The target data type to cast the tensors to.

class caustics.lenses.PixelatedDeflection(pixelscale: Annotated[float, 'pixelscale', True], cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the center of the grid', True] = tensor(0.), y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the center of the grid', True] = tensor(0.), deflection_map: Annotated[ArrayLike | None, 'A 3D tensor (2, nx, ny) representing the reduced deflection angle map', True] = None, shape: Annotated[tuple[int | None, ...], 'The shape of the deflection map'] = (2, None, None), name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

convergence(x, y, **kwargs)

Computes the convergence of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

Dimensionless convergence, normalized by the critical surface density at the lens plane

Unit: unitless

Return type:

ArrayLike

potential(x, y, **kwargs)

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], deflection_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection at the specified positions.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the convergence for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the convergence for.

  Unit: arcsec

Returns:

The deflection at the specified positions.

Unit: unitless

Return type:

ArrayLike

class caustics.lenses.PixelatedPotential(pixelscale: Annotated[float, 'pixelscale', True], cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the center of the grid', True] = tensor(0.), y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the center of the grid', True] = tensor(0.), potential_map: Annotated[ArrayLike | None, 'A 2D tensor representing the potential map', True] = None, shape: Annotated[tuple[int | None, ...], 'The shape of the potential map'] = (None, None), name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], potential_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence at the specified positions.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the convergence for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the convergence for.

  Unit: arcsec

Returns:

The convergence at the specified positions.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], potential_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the lensing potential for.

  Unit: arcsec

Returns:

The lensing potential at the specified positions.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], potential_map: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection angles at the specified positions using the given convergence map.

Parameters:

• x (ArrayLike) –

  The x-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinates of the positions to compute the deflection angles for.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

class caustics.lenses.Point(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the center of the lens', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the center of the lens', True] = None, Rein: Annotated[ArrayLike | float | None, 'Einstein radius of the lens', True] = None, parametrization: Literal['Rein', 'mass'] = 'Rein', s: Annotated[float, 'Softening parameter to prevent numerical instabilities'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: ThinLens

Class representing a point mass lens in strong gravitational lensing.

name

The name of the point lens.

Type:

str

cosmology

The cosmology used for calculations.

Type:

Cosmology

z_l

Redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

x-coordinate of the center of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

y-coordinate of the center of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

Rein

Einstein radius of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

Softening parameter to prevent numerical instabilities.

Unit: arcsec

Type:

float

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the convergence (dimensionless surface mass density).

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The convergence (dimensionless surface mass density).

Unit: unitless

Return type:

ArrayLike

mass_to_rein(mass: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → ArrayLike

Convert mass to the Einstein radius.

Parameters:

mass (ArrayLike) –

The mass of the lens

Unit: solar mass

Returns:

The Einstein radius.

Unit: arcsec

Return type:

ArrayLike

property parametrization

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the deflection angles.

Parameters:

• x (ArrayLike) –

  x-coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

rein_to_mass(r: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → ArrayLike

Convert Einstein radius to mass.

Parameters:

r (ArrayLike) –

The Einstein radius.

Unit: arcsec

Returns:

The mass of the lens

Unit: solar mass

Return type:

ArrayLike

class caustics.lenses.PseudoJaffe(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'X coordinate of the center of the lens', True] = None, y0: Annotated[ArrayLike | float | None, 'Y coordinate of the center of the lens', True] = None, mass: Annotated[ArrayLike | float | None, 'Total mass of the lens', True, 'Msol'] = None, Rc: Annotated[ArrayLike | float | None, 'Core radius of the lens', True, 'arcsec'] = None, Rs: Annotated[ArrayLike | float | None, 'Scaling radius of the lens', True, 'arcsec'] = None, s: Annotated[float, 'Softening parameter to prevent numerical instabilities'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Class representing a Pseudo Jaffe lens in strong gravitational lensing, based on Eliasdottir et al 2007 and the lenstronomy source code.

name

The name of the Pseudo Jaffe lens.

Type:

string

cosmology

The cosmology used for calculations.

Type:

Cosmology

z_l

Redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

Redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

x-coordinate of the center of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

y-coordinate of the center of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

mass

Total mass of the lens (Msun).

Unit: Msun

Type:

Optional[Union[ArrayLike, float]]

Rc

Core radius of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

Rs

Scaling radius of the lens (arcsec).

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

Softening parameter to prevent numerical instabilities.

Unit: arcsec

Type:

float

static central_convergence(rho_0, Rc, Rs, critical_surface_density)

Compute the central convergence.

Parameters:

• rho_0 (ArrayLike) –

  Central mass density.

  Unit: Msun/Mpc^3

• Rc (ArrayLike) –

  Core radius of the lens (must be in Mpc).

  Unit: Mpc

• Rs (ArrayLike) –

  Scaling radius of the lens (must be in Mpc).

  Unit: Mpc

• cosmology (Cosmology) – The cosmology used for calculations.

Returns:

The central convergence.

Unit: unitless

Return type:

ArrayLike

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density, based on equation A6.

Parameters:

• x (ArrayLike) –

  x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate of the lens.

  Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

get_convergence_0(z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'])

mass_enclosed_2d(theta, mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'])

Calculate the mass enclosed within a two-dimensional radius. Using equation A10 from Eliasdottir et al 2007.

Parameters:

theta (ArrayLike) –

Radius at which to calculate enclosed mass (arcsec).

Unit: arcsec

Returns:

The mass enclosed within the given radius.

Unit: Msun

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential. This calculation is based on equation A18 from Eliasdottir et al 2007.

Parameters:

• x (ArrayLike) –

  x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate of the lens.

  Unit: arcsec

Returns:

The lensing potential (arcsec^2).

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rc: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the deflection angle.

Parameters:

• x (ArrayLike) –

  x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – y-component of the deflection angle.

  Unit: arcsec

class caustics.lenses.SIE(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, q: Annotated[ArrayLike | float | None, 'The axis ratio of the lens convergence', True] = None, phi: Annotated[ArrayLike | float | None, 'The orientation angle of the lens (position angle)', True] = None, Rein: Annotated[ArrayLike | float | None, 'The Einstein radius of the lens', True] = None, parametrization: Literal['Rein', 'velocity_dispersion'] = 'Rein', sigma_v: ArrayLike | float | None = None, angle_system: str = 'q_phi', e1: ArrayLike | float | None = None, e2: ArrayLike | float | None = None, c1: ArrayLike | float | None = None, c2: ArrayLike | float | None = None, s: Annotated[float, 'The core radius of the lens'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None, **kwargs)

Bases: Angle_Mixin, ThinLens

A class representing a Singular Isothermal Ellipsoid (SIE) strong gravitational lens model. This model is based on Keeton 2001, which can be found at https://arxiv.org/abs/astro-ph/0102341.

name

The name of the lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

z_l

The redshift of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The redshift of the source.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

The x-coordinate of the lens center.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

The y-coordinate of the lens center.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

q

The axis ratio of the lens.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

phi

The orientation angle of the lens (position angle).

Unit: radians

Type:

Optional[Union[ArrayLike, float]]

Rein

The Einstein radius of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

The core radius of the lens (defaults to 0.0).

Unit: arcsec

Type:

float

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

property parametrization: str

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the physical deflection angle.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the deflection angle.

  Unit: arcsec

class caustics.lenses.SIS(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'The x-coordinate of the lens center', True] = None, y0: Annotated[ArrayLike | float | None, 'The y-coordinate of the lens center', True] = None, Rein: Annotated[ArrayLike | float | None, 'The Einstein radius of the lens', True] = None, s: Annotated[float, 'A smoothing factor'] = 0.0, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

A class representing the Singular Isothermal Sphere (SIS) model. This model inherits from the base ThinLens class.

name

The name of the SIS lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

z_l

The lens redshift.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

z_s

The source redshift.

Unit: unitless

Type:

Optional[Union[ArrayLike, float]]

x0

The x-coordinate of the lens center.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

y0

The y-coordinate of the lens center.

Type:

Optional[Union[ArrayLike, float]]

Rein

The Einstein radius of the lens.

Unit: arcsec

Type:

Optional[Union[ArrayLike, float]]

s

A smoothing factor, default is 0.0.

Unit: arcsec

Type:

float

convergence(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the projected mass density of the SIS lens.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential of the SIS lens.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], Rein: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Calculate the deflection angle of the SIS lens.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle

  Unit: arcsec

class caustics.lenses.SinglePlane(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], lenses: Tuple[ThinLens], name: Annotated[str | None, 'Name of the lens model'] = None, z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None)

Bases: ThinLens

A class for combining multiple thin lenses into a single lensing plane. This model inherits from the base ThinLens class.

name

The name of the single plane lens.

Type:

str

cosmology

An instance of the Cosmology class.

Type:

Cosmology

lenses

A list of ThinLens objects that are being combined into a single lensing plane.

Type:

List[ThinLens]

convergence(x: ArrayLike, y: ArrayLike) → ArrayLike

Calculate the total projected mass density by summing the mass densities of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total projected mass density.

Unit: unitless

Return type:

ArrayLike

potential(x: ArrayLike, y: ArrayLike) → ArrayLike

Compute the total lensing potential by summing the lensing potentials of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

The total lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x: ArrayLike, y: ArrayLike) → tuple[ArrayLike, ArrayLike]

Calculate the total deflection angle by summing the deflection angles of all individual lenses.

Parameters:

• x (ArrayLike) –

  The x-coordinate of the lens.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate of the lens.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – The x-component of the deflection angle.

  Unit: arcsec

• y_component (ArrayLike) – The y-component of the deflection angle.

  Unit: arcsec

class caustics.lenses.TNFW(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, x0: Annotated[ArrayLike | float | None, 'Center of lens position on x-axis', True, 'arcsec'] = None, y0: Annotated[ArrayLike | float | None, 'Center of lens position on y-axis', True, 'arcsec'] = None, mass: Annotated[ArrayLike | float | None, 'Mass of the lens', True, 'Msol'] = None, Rs: Annotated[ArrayLike | float | None, 'Scale radius of the TNFW lens', True, 'arcsec'] = None, tau: Annotated[ArrayLike | float | None, 'Truncation scale. Ratio of truncation radius to scale radius', True, 'rt/rs'] = None, s: Annotated[float, 'Softening parameter to avoid singularities at the center of the lens'] = 0.0, interpret_m_total_mass: Annotated[bool, "Indicates how to interpret the mass variable 'm'"] = True, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: ThinLens

Truncated Navaro-Frenk-White profile

TNFW lens class. This class models a lens using the truncated Navarro-Frenk-White (NFW) profile. The NFW profile is a spatial density profile of dark matter halo that arises in cosmological simulations. It is truncated with an extra scaling term which smoothly reduces the density such that it does not diverge to infinity. This is based off the paper by Baltz et al. 2009:

https://arxiv.org/abs/0705.0682

https://ui.adsabs.harvard.edu/abs/2009JCAP…01..015B/abstract

Notes

The mass m in the TNFW profile corresponds to the total mass of the lens. This is different from the NFW profile where the mass m parameter corresponds to the mass within R200. If you prefer the “mass within R200” version you can set: interpret_m_total_mass = False on initialization of the object. However, the mass within R200 will be computed for an NFW profile, not a TNFW profile. This is in line with how lenstronomy interprets the mass parameter.

Parameters:

• name (string) – Name of the lens instance.

• cosmology (Cosmology) – An instance of the Cosmology class which contains information about the cosmological model and parameters.

• z_l (Optional[ArrayLike]) –

  Redshift of the lens.

  Unit: unitless

• z_s (Optional[ArrayLike]) –

  Redshift of the source.

  Unit: unitless

• x0 (Optional[ArrayLike]) –

  Center of lens position on x-axis.

  Unit: arcsec

• y0 (Optional[ArrayLike]) –

  Center of lens position on y-axis.

  Unit: arcsec

• mass (Optional[ArrayLike]) –

  Mass of the lens.

  Unit: Msun

• Rs (Optional[ArrayLike]) –

  Scale radius of the TNFW lens.

  Unit: arcsec

• tau (Optional[ArrayLike]) –

  Truncation scale. Ratio of truncation radius to scale radius.

  Unit: unitless

• s (float) –

  Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

  Unit: arcsec

• interpret_m_total_mass (boolean) – Indicates how to interpret the mass variable “m”. If true the mass is interpreted as the total mass of the halo (good because it makes sense). If false it is interpreted as what the mass would have been within R200 of a an NFW that isn’t truncated (good because it is easily compared with an NFW).

M0(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the reference mass. This is an abstract reference mass used internally in the equations from Baltz et al. 2009.

Returns:

The reference mass of the lens in Msun.

Unit: Msun

Return type:

ArrayLike

convergence(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

TNFW convergence as given in Baltz et al. 2009. This is unitless since it is Sigma(x) / Sigma_crit.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

Convergence at requested position.

Unit: unitless

Return type:

ArrayLike

get_concentration(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the concentration parameter “c” for a TNFW profile.

Parameters:

• z_l (ArrayLike) –

  Redshift of the lens.

  Unit: unitless

• x0 (ArrayLike) –

  Center of lens position on x-axis.

  Unit: arcsec

• y0 (ArrayLike) –

  Center of lens position on y-axis.

  Unit: arcsec

• mass (Optional[ArrayLike]) –

  Mass of the lens.

  Unit: Msun

• Rs (Optional[ArrayLike]) –

  Scale radius of the TNFW lens.

  Unit: arcsec

• tau (Optional[ArrayLike]) –

  Truncation scale. Ratio of truncation radius to scale radius.

  Unit: unitless

Returns:

The concentration parameter “c” for a TNFW profile.

Unit: unitless

Return type:

ArrayLike

get_scale_density(z_l: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the scale density of the lens.

Returns:

The scale density of the lens.

Unit: Msun/Mpc^3

Return type:

ArrayLike

get_truncation_radius(Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Calculate the truncation radius of the TNFW lens.

Returns:

The truncation radius of the lens.

Unit: arcsec

Return type:

ArrayLike

mass_enclosed_2d(r: ArrayLike, Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Total projected mass (Msun) within a radius r (arcsec).

Parameters:

r (ArrayLike) –

Radius within which to calculate the mass.

Unit: arcsec

Returns:

Integrated mass projected in infinite cylinder within radius r.

Unit: Msun

Return type:

ArrayLike

physical_deflection_angle(x: ArrayLike, y: ArrayLike, z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Compute the physical deflection angle (arcsec) for this lens at the requested position. Note that the NFW/TNFW profile is more naturally represented as a physical deflection angle, this is easily internally converted to a reduced deflection angle.

Parameters:

• x (ArrayLike) –

  The x-coordinate on the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  The y-coordinate on the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

potential(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param'], x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], mass: Annotated[ArrayLike, 'Param'], Rs: Annotated[ArrayLike, 'Param'], tau: Annotated[ArrayLike, 'Param']) → ArrayLike

Compute the lensing potential. Note that this is not a unitless potential! This is the potential as given in Baltz et al. 2009.

TODO: convert to dimensionless potential.

Parameters:

• x (ArrayLike) –

  x-coordinate in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  y-coordinate in the lens plane.

  Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

reduced_deflection_angle(x, y, z_s, z_l)

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

class caustics.lenses.ThickLens(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], name: Annotated[str | None, 'Name of the lens model'] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None)

Bases: Lens

Base class for modeling gravitational lenses that cannot be treated using the thin lens approximation. It is an abstract class and should be subclassed for different types of lens models.

cosmology

An instance of a Cosmology class that describes the cosmological parameters of the model.

Type:

Cosmology

effective_convergence_curl(x: ArrayLike, y: ArrayLike, **kwargs) → ArrayLike

Use the curl of the effective reduced deflection angle vector field to compute an effective convergence which derives specifically from the curl of the deflection field. This field is purely a result of multiplane lensing and cannot occur in single plane lensing.

See: https://arxiv.org/pdf/2006.07383.pdf

effective_convergence_div(x: ArrayLike, y: ArrayLike, **kwargs) → ArrayLike

Using the divergence of the effective reduced delfection angle we can compute the divergence component of the effective convergence field. This field produces a single plane convergence field which reproduces as much of the deflection field as possible for a single plane.

See: https://arxiv.org/pdf/2006.07383.pdf see also the effective_convergence_curl method.

effective_reduced_deflection_angle(x: ArrayLike, y: ArrayLike, **kwargs) → tuple[ArrayLike, ArrayLike]

ThickLens objects do not have a reduced deflection angle since the distance D_ls is undefined. Instead we define an effective reduced deflection angle by simply assuming the relation $lpha = heta - eta$ holds, where $lpha$ is the effective reduced deflection angle, $ heta$ are the observed angular coordinates, and $eta$ are the angular coordinates to the source plane.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

jacobian_effective_deflection_angle(x: ArrayLike, y: ArrayLike, method='autograd', pixelscale=None, **kwargs) → tuple[tuple[ArrayLike, ArrayLike], tuple[ArrayLike, ArrayLike]]

Return the jacobian of the effective reduced deflection angle vector field. This equates to a (2,2) matrix at each (x,y) point.

method: autograd or fft

physical_deflection_angle(x: ArrayLike, y: ArrayLike, *args, **kwargs) → tuple[ArrayLike, ArrayLike]

Physical deflection angles are computed with respect to a lensing plane. ThickLens objects have no unique definition of a lens plane and so cannot compute a physical_deflection_angle

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y direction.

  Unit: arcsec

abstract raytrace(x: ArrayLike, y: ArrayLike, *args, **kwargs) → tuple[ArrayLike, ArrayLike]

Performs ray tracing by computing the angular position on the source plance associated with a given input observed angular coordinate x,y.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x (ArrayLike) – x coordinate ArrayLike of the ray-traced light rays

  Unit: arcsec

• y (ArrayLike) – y coordinate ArrayLike of the ray-traced light rays

  Unit: arcsec

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, **kwargs) → tuple[ArrayLike, ArrayLike]

ThickLens objects do not have a reduced deflection angle since the distance D_ls is undefined

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: unitless

abstract surface_density(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the projected mass density at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

The projected mass density at the given coordinates in units of solar masses per square Mpc.

Unit: Msun/Mpc^2

Return type:

ArrayLike

abstract time_delay(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the gravitational time delay at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

The gravitational time delay at the given coordinates.

Unit: seconds

Return type:

ArrayLike

class caustics.lenses.ThinLens(cosmology: Annotated[Cosmology, 'Cosmology object that encapsulates cosmological parameters and distances'], z_l: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, z_s: Annotated[ArrayLike | float | None, 'The redshift of an object in the lens system', True] = None, name: Annotated[str | None, 'Name of the lens model'] = None)

Bases: Lens

Base class for thin gravitational lenses.

This class provides an interface for thin gravitational lenses, i.e., lenses that can be modeled using the thin lens approximation. The class provides methods to compute several lensing quantities such as the deflection angle, convergence, potential, surface mass density, and gravitational time delay.

name

Name of the lens model.

Type:

string

cosmology

Cosmology object that encapsulates cosmological parameters and distances.

Type:

Cosmology

z_l

Redshift of the lens. Defaults to None.

Unit: unitless

Type:

(Optional[ArrayLike], optional)

abstract convergence(x: ArrayLike, y: ArrayLike, chunk_size: int | None = None, *args, **kwargs) → ArrayLike

Computes the convergence of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

Dimensionless convergence, normalized by the critical surface density at the lens plane

Unit: unitless

Return type:

ArrayLike

jacobian_deflection_angle(x: ArrayLike, y: ArrayLike, method='autograd', pixelscale=None, chunk_size: int | None = None) → tuple[tuple[ArrayLike, ArrayLike], tuple[ArrayLike, ArrayLike]]

Return the jacobian of the deflection angle vector. This equates to a (2,2) matrix at each (x,y) point.

method: autograd or fft

physical_deflection_angle(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → tuple[ArrayLike, ArrayLike]

Computes the physical deflection angle immediately after passing through this lens’s plane.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y-direction.

  Unit: arcsec

abstract potential(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike

Computes the gravitational lensing potential at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Gravitational lensing potential at the given coordinates in arcsec^2.

Unit: arsec^2

Return type:

ArrayLike

raytrace(x: ArrayLike, y: ArrayLike, **kwargs) → tuple[ArrayLike, ArrayLike]

Perform a ray-tracing operation by subtracting the deflection angles from the input coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

• x_component (ArrayLike) – Deflection Angle in x direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in y direction.

  Unit: arcsec

reduced_deflection_angle(x: ArrayLike, y: ArrayLike, chunk_size: int | None = None) → tuple[ArrayLike, ArrayLike]

Computes the reduced deflection angle of the lens at given coordinates [arcsec].

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• chunk_size (int) –

  Chunk size for the autograd computation.

  Unit: number

Returns:

• x_component (ArrayLike) – Deflection Angle in the x-direction.

  Unit: arcsec

• y_component (ArrayLike) – Deflection Angle in the y-direction.

  Unit: arcsec

surface_density(x: ArrayLike, y: ArrayLike, z_s: Annotated[ArrayLike, 'Param'], z_l: Annotated[ArrayLike, 'Param']) → ArrayLike

Computes the surface mass density of the lens at given coordinates.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

Returns:

Surface mass density at the given coordinates in solar masses per Mpc^2.

Unit: Msun/Mpc^2

Return type:

ArrayLike

time_delay(x: ArrayLike, y: ArrayLike, shapiro_time_delay: bool = True, geometric_time_delay: bool = True) → ArrayLike

Computes the gravitational time delay for light passing through the lens at given coordinates.

This time delay is induced by the photons traveling through a gravitational potential well (Shapiro time delay) plus the effect of the increased path length that the photons must traverse (geometric time delay). The main equation involved here is the following:

\[\Delta t = \frac{1 + z_l}{c} \frac{D_s}{D_l D_{ls}} \left[ \frac{1}{2}|\vec{\alpha}(\vec{\theta})|^2 - \psi(\vec{\theta}) \right]\]

where \(\vec{\alpha}(\vec{\theta})\) is the deflection angle, \(\psi(\vec{\theta})\) is the lensing potential, \(D_l\) is the comoving distance to the lens, \(D_s\) is the comoving distance to the source, and \(D_{ls}\) is the comoving distance between the lens and the source. In the above equation, the first term is the geometric time delay and the second term is the gravitational time delay.

Parameters:

• x (ArrayLike) –

  ArrayLike of x coordinates in the lens plane.

  Unit: arcsec

• y (ArrayLike) –

  ArrayLike of y coordinates in the lens plane.

  Unit: arcsec

• shapiro_time_delay (bool) – Whether to include the Shapiro time delay component.

• geometric_time_delay (bool) – Whether to include the geometric time delay component.

Returns:

Time delay at the given coordinates.

Unit: days

Return type:

ArrayLike

References

1. Irwin I. Shapiro (1964). “Fourth Test of General Relativity”. Physical Review Letters. 13 (26): 789-791

2. Refsdal, S. (1964). “On the possibility of determining Hubble’s parameter and the masses of galaxies from the gravitational lens effect”. Monthly Notices of the Royal Astronomical Society. 128 (4): 307-310.