Tutorial 5: Multiplane Lensing

:::info Migrated from Old Wiki This tutorial was created from content in the old GLEE wiki. Content should be double-checked for accuracy. :::

:::tip Prerequisite Familiarity with single-plane lensing (Tutorials 1-2) is required. This tutorial extends those concepts to multiple deflector planes along the line of sight. :::

Introduction

In multiplane lensing, light from a distant source passes through multiple mass structures at different redshifts before reaching the observer. This is crucial for:

• Line-of-sight galaxy groups/clusters that perturb the main lens
• Hierarchical systems where a background source is itself a lens for an even more distant source
• Cosmological constraints that account for mass distribution along the entire light path

GLEE implements full multiplane ray-tracing, computing deflections iteratively through each plane:

$$\vec{\theta}_{i+1} = \vec{\theta}_1 - \sum_{j=1}^{i} \frac{D_{j,i+1}}{D_{0,i+1}} \vec{\alpha}_j(\vec{\theta}_j)$$

where:

• $\vec{\theta}_i$: position in plane $i$
• $\vec{\alpha}_j$: deflection angle at plane $j$ (for source at $z=\infty$)
• $D_{j,i+1}$: angular diameter distance from plane $j$ to plane $i+1$
• $D_{0,i+1}$: angular diameter distance from observer (plane 0) to plane $i+1$

---

Enabling Multiplane Lensing

To activate multiplane mode, add the following at the top of your config file:

cosmo_H0        70.0
cosmo_OmegaM    0.27
cosmo_OmegaDE   0.73
cosmo_w         -1.0

mlplane  lens_coord_observed

Cosmological Parameters

Keyword	Description	Default
cosmo_H0	Hubble constant (km/s/Mpc)	70.0
cosmo_OmegaM	Matter density parameter	0.27
cosmo_OmegaDE	Dark energy density parameter	0.73
cosmo_w	Dark energy equation of state	-1.0

These are used to compute angular diameter distances $D_d$, $D_s$, $D_{ds}$ for all plane combinations.

:::note Cosmology GLEE assumes a flat ΛCDM cosmology by default. The cosmo_* parameters define the distance-redshift relation needed for multiplane ray-tracing. :::

Multiplane Mode Options

mlplane  lens_coord_observed

or

mlplane  lens_coord_unlensed

Mode	Lens Position Interpretation	Use Case
lens_coord_observed	Lens centers are observed sky positions	Recommended — Directly use measured galaxy positions
lens_coord_unlensed	Lens centers are unlensed positions	Theoretical models where lenses are at their intrinsic positions

:::tip Best Practice Use lens_coord_observed unless you're simulating a system from scratch with known unlensed positions. :::

---

Specifying Lens Planes

In multiplane mode, each lens profile requires a redshift (z) instead of Dds/Ds:

lenses_vary 2
    piemd
    z       0.500    exact:
    0.000   #x-coord   flat:-0.5,0.5   step:0.05
    0.000   #y-coord   flat:-0.5,0.5   step:0.05
    1.000   #b/a       flat:0.5,1.0    step:0.05
    1.571   #theta     flat:0,6.28     step:0.1
    0.800   #theta_e   flat:0.5,1.5    scale:  step:0.05
    0.000   #r_core    flat:0,0.5      step:0.01
    
    piemd
    z       0.700    exact:
   -10.000  #x-coord   flat:-12,− step:0.1
    0.000   #y-coord   flat:-2,2      step:0.1
    1.000   #b/a       flat:0.5,1.0    step:0.05
    0.000   #theta     flat:0,6.28     step:0.1
    0.500   #theta_e   flat:0.2,0.8    scale:  step:0.05
    0.000   #r_core    flat:0,0.5      step:0.01

Key difference from single-plane:

• Single-plane: Dds/Ds specifies distance ratio to specific source
• Multiplane: z specifies absolute redshift; GLEE computes all necessary distance ratios

---

Lens Strength Normalization

:::warning Critical Concept In multiplane mode, lens strengths are normalized to $z_s = \infty$.

For example, for a Singular Isothermal Sphere (SIS):

$$\alpha_j = \theta_{E,j} = \frac{4\pi \sigma_v^2}{c^2}$$

This is independent of source redshift. GLEE applies distance scaling automatically during ray-tracing. :::

Converting Single-Plane → Multiplane

If your single-plane model used Dds/Ds = 1:

Single-plane (observed Einstein radius for specific $z_s$):

Dds/Ds    1.0      exact:
theta_e   0.800    # Observed Einstein radius

Multiplane (Einstein radius for $z_s = \infty$):

z         0.500    exact:
theta_e   ???      # Need to rescale!

Rescaling formula (for profiles with scale: keyword, like SPEMD):

$$\theta_{E,\text{MP}} = \frac{\theta_{E,\text{SP}}}{f + \sqrt{w^2 + f^2}} \cdot \frac{D_s}{D_{ds}}$$

where:

• $\theta_{E,\text{SP}}$: Einstein radius from single-plane model
• $\theta_{E,\text{MP}}$: Einstein radius for multiplane (source at $z=\infty$)
• $f = \frac{D_s}{D_{ds}}$: distance ratio (compute from cosmology + redshifts)
• $w$: core radius (for PIEMD/SPEMD)

For cored profiles without scale:, the conversion is simpler:

$$\theta_{E,\text{MP}} = \theta_{E,\text{SP}} \cdot \frac{D_s}{D_{ds}}$$

:::tip Simplification If your single-plane model already used the actual Dds/Ds value (not 1.0), then:

$$\theta_{E,\text{MP}} = \theta_{E,\text{SP}}$$

No rescaling needed! :::

---

Specifying Source Planes

Source redshifts replace Dds/Ds and Dt:

sources 1
    z         1.000    exact:
    source weighted
    srcx      0.178    exact:
    srcy     -0.027    exact:
    5
    1.000    0.000    error:0.05
    0.000    1.000    error:0.05
    1.000    1.000    error:0.05
   -1.000    0.000    error:0.05
    1.000   -2.000    error:0.05

Key differences:

• Single-plane: Dds/Ds and Dt (time-delay distance)
• Multiplane: z only (GLEE computes all distances from cosmology)

---

Hierarchical Systems (Source = Lens)

A powerful feature: a source at intermediate redshift can itself be a lens for a more distant background source.

Example: Galaxy at $z=0.7$ is lensed by foreground structure at $z=0.5$, while also lensing a quasar at $z=1.5$.

lenses_vary 2
    piemd
    z       0.500    exact:
    # ... main lens parameters
    
    piemd
    z       0.700    exact:
    # ... this galaxy is both a source (for z=0.5 lens)
    #     and a lens (for z=1.5 quasar)

sources 2
    z         0.700    exact:    # Images of the z=0.7 galaxy
    source weighted
    # ... observed images
    
    z         1.500    exact:    # Images of the z=1.5 quasar
    source weighted
    # ... observed images

:::caution Parameter Linking If you want the $z=0.7$ galaxy's mass center to track its source position (as determined by ray-tracing from the $z=0.5$ lens):

Use source parameter instead of source weighted:

sources 1
    z         0.700    exact:
    source parameter           # ← Allow srcx, srcy to be free parameters
    srcx      -5.0    flat:-6,-4   step:0.1   label:gal_src_x
    srcy       0.5    flat:0,1     step:0.1   label:gal_src_y

lenses_vary 2
    piemd
    z       0.700    exact:
   -5.000   #x-coord   link:gal_src_x   a:0,1,1
    0.500   #y-coord   link:gal_src_y   a:0,1,1

This enforces: lens position = source position (accounting for lensing by foreground planes). :::

---

Visualization with gleeview.py

Multiplane systems require specifying which source redshift to visualize:

glee.py -s -z 1.5 -r -3,3,-3,3 -n 200 configfile_multiplane

• -s: Generate data cube
• -z 1.5: Compute convergence/shear for source at $z=1.5$
• -r x0,x1,y0,y1: Field of view (arcsec)
• -n 200: Grid resolution (200×200 pixels)

Output: configfile_multiplane.fits (5-frame cube: $\phi$, $\kappa$, $\alpha_1$, $\alpha_2$, $\gamma$)

:::note Default Behavior If -z is omitted, GLEE uses the redshift of the first source in the sources block. :::

Deflection Angle Frames

Multiplane mode: Deflection angles (frames 3-4) include $D_{ds}/D_s$ scaling for the specified source redshift $z$.

Single-plane mode: Deflection angles exclude $D_{ds}/D_s$ (you must multiply by Dds/Ds manually).

This means convergence $\kappa$ (frame 5) in multiplane mode is correctly scaled for the chosen source redshift.

---

Workflow: Building a Multiplane Model

Step 1: Start from Single-Plane

Use Tutorials 1-2 to get initial parameter estimates for the primary lens at redshift $z_d$.

Step 2: Enable Multiplane

Add cosmology and mlplane keyword:

cosmo_H0        70.0
cosmo_OmegaM    0.27
mlplane  lens_coord_observed

Step 3: Convert Lens Parameters

• Replace Dds/Ds with z for each lens profile
• Rescale $\theta_E$ if necessary (see conversion formulas above)

Step 4: Add Line-of-Sight Structures

Identify perturbers from imaging/spectroscopy:

lenses_vary 3
    piemd
    z       0.500    exact:
    # ... primary lens
    
    nfw
    z       0.350    exact:   # Foreground group
   -20.0    #x-coord   # Observed position from imaging
    15.0    #y-coord
    # ... NFW parameters
    
    piemd
    z       0.650    exact:   # Nearby galaxy
    5.0     #x-coord
   -8.0     #y-coord
    # ... PIEMD parameters

Step 5: Optimize

Run siman + MCMC as usual:

glee.py minimise -o configfile_mp_v2 configfile_mp_v1
glee.py mcmc configfile_mp_v2

Step 6: Check Convergence

Verify that multiplane effects are significant:

glee.py chi2 -c img -- configfile_mp_mcmc_best

Compare $\chi^2_{\text{img}}$ with and without line-of-sight structures.

---

Advanced: Time Delays in Multiplane

Time delays work differently in multiplane:

• Single-plane: Requires Dt (time-delay distance)
• Multiplane: Computes delays automatically from cosmology + ray-tracing

Configuration (same t: syntax as single-plane):

sources 1
    z         1.500    exact:
    source weighted
    srcx      0.178    exact:
    srcy     -0.027    exact:
    4
    1.000    0.000    error:0.05   t:10.5,1.2
    0.000    1.000    error:0.05   t:0,0
    1.000    1.000    error:0.05   t:25.3,2.1
   -1.000    0.000    error:0.05   t:42.1,3.5

Key difference:

• Each observed image position is ray-traced back through all planes to get its source position
• Time delays account for all deflections along the light path
• Source positions may differ slightly for different images (due to multiplane degeneracy)

:::tip Recommendation For Hubble constant measurements, multiplane modeling with line-of-sight corrections is essential to avoid systematic errors from unaccounted mass. :::

---

Common Pitfalls

1. Forgetting to Rescale Einstein Radii

Symptom: Model fits poorly after converting to multiplane.

Solution: Apply the $D_s/D_{ds}$ rescaling (or use Dds/Ds ≠ 1 in single-plane).

2. Linking Issues in Hierarchical Systems

Symptom: GLEE crashes or produces nonsensical results when linking lens position to source position.

Solution: Use source parameter (not source weighted) for intermediate-redshift sources that are also lenses.

3. Visualization at Wrong Redshift

Symptom: Critical curves look wrong in gleeview.py.

Solution: Always specify -z to match the source system you're modeling.

4. Ignoring Line-of-Sight Structures

Symptom: Residuals show systematic patterns; external shear is unexpectedly large.

Solution: Check for nearby galaxies/groups in imaging; add them as additional lens planes.

---

Summary

Feature	Single-Plane	Multiplane
Enable mode	(default)	mlplane lens_coord_observed
Lens redshift	N/A	z value exact: for each profile
Source dist.	Dds/Ds value exact:	z value exact:
Lens strength	For specific source $z_s$	For $z_s = \infty$ (rescale needed!)
Time delays	Requires Dt	Computed from cosmology
Visualization	glee -s	glee -s -z <source_z>
Ray-tracing	Single deflection	Iterative through all planes

:::tip When to Use Multiplane

• Line-of-sight galaxies/groups are visible and likely contributing $\gtrsim 5\%$ convergence
• Hierarchical systems (source at $z_1$ lenses source at $z_2 > z_1$)
• High-precision cosmological constraints (e.g., H0LiCOW, TDCOSMO)
• Source reconstruction with foreground contamination

When single-plane is sufficient:

• Isolated lens, no nearby structures
• Exploratory modeling (multiplane adds complexity) :::

:::tip Next Steps

• Combine multiplane with time delays (Tutorial 4) for full cosmological analysis
• Use external shear to model unconstrained line-of-sight mass (simpler alternative to full multiplane)
• Explore simulation mode (Tutorial 6) to test multiplane recovery :::