Section `sources`

The last section of the configuration is used to specify the set of observed sources and the associated images. The code is designed to accommodate for various kind of sources: parametric point sources, parametric extended sources, and non-parametric extended sources.

A typical source section looks like the following

sources:
    - Point:
        name: S1 
        z: 0.609
        x: (0, 0) ± 10
        images:
            - Point:
                x: (0.34, -1.50) ± 0.03
            - Point:
                x: (-0.94, 0.68) ± 0.04
            - Point:
                x: (1.52, 0.19) ± 0.02
    - Luminous:
        name: S2
        z: 0.609
        x: (0, 0) ± 10
        mag: 15 ± 15
        images:
            - Luminous:
                name: S2a
                x: (-1.16, 0.22) ± 0.03
                mag: 18.3 ± 0.1
            - Luminous:
                name: S2b
                x: (1.44, 0.88) ± 0.03
                mag: 19.2 ± 0.1

Essentially, each source is characterized by a few parameters, and is followed by an images sub-section, used to list all observed images associated to the source. Note how the images associated to each source must be of the same type (Point sources will have Point images).

Similarly to the Section lenses, a few standard parameters have fixed meaning:

name: is the name associated to the source. This is optional, and only provided as a convenience feature.
scheme: is an optional parameter useful to set the fitting scheme to be used for each specific source and associated image family. If it is not specified, the default sampling.scheme is used instead.
z: is the redshift of the source. Sources located at identical redshifts will be put on the same SourcePlane. This applies both to constant redshifts, as well as to the cases where the redshift is a free parameter.
x: is the source position, specified as tuple (x₁, x₂). It is expressed with respect to the global coordinate system, so in units of angular_unit. If desired, one can use wcsmap(α, δ) to covert on the fly celestial coordinates into global ones.
mag: is the source magnitude.
Q: is the source quadrupole moment, specified a tuple (Q₁₁, Q₁₂, Q₂₂).
t: is the (relative) time delay of the source, in days.

For the source position x, the user can specify the special function fiducialposition. This function takes, as parameters, a list of image positions (with optional associated errors), and returns the fiducial position of the images in the source plane, i.e.\ a weighted average of the mapped points. If no errors are entered, the function produces an exact source position, obtained as a weighted average of the projected coordinates; otherwise, if errors are entered, these are projected into the source plane and an uncertain source position is generated. The position is parametrized by an automatically generated parameter ending with _fiducial, which is normally distributed. All this machinery is based on Gravity.fiducialposition, with the first two (or three) arguments automatically filled in. A typical use therefore would be

    x: fiducialposition((1.4772, 0.5532) ± 0.002, (2.4687, -0.6033) ± 0.004, (0.9377, -1.6147) ± 0.003)

Note that, for point sources, the use of this function in scheme: imageplane is essentially equivalent to use a scheme: simplified-imageplane. This function, therefore, is generally useful only for parametric extended sources.

Parametric point sources

The simplest source types are parametric point-like sources, mainly characterized by their position (and optionally by additional parameters, such as the luminosity or the time-delay).

Parametric point sources will generally have many of their parameter unknown. Therefore, one will typically specify a relatively broad distribution for them. The distribution of source parameters are completely free, and the user can therefore use whatever is more appropriate for the specific problem. However, some simplified inference modes make specific assumptions on a few key source parameters. The reason for this is discussed in detail elsewhere. Here, we just mention that if the free parameters use the specific distributions discussed below, then Gravity is able to estimate correctly the evidence of the model even in fast modes such as scheme: sourceplane, scheme: simplified-imageplane, scheme: imageplane, or scheme: extended-imageplane. In particular

x should follow a bi-variate normal (Gaussian) distribution, and therefore a typical source position could be expressed as x: (2.13, 3.54) ± 0.05.
mag should follow a normal (Gaussian) distribution, as in mag: 18.34 ± 0.1.
Q should follow an inverse Wishart distribution. This can be specified with the convenient notation Q: (6.3, -1.8, 4.2) ±ᴵᵂ 18.3, where the first triplet indicates the mean quadrupole moment $(Q_{11}, Q_{12}, Q_{22})$, and the last number $\nu$ the degrees-of-freedom of the distribution. Alternatively, one can specify the distribution with the notation IWishart(a, b, φ, ν), where a and b are the semi-axes of the mean shape, and φ the position angle (measured clockwise from the vertical direction). Note that $2 / \sqrt{\nu}$ is approximately the relative error on the semi-axes.
t should follow a normal (Gaussian) distribution, similarly to mag.

The associated images must have the same parameters as the source, except the redshift z, which of course is the same for source and images. Therefore, for example, the images associated to a Luminous source will have as parameters x and mag.

`Point`

A point source with associated position only.

Parameters: z, x

Example:

- Point:
    z: 3.278
    x: (0, 0) ± 10
    images:
        - Point:
            x: (0.278, -3.218) ± 0.05
        - Point:
            x: (-2.314, 1.780) ± 0.05

`Luminous`

A luminous source, characterized by position and magnitude. The source position x, if unknown, can have any distribution. However, if one uses a bi-variate normal (Gaussian) distribution for the source position, then Gravity is able to estimate correctly the evidence of the model even in fast mode (such as scheme: sourceplane or scheme: simplified-imageplane).

Parameters: z, x, mag

Example:

- Luminous:
    z: 3.278
    x: (0, 0) ± 10
    mag: 15 ± 15
    images:
        - Luminous:
            x: (0.278, -3.218) ± 0.05
            mag: 21.3 ± 0.2
        - Luminous:
            x: (-2.314, 1.780) ± 0.05
            mag: 22.5 ± 0.3

`Elliptical`

A small elliptical source, characterized by position, magnitude, and quadrupole moment.

The quadrupole moment associated to the source, if kept as free parameters, should follow an inverse Wishart distribution and can be entered using the syntax (Q₁₁, Q₁₂, Q₂₂) ±ᴵᵂ ν, where (Q₁₁, Q₁₂, Q₂₂) represent the components of average quadrupole, and ν the degrees of freedom of the distribution: large values of ν corresponds to increasingly constrained quadrupoles.

Alternatively, one can describe the source shape using the elliptical radius r = sqrt(a * b), the axis ratio q = b / a, and the position angle θ (North to West in astronomical sense, in radians). @@@

The measured quadrupole moments of the images are taken to follow a Wishart distribution. They can be entered as (Q₁₁, Q₁₂, Q₂₂) ±ᵂ ν or, more conveniently, as Wishart(a, b, θ, ν), to use the standard parameters a (semi-major axis), b (semi-minor axis), and θ (position angle).

Parameters: z, x, mag, Q

Example:

- Elliptical:
    z: 3.278
    x: (0, 0) ± 10
    mag: 15 ± 15
    Q: IWishart(3.0, 3.0, 0.0, 4.0)
    images:
        - Elliptical:
            x: (0.278, -3.218) ± 0.05
            mag: 21.3 ± 0.2
            Q: Wishart(4.0, 2.1, -0.87, 31.2)
        - Elliptical:
            x: (-2.314, 1.780) ± 0.05
            mag: 22.5 ± 0.3
            Q: Wishart(2.8, 2.5, 0.43, 27.2)

`Time`

A point source with an associated measurement of time events (in days).

Parameters: z, x, t

Example:

- Time:
    z: 3.278
    x: (0, 0) ± 10
    t: 0 ± 100
    images:
        - Time:
            x: (0.278, -3.218) ± 0.05
            t: 0.0 ± 0.001
        - Time:
            x: (-2.314, 1.780) ± 0.05
            t: 15.3 ± 0.2

`TimeDelay`

A point source with an associated time-delay measurement (in days). The time-delay measurements use the first image as reference (which, therefore, should have a vanishing value for the time parameter). A positive value for the time delay for an image indicates that a given feature in the light curve of the image will be seen after the same feature is observed in the first source.

Errors in the time delay measurements can be represented as usual using the ± notation. Alternatively, one can specify a full covariance matrix for the time delays using the t_cov field. This should be a vector with increasing number of entries (absent or null for the first image). The vector represents a line in the lower triangular part of the covariance matrix. The values given in t_cov must be measured in squared days.

Source parameters: z, x

Image parameters: x, t, t_cov

Example:

- TimeDelay:
    z: 3.278
    x: (0, 0) ± 10
    images:
        - TimeDelay:
            x: (0.278, -3.218) ± 0.05
            t: 0.0
        - TimeDelay:
            x: (-2.314, 1.780) ± 0.05
            t: 15.3
            t_cov: [0.12]
        - TimeDelay:
            x: (3.214, -2.340) ± 0.05
            t: 27.3
            t_cov: [-0.04, 0.23]

`LuminousTimeDelay`

This is a special point source with associated both time-delay measurement (in days) and magnitude (differences) between the various images. Both the time-delay and the magnitude measurements use the first image as reference (which, therefore, should have a vanishing value for the time parameter). Time-variable images can have their magnitude measured only in conjunction with their time delays: in practice one needs to shift the time-delay curves horizontally (to fit the time-delay) and vertically (to fid the magnitude difference) until a good match among the various images is obtained. As a result, these measurements will have magnitude and time measurements correlated.

Errors in the magnitude measurements can be represented as usual using the ± notation. Alternatively, one can specify a magnitude covariance matrix using the mag_cov field. This should be a vector with increasing number of entries (absent or null for the first image). The vector represents a line in the lower triangular part of the covariance matrix.

Similarly, errors in errors in the time delay measurements can be represented using the ± notation or entered in the t_cov field. This too should be a vector with increasing number of entries (absent or null for the first image). The vector represents a line in the lower triangular part of the covariance matrix. The values given in cov must be measured in squared days.

Finally, the cross-covariance between magnitude and time-delay measurements can be entered in the mag_t_cov field. This should be a vector representing a row in the covariance matrix; it must be also null or absent for the first image. For the i+1 image, this vector will report the correlation between the magnitude measurement of this image and all the time-delays.

Source parameters: z, x

Image parameters: x, mag, mag_cov, t, t_cov, mag_t_cov

Example:

- LuminousTimeDelay:
    z: 2.318
    x: (0, 0) ± 10
    images:
        - LuminousTimeDelay:
            x: (0.278, -3.218) ± 0.05
            mag: 17.2
            t: 0.0
        - LuminousTimeDelay:
            x: (-2.314, 1.780) ± 0.05
            mag: 18.3
            t: 18.3
            mag_cov: [0.28]
            t_cov: [0.12]
            mag_t_cov: [0.02, -0.05]
        - LuminousTimeDelay:
            x: (3.214, -2.340) ± 0.05
            mag: 19.2
            t: 35.3
            mag_cov: [0.03, 0.42]
            t_cov: [-0.04, 0.23]
            mag_t_cov: [0.04, 0.03]

Parametric extended sources

Parametric extended sources represent the surface brightness of a source with an analytic expression, with a number of parameters.

Parametric extended sources can be used to describe both the light distribution of lensed sources and of other objects (such as galaxies acting as lenses or field galaxies). In order to use any extended source, including the parametric ones described here, it is necessary to use the wcs and data sections of the configuration file.

Moreover, these sources will include images that refer to an appropriate dataset. For example, a parametric source might appear in the configuration file as

sources:
    - XElliptical:
        z: 1.0
        x: (1.0, 1.0) ± 1.0
        flux: 1.2 ± 0.3
        Q: (10.0, 2.0, 6.0) ±ᴵᵂ 12.0
        profile: exponential()
        images:
            - XElliptical:
                data: rband
                maskids: 1
            - XElliptical:
                data: rband
                maskids: [7, 9]

As shown here, the images associated to extended sources typically refer to external data (rband in the example). This label refers to a dataset and the two images defined here are associated to the pixels that have mask = 1 (in the first case) or mask ∈ (7,8) in the second. Note how, for extended sources, there is no clear definition of a single image: often, indeed, a part of a source is multiply lensed, while another part is not. Therefore, it is a responsibility of the user to decide how to separate the various images: in the example above, it would be possible to have three images, each with a different maskid, or even a single image, with maskids: [1, 7, 9]. The results will be identical, but the computations will be carried out in a slightly different way, since the PSF convolution will be done individually for each image.

`XSky`

The simplest extended "source" one can consider is a flat sky background. This source should be typically put at redshift z = 0. It is characterized by a constant background level, with an optional gradient (computed with respect to the source position x).

Source parameters: z (should be set to zero), x, level [, gradient]

Image parameters: data, maskids

`XCircular`

Represents an extended source with a circular profile. This source type includes as parameters the redshift z, the center of the profile x, the radius r, and the flux (typically representing the peak surface brightness of source in ADUs).

This source has an associated profile, specified with the profile: field, which can be any of the following (more details can be found in the library documentation)

gaussian(): a Gaussian profile $\propto \exp(-r^2/2)$;
exponential(): an exponential profile $\propto \exp(-r)$;
isothermal(): a singular isothermal profile, with light distribution $\propto 1 / r$;
softisothermal(): a non-singular pseudo-isothermal profile, with light distribution $\propto 1 / \sqrt{1 + r^2}$;
plummer(): a Plummer profile $\propto 1 / (1 + r^2)^2$;
jaffe(): a Jaffe profile $∝ 1 / (r^2 (1 + r^2))$;
hernquist(): an Hernquist profile;
powerlaw(γ): a power-law profile $\propto r^{1 - \gamma}$;
softpowerlaw(γ): a softened power-law profile $\propto (1 + r^2)^{(1 - \gamma)/2}$;
devaucouleurs(): a de Vaucouleurs $r^{1/4}$ profile;
sersic([n = 4]): a Sérsic profile $\exp(-b_n r^{1/n})$; the term $b_n$ is chosen so that $r$ is one at the half-light radius;
profile(fun): a generic user-defined profile, defined in terms of the function fun. The function must take a single argument, representing the square of the elliptical radius of the source.

Additionally, one can modify and combine profiles using a set of operators:

+ sums two different profiles, both centered in the same position;
* scale "vertically" a profile, i.e. changes its flux by a real value;
% scale "horizontally" a profile, i.e. changes its size.

For example, the luminosity profile of a spiral galaxy could be parametrized as

profile: 0.8 * exponential() + 0.2 * devaucouleurs() % 0.1

to indicate an exponential profile with embedded a de Vaucouleurs profile that is 10 times smaller. The factors 0.8 and 0.2 ensures that the peak flux is not modified.

Source parameters: z, x, flux, r, profile

Image parameters: data, maskids

Example:

sources:
    - XCircular:
        z: 1.0
        x: (1.0, 1.0) ± 1.0
        flux: 1.0 .. 20.0
        r: 2.0 .. 5.0
        profile: hernquist()
        images:
            - XCircular:
                data: rband
                maskids: 1
            - XCircular:
                data: rband
                maskids: 2

`XElliptical`

Represents an extended source with an elliptical profile. This source is essentially identical to XCircular, with the notable difference that it uses as parameter the quadrupole moment Q instead of the radius r (see above the description of elliptical sources for possible distributions to use in the inference of the quadrupole moment).

All other parameters have the same meaning as in XCircular.

Source parameters: z, x, flux, Q, profile

Image parameters: data, maskids

Example:

sources:
    - XElliptical:
        z: 1.0
        x: (1.0, 1.0) ± 1.0
        flux: 1.0 .. 20.0
        Q: IWishart(5.0, 5.0, 0.0, 4.0)
        profile: (1-bulge_frac) * exponential() + bulge_frac * devaucouleurs() % bulge_scale
        images:
            - XElliptical:
                data: rband
                maskids: 1
            - XElliptical:
                data: rband
                maskids: 2

`XComposite`

As we have seen, circular and elliptical extended provide already a lot of flexibility, since their radial profiles can be composed using several radial functions. However, sometimes one might want to build an extended source using components that might not share the same center or the same ellipticity. This happens naturally for sources with complex profiles (for example, lenticular galaxies), or for clustered sources (pairs or triplets of galaxies).

In principle, one could just describe these situations using several individual sources. However, from a computational point of view, this is inefficient, as the ray-tracing and convolution would be performed for each source independently.

For this reason, Gravity.jl allows one to use composite extended sources. These are extended sources which have a special components field, where one can list all the objects that make the source. Each component must be either an XCircular, an XElliptical, or an XSky source. Note that the components should not include any redshift z field, as this is common among all of them and has to be specified for the XComposite source.

As for other contexts, it is possible to specify the components from an external catalog with the loop construct.

Source parameters: z, components

Image parameters: data, maskids

Example:

sources:
    - XComposite:
        name: lenticular
        z: 1.0
        components:
            - XCircular:
                name: bulge
                x: (1.0, 1.0) ± 1.0
                flux: 1.0 .. 20.0
                r: 0.1 .. 2
                profile: devaucouleurs()
            - XElliptical:
                name: disk
                x: sources_lenticular_XComposite_components_bulge_XCircular_x
                flux: 1.0 .. 50.0
                Q: IWishart(5.0, 5.0, 0.0, 4.0)
                profile: devaucouleurs()
        images:
            - XElliptical:
                data: rband
                maskids: 1
            - XElliptical:
                data: rband
                maskids: 2

`XVelocity`

Represents an extended velocity field of a disk-like source (typically, a spiral galaxy). This source, in addition to the redshift z, has a few associated geometric parameters: the center of the profile x, the position angle θ, and the inclination angle ϕ, defined as the angle between the galaxy angular momentum and the line of sight (in radians). A face-on galaxy therefore will have ϕ = 0 or ϕ = π, while an edge-on galaxy will have ϕ = π/2.

The light profile of the source is described by the field flux-profile, which can be any of the profiles described above. Additionally, one has to specify a velocity-profile field, which describes the way the (square of) the tangential velocity changes as a function of the distance from the galaxy center, because the rotational velocity of a galaxy is proportional to $M(<r) / r$.

Note that the two profiles will be in general different: the velocity-profile should include all mass components of the galaxy (including the dark-matter one), since they all concur to the total mass and therefore they all shape the (square) velocity; the flux-profile, instead, depends on the components of the galaxy that emit the flux associated to the velocity measurements: this, typically, is only the disk component of the galaxy, where star-formation emission lines are detected.

Both profiles can be composed with the +, *, and % operators. The meaning of the various operators is as described above: % introduces a spatial rescaling, * can be used to multiply the profiles by a constant, and + can be used to compose profiles. An important difference is that * used with a constant $k$ introduces a rescaling in flux by $k$, but a rescaling in velocity by $\sqrt{k}$: this happens because the velocity is associated to the square root of the mass.

Note also that an XVelocity source does not include any explicit flux or size parameter, since the frequent use of composed profiles would make these not very useful.

The source includes a bulk velocity parameter v, to take into account a constant velocity in the entire field.

The images section of this source is necessarily more complicated than standard extended sources, as it is associated to two datasets: one, introduced by the field flux-data, is for flux measurements; a second, introduced by the field velocity-data, is for flux-weighted velocity measurements (i.e., measurements representing as the product of a velocity field times the flux).

Source parameters: z, x, θ, ϕ, v, flux-profile, velocity-profile

Image parameters: flux-data, velocity-data, maskids

Example:

sources:
    - XVelocity:
        z: 1.0
        x: (1.0, 1.0) ± 1.0
        θ: -π .. π
        ϕ: -π/2 .. π/2
        flux-profile: flux_disk * exponential() % scale_disk
        velocity-profile: mass_disk * exponential() % scale_disk + mass_bulge * hernquist() % scale_bulge + mass_halo * nfw % scale_halo
        images:
            - XVelocity:
                flux-data: rband
                velocity-data: rvband
                maskids: 1
            - XVelocity:
                flux-data: rband
                velocity-data: rvband
                maskids: 2

XStamp

A special source that is mostly useful in simulations. It is composed of a fixed set of pixel values, specified in a way similar to images. The pixels are then mapped back to the image plane using a chosen interpolation kernel, as specified with the kernel parameter (see the specific section on interpolations). If not specified, BSpline{2}() will be used.

Source parameters: z, data, maskids [, kernel]

Image parameters: data, maskids

Example:

sources:
    - XStamp:
        z: 1.0
        data: source_simulation
        maskids: [1,2]
        kernel: Drizzler()
        images:
            - XStamp:
                data: example
                maskids: [1, 3]
            - XStamp:
                data: example
                maskids: [2]

Non-parametric extended linear sources

The most general extended sources that can be used in Gravity are non-parametric extended linear sources. These are extended sources that can be characterized by a large (potentially infinite) number of parameters. Most importantly, these sources produce surface brightness maps that are linearly dependent on the parameters, hence their name. The associated theory is discussed in detail in a dedicated page.

Non-parametric sources whose images overlap need to be jointly modeled. For this reason, the user has to specify the for each dataset used for non-parametric sources present in the data section, a set of clans, i.e. image families that will be jointly processed. A non-parametric source needs to be associated to one and only one clan: therefore, all its images must belong to the same clan (but can belong to different datasets).

`XPixelated`

Represents a pixelated extended source, i.e. a source described in terms of a rectangular grid of pixels.

The grid parameter indicates the regular grid used for the description of the source. The grid can be optionally re-adapted depending on the position of the projected images on the source plane. The way this is performed depends on the value of the parameter geometry.

If geometry is set to fixed, no re-adaptation is performed: the grid is used as specified by the user, regardless of the mapped image positions. One would normally use this option only when the lensing parameters are all fixed.

More usually, one might want to adapt the grid to the lensed images. If geometry is set to fixed_dx_dy, the grid is adapted keeping fixed the pixel scale, and therefore depending on the area occupied by the projected images one might end up using a very large grid. This is often too computationally depending and should be avoided during the inference of the lensing parameters.

A similar situation is obtained when geometry is set to snapped_dx_dy. In this case the grid has the provided pixel sizes, and additionally it is snapped to integer pixels. This is useful to combine multiple sources on a common grid.

A viable option is to set geometry to fixed_nx_ny: in this case the grid is adapted by keeping the grid size, i.e. the number of rows and column, fixed. As a result, pixels will be generally not square (even if the user has originally specified squared pixels).

Another possibility is to use bounded_n: in this case the algorithm produces a grid that does not exceed the total pixel numbers originally specified, but will adapt the number of rows and columns of the grid to match the image. This is done keeping the pixel aspect ration unchanged: therefore, if the original grid has squared pixels, pixels will always remain squared. This is the default.

Note that in all cases where a geometry adaptation is performed, the grid is build in a way to leave a frame of two pixels around the mapped image locations. This significantly mitigates the boundary effects associated with the regularization.

The kernel parameter must represent an interpolation kernel, as described in the specific section. If not specified, LanczosKernel{2}() will be used.

The λ parameter controls the regularization. Currently, Gravity implements a discrete just a Laplacian regularization. This is usually set to a small number and, often, is left as a free parameter.

Source parameters: z, grid, kernel, λ, geometry

Image parameters: data, maskids

Example:

sources:
    - XPixelated:
        z: 1.2
        grid: (0.00:0.01:0.5, 0.00:0.01:0.5)
        kernel: BSpline{2}()
        λ: 2e-3
        geometry: bounded_n
        images:
            - XPixelated:
                data: vband
                maskids: [1, 3]
            - XPixelated:
                data: vband
                maskids: 2