Section lens-inversion

This optional section can be used to select a few options related to the inversion of the lens equation. This task is required for all schemes except scheme: sourceplane, and therefore is ignored in this case.

grid

This optional key can be set to a tuple of two ranges, indicating the grid specification in pixel units. This is ignore if scheme: sourceplane.

If this key is not specified, the inversion of the lensing equation is obtained using Newton's method with starting points corresponding to the positions of the observed images (see failsafe below). This, often, ensures that one obtain as counter-images of a given source solutions of the lensing equation which are close to the observed images; generally, this method prevents one from discovering other counter-images. Note, also, that this works reasonably only if the lensing model and the source position do not differ too much from the true ones.

The more robust, but much more time-consuming alternative is to generate a grid with this option, and to compute the lens mapping of the grid points. This way, we can find out all approximate solutions of the lens equation by checking which lensed grid cells enclose the putative source position. These approximate solutions are then refined using Newton's method. To proceed this way, one needs to specify the keyword sampling.grid as a tuple of two ranges. For example (-5:0.1:5, -3:0.1:3), produces a rectangular grid with square cells of size 0.1 × 0.1.

grid-refinement

A dictionary used to indicate the maximum refinement levels to be reached for various parts of the main grid, only considered if the grid keyword is present. The accepted keys are

• critical-curves, for the refinements around the lens critical curves at all source redshifts;
• images, for the refinements around the positions of the observed images;
• lenses, for the refinements around the centers of the lenses

If this section is absent, no refinement is carried out: in this case, the grid is static, i.e. it is not updated between iterations (because, effectively, the grid will never change).

failsafe

In some cases, when using a grid to solve the lensing equation it can happen that a source position does not correspond to any image inside the grid, a degenerated situation that would create a vanishing likelihood. To avoid this, one can perform an image search using Newton's method from the source position. This can be done always (always, the default), only if no image is found within the grid (maybe), or never (never).

methods

A dictionary that indicates the list of methods to be used to solve the lens equation. This is ignored for scheme: sourceplane since no lens inversion is performed in this case.

The various methods are tried in cascade in the order provided: if a method succeed, the computation is interrupted and the result is returned.

The recognized methods are

• newton: An advanced Newton-Raphson implementation. Requires the use of derivatives (the Jacobian of the lensing equation), but can deal with singular Jacobian matrices.

• broyden: Broyden's algorithm, a a quasi-Newton method that does not require derivatives. It is generally less stable and often slower than Newton's method, but is less affected by singular solutions.

• klement: An algorithm based on Klement (2014). Does not require derivatives but is often slower and less performant than Broyden's one.

All methods accept the following keywords:

• maxiters: the maximum number of iterations to perform (default: 100);

• xtol: the tolerance in the position to accept a solution: that is, a position is accepted as a solution if, during the algorithm, the position update is smaller than xtol. If set to null, the algorithm does not use xtol as a stopping criterion. The default is xtol: 0.00074 (corresponding to eps(Float64)^0.2).

• ftol: the tolerance in the lens equation to accept a solution: that is, a position is accepted as a solution if, during the algorithm, the computed source-plane position for an image differs by less than ftol from the assumed source position. If set to null, the algorithm does not use ftol as a stopping criterion. The default is ftol: null.

• trust-region: a positive number, indicating the maximum ratio between size of the position correction (|δx|) and the error on the source plane (|δy|): $|\delta x| \le \tt{trustregion} \cdot |\delta y|$. If set to null, the algorithm is unconstrained. The default is trustregion: null.

The special method success can appear as a last item and indicates that, regardless of the effective convergence, the lensing equation is always taken to be solved. In this case, if no solution is found within the tolerance set by xtol and ftol, the last point of the last algorithm is returned.

The current default uses only newton, and is therefore equivalent to the specification

lens-inversion:
    methods:
        newton:
            maxiters: 100
            xtol: 0.00074
            ftol: null
            trustregion: null
        success: