Installation

Dependencies

Python, ROOT, and Ph2 ACF are dependencies of dirigent but do not come packaged with it. Right now, we assume that test centres wishing to use dirigent already have all these dependencies installed, and are familiar with them. As more institutes develop their testing facilities, this may be revised and dependencies such as Ph2 ACF may come packaged. Below some notes are provided for correct configuration of dependencies. For additional help, Ph2 ACF provides very useful instructions for a lot of the process.

Python

Python 3.9 (minimum) is required for the installation of dirigent. Earlier versions cannot be substituted as modern syntax and language features are used throughout the project.

ROOT

For the installation of ROOT, it is recommended to follow the instructions on the official website of the ROOT project. This is a bit more work than the installation with the package manager, but it is generally easier for usage with environments than the installation through the package manager. For proper behaviour, ROOT should be sourced prior to running dirigent. Most accomplish this by sourcing thisroot.sh in their .bashrc.

On AlmaLinux 9, the following instructions might give some help on what the dependencies are. This is however not an official instruction and it might depend on the specific setup. Therefore, please refer also to the official website:

sudo dnf install epel-release git make cmake gcc-c++ gcc binutils \
libX11-devel libXpm-devel libXft-devel libXext-devel python openssl-devel \
xrootd-client-devel xrootd-libs-devel xxhash xxhash-libs tbb-devel python3-numpy
wget https://root.cern/download/root_v6.32.02.Linux-almalinux9.4-x86_64-gcc11.4.tar.gz
tar -xzvf root_v6.32.02.Linux-almalinux9.4-x86_64-gcc11.4.tar.gz
source root/bin/thisroot.sh # also available: thisroot.{csh,fish,bat,ps1}

On AlmaLinux 9, ROOT can also be installed through the package manager. However, this installation can cause difficulties with python environments. For this, use the following commands:

dnf install -y epel-release
dnf config-manager --set-enabled crb
dnf install -y root python3-root git

From these commands, it is likely, that only python3-root has to be installed. The rest should be already there, if Ph2 ACF was installed before.

On CentOS 7, both Python 3.9 and ROOT must be built from source in that order. On CentOS Stream 8, Python 3.9 can be installed via the python39 python39-devel python39-numpy packages prior to compiling ROOT. ROOT should be compiled against C++14 to ensure compatibility with Ph2 ACF.

Ph2 ACF

Ph2 ACF can be cloned from the TK_Ph2 gitlab repo (or for development versions, the Inner Tracker Upstream Repo) and compiled/installed using the instructions provided there. dirigent can also handle your Ph2 ACF installation if your system does not have Ph2 ACF installed. For those wishing to maintain separate Ph2 ACF installations, it is recommended to use the most recent tagged version of Ph2 ACF for the IT (v6-15 at the time of writing), but since Ph2 ACF is constantly under development, I also recommend maintaining the master branch of the development version on lab PCs just in case new fixes are pushed. Also, Ph2 ACF must be compiled against the ROOT installation with Python 3.9 bindings (see previous section).

The dirigent Ph2 ACF handler requires xterm to be installed (or for expert users, a compatible version of tmux newer than version 1.8 can also be explored, but it is not currently fully supported). The installation script described in the Installation script section below can automatically install xterm for you, or on AlmaLinux for example, xterm can simply be installed through the package manager:

dnf install -y xterm

Clone the repository

Navigate to your software folder and create a folder for dirigent:

mkdir dirigent && cd dirigent

Next, clone the repository into a folder named after the version you want, enter that directory, and checkout the correct version (3.3.1 is used here as an example):

git clone https://gitlab.cern.ch/cms_tk_ph2/dirigent.git dirigent-3.3.1
cd dirigent-3.3.1
git checkout tags/3.3.1

Installation script

To simplify the installation process, an install script install.sh is provided. Run this with the -p flag to also install Ph2 ACF:

. install.sh -p N

where N is the number of jobs given to the Ph2 ACF make -jN command, as described here. This will create (and activate) a virtual Python environment (.dirigenv) (‘dirigent environment’, see the next section) and install everything in there, ensuring pip is up to date.

If you already have Ph2 ACF installed on your system, you can also run the install script without the -p flag to save a lot of time:

. install.sh

Just remember to source Ph2 ACF. See the Set up Ph2 ACF section below. For other options, run the install script with the --help flag to list them:

. install.sh --help

Manual installation

For expert users, dirigent testers, and developers, a manual installation may be preferred. After installing xterm, the install.sh script simply initialises all of the git submodules (dependencies). This can be done manually by running:

git submodule update --init --recursive

This command will clone the submodules inner-tracker-tests, icicle, felis, resthub-dev, and of course, Ph2 ACF. An expert user may wish to checkout specific commits of each of these submodules before installation. inner-tracker-tests is a repository containing standardised settings for Ph2 ACF scans. felis is the interface used for uploading data to the Panthera database. resthub-dev is the API used to provide access to the module database. icicle is particularly important as it is used for controlling instruments. Expert users may already be maintaining their own Ph2 ACF installs. To avoid compiling Ph2 ACF again, this submodule can be ignored by first running:

git config submodule.deps/Ph2_ACF.update none
git submodule update --init --recursive

It is not recommended to ignore any other submodules.

Python environment

The next step that the install.sh script takes is to create the python environment. It is recommended to install dirigent in a separate python environment. One may use Python virtual environments or anaconda environments for this purpose - it makes litte practical difference. An example of how to set up a python virtual environment for this purpose is below:

python3 -m venv .venv
source .venv/bin/activate

Note: If ROOT was installed via the package manager, the environment has to be created with the flag --system-site-packages. The install.sh script can also handle this, by passing it the -s flag. For flexibility reasons, it is however recommended to install ROOT directly from the binary.

Then inside the python environment, make sure pip is upgraded, which the install script also handles:

pip install --upgrade pip

Then finally:

pip install .

Or for a developer installation of these packages (i.e. modifications of source files will affect the installation):

pip install -e .

This can also be achieved by running the install.sh script with the -d flag. Now that installation of dirigent has been performed in the python environment, on computer reboot, simply enabling that python environment will automatically load dirigent too:

source /path/to/software/dirigent/dirigent-3.3.1/.venv/bin/activate

Another script has also been written to simplify this:

. /path/to/software/dirigent/dirigent-3.3.1/setup.py

which also includes sourcing the Ph2 ACF version in deps/Ph2_ACF/ if it was installed by the install.sh script. This is described in the next section.

Set up Ph2 ACF

The activation of the python environment can cause the environment variables set by Ph2 ACF to be reset. Therefore, the virtual dirigent python environment should be loaded before Ph2 ACF is sourced. Once the environment has been activated, you must source the setup.sh file for the specific version of Ph2 ACF you want to use:

cd path/to/Ph2_ACF/install/
source setup.sh

Note: Since Ph2 ACF uses absolute paths in their setup.sh, you must cd to the install directory first.

dirigent should now be ready to run. You can check with:

dirigent --help