Installation

CosmoForge is distributed as four PyPI packages that share a uv workspace in this repository:

  • CosmoCore (cosmocore) — shared algebra, fields, I/O, computation bases.

  • QUBE (qube, PyPI name qube-qml) — Fisher and QML estimation.

  • PICSLike (picslike) — pixel-space likelihood.

  • CosmoForge (cosmoforge) — umbrella metapackage that depends on the three above.

Requirements

  • Python 3.11–3.13

cosmocore runtime dependencies (installed automatically):

  • numpy >= 2.2.6

  • scipy >= 1.16.1

  • healpy >= 1.18.1

  • numba >= 0.61.2

  • psutil >= 5.9

  • threadpoolctl >= 3.0

Optional extras:

  • cosmocore[mpi] — adds mpi4py >= 4.1.0 for MPI parallel runs. qube-qml[mpi], picslike[mpi], cosmoforge[mpi] all pull this in transitively.

  • qube-qml[pcl] — adds pymaster >= 2.6 for the pseudo-Cl comparison utilities.

Development tools (uv dependency groups in the root pyproject.toml):

  • dev group: matplotlib, pytest, pytest-cov, pyyaml, ruff.

  • docs group: sphinx, sphinx-rtd-theme, myst-parser, sphinx-autodoc-typehints.

  • pre-commit is currently only declared in src/cosmoforge.cosmocore/pyproject.toml’s dev group.

Install from PyPI

The umbrella distribution pulls in all three subpackages:

pip install cosmoforge

Or pick subpackages individually:

pip install cosmocore       # core utilities only
pip install qube-qml        # adds QML / Fisher (imports as `qube`)
pip install picslike        # adds pixel-space likelihood

Add the MPI extra if you intend to run in parallel:

pip install "cosmoforge[mpi]"

Install from source (development)

The repository is a uv workspace. Install uv first, then clone and set up the minimal dev environment — every workspace member installed editable, plus lint/test tooling:

git clone https://github.com/ggalloni/CosmoForge.git
cd CosmoForge
uv sync --all-packages --dev

Any subsequent Python command should be run through uv:

uv run python -c "import cosmocore"
uv run pytest src/cosmoforge.cosmocore/tests/ -s

The optional groups below are opt-in — add them only when you need them. --dev always pulls in the root dev group; --group docs adds Sphinx + theme; --extra mpi / --extra pcl add runtime extras on the workspace packages.

MPI parallel runs

Adds mpi4py. Requires an MPI implementation (OpenMPI or MPICH) on the system before running the sync.

uv sync --all-packages --extra mpi --dev

Pseudo-Cl comparison (pymaster)

The pcl extra pulls pymaster, which is a C extension and needs healpix, cfitsio, and fftw installed at the system level before any pip/uv install can succeed.

System packages first (pick the route that matches your OS):

# Debian/Ubuntu
sudo apt-get install libcfitsio-dev libhealpix-cxx-dev libfftw3-dev

# macOS (Homebrew)
brew install cfitsio healpix fftw

Then:

uv sync --all-packages --extra pcl --dev

Or, if you’d rather sidestep system packages entirely, conda-forge ships a pre-built pymaster with its C dependencies baked in:

conda install -c conda-forge pymaster
# then the regular uv sync inside the same env
uv sync --all-packages --dev

Building docs locally

Docs are built and hosted on Read the Docs — both master and every PR get an auto-build. Only install the docs group if you’re iterating on the documentation itself:

uv sync --all-packages --group docs --dev
uv run sphinx-build -b html docs/source docs/build/html

Verification

After installation, confirm the imports succeed:

# cosmocore
from cosmocore.settings import InputParams
params = InputParams()
print(f"cosmocore OK, nside={params.nside}")

# qube
try:
    from qube import Fisher, Spectra
    print("qube OK")
except ImportError:
    print("qube not installed")

# picslike
try:
    from picslike import PICSLike
    print("picslike OK")
except ImportError:
    print("picslike not installed")

The cosmoforge umbrella package itself exposes no module surface — it only declares dependencies on the three packages above.