Installation#

There are several ways to install and use the climate-ref package and associated CLI tool (ref). If you find the various options to be confusing, we recommend reading this overview about the state of python package installation.

The REF itself is a pure Python package and does not require any conda-based dependencies. This was a deliberate decision to make it easy to make the framework easy to install in a range of different environments. Some of the diagnostic providers require additional dependencies in order to run an execution. For these providers, the REF can automatically create a new Conda environment and install the required dependencies in this standalone environment. Each of these provider-specific environments are decoupled to allow for potentially incompatible dependencies. This uses a bundled version of the micromamba to create and manage the environments so no additional dependencies are required.

conda create -n climate-ref python=3.11
conda activate climate-ref
pip install "climate-ref[aft-providers]"

Installing climate-ref#

PyPI#

You can install climate-ref using pip:

pip install climate-ref

The PyPI package contains some extras that bundle some additional dependencies. Depending on your use case you may want to install:

• celery - for running the REF in a distributed manner
• aft-providers - diagnostic providers for Assessment Fast Track
• postgres - additional dependencies required for using a PostgresSQL database

Extras can be installed by including the name inside square brackets after the package name:

pip install climate-ref[celery,aft-providers]

Conda#

We intend on providing a recipe on conda-force. Once complete you can install climate-ref using mamba or conda:

mamba install -c conda-forge climate-ref
conda install -c conda-forge climate-ref

A modern alternative to using conda as package a manager is Pixi. Pixi uses the same packages as conda but is faster and can create reproducible environments out of the box.

Docker#

For production use, we recommend using the climate-ref Docker image to provide a consistent environment for running the REF. Not all users may support Docker directly, instead requiring the use of Apptainer to provide some additional isolation.

docker pull ghcr.io/climate-ref/climate-ref:latest

or

apptainer pull docker://ghcr.io/climate-ref/climate-ref:latest

If you want to use the latest development version, you can build the Docker image from the source code:

git clone https://github.com/Climate-REF/climate-ref.git
cd climate-ref
docker-compose build

If you require the full-stack of services recommended for a production deployment, you can use the docker-compose file to start the services. This requires an initialisation step to fetch some required datasets and environments before starting the services.

bash scripts/initialise-docker.sh
docker-compose up

From Source#

To install climate-ref from the source code, clone the repository and install it:

git clone https://github.com/Climate-REF/climate-ref.git
cd climate-ref
make virtual-environment

See the development documentation for more information on how to contribute to the project.

Installing metric provider dependencies#

Some metric providers can use their own conda environments. The REF can manage these for you, using a bundled version of micromamba.

The conda environments for the registered providers can be created with the following command:

ref providers create-env

A new environment will be created automatically for each conda-based metric provider when it is first used, if one does not already exist. This can cause issues if the environment is created on a node that doesn't have internet access, or if a race condition occurs when multiple processes try to create the environment at the same time.

MAMBA_PLATFORM=osx-64 ref providers create-env --provider pmp

The created environments and their locations can be viewed using the command:

ref providers list