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

[nuts]

BlackJAX

NUTS / HMC sampling

[optax]

optax

MAP optimization

[grain-dust]

dust-extinction

Grain-model dust attenuation laws (wd01, d03, hd23)

[filters]

astroquery

Downloading filter curves from SVO Filter Profile Service

[gpu]

jax with CUDA wheels

NVIDIA GPU fits

[mps]

jax-mps

Apple Silicon GPU, float32 only, in its own environment (experimental; see the Apple MPS notebook)

[all]

nuts, optax, grain-dust, filters

recommended for new users; does not include GPU backends

[dev]

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 re extra

  • filelock ≥ 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