HowToGalaxy

Start Here on Colab | Installation Guide | PyAutoGalaxy readthedocs | Browse Chapter 1 With Images | autogalaxy_workspace

Welcome to HowToGalaxy — the tutorial lecture series for PyAutoGalaxy, an open-source library for modeling the light of galaxies.

PyAutoGalaxy can be used with an AI coding agent to compose galaxy models, fit data and explore results using natural language. HowToGalaxy 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 profiles and simulated images, then progress to Bayesian model-fitting, pixelized reconstructions and modeling multiple galaxies.

For experienced scientists who already know the fundamentals of galaxy light profile fitting and Bayesian modeling, the autogalaxy_workspace examples will be more appropriate — they are concise and assume the concepts taught in HowToGalaxy as background.

Chapters

• chapter_1_introduction — An introduction to galaxy morphology and PyAutoGalaxy: grids, light profiles, galaxies, simulated imaging data, and fitting.
• chapter_2_modeling — Bayesian inference, non-linear searches, and how to fit a galaxy model to CCD imaging data with PyAutoGalaxy, ending with search chaining and automated pipelines.
• chapter_3_pixelizations — Pixelized reconstructions (inversions) for galaxies with irregular morphologies, including the Bayesian formalism underpinning them.
• chapter_4_scaling_up_galaxies — Scaling galaxy modeling up beyond a single galaxy: extra galaxies, blended multi-galaxy systems, and cluster fields.
• chapter_optional — Optional tutorials on alternative non-linear searches and other advanced topics.

HowToGalaxy 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 galaxy modeling in the autogalaxy_workspace before returning for the more advanced material in chapters 3 and 4.

Getting Started

Study with the assistant

Use the Jupyter notebooks to run the code (recommended), or read the available Markdown lectures directly on GitHub.

For help alongside the lectures, study with the PyAutoGalaxy AI Assistant in teacher mode. Open Claude Code, Codex or another AI coding agent and paste the prompt below. The agent downloads the assistant and installs PyAutoGalaxy for you:

I want to work through the HowToGalaxy lectures (https://github.com/PyAutoLabs/HowToGalaxy) with the
PyAutoGalaxy Assistant: https://github.com/PyAutoLabs/autogalaxy_assistant
First clone that repository, cd into it and follow its AGENTS.md.

Enter teacher mode. Show me where to find the lectures 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.

Run in Google Colab (nothing to install)

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 — PyAutoGalaxy 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 profiles, galaxies, simulated imaging data, and fitting.

  • Tutorial 0: Visualization — (Colab / markdown)
  • Tutorial 1: Grids and Galaxies — (Colab / markdown)
  • Tutorial 2: Data — (Colab / markdown)
  • Tutorial 3: Fitting — (Colab / markdown)
  • Tutorial 4: Methods — (Colab)
  • Tutorial 5: Summary — (Colab / markdown)

• Chapter 2: Modeling — Practical galaxy models, data and likelihoods, linear profiles and search chaining.

  • Tutorial 1: Non-linear Search — (Colab)
  • Tutorial 2: Practicalities — (Colab)
  • Tutorial 3: Why Modeling Is Hard — (Colab)
  • Tutorial 4: Linear Profiles — (Colab)
  • Tutorial 5: Data and Likelihoods — (Colab)
  • Tutorial 6: Search Chaining — (Colab)
  • Tutorial 7: Summary — (Colab)

• Chapter 3: Pixelizations — Indexed mappings, inversions, regularization and MGE search chaining.

  • Tutorial 1: Pixelizations — (Colab)
  • Tutorial 2: Bayesian Regularization — (Colab)
  • Tutorial 3: Model Fit — (Colab)

• Chapter 4: Scaling Up Galaxies — Extra galaxies, blended multi-galaxy systems, and cluster fields.

  • Tutorial 1: Extra Galaxies — (Colab)
  • Tutorial 2: Multi Galaxy — (Colab)
  • Tutorial 3: Cluster — (Colab)

• Optional Tutorials — Alternative non-linear searches and advanced topics.

  • Alternative Searches — (Colab)
  • Need for Speed — (Colab)
  • Historical Prior Passing — (Colab); not required reading.

Model-fits can run faster on a GPU. In Colab, enable one via Runtime → Change runtime type → Hardware accelerator before running a notebook.

Run on your own machine

Follow the PyAutoGalaxy installation guide, then clone this repository:

git clone https://github.com/PyAutoLabs/HowToGalaxy.git
cd HowToGalaxy

The 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 PyAutoGalaxy use, which is the workflow chapter 3 onwards transitions you to.

Before Chapter 1

Before starting chapter 1, complete scripts/chapter_1_introduction/tutorial_0_visualization.py (or the equivalent notebook). This confirms your PyAutoGalaxy installation, walks you through how images and figures display in Jupyter, and configures matplotlib for the rest of the tutorial series.

Repository Structure

• scripts/ — Runnable Python tutorial scripts, one subfolder per chapter.
• notebooks/ — Jupyter notebook versions of the scripts (auto-generated; see below).
• config/ — PyAutoGalaxy configuration YAML files used by the tutorials.
• dataset/ — Tutorial datasets are generated at runtime by scripts in scripts/simulators/ — no .fits files are committed.
• output/ — Model-fit results (generated at runtime, not committed).

Notebooks vs Scripts

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.

Relationship to autogalaxy_workspace

autogalaxy_workspace is the main user-facing workspace for PyAutoGalaxy — concise examples, guides, and science templates aimed at users who have a working understanding of galaxy morphology and light profile fitting. HowToGalaxy is the teaching companion. Many tutorials in chapters 2–4 reference autogalaxy_workspace scripts as the next place to go after the relevant concept has been introduced.

Citations

If you use HowToGalaxy or PyAutoGalaxy in your research, please cite the references listed in CITATIONS.rst.

Community & Contributing

PyAutoGalaxy 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 PyAutoGalaxy community page.