Spaceborne: fast and accurate analytical covariance matrices for precision cosmology

---

Spaceborne is a code for the fast and accurate computation of the analytical photometric probes (weak lensing, photometric galaxy clustering and galaxy-galaxy lensing) covariance matrix for modern cosmological analyses. Some of its features include:

• Easy to use: all settings are detailed (along with type hints) in the yaml example config file, with further explanations in the readthecods page.
• Extensively validated against simulations and other public codes.
• Interfaced with CCL and cloelib (soon), two of the most modern and extensive cosmological libraries.
• Different statistics available: $C(\ell)$ and 2PCF
• Python native: written entirely in pure Python, with no low-level interfaces (e.g., C/C++ wrappers). This makes the code highly accessible, transparent, and easy to modify.
• JAX-accelerated: the most intensive computations are optimised using JAX, seamlessly providing multi-device (CPU, GPU, TPU) support.
• ... and much more!

For detailed instructions on how to install and use Spaceborne, please refer to the official documentation.

📔 For a hands-on walkthrough, you can check out the DEMO.ipynb notebook.

Installation

To install Spaceborne within a dedicated conda environment:

# Clone the repository
git clone https://github.com/davidesciotti/Spaceborne.git

# Enter the Spaceborne root directory you just cloned
cd Spaceborne

# Checkout the latest release (version tag); e.g., git checkout v2025.07.1
git checkout <latest_version_tag>

# Create the conda environment. This step can be slow; add --solver=libmamba 
# to speed it up (see below for more details)
conda env create -f environment.yaml

# activate the newly created conda environment
conda activate spaceborne

# Finally, install Spaceborne
pip install .

Some notes

❗ The only stable versions you should consider are the code releases. Please avoid simply cloning and installing the code from the main branch. As the code is evolving quite quickly at the moment, please make sure to check for new releases periodically Moreover, installation is only supported in a dedicated Conda environment, for the time being (installation via PyPI is work in progress).

🐍 To significantly speed up the environment creation, install mamba by running conda install mamba in your base environment., then do

mamba env create -f environment.yaml 
# or
conda env create -f environment.yaml --solver=libmamba 

🔵🟢🟣 Spaceborne leverages JAX for computationally intensive tasks. This is included as a pip dependency in the environment.yaml file. If you want to run the jax-optimised parts of the code on an NVIDIA GPU, after creating and activating the enviromnent do

pip install -U "jax[cuda12]"

Please refer to the official installation instructions for more accurate, up-to date and platform specific (see e.g. Silicon Macs) intructions.

Running the Code

All the available options and configurations can be found, along with their most up-to-date explanation, in the config.yaml file. To run Spaceborne with the configuration specified in the Spaceborne/config.yaml file, simply execute the following command:

python main.py

If you want to use a configuration file with a different name and/or location, you can instead run with

python main.py --config=<path_to_config_file>

for example:

python main.py --config="path/to/my/config/config.yaml"

To display the plots generated by the code, add the --show-plots flag:

python main.py --config="path/to/my/config/config.yaml" --show-plots

Additionally, in the config.yaml file you can set save_figs: True to save the figures in the <output_folder>/figs path.

Benchmarks ⏱️

On a 2024 MacBook Pro with a 14-core Apple M4 Pro processor and 24GB of RAM, for a configuration with $\ell_{\rm min}, \ell_{\rm max}, \ell_{\rm bins} = (10, 3000, 30)$ and 10 redshift bins, the 3×2pt harmonic-space covariance matrix takes:

• Gaussian term (binned by computing the covariance over all integer $\ell$ values, then averaging): ~ 5s
• SSC (on high precision settings, i.e. using the double redshift integral expression): ~5s

Stay tuned for more!

Using Docker 🐋

If you find issues with the installation, you can happily disregard the above instructions and run the code through Docker. To do this, install Docker Desktop or the Docker engine; then, in the root of the cloned repository (again, remember to checkout the latest release), run:

docker-compose up --build

Note that the --build flag is only needed the first time you run the code (or if you modify the environment.yaml or Dockerfile, which is highly discouraged). For subsequent runs, simply do:

docker-compose up

Finally, to stop the container, do

docker-compose down

That's it! The container will use your local config.yaml file and output to the directories specified in your configuration, just as if you were running locally.

---