llms.txt

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

# PyAutoGalaxy Workspace

> Example and tutorial scripts (and generated notebooks) for modelling the morphologies and
> structures of galaxies — light and mass profiles, single-plane galaxies — with **PyAutoGalaxy**.
> This is galaxy morphology, NOT lensing (no ray-tracing, no source reconstruction — the
> `multi_galaxy/` and `cluster/` packages model those systems' LIGHT, e.g. blended pairs and
> BCG + member-population fields). This file is a routing layer: given a user's task, point them to the RIGHT existing
> script/notebook/guide in this workspace instead of inventing code. Every path below is a real file
> in this repository; scripts are run from the repo root (e.g. `python scripts/imaging/start_here.py`).

## New to galaxy morphology?

- [HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy): The from-first-principles tutorial lecture series that teaches galaxy morphology modeling and the PyAutoGalaxy API. The on-ramp for beginners — start here before the workspace examples below.

## Start here

- [start_here.py](start_here.py) / [start_here.ipynb](start_here.ipynb): Top-level overview of PyAutoGalaxy's features and API (galaxies, light/mass profiles, fitting, JAX) — the single best first read.
- [scripts/imaging/start_here.py](scripts/imaging/start_here.py): Model a single galaxy in CCD imaging (HST/JWST/ground-based) with minimal setup — ~15 min to point at your own FITS files.
- [scripts/interferometer/start_here.py](scripts/interferometer/start_here.py): Interferometer (e.g. ALMA) entry point — fits complex visibilities in the uv-plane, not CCD images.
- [scripts/multi_dataset/start_here.py](scripts/multi_dataset/start_here.py): Multi-wavelength / multi-dataset entry point — simultaneous fit of the same galaxy across datasets taken at different wavelengths.
- [scripts/multi_galaxy/start_here.py](scripts/multi_galaxy/start_here.py): Blended multi-galaxy systems (interacting/close pairs) — one free light model per galaxy, fitted simultaneously.
- [scripts/cluster/start_here.py](scripts/cluster/start_here.py): Cluster fields — a BCG modeled individually plus a catalogue-driven member population (one shared free normalization).

## I want to…

- **Simulate galaxy imaging data** → [scripts/imaging/simulator.py](scripts/imaging/simulator.py): Overview of the galaxy simulation API; builds a Sersic bulge + Exponential disk galaxy to `.fits` CCD imaging (more cases in `simulator_sample.py` and `simulator_sersic.py`).
- **Model galaxy light & mass in CCD imaging** → [scripts/imaging/modeling.py](scripts/imaging/modeling.py): Full imaging modeling API (model composition, masking, over-sampling, search) — the detailed companion to `imaging/start_here.py`.
- **Use linear light profiles** → [scripts/imaging/features/linear_light_profiles/modeling.py](scripts/imaging/features/linear_light_profiles/modeling.py): Solve each profile's `intensity` via linear algebra (an inversion) instead of as a free parameter — recommended over standard profiles.
- **Multi Gaussian Expansion (MGE)** → [scripts/imaging/features/multi_gaussian_expansion/modeling.py](scripts/imaging/features/multi_gaussian_expansion/modeling.py): Decompose galaxy light into ~15–100 Gaussians to capture asymmetric/irregular structure no single Sersic can fit.
- **Pixelized / inversion reconstruction of irregular light** → [scripts/imaging/features/pixelization/modeling.py](scripts/imaging/features/pixelization/modeling.py): Reconstruct a galaxy's clumpy/irregular light on a regularized pixel-grid mesh (bulge Sersic + pixelization); export the reconstruction via [galaxy_reconstruction.py](scripts/imaging/features/pixelization/galaxy_reconstruction.py).
- **Model interferometer / ALMA (uv-plane) data** → [scripts/interferometer/modeling.py](scripts/interferometer/modeling.py): Detailed uv-plane modeling API fitting complex visibilities directly.
- **Multi-wavelength / multi-dataset modeling** → [scripts/multi_dataset/modeling.py](scripts/multi_dataset/modeling.py): Detailed API for jointly fitting multiple datasets of one galaxy.
- **Model 2+ blended galaxies simultaneously** → [scripts/multi_galaxy/modeling.py](scripts/multi_galaxy/modeling.py): One free MGE per galaxy via the list-based `galaxy_0`/`galaxy_1` API; per-galaxy decomposition and photometry of the blend.
- **Model a cluster field's light (BCG + members from a catalogue)** → [scripts/cluster/modeling.py](scripts/cluster/modeling.py): Members loaded from `scaling_galaxies.csv` with intensities tied to catalogue luminosities through one shared free normalization; refinements (shared free shapes, promoting bright members).
- **Ellipse fitting (non-parametric morphology)** → [scripts/ellipse/modeling.py](scripts/ellipse/modeling.py): Fit a distribution of ellipses to a galaxy's isophotes — non-parametric morphology, no light-profile model; see also [multipoles.py](scripts/ellipse/multipoles.py) and [fit.py](scripts/ellipse/fit.py).
- **Load & inspect results from `output/`** → [scripts/guides/results/start_here.py](scripts/guides/results/start_here.py): Load a completed fit back into Python (`Galaxies`, `Model`, samples, model images) from a fit's `output/...` folder, via `.json` and `.fits` files or the database.
- **Compute galaxy quantities (luminosity, flux, sizes)** → [scripts/guides/galaxies.py](scripts/guides/galaxies.py): Extract and visualize a fitted galaxy's light profiles and derived quantities; for absolute flux / magnitude / luminosity calibration see [scripts/guides/units/flux.py](scripts/guides/units/flux.py).
- **Prepare data (image / noise map / PSF)** → [scripts/imaging/data_preparation/start_here.py](scripts/imaging/data_preparation/start_here.py): Data standards (pixel scale, image, noise-map, PSF) your dataset must meet; per-product detail in [examples/data.py](scripts/imaging/data_preparation/examples/data.py), [examples/noise_map.py](scripts/imaging/data_preparation/examples/noise_map.py), [examples/psf.py](scripts/imaging/data_preparation/examples/psf.py).
- **API guides (light profiles, units, plotting)** → [scripts/guides/](scripts/guides/): Reference guides — e.g. [profiles/light.py](scripts/guides/profiles/light.py), [units/cosmology.py](scripts/guides/units/cosmology.py), [data_structures.py](scripts/guides/data_structures.py), and the `plot/`, `modeling/`, `advanced/`, `hpc/` subfolders.

## How to answer (for the assistant)

When routing a user, reply in this shape:

- **Start here** — the single best existing file for their task (from the lists above).
- **Then see** — the deeper/detailed companion file (e.g. `start_here.py` → `modeling.py`).
- **Related guide** — a relevant page under `scripts/guides/` (results, units, plotting, profiles).
- **Why this is the right example** — one line tying the file to their specific need.
- **What to modify** — the few lines they'd change for their case (dataset path, model components, profiles, search settings).
- **What needs local execution** — flag any step that requires actually running the fit on their machine.

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

Drafted code must match this workspace's style: use triple-quoted `"""__Section__"""` docstrings
with a line of prose explaining each step, and give a full script a module docstring whose title is
underlined with `=`. Do NOT use `# -----` banner comments to mark sections. Reserve inline `#` for
short line-level notes only. The standard imports are `import autofit as af`,
`import autogalaxy as ag`, `import autogalaxy.plot as aplt`.

Write this:

```python
"""__Mask__

Apply a 3.0" circular mask to the imaging data.
"""
mask = ag.Mask2D.circular(shape_native=dataset.shape_native, pixel_scales=0.1, radius=3.0)
```

Not this:

```python
# ----- Mask -----
mask = ag.Mask2D.circular(shape_native=dataset.shape_native, pixel_scales=0.1, radius=3.0)
```

## Capability boundary (chat without local execution)

A chat assistant can route to the right file, explain galaxy-morphology concepts, review pasted
scripts / tracebacks / plots, and draft code. It CANNOT run fits, inspect the user's local files or
`output/` folder, or guarantee code against their installed PyAutoGalaxy version. To actually run
something, the user should execute the script locally from the repo root, or in Google Colab (the
`start_here` scripts ship Colab setup cells). For sustained editing, execution, and project state,
point them to a local coding agent (Claude Code / Codex) or the
[autogalaxy_assistant](https://github.com/PyAutoLabs/autogalaxy_assistant) science-assistant
workspace.

## Scientific context

For scientific background — Sersic profiles, bulge–disk decomposition, MGE, isophote analysis,
scaling relations, high-z structure and more — consult the
[autogalaxy_assistant](https://github.com/PyAutoLabs/autogalaxy_assistant) literature wiki
(`wiki/literature/` — concept pages, survey/instrument entities, per-topic annotated
bibliographies, every citation verified). Start from its `wiki/literature/index.md`.

---

For the full per-script listing, see the generated companion catalogue `llms-full.txt`. It is large
(tens of thousands of tokens and growing) — intended for local coding agents that can grep it. In a
browser chat (GitHub connector), do NOT fetch it wholesale: route from this file's lists and read only
the specific script you need.