Installation

Below are full installation steps (catered towards Ubuntu & Slurm users) so as to maximize CNeuroMax’s reproducibility across platforms, utilizing virtualization technologies Docker, Podman & Apptainer.

Common to all machines

The following commands are meant to set-up the repository.

1. Move to the desired containing folder

Note

We recommend, in the Contribution section, to make use of Dropbox/Maestral if you plan to alter the code on different machines.

# Examples
cd ${HOME}/Dropbox/
cd ${SCRATCH}/Dropbox/

2. Clone the repository

git clone git@github.com:courtois-neuromod/cneuromax.git

3. Define the CNEUROMAX_PATH variable

echo -e "\nexport CNEUROMAX_PATH=${PWD}/cneuromax" >> ~/.bashrc \
    && source ~/.bashrc

4. Weights & biases

Weights & Biases is a tool to log experiments. In order to make use of it, you will need to create an account on their website and generate an API key. Once you have done so, create a file called WANDB_KEY.txt at the root of the repository and paste your API key in it.

You can now log experiments to your personal account. To log experiments to the CNeuroMod account, contact any existing team member with your email address to be added to the team list.

On an Ubuntu machine

Note

Skip to Step 4 if you do not have administrator privileges.

1. Install Docker or Podman

Note

We suggest installing Docker if you meet any of the following conditions:

  • This is your own machine and plan to contribute to the library (Development Containers are smoother with Docker than Podman).

  • You are an administrator of this machine, do not want to install Podman and are fine with adding users to the docker group. See this link on security implications.

Otherwise, install Podman.

Option A) Install Docker

Follow the Docker installation guide. Do not forget the Docker post-installation steps.

Note

You could be interested in setting up Rootless mode if you plan to make use of the library’s Development Container (so that files created by the container are owned by your user and not by root). See this link for more information.

Option B) Install Podman

Follow the Podman installation guide.

2. Install the NVIDIA driver

Note

Skip this step if your machine does not have an NVIDIA GPU.

Note

In addition to the method described below, Ubuntu users can also install the driver by opening the “Software & Updates” application, going to the “Additional Drivers” tab and selecting the “Using NVIDIA driver metapackage from nvidia-driver-XXX (proprietary, tested)” option.

Follow the NVIDIA driver installation guide.

3. Install the NVIDIA Container Toolkit

Note

Skip this step if your machine does not have an NVIDIA GPU.

Follow the NVIDIA Container Toolkit installation guide.

If you are using a Rootless Docker or Podman, make sure to follow the Rootless setup.

4. Pull the image

# Substitute `docker` with `podman` if you installed Podman.
docker pull docker.io/cneuromod/cneuromax:latest

On a Slurm cluster

Apptainer (previously called Singularity) is a generally available alternative to Docker on HPC clusters. We automate the process of building the CNeuroMax Apptainer image for CNeuroMod team members through our GitHub Actions.

The latest image is available on Ginkgo at the following location:

/scratch/cneuromax/cneuromax.sif

The process of setting up SSH keys and the required tunneling is beyond the scope of this documentaion. Reach out to seasoned team members if you need assistance.