The GLEE Configfile

A configfile is the primary control file for GLEE, used to define the full lensing model, source properties, optimisation algorithm, PSF, masks, image input files, etc. It is a structured plain text file that GLEE reads to perform different stages of gravitational lens modelling.

Structure of the Configfile

Not everything discussed here is included in a single configfile. For instance, one may want to do a mass model using only image positions and no extended source.

Global Settings

This section defines the optimisation and sampling strategy, including the type of $\chi^2$ to minimise, the annealing and MCMC settings, the use of a covariance matrix for efficient sampling, as well as the cosmological model parameters and options for enabling multiplane lensing.

Chi-Squared Type

chi2type           1

This integer controls what components are included in the $\chi^2$ minimisation. It is a bitwise flag, so multiple types can be added together:

Value	Meaning
1	Source plane positions
2	Image plane positions
4	Include magnification constraints
8	Fit to critical curves
16	Extended source fitting
128	Time delays

Example: A value of chi2type = 146 (2 + 16 + 128) tells GLEE to optimise using image plane positions, extended sources, and time delay constraints.

Optimiser

minimiser       siman
seed            2

• siman: Simulated annealing (the standard optimiser in GLEE, for other options for optimisers seeglee.py).
• seed: Sets the random number generator seed—useful for reproducibility.

Siman Parameters

Simulated annealing is a global optimisation algorithm inspired by thermodynamics. The system explores the parameter space with a "temperature" that gradually cools, allowing it to escape local minima early and focus on refinement later.

GLEE implements this with the following parameters:

siman_iter          1
siman_nT         1000
siman_dS           10
siman_Sf          1.1
siman_k             2
siman_Ti           10
siman_Tf          1.1
siman_Tmin          1

• siman_iter: Number of annealing cycles (usually 1)
• siman_nT: Steps per temperature (1e3–1e5). For point sources, 1e4–1e5 is recommended. For extended sources, 1e3 is usually sufficient.
• siman_dS: Initial global step size scaling
• siman_Sf: Step-size shrinkage per temperature ($dS_j = dS / Sf^j$)
• siman_k: Analog of Boltzmann constant in $\exp(-E/kT)$
• siman_Ti: Initial temperature
• siman_Tf: Temperature reduction factor ($T_j = Ti / Tf^j$)
• siman_Tmin: Final temperature

For more information on Simulated Annealing, see the Wikipedia entry.

MCMC Sampling

After optimisation, GLEE can sample the posterior probability distribution using MCMC.

mcmc_n         100000
mcmc_dS           0.3
mcmc_dSini          0
mcmc_k              2

• mcmc_n: Number of steps in the chain
• mcmc_dS: Global scaling of parameter step sizes
• mcmc_dSini: 0 = use defined steps; 1 = random steps
• mcmc_k: Acceptance parameter (same meaning as in siman)

Pro Tip

A good rule of thumb is to tune mcmc_dS so that the acceptance rate is around 25% ± 5% (seeDunkley et al., 2005).

Proposal Distribution for MCMC (Covariance Matrix)

In MCMC, the proposal distribution determines how the algorithm suggests new points in parameter space based on the current parameter values and a covariance matrix.

sampling_f     gaussian
sampling_cov   /fake/path/to/matrix.cov

• sampling_f: Form of the proposal distribution (usually gaussian).
• sampling_cov: A covariance matrix to inform how parameter steps are correlated and scaled. This improves convergence and acceptance rates.

If no covariance matrix is given, GLEE will use step sizes defined directly in the configfile (via step: on each parameter).

Cosmological Model

cosmo_H0         70.000000  flat:1,150 
cosmo_OmegaM      0.300000  exact:
cosmo_OmegaDE     0.700000  exact:
cosmo_w          -1.000000  exact:

These parameters define the cosmological model assumed for the lens model (typically Flat $\Lambda$CDM).

• cosmo_H0: Hubble constant in km/s/Mpc. If you’re doing time-delay cosmography, you typically let cosmo_H0 vary (e.g. flat:0,150).
• cosmo_OmegaM: Matter density parameter $\Omega_m$ (typically fixed to 0.3).
• cosmo_OmegaDE: Dark energy density $\Omega_\Lambda$ (typically fixed to $1 - \Omega_m = 0.7$).
• cosmo_w: Dark energy equation-of-state parameter (typically fixed to $w = -1$).

Multiplane Lensing

To activate multiplane lensing (modelling multiple lens planes at different redshifts), you must specify the keyword:

mlplane      lens_coord_observed

• lens_coord_observed: Coordinates are given in the observed (image) plane.
• lens_coord_unlensed: Coordinates are in the unlensed source plane.

Softening Radius

Some profiles (such as the Elliptical Navarro–Frenk–White (eNFW)) make use of a softening radius r_soft to avoid numerical singularities. The default is 1e-4. Reset this to a new value with:

Rsoft  1e-05

---

Lens Mass Parameters

This is where the mass distribution of the lensing galaxy (or galaxies) is defined using models listed in the Mass Profiles section.

Example for an epl + shear model:

lenses_vary 2              

    epl
    z         1.23000  exact:
    4.000000  #x-coord   noprior:  step:0.001 
    4.000000  #y-coord   noprior:  step:0.001
    0.800000  #b/a       flat:0.3,1  step:0.01
    1.600000  #theta     noprior:  step:0.05
    1.500000  #theta_e   flat:0.75,2.5  step:0.01
    2.500000  #gam       exact:  step:0.01

    shear
    z         1.23000  exact:                   
    0.10      #magnitude   flat:0,0.3    step:0.01
    1.30      #theta       flat:0,6.30   step:0.01

Important

The redshifts (z 1.23000 exact:) must be included when doing multiplane lensing!

---

Point-like Sources Parameters

This section defines the model for point-like lensed sources (quasars, supernovae). It specifies the source position, estimation methods, and multiple lensed image uncertainties.

sources 1
    z         2.3      exact:
    Dds/Ds    1.00000  exact:
    Dt	      4.00000  exact:
    source weighted
    srcx      3.516893 exact:
    srcy      3.834896 exact:
    4
    3.307154  4.952908 error:0.004 t:0,0
    5.408441  4.828180 error:0.004 t:-1,10
    2.566705  3.181805 error:0.004 t:-1,10
    4.562741  2.864456 error:0.004 t:-1,10

Important

• Include z 1.23000 exact: for multiplane lensing.
• Include Dds/Ds 1.00000 exact: for single-plane lensing.
• Include Dt 4.00000 exact: when optimising for time delays in single-plane lensing.

---

Extended Sources Parameters

The esources section specifies how GLEE models extended lensed emission (arcs, background galaxies). This includes science images, error maps, PSF models, masks, and regularisation settings. There is one esources section for every band being modelled.

esources 1
    z                           1.2345 exact:
    Dds/Ds                      1.000000  exact:
    esource_ngy                 20       
    esource_ngx                 120      
    esource_dx                  0.08      
    esource_data                /path/to/Science.fits
    esource_err                 /path/to/ErrorMap.fits
    esource_wht                 /path/to/InverseVariance.fit
    esource_arcmask             /path/to/ArcMask.fits
    esource_lensmask            /path/to/LensMask.fits
    esource_noise_model_mask    /path/to/NoiseMask.fits
    esource_mod_light           LensOnly  
    esource_psf                 /path/to/PSF.fits
    esource_sub_agn_psf         /path/to/PSF_AGN.fits
    esource_sub_agn_psf_factor  3
    ...
    esource_end

• esource_ngx / esource_ngy: Number of pixels in the source reconstruction grid (x and y).
• esource_dx: Pixel size (in arcseconds) of the science image and source grid.
• esource_refcoord: Lower-left corner pixel coordinates of the science image. Defaults to (dx, dx).
• esource_data: Path to the science image .fits.
• esource_err / esource_wht: RMS noise map ($\sigma$) or inverse variance map ($1/\sigma^2$).
• esource_arcmask: FITS mask for pixels included in arc/source modelling.
• esource_lensmask: FITS mask isolating the system (masking perturbers).
• esource_mod_light: Toggles LensOnly mode (fits only lens light, no arcs).
• esource_psf: Path to the grid resolution PSF.
• esource_sub_agn_psf_factor: Subsampling factor of the AGN PSF (must be odd: 3, 5, 7).
• esource_regtype: Regularisation scheme (zeroth, grad, curv, quad).
• esource_regopt: Optimisation strategy for regularisation strength $\lambda$. Recommended: SpecRegPrecSigFigOnce.

---

Linking Parameters

In GLEE, you can link one parameter to another so its value is dynamically computed.

• Assign a name with label:<name>.
• Reference it later with link:<name> a:a1,a2,a3.

sersic
    2.00000  # x-coord   label:lenslightx1
...
sersic
    2.00000  # x-coord   link:lenslightx1 a:0,1,1

This uses the formula: $x_{\text{profile2}} = a_1 + a_2 \cdot (x_{\text{profile1}})^{a_3}$

In this example: $x_{\text{profile2}} = 0 + 1 \cdot (x_{\text{profile1}})^1 = x_{\text{profile1}}$.

Execution Order

GLEE processes parameters in the order they appear in the config. Always define parameters with label before the ones that link to them. If you link to a label defined further down, GLEE will use an outdated, un-updated value.

---

Parameter Flags

Priors

• exact: Fix the parameter to a constant value.
• flat:X,Y Uniform prior between X and Y.
• gaussian:mean,std Gaussian prior, e.g., N(8, $2^2$).
• noprior: No prior applied.
• file: Use a custom prior defined in an external file.

Bounds

• min:X / max:Y: Restrict parameter values (e.g., min:3 max:10).

Step Size

• step:X: Standard deviation of the Gaussian random steps for sampling (e.g. step:1.4 means $\sigma = 1.4$). Overridden if sampling_cov is active.

Logarithmic Sampling

• log: Samples the parameter in $\log_{10}$ space. All priors and steps are interpreted in log space (e.g. flat:-1,1 equates to values between 0.1 and 10). Only certain parameters support this.