Start Here on Colab | Installation Guide | PyAutoLens readthedocs | Browse Chapter 1 With Images | autolens_workspace
Welcome to HowToLens — the tutorial lecture series for PyAutoLens, an open-source library for strong gravitational lens modeling.
PyAutoLens can be used with an AI coding agent to compose lens models, fit data and explore results using natural language. HowToLens teaches the core principles behind this workflow, so you understand the science and inference being performed rather than treating them as a black box.
The tutorials assume minimal prior knowledge of astronomy or statistics. They start from first principles: grids, light and mass profiles, and ray-tracing, then progress to Bayesian lens modeling, pixelized source reconstructions and group- and cluster-scale lenses.
For experienced scientists who already know the fundamentals of strong lensing and Bayesian modeling, the autolens_workspace examples will be more appropriate — they are concise and assume the concepts taught in HowToLens as background.
chapter_1_introduction— An introduction to strong gravitational lensing and PyAutoLens: grids, light and mass profiles, galaxies, ray-tracing, point sources, the lensing formalism, simulated imaging data, and fitting.chapter_2_lens_modeling— Bayesian inference, non-linear searches, and how to fit a lens model to CCD imaging data with PyAutoLens, ending with search chaining and automated pipelines.chapter_3_pixelizations— Pixelized source reconstructions (inversions) for sources with irregular morphologies, including the Bayesian formalism underpinning them.chapter_4_scaling_up_lensing— Scaling lens modeling up beyond a single lens galaxy: extra galaxies, multi-galaxy lenses, scaling relations, group and cluster scales, and weak lensing.chapter_optional— Optional tutorials on alternative non-linear searches and other advanced topics.
HowToLens currently sits at four chapters. Each chapter will take around a day to work through.
We recommend completing chapters 1 and 2, then applying what you've learned to real lens modeling in the
autolens_workspace before returning for the more advanced material in chapters 3 and 4.
Use the Jupyter notebooks to run the code (recommended), or read the available Markdown lectures directly on GitHub.
For help alongside the lectures, open the autolens_assistant repository in your AI coding agent, following its setup instructions, and paste:
Enter teacher mode.
I want to work through the HowToLens lectures. Show me where to find them
and how to use Jupyter Notebook or Markdown, then help me with questions
as I go.
The assistant can answer questions about concepts, equations, code and results as you study, and help with notebook errors. Share the lecture link and section or the cell you are working on; you choose when to move on.
Every tutorial opens in Google Colab in one click. There is nothing to install on your own machine and no local Python environment to set up — PyAutoLens installs itself in the notebook's first cell. In Colab you run the tutorial: edit the code, change the model, and see the output for yourself.
Whilst in Colab, you can use Gemini as a study assistant alongside the lecture: ask it to explain an equation, unpack what a cell is doing, or help interpret the output of a fit.
The markdown links are the same tutorial already executed and rendered on GitHub, with its real
output figures inline. Nothing runs and nothing installs — you just read it. They are good for
skimming a tutorial before running it, or for reading on a phone. Markdown pages currently exist only
for the chapter 1 tutorials listed with a markdown link below; every other tutorial is Colab-only.
Start Here — a one-page overview of the whole series.
- Chapter 1: Introduction — Grids, light and mass profiles, galaxies, ray-tracing, point sources, the lensing formalism, data, and fitting.
- Tutorial 0: Visualization — (Colab / markdown)
- Tutorial 1: Grids and Galaxies — (Colab / markdown)
- Tutorial 2: Ray Tracing — (Colab / markdown)
- Tutorial 3: More Ray Tracing — (Colab / markdown)
- Tutorial 4: Point Sources — (Colab / markdown)
- Tutorial 5: Lensing Formalism — (Colab / markdown)
- Tutorial 6: Data — (Colab / markdown)
- Tutorial 7: Fitting — (Colab / markdown)
- Tutorial 8: Summary — (Colab / markdown)
- Chapter 2: Lens Modeling — Bayesian inference, non-linear searches, lens modeling, search chaining, prior passing, and SLaM pipelines.
- Tutorial 1: Non-linear Search — (Colab)
- Tutorial 2: Practicalities — (Colab)
- Tutorial 3: Realism and Complexity — (Colab)
- Tutorial 4: Dealing with Failure — (Colab)
- Tutorial 5: Linear Profiles — (Colab)
- Tutorial 6: Masking and Positions — (Colab)
- Tutorial 7: Results — (Colab)
- Tutorial 8: Need for Speed — (Colab)
- Tutorial 9: Search Chaining — (Colab)
- Tutorial 10: Prior Passing — (Colab)
- Tutorial 11: SLaM — (Colab)
- Chapter 3: Pixelizations — Pixelized source reconstructions, inversions, the Bayesian formalism, and adaptive pixelizations and regularization.
- Tutorial 1: Pixelizations — (Colab)
- Tutorial 2: Mappers — (Colab)
- Tutorial 3: Inversions — (Colab)
- Tutorial 4: Bayesian Regularization — (Colab)
- Tutorial 5: Bayesian Formalism — (Colab)
- Tutorial 6: Borders — (Colab)
- Tutorial 7: Lens Modeling — (Colab)
- Tutorial 8: Adaptive Pixelization — (Colab)
- Tutorial 9: Model Fit — (Colab)
- Tutorial 10: Fit Problems — (Colab)
- Tutorial 11: Brightness Adaption — (Colab)
- Tutorial 12: Adaptive Regularization — (Colab)
- Chapter 4: Scaling Up Lensing — Extra galaxies, multi-galaxy lenses, scaling relations, group and cluster scales, and weak lensing.
- Optional Tutorials — Alternative non-linear searches and advanced topics.
- Tutorial Optional: Searches — (Colab)
Model-fits can run faster on a GPU. In Colab, enable one via Runtime → Change runtime type → Hardware accelerator before running a notebook.
Follow the PyAutoLens installation guide, then clone this repository:
git clone https://github.com/PyAutoLabs/HowToLens.git
cd HowToLensThe tutorials are distributed as both Jupyter notebooks (notebooks/) and Python scripts (scripts/).
We recommend the notebooks for reading — images and plots render inline, and you can step through small
code blocks interactively. Use the Python scripts for actual PyAutoLens use, which is the workflow
chapter 3 onwards transitions you to.
Before starting chapter 1, complete scripts/chapter_1_introduction/tutorial_0_visualization.py
(or the equivalent notebook). This confirms your PyAutoLens installation, walks you through how images
and figures display in Jupyter, and configures matplotlib for the rest of the tutorial series.
HowToLens assumes minimal previous knowledge of gravitational lensing. It is helpful to have the following lecture course on gravitational lensing by Massimo Meneghetti open as you go through the tutorials:
http://www.ita.uni-heidelberg.de/~massimo/sub/Lectures/gl_all.pdf
scripts/— Runnable Python tutorial scripts, one subfolder per chapter.notebooks/— Jupyter notebook versions of the scripts (auto-generated; see below).config/— PyAutoLens configuration YAML files used by the tutorials.dataset/— Tutorial datasets are generated at runtime by scripts inscripts/simulator/— no.fitsfiles are committed.output/— Model-fit results (generated at runtime, not committed).
Notebooks in notebooks/ are generated from the Python files in scripts/. Always edit the ``.py``
scripts, never the notebooks directly. The # %% markers in each script alternate between code and
markdown cells, which PyAutoHands uses to produce the
.ipynb files.
autolens_workspace is the main user-facing workspace
for PyAutoLens — concise examples, guides, and science templates aimed at users who have a working
understanding of strong lensing. HowToLens is the teaching companion. Many tutorials in chapters 2–4
reference autolens_workspace scripts as the next place to go after the relevant concept has been
introduced.
If you use HowToLens or PyAutoLens in your research, please cite the references listed in
CITATIONS.rst.
PyAutoLens is built in the open by its users: everyone is welcome to ask questions, share what they have made with it, and contribute.
Questions, ideas and bug reports: the PyAutoLabs Discussions. Chat with us on Slack.
Community-built tools and tutorials, and how to contribute: the PyAutoLens community page.