Skip to main content

Open-Source Strong Lensing

Project description

PyAutoLens: Open-Source Strong Lensing

.. |nbsp| unicode:: 0xA0 :trim:

.. |binder| image:: :target:

.. |code-style| image:: :target:

.. |JOSS| image:: :target:

.. |arXiv| image:: :target:

|binder| |code-style| |JOSS| |arXiv|

Installation Guide <>_ | readthedocs <>_ | Introduction on Binder <>_ | HowToLens <>_

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 and PyAutoLens makes it simple to model strong gravitational lenses, like this one:

.. image::

Getting Started

The following links are useful for new starters:

  • The introduction Jupyter Notebook on Binder <>_, where you can try PyAutoLens in a web browser (without installation).

  • The PyAutoLens readthedocs <>, which includes an installation guide <> and an overview of PyAutoLens's core features.

  • The autolens_workspace GitHub repository <>, which includes example scripts and the HowToLens Jupyter notebook tutorials <> which give new users a step-by-step introduction to PyAutoLens.

API Overview

Lensing calculations are performed in PyAutoLens by building a Tracer object from LightProfile, MassProfile and Galaxy objects. Below, we create a simple strong lens system where a redshift 0.5 lens Galaxy with an EllIsothermal MassProfile lenses a background source at redshift 1.0 with an EllExponential LightProfile representing a disk.

.. code-block:: python

import autolens as al
import autolens.plot as aplt
from astropy import cosmology as cosmo

To describe the deflection of light by mass, two-dimensional grids of (y,x) Cartesian
coordinates are used.
grid = al.Grid2D.uniform(
    shape_native=(50, 50),
    pixel_scales=0.05,  # <- Conversion from pixel units to arc-seconds.

The lens galaxy has an elliptical isothermal mass profile and is at redshift 0.5.
mass =
    centre=(0.0, 0.0), elliptical_comps=(0.1, 0.05), einstein_radius=1.6

lens_galaxy = al.Galaxy(redshift=0.5, mass=mass)

The source galaxy has an elliptical exponential light profile and is at redshift 1.0.
disk = al.lp.EllExponential(
    centre=(0.3, 0.2),
    elliptical_comps=(0.05, 0.25),

source_galaxy = al.Galaxy(redshift=1.0, disk=disk)

We create the strong lens using a Tracer, which uses the galaxies, their redshifts
and an input cosmology to determine how light is deflected on its path to Earth.
tracer = al.Tracer.from_galaxies(
    galaxies=[lens_galaxy, source_galaxy], cosmology=cosmo.Planck15

We can use the Grid2D and Tracer to perform many lensing calculations, for example
plotting the image of the lensed source.
tracer_plotter = aplt.TracerPlotter(tracer=tracer, grid=grid)

With PyAutoLens, you can begin modeling a lens in just a couple of minutes. The example below demonstrates a simple analysis which fits the lens galaxy's mass with an EllIsothermal and the source galaxy's light with an EllSersic.

.. code-block:: python

import autofit as af
import autolens as al
import autolens.plot as aplt

Load Imaging data of the strong lens from the dataset folder of the workspace.
imaging = al.Imaging.from_fits(

Create a mask for the imaging data, which we setup as a 3.0" circle, and apply it.
mask = al.Mask2D.circular(
    shape_native=imaging.shape_native, pixel_scales=imaging.pixel_scales, radius=3.0
imaging = imaging.apply_mask(mask=mask)

We model the lens galaxy using an elliptical isothermal mass profile and
the source galaxy using an elliptical sersic light profile.
lens_mass_profile =
source_light_profile = al.lp.EllSersic

To setup these profiles as model components whose parameters are free & fitted for
we set up each Galaxy as a Model and define the model as a Collection of all galaxies.
lens_galaxy_model = af.Model(al.Galaxy, redshift=0.5, mass=lens_mass_profile)
source_galaxy_model = af.Model(al.Galaxy, redshift=1.0, disk=source_light_profile)
model = af.Collection(lens=lens_galaxy_model, source=source_galaxy_model)

We define the non-linear search used to fit the model to the data (in this case, Dynesty).
search = af.DynestyStatic(name="search[example]", nlive=50)

We next set up the `Analysis`, which contains the `log likelihood function` that the
non-linear search calls to fit the lens model to the data.
analysis = al.AnalysisImaging(dataset=imaging)

To perform the model-fit we pass the model and analysis to the search's fit method. This will
output results (e.g., dynesty samples, model parameters, visualization) to hard-disk.
result =, analysis=analysis)

The results contain information on the fit, for example the maximum likelihood
model from the Dynesty parameter space search.


Support for installation issues, help with lens modeling and using PyAutoLens is available by raising an issue on the GitHub issues page <>_.

We also offer support on the PyAutoLens Slack channel <>, where we also provide the latest updates on PyAutoLens. Slack is invitation-only, so if you'd like to join send an email <> requesting an invite.

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 2021.8.12.1
Filename, size File type Python version Upload date Hashes
Filename, size autolens-2021.8.12.1-py3-none-any.whl (138.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size autolens-2021.8.12.1.tar.gz (8.1 MB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page