Skip to content

Installation

Requires Python 3.11+

Nested sampling depends on the official blackjax (its merged NSS), which requires Python 3.11 or newer. The examples below use 3.11.

A fresh conda environment is the easy route:

conda create -n ceridwen python=3.11 -y
conda activate ceridwen

git clone https://github.com/Espe13/ceridwen.git
cd ceridwen
pip install .

This pulls everything needed to import CERIDWEN, build the forward model, and run NUTS / VI / nested sampling including posterior plotting: jax, jaxlib, numpy, scipy, matplotlib, h5py, astropy, tensorflow-probability, blackjax, tqdm, fastprogress, optax, anesthetic, and pytest. The only thing not installed automatically is FSPS (see below).

There are no extras to choose. pip install . includes VI, nested-sampling plotting, and the test runner. FSPS is installed separately (see below), because it compiles Fortran and cannot be a normal Python dependency. Building this documentation site needs pip install ".[docs]" (maintainers only).

blackjax

Nested sampling uses blackjax.nss, which is merged into the official blackjax but not yet in a tagged PyPI release. CERIDWEN therefore pins a fixed blackjax commit (f73e12956) and installs it from GitHub, so every install gets the same validated state. The pin is also why CERIDWEN itself is installed from a clone rather than PyPI (PyPI refuses packages with direct-URL dependencies). Both revert to normal version pins once a blackjax release ships NSS.

Getting the SSP grid

Fitting needs a pre-computed SSP grid (an HDF5 file). The quickstart resolves it in the order $SSP_FILE, then examples/ssp_data.h5, then a local developer grid at ceridwen/data/test_data/ssp_data_bpass.h5 (not shipped in the repository).

  1. Build your own with FSPS (recommended for custom choices). Install FSPS (below) and let the quickstart build the grid on first run, or call SSPData.from_fsps(save_to="examples/ssp_data.h5", imf_type=1) directly. You control the isochrones, spectral library, and IMF. FSPS is needed anyway for nebular and dust emission, which read the CLOUDY and Draine & Li data from $SPS_HOME.

  2. Download from Zenodo (no FSPS needed): doi:10.5281/zenodo.21977508. The canonical grids are registered in ceridwen.ssps.grid_fetch (mist_miles_chab for MIST+MILES with a Chabrier IMF, mist_bpass_v2 for BPASS binary populations, plus the α-enhanced grids below), so the easiest route is by name — downloaded once into ~/.ceridwen/grids (override with $CERIDWEN_GRID_DIR) and verified against a pinned SHA-256 on every fetch:

    from ceridwen.ssps import fetch_grid, available_grids, SSPData

print(available_grids())                       # name -> description
ssp = SSPData.load(fetch_grid("mist_miles_chab"))

    or by hand, e.g. for the quickstart location:

    curl -L -o examples/ssp_data.h5 \
    "https://zenodo.org/records/21977508/files/ssp_data_mist_miles.h5?download=1"

α-enhanced grids: download, don't build

The [α/Fe]-aware grids for CSPBasis_afe are a special case, in both directions:

  • Building them yourself is hard — it requires python-fsps compiled from source with AFE_FLAG=1 against the FSPS v4.0 data tree (aMIST isochrones
  • C3K spectra), an easy source of silent misbuilds.
  • Downloading them is all you need — CSPBasis_afe (a subclass of CSPBasis that adds the [α/Fe] interpolation and drops the nebular arguments) carries no nebular model (no α-enhanced CLOUDY tables exist), so nothing is read from $SPS_HOME at fit time unless you also switch on add_dust_emission=True (the dust-emission templates come from the FSPS data files). With the downloaded grid and no dust emission, fitting [α/Fe] requires no FSPS install at all: skip the whole FSPS section below.
from ceridwen.ssps import fetch_grid, SSPDataAfe
from ceridwen.csp import CSPBasis_afe
from ceridwen import Cosmology
import jax.numpy as jnp

path = fetch_grid("amist_c3k_hr_krou_afe")     # cached + checksummed (~612 MB)
ssp  = SSPDataAfe.load(path)                   # (n_afe, n_Z, n_age, n_wave)
csp  = CSPBasis_afe(ssp, lookback_time=jnp.linspace(0.0, 12.0, 9),
                    cosmo=Cosmology.planck18(), zh_const=True, verbose=False)

The current deposit ships one α grid: amist_c3k_hr_krou_afe (high-resolution C3K, Kroupa IMF, 612 MB, schema 2.1 — loads as downloaded, shown above). The low-resolution Chabrier grid behind the methods-paper mock suite, amist_c3k_lr_chab_afe, lives only in an older version of the deposit and predates schema 2; if you need it to reproduce the paper, fetch_grid("amist_c3k_lr_chab_afe") still downloads it, then upgrade it once with

python scripts/convert_grids_schema2.py ~/.ceridwen/grids/amist_c3k_lr_chab_afe.h5

and load the amist_c3k_lr_chab_afe_schema2.h5 it writes alongside.

CSPBasis_afe accepts only α-aware (4-D) grids; passing a solar-scaled 3-D grid raises a TypeError pointing you back to CSPBasis. Conversely the nebular and dust-emission switches of CSPBasis still need $SPS_HOME, so solar-scaled fits with emission keep using the FSPS data files as before.

Installing FSPS and setting $SPS_HOME

CERIDWEN uses FSPS (via the python-fsps wrapper) to build the SSP cache. The FSPS data files also supply the CLOUDY nebular grids and Draine & Li dust-emission templates: when add_neb=True or add_dust_emission=True, CERIDWEN reads those files directly from $SPS_HOME (FSPS itself is not run at fit time; it just provides the data).

FSPS is not a pure-Python wheel: it needs a Fortran compiler and a clone of the FSPS data files.

# 1. A Fortran compiler (pick one for your system):
brew install gcc                       # macOS (Homebrew)
sudo apt-get install gfortran          # Debian/Ubuntu
conda install -c conda-forge gfortran  # any OS, inside your conda env

# 2. Pick where the FSPS data should live (ANY path: $HOME, a data disk, cluster
#    scratch, ...). git clone writes to the absolute $SPS_HOME path, so it does
#    not matter which directory you run it from.
export SPS_HOME="$HOME/fsps"           # <- edit to your chosen location
git clone https://github.com/cconroy20/fsps.git "$SPS_HOME"

# 3. Install the Python wrapper (it compiles against $SPS_HOME):
python -m pip install "fsps>=0.4.4"

Make $SPS_HOME permanent

python-fsps needs $SPS_HOME in every shell session and fails to import without it. Add it to your shell startup file (use the same path as above):

echo 'export SPS_HOME="$HOME/fsps"' >> ~/.zshrc   # zsh (macOS default)
echo 'export SPS_HOME="$HOME/fsps"' >> ~/.bashrc  # bash (most Linux)

Open a new terminal and check echo $SPS_HOME prints the path.

Verify your setup

With FSPS installed and $SPS_HOME set, run the environment doctor before your first fit:

python -m ceridwen.check

It prints an ok / warn / FAIL line per component (dependencies, FSPS, $SPS_HOME, nested-sampling support) with the fix for anything missing. Run it only after FSPS is set up. Before that it will correctly report python-fsps as missing.