Lenses

get_meshgrid(θx::RV, θy::RV, dθ::RV) --> Tuple{Matrix{Float64}, Matrix{Float64}}

Generate a meshgrid of coordinates on which various quantities can be evaluated. At present, this function only generates square pixels. In future if the need arises, it can be extended to generate rectangular pixels as well.

Arguments

• θx::RV: Half-size of the grid in x-direction (in $\rm \mathbf{arcseconds}$)
• θy::RV: Half-size of the grid in y-direction (in $\rm \mathbf{arcseconds}$)
• dθ::RV: Pixel size (in $\rm \mathbf{arcseconds}$)

Returns

• grid_x::Matrix{Float64}: x-coordinates of the grid (in $\rm \mathbf{arcseconds}$)
• grid_y::Matrix{Float64}: y-coordinates of the grid (in $\rm \mathbf{arcseconds}$)

get_critical_density(D_d::Float64, D_ds::Float64, D_s::Float64s; unit::Symbol=:kg_m2) --> Float64s

Calculate the critical surface density,

\[Σ_{\rm cr} = \frac{c^2}{4 π {\rm G}} \frac{D_s}{D_d D_{ds}}.\]

Arguments

• D_d::Float64: Angular diameter distance to the lens (in $\rm \mathbf{meters}$)
• D_ds::Float64: Angular diameter distance to the source (in $\rm \mathbf{meters}$)
• D_s::Float64: Angular diameter distance to the lens (in $\rm \mathbf{meters}$)

Keyword Arguments

• unit::Symbol = :kg_m2: Output units of the critical surface density.
  • :kg_m2 $\Rightarrow{\rm \mathbf{kg/m^2}}$
  • :msun_pc2 $\Rightarrow{\rm \mathbf{M_⊙/pc^2}}$
  • :msun_arcsec2 $\Rightarrow{\rm \mathbf{M_⊙/arcsec^2}}$

Returns

• Σ_cr::Float64: Critical surface density in the requested unit

get_potential(lens::AbstractLens, θx::T, θy::T) where T <: RV --> RV

get_potential(lens::AbstractLens, θx::T, θy::T) where T <: ROA --> ROA

Calculate lensing potential at the given angular coordinates for the given lens model,

\[ψ(\pmb{θ}) = \frac{4{\rm G}}{\rm c^2} \frac{1}{D_d} \int d^2 \pmb{θ}' \, Σ(\pmb{θ}') \, \ln\left(|\pmb{θ} - \pmb{θ'}|\right).\]

Arguments

• lens::AbstractLens: Lens model.
• θx: x-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• θy: y-coordinate(s) (in $\rm \mathbf{arcseconds}$).

Returns

• ψ: Lensing potential at the given angular coordinate(s).

get_deflection(lens::AbstractLens, θx::T, θy::T) where T <: RV --> Tuple{RV, RV}

get_deflection(lens::AbstractLens, θx::T, θy::T) where T <: ROA --> Tuple{ROA, ROA}

Calculate (vector) deflection angle at the given angular coordinate(s) for a given lens model,

\[\pmb{α}(\pmb{θ}) = \pmb{∇} ψ(\pmb{θ}) = \frac{4{\rm G}}{\rm c^2} \frac{1}{D_d} \int d^2 \pmb{θ}' \, Σ(\pmb{θ}') \frac{\pmb{θ} - \pmb{θ}'}{|\pmb{θ} - \pmb{θ}'|^2}.\]

Arguments

• lens::AbstractLens: Lens model.
• θx: x-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• θy: y-coordinate(s) (in $\rm \mathbf{arcseconds}$).

Returns

• αx: x-component of the deflection angle (in $\rm \mathbf{arcseconds}$).
• αy: y-component of the deflection angle (in $\rm \mathbf{arcseconds}$).

get_jacobian(lens::AbstractLens, θx::T, θy::T) where T <: RV --> Tuple{RV, RV, RV}

get_jacobian(lens::AbstractLens, θx::T, θy::T) where T <: ROA --> Tuple{ROA, ROA, ROA}

Calculate jacobian (i.e., deformation tensor) of the lens mapping for a given lens model,

\[\mathcal{A}(\pmb{θ}) = \begin{pmatrix} ψ_{xx} & ψ_{xy} \\ ψ_{xy} & ψ_{yy} \end{pmatrix}.\]

Since the jacobian is symmetric (for single lens plane), only three components are returned, i.e., $(ψ_{xx}, ψ_{yy}, ψ_{xy})$.

Arguments

• lens::AbstractLens: Lens model.
• θx: x-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• θy: y-coordinate(s) (in $\rm \mathbf{arcseconds}$).

Returns

• ψxx: xx-component of the jacobian.
• ψyy: yy-component of the jacobian.
• ψxy: xy-component of the jacobian.

get_time_delay(lens::AbstractLens, θx::T, θy::T, adis::Float64, z_d::RV, D_d::RV, β::NTuple{2, RV}) where T <: RV --> RV

get_time_delay(lens::AbstractLens, θx::T, θy::T, adis::Float64, z_d::RV, D_d::RV, β::NTuple{2, RV}) where T <: ROA --> ROA

Calculate time delay for a given lens model and source position. The corresponding expression is given as,

\[t_d(\pmb{θ}; \pmb{β}) = \frac{1+z_l}{\rm c} \frac{D_d D_s}{D_{ds}} \theta_0^2 \left[ \frac{(\pmb{θ} - \pmb{β})^2}{2} - \frac{D_{ds}}{D_s} \psi(\pmb{θ}) \right],\]

where $\theta_0$ is normalizing angular unit.

Arguments

• lens::AbstractLens: Lens model.
• θx: x-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• θy: y-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).
• z_d::RV: Lens redshift.
• D_d::RV: Angular diameter distance to the lens (in $\rm \mathbf{meters}$).
• β::NTuple{2, RV}: Source angular position (in $\rm \mathbf{arcseconds}$).

Returns

• t_d: Time delay at the given angular coordinate(s) (in $\rm \mathbf{seconds}$).

get_magnification_image(lens::AbstractLens, θx::T, θy::T, adis::Float64) where T <: RV --> RV

get_magnification_image(lens::AbstractLens, θx::T, θy::T, adis::Float64) where T <: ROA --> ROA

Calculate signed magnification at the given angular coordinate(s) for a given lens model,

\[\mu(\pmb{θ}) = \frac{1}{det\left[ \mathbb{I} - a_{\rm dis} \, \mathcal{A} \right]},\]

where $\mathbb{I}$ is the identity matrix.

Arguments

• lens::AbstractLens: Lens model.
• θx: x-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• θy: y-coordinate(s) (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).

Returns

• μ: Magnification at the given angular coordinate(s).

get_magnification_source(lens::AbstractLens, θx::T, θy::T, adis::Float64; rays_per_pixel::Int64=1) where T <: Matrix{<:RV} --> Matrix{RV}

Calculates the magnification map in source plane using inverse ray shooting (IRS) for a given lens model. The number of average rays per pixel can be specified using the rays_per_pixel keyword argument. This function is not optimized for speed and is only intended to visualize the magnification map.

Arguments

• lens::AbstractLens: Lens model.
• θx::Matrix{<:RV}: x-grid (in $\rm \mathbf{arcseconds}$).
• θy::Matrix{<:RV}: y-grid (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).
• rays_per_pixel::Int64: Average number of rays per pixel.

Returns

• μ_source::Matrix{<:RV}: Magnification map in source plane.

get_image(lens::AbstractLens, θx::ROA, θy::ROA, adis::Float64, β::NTuple{2, RV}) --> Vector{NTuple{2, RV}}

get_image(lens::AbstractLens, θx::T, θy::T, adis::Float64, β::T) where T <: Matrix{<:RV} --> Matrix{<:RV}

Calculate image positions for a given lens model and source position. To get the image positions, this implementation finds the intersection points of contours corresponding to,

\[\pmb{β} - \pmb{θ} + a_{\rm dis} \, \pmb{α}(\pmb{θ}) = 0,\]

where $\pmb{β}$ is the source position, $\pmb{θ}$ is the image plane grid, $a_{\rm dis}$ is the distance ratio (i.e., $D_{ds}/D_s$), and $\pmb{α}(\pmb{θ})$ is the deflection angle. To find the intersection points inside the pixels, we use bi-linear interpolation.

Arguments

• lens::AbstractLens: Lens model.
• θx::Matrix{<:RV}: x-grid (in $\rm \mathbf{arcseconds}$).
• θy::Matrix{<:RV}: y-grid (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).
• β: Source position (in $\rm \mathbf{arcseconds}$).

Returns

• image_position: Image positions (in $\rm \mathbf{arcseconds}$).

get_critical_curve(lens::AbstractLens, θx::T, θy::T, adis::Float64) where T <: Matrix{<:RV} --> Tuple{Vector{Vector{Vector{Float64}}}, Vector{Vector{Vector{Float64}}}}

Calculate critical curves for a given lens model. This function essentially runs marching squares algorithm to find the zero eigenvalue contours.

Arguments

• lens::AbstractLens: Lens model.
• θx::Matrix{<:RV}: x-grid (in $\rm \mathbf{arcseconds}$).
• θy::Matrix{<:RV}: y-grid (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).

Returns

• critical_tan::Vector{Vector{Vector{Float64}}}: Tangential critical curve(s) (in $\rm \mathbf{arcseconds}$).
• critical_rad::Vector{Vector{Vector{Float64}}}: Radial critical curve(s) (in $\rm \mathbf{arcseconds}$).

get_caustic(lens::AbstractLens, θx::T, θy::T, adis::Float64) where T <: Matrix{<:RV}

Calculate caustics for a given lens model. The function first gets the critical curves and then maps them to the source plane using lens equation.

Arguments

• lens::AbstractLens: Lens model.
• θx::Matrix{<:RV}: x-grid (in $\rm \mathbf{arcseconds}$).
• θy::Matrix{<:RV}: y-grid (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).

Returns

• caustics_tan::Vector{Vector{Vector{Float64}}}: Tangential caustic curve(s) (in $\rm \mathbf{arcseconds}$).
• caustics_rad::Vector{Vector{Vector{Float64}}}: Radial caustic curve(s) (in $\rm \mathbf{arcseconds}$).

get_critical_area(lens::AbstractLens, θx::T, θy::T, adis::Float64) where T <: Matrix{<:RV} --> Float64

Calculate the total angular area enclosed by tangential critical curve(s). The function runs shoelace algorithm to calculate the area.

Arguments

• lens::AbstractLens: Lens model.
• θx::Matrix{<:RV}: x-grid (in $\rm \mathbf{arcseconds}$).
• θy::Matrix{<:RV}: y-grid (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).

Returns

• area::Float64: Total angular area enclosed by tangential critical curve(s) (in $\rm \mathbf{arcseconds^2}$).

get_einstein_angle(lens::AbstractLens, θx::T, θy::T, adis::Float64) where T <: Matrix{<:RV} --> Float64

Calculate the Einstein radius (i.e., $θ_E$) for an arbitrary lens model, which is defined as,

\[θ_E = \sqrt{\frac{A_{\rm critical}}{π}},\]

where $A_{\rm critical}$ is the total angular area enclosed by the tangential critical curve(s).

Arguments

• lens::AbstractLens: Lens model.
• θx::Matrix{<:RV}: x-grid (in $\rm \mathbf{arcseconds}$).
• θy::Matrix{<:RV}: y-grid (in $\rm \mathbf{arcseconds}$).
• adis::Float64: Distance ratio (i.e., $D_{ds}/D_s$).

Returns

• θ_E::Float64: Einstein radius (i.e., $θ_E$) (in $\rm \mathbf{arcseconds}$).

shear_cartesian2polar(γ1::T, γ2::T) where T <: RV --> Tuple{Float64, Float64}

Converts the Cartesian components of the shear (i.e., $γ_1$ and $γ_2$) to polar components (i.e., $γ$ and $φ$) using the relations,

\[\begin{align*} γ &= \sqrt{γ_1^2 + γ_2^2}, \\ φ &= \frac{1}{2} \tan^{-1}\left(\frac{γ_2}{γ_1}\right). \end{align*}\]

Arguments

• γ1::T: Cartesian component of the shear (i.e., $γ_1$).
• γ2::T: Cartesian component of the shear (i.e., $γ_2$).

Returns

• γ::Float64: Polar component of the shear (i.e., $γ$).
• φ::Float64: Polar component of the shear (i.e., $φ$ in $\rm \mathbf{degrees}$).

shear_polar2cartesian(γ::T, phi::T) where T <: RV --> Tuple{Float64, Float64}

Converts the polar components of the shear (i.e., $γ$ and $φ$) to Cartesian components (i.e., $γ_1$ and $γ_2$) using the relations,

\[\begin{align*} γ_1 &= γ \cos(2φ), \\ γ_2 &= γ \sin(2φ). \end{align*}\]

Arguments

• γ::T: Polar component of the shear (i.e., $γ$).
• φ::T: Polar component of the shear (i.e., $φ$ in $\rm \mathbf{degrees}$).

Returns

• γ1::Float64: Cartesian component of the shear (i.e., $γ_1$).
• γ2::Float64: Cartesian component of the shear (i.e., $γ_2$).

ellipticity_cartesian2polar(e1::T, e2::T) where T <: RV --> Tuple{Float64, Float64}

Converts the Cartesian components of the ellipticity (i.e., $e_1$ and $e_2$) to polar components (i.e., $e$ and $φ$) using the relations,

\[\begin{align*} e &= \sqrt{e_1^2 + e_2^2}, \\ φ &= \frac{1}{2} \tan^{-1}\left(\frac{e_2}{e_1}\right). \end{align*}\]

Arguments

• e1::T: Cartesian component of the ellipticity (i.e., $e_1$).
• e2::T: Cartesian component of the ellipticity (i.e., $e_2$).

Returns

• e::Float64: Polar component of the ellipticity (i.e., $e$).
• φ::Float64: Polar component of the ellipticity (i.e., $φ$ in $\rm \mathbf{degrees}$).

ellipticity_polar2cartesian(e::T, phi::T) where T <: RV --> Tuple{Float64, Float64}

Converts the polar components of the ellipticity (i.e., $e$ and $φ$) to Cartesian components (i.e., $e_1$ and $e_2$) using the relations,

\[\begin{align*} e_1 &= e \cos(2φ), \\ e_2 &= e \sin(2φ). \end{align*}\]

Arguments

• e::T: Polar component of the ellipticity (i.e., $e$).
• φ::T: Polar component of the ellipticity (i.e., $φ$ in $\rm \mathbf{degrees}$).

Returns

• e1::Float64: Cartesian component of the ellipticity (i.e., $e_1$).
• e2::Float64: Cartesian component of the ellipticity (i.e., $e_2$).