pysm: Instructions file for Codex

Repository Guidelines

Project Overview

PySM (Python Sky Model) generates full-sky simulations of Galactic foreground emissions in intensity and polarization for Cosmic Microwave Background (CMB) experiments. It uses HEALPix pixelization via healpy and supports MPI parallelization.

Project Structure & Key Files

src/pysm3/
├── __init__.py          # Public API exports
├── sky.py               # Main Sky class for combining components
├── models/              # Sky model implementations (dust, synchrotron, CMB, etc.)
├── utils/               # Helper functions for map I/O, smoothing
├── units.py             # Unit conversion utilities (uses astropy.units)
├── mpi.py               # MPI distribution helpers
└── data/                # Model configuration files (TOML)

tests/
├── test_dust.py         # Dust model tests
├── test_synchrotron.py  # Synchrotron model tests
├── test_cmb.py          # CMB model tests
└── test_*.py            # Other component tests

docs/
├── *.ipynb              # Tutorials; selected files are executed by pytest/nbval
├── preprocess-templates/ # Large, data-producing notebooks; not executed in CI
├── conf.py              # Sphinx configuration
└── *.rst                # RST documentation files

Quick Start Commands

# Setup environment
uv venv .venv && source .venv/bin/activate
uv pip install -e .[test]

# Run tests (includes notebook validation)
uv run pytest -v

# Run specific test file
uv run pytest tests/test_dust.py -v

# Lint the Python files changed by your patch
uv run flake8 PATH/TO/CHANGED_FILE.py --count --max-line-length=100

# Execute one notebook into a separate output file (nbconvert is not in the test extra)
uv run --with nbconvert jupyter nbconvert --to notebook --execute INPUT.ipynb \
  --output OUTPUT.ipynb

# Build documentation
uv run --extra docs sphinx-build -W -b html docs docs/_build/html

# Coverage report
uv run pytest --cov pysm3 --cov-report=xml

Important: the full test suite (including notebook validation) is slow and is run by GitHub Actions on every push / pull request. While working on a bug fix or a feature, run only the tests attached to that change (e.g. uv run pytest tests/test_<component>.py -q), not the whole suite.