GitHub

Section parameters

This section can be used to specify common constants or common free parameters. For example, in a galaxy cluster one could define the cluster redshift here, and use than this definition to build the lens associated to each member galaxy.

As in many other places in the setup file, the value of a parameter can be a constant (such as 2, 3.12, or π), a valid Julia expression evaluating to a constant (such as sqrt(10) - π) or a distribution. In the last situation, one can proceed in two ways: one can either set the value to a valid distribution from Distributions (such as Uniform(0.3, 0.8), Normal(5.0, 0.2), or Gamma(3.0, 1.2)), or one can use suitable aliases (see below). Parameters defined as a distributions are taken as free parameters: they will be subjects to parameter inference.

The parameter definitions are loaded in sequence, and any parameter, constant or distribution-like, can be used in any following line of the configuration file. This allows one to define easily and in a flexible way linked parameters. For example, one could set x: Uniform(0, 1) and y: -log(x): this way y would not be taken as a free parameter, but as a linked parameter, i.e. as a quantity that can change, but not in a free way.

Finally, note that the expression parameters are evaluated using the Julia parser, and therefore there is a lot of flexibility. One can even use vector parameters, or multivariate distributions.

Aliases

These are the recognized aliases:

  • a .. b is equivalent to Uniform(a, b);

  • x ± σ is equivalent to Normal(x, σ);

  • x ±ᵧ σ is equivalent to Gamma((x / σ)^2, σ^2 / x), i.e. a Gamma distribution with mean x and standard deviation σ;

  • a ±ᵦ b is equivalent to Beta(a, b);

  • (a₁, a₂) .. (b₁, b₂) is equivalent to a multivariate uniform distribution with support in the rectangle [a₁, b₁] × [a₂, b₂];

  • (x₁, x₂) ± σ is equivalent to a bi-variate normal distribution with identical standard deviation σ in both components;

  • (x₁, x₂) ± (σ₁, σ₂) is equivalent to a bi-variate normal distribution with diagonal covariance, characterized by the two standard deviations σ₁ and σ₂;

  • (x₁, x₂) ± (a, b, φ) is equivalent to a bi-variate normal distribution representing an uncertainty ellipse with semi-major axis a, semi-minor axis b, and position angle φ (in radians, measured clockwise from the y-axis);

  • (x₁, x₂) ± (C₁₁, C₁₂, C₁₂, C₂₂), or (x₁, x₂) ± ((C₁₁, C₁₂), (C₁₂, C₂₂)) is equivalent to a bi-variate normal distribution with full covariance C.

  • (q₁, q₂, q₃) ±ᵂ ν is equivalent to Gravity.QWishart([q₁, q₂, q₃], ν), which is like Wishart(ν, [q₁ q₂; q₂ q₃] ./ ν), a Wishart distribution with mean [q₁ q₂; q₂ q₃] and degrees-of-freedom ν. Note that Gravity.QWishart produces vector samples (as required by Gravity), while Wishart produces matrix samples and therefore cannot be used directly.

  • (q₁, q₂, q₃) ±ᴵᵂ ν is equivalent to Gravity.QIWishart([q₁, q₂, q₃], ν), which is like InverseWishart(ν, [q₁ q₂; q₂ q₃] .* ν), an inverse Wishart distribution. Note that Gravity.QIWishart produces vector samples (as required by Gravity), while InverseWishart produces matrix samples and therefore cannot be used directly.

  • (ϵ₁, ϵ₂) ±ₑ ν is equivalent to Gravity.EllipticityDistribution((ϵ₁, ϵ₂), ν). This is a special distribution with support in the unit disk. It is strictly related to the Wishart distribution (in the sense that the ellipticity of a quadrupole sampled from a Wishart distribution is distributed as an ellipticity distribution). ν has the same meaning as for a Wishart distribution: therefore, large values for ν produce tighter distributions.

Special parameters

A few parameters have a special meaning:

  • angular_unit: indicates the unit used in all angular data, including the image positions and associated measurement errors, the lens positions, the lens cores and truncation radii... The value provided must be expressed in arc-seconds. By default, angular_unit: 1.0, so all angular data are taken to be expressed in arc-seconds.

  • wcs_origin: a 2-tuple that indicates the origin, in equatorial coordinates, of the coordinate system used in all angular data. This parameter is only needed for extended images or to interact with external viewers. Together with angular_unit, it can also be specified in the WCS section of the configuration file in a more generic way.

  • background: used to indicate, within the configuration file, the image that should be used as background when plotting the lens model (see the Visual interface page). In its simplest version, this parameter is a single string indicating a local filename or a URL: this can be a FITS file, but also a JPEG, PNG, or TIFF image with suitable astrometry using AVM metadata. Alternatively, one can indicate explicitly the WCS associated to the image using a flexible syntax, as in

    parameters:
  background:
    image: RGB.jpg
    wcs: RGB.fits
    url: https://myniceserver.org/data/RGB.jpg

    As shown in the example above, the background section can include, in addition to the wcs field, a url field. This allows one to specify both a local filename and a remote URL, which is preferentially used by the Aladin plotting backend.

  • use_threads: a comma-separated list of situations where threads are used. Can be any combination of grid (use threads for grid operations), imageplane (image plane operations), lensunmap (inversion of the lens equation), xsources (extended sources), sampling (MCMC sampling operations), blas (BLAS matrix operations), always (all of above), never (never use threads). Additionally, if CUDA is available, the combinations cuda-grid and cuda-xsources are also accepted. The default is use_threads: sampling. See the documentation of Gravity.parse_use_threads for further details.

  • lens_lenses: this boolean value controls the lensing of lenses in multi-plane system. If set to true (the default), the constraints put on lenses located behind other lens planes will be taken as set on the observed properties of these lenses. This will affect both the lens positions, and the lens ellipticities (only for elliptical lenses).

  • stable_lenses: indicates if lens planes are allowed to change order. Can be set to true, meaning that lens planes are guaranteed to have stable rank; false, meaning that lens planes are free to change rank; and auto, in which case the stability of lens planes is deduced from the given setup. In the last case, the code generates many samples from the parameters' prior distributions, computes the lens redshifts, and check if lenses can change rank. Note that for this task, lenses are grouped to the same plane only if their redshifts are identical expressions: thus, if two lenses have as redshifts 0.5 and z, where z is a constant that evaluates to 0.5, they will not be taken to belong to the same plane.

  • strict_priors: if true (the default), a warning message is displayed for point-like sources that have non-standard (i.e., in most cases Gaussian) priors, as they can make the computation of the evidence slightly inaccurate. Can be set to false to avoid this check and the related warning messages.