# haloemu

> DEGRACE-pilot halo- and matter-property emulator suite. Per-(property, gravity,
> redshift) Gaussian-process emulators behind one registry, for LCDM and f(R)
> (fRn1) gravity. Split out of the `halocat` repo; uses it (and optionally
> `freyja`) only at TRAINING time. Prediction is portable: the trained artifacts
> ship in the package and run on a plain pip install (PyPI deps only).

One call does almost everything:

```python
import os; os.environ.setdefault("JAX_PLATFORMS", "cpu")
from haloemu import get_registry
reg = get_registry()
reg.predict(prop, gravity, z, theta)   # prop/gravity/z key + raw theta vector
```

Conventions (the common pitfalls):
- theta = [Omega_m, h, n_s, S_8] for LCDM, + logf_R0 for fRn1. Pass S_8, NOT sigma_8 (S_8 = sigma_8*sqrt(Omega_m/0.3)).
- Registered z: 0.25 (all properties); 0.00 (hmf, pk_mm, xi_mm only). Both gravities LCDM, fRn1.
- Run via `micromamba run -n cosemu python3`; set JAX_PLATFORMS=cpu. Heavy work to slurm (dp004, cosma8-serial).
- ξ near the BAO and all velocity moments cross zero: accuracy is χ=residual/SEM, not fractional.
- Frozen-seed +2–3% large-scale offset in ξ/ξ_hh (pk_mm closed via low-k anchor; ξ open).

## Docs

- [Home](index.md): overview, headline accuracy, audiences.
- [Getting started](getting-started.md): install, first prediction, CLI, tests.
- [The registry](concepts/registry.md): keys, redshift snapping, theta conventions, design ranges.
- [Representations](concepts/representations.md): what each emulator actually emulates; f(R) seed-paired boosts.
- [Suite design](concepts/design.md): 64-cosmology design, plugin abstraction, core engine, phases.
- [Properties overview](properties/index.md): all keys, shapes, coordinates.
- [HMF — n(>M)](properties/hmf.md)
- [Matter clustering — pk_mm, xi_mm](properties/matter-clustering.md)
- [Halo bias — b_cum, b_diff](properties/bias.md)
- [Halo clustering — xi_hh, xi_hh_smallr, r_ab](properties/halo-clustering.md)
- [Velocity moments — vel_m10…c22](properties/velocity.md)
- [f(R) gravity](frn1.md): fRn1 suite, boosts, fiducials, new-simulation infill design.

## Examples (Jupyter notebooks)

- [Predicting](notebooks/01_predicting.ipynb): worked, output-embedded — calls every emulator family + plots.
- [Training new emulators](notebooks/02_training.ipynb): assemble→build→validate→register, CLI + programmatic (COSMA-bound).

## Guides

- [Predicting](guides/predicting.md): per-property one-liners, shapes, kwargs, checklist.
- [Training & CLI](guides/training-and-cli.md): CLI verbs, training flow, slurm, evidence harnesses.
- [Accuracy & gates](guides/accuracy.md): headline numbers, how measured, audit, rejected routes.
- [Caveats](guides/caveats.md): frozen-seed offset, BAO mask, NaN wedge, redshift coverage.
- [Portability](portability.md): predict off-COSMA (PyPI only); halocat/freyja training-time only; pickle caveat.

## For AI agents

- [Agent guide](ai/index.md): ground rules, the 90% task, where the truth lives.
- [Machine reference](ai/reference.md): flat fact table — API, shapes, ranges, f(R) representations, hard rules.

## Reference

- [Registered artifacts](reference/artifacts.md): the live manifest table.

## Source-of-truth files (in the repo)

- `haloemu/manifest.json`: provenance per artifact (accuracy, dependency pins, code version).
- `doc/emulation_methods.pdf` / `.tex`: methods paper, every gate number derived.
- `DOCUMENTATION.md`, `SUITE_DESIGN.md`: long-form design + usage.
- `.claude/skills/predicting-halo-properties/`: the auto-loaded calling-conventions skill (human export: `haloemu_skills.md`).