llms.txt

If your AI can't browse GitHub, paste this entire file into the chat as context.

# HowToGalaxy

> The **HowToGalaxy** lecture series: tutorial scripts (and generated notebooks) that teach
> galaxy morphology and the **PyAutoGalaxy** API from first principles. This file is a
> routing layer: given a learner's question, point them to the RIGHT existing tutorial in
> this repository instead of inventing an explanation. Every path below is a real file in
> this repo; scripts run from the repo root (e.g. `python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py`),
> and each has a matching notebook under `notebooks/`.

## Who this is for

HowToGalaxy is the **on-ramp for beginners** — students new to galaxy structure analysis, or
new to PyAutoGalaxy. It teaches the concepts and the API step by step. Once a learner wants
to run a real analysis on their own data, route them *out* to the production examples in
[autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) (see "Ready for
real analysis?" below).

## Start here

- [start_here.ipynb](start_here.ipynb): One-page orientation — what the lectures cover and how to run them (locally or in Colab).
- [scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py](scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py): The first real lecture — galaxy morphology (the Hubble tuning fork), grids, geometry and light profiles. Begin here if the learner is new to galaxy structure.

## The learning path (chapters in order)

- **Chapter 1 — Introduction** → [scripts/chapter_1_introduction/](scripts/chapter_1_introduction/): Galaxies from first principles: grids & galaxies, light profiles, simulating data, and fitting data. The conceptual foundation.
- **Chapter 2 — Modeling** → [scripts/chapter_2_modeling/](scripts/chapter_2_modeling/): Fitting a galaxy model to data with a non-linear search — parameter spaces, priors, dealing with failure, linear light profiles, masking, and reading results.
- **Chapter 3 — Search Chaining** → [scripts/chapter_3_search_chaining/](scripts/chapter_3_search_chaining/): Breaking a hard fit into a sequence of searches (prior passing) and modeling multi-galaxy images.
- **Chapter 4 — Pixelizations** → [scripts/chapter_4_pixelizations/](scripts/chapter_4_pixelizations/): Reconstructing irregular galaxy structure on a pixel-grid instead of with light profiles — mappers, inversions, Bayesian regularization.

## I want to understand…

- **What is a light profile / how is a galaxy's light described?** → [scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py](scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py): Sersic profiles, geometry, projecting light in 1D.
- **How does a telescope image (and noise/PSF) get simulated?** → [scripts/chapter_1_introduction/tutorial_2_data.py](scripts/chapter_1_introduction/tutorial_2_data.py): Optics blurring, Poisson noise, background sky, the simulator API.
- **What does "fitting" a galaxy mean?** → [scripts/chapter_1_introduction/tutorial_3_fitting.py](scripts/chapter_1_introduction/tutorial_3_fitting.py): Masking, model images, residuals and the log likelihood.
- **How does a non-linear search find a model?** → [scripts/chapter_2_modeling/tutorial_1_non_linear_search.py](scripts/chapter_2_modeling/tutorial_1_non_linear_search.py): Parameter space, priors, MLE / MCMC / nested sampling.
- **My fit found a wrong (local-maxima) solution — what do I do?** → [scripts/chapter_2_modeling/tutorial_4_dealing_with_failure.py](scripts/chapter_2_modeling/tutorial_4_dealing_with_failure.py): Prior tuning, reducing complexity, and looking harder.
- **What are linear light profiles / MGE?** → [scripts/chapter_2_modeling/tutorial_5_linear_profiles.py](scripts/chapter_2_modeling/tutorial_5_linear_profiles.py): Solving intensities linearly; the Multi-Gaussian Expansion basis.
- **How do I model an image with two galaxies?** → [scripts/chapter_3_search_chaining/tutorial_3_x2_galaxies.py](scripts/chapter_3_search_chaining/tutorial_3_x2_galaxies.py): Search chaining to handle multi-galaxy degeneracies.
- **How do I reconstruct irregular structure on a pixel grid?** → [scripts/chapter_4_pixelizations/tutorial_1_pixelizations.py](scripts/chapter_4_pixelizations/tutorial_1_pixelizations.py) through [tutorial_4_bayesian_regularization.py](scripts/chapter_4_pixelizations/tutorial_4_bayesian_regularization.py).

## Ready for real analysis?

When the learner wants to model their *own* galaxy (not a teaching dataset), route them to
the production workspace — it has science-case entry points and a data-preparation guide:

- [autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) — see its own `llms.txt` routing layer; e.g. `imaging/start_here.py` for CCD data and its data-preparation guide for getting their FITS files analysis-ready.

## How to answer (for the assistant)

When routing a learner, reply in this shape (the same shape the workspace navigator uses, so
the two agree):

- **Start here** — the single best tutorial for their question (from the lists above).
- **Then see** — the next tutorial in the chapter, or the concept it builds toward.
- **Related guide** — a relevant later chapter, or the matching `autogalaxy_workspace` example for production use.
- **Why this is the right example** — one line tying the tutorial to their question.
- **What to modify** — the few things they'd change to explore (model components, dataset, search settings).
- **What needs local execution** — flag any step that requires actually running the fit on their machine.

### Code style (match the lectures, not banner comments)

Drafted code must match this repo's style: triple-quoted `"""__Section__"""` docstrings with
a line of prose explaining each step, and a module docstring whose title is underlined with
`=`. Do NOT use `# -----` banner comments to mark sections; reserve inline `#` for short
line-level notes only.

## Capability boundary (chat without local execution)

A chat assistant can route to the right tutorial, explain galaxy-structure concepts, review
pasted scripts / tracebacks / plots, and draft code. It CANNOT run fits, inspect the
learner's local files or `output/` folder, or guarantee code against their installed
PyAutoGalaxy version. To run a tutorial, the learner executes it locally from the repo root,
or in Google Colab (the notebooks ship Colab setup cells). For sustained editing, execution
and project state, point them to a local coding agent (Claude Code / Codex).

---

For the full per-tutorial listing, see the generated companion catalogue `llms-full.txt`.