Installation¶
From source¶
git clone https://github.com/suchethac/tengri.git
cd tengri
pip install -e ".[all]"
This installs the package in editable mode with all optional dependencies
needed for fitting workflows and reproducible results. For development,
use .[dev] instead. Editable installs are recommended for any work that
touches the forward model.
Optional extras¶
Extra |
Adds |
When you need it |
|---|---|---|
|
BlackJAX |
NUTS / HMC sampling |
|
optax |
MAP optimization |
|
dust-extinction |
Grain-model dust attenuation laws (wd01, d03, hd23) |
|
astroquery |
Downloading filter curves from SVO Filter Profile Service |
|
jax with CUDA wheels |
NVIDIA GPU fits |
|
jax-mps |
Apple Silicon GPU, float32 only, in its own environment (experimental; see the Apple MPS notebook) |
|
nuts, optax, grain-dust, filters |
recommended for new users; does not include GPU backends |
|
pytest, ruff, jupytext, and testing backends |
development |
pip install -e ".[all]"
Requirements¶
Python ≥ 3.12
JAX ≥ 0.4.20 and jaxlib ≥ 0.4.20
DSPS 0.4.6–0.4.7 (0.4.8 excluded: its PyPI sdist breaks at install time)
NumPy ≥ 1.24
Matplotlib ≥ 3.7
h5py ≥ 3.0
NIFTy ≥ 8.5 with the
reextrafilelock ≥ 3.0 (required for persistent JAX cache)
JAX backends¶
CPU. Default. No extra setup; reliable across operating systems.
CUDA (NVIDIA GPU). Install with the [gpu] extra and then follow
JAX’s CUDA notes
to match the driver and CUDA versions on the host.
Apple Silicon: Apple’s own jax-metal (0.1.1, 2024-10) is not viable with this JAX version. The supported path is the community jax-mps plugin (MLX-backed, float32 only). See notebooks/apple_mps.py for setup and bench/scripts/benchmark_float32_mps_parity.py for the float32 accuracy check. Set JAX_PLATFORMS=cpu for any fit you intend to trust without it.
On every backend, import tengri enables 64-bit precision globally (jax_enable_x64), with float64 as the reference. Pure float32 is supported end-to-end (2026-09, #1206): set JAX_ENABLE_X64=0 before Python starts (not after import tengri), and the forward model, emission-line channel, and default photometry plus line fit reproduce the float64 optimum to ~1e-5 on CPU and CUDA, achieving 2x the galaxies per GiB. Quantities that overflow float32 (e.g., 4 pi d_L^2 at ~1e57 cm^2 at any redshift, erg/s luminosities) are carried as log10 offsets internally. This is why linear line and X-ray luminosity properties are in Lsun and the ionizing rate is log_q_h only. import tengri also raises the default matmul precision to "highest", ensuring float32 matmuls never lower to TF32 on Ampere+ GPUs. Details and measurements are in docs/dev/float32-tier-b-boundary.md.
SSP grids¶
Tengri needs a pre-computed Simple Stellar Population grid in DSPS HDF5 format. The default is FSPS with MIST isochrones and the C3K library (Chabrier IMF), bare-stellar so the Cue and Cloudy nebular backends can sit on top. The Padova grids (PARSEC, PADOVA) are still available by name, but they give old populations almost no far-UV, so they are not the default. It is the grid the quickstart notebook uses.
import tengri
tengri.download_ssp() # → data/ssp_mist_c3k_hr_chabrier_wNE_logGasU-3.0_logGasZ0.0.h5 (or $TENGRI_DATA_DIR)
tengri.list_known_ssps() # other grids
Or via shell, using either the wrapper script or a direct fetch:
bash scripts/setup_ssp.sh
# or
wget https://halos.as.arizona.edu/suchethacooray/ssp-spectra/fsps_prsc_miles_chabrier.h5 -P data/
The full catalog of pre-formatted grids (BC03, BPASS, FSPS,
ProGeny) lives at the
public mirror.
Use tengri.list_known_ssps() to list the hosted SSP grids.
Verify your install¶
pytest tests/components/sps/test_alpha_fe.py \
tests/components/stellar/test_stellar_skeleton.py -q --no-header
The same two-file selection runs as the smoke gate on every PR. If it
passes, import tengri and the SSP-loading path are healthy.
import tengri
tengri.doctor() # install + JAX backend + SSP files
Persistent JAX cache¶
import tengri enables a persistent on-disk JAX compile cache at ~/.cache/tengri_jax_cache, allowing notebook restarts, slurm tasks, and benchmark worker subprocesses to skip the expensive first compile. After upgrading JAX, wipe stale entries:
import tengri; tengri.clear_cache()
A sibling cache at ~/.cache/tengri_precomp persists the photometry redshift table that free-redshift models precompute at build time, so the first SEDModel.build of a given SSP plus filter set pays the cost once, and subsequent builds (in any session) take seconds.
Override the location or disable via env:
export TENGRI_JAX_CACHE_DIR=/scratch/$USER/jax_cache
export TENGRI_DISABLE_JAX_CACHE=1
export TENGRI_PRECOMP_CACHE_DIR=/scratch/$USER/tengri_precomp
export TENGRI_DISABLE_PRECOMP_CACHE=1