Section `lenses`

The section lenses is used to specify the models for the mass distributions responsible for the observed gravitational effects. The section is a list of lens models, representing the individual structures. A typical example could be

lenses:
    - NIE:
        name: main  # optional name: if unspecified, lenses are numbered
        z: 0.32  # lens redshift, can also be a free parameter
        x: (0.213, 1.738)  # lens center, in units of angular_unit
        σ: 200..500  # lens velocity dispersion, in km/s
        s: 0.001  # lens core radius, here essentially vanishing
        q: 0.3 .. 0.9  # lens ellipticity b/a
        θ: 0 .. π  # lens position angle: 0 means vertical major axis
    - SIE:
        name: secondary
        z: 0.28
        x: (-1.232, -0.795)
        σ: 100 .. 200

The name after the dash indicates the model adopted for the specific lens; the different mass models defined in the code are described below. All following indented lines are used to specify the values for the lens parameters.

Many parameters are shared by different lens models:

name: is the name associated to the lens. This is optional, and only provided as a convenience feature to recognize the different mass components.
z: is the redshift of the lens. Lenses located at identical redshifts will be put on the same LensPlane. This applies both to constant redshifts, as well as to the cases where the redshift is a free parameter. In case of multi-plane lensing, i.e. if there are lenses at different redshifts (as in the example above), one might want to specify the lens-lenses parameter in the parameters section. Additionally, if one of the lens redshifts is a free parameter, it might be convenient to use [stable-lenses: true] in the same section to avoid costly computations.
x: is the lens position. Should be measured with respect to the global coordinate system, as specified with angular_unit and wcs_origin in the parameters section. Alternatively, one can convert on-the-fly celestial coordinates (such as right ascension and declination) into the global coordinate system using the special function wcsmap(α, δ).
σ: for isothermal models, it is the lens velocity dispersion expressed in kilometers-per-seconds.

Axisymmetric and elliptical lenses

Most lens models falls into two general classes: axisymmetric lens models, and elliptical ones.

Axisymmetric models have mass distribution and lensing potential with axial symmetry. These models are generally very fast to compute.

Elliptical models come in two flavors: the ones with elliptical mass distributions and the ones with elliptical potentials. Models with elliptical mass distributions, often, requires numerical integrations to compute the relevant lensing quantities (deflection angle, potential, Jacobian matrix), which makes their computations particularly inefficient. The exceptions are isothermal models (NIE and JaffeEll), as well as elliptical power-law models without core (PowEll). Models with elliptical potentials, instead, have always analytical expressions for all lensing quantities, but can result in unrealistic mass distributions for large ellipticities.

All elliptical models have common parameters to specify the ellipticity of the mass distribution or of the potential. In details, there are three alternative ways to indicate the shape of a galaxy:

q and θ: these two parameter must appear together and indicate the galaxy axis ratio q, defined as $q = b/a$ (so that q = 1 for spherical lens), and the position angle θ expressed in radians (with θ = 0 for a lens aligned with its major axis vertical);
ϵ (or alternatively e): the ellipticity is a quantity with two entries (a 2-tuple), and can also be considered as a complex quantity. Its modulus is $e = (1 - q) / (1 + q)$ and its argument is twice the position angle θ. This is the usual definition of ellipticity adopted in weak lensing. Note that, since the modulus of ϵ has to be smaller than unity, some care is needed to fit this quantity, in the sense that the prior probability distribution must have support in the unit disk. Gravity provides to this purpose an ellipticity distribution, which can be entered as (e₁, e₂) ±ₑ ν, where ν is a precision parameter approximately inversely proportional to the variance of e.
η (or alternatively eta): the conformal ellipticity is also entered as a 2-tuple. Its modulus is just $\eta = \exp(-q)$, and its argument, similarly to ϵ, is the double of the position angle. The conformal ellipticity is defined over the entire plane, so one can just use a bi-variate normal distribution as prior.

Note that there is a key difference in the use of (q, θ) vs. ϵ or η: both ϵ and η are natural parameters, in the sense that when one smooth changes in the shape of an ellipse reflect in smooth changes of both these quantities. In contrast, the simpler (q, θ) parameters can lead to artificial discontinuities (because of the periodicity π in θ) or to indeterminate values (for θ when q = 1, i.e. for round sources).

Note also that the usual choice of a flat prior for q puts a very strong (divergent) weight for round sources if interpreted in terms of (conformal) ellipticity. For this reason, when replacing (q, θ) parameters in a model, it is a good idea to choose the priors in the ellipticities accordingly, as for example ϵ: (0, 0) ±ₑ 15 or η: (0, 0) ± 0.3.

Lens models

The code implements the following lens models. For each model we just provide a short description and a list of the parameters used. In some cases, multiple parameter choices are possible: the associated parameters are indicated within parentheses. Note also that all parameters containing special symbols can also be entered using standard ascii characters, by spelling out the symbols using a TeX-like notation: so, for example, σ can also be entered as sigma, and rₑ as r_e.

`Point`

A point-like lens. The lens strength must be expressed as a the size of the associated Einstein radius rₑ for D(zₛ) = D(zₗ, zₛ).

Parameters: z, x, rₑ.

`Gaussian`

A spherical lens with a Gaussian profile. The lens strength must be expressed as a the size of the associated Einstein radius rₑ for D(zₛ) = D(zₗ, zₛ), while the size is the expressed in terms of the Gaussian standard deviation s.

Parameters: z, x, rₑ, s.

`SIS`

A singular isothermal sphere. The lens strength is expressed as a velocity dispersion in km/s using the parameter σ.

Parameters: z, x, σ.

`NIS`

A non-singular isothermal sphere with a core radius s.

Parameters: z, x, σ.

`NIE`

A non-singular isothermal ellipsoid with a core radius s, an axis ratio q (with $q = b/a$, so that q: 1 for spherical lens), and a position angle θ expressed in radians (θ: 0 for a lens aligned with its major axis vertical).

Parameters: z, x, σ, s, (q, θ | ϵ | η).

`JaffeSph`

A Jaffe-like spherical lens, characterized by a core radius s and a truncation radius a.

Parameters: z, x, σ, s.

`JaffeEll`

A Jaffe-like elliptical lens, characterized by a core radius s and a truncation radius a.

Parameters: z, x, σ, s, a, (q, θ | ϵ | η).

`PowSph`

A power-law spherical lens, with strictly positive power-law exponent α. This profile is equivalent to a SIS lens when α: 1. The strength of this model is parametrized by its Einstein radius rₑ.

Parameters: z, x, rₑ, α.

`PowEll`

A power-law elliptical lens, with strictly positive power-law exponent α. This profile is equivalent to a singular isothermal elliptical lens (i.e., a NIE with vanishing core) when α: 1. The strength of this model is parametrized by its Einstein radius rₑ.

Parameters: z, x, rₑ, α, (q, θ | ϵ | η).

`PowSoftSph`

A softened power-law spherical lens, with strictly positive power-law exponent α and core radius s. This profile is equivalent to a NIS lens when α: 1. The strength of this model is parametrized by its Einstein radius rₑ for the equivalent singular profile PowSph. This is done because softened power-law profiles might have vanishing Einstein radius.

Parameters: z, x, rₑ, s, α.

`PowSoftEll`

A softened power-law elliptical lens, with strictly positive power-law exponent α and core radius s. This profile is equivalent to a NIE lens when α: 1. Note that this lens requires a 1D integration for each computation, resulting in a rather slow execution. The number of points used for the integration is controlled by the optional parameter npoints (default: 1024). The strength of this model is parametrized by its Einstein radius rₑ for the equivalent singular profile PowSph. This is done because softened power-law profiles might have vanishing Einstein radius.

Parameters: z, x, rₑ, s, α, (q, θ | ϵ | η) [, npoints].

`PowSoftEllPot`

A softened power-law elliptical lens, with strictly positive power-law exponent α and core radius s. This profile uses an elliptical potential, resulting in an approximate elliptical mass distribution for values of q close to 1. The strength of this model is parametrized by its Einstein radius rₑ for the equivalent singular profile PowSph. This is done because softened power-law profiles might have vanishing Einstein radius.

Parameters: z, x, rₑ, s, α, (q, θ | ϵ | η).

`SersicSph`

A Sersic spherical profile, characterized by a Sersic index n and a profile scale length rₛ. The lens strength is entered as a dimensionless parameter b.

Parameters: z, x, b, rₛ, n.

`SersicEll`

A Sersic elliptical profile, characterized by a Sersic index n and a profile scale length rₛ. The lens strength is entered as a dimensionless parameters b. This profile is equivalent to a NIE lens when α: 1. Note that this lens requires a 1D integration for each computation, resulting in a rather slow execution. The number of points used for the integration is controlled by the optional parameter npoints (default: 1024).

Parameters: z, x, b, rₛ, n, (q, θ | ϵ | η) [, npoints].

`SersicEllPot`

A Sersic elliptical profile, characterized by a Sersic index n and a profile scale length rₛ. The lens strength is entered as a dimensionless parameters b. This profile is equivalent to a NIE lens when α: 1. This profile uses an elliptical potential, resulting in an approximate elliptical mass distribution for values of q close to 1.

Parameters: z, x, (m or b), rₛ, n, (q, θ | ϵ | η) [, npoints].

`HernquistSph`

An Hernquist spherical profile with scale length rₛ. The lens strength can is entered as a dimensionless parameters b.

Parameters: z, x, b, rₛ.

`HernquistEll`

An Hernquist elliptical profile with scale length rₛ. The lens strength is entered as a dimensionless parameter b. Note that this lens requires a 1D integration for each computation, resulting in a rather slow execution. The number of points used for the integration is controlled by the optional parameter npoints (default: 1024).

Parameters: z, x, b, rₛ, (q, θ | ϵ | η) [, npoints].

`HernquistEllPot`

An Hernquist elliptical profile with scale length rₛ. The lens strength is entered as a dimensionless parameters b. This profile uses an elliptical potential, resulting in an approximate elliptical mass distribution for values of q close to 1.

Parameters: z, x, (m or b), rₛ, (q, θ | ϵ | η).

`NFWSph`

A Navarro-Frenk-White spherical profile.

Parameters: z, x, b, rₛ.

`NFWEll`

A Navarro-Frenk-White elliptical profile. Note that this lens requires a 1D integration for each computation, resulting in a rather slow execution. The number of points used for the integration is controlled by the optional parameter npoints (default: 1024).

Parameters: z, x, b, rₛ, (q, θ | ϵ | η) [, npoints].

`NFWEllPot`

A Navarro-Frenk-White elliptical profile. This profile uses an elliptical potential, resulting in an approximate elliptical mass distribution for values of q close to 1.

Parameters: z, x, b, rₛ, (q, θ | ϵ | η).

`Shear`

An external shear, typically used to handle external perturbations. The shear can be entered as a scalar and a direction θ, or as a 2-tuple.

Parameters: z, x, γ [, θ].

`Convergence`

An external convergence, rarely used.

Parameters: z, x, κ.

`MappedPotential`

This is a special lens type that takes a (fixed) potential mapped on a grid and interpolates it on the image plane as requested. This lens can be useful to introduce external mass components components whose potential is known, or also to reproduce results from external programs. The potential map must be entered as an external FITS file with appropriate astrometry (WCS), using the data section. Optionally, one can specify a scaling multiplicative factor for the lens potential.

The interpolation is performed using the provided kernels, described in the specific section. Note that, as usual with interpolation, one can specify a tuple of kernels for x and y, or just a single kernel to be used for both coordinates. If no kernel is specified, LanczosKernel{2}() will be used

Parameters: z, potential [, scale] [, kernel]

`MappedDeflection`

Similarly to MappedPotential, this special lens type takes external deflections data mapped on a grid and interpolates them on the image plane as requested. Since the deflection is a vector field, one needs to specify two different external FITS file with identical size and astrometry (WCS) using the data section. Optionally, one can specify a scaling multiplicative factor.

Note that for this lens type no potential is defined: therefore, this lens cannot be used together with Time, TimeDelay, or LuminousTimeDelay sources.

The interpolation is performed using the provided kernel(s), described in the specific section. Note that, as usual with interpolation, one can specify a tuple of kernels for x and y, or just a single kernel to be used for both coordinates. If no kernel is specified, LanczosKernel{2}() will be used

Parameters: z, deflection1, deflection2 [, scale] [, kernel]

`Torus`

This special lens is used solely for testing purposes. It produces a lens that act as a torus, so that it replicate infinitely a patch of the source plane in a chessboard way. The process is controlled by a few parameters. Specifically, the positive number d gives the size of the patch in both directions; the positive parameter k should be set to k = Dₗₛ / Dₛ, where Dₛ is the angular-diameter distance of the source and Dₗₛ is the angular-diameter distance between the lens and the source (both these quantities can be obtained through Gravity.angular_diameter_dist, eventually with the standard cosmology Gravity.default_cosmology). Optionally, one can also specify a constant magnification matrix through the parameters κ or kappa (the convergence), and γ or gamma (the shear).

Parameters: z, x, d, k [, κ] [, gamma].

`LensTool-`type lenses

As a convenience feature, Gravity incorporates specialized lens types defined in terms of the LensTool parameterization. This functionality facilitates the seamless conversion of LensTool models into Gravity-compatible formats.

The LensTool lens types are identified by the prefix LensTool-. These types are available for all isothermal mass models, including SIS, NIS, NIE, JaffeSph, and JaffeEll. Each of these lens types accepts the same set of parameters as the PIEMD lens type in LensTool. Consequently, a LensTool-JaffeSph is functionally equivalent to a LensTool-JaffeEll with zero ellipticity. Similarly, the LensTool-NIS and LensTool-NIE are equivalent to LensTool-JaffeSph and LensTool-JaffeEll, respectively, in the limit where the cutoff radius approaches infinity. Furthermore, the LensTool-SIS model is equivalent to the LensTool-NIS model in the limit of a vanishing core radius.

Elliptical LensTool lenses use as shape parameter the ellipticity ε, defined as $\varepsilon = (a^2 - b^2) / (a^2 + b^2)$, where $a$ and $b$ are the semi-major and semi-minor axes. Note that, with this definition, the axis ratio is $q = b / a = \sqrt{(1 - \varepsilon) / (1 + \varepsilon)}$. Note also that all other parameters (and in particular the velocity dispersion σ) scale in a non-trivial way with ε.

Note also that, following the LensTool notation, the lens position angle is measured in degrees and goes from West to North in astronomical coordinates.

Parameters for LensTool-SIS: z, x, σ.

Parameters for LensTool-NIS: z, x, σ, s.

Parameters for LensTool-NIE: z, x, σ, s, ε, θ.

Parameters for LensTool-JaffeSph: z, x, σ, s, a.

Parameters for LensTool-JaffeEll: z, x, σ, s, a, ε, θ.

`Glee-`type lenses

Similarly, to the Lenstool models, Gravity incorporates specialized lens types defined in terms of the Glee parameterization.

The Glee lens types are identified by the prefix Glee-. These types are available for all isothermal mass models, including SIS, NIS, NIE, JaffeSph, and JaffeEll. Glee uses as strength parameter a quantity associated to the Einstein radius of the lens, which is called E below. The parameter w, instead, is associated to the core radius of the lens, while s is associated to the truncation radius (notice that this differs from the standard Gravity notation, where s is a core radius).

Note also that, following the Glee notation, the lens position angle is measured in radians and goes from West to North in astronomical coordinates.

Parameters for Glee-SIS: z, x, E.

Parameters for Glee-NIS: z, x, E, w.

Parameters for Glee-NIE: z, x, E, w, q, θ.

Parameters for Glee-JaffeSph: z, x, E, w, s.

Parameters for Glee-JaffeEll: z, x, E, w, s, q, θ.