MultiPlane
When the deflectors along the line of sight are located at different redshifts (e.g., a galaxy lens with line-of-sight perturbers, or a cluster with structures at multiple redshifts), the single-plane approximation breaks down, and the light rays need to be propagated through a series of lens planes.
Following same terminology as single plane lensing, we can write the lensing potential and deflection in $j$th plane as,
\[\begin{align*} ψ_j(\pmb{θ}_j) &= \frac{4{\rm G}}{\rm c^2} \frac{1}{D_j} \int d^2 \pmb{θ}' \, Σ_j(\pmb{θ}') \, \ln|\pmb{θ}_j - \pmb{θ'}|, \\ \pmb{α}_j(\pmb{θ}_j) &= \pmb{∇}_j ψ_j(\pmb{θ}_j), \end{align*}\]
where $D_j$ is the angular diameter distance from observer to the $j$th lens plane and $Σ_j$ is the surface mass density in the $j$th lens plane. Starting from observer, by the time a ray reaches $j$th lens plane it has already deflected in previous $j-1$ lens planes. Hence, the impact parameter in the 1st lens plane is related to impact parameters in $j$th lens plane as,
\[\pmb{θ}_j = \pmb{θ}_1 - \sum_{i=1}^{j-1} \frac{D_{ij}}{D_j} \pmb{α}_i(\pmb{θ}_i).\]
With the above, the total potential and deflection for a lens system with $N_p$ planes is given as,
\[\begin{align*} ψ(\pmb{θ}) &= \sum_{i=1}^{N_p} \frac{D_{is}}{D_s} ψ_i(\pmb{θ}_i), \\ \pmb{α}(\pmb{θ}) &= \sum_{i=1}^{N_p} \frac{D_{is}}{D_s} \pmb{α}_i(\pmb{θ}_i). \end{align*}\]
Similarly, the excess time delay accumulates between consecutive planes as,
\[\begin{equation*} Δt = \sum_{i=1}^{N_p} \frac{1 + z_i}{\rm c} \frac{D_i D_{i+1}}{D_{i,i+1}} \left[ \frac{1}{2} \left| \pmb{θ}_i - \pmb{θ}_{i+1} \right|^2 - \frac{D_{i,i+1}}{D_{i+1}} ψ_i(\pmb{θ}_i) \right], \end{equation*}\]
where $z_i$ is the redshift of the $i$th lens plane and the ($N_p$+1)th plane is the source plane, i.e., $\pmb{θ}_{N_p+1} = \pmb{β}$ and $D_{N_p+1} = D_s$.
In LensFactory, a multi-plane lens is initialized from a vector of lens components, where each component specifies its lens redshift (z_d) in addition to the usual lens model parameters. Components sharing the same redshift are automatically grouped into a single (composite) lens plane, and the lens planes are sorted in increasing redshift.
LensFactory.Lenses.init_MultiPlaneLens — Type
init_MultiPlaneLens(lens::Vector{<:NamedTuple};
cosmology::Union{Nothing, Cosmology.AbstractCosmology} = nothing,
position::Symbol = :physical)Initialize a multi-plane lens from a vector of lens components. Each component must contain the lens redshift (z_d) along with the parameters of the corresponding lens model. Components sharing the same redshift are grouped into a single (composite) lens plane, and the lens planes are sorted in increasing redshift. At least two distinct lens planes are required.
Arguments
lens::Vector{<:NamedTuple}: Vector of lens components.
Keyword Arguments
cosmology = nothing: Cosmology model. Required only whenposition = :observedto calculate the plane-plane distance ratios.position = :physical: Convention for the supplied deflector centres.:physical: centres are already plane-frame positions and are used as-is.:observed: centres are observed (on-sky) positions. Those on planes behind the first need to be mapped to their physical (plane-frame) positions by ray-tracing through the foreground planes.
Returns
MultiPlaneLens: Multi-plane lens.
LensFactory.MultiPlane.get_potential — Function
get_potential(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: Realget_potential(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: ROACalculate potential at the given angular coordinate(s) for a given multi-plane lens system with cosmology and source redshift. The function is designed to handle both single coordinate and array of coordinates as input via multiple dispatch, depending on the type of T (ROA or Real).
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Union{Real, ROA}: The x-coordinate(s) (in arcseconds).θy::Union{Real, ROA}: The y-coordinate(s) (in arcseconds).z_s::Real: The redshift of the source plane.
Returns
ψ: The potential at the given coordinates.
LensFactory.MultiPlane.get_deflection — Function
get_deflection(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: Realget_deflection(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: ROACalculate deflection angle at the given angular coordinate(s) for a given multi-plane lens system with cosmology and source redshift. The function is designed to handle both single coordinate and array of coordinates as input via multiple dispatch, depending on the type of T (ROA or Real).
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Union{Real, ROA}: The x-coordinate(s) (in arcseconds).θy::Union{Real, ROA}: The y-coordinate(s) (in arcseconds).z_s::Real: The redshift of the source plane.
Returns
ψx: The x-component of the deflection angle at the given coordinates.ψy: The y-component of the deflection angle at the given coordinates.
LensFactory.MultiPlane.get_jacobian — Function
get_jacobian(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: Realget_jacobian(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: ROACalculate jacobian (i.e., deformation tensor) of the lens mapping at the given angular coordinate(s) for a given multi-plane lens system with cosmology and source redshift. The function is designed to handle both single coordinate and array of coordinates as input via multiple dispatch, depending on the type of T (ROA or Real).
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Union{Real, ROA}: The x-coordinate(s) (in arcseconds).θy::Union{Real, ROA}: The y-coordinate(s) (in arcseconds).z_s::Real: The redshift of the source plane.
Returns
ψxx: xx-component of the jacobian.ψyy: yy-component of the jacobian.ψxy: xy-component of the jacobian.ψyx: yx-component of the jacobian.
LensFactory.MultiPlane.get_time_delay — Function
get_time_delay(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real, β::NTuple{2, <:Real}) where T <: Realget_time_delay(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real,
β::NTuple{2, <:Real}) where T <: ROACalculate time delay at the given angular coordinate(s) for a given multi-plane lens system with cosmology and source redshift. The function is designed to handle both single coordinate and array of coordinates as input via multiple dispatch, depending on the type of T (ROA or Real).
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Union{Real, ROA}: The x-coordinate(s) (in arcseconds).θy::Union{Real, ROA}: The y-coordinate(s) (in arcseconds).z_s::Real: The redshift of the source plane.β::NTuple{2, Real}: The source plane position (in arcseconds) as a tuple (βx, βy).
Returns
t_d: The time delay at the given coordinates (in days).
LensFactory.MultiPlane.get_magnification_image — Function
get_magnification_image(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: RealCalculate magnification at the given angular coordinate(s) in the image plane for a given multi-plane lens system with cosmology and source redshift. The function is designed to handle both single coordinate and array of coordinates as input via multiple dispatch, depending on the type of T (ROA or Real).
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Union{Real, ROA}: The x-coordinate(s) (in arcseconds).θy::Union{Real, ROA}: The y-coordinate(s) (in arcseconds).z_s::Real: The redshift of the source plane.
Returns
μ_image: The magnification at the given coordinates.
LensFactory.MultiPlane.get_magnification_source — Function
get_magnification_source(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real;
rays_per_pixel::Int64=1) where T <: Matrix{<:Real}Calculate magnification map in the source plane for a given multi-plane lens system with cosmology and source redshift. The function uses a ray-shooting method to compute the magnification map in the source plane. The rays_per_pixel parameter controls the number of rays to shoot per pixel in the image plane, which can be increased for higher accuracy at the cost of increased computation time.
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Matrix{<:Real}: The x-coordinate grid (in arcseconds).θy::Matrix{<:Real}: The y-coordinate grid (in arcseconds).z_s::Real: The redshift of the source plane.
Keyword Arguments
rays_per_pixel::Int64=1: The average number of rays to shoot per pixel.
Returns
μ_source: The magnification map in the source plane.
LensFactory.MultiPlane.get_image — Function
get_image(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real, β::NTuple{2, Real}) where T <: Matrix{<:Real}Calculate image positions for a given source position in the source plane for a given multi-plane lens system with cosmology and source redshift. The function uses a contour-finding method to compute the image positions by finding the intersection of contours corresponding to the lens equation in the image plane.
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Matrix{<:Real}: The x-coordinate grid (in arcseconds).θy::Matrix{<:Real}: The y-coordinate grid (in arcseconds).z_s::Real: The redshift of the source plane.β::NTuple{2, Real}: The source plane position (in arcseconds) as a tuple (βx, βy).
Returns
image_position: A vector of tuples containing the image positions (in arcseconds).
get_image(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real, β::T) where T <: Matrix{<:Real}Calculate image plane map for a given extended source in the source plane for a given multi-plane lens system with cosmology and source redshift.
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Matrix{<:Real}: The x-coordinate grid (in arcseconds).θy::Matrix{<:Real}: The y-coordinate grid (in arcseconds).z_s::Real: The redshift of the source plane.β::Matrix{<:Real}: The source plane brightness distribution.
Returns
image_map: The image plane map corresponding to the given extended source.
LensFactory.MultiPlane.get_critical_curve — Function
get_critical_curve(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: Matrix{<:Real}Calculate critical curves in the image plane for a given multi-plane lens system with cosmology and source redshift. The function uses a contour-finding method to compute the critical curves by finding $det(A) = 0$ contours in the image plane, where $A$ is the jacobian matrix of the lens mapping.
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Matrix{<:Real}: The x-coordinate grid (in arcseconds).θy::Matrix{<:Real}: The y-coordinate grid (in arcseconds).z_s::Real: The redshift of the source plane.
Returns
critical_curve: A vector of vectors containing the critical curve coordinates (in arcseconds).
LensFactory.MultiPlane.get_caustic — Function
get_caustic(cosmology::Cosmology.AbstractCosmology,
lens::Lenses.AbstractLens,
θx::T, θy::T, z_s::Real) where T <: Matrix{<:Real}Calculate caustics in the source plane for a given multi-plane lens system with cosmology and source redshift. The function first computes the critical curves in the image plane and then maps them to the source plane using the lens equation to obtain the caustics.
Arguments
cosmology::Cosmology.AbstractCosmology: Cosmology model.lens::Lenses.AbstractLens: Multi-plane lens model.θx::Matrix{<:Real}: The x-coordinate grid (in arcseconds).θy::Matrix{<:Real}: The y-coordinate grid (in arcseconds).z_s::Real: The redshift of the source plane.
Returns
caustics_curve: A vector of vectors containing the caustic curve coordinates (in arcseconds).