Skip to content

CLAUDE.md

Latest commit

 

History

History
104 lines (72 loc) · 4.82 KB

CLAUDE.md

File metadata and controls

104 lines (72 loc) · 4.82 KB

HowToGalaxy

This is the HowToGalaxy tutorial lecture series for PyAutoGalaxy, a Python library for galaxy morphology modeling. Tutorials teach new users how to model galaxy light from first principles.

Repository Structure

  • scripts/ — Runnable Python tutorial scripts
    • chapter_1_introduction/ — Grids, light profiles, galaxies, data, fitting
    • chapter_2_modeling/ — Non-linear searches, Bayesian inference, galaxy modeling
    • chapter_3_search_chaining/ — Search chaining, prior passing, automated pipelines
    • chapter_4_pixelizations/ — Pixelized galaxy reconstruction, inversions, regularization
    • chapter_optional/ — Alternative non-linear searches and advanced topics
    • simulators/ — Simulator scripts that generate the tutorial datasets at runtime
  • notebooks/ — Jupyter notebook versions of scripts (generated from scripts/, do not edit directly)
  • config/ — PyAutoGalaxy configuration YAML files
  • dataset/ — Empty in the repo; tutorial datasets are written here at runtime by the simulator scripts
  • output/ — Model-fit results (generated at runtime, not committed)

Running Scripts

Scripts are run from the repository root so relative paths to dataset/ and output/ resolve correctly:

python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py

Tutorials in chapters 1 and 2 that need a dataset invoke the relevant script in scripts/simulators/ via subprocess if the dataset folder does not already exist — there is no manual simulate-then-run step.

Integration testing / fast mode: set PYAUTO_TEST_MODE=1 to skip non-linear search sampling:

PYAUTO_TEST_MODE=1 python scripts/chapter_2_modeling/tutorial_1_non_linear_search.py

Fast smoke tests: combine test mode with the skip flags:

PYAUTO_TEST_MODE=2 PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_SKIP_VISUALIZATION=1 PYAUTO_SKIP_CHECKS=1 PYAUTO_FAST_PLOTS=1 python scripts/chapter_1_introduction/tutorial_5_summary.py

Note: PYAUTO_SMALL_DATASETS is deliberately not used in HowToGalaxy. Tutorials assume the full-resolution simulated datasets that the simulator scripts produce.

Codex / sandboxed runs: set writable cache directories so numba and matplotlib do not fail on unwritable home paths:

NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py

Core API Patterns

Imports used throughout the tutorials:

import autofit as af
import autogalaxy as ag
import autogalaxy.plot as aplt

Notebooks vs Scripts

Notebooks in notebooks/ are generated from the .py files in scripts/ using generate.py from the PyAutoBuild repo. Always edit the .py scripts, never the notebooks directly. The # %% marker alternates between code and markdown cells.

Building Notebooks

Run from the workspace root:

PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtogalaxy

The howtogalaxy project target needs to be added to PyAutoBuild/autobuild/config.yaml. This is a known follow-up from the initial bootstrap.

Relationship to autogalaxy_workspace

HowToGalaxy is the teaching companion to autogalaxy_workspace. Many tutorials (particularly in chapters 2–4) point users to autogalaxy_workspace scripts (e.g. scripts/imaging/modeling.py, scripts/guides/...) as the next destination after the relevant concept has been introduced. Those cross-references use absolute paths like autogalaxy_workspace/scripts/... and refer to the separate autogalaxy_workspace repository — not to anything inside HowToGalaxy.

Related Repos

  • PyAutoGalaxy source: ../PyAutoGalaxy
  • autogalaxy_workspace: ../autogalaxy_workspace — main user-facing workspace
  • PyAutoBuild: ../PyAutoBuild — notebook generation and CI/CD tooling

Never rewrite history

NEVER perform these operations on any repo with a remote:

  • git init in a directory already tracked by git
  • rm -rf .git && git init
  • Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset for AI workflow", or any equivalent message on a branch with a remote
  • git push --force to main (or any branch tracked as origin/HEAD)
  • git filter-repo / git filter-branch on shared branches
  • git rebase -i rewriting commits already pushed to a shared branch

If the working tree needs a clean state, the only correct sequence is:

git fetch origin
git reset --hard origin/main
git clean -fd

This applies equally to humans, local Claude Code, cloud Claude agents, Codex, and any other agent. The "Initial commit — fresh start for AI workflow" pattern that appeared independently on origin and local for three workspace repos is exactly what this rule prevents — it costs ~40 commits of redundant local work every time it happens.