Installation & Run

Usage and publication policy

When using CARACal please be aware of and adhere to the CARACal publication policy.

Requirements

  • Python 3.9 - 3.12. (For Python version below 3.12 if working on Ubuntu> 22.04. Install the earlier Python version through this link)

  • Container technology of your choice. It can be one of the following:

    • Docker

    • Podman

    • Singularity 3.5 - 4.1 (nearly all functionality available for > 2.6.0-dist, see here for further information)

      • Apptainer does not support all CARACal functionalities (at the moment).

Installation

We strongly recommend and describe an installation using a Python3 virtual environment. Only try outside a virtual environment if you know what you are doing. Any name as ${name} occurring in the description below can be chosen arbitrarily. If it symbolises directories or files, those directories or files should exist and the user should have write access.

There are three (3) available methods to install the caracal pipeline:

1. Manual

Choose the name of the virtual environment ${caracal-venv}. Then:

$ python3 -m venv ${caracal-venv}  # Ensure Python version is between 3.9 and 3.12.

OR, if the command above does not work

virtualenv -p python3 ${caracal-venv}
source ${caracal-venv}/bin/activate
pip install -U pip setuptools wheel

For a CARACal stable release run:

pip install -U caracal

And CARACal developer version which is not recommended for users:

pip install -U 'caracal @ git+https://github.com/caracal-pipeline/caracal.git@master'

Ignore any error messages concerning `pyregion`.

1.1 container configuration

In case you are not carrying out a fresh installation, remove earlier Stimela images with:

stimela clean -ac

Then, if using Docker:

stimela pull

If using Singularity, choose a pull folder ${singularity_pull_folder}, where the Singularity images are stored and define an environment variable by adding this in the rc file of your shell (e.g. .bashrc):

export SINGULARITY_PULLFOLDER=${WORKSPACE_ROOT}/singularity_images

and run:

stimela pull -s

If using Podman:

stimela pull -p

2. caratekit.sh script

Download the installation script caratekit.sh . Choose the parent directory ${workspace} and the name of the CARACal directory ${caracal_dir}. Any name as ${name} occurring in the description below can be chosen arbitrarily. If it symbolises directories or files, those directories or files should exist and the user should have write acccess.

If using Docker:

caratekit.sh -ws ${workspace} -cr -di -ct ${caracal_dir} -rp install -f -kh

If using Singularity:

caratekit.sh -ws ${workspace} -cr -si -ct ${caracal_testdir} -rp install -f -kh

3. Poetry (For developers)

Installation from source using poetry. First, install poetry:

pip install poetry

In the working directory where source is checked out run poetry install or to include all optional dependencies:

poetry install

Installation on (ILIFU) slurm environment

The installation of CARACal on ilifu has been tried and tested on the Ubuntu 20.0 operating system, although, it should also work on other OS versions. On the login node, follow these instructions:

cd /path/to/working/area
module add python/3.9.4
python3 -m venv <venv-name>
source <venv-name>/bin/activate
pip install -U pip setuptools wheel
git clone https://github.com/caracal-pipeline/caracal.git
pip install -U -e caracal
deactivate

where /path/to/working/area is the actual path to the directory where you wish to install CARACal. In principle, this can also be done in the Slurm environment of ILIFU by submitting an sbatch script. Please amend your pip install command with [all] option when needed in accordance with the instructions above. Install the latest release with:

pip install -U caracal

NB: The latest version of stimela singularity images needed for CARACal are stored in this location: /idia/software/containers/STIMELA_IMAGES/. For older versions, refer to the legacy directory: /idia/software/containers/STIMELA_IMAGES_legacy/.