Installation

Installing the Cedalion toolbox on your local machine takes 6 steps, which are summarized below and then descibed in more detail in the following section.

Summary

  1. Install conda – Install either Miniconda or Anaconda for environment and package management.

  2. Get the source code – Clone the Cedalion GitHub repository.

  3. Select a version - Use the main branch for stable releases or dev for the most recent development version.

  4. Create a conda environment – Create a new conda environment using the provided environment_dev.yml file.

  5. Install Cedalion – Install Cedalion in editable mode so you can use or modify it directly.

  6. Optional: Install NirFaster - Install a supplemental package for simulating light propagation in tissue.

Step-by-Step Instructions

1. Install conda

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

Install either Miniconda or Anaconda:

2. Get the source code

The source code of the Cedalion toolbox is hosted on our public git repository. By following this guide, you will clone the public repository to your local machine. This clone contains the complete developement history and maintains a connection to the public repository. This way you can switch between version, pull updates and contribute changes back.

Open a terminal, navigate to the directory where you want the local repository to be stored, and run the clone command. This will create a new folder named cedalion in that location.

(The $ sign represents the terminal prompt and should not be copied. The # signs indicate comments. Placeholders are written as <placeholder> and should be replaced by the user.)

$ cd /path/to/install_directory

# for read-write access with a GitHub account:
$ git clone git@github.com:ibs-lab/cedalion.git

# alternatively for read-only access without a GitHub account:
$ git clone https://github.com/ibs-lab/cedalion.git

Alternatively, if you prefer using the GitHub Desktop application, please refer to its documentation on cloning repositories.

3. Select a version

Select the desired version by choosing the appropriate branch in your local repository.

  • The main branch serves as the release branch. Its latest commit always represents the most recent stable release. As the default branch, main is checked out when the repository is cloned.

  • Older releases on main are marked with tags such as v25.0.0.

  • The dev branch contains the latest development version.

For a complete release history and details on differences between dev and main, see the CHANGELOG.

$ cd /path/to/install_directory/cedalion

# switch between branches
$ git switch <branchname>

# select specific versions
$ git switch -d <tagname>

Alternatively, if you prefer using the GitHub Desktop application, please refer to its documentation on switching between branches.

4. Create a conda environment

Next, create a conda environment with all required dependendencies:

$ conda env create -n <environment_name> -f environment_dev.yml

Choose a descriptive name for the environment. Since you may need multiple environments over time (e.g., for projects using different Cedalion versions), a naming convention like cedalion_YYMMDD can be helpful, but feel free to use any scheme that works for you.

5. Install Cedalion

Activate the new environment and install Cedalion in editable mode so you can use it and easily modify its functionality if needed.

$ conda activate <environment_name>
$ pip install -e . --no-deps

6. Optional: Install nirfaster-uFF

Cedalion supports two photon propagators to simulate light transport in tissue: pmcx and NIRFASTER-uFF. pmcx is installed by default but it requires a GPU with CUDA support. NIRFASTER-uFF runs also on the CPU and can be installed by running:

$ bash install_nirfaster.sh CPU # or GPU

Using the environment

To use your Cedalion installation, first activate the environment and then execute python programs using Cedalion within that environment.

For example, to run jupyter notebook:

$ conda activate <environment_name>
$ jupyter notebook

To test your installation, you can use the example notebook examples/00_test_installation.ipynb.

Alternatively, integrated development environments (IDEs) like VSCode have builtin support for managing environments and working with Jupyter notebooks. Make sure that you select the correct environment and Jupyter kernel.

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 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 cedalion’s dependencies changed over time. When pulling recent changes from dev you might need to update or recreate the environment.

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

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