Installation

Important

This application uses 3.10 <= python <= 3.12

Latest Version

This option is recommended to learn the software, run the tutorials, and drafting Testing Experiments.

Note

We recommend installing with conda because it bundles native/system dependencies.

1. Using conda

First, clone the floatCSEP source code into a new directory by typing into a terminal:

$ git clone https://github.com/cseptesting/floatcsep
$ cd floatcsep

Then, let conda automatically install all required dependencies of floatCSEP (from its environment.yml file) into a new environment, and activate it:

$ conda env create -f environment.yml
$ conda activate floatcsep

Note

For this to work, you need to have conda installed (see conda.io), either by installing the Anaconda Distribution, or its more minimal variants Miniconda or Miniforge (recommended). If you install Miniforge, we further recommend to use the mamba command instead of conda (a faster drop-in replacement).

Lastly, install floatCSEP into the new environment using pip:

$ pip install .

Note

To update floatCSEP and its dependencies at a later date, simply execute:

$ git pull
$ conda env update --file environment.yml
$ pip install . -U

2. Using only pip

To install using the pip manager only, you need the binary dependencies of pyCSEP (see Installing pyCSEP).

Note

Pip-only installs may require native libraries for PDF report generation (WeasyPrint). See Binary dependencies for pip-only installs.

The floatCSEP latest version can then be installed as:

$ git clone https://github.com/cseptesting/floatcsep
$ cd floatcsep
$ python -m venv venv
$ pip install .

Binary dependencies for pip-only installs

Debian/Ubuntu:

$ sudo apt-get update
$ sudo apt-get install -y \
    libglib2.0-0 \
    libpango-1.0-0 \
    libpangoft2-1.0-0 \
    libharfbuzz0b \
    libharfbuzz-subset0

macOS (Homebrew):

$ brew install cairo pango gdk-pixbuf libffi

In macOS, if import weasyprint fails to find libraries (e.g. libgobject-2.0-0), set this for the current terminal session:

$ export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib:/usr/local/lib:$DYLD_FALLBACK_LIBRARY_PATH"

Latest Stable Release

This option is recommended for deploying Floating Testing Experiments live.

1. From the conda-forge channel

Having a conda manager installed (see conda managers in 1. Using conda), type in a console:

$ conda create -n experiment python={PYTHON_VERSION}
$ conda activate experiment
$ conda install -c conda-forge floatcsep

where 3.10 < {PYTHON_VERSION} <= 3.12 is at your convenience.

2. From the PyPI repository

Having installed the binary dependencies of pyCSEP (see Installing pyCSEP) and, for pip-only environments, the system dependencies in Binary dependencies for pip-only installs, install floatCSEP by:

$ python -m venv venv
$ pip install floatcsep

Important

If you want to run the tutorials from a floatCSEP installation obtained through conda-forge or PyPI, the tutorials can be downloaded to your current directory as:

$ latest_version=$(curl --silent "https://api.github.com/repos/cseptesting/floatcsep/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') && \
wget "https://github.com/cseptesting/floatcsep/releases/download/$latest_version/tutorials.zip"
$ unzip tutorials.zip -d ./ && rm tutorials.zip

Or downloaded manually from the latest release.

Docker (Model Containerization & Parallel Run)

Some tutorials and experiments containerize models with Docker, and the engine can use Docker for parallel execution. To use these features, please install Docker and (on Linux) perform the post-installation steps:

Tip

After installing, verify Docker works:

$ docker run --rm hello-world

For Developers

We recommend using a conda environment for development to avoid relying on system libraries. For contributing to the floatCSEP codebase, please consider forking the repository and creating pull requests from there.

$ conda create -n floatcsep_dev
$ conda activate floatcsep_dev
$ git clone https://github.com/${your_fork}/floatcsep
$ cd floatcsep
$ pip install -e ".[dev]"

This will install and configure all the unit-testing, linting, and documentation packages.