Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (75 loc) · 3.83 KB

AGENTS.md

File metadata and controls

100 lines (75 loc) · 3.83 KB

PyAutoFit — Agent Instructions

Canonical, agent-agnostic instructions for this repo. CLAUDE.md imports this file; any tool that does not process @-imports should read this directly.

What this repo is

PyAutoFit (package autofit) is a probabilistic programming language for model composition, non-linear search, and Bayesian inference: af.Model / af.Collection, the af.Analysis interface, MCMC / nested-sampling / MLE searches, samples, aggregator, and a SQLAlchemy results database.

Dependency direction: autofit depends on autoconf only. It does not import autoarray, autogalaxy, or autolens — never add such an import. Shared utilities (e.g. test_mode, jax_wrapper) belong in autoconf.

Related repos

  • Source siblings: PyAutoConf (upstream). PyAutoGalaxy / PyAutoLens are downstream consumers (they build Analysis subclasses on autofit).
  • autofit_workspace — runnable tutorials/examples (../autofit_workspace).
  • autofit_workspace_test — integration + JAX/likelihood parity scripts.
  • HowToFit — the lecture-style tutorial series (../HowToFit).
  • docs/ — Sphinx source; published to ReadTheDocs.

Quick commands

pip install -e ".[dev]"                       # install with dev/test extras
python -m pytest test_autofit/                # full test suite
python -m pytest test_autofit/non_linear/     # one focused subtree (add -s for output)
black autofit/                                # formatter (advisory — not gated)

In a sandboxed / restricted environment, point numba and matplotlib at writable caches:

NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autofit/

CI / definition of green

PRs must pass pytest --cov on the CI matrix (Python 3.12 and 3.13). There is no black/ruff/flake8 gate — formatting is advisory. (requires-python in pyproject.toml is >=3.9.)

Configuration & defaults

autoconf supplies the packaged defaults under autofit/config/. Workspaces override them via their own config/ directory; the test suite pushes a local config dir via conf.instance.push(...) in test_autofit/conftest.py. When a change adds a new config key, mirror it into the packaged defaults so downstream workspaces inherit it.

Public API

The public surface is defined authoritatively in autofit/__init__.py — read it rather than trusting a hand-maintained list. Canonical import:

import autofit as af

Key subsystems: non_linear/search/ (MCMC: emcee/zeus; nested: dynesty, nautilus, NSS; MLE: LBFGS/BFGS/drawer), mapper/ (model + priors), non_linear/analysis/ (af.Analysis.log_likelihood_function), aggregator/, database/ (SQLAlchemy), graphical/ (expectation propagation), interpolator/.

Key rules / footguns

  • Import direction: autoconf only — never autoarray / autogalaxy / autolens.
  • The [nss] extra (for af.NSS) needs a pinned handley-lab/blackjax fork installed manually after the extras step; that fork conflicts with the mainline blackjax pinned in [optional]. Do not naively combine or bump them — see the install notes in pyproject.toml.
  • All files use Unix line endings (LF, \n) — never \r\n.

Working on issues

  1. Read the issue description and any linked plan.
  2. Identify affected files and make the change.
  3. Run the full suite: python -m pytest test_autofit/.
  4. If you changed public API, say so explicitly — downstream packages (PyAutoGalaxy, PyAutoLens) and the workspaces may need updates.
  5. Ensure all tests pass before opening a PR.

Clean state

Never rewrite history on a repo with a remote (no git init over a tracked tree, no force-push to main, no rebasing pushed shared branches). To reset a dirty tree the only correct sequence is:

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