Skip to main content

Automated Strong Gravitational Lens Modeling

Project description


When two or more galaxies are aligned perfectly down our line-of-sight, the background galaxy appears multiple times. This is called strong gravitational lensing, & PyAutoLens makes it simple to model strong gravitational lenses, like this one:

.. image:: :width: 400 :alt: Alternative text

PyAutoLens is based on the following papers:

Adaptive Semi-linear Inversion of Strong Gravitational Lens Imaging <>_

AutoLens: Automated Modeling of a Strong Lens's Light, Mass & Source <>_


With PyAutoLens, you can begin modeling a lens in just a couple of minutes. The example below demonstrates a simple analysis which fits the foreground lens galaxy's mass & the background source galaxy's light.

.. code-block:: python

import autofit as af
import autolens as al

import os

# In this example, we'll fit a simple lens galaxy + source galaxy system.
dataset_path = '{}/../data/'.format(os.path.dirname(os.path.realpath(__file__)))

lens_name = 'example_lens'

# Use the relative path to the dataset to load the imaging data.
imaging = al.Imaging.from_fits(
    image_path=dataset_path + lens_name + '/image.fits',

# Create a mask for the data, which we setup as a 3.0" circle.
mask = al.Mask.circular(shape_2d=imaging.shape_2d, pixel_scales=imaging.pixel_scales, radius=3.0)

# We model our lens galaxy using a mass profile (a singular isothermal ellipsoid) & our source galaxy
# a light profile (an elliptical Sersic).
lens_mass_profile =
source_light_profile = al.lp.EllipticalSersic

# To setup our model galaxies, we use the GalaxyModel class, which represents a galaxy whose parameters
# are free & fitted for by PyAutoLens. The galaxies are also assigned redshifts.
lens_galaxy_model = al.GalaxyModel(redshift=0.5, mass=lens_mass_profile)
source_galaxy_model = al.GalaxyModel(redshift=1.0, light=source_light_profile)

# To perform the analysis we set up a phase, which takes our galaxy models & fits their parameters using a non-linear
# search (in this case, MultiNest).
phase = al.PhaseImaging(

# We pass the imaging data and mask to the phase, thereby fitting it with the lens model & plot the resulting fit.
result =, mask=mask)


PyAutoLens's advanced modeling features include:

  • Galaxies - Use light & mass profiles to make galaxies & perform lensing calculations.
  • Pipelines - Write automated analysis pipelines to fit complex lens models to large samples of strong lenses.
  • Pixelizations - Reconstruct complex source galaxy morphologies on a variety of pixel-grids.
  • Adaption - Adapt the lensing analysis to the features of the observed strong lens imaging.
  • Multi-Plane - Perform multi-plane ray-tracing & model multi-plane lens systems.
  • Interferometry - Model radio / sub-mm interferometer data directly in the uv-plane.
  • Visualization - Custom visualization libraries for plotting physical lensing quantities & modeling results.
  • PyAutoFit - Perform fits using many non-linear searches (MCMC, Nested Sampling) and manipulate large result outputs via the probablistic programming language PyAutoFit <>_


Included with PyAutoLens is the HowToLens lecture series, which provides an introduction to strong gravitational lens modeling with PyAutoLens. It can be found in the workspace & consists of 5 chapters:

  • Introduction - An introduction to strong gravitational lensing & PyAutolens.
  • Lens Modeling - How to model strong lenses, including a primer on Bayesian non-linear analysis.
  • Pipelines - How to build model-fitting pipelines & tailor them to your own science case.
  • Inversions - How to perform pixelized reconstructions of the source-galaxy.
  • Hyper-Mode - How to use PyAutoLens advanced modeling features that adapt the model to the strong lens being analysed.


PyAutoLens comes with a workspace, which can be found here <>_ & which includes:

  • Aggregator - Manipulate large suites of modeling results via Jupyter notebooks, using PyAutoFit's in-built results database.
  • API - Illustrative scripts of the PyAutoLens interface, for examples on how to make plots, perform lensing calculations, etc.
  • Config - Configuration files which customize PyAutoLens's behaviour.
  • Dataset - Where data is stored, including example datasets distributed with PyAutoLens.
  • HowToLens - The HowToLens lecture series.
  • Output - Where the PyAutoLens analysis and visualization are output.
  • Pipelines - Example pipelines for modeling strong lenses.
  • Preprocess - Tools to preprocess data before an analysis (e.g. convert units, create masks).
  • Quick Start - A quick start guide, so you can begin modeling lenses within hours.
  • Runners - Scripts for running PyAutoLens pipelines.
  • Simulators - Scripts for simulating strong lens datasets with PyAutoLens.


We're building a PyAutoLens community on Slack, so you should contact us on our Slack channel <>_ before getting started. Here, I will give you the latest updates on the software & discuss how best to use PyAutoLens for your science case.

Unfortunately, Slack is invitation-only, so first send me an email <>_ requesting an invite.

Documentation & Installation

The PyAutoLens documentation can be found at our readthedocs <>, including instructions on installation <>.


If you have any suggestions or would like to contribute please get in touch.


A list of published articles using PyAutoLens can be found here <>_ .



James Nightingale <>_ - Lead developer & PyAutoLens guru.

Richard Hayes <>_ - Lead developer & PyAutoFit <>_ guru.

Ashley Kelly <>_ - Developer of pyquad <>_ for fast deflections computations.

Amy Etherington <>_ - Magnification, Critical Curves and Caustic Calculations.

Xiaoyue Cao <>_ - Analytic Ellipitcal Power-Law Deflection Angle Calculations.

Qiuhan He - NFW Profile Lensing Calculations.

Nan Li <>_ - Docker integration & support.

Code Donors:

Andrew Robertson <>_ - Critical curve & caustic calculations.

Mattia Negrello - Visibility models in the uv-plane via direct Fourier transforms.

Andrea Enia <>_ - Voronoi source-plane plotting tools.

Aristeidis Amvrosiadis <>_ - ALMA imaging data loading.

Conor O'Riordan - Broken Power-Law mass profile.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for autolens, version 0.46.2
Filename, size File type Python version Upload date Hashes
Filename, size autolens-0.46.2-py3-none-any.whl (214.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size autolens-0.46.2.tar.gz (101.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page