Installation

Get the latest release of the cedalion toolbox from our public github repository. Releases can be found in the main branch of the repository wheras development happens in the dev branch.

Cedalion depends on many third-party python libraries. To uniformly provide environments containing these dependencies across different platforms (Linux, Windows, MacOS) we rely on the conda package manager and the conda-forge package repository.

Development

Follow the installation instructions to install the Miniconda or Anaconda distribution.

Clone the git repository to a directory on your machine:

$ git clone git@github.com:ibs-lab/cedalion.git

This creates a new directory cedalion in your current folder. It checks out the latest stable release from the main branch. If you intend to contribute to cedalion please check out the dev branch.

To create a conda environment named cedalion with the necessary dependendencies enter this checked-out directory and run:

$ conda env create -n cedalion -f environment_dev.yml

Select a descriptive name for the environment. Keep in mind that over time you may want to have multiple environments in parallel, for example when you are working on two projects that use different versions of cedalion. A naming scheme that includes the current date (‘cedalion_YYMMDD’) is practical but you are free to choose whatever works best for you.

Afterwards activate the environment and add an editable install of cedalion to it:

$ conda activate cedalion
$ pip install -e . --no-deps

This will also install Jupyter Notebook to run the example notebooks.

If it’s slow…

To create the environment conda needs to find a set of packages that fulfills all requirements. If conda needs too much time to find a solution, there are two ways to speed it up.

  1. Make sure that you are using a recent version of conda (> 23.10) that uses libmamba-solver to resolve dependcies. (recommended)

  2. Install mamba, a drop-in replacement for conda.

Development using Hatch

Alternatively, there is preliminary support for using the Python project manager Hatch. Hatch helps with the handling of the python environments and offers a simple interface to perform common tasks.

As a tool to manage cedalion’s environment, hatch and its dependencies must be installed in a separate environment, like for example the base environment of a Miniconda/Anaconda installation or using pipx:

$ pipx install hatch
$ pipx inject hatch hatch-vcs hatch-conda hatchling

Then clone cedalion’s git repository and change to the checked-out directory:

$ git clone git@github.com:ibs-lab/cedalion.git
$ cd cedalion

To create the environment run and install cedalion in editable mode run:

$ hatch env create

To run the tests call:

$ hatch test

To locally build the documenation run:

$ hatch run build_docs

Production

The same procedure as above applies. However, make sure to use a released version from the main branch.

Updating

Updating between releases

In the past, you cloned the git repository to a local directory using the last released version on the main branch. During installation, you created a conda environment and added cedalion from that directory to the environment.

Updating to a newer version is easiest done by cloning the git repository again to a different folder and creating a new environment. This way, the installed version remains usable. It also guarantees that the new environment contains any updated dependencies.

The following example uses the version suffix in the directory and environment name.

$ git clone git@github.com:ibs-lab/cedalion.git path/to/cedalion_v25.1.0
$ cd path/to/cedalion_v25.1.0
$ conda env create -n cedalion_v25.1.0 -f environment_dev.yml
$ conda activate cedalion_v25.1.0
$ pip install -e . --no-deps

Switching between the different cedalion versions is then possible by activating the corresponding environment.

During development

Cedalion’s development happens in the dev branch. The cloned git repository contains the complete development history and maintains the connection to our main repository at GitHub. By pulling the recent changes from there or by checking out a commit from the past the cedalion directory can be brought to any desired version. The conda environment will then use the checked out version.

Keep in mind that the cedalion’s dependencies changed over time. When pulling recent changes from dev you might need to update or recreate the environment.

Container Environments

Apptainer

For running cedalion in a headless environment we provide an Apptainer definition file. This container provides a populated conda environment and runs the X Window virtual Framebuffer (Xvfb) needed for the 3D plotting functionality of pyvista. The directory with the cedalion source code is expected to be mounted under /app. It is added as an editable install to the conda environment, i.e. changes made in the host directory propagate into the container.

XVfb needs write access under /var/lib/xkb which is not available from inside the container. As workaround we bind a writable directory from the host to this folder. Probably a more elegant solution exists.

Building the container:

Clone the cedalion repository to ./cedalion

$ git clone https://github.com/ibs-lab/cedalion.git

Build the container. The cedalion source code needs to be mounted under /app.

$ apptainer build --bind `pwd`/cedalion:/app cedalion.sif cedalion/cedalion.def

Run jupyter notebook in the container

$ mkdir -p xkb
$ apptainer run --nv --bind `pwd`/xkb:/var/lib/xkb,`pwd`/cedalion:/app cedalion.sif jupyter notebook --ip 0.0.0.0 --no-browser

Docker