caustics package

caustics package#

Subpackages#

Submodules#

caustics.angle_mixin module#

class caustics.angle_mixin.Angle_Mixin(*args, **kwargs)[source]#

Bases: object

property angle_system: str#

caustics.angle_mixin.c1c2_to_phi(c1, c2)[source]#

caustics.angle_mixin.c1c2_to_q(c1, c2)[source]#

caustics.angle_mixin.c1c2_to_qphi(c1, c2)[source]#

caustics.angle_mixin.e1e2_to_phi(e1, e2)[source]#

caustics.angle_mixin.e1e2_to_q(e1, e2)[source]#

caustics.angle_mixin.e1e2_to_qphi(e1, e2)[source]#

caustics.angle_mixin.qphi_to_c1c2(q, phi)[source]#

caustics.angle_mixin.qphi_to_e1e2(q, phi)[source]#

caustics.backend_obj module#

class caustics.backend_obj.Backend(backend=None)[source]#

Bases: object

abs(array)[source]#

all(array)[source]#

allclose(a, b, rtol=1e-05, atol=1e-08)[source]#

any(array)[source]#

arccos(array)[source]#

arccosh(array)[source]#

arcsin(array)[source]#

arcsinh(array)[source]#

arctan(array)[source]#

arctan2(y, x)[source]#

argmax(array, dim=None)[source]#

property array_type#

atan(array)[source]#

atanh(array)[source]#

atleast_1d(array)[source]#

property backend#

property bool#

conj(array)[source]#

cos(array)[source]#

cosh(array)[source]#

cumprod(array, dim=None)[source]#

diag(array)[source]#

dot(*arrays)[source]#

einsum(equation, *operands)[source]#

empty(shape, dtype=None, device=None)[source]#

exp(array)[source]#

eye(n, dtype=None, device=None)[source]#

property fft#

flip(array, dims)[source]#

property float32#

property float64#

floor(array)[source]#

property inf#

property int32#

is_finite(array)[source]#

isfinite(array)[source]#

isnan(array)[source]#

property linalg#

log(array)[source]#

log10(array)[source]#

maximum(a, b)[source]#

minimum(a, b)[source]#

property nan#

nan_to_num(array, posinf=None, neginf=None)[source]#

ones(shape, dtype=None, device=None)[source]#

ones_like(array, dtype=None)[source]#

outer(a, b)[source]#

property pi#

prod(array, dim=None)[source]#

round(array)[source]#

safe_log(array)[source]#

searchsorted(array, value)[source]#

setup_jax()[source]#

setup_torch()[source]#

sin(array)[source]#

sqrt(array)[source]#

tanh(array)[source]#

tile(array, dims)[source]#

where(condition, x, y)[source]#

zeros(shape, dtype=None, device=None)[source]#

zeros_like(array, dtype=None)[source]#

class caustics.backend_obj.TopKResult(values, indices)#

Bases: tuple

indices#: Alias for field number 1

values#: Alias for field number 0

caustics.constants module#

caustics.func module#

caustics.func.M0_scalemass_tnfw(Rs, c, critical_density, d_l, DELTA=200.0)[source]#

What M0 would be for an NFW

Parameters:

Rs (ArrayLike) –
The scale radius of the TNFW lens.

Unit: arcsec
c (ArrayLike) –
The concentration parameter of an NFW lens with the same parameters.

Unit: unitless
critical_density (ArrayLike) –
The critical density of the universe.

Unit: Msun / Mpc^3
d_l (ArrayLike) –
The angular diameter distance to the lens.

Unit: Mpc
DELTA (float) –
The overdensity parameter.

Unit: unitless

caustics.func.M0_totmass_tnfw(mass, tau)[source]#: Rearranged from Baltz et al. 2009 equation A.4

caustics.func.brightness_sersic(x0, y0, q, phi, n, Re, Ie, x, y, k, s=0.0)[source]#

caustics.func.build_kernels_pixelated_convergence(pixelscale, n_pix)[source]#

Build the kernels for the pixelated convergence.

Parameters:

pixelscale (float) –
The pixel scale of the convergence map.

Unit: arcsec/pixel
n_pix (int) –
The number of pixels in the convergence map.

Unit: number

Returns:

x_kernel (ArrayLike) – The x-component of the kernel.

Unit: unitless
y_kernel (ArrayLike) – The y-component of the kernel.

Unit: unitless

caustics.func.c1c2_to_qphi(c1, c2)[source]#

caustics.func.concentration_tnfw(mass, Rs, critical_density, d_l, DELTA=200.0)[source]#

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

Parameters:

mass (ArrayLike) –
The mass of the lens.

Unit: Msun
Rs (ArrayLike) –
The scale radius of the TNFW lens.

Unit: arcsec
critical_density (ArrayLike) –
The critical density of the universe.

Unit: Msun / Mpc^3
d_l (ArrayLike) –
The angular diameter distance to the lens.

Unit: Mpc
DELTA (float) –
The overdensity parameter.

Unit: unitless

Returns:

The concentration parameter “c” for a TNFW profile.

Unit: unitless

Return type:

ArrayLike

caustics.func.convergence_0_pseudo_jaffe(mass, Rc, Rs, d_l, critical_surface_density)[source]#

Compute the convergence (dimensionless surface mass density). This is rearranged from Eliasdottir et al 2007 equation A11.

Parameters:

mass (ArrayLike) –
Total mass of the lens (Msun).

Unit: Msun
Rc (ArrayLike) –
Core radius of the lens.

Unit: arcsec
Rs (ArrayLike) –
Scaling radius of the lens.

Unit: arcsec
d_l (ArrayLike) –
Distance to the lens.

Unit: Mpc
critical_surface_density (ArrayLike) –
Critical surface density of the universe at the lens redshift.

Unit: Msun / Mpc^2

Returns:

The convergence (dimensionless surface mass density) at the center of the pseudo jaffe.

Unit: unitless

Return type:

ArrayLike

caustics.func.convergence_epl(x0, y0, q, phi, Rein, t, x, y, s=0.0)[source]#

Calculate the reduced deflection angle.

See Tessore et al. 2015 equation 2.

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
q (ArrayLike) –
The axis ratio of the lens. Semi-minor over semi-major axis lengths.

Unit: unitless
phi (ArrayLike) –
The orientation angle of the lens (position angle).

Unit: radians
Rein (ArrayLike) –
The Einstein radius of the lens.

Unit: arcsec
t (ArrayLike) –
Power law slope (gamma-1) of the lens. If not provided, it is considered as a free parameter.

Unit: unitless
x (ArrayLike) –
The x-coordinate of the lens.

Unit: arcsec
y (ArrayLike) –
The y-coordinate of the lens.

Unit: arcsec
s (float) –
The core radius of the lens (defaults to 0.0).

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.func.convergence_mass_sheet(kappa, x)[source]#

Compute the lensing convergence. In the case of a mass sheet, this is just the convergence value mapped to the input shape.

Parameters:

kappa (Optional[Union[ArrayLike, float]]) –
Convergence. Surface density normalized by the critical surface density.

Unit: unitless
x (ArrayLike) –
The x-coordinate of the lens. Only used for shape and device.

Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

caustics.func.convergence_multipole(x0, y0, m, a_m, phi_m, x, y)[source]#

Compute the lensing convergence.

Parameters:

x (ArrayLike) – x-coordinates in the lens plane.
y (ArrayLike) – y-coordinates in the lens plane.
x0 (ArrayLike) – x-coordinate of the center of the lens.
y0 (ArrayLike) – y-coordinate of the center of the lens.
m (ArrayLike) – The multipole order(s).
a_m (ArrayLike) – The multipole amplitude(s).
phi_m (ArrayLike) – The multipole orientation(s).

Returns:

convergence (ArrayLike) – Lensing convergence.

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

caustics.func.convergence_nfw(critical_surface_density, critical_density, x0, y0, mass, c, x, y, d_l, DELTA=200.0, s=0.0)[source]#

Compute the convergence. This can be found in the Meneghetti Lecture notes equation 3.74.

Parameters:

critical_surface_density (ArrayLike) –
The critical surface density of the Universe at the appropriate redshift.

Unit: Msun/Mpc^2
critical_density (ArrayLike) –
The critical density of the Universe at the appropriate redshift.

Unit: Msun/Mpc^3
mass (ArrayLike) – The mass of the halo
c (Optional[ArrayLike]) –
Concentration parameter of the lens. Default is None.

Unit: unitless
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

Unit: arcsec

caustics.func.convergence_point(x0, y0, x, y)[source]#

Compute the convergence (dimensionless surface mass density). This follows essenitally by definition.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
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

caustics.func.convergence_pseudo_jaffe(x0, y0, mass, Rc, Rs, x, y, d_l, critical_surface_density, s=0.0)[source]#

Compute the convergence (dimensionless surface mass density). See Eliasdottir et al 2007 Equation A3.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
mass (ArrayLike) –
Total mass of the lens

Unit: Msun
Rc (ArrayLike) –
Core radius of the lens.

Unit: arcsec
Rs (ArrayLike) –
Scaling radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
d_l (ArrayLike) –
Distance to the lens.

Unit: Mpc
critical_surface_density (ArrayLike) –
Critical surface density of the universe at the lens redshift.

Unit: Msun / Mpc^2
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

caustics.func.convergence_sie(x0, y0, q, phi, Rein, x, y, s=0.0)[source]#

Calculate the projected mass density. This is converted from the SIS convergence definition.

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
q (ArrayLike) –
The axis ratio of the lens.

Unit: unitless
phi (ArrayLike) –
The orientation angle of the lens (position angle).

Unit: radians
Rein (ArrayLike) –
The Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
The x-coordinate of the lens.

Unit: arcsec
y (ArrayLike) –
The y-coordinate of the lens.

Unit: arcsec
s (float) –
The core radius of the lens (defaults to 0.0).

Unit: arcsec

Returns:

The projected mass density.

Unit: unitless

Return type:

ArrayLike

caustics.func.convergence_sis(x0, y0, Rein, x, y, s=0.0)[source]#

Compute the lensing convergence. See the Meneghetti lecture notes equation 3.44.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
Rein (ArrayLike) –
Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

Returns:

convergence – Lensing convergence.

Unit: unitless

Return type:

ArrayLike

caustics.func.convergence_tnfw(x0, y0, Rs, tau, x, y, critical_density, M0, d_l, s=0.0)[source]#

Compute the dimensionless convergence for the TNFW. See Baltz et al. 2009 equation A.8

Parameters

Unit: arcsec

y0: ArrayLike

The y-coordinate of the lens center.

Unit: arcsec

Rs: ArrayLike

The scale radius of the TNFW lens.

Unit: arcsec

tau: ArrayLike

The truncation scale. Ratio of truncation radius to scale radius.

Unit: unitless

x: ArrayLike

The x-coordinate in the lens plane.

Unit: arcsec

y: ArrayLike

The y-coordinate in the lens plane.

Unit: arcsec

M0: ArrayLike

The mass normalization constant. See M0_totmass_tnfw and M0_scalemass_tnfw.

Unit: Msun

d_l: ArrayLike

The angular diameter distance to the lens.

Unit: Mpc

s: float

Softening parameter to prevent numerical instabilities.

Unit: arcsec

caustics.func.e1e2_to_qphi(e1, e2)[source]#

caustics.func.forward_raytrace(s, raytrace, x0, y0, fov, n, epsilon, max_depth=25)[source]#

caustics.func.gamma_phi_to_gamma1(gamma, phi)[source]#

Convert the shear magnitude and angle to the gamma_1 component.

Parameters:

gamma (ArrayLike) –
The shear magnitude.

Unit: unitless
phi (ArrayLike) –
The shear angle.

Unit: radians

Returns:

The gamma_1 component of the shear.

Unit: unitless

Return type:

ArrayLike

caustics.func.gamma_phi_to_gamma2(gamma, phi)[source]#

Convert the shear magnitude and angle to the gamma_2 component.

Parameters:

gamma (ArrayLike) –
The shear magnitude.

Unit: unitless
phi (ArrayLike) –
The shear angle.

Unit: radians

Returns:

The gamma_2 component of the shear.

Unit: unitless

Return type:

ArrayLike

caustics.func.k_lenstronomy(n: ArrayLike) → ArrayLike[source]#

Computes the value of k for the Sersic profile, as used in the lenstronomy package.

Parameters:

n (ArrayLike) –

The Sersic index, which describes the degree of concentration of the source.

Unit: unitless

Returns:

k – The value of k for the Sersic profile.

Unit: unitless

Return type:

ArrayLike

caustics.func.k_sersic(n: ArrayLike) → ArrayLike[source]#

Computes the value of k for the Sersic profile.

Parameters:

n (ArrayLike) –

The Sersic index, which describes the degree of concentration of the source.

Unit: unitless

Returns:

k – The value of k for the Sersic profile.

Unit: unitless

Return type:

ArrayLike

caustics.func.mass_enclosed_2d_pseudo_jaffe(radius, mass, Rc, Rs, s=0.0)[source]#

Compute the mass enclosed within a given radius. See Eliasdottir et al 2007 equation A10.

Parameters:

radius (Optional[ArrayLike]) –
Radius at which to calculate enclosed mass (arcsec).

Unit: arcsec
mass (ArrayLike) –
Total mass of the lens

Unit: Msun
Rc (ArrayLike) –
Core radius of the lens.

Unit: arcsec
Rs (ArrayLike) –
Scaling radius of the lens.

Unit: arcsec

caustics.func.mass_enclosed_2d_tnfw(r, Rs, tau, M0)[source]#

Total projected mass (Msun) within a radius r (arcsec). Given in Baltz et al. 2009 equation A.11

Parameters:

r (ArrayLike) –
Radius at which to compute the enclosed mass.

Unit: arcsec
mass (ArrayLike) –
Mass of the lens.

Unit: Msun
Rs (ArrayLike) –
Scale radius of the TNFW lens.

Unit: arcsec
tau (ArrayLike) –
Truncation scale. Ratio of truncation radius to scale radius.

Unit: unitless

Returns:

Integrated mass projected in infinite cylinder within radius r.

Unit: Msun

Return type:

ArrayLike

caustics.func.mass_to_rein_point(M, d_ls, d_l, d_s)[source]#

Compute the Einstein radius of a point mass. See Meneghetti lecture notes equation 1.39

Parameters:

M (ArrayLike) –
Mass of the lens.

Unit: solar masses
d_ls (ArrayLike) –
Distance between the lens and the source.

Unit: Mpc
d_l (ArrayLike) –
Distance between the observer and the lens.

Unit: Mpc
d_s (ArrayLike) –
Distance between the observer and the source.

Unit: Mpc

Returns:

The Einstein radius.

Unit: arcsec

Return type:

ArrayLike

caustics.func.physical_deflection_angle_nfw(x0, y0, mass, c, critical_density, d_l, x, y, DELTA=200.0, s=0.0)[source]#

Compute the physical deflection angles. This is an expanded form of the Meneghetti notes equation 3.72

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
mass (ArrayLike) –
Mass of the lens. Default is None.

Unit: Msun
c (ArrayLike) –
Concentration parameter of the lens. Default is None.

Unit: unitless
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

Unit: arcsec

caustics.func.physical_deflection_angle_tnfw(x0, y0, Rs, tau, x, y, M0, d_l, s=0.0)[source]#

Compute the physical deflection angle for a TNFW profile. Converted from Baltz et al. 2009 equation A.18

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
Rs (ArrayLike) –
The scale radius of the TNFW lens.

Unit: arcsec
tau (ArrayLike) –
The truncation scale. Ratio of truncation radius to scale radius.

Unit: unitless
x (ArrayLike) –
The x-coordinate in the lens plane.

Unit: arcsec
y (ArrayLike) –
The y-coordinate in the lens plane.

Unit: arcsec
M0 (ArrayLike) –
The mass normalization constant. See M0_totmass_tnfw and M0_scalemass_tnfw.

Unit: Msun
d_l (ArrayLike) –
The angular diameter distance to the lens.

Unit: Mpc
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

caustics.func.physical_from_reduced_deflection_angle(ax, ay, d_s, d_ls)[source]#

Computes the physical deflection angle of the given the reduced deflection angles [arcsec].

Parameters:

ax (ArrayLike) –
ArrayLike of x axis reduced deflection angles in the lens plane.

Unit: arcsec
y (ArrayLike) –
ArrayLike of y axis reduced deflection angles in the lens plane.

Unit: arcsec
d_s (float) –
distance to the source.

Unit: Mpc
d_ls (float) –
distance from lens to source.

Unit: Mpc

Returns:

x_component (ArrayLike) – Physical deflection Angle in the x-direction.

Unit: arcsec
y_component (ArrayLike) – Physical deflection Angle in the y-direction.

Unit: arcsec

caustics.func.potential_epl(x0, y0, q, phi, Rein, t, x, y, n_iter, chunk_size)[source]#

Calculate the potential for the EPL as defined in Tessore et al. 2015 equation 15.

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
q (ArrayLike) –
The axis ratio of the lens. Semi-minor over semi-major axis lengths.

Unit: unitless
phi (ArrayLike) –
The orientation angle of the lens (position angle).

Unit: radians
Rein (ArrayLike) –
The Einstein radius of the lens.

Unit: arcsec
t (ArrayLike) –
Power law slope (gamma-1) of the lens. If not provided, it is considered as a free parameter.

Unit: unitless
x (ArrayLike) –
The x-coordinate of the lens.

Unit: arcsec
y (ArrayLike) –
The y-coordinate of the lens.

Unit: arcsec
n_iter (int) –
Number of iterations for the iterative solver.

Unit: number
chunk_size (int) –
Number of iterations to do in parallel for the iterative solver.

Unit: number

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.func.potential_external_shear(x0, y0, gamma_1, gamma_2, x, y)[source]#

Compute the lensing potential for an external shear field. Here we use the Meneghetti lecture notes equation 3.80

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
gamma_1 (ArrayLike) –
The shear component in the x-direction.

Unit: unitless
gamma_2 (ArrayLike) –
The shear component in the y-direction.

Unit: unitless
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

caustics.func.potential_mass_sheet(x0, y0, kappa, x, y)[source]#

Compute the lensing potential. Here we use the Meneghetti lecture notes equation 3.81.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
kappa (Optional[Union[ArrayLike, float]]) –
Convergence. Surface density normalized by the critical surface density.

Unit: unitless
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

caustics.func.potential_multipole(x0, y0, m, a_m, phi_m, x, y)[source]#

Compute the lensing potential.

Parameters:

x (ArrayLike) – x-coordinates in the lens plane.
y (ArrayLike) – y-coordinates in the lens plane.
x0 (ArrayLike) – x-coordinate of the center of the lens.
y0 (ArrayLike) – y-coordinate of the center of the lens.
m (ArrayLike) – The multipole order(s).
a_m (ArrayLike) – The multipole amplitude(s).
phi_m (ArrayLike) – The multipole orientation(s).

Returns:

potential (ArrayLike) – Lensing potential.

Unit: arcsec^2
Equation (B11) and (B3) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

caustics.func.potential_nfw(critical_surface_density, critical_density, x0, y0, mass, c, d_l, x, y, DELTA=200.0, s=0.0)[source]#

Compute the convergence. This can be found in the Meneghetti Lecture notes equation 3.70.

Parameters:

critical_surface_density (ArrayLike) –
The critical surface density of the Universe at the appropriate redshift.

Unit: Msun/Mpc^2
critical_density (ArrayLike) –
The critical density of the Universe at the appropriate redshift.

Unit: Msun/Mpc^3
mass (ArrayLike) – The mass of the halo
c (Optional[ArrayLike]) –
Concentration parameter of the lens. Default is None.

Unit: unitless
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to avoid singularities at the center of the lens. Default is 0.0.

Unit: arcsec

caustics.func.potential_pixelated_convergence(x0, y0, convergence_map, x, y, potential_kernel, pixelscale, fov, n_pix, padding, convolution_mode='fft')[source]#

Compute the lensing potential for a pixelated convergence map. This follows from the basic formulas for potential, namely that it is the convolution of the convergence with the logarithm of a vector pointing towards the origin. For more details see the Meneghetti lecture notes equation 2.31

Parameters:

x0 (float) –
The x-coordinate of the center of the lens.

Unit: arcsec
y0 (float) –
The y-coordinate of the center of the lens.

Unit: arcsec
convergence_map (ArrayLike) –
The pixelated convergence map.

Unit: unitless
x (ArrayLike) –
The x-coordinate in the lens plane at which to compute the deflection.

Unit: arcsec
y (ArrayLike) –
The y-coordinate in the lens plane at which to compute the deflection.

Unit: arcsec
potential_kernel (ArrayLike) –
The kernel for convolution.

Unit: unitless
pixelscale (float) –
The pixel scale of the convergence map.

Unit: arcsec/pixel
fov (float) –
The field of view of the convergence map.

Unit: arcsec
n_pix (int) –
The number of pixels in the convergence map.

Unit: number
padding (str) – The type of padding to use. Either “zero”, “reflect”, “circular”, or “tile”.
convolution_mode (str) – The mode of convolution to use. Either “fft” or “conv2d”.

caustics.func.potential_point(x0, y0, Rein, x, y, s=0.0)[source]#

Compute the lensing potential. See the Meneghetti lecture notes equation 3.3 for more detail.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
Rein (ArrayLike) –
Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

caustics.func.potential_pseudo_jaffe(x0, y0, mass, Rc, Rs, x, y, d_l, d_s, d_ls, s=0.0)[source]#

Compute the lensing potential for the pseudo jaffe lens. See Eliasdottir et al 2007 equation A18.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
mass (ArrayLike) –
Total mass of the lens

Unit: Msun
Rc (ArrayLike) –
Core radius of the lens.

Unit: arcsec
Rs (ArrayLike) –
Scaling radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
d_l (ArrayLike) –
Distance to the lens.

Unit: Mpc
d_s (ArrayLike) –
Distance to the source.

Unit: Mpc
d_ls (ArrayLike) –
Distance from the lens to the source.

Unit: Mpc
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

caustics.func.potential_sie(x0, y0, q, phi, Rein, x, y, s=0.0)[source]#

Compute the lensing potential. For more detail see Keeton 2002 equation 33, although our Rein is defined as $b/\sqrt(q)$ in Keeton’s notation.

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
q (ArrayLike) –
The axis ratio of the lens.

Unit: unitless
phi (ArrayLike) –
The orientation angle of the lens (position angle).

Unit: radians
Rein (ArrayLike) –
The Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
The x-coordinate of the lens.

Unit: arcsec
y (ArrayLike) –
The y-coordinate of the lens.

Unit: arcsec
s (float) –
The core radius of the lens (defaults to 0.0).

Unit: arcsec

Returns:

The lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

caustics.func.potential_sis(x0, y0, Rein, x, y, s=0.0)[source]#

Compute the lensing potential. See the Meneghetti lecture notes equation 3.45.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
Rein (ArrayLike) –
Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

Returns:

potential – Lensing potential.

Unit: arcsec^2

Return type:

ArrayLike

caustics.func.potential_tnfw(x0, y0, Rs, tau, x, y, M0, d_l, d_s, d_ls, s=0.0)[source]#

Compute the lensing potential for a TNFW profile. See Baltz et al. 2009 equation A.14

Parameters

Unit: arcsec

y0: ArrayLike

The y-coordinate of the lens center.

Unit: arcsec

Rs: ArrayLike

The scale radius of the TNFW lens.

Unit: arcsec

tau: ArrayLike

The truncation scale. Ratio of truncation radius to scale radius.

Unit: unitless

x: ArrayLike

The x-coordinate in the lens plane.

Unit: arcsec

y: ArrayLike

The y-coordinate in the lens plane.

Unit: arcsec

M0: ArrayLike

The mass normalization constant. See M0_totmass_tnfw and M0_scalemass_tnfw.

Unit: Msun

d_l: ArrayLike

The angular diameter distance to the lens.

Unit: Mpc

d_s: ArrayLike

The angular diameter distance to the source.

Unit: Mpc

d_ls: ArrayLike

The angular diameter distance between the lens and the source.

Unit: Mpc

s: float

Softening parameter to prevent numerical instabilities.

Unit: arcsec

caustics.func.qphi_to_c1c2(q, phi)[source]#

caustics.func.qphi_to_e1e2(q, phi)[source]#

caustics.func.reduced_deflection_angle_epl(x0, y0, q, phi, Rein, t, x, y, n_iter, chunk_size=None)[source]#

Calculate the reduced deflection angle. Given in Tessore et al. 2015 equation 13.

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
q (ArrayLike) –
The axis ratio of the lens. Semi-minor over semi-major axis lengths.

Unit: unitless
phi (ArrayLike) –
The orientation angle of the lens (position angle).

Unit: radians
Rein (ArrayLike) –
The Einstein radius of the lens.

Unit: arcsec
t (ArrayLike) –
Power law slope (gamma-1) of the lens. If not provided, it is considered as a free parameter.

Unit: unitless
x (ArrayLike) –
The x-coordinate of the lens.

Unit: arcsec
y (ArrayLike) –
The y-coordinate of the lens.

Unit: arcsec
n_iter (int) –
Number of iterations for the iterative solver.

Unit: number
chunk_size (int) –
Number of iterations to do in parallel for the iterative solver.

Unit: number

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.func.reduced_deflection_angle_external_shear(x0, y0, gamma_1, gamma_2, x, y)[source]#

Compute the reduced deflection angles for an external shear field. Here we use the Meneghetti lecture notes and take derivatives of equation 3.80

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
gamma_1 (ArrayLike) –
The shear component in the x-direction.

Unit: unitless
gamma_2 (ArrayLike) –
The shear component in the y-direction.

Unit: unitless
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

caustics.func.reduced_deflection_angle_mass_sheet(x0, y0, kappa, x, y)[source]#

Compute the reduced deflection angles. Here we use the Meneghetti lecture notes equation 3.84.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
kappa (Optional[Union[ArrayLike, float]]) –
Convergence. Surface density normalized by the critical surface density.

Unit: unitless
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

caustics.func.reduced_deflection_angle_multipole(x0, y0, m, a_m, phi_m, x, y)[source]#

Calculates the reduced deflection angle.

Parameters:

x (ArrayLike) – x-coordinates in the lens plane.
y (ArrayLike) – y-coordinates in the lens plane.
x0 (ArrayLike) – x-coordinate of the center of the lens.
y0 (ArrayLike) – y-coordinate of the center of the lens.
m (ArrayLike) – The multipole order(s).
a_m (ArrayLike) – The multipole amplitude(s).
phi_m (ArrayLike) – The multipole orientation(s).

Returns:

tuple[ArrayLike, ArrayLike] – The reduced deflection angles in the x and y directions.
Equation (B11) and (B12) https (//arxiv.org/pdf/1307.4220, Xu et al. 2014)

caustics.func.reduced_deflection_angle_pixelated_convergence(x0, y0, convergence_map, x, y, ax_kernel, ay_kernel, pixelscale, fov, n_pix, padding, convolution_mode='fft')[source]#

Compute the reduced deflection angle for a pixelated convergence map. This follows from the basic formulas for deflection angle, namely that it is the convolution of the convergence with a unit vector pointing towards the origin. For more details see the Meneghetti lecture notes equation 2.32

Parameters:

x0 (float) –
The x-coordinate of the center of the lens.

Unit: arcsec
y0 (float) –
The y-coordinate of the center of the lens.

Unit: arcsec
convergence_map (ArrayLike) –
The pixelated convergence map.

Unit: unitless
x (ArrayLike) –
The x-coordinate in the lens plane at which to compute the deflection.

Unit: arcsec
y (ArrayLike) –
The y-coordinate in the lens plane at which to compute the deflection.

Unit: arcsec
ax_kernel (ArrayLike) –
The x-component of the kernel for convolution.

Unit: unitless
ay_kernel (ArrayLike) –
The y-component of the kernel for convolution.

Unit: unitless
pixelscale (float) –
The pixel scale of the convergence map.

Unit: arcsec/pixel
fov (float) –
The field of view of the convergence map.

Unit: arcsec
n_pix (int) –
The number of pixels in the convergence map.

Unit: number
padding (str) – The type of padding to use. Either “zero”, “reflect”, “circular”, or “tile”.
convolution_mode (str) – The mode of convolution to use. Either “fft” or “conv2d”.

caustics.func.reduced_deflection_angle_point(x0, y0, Rein, x, y, s=0.0)[source]#

Compute the reduced deflection angles. See the Meneghetti lecture notes equation 3.1 for more detail.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
Rein (ArrayLike) –
Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to prevent numerical instabilities.

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.func.reduced_deflection_angle_pseudo_jaffe(x0, y0, mass, Rc, Rs, x, y, d_l, critical_surface_density, s=0.0)[source]#

Compute the reduced deflection angle. See Eliasdottir et al 2007 equation A19.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
mass (ArrayLike) –
Total mass of the lens

Unit: Msun
Rc (ArrayLike) –
Core radius of the lens.

Unit: arcsec
Rs (ArrayLike) –
Scaling radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
d_l (ArrayLike) –
Distance to the lens.

Unit: Mpc
critical_surface_density (ArrayLike) –
Critical surface density of the universe at the lens redshift.

Unit: Msun / Mpc^2
s (float) –
Softening parameter to prevent numerical instabilities.

Unit: arcsec

caustics.func.reduced_deflection_angle_sie(x0, y0, q, phi, Rein, x, y, s=0.0)[source]#

Calculate the physical deflection angle. For more detail see Keeton 2002 equations 34 and 35, although our Rein is defined as $b/\sqrt(q)$ in Keeton’s notation.

Parameters:

x0 (ArrayLike) –
The x-coordinate of the lens center.

Unit: arcsec
y0 (ArrayLike) –
The y-coordinate of the lens center.

Unit: arcsec
q (ArrayLike) –
The axis ratio of the lens.

Unit: unitless
phi (ArrayLike) –
The orientation angle of the lens (position angle).

Unit: radians
Rein (ArrayLike) –
The Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
The x-coordinate of the lens.

Unit: arcsec
y (ArrayLike) –
The y-coordinate of the lens.

Unit: arcsec
s (float) –
The core radius of the lens (defaults to 0.0).

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.func.reduced_deflection_angle_sis(x0, y0, Rein, x, y, s=0.0)[source]#

Compute the reduced deflection angles. See the Meneghetti lecture notes equation 3.46.

Parameters:

x0 (ArrayLike) –
x-coordinate of the center of the lens.

Unit: arcsec
y0 (ArrayLike) –
y-coordinate of the center of the lens.

Unit: arcsec
Rein (ArrayLike) –
Einstein radius of the lens.

Unit: arcsec
x (ArrayLike) –
x-coordinates in the lens plane.

Unit: arcsec
y (ArrayLike) –
y-coordinates in the lens plane.

Unit: arcsec
s (float) –
Softening parameter to prevent numerical instabilities.

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.func.reduced_from_physical_deflection_angle(ax, ay, d_s, d_ls)[source]#

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

Parameters:

ax (ArrayLike) –
ArrayLike of x axis physical deflection angles in the lens plane.

Unit: arcsec
y (ArrayLike) –
ArrayLike of y axis physical deflection angles in the lens plane.

Unit: arcsec
d_s (float) –
distance to the source.

Unit: Mpc
d_ls (float) –
distance from lens to source.

Unit: Mpc

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

caustics.func.rein_to_mass_point(r, d_ls, d_l, d_s)[source]#

Compute the Einstein radius of a point mass. See Meneghetti lecture notes equation 1.39

Parameters:

r (ArrayLike) –
Einstein radius of the lens.

Unit: arcsec
d_ls (ArrayLike) –
Distance between the lens and the source.

Unit: Mpc
d_l (ArrayLike) –
Distance between the observer and the lens.

Unit: Mpc
d_s (ArrayLike) –
Distance between the observer and the source.

Unit: Mpc

Returns:

The mass of the lens

Unit: solar masses

Return type:

ArrayLike

caustics.func.scale_density_tnfw(c, critical_density, DELTA=200.0)[source]#

caustics.func.sigma_v_to_rein_sie(sigma_v, dls, ds)[source]#

Convert the velocity dispersion to the Einstein radius. See equation 16.22 in Dynamics and Astrophysics of Galaxies by Jo Bovy

Parameters:

sigma_v (ArrayLike) –
The velocity dispersion of the lens.

Unit: km/s
dls (ArrayLike) –
The angular diameter distance between the lens and the source.

Unit: Mpc
ds (ArrayLike) –
The angular diameter distance between the observer and the source.

Unit: Mpc

Returns:

The Einstein radius.

Unit: arcsec

Return type:

ArrayLike

caustics.func.time_delay_arcsec2_to_days(d_l, d_s, d_ls, z_l)[source]#: Computes a scaling factor to use in time delay calculations which converts the time delay (i.e. potential and deflection angle squared terms) from arcsec^2 to units of days.

caustics.tests module#

caustics.tests.test(device=device(type='cpu'))[source]#

Run tests for caustics basic functionality. Run this function to ensure that caustics is working properly.

Simply call:

>>> import caustics
>>> caustics.test()
all tests passed!

To run the checks.

caustics.utils module#

caustics.utils.batch_lm(X, Y, f, C=None, epsilon=0.1, L=1.0, L_dn=11.0, L_up=9.0, max_iter=50, L_min=1e-09, L_max=1000000000.0, stopping=0.0001, f_args=(), f_kwargs={})[source]#

caustics.utils.bicubic_kernels(Z, d1, d2)[source]#: This is just a quick script to compute the necessary derivatives using finite differences. This is not the most accurate way to compute the derivatives, but it is good enough for most purposes.

caustics.utils.cluster_means(xs: ArrayLike, k: int, key=None)[source]#

Computes cluster means using the k-means++ initialization algorithm.

Parameters:

xs (ArrayLike) – A tensor of data points.
k (int) – The number of clusters.
key (Optional[Union[None, jax.random.key]]) – A jax.random.key if using the Jax backend.

Returns:

A tensor of cluster means.

Return type:

ArrayLike

caustics.utils.derotate(vx, vy, phi: ArrayLike | None = None)[source]#

Applies inverse rotation to the velocity components (vx, vy) using the rotation angle phi.

Parameters:

vx (ArrayLike) – ArrayLike containing the x-component of velocity.
vy (ArrayLike) – ArrayLike containing the y-component of velocity.
phi (Optional[ArrayLike], optional)) – ArrayLike containing the rotation angles. If None, no rotation is applied. Defaults to None.

Returns:

Tuple – Tuple containing the derotated x and y components of velocity.

Return type:

[ArrayLike, ArrayLike]

caustics.utils.flip_axis_ratio(q, phi)[source]#

Makes the value of ‘q’ positive, then swaps x and y axes if ‘q’ is larger than 1.

Parameters:

q (ArrayLike) – ArrayLike containing values to be processed.
phi (ArrayLike) – ArrayLike containing the phi values for the orientation of the axes.

Returns:

Tuple containing the processed ‘q’ and ‘phi’ ArrayLikes.

Return type:

Tuple[ArrayLike, ArrayLike]

caustics.utils.gaussian(pixelscale, nx, ny, sigma, upsample=1, dtype=torch.float32, device=None)[source]#

caustics.utils.gaussian_quadrature_grid(pixelscale, X, Y, quad_level=3)[source]#

Generates a 2D meshgrid for Gaussian quadrature based on the provided pixelscale and dimensions.

Parameters:

pixelscale (float) – The scale of the meshgrid in each dimension.
X (ArrayLike) – The x-coordinates of the pixel centers.
Y (ArrayLike) – The y-coordinates of the pixel centers.
quad_level (int, optional) – The number of quadrature points in each dimension. Default is 3.

Returns:

The generated meshgrid as a tuple of ArrayLikes.

Return type:

Tuple[ArrayLike, ArrayLike]

Example

Usage would look something like:: python

X, Y = meshgrid(pixelscale, nx, ny) Xs, Ys, weight = gaussian_quadrature_grid(pixelscale, X, Y, quad_level) F = your_brightness_function(Xs, Ys, other, parameters) res = gaussian_quadrature_integrator(F, weight)

caustics.utils.gaussian_quadrature_integrator(F: ArrayLike, weight: ArrayLike)[source]#

Performs a pixel-wise integration using Gaussian quadrature. It takes the brightness function evaluated at the quadrature points F and the quadrature weights weight as input. The result is the integrated brightness function at each pixel.

Parameters:

F (ArrayLike) – The brightness function evaluated at the quadrature points.
weight (ArrayLike) – The quadrature weights as provided by the get_pixel_quad_integrator_grid function.

Returns:

The integrated brightness function at each pixel.

Return type:

ArrayLike

Example

Usage would look something like:: python

X, Y = meshgrid(pixelscale, nx, ny) Xs, Ys, weight = gaussian_quadrature_grid(pixelscale, X, Y, quad_level) F = your_brightness_function(Xs, Ys, other, parameters) res = gaussian_quadrature_integrator(F, weight)

caustics.utils.interp1d(x: ArrayLike, y: ArrayLike, xs: ArrayLike, extend: Literal['extrapolate', 'const', 'linear'] = 'extrapolate') → ArrayLike[source]#

Compute the 1D cubic spline interpolation for the given data points using PyTorch.

Parameters:

x (ArrayLike) – A 1D tensor representing the x-coordinates of the known data points.
y (ArrayLike) – A 1D tensor representing the y-coordinates of the known data points.
xs (ArrayLike) – A 1D tensor representing the x-coordinates of the positions where the cubic spline function should be evaluated.
extend ((str, optional)) – The method for handling extrapolation, either “const”, “extrapolate”, or “linear”. Default is “extrapolate”. “const”: Use the value of the last known data point for extrapolation. “linear”: Use linear extrapolation based on the last two known data points. “extrapolate”: Use cubic extrapolation of data.

Returns:

A 1D tensor representing the interpolated values at the specified positions (xs).

Return type:

ArrayLike

caustics.utils.interp2d(im: ArrayLike, x: ArrayLike, y: ArrayLike, method: Literal['linear', 'nearest'] = 'linear', padding_mode: str = 'zeros') → ArrayLike[source]#

Interpolates a 2D image at specified coordinates. Similar to torch.nn.functional.grid_sample with align_corners=False.

Parameters:

im (ArrayLike) – A 2D tensor representing the image.
x (ArrayLike) – A 0D or 1D tensor of x coordinates at which to interpolate.
y (ArrayLike) – A 0D or 1D tensor of y coordinates at which to interpolate.
method ((str, optional)) – Interpolation method. Either ‘nearest’ or ‘linear’. Defaults to ‘linear’.
padding_mode ((str, optional)) – Defines the padding mode when out-of-bound indices are encountered. Either ‘zeros’, ‘clamp’, or ‘extrapolate’. Defaults to ‘zeros’ which fills padded coordinates with zeros. The ‘clamp’ mode clamps the coordinates to the image boundaries (essentially taking the border values out to infinity). The ‘extrapolate’ mode extrapolates the outer linear interpolation beyond the last pixel boundary.

Raises:

ValueError – If im is not a 2D tensor.
ValueError – If x is not a 0D or 1D tensor.
ValueError – If y is not a 0D or 1D tensor.
ValueError – If padding_mode is not ‘extrapolate’ or ‘zeros’.
ValueError – If method is not ‘nearest’ or ‘linear’.

Returns:

ArrayLike with the same shape as x and y containing the interpolated values.

Return type:

ArrayLike

caustics.utils.interp3d(cu: ArrayLike, x: ArrayLike, y: ArrayLike, t: ArrayLike, method: Literal['linear', 'nearest'] = 'linear', padding_mode: Literal['zeros', 'extrapolate'] = 'zeros') → ArrayLike[source]#

Interpolates a 3D image at specified coordinates. Similar to torch.nn.functional.grid_sample with align_corners=False.

Parameters:

cu (ArrayLike) – A 3D tensor representing the cube.
x (ArrayLike) – A 0D or 1D tensor of x coordinates at which to interpolate.
y (ArrayLike) – A 0D or 1D tensor of y coordinates at which to interpolate.
t (ArrayLike) – A 0D or 1D tensor of t coordinates at which to interpolate.
method ((str, optional)) – Interpolation method. Either ‘nearest’ or ‘linear’. Defaults to ‘linear’.
padding_mode ((str, optional)) – Defines the padding mode when out-of-bound indices are encountered. Either ‘zeros’ or ‘extrapolate’. Defaults to ‘zeros’.

Raises:

ValueError – If cu is not a 3D tensor.
ValueError – If x is not a 0D or 1D tensor.
ValueError – If y is not a 0D or 1D tensor.
ValueError – If t is not a 0D or 1D tensor.
ValueError – If padding_mode is not ‘extrapolate’ or ‘zeros’.
ValueError – If method is not ‘nearest’ or ‘linear’.

Returns:

ArrayLike with the same shape as x and y containing the interpolated values.

Return type:

ArrayLike

caustics.utils.interp_bicubic(x, y, Z, dZ1=None, dZ2=None, dZ12=None, get_Y: bool = True, get_dY: bool = False, get_ddY: bool = False)[source]#

Compute bicubic interpolation of a 2D grid at arbitrary locations. This will smoothly interpolate a grid of points, including smooth first derivatives and smooth cross derivative (d^2Y/dxdy). For the derivatives, continuity is enforced, though the transition may be sharp as higher order derivatives are not considered.

The interpolation requires knowing the values of the first derivative in each axis and the cross derivative. If these are not provided, they will be estimated using central differences. For this function, the derivatives should be provided in pixel units. The interpolation will be more accurate if an analytic value is available for the derivatives.

See Numerical Recipes in C, Chapter 3 (specifically: “Higher Order for Smoothness: Bicubic Interpolation”) for more details.

Parameters:

x (torch.ArrayLike) – x-coordinates of the points to interpolate. Must be a 0D or 1D tensor. It should be in (-1,1) fov units, meaning that -1 is the left edge of the left pixel, and 1 is the right edge of the right pixel.
y (torch.ArrayLike) – y-coordinates of the points to interpolate. Must be a 0D or 1D tensor. It should be in (-1,1) fov units, meaning that -1 is the bottom edge of the bottom pixel, and 1 is the top edge of the top pixel.
Z (torch.ArrayLike) – 2D grid of values to interpolate. The first axis corresponds to the y-axis and the second axis to the x-axis. The values in Z correspond to pixel center values, so Z[0,0] is the value at the center of the bottom left corner pixel of the grid. The grid should be at least 2x2 so the bicubic interpolation can go between the values.
dZ1 (torch.ArrayLike or None) – First derivative of Z along the x-axis. If None, it will be estimated using central differences. Note that the derivative should be computed in pixel units, meaning that the distance from one pixel to the next is considered “1” in these units.
dZ2 (torch.ArrayLike or None) – First derivative of Z along the y-axis. If None, it will be estimated using central differences. Note that the derivative should be computed in pixel units, meaning that the distance from one pixel to the next is considered “1” in these units.
dZ12 (torch.ArrayLike or None) – Second derivative of Z along both axes. If None, it will be estimated using central differences. Note that the derivative should be computed in pixel units, meaning that the distance from one pixel to the next is considered “1” in these units.
get_Y (bool) – Whether to return the interpolated values. This will add the estimated Y values to the return tuple
get_dY (bool) – Whether to return the interpolated first derivatives. This will add dY1 and dY2 to the return tuple
get_ddY (bool) – Whether to return the interpolated second derivatives. This will add dY12, dY11, and dY22 to the return tuple

Returns:

Y (torch.ArrayLike or None) – Interpolated values at the given locations. Only returned if get_Y is True
dY1 (torch.ArrayLike or None) – Interpolated first derivative along the x-axis. Only returned if get_dY is True
dY2 (torch.ArrayLike or None) – Interpolated first derivative along the y-axis. Only returned if get_dY is True
dY12 (torch.ArrayLike or None) – Interpolated second derivative along both axes. Only returned if get_ddY is True
dY11 (torch.ArrayLike or None) – Interpolated second derivative along the x-axis. Only returned if get_ddY is True
dY22 (torch.ArrayLike or None) – Interpolated second derivative along the y-axis. Only returned if get_ddY is True

caustics.utils.meshgrid(pixelscale, nx, ny=None, device=None, dtype=torch.float32) → Tuple[ArrayLike, ArrayLike][source]#

Generates a 2D meshgrid based on the provided pixelscale and dimensions.

Parameters:

pixelscale (float) – The scale of the meshgrid in each dimension.
nx (int) – The number of grid points along the x-axis.
ny (int) – The number of grid points along the y-axis.
device (optional) – The device on which to create the tensor. Defaults to None.
dtype (optional) – The desired data type of the tensor. Defaults to torch.float32.

Returns:

Tuple – The generated meshgrid as a tuple of ArrayLikes.

Return type:

[ArrayLike, ArrayLike]

caustics.utils.pixel_to_plane(i, j, crpix, CD, sip_powers=[], sip_coefs=[], crplane=None)[source]#

Convert pixel coordinates to a tangent plane using the WCS information. This matches the FITS convention for SIP transformations.

For more information see:

FITS World Coordinate System (WCS): https://fits.gsfc.nasa.gov/fits_wcs.html
Representations of world coordinates in FITS, 2002, by Geisen and Calabretta
The SIP Convention for Representing Distortion in FITS Image Headers, 2008, by Shupe and Hook

Parameters:

i (ArrayLike) – The first coordinate of the pixel in pixel units. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), simply ensure that crpix has the same convention.
j (ArrayLike) – The second coordinate of the pixel in pixel units. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), simply ensure that crpix has the same convention.
crpix (ArrayLike) – The reference pixel in pixel units, should be a shape (2,) tensor. This is the point that will be placed at crval in the world coordinates. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), simply ensure that i and j have the same convention.
CD (ArrayLike) – The CD matrix in degrees per pixel. This 2x2 matrix is used to convert from pixel to degree units and also handles rotation/skew.
sip_powers (ArrayLike) – The powers of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the powers in order i, j.
sip_coefs (ArrayLike) – The coefficients of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the coefficients in order delta_x, delta_y.
crplane (Optional[ArrayLike], optional) – The reference plane coordinates in degrees, should be a shape (2,) tensor. This is the point that will be placed at crpix in the pixel coordinates. If None, it is assumed to be (0, 0). Defaults to None.

Note

The representation of the SIP powers and coefficients assumes that the SIP polynomial will use the same orders for both the x and y coordinates. If this is not the case you may use zeros for the coefficients to ensure all polynomial combinations are evaluated. However, it is very common to have the same orders for both.

Note

While it is not perfect, an approximate inverse for the SIP distortion can be determined by taking the negative of the coefficients (and using the plane_to_pixel function).

Returns:: Tuple – Tuple containing the x and y tangent plane coordinates in degrees.
Return type:: [ArrayLike, ArrayLike]

caustics.utils.pixel_to_world(i, j, crpix, crval, CD, sip_powers=[], sip_coefs=[], crplane=None)[source]#

Convert pixel coordinates to world coordinates using the WCS information. This matches the FITS convention for SIP transformations.

For more information see:

FITS World Coordinate System (WCS): https://fits.gsfc.nasa.gov/fits_wcs.html
Representations of world coordinates in FITS, 2002, by Geisen and Calabretta
The SIP Convention for Representing Distortion in FITS Image Headers, 2008, by Shupe and Hook

Parameters:

i (ArrayLike) – The first coordinate of the pixel in pixel units. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), simply ensure that crpix has the same convention.
j (ArrayLike) – The second coordinate of the pixel in pixel units. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), simply ensure that crpix has the same convention.
crpix (ArrayLike) – The reference pixel in pixel units, should be a shape (2,) tensor. This is the point that will be placed at crval in the world coordinates. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), simply ensure that i and j have the same convention.
crval (ArrayLike) – The reference world coordinates in degrees, should be a shape (2,) tensor. This is the point that will be placed at crpix in the pixel coordinates.
CD (ArrayLike) – The CD matrix in degrees per pixel. This 2x2 matrix is used to convert from pixel to world units and also handles rotation/skew.
sip_powers (ArrayLike) – The powers of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the powers in order i, j.
sip_coefs (ArrayLike) – The coefficients of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the coefficients in order delta_x, delta_y.
crplane (Optional[ArrayLike], optional) – The reference plane coordinates in degrees, should be a shape (2,) tensor. This is the point that will be placed at crpix in the pixel coordinates. If None, it is assumed to be (0, 0). Defaults to None.

Note

The representation of the SIP powers and coefficients assumes that the SIP polynomial will use the same orders for both the x and y coordinates. If this is not the case you may use zeros for the coefficients to ensure all polynomial combinations are evaluated. However, it is very common to have the same orders for both.

Note

While it is not perfect, an approximate inverse for the SIP distortion can be determined by taking the negative of the coefficients (and using the world_to_pixel function).

Returns:: Tuple – Tuple containing the right ascension and declination in degrees.
Return type:: [ArrayLike, ArrayLike]

caustics.utils.plane_to_pixel(px, py, crpix, CD, sip_powers=[], sip_coefs=[], crplane=None)[source]#

Convert tangent plane coordinates to pixel coordinates using the WCS information. This matches the FITS convention for SIP transformations.

For more information see:

FITS World Coordinate System (WCS): https://fits.gsfc.nasa.gov/fits_wcs.html
Representations of world coordinates in FITS, 2002, by Geisen and Calabretta
The SIP Convention for Representing Distortion in FITS Image Headers, 2008, by Shupe and Hook

Parameters:

px (ArrayLike) – The x-coordinate of the point on the tangent plane in degrees.
py (ArrayLike) – The y-coordinate of the point on the tangent plane in degrees.
crpix (ArrayLike) – The reference pixel in pixel units, should be a shape (2,) tensor. This is the point that will be placed at crval in the world coordinates. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), i and j will have the same convention.
CD (ArrayLike) – The CD matrix in degrees per pixel. This 2x2 matrix is used to convert from pixel to world units and also handles rotation/skew.
sip_powers (ArrayLike) – The powers of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the powers in order px, py.
sip_coefs (ArrayLike) – The coefficients of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the coefficients in order delta_x, delta_y.
crplane (Optional[ArrayLike], optional) – The reference plane coordinates in degrees, should be a shape (2,) tensor. This is the point that will be placed at crpix in the pixel coordinates. If None, it is assumed to be (0, 0). Defaults to None.

Note

The representation of the SIP powers and coefficients assumes that the SIP polynomial will use the same orders for both the x and y coordinates. If this is not the case you may use zeros for the coefficients to ensure all polynomial combinations are evaluated. However, it is very common to have the same orders for both.

Note

While it is not perfect, an approximate inverse for the SIP distortion can be determined by taking the negative of the coefficients (and using the pixel_to_plane function).

Returns:: Tuple – Tuple containing the i and j pixel coordinates (in pixel units).
Return type:: [ArrayLike, ArrayLike]

caustics.utils.plane_to_world_gnomonic(px, py, crval)[source]#

Perform a gnomonic projection from a tangent plane to the celestial sphere world coordinates.

Parameters:

px (ArrayLike) – The x-coordinate of the point on the tangent plane in degrees.
py (ArrayLike) – The y-coordinate of the point on the tangent plane in degrees.
crval (ArrayLike) – The celestial sphere world coordinates in degrees where the tangent plane meets the celestial sphere, should be a shape (2,) tensor. It is assumed that the tangent plane is centered at (0,0) for these coordinates. Thus crval matches the standard FITS convention.

Returns:

Tuple – Tuple containing the right ascension and declination in degrees.

Return type:

[ArrayLike, ArrayLike]

caustics.utils.quad(F: Callable, pixelscale: float, X: ArrayLike, Y: ArrayLike, args: Tuple = (), quad_level: int = 3)[source]#

Performs a pixel-wise integration on a function using Gaussian quadrature.

Parameters:

F (Callable) – The brightness function to be evaluated at the quadrature points. The function should take as input: F(X, Y, *args).
pixelscale (float) – The scale of each pixel.
X (ArrayLike) – The x-coordinates of the pixels.
Y (ArrayLike) – The y-coordinates of the pixels.
args (Optional[Tuple], optional) – Additional arguments to be passed to the brightness function, by default None.
quad_level (int, optional) – The level of quadrature to use, by default 3.

Returns:

The integrated brightness function at each pixel.

Return type:

ArrayLike

caustics.utils.safe_divide(num, denom)[source]#

Safely divides two tensors, returning zero where the denominator is zero.

Parameters:

num (ArrayLike) – The numerator tensor.
denom (ArrayLike) – The denominator tensor.

Returns:

The result of the division, with zero where the denominator was zero.

Return type:

ArrayLike

caustics.utils.safe_log(x)[source]#

Safely applies the logarithm to a tensor, returning zero where the tensor is zero.

Parameters:: x (ArrayLike) – The input tensor.
Returns:: The result of applying the logarithm, with zero where the input was zero.
Return type:: ArrayLike

caustics.utils.to_elliptical(x, y, q: ArrayLike)[source]#

Converts Cartesian coordinates to elliptical coordinates.

Parameters:

x (ArrayLike) – ArrayLike containing the x-coordinates.
y (ArrayLike) – ArrayLike containing the y-coordinates.
q (ArrayLike) – ArrayLike containing the elliptical parameters.

Returns:

Tuple – Tuple containing the x and y coordinates in elliptical form.

Return type:

ArrayLike, ArrayLike

caustics.utils.translate_rotate(x, y, x0, y0, phi: ArrayLike | None = None)[source]#

Translates and rotates the points (x, y) by subtracting (x0, y0) and applying rotation angle phi.

Parameters:

x (ArrayLike) – ArrayLike containing the x-coordinates.
y (ArrayLike) – ArrayLike containing the y-coordinates.
x0 (ArrayLike) – ArrayLike containing the x-coordinate translation values.
y0 (ArrayLike) – ArrayLike containing the y-coordinate translation values.
phi (Optional[ArrayLike], optional)) – ArrayLike containing the rotation angles. If None, no rotation is applied. Defaults to None.

Returns:

Tuple – Tuple containing the translated and rotated x and y coordinates.

Return type:

[ArrayLike, ArrayLike]

caustics.utils.vmap_n(func: Callable, depth: int = 1, in_dims: int | Tuple = 0, out_dims: int | Tuple[int, ...] = 0, randomness: str = 'error') → Callable[source]#

Transforms a function depth times using torch.vmap with the same arguments passed each time. Returns func transformed depth times by vmap, with the same arguments passed to vmap each time.

Parameters:

func (Callable) – The function to transform.
depth ((int, optional)) – The number of times to apply torch.vmap. Defaults to 1.
in_dims ((Union[int, Tuple], optional)) – The dimensions to vectorize over in the input. Defaults to 0.
out_dims ((Union[int, Tuple[int, ...]], optional):) – The dimensions to vectorize over in the output. Defaults to 0.
randomness ((str, optional)) – How to handle randomness. Defaults to ‘error’.

Raises:

ValueError – If depth is less than 1.

Returns:

Callable – The transformed function.
TODO (test.)

caustics.utils.vmap_reduce(func: ~typing.Callable, reduce_func: ~typing.Callable = <function <lambda>>, chunk_size: int | None = None, in_dims: ~typing.Tuple[int, ...] | ~typing.Dict[str, int] = (0, ), out_dims: int | ~typing.Tuple[int, ...] = 0, **kwargs) → Callable[source]#

Applies torch.vmap to func and then reduces the output using reduce_func along the appropriate dimensions. This saves on memory management if the dimension being reduced can cause the intermediate tensor (before reduction) to be large.

Note

The chunking and reduction is only “one level deep”. If the output of func is still large even after chunking, this function will not completely solve the problem. Essentially if the batch dimension divided by chunk_size is still larger than chunk_size, then you will still have a large intermediate tensor.

Parameters:

func (Callable) – The function to transform.
reduce_func (Callable) – The function to reduce the output of func.
in_dims (Tuple[int,...]) – The dimensions to vectorize over in the input.
out_dims (Tuple[int,...]) – The dimension to stack the output over.
chunk_size ((Optional[int])) – The size of the chunks to process. If None, the entire input is processed at once.
kwargs (Dict) – Additional keyword arguments to pass to torch.vmap.

Returns:

The reduced output.

Return type:

ArrayLike

caustics.utils.world_to_pixel(ra, dec, crpix, crval, CD, sip_powers=[], sip_coefs=[], crplane=None)[source]#

Convert world coordinates to pixel coordinates using the WCS information. This matches the FITS convention for SIP transformations.

For more information see:

FITS World Coordinate System (WCS): https://fits.gsfc.nasa.gov/fits_wcs.html
Representations of world coordinates in FITS, 2002, by Geisen and Calabretta
The SIP Convention for Representing Distortion in FITS Image Headers, 2008, by Shupe and Hook

Parameters:

ra (ArrayLike) – The right ascension in degrees.
dec (ArrayLike) – The declination in degrees.
crpix (ArrayLike) – The reference pixel in pixel units, should be a shape (2,) tensor. This is the point that will be placed at crval in the world coordinates. The origin may be either 0 indexed (python convention) or 1 indexed (FITS convention), i and j will have the same convention.
crval (ArrayLike) – The reference world coordinates in degrees, should be a shape (2,) tensor. This is the point that will be placed at crpix in the pixel coordinates (unless crplane is non-zero).
CD (ArrayLike) – The CD matrix in degrees per pixel. This 2x2 matrix is used to convert from pixel to world units and also handles rotation/skew.
powers (ArrayLike) – The powers of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the powers in order i, j.
coefs (ArrayLike) – The coefficients of the pixel coordinates for the SIP distortion, should be a shape (N orders, 2) tensor. N orders is the number of non-zero polynomial coefficients. The second axis has the coefficients in order delta_x, delta_y.

Note

The representation of the SIP powers and coefficients assumes that the SIP polynomial will use the same orders for both the x and y coordinates. If this is not the case you may use zeros for the coefficients to ensure all polynomial combinations are evaluated. However, it is very common to have the same orders for both.

Note

While it is not perfect, an approximate inverse for the SIP distortion can be determined by taking the negative of the coefficients (and using the pixel_to_world function).

Returns:: Tuple – Tuple containing the x and y pixel coordinates (in pixels).
Return type:: [ArrayLike, ArrayLike]

caustics.utils.world_to_plane_gnomonic(ra, dec, crval)[source]#

Perform a gnomonic projection from the celestial sphere world coordinates to a tangent plane.

Parameters:

ra (ArrayLike) – The right ascension in degrees.
dec (ArrayLike) – The declination in degrees.
crval (ArrayLike) – The celestial sphere world coordinates in degrees where the tangent plane meets the celestial sphere, should be a shape (2,) tensor. It is assumed that the tangent plane is centered at (0,0) for these coordinates. Thus crval matches the standard FITS convention.

Returns:

Tuple – Tuple containing the x and y tangent plane coordinates in degrees.

Return type:

[ArrayLike, ArrayLike]

Module contents#

class caustics.Angle_Mixin(*args, **kwargs)[source]#

Bases: object

property angle_system: str#

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

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

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

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

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.Cosmology(name: Annotated[str | None, 'Name of the cosmology'] = None)[source]#

Bases: Module

Abstract base class for cosmological models.

This class provides an interface for cosmological computations used in lensing such as comoving distance and critical surface density.

Distance

Unit: Mpc

Mass

Unit: Msun

name#

Name of the cosmological model.

Type:: str

angular_diameter_distance(z: ArrayLike) → ArrayLike[source]#

Compute the angular diameter distance to redshift z.

Parameters:

z (ArrayLike) –

The redshift.

Unit: unitless

Returns:

The angular diameter distance to each redshift.

Unit: Mpc

Return type:

ArrayLike

angular_diameter_distance_z1z2(z1: ArrayLike, z2: ArrayLike) → ArrayLike[source]#

Compute the angular diameter distance between two redshifts.

Parameters:

z1 (ArrayLike) –
The starting redshift.

Unit: unitless
z2 (ArrayLike) –
The ending redshift.

Unit: unitless

Returns:

The angular diameter distance between each pair of redshifts.

Unit: Mpc

Return type:

ArrayLike

abstract comoving_distance(z: ArrayLike, *args, **kwargs) → ArrayLike[source]#

Compute the comoving distance to redshift z.

Parameters:

z (ArrayLike) –

The redshift.

Unit: unitless

Returns:

The comoving distance to each redshift.

Unit: Mpc

Return type:

ArrayLike

comoving_distance_z1z2(z1: ArrayLike, z2: ArrayLike) → ArrayLike[source]#

Compute the comoving distance between two redshifts.

Parameters:

z1 (ArrayLike) –
The starting redshift.

Unit: unitless
z2 (ArrayLike) –
The ending redshift.

Unit: unitless

Returns:

The comoving distance between each pair of redshifts.

Unit: Mpc

Return type:

ArrayLike

abstract critical_density(z: ArrayLike) → ArrayLike[source]#

Compute the critical density at redshift z.

Parameters:

z (ArrayLike) –

The redshift.

Unit: unitless

Returns:

The critical density at each redshift.

Unit: Msun/Mpc^3

Return type:

ArrayLike

critical_surface_density(z_l: ArrayLike, z_s: ArrayLike) → ArrayLike[source]#

Compute the critical surface density between lens and source planes.

Parameters:

z_l (ArrayLike) –
The lens redshift.

Unit: unitless
z_s (ArrayLike) –
The source redshift.

Unit: unitless

Returns:

The critical surface density for each pair of lens and source redshifts.

Unit: Msun/Mpc^2

Return type:

ArrayLike

time_delay_distance(z_l: ArrayLike, z_s: ArrayLike) → ArrayLike[source]#

Compute the time delay distance between lens and source planes.

Parameters:

z_l (ArrayLike) –
The lens redshift.

Unit: unitless
z_s (ArrayLike) –
The source redshift.

Unit: unitless

Returns:

The time delay distance for each pair of lens and source redshifts.

Unit: Mpc

Return type:

ArrayLike

abstract transverse_comoving_distance(z: ArrayLike, *args, **kwargs) → ArrayLike[source]#

Compute the transverse comoving distance to redshift z (Mpc).

Parameters:

z (ArrayLike) –

The redshift.

Unit: unitless

Returns:

The transverse comoving distance to each redshift in Mpc.

Unit: Mpc

Return type:

ArrayLike

transverse_comoving_distance_z1z2(z1: ArrayLike, z2: ArrayLike) → ArrayLike[source]#

Compute the transverse comoving distance between two redshifts (Mpc).

Parameters:

z1 (ArrayLike) –
The starting redshift.

Unit: unitless
z2 (ArrayLike) –
The ending redshift.

Unit: unitless

Returns:

The transverse comoving distance between each pair of redshifts in Mpc.

Unit: Mpc

Return type:

ArrayLike

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

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

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

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

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

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

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

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

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

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

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

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

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

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.FlatLambdaCDM(h0: Annotated[ArrayLike | None, 'Hubble constant over 100', True] = 0.6766, critical_density_0: Annotated[ArrayLike | None, 'Critical density at z=0', True] = 127052815397.49832, Om0: Annotated[ArrayLike | None, 'Matter density parameter at z=0', True] = 0.30966, name: Annotated[str | None, 'Name of the cosmology'] = None)[source]#

Bases: Cosmology

Subclass of Cosmology representing a Flat Lambda Cold Dark Matter (LCDM) cosmology with no radiation.

comoving_distance(z: ArrayLike, h0: Annotated[ArrayLike, 'Param'], Om0: Annotated[ArrayLike, 'Param']) → ArrayLike[source]#

Calculate the comoving distance to redshift z.

Parameters:: z (ArrayLike) – Redshift.
Returns:: Comoving distance to redshift z.
Return type:: ArrayLike

critical_density(z: ArrayLike, critical_density_0: Annotated[ArrayLike, 'Param'], Om0: Annotated[ArrayLike, 'Param']) → ArrayLike[source]#

Calculate the critical density at redshift z.

Parameters:: z (ArrayLike) – Redshift.
Returns:: Critical density at redshift z.
Return type:: ArrayLike

hubble_distance(h0: Annotated[ArrayLike, 'Param'])[source]#

Calculate the Hubble distance.

Parameters:: h0 (ArrayLike) – Hubble constant.
Returns:: Hubble distance.
Return type:: ArrayLike

to(device=None, dtype=None)[source]#

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters:

device ((optional)) – The device to move the values to. Defaults to None.
dtype ((optional)) – The desired data type. Defaults to None.

transverse_comoving_distance(z: ArrayLike) → ArrayLike[source]#

Compute the transverse comoving distance to redshift z (Mpc).

Parameters:

z (ArrayLike) –

The redshift.

Unit: unitless

Returns:

The transverse comoving distance to each redshift in Mpc.

Unit: Mpc

Return type:

ArrayLike

class caustics.LensSource(lens: Annotated[Lens, 'caustics lens mass model object'], source: Annotated[Source, 'caustics light object which defines the background source'], pixelscale: Annotated[float, 'pixelscale of the sampling grid'], pixels_x: Annotated[int, 'number of pixels on the x-axis for the sampling grid'], lens_light: Annotated[Source | None, "caustics light object which defines the lensing object's light"] = None, pixels_y: Annotated[int | None, 'number of pixels on the y-axis for the sampling grid'] = None, upsample_factor: Annotated[int, 'Amount of upsampling to model the image'] = 1, quad_level: Annotated[int | None, 'sub pixel integration resolution'] = None, psf_mode: Annotated[Literal['fft', 'conv2d'], 'Mode for convolving psf'] = 'fft', psf_shape: Annotated[tuple[int, ...] | None, 'The shape of the psf'] = None, psf: Annotated[ArrayLike | list | None, 'An image to convolve with the scene', True] = [[1.0]], x0: Annotated[ArrayLike | float | None, 'center of the fov for the lens source image', True] = 0.0, y0: Annotated[ArrayLike | float | None, 'center of the fov for the lens source image', True] = 0.0, name: Annotated[str | None, 'Name of the simulator'] = 'sim')[source]#

Bases: Module

Lens image of a source.

Straightforward simulator to sample a lensed image of a source object. Constructs a sampling grid internally based on the pixelscale and gridding parameters. It can automatically upscale and fine sample an image. This is the most straightforward simulator to view the image if you already have a lens and source chosen.

Example usage:
import matplotlib.pyplot as plt
import caustics

cosmo = caustics.FlatLambdaCDM()
lens = caustics.lenses.SIS(cosmology=cosmo, x0=0.0, y0=0.0, th_ein=1.0)
source = caustics.sources.Sersic(x0=0.0, y0=0.0, q=0.5, phi=0.4, n=2.0, Re=1.0, Ie=1.0)
sim = caustics.sims.LensSource(
    lens, source, pixelscale=0.05, pixels_x=100, upsample_factor=2, z_s=1.0
)

img = sim()
plt.imshow(img, origin="lower")
plt.show()
lens: Lens
caustics lens mass model object

source: Source
caustics light object which defines the background source

pixelscale: float
pixelscale of the sampling grid.

pixels_x: int
number of pixels on the x-axis for the sampling grid

lens_light: Source, optional
caustics light object which defines the lensing object’s light

psf: ArrayLike, optional
An image to convolve with the scene. Note that if upsample_factor > 1 the psf must also be at the higher resolution.

pixels_y: Optional[int]
number of pixels on the y-axis for the sampling grid. If left as None then this will simply be equal to gridx

upsample_factor (default 1)
Amount of upsampling to model the image. For example upsample_factor = 2 indicates that the image will be sampled at double the resolution then summed back to the original resolution (given by pixelscale and gridx/y).

quad_level: int (default None)
sub pixel integration resolution. This will use Gaussian quadrature to sample the image at a higher resolution, then integrate the image back to the original resolution. This is useful for high accuracy integration of the image, but may increase memory usage and runtime.

e

name: string (default “sim”): a name for this simulator in the parameter DAG.

The simulator will automatically pad the image to half the PSF size to ensure valid convolution. This is done by default, but can be turned off by setting psf_pad = False. This is only relevant if you are using a PSF.
The upsample factor will increase the resolution of the image by the given factor. For example, upsample_factor = 2 will sample the image at double the resolution, then sum back to the original resolution. This is used when a PSF is provided at high resolution than the original image. Not that the when a PSF is used, the upsample_factor must equal the PSF upsampling level.
For arbitrary pixel integration accuracy using the quad_level parameter. This will use Gaussian quadrature to sample the image at a higher resolution, then integrate the image back to the original resolution. This is useful for high accuracy integration of the image, but is not recommended for large images as it will be slow. The quad_level and upsample_factor can be used together to achieve high accuracy integration of the image convolved with a PSF.
A Pixelated light source is defined by bilinear interpolation of the provided image. This means that sub-pixel integration is not required for accurate integration of the pixels. However, if you are using a PSF then you should still use upsample_factor (if your PSF is supersampled) to ensure that everything is sampled at the PSF resolution.

property pixels_x#

property pixels_y#

property pixelscale#

property psf_mode#

property psf_shape#

property quad_level#

to(device=None, dtype=None)[source]#

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters:

device ((optional)) – The device to move the values to. Defaults to None.
dtype ((optional)) – The desired data type. Defaults to None.

property upsample_factor#

class caustics.LightStack(light_models: Annotated[Tuple[Source], 'a list of light models to sum their brightnesses'], name: Annotated[str | None, 'Name of the source'] = None)[source]#

Bases: Source

LightStack is a subclass of the abstract class Source which takes the sum of multiple Source models to make a single brightness model.

light_models#

A list of light models to sum.

Type:: List[Source]

brightness(x, y, **kwargs)[source]#

Implements the brightness method for Sersic. The brightness at a given point is determined by the Sersic profile formula.

Parameters:

x (ArrayLike) –
The x-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
y (ArrayLike) –
The y-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec

Returns:

The brightness of the source at the given point(s). The output tensor has the same shape as x and y.

Unit: flux

Return type:

ArrayLike

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

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

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

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

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.Microlens(lens: Annotated[Lens, 'caustics lens mass model object'], source: Annotated[Source, 'caustics light object which defines the background source'], name: Annotated[str | None, 'Name of the simulator'] = 'sim')[source]#

Bases: Module

Computes the total flux from a microlens system within an fov.

Straightforward simulator to compute the total flux a lensed image of a source object within a given field of view. Constructs a sampling points internally based on the user settings.

Example usage:: python

import matplotlib.pyplot as plt import torch import caustics

cosmo = caustics.FlatLambdaCDM() lens = caustics.lenses.SIS(cosmology = cosmo, x0 = 0., y0 = 0., th_ein = 1.) source = caustics.sources.Sersic(x0 = 0., y0 = 0., q = 0.5, phi = 0.4, n = 2., Re = 1., Ie = 1.) sim = caustics.sims.Microlens(lens, source, z_s = 1.)

fov = torch.tensor([-1., 1., -1., 1.]) print(“Flux and uncertainty: “, sim(fov=fov))

lens#

caustics lens mass model object

Type:: Lens

source#

caustics light object which defines the background source

Type:: Source

name#

a name for this simulator in the parameter DAG.

Type:: string (default “sim”)

class caustics.Module(name: str | None = None, **kwargs)[source]#

Bases: Node, GetSetValues

Node to represent a simulation module in the graph.

The Module object is used to represent a simulation module in the graph. These are python objects that contain the calculations for a simulation, they also hold the Param objects that are used in the calculations. The Module object has additional functionality to manage the Param objects below it in the graph, it keeps track of all dynamic Param objects so that at runtime their values may be filled. The Module object manages its links to other nodes through attributes of the class.

Examples

Example of a nested pair of Module objects and how their @forward methods are called:

class MySim(Module):
    def __init__(self, a, b=None):
        super().__init__()
        self.a = a
        self.b = Param("b", b)

    @forward
    def myfunc(self, x, b=None):
        return x * self.a.otherfun(x) + b

class OtherSim(Module):
    def __init__(self, c=None):
        super().__init__()
        self.c = Param("c", c)

    @forward
    def otherfun(self, x, c = None):
        return x + c

othersim = OtherSim()
mysim = MySim(a=othersim)
#                       b                         c
params = [torch.tensor([1.0, 2.0]), torch.tensor([3.0, 4.0])]
result = mysim.myfunc(3.0, params=params)
# result is tensor([19.0, 23.0])

property all_params#

All parameters below this module in the DAG.

Returns:: Concatenation of static, dynamic, and pointer parameters.
Return type:: tuple of Param

clear_state()[source]#: Clear the active state _value for all params below this Module in the DAG. This should not be used by a user under normal circumstances.

property dynamic: bool#

Return True if the module has dynamic parameters as direct children.

Returns:: True if any direct children are dynamic parameters.
Return type:: bool

fill_kwargs(keys: tuple[str]) → dict[str, ArrayLike][source]#: Fill the kwargs for an @forward method with the values of the dynamic parameters. The requested keys are matched to names of Param objects owned by the Module. This should not be used by the user under normal circumstances.

fill_params(params: ArrayLike | Sequence | Mapping, dynamic=True)[source]#

Fill the dynamic/static parameters of the module with the input values from params.

Parameters:

params ((Union[ArrayLike, Sequence, Mapping])) – The input values to fill the dynamic parameters with. The input can be an ArrayLike, a Sequence, or a Mapping.
dynamic (bool) – Operate on dynamic parameters (True, default) or static parameters (False).

property graphviz_style#

property node_str: str#: Returns a string representation of the node for graph visualization.

param_order()[source]#

Return a human-readable string of dynamic parameter ordering.

Each line corresponds to a parameter group and lists the parameters in the format parent_name: param_name.

Returns:: Multi-line string describing the dynamic parameter order.
Return type:: str

remove_memo(memo)[source]#

Remove a memo string and propagate removal to all children.

Parameters:: memo (str) – The memo message to remove. The same propagation rules as add_memo apply.

property static: bool#

Return True if the module has no dynamic parameters as direct children.

Returns:: True if none of the direct children are dynamic parameters.
Return type:: bool

to_dynamic(children_only=True)[source]#

Change all parameters to dynamic parameters.

Parameters:: children_only ((bool, optional)) – If True, only convert the children of this module to dynamic. If False, convert all parameters in the graph below this module. Defaults to True.

to_static(children_only=True)[source]#

Change all parameters to static parameters.

Parameters:: children_only ((bool, optional)) – If True, only convert children of this module to static. If False, convert all parameters in the graph below this module. Defaults to True.

update_graph()[source]#: Maintain a tuple of dynamic, static, and pointer parameters at all points lower in the DAG.

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

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

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

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

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

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

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

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

Petters A. O., Levine H., Wambsganss J., 2001, Singularity Theory and Gravitational Lensing. Birkhauser, Boston
McCully et al. 2014, A new hybrid framework to efficiently model lines of sight to gravitational lenses

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

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

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

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

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

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

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()[source]#: Returns the scale radius of the lens.

get_scale_density()[source]#: 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()[source]#: Computes the convergence (dimensionless surface mass density).

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

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

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

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

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

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

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

Bases: Node

Node to represent a parameter in the graph.

The Param object is used to represent a parameter in the graph. During runtime this will represent a value which can be used in various calculations. The Param object can be set to a constant value (static); None meaning the value is to be provided at runtime (dynamic); another Param object meaning it will take on that value at runtime (pointer); or a function of other Param objects to be computed at runtime (also pointer, see user guides). These options allow users to flexibly set the behavior of the simulator.

Examples

Example making some Param objects:

p1 = Param("test", (1.0, 2.0)) # constant value, length 2 vector
p2 =Param("p2", None, (2,2)) # dynamic 2x2 matrix value
p3 = Param("p3", p1) # pointer to another parameter
p4 = Param("p4", lambda p: p.children["other"].value * 2) # arbitrary function of another parameter
p5 = Param("p5", valid=(0.0,2*pi), units="radians", cyclic=True) # parameter with metadata

Parameters:

name ((str)) – The name of the parameter.
value ((Optional[Union[ArrayLike, float, int]], optional)) – The value of the parameter. Defaults to None meaning dynamic.
shape ((Optional[tuple[int, ...]], optional)) – The shape of the parameter. Defaults to () meaning scalar.
cyclic ((bool, optional)) – Whether the parameter is cyclic, imposing periodic boundary conditions. Such as a rotation from 0 to 2pi. Defaults to False.
valid ((Optional[tuple[Union[ArrayLike, float, int, None]]], optional)) – The valid range of the parameter. Defaults to None meaning all of -inf to inf is valid.
units ((Optional[str], optional)) – The units of the parameter. Defaults to None.
dynamic ((bool, optional)) – Force param to be dynamic if True. If a value is provided and param is dynamic then it has a default value at call time.
(bool (batched) – If True, the param is assumed batched and the shape may now take the form (*B, *D) where *D is the shape of the value.
optional) – If True, the param is assumed batched and the shape may now take the form (*B, *D) where *D is the shape of the value.
dtype ((Optional[Any], optional)) – The data type of the parameter. Defaults to None meaning the data type will be inferred from the value.
device ((Optional[Any], optional)) – The device of the parameter. Defaults to None meaning the device will be inferred from the value.

property batch_shape: tuple[int, ...]#

The batch dimensions of the parameter value.

Batch dimensions are the leading dimensions of the value that precede the event shape. If an explicit batch shape was set it is returned directly; otherwise it is inferred from the value.

Returns:: The batch shape, or () if the parameter is not batched.
Return type:: tuple of int

property batched: bool#

Whether this parameter carries batch dimensions.

Returns:: True if batch_shape is non-empty.
Return type:: bool

property cyclic: bool#

Whether the parameter has cyclic (periodic) boundary conditions.

When True, values wrap around the valid range (e.g. an angle from 0 to 2π).

Returns:: True if the parameter is cyclic.
Return type:: bool

property device: str | None#

The device on which the parameter value resides.

If no explicit device was set, the device is inferred from the current value.

Returns:: The device, or None if unknown.
Return type:: device or None

property dtype: str | None#

The data type of the parameter value.

If no explicit dtype was set, the dtype is inferred from the current value.

Returns:: The data type, or None if unknown.
Return type:: dtype or None

property dynamic: bool#

Whether this parameter is dynamic.

Returns:: True if the parameter’s value is provided at runtime.
Return type:: bool

property graphviz_style#

property group: int#

The group index of this parameter.

Parameters that share the same group index are collected together into a single params object when calling a simulator’s @forward method, as well as when using get_values or set_values.

Returns:: The group index (default 0).
Return type:: int

is_valid(value=None) → bool[source]#

Check whether a value lies within the allowed range.

Parameters:: value (ArrayLike or None, optional) – The value to check. If None (default), the parameter’s current value is used.
Returns:: True if the value is within the valid range or if no constraints are set. False otherwise; a warning is also emitted.
Return type:: bool

property node_str: str#: Returns a string representation of the node for graph visualization.

property node_type#

The current type of this parameter node.

Returns:: One of "static", "dynamic", or "pointer".
Return type:: str

property npvalue: ndarray#

The current value converted to a NumPy array.

Returns:: The value as a NumPy ndarray.
Return type:: numpy.ndarray

property pointer: bool#

Whether this parameter is a pointer.

Returns:: True if the parameter points to another Param or a callable that is evaluated at runtime.
Return type:: bool

property shape: tuple[int, ...]#

The event (non-batch) shape of the parameter value.

Wildcard dimensions (None) in the declared shape are resolved using the current value. If no shape was declared, the shape of the current value is returned directly.

Returns:: The resolved shape of the parameter.
Return type:: tuple of int

property static: bool#

Whether this parameter is static.

Returns:: True if the parameter holds a fixed value that does not change at runtime.
Return type:: bool

to(device=None, dtype=None) → Param[source]#

Moves and/or casts the values of the parameter.

Parameters:

device ((optional)) – The device to move the values to. Defaults to None.
dtype ((optional)) – The desired data type. Defaults to None.

to_dynamic(value=<object object>)[source]#

Change this parameter to a dynamic parameter.

If a value is provided, it is stored as the default dynamic value. When called without arguments the existing value (if any) is kept.

Parameters:

value (ArrayLike, float, int, None, or sentinel, optional) – The default value for the dynamic parameter. Must not be a Param or callable. By default the current value is retained.

Raises:

ActiveStateError – If the parameter is currently active.
ParamTypeError – If value is a Param or callable.
ParamConfigurationError – If the value shape does not match the declared shape.

to_pointer(value, link=())[source]#

Change this parameter to a pointer parameter.

The parameter’s value will be computed at runtime by dereferencing another Param or by calling a user-supplied function.

Parameters:

value (Param or callable) – A Param whose value will be mirrored, or a callable f(param) -> ArrayLike evaluated at runtime.
link (Node or tuple of Node, optional) – Additional nodes to link into the graph when creating the pointer. Defaults to an empty tuple.

Raises:

ActiveStateError – If the parameter is currently active.
ParamTypeError – If value is not a Param or callable.

to_static(value=<object object>)[source]#

Change this parameter to a static parameter.

If a value is provided, it is stored as the fixed static value. When called without arguments the existing value (if any) is kept.

Parameters:

value (ArrayLike, float, int, None, or sentinel, optional) – The constant value for the static parameter. Must not be a Param or callable. By default the current value is retained.

Raises:

ActiveStateError – If the parameter is currently active.
ParamTypeError – If value is a Param or callable.
ParamConfigurationError – If the value shape does not match the declared shape.

property valid: tuple[ArrayLike | None, ArrayLike | None]#

The valid range of the parameter value.

Returns:: (lower_bound, upper_bound). Either bound may be None indicating no constraint on that side.
Return type:: tuple of (ArrayLike or None, ArrayLike or None)

property value: ArrayLike | None#

The current value of the parameter.

For static and dynamic parameters the stored value is returned. For pointer parameters the linked callable is evaluated. During an active simulation the result is cached.

Returns:: The parameter value, or None if no value has been set.
Return type:: ArrayLike or None

class caustics.Pixelated(image: Annotated[ArrayLike | None, 'The source image from which brightness values will be interpolated.', True, 'flux'] = None, x0: Annotated[ArrayLike | float | None, "The x-coordinate of the source image's center.", True] = None, y0: Annotated[ArrayLike | float | None, "The y-coordinate of the source image's center.", True] = None, pixelscale: Annotated[ArrayLike | float | None, 'The pixelscale of the source image in the lens plane', True, 'arcsec/pixel'] = None, scale: Annotated[ArrayLike | float | None, 'A scale factor to multiply by the image', True, 'flux'] = 1.0, shape: Annotated[tuple[int | None, ...], 'The shape of the source image.'] = (None, None), name: Annotated[str | None, 'Name of the source'] = None)[source]#

Bases: Source

Pixelated is a subclass of the abstract class Source. It represents the brightness profile of source with a pixelated grid of intensity values.

This class provides a concrete implementation of the brightness method required by the Source superclass. In this implementation, brightness is determined by interpolating values from the provided source image.

x0#

The x-coordinate of the source image’s center.

Unit: arcsec

Type:: ArrayLike, optional

y0#

The y-coordinate of the source image’s center.

Unit: arcsec

Type:: ArrayLike, optional

image#

The source image from which brightness values will be interpolated.

Unit: flux

Type:: ArrayLike, optional

pixelscale#

The pixelscale of the source image in the lens plane.

Unit: arcsec/pixel

Type:: ArrayLike, optional

shape#

The shape of the source image.

Type:: Tuple of ints, optional

brightness(x, y, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], image: Annotated[ArrayLike, 'Param'], pixelscale: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param'], padding_mode: str = 'zeros')[source]#

Implements the brightness method for Pixelated. The brightness at a given point is determined by interpolating values from the source image.

Parameters:

x (ArrayLike) –
The x-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
y (ArrayLike) –
The y-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec

Returns:

The brightness of the source at the given coordinate(s). The brightness is determined by interpolating values from the source image.

Unit: flux

Return type:

ArrayLike

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

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

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

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

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

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

Bases: ThinLens

convergence(x, y, **kwargs)[source]#

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

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

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

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

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

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

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.PixelatedTime(cube: Annotated[ArrayLike | None, 'The source image cube from which brightness values will be interpolated.', True, 'flux'] = None, x0: Annotated[ArrayLike | float | None, "The x-coordinate of the source image's center.", True] = None, y0: Annotated[ArrayLike | float | None, "The y-coordinate of the source image's center.", True] = None, pixelscale: Annotated[ArrayLike | float | None, 'The pixelscale of the source image in the lens plane', False, 'arcsec/pixel'] = None, t_end: Annotated[ArrayLike | float | None, 'The end time of the source image cube.', False, 'seconds'] = None, scale: Annotated[ArrayLike | float | None, 'A scale factor to multiply by the image', True, 'flux'] = 1.0, shape: Annotated[tuple[int, ...] | None, 'The shape of the source image.'] = None, name: Annotated[str | None, 'Name of the source'] = None)[source]#

Bases: Source

PixelatedTime is a subclass of the abstract class Source. It represents the brightness profile of source with a pixelated grid of intensity values that also may vary over time.

This class provides a concrete implementation of the brightness method required by the Source superclass. In this implementation, brightness is determined by interpolating values from the provided source image.

x0#

The x-coordinate of the source image’s center.

Unit: arcsec

Type:: ArrayLike, optional

y0#

The y-coordinate of the source image’s center.

Unit: arcsec

Type:: ArrayLike, optional

cube#

The source image cube from which brightness values will be interpolated.

Unit: flux

Type:: ArrayLike, optional

pixelscale#

The pixelscale of the source image in the lens plane.

Unit: arcsec/pixel

Type:: ArrayLike, optional

t_end#

The end time of the source image cube. Time in the cube is assumed to be in the range (0, t_end) in seconds.

Unit: seconds

Type:: ArrayLike, optional

shape#

The shape of the source image and time dim.

Type:: Tuple of ints, optional

brightness(x, y, t, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], cube: Annotated[ArrayLike, 'Param'], scale: Annotated[ArrayLike, 'Param'])[source]#

Implements the brightness method for Pixelated. The brightness at a given point is determined by interpolating values from the source image.

Parameters:

x (ArrayLike) –
The x-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
y (ArrayLike) –
The y-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
t (ArrayLike) –
The time coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: seconds

Returns:

The brightness of the source at the given coordinate(s). The brightness is determined by interpolating values from the source image.

Unit: flux

Return type:

ArrayLike

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.Sersic(x0: Annotated[ArrayLike | float | None, "The x-coordinate of the Sersic source's center", True] = None, y0: Annotated[ArrayLike | float | None, "The y-coordinate of the Sersic source's center", True] = None, q: Annotated[ArrayLike | float | None, 'The axis ratio of the Sersic source', True] = None, phi: Annotated[ArrayLike | float | None, 'The orientation of the Sersic source (position angle)', True] = None, n: Annotated[ArrayLike | float | None, 'The Sersic index, which describes the degree of concentration of the source', True] = None, Re: Annotated[ArrayLike | float | None, 'The scale length of the Sersic source', True] = None, Ie: Annotated[ArrayLike | float | None, 'The intensity at the effective radius', True] = None, s: Annotated[float, 'A small constant for numerical stability'] = 0.0, use_lenstronomy_k: Annotated[bool, 'A flag indicating whether to use lenstronomy to compute the value of k.'] = False, 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, name: Annotated[str | None, 'Name of the source'] = None)[source]#

Bases: Angle_Mixin, Source

Sersic is a subclass of the abstract class Source. It represents a source in a strong gravitational lensing system that follows a Sersic profile, a mathematical function that describes how the intensity I of a galaxy varies with distance r from its center.

The Sersic profile is often used to describe elliptical galaxies and spiral galaxies’ bulges.

x0#

The x-coordinate of the Sersic source’s center.

Unit: arcsec

Type:: Optional[ArrayLike]

y0#

The y-coordinate of the Sersic source’s center.

Unit: arcsec

Type:: Optional[ArrayLike]

q#

The axis ratio of the Sersic source.

Unit: unitless

Type:: Optional[ArrayLike]

phi#

The orientation of the Sersic source (position angle).

Unit: radians

Type:: Optional[ArrayLike]

n#

The Sersic index, which describes the degree of concentration of the source.

Unit: unitless

Type:: Optional[ArrayLike]

Re#

The scale length of the Sersic source.

Unit: arcsec

Type:: Optional[ArrayLike]

Ie#

The intensity at the effective radius.

Unit: flux

Type:: Optional[ArrayLike]

s#

A small constant for numerical stability.

Unit: arcsec

Type:: float

lenstronomy_k_mode#

A flag indicating whether to use lenstronomy to compute the value of k.

Type:: bool

brightness(x, y, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], q: Annotated[ArrayLike, 'Param'], phi: Annotated[ArrayLike, 'Param'], n: Annotated[ArrayLike, 'Param'], Re: Annotated[ArrayLike, 'Param'], Ie: Annotated[ArrayLike, 'Param'])[source]#

Implements the brightness method for Sersic. The brightness at a given point is determined by the Sersic profile formula.

Parameters:

x (ArrayLike) –
The x-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
y (ArrayLike) –
The y-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec

Returns:

The brightness of the source at the given point(s). The output tensor has the same shape as x and y.

Unit: flux

Return type:

ArrayLike

Notes

The Sersic profile is defined as: I(r) = Ie * exp(-k * ((r / r_e)^(1/n) - 1)), where Ie is the intensity at the effective radius r_e, n is the Sersic index that describes the concentration of the source, and k is a parameter that depends on n. In this implementation, we use elliptical coordinates ex and ey, and the transformation from Cartesian coordinates is handled by to_elliptical. The value of k can be calculated in two ways, controlled by lenstronomy_k_mode. If lenstronomy_k_mode is True, we use the approximation from Lenstronomy, otherwise, we use the approximation from Ciotti & Bertin (1999).

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

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

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

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

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.Source(name: str | None = None, **kwargs)[source]#

Bases: Module

This is an abstract base class used to represent a source in a strong gravitational lensing system. It provides the basic structure and required methods that any derived source class should implement. The Source class inherits from the Module class, implying that it contains parameters that can be optimized or manipulated.

The class introduces one abstract method, brightness, that must be implemented in any concrete subclass. This method calculates the brightness of the source at given coordinates.

abstract brightness(x: ArrayLike, y: ArrayLike, *args, **kwargs) → ArrayLike[source]#

Abstract method that calculates the brightness of the source at the given coordinates. This method is expected to be implemented in any class that derives from Source.

Parameters:

x (ArrayLike) –
The x-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
y (ArrayLike) –
The y-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec

Returns:

The brightness of the source at the given coordinate(s). The exact form of the output will depend on the specific implementation in the derived class.

Return type:

ArrayLike

Notes

This method must be overridden in any class that inherits from Source.

Note that the source redshift z_s is not included as an argument since most sources don’t need to know their redshift, it is instead held by the lens object.

class caustics.StarSource(x0: Annotated[ArrayLike | float | None, "The x-coordinate of the star source's center", True] = None, y0: Annotated[ArrayLike | float | None, "The y-coordinate of the star source's center", True] = None, theta_s: Annotated[ArrayLike | float | None, 'The radius of the star source', True] = None, Ie: Annotated[ArrayLike | float | None, 'The intensity at the effective radius', True] = None, gamma: Annotated[ArrayLike | float | None, 'The linear limb darkening coefficient', True] = None, name: Annotated[str | None, 'Name of the source'] = None)[source]#

Bases: Source

Star is a subclass of the abstract class Source. It represents a star source in a gravitational lensing system.

The Star profile is meant to describe individual light sources.

x0#

The x-coordinate of the Star source’s center.

Unit: arcsec

Type:: Optional[ArrayLike]

y0#

The y-coordinate of the Star source’s center.

Unit: arcsec

Type:: Optional[ArrayLike]

theta_s#

The radius of the star.

Unit: arcsec

Type:: Optional[ArrayLike]

Ie#

The intensity at the center of the star.

Unit: flux

Type:: Optional[ArrayLike]

gamma#

The linear limb darkening coefficient.

Unit: unitless

Type:: Optional[ArrayLike]

brightness(x, y, x0: Annotated[ArrayLike, 'Param'], y0: Annotated[ArrayLike, 'Param'], theta_s: Annotated[ArrayLike, 'Param'], Ie: Annotated[ArrayLike, 'Param'], gamma: Annotated[ArrayLike, 'Param'])[source]#

Implements the brightness method for star. This method calculates the brightness of the source at the given point(s).

Parameters:

x (ArrayLike) –
The x-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec
y (ArrayLike) –
The y-coordinate(s) at which to calculate the source brightness. This could be a single value or a tensor of values.

Unit: arcsec

Returns:

The brightness of the source at the given point(s). The output tensor has the same shape as x and y.

Unit: flux

Return type:

ArrayLike

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Irwin I. Shapiro (1964). “Fourth Test of General Relativity”. Physical Review Letters. 13 (26): 789-791
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.

class caustics.ValidContext(module: Module)[source]#

Bases: object

Context manager that transforms parameter values to an unconstrained space.

Inside a ValidContext, all parameter values are automatically mapped into the range (-inf, inf) via each parameter’s to_valid / from_valid transformations. This is useful when interfacing with samplers or optimizers that expect unconstrained parameters—any value they propose will be mapped back into the parameter’s original valid range on exit.

Parameters:: module (Module) – The module whose parameters should be transformed.

Examples

Get unconstrained parameter values for use with an optimizer:

with ValidContext(my_module):
    unconstrained_params = my_module.get_values()
    # unconstrained_params live in (-inf, inf)

caustics.build_simulator(config: str | TextIO) → Module[source]#

caustics.forward(method)[source]#

Decorator to define a forward method for a module.

Manages parameter passing and activation for the decorated method. When called, it automatically fills keyword arguments from the module’s Param children and handles parameter overrides and active context.

Parameters:: method ((Callable)) – The forward method to be decorated.
Returns:: The decorated forward method.
Return type:: Callable

Examples

Standard usage of the forward decorator:

class ExampleSim(Module):
    def __init__(self, a, b, c):
        super().__init__("example_sim")
        self.a = a
        self.b = Param("b", b)
        self.c = Param("c", c)

    @forward
    def example_func(self, x, b=None):
        return x + self.a + b

E = ExampleSim(a=1, b=None, c=3)
print(E.example_func(4, params=[5]))
# Output: 10

caustics.test(device=device(type='cpu'))[source]#

Run tests for caustics basic functionality. Run this function to ensure that caustics is working properly.

Simply call:

>>> import caustics
>>> caustics.test()
all tests passed!

To run the checks.

caustics package

Contents

caustics package#

Subpackages#

Submodules#

caustics.angle_mixin module#

caustics.backend_obj module#

caustics.constants module#

caustics.func module#

caustics.tests module#

caustics.utils module#

Module contents#