Installing study-DA locally

Cloning the repository

If you encounter trouble with the pip installation, or if you want to modify and/or contribute to the package, you can install it locally by cloning the repository and installing the dependencies with Poetry. Note, that, if you plan to submit jobs to CERN HTCondor from a local Python installation, you should move to your AFS space first (e.g. cd /afs/cern.ch/work/u/username/private).:

git clone --recurse-submodules https://github.com/ColasDroin/study-DA.git

If you missed this step and clone the repository without the submodules, you can do a posteriori:

git submodule update --init --recursive

Cloning the submodules is important as this allows to download the optics for HL-LHC, which are necessary to run the tracking examples. Therefore, you should be able to skip the Installing the optics section.

Installing with Poetry

Standard installation with Poetry

If not already done, install Poetry following the tutorial here.

For easier submission later, impose the virtual environment to be created in the repository folder by running the following command:

poetry config virtualenvs.in-project true

Be careful where Python is installed

If you're from CERN and intend to submit jobs to HTCondor from your local Python environment, ensure that the executable that Poetry will use to spawn a virtual environment is available on AFS.

You can check the base executable of Python that Poetry is using by running the following command:

poetry env info

If needed (for instance, if your Python base executable is not on AFS), you can change the exectutable with e.g:

poetry env use /full/path/to/python

If you're not interested in using GPUs, you should jump directly to the Installing dependencies section. Otherwise, follow the next section.

Are you sure you want to install study-DA locally?

If you're not planning to contribute to the package, it is recommended to install it with pip from PyPI, from a conda environment. Installing the package locally makes it much harder to have it compatible with GPUs.

Installing with Poetry for GPUs

Using Poetry along with GPUs is a bit more complicated, as conda is not natively supported by Poetry. However, not all is lost as a simple trick allows to bypass this issue. First, from a conda-compatible Python environment (not the one you used to install Poetry), create a virtual environment with the following command:

conda create -n gpusim python=3.11
conda activate gpusim

Now configure Poetry to use the virtual environment you just created:

poetry config virtualenvs.in-project false
poetry config virtualenvs.path $CONDA_ENV_PATH
poetry config virtualenvs.create false

Where $CONDA_ENV_PATH is the path to the base envs folder (e.g. /home/user/miniforge3/envs).

You can then install the CUDA toolkit and the necessary packages (e.g. cupy) in the virtual environment (from Xsuite documentation ):

conda install mamba -n base -c conda-forge
mamba install cudatoolkit=11.8.0

Don't forget to select the path to your virtual environment for submission with the submit()method will be the conda one (e.g. home/user/miniforge3/bin/activate, and add right after conda activate gpusim), i.e.:

submit(
    ...
    path_python_environment="/home/user/miniforge3/bin/activate; conda activate gpusim",
    ...
)

You're now good to go with the next section, as Poetry will automatically detect that the conda virtual environment is activated and use it to install the dependencies.

Installing dependencies

Finally, install the dependencies by running the following command:

poetry install

Developer installation

If you plan to contribute to the package, you can install the dependencies needed for development (tests, documentation) with:

poetry install --with test,docs,dev

At this point, ensure that a .venv folder has been created in the repository folder (except if you modified the procedure to use GPUs, as explained above). If not, follow the fix described in the next section.

Nafflib dependencies

If you encounter an error while installing nafflib, you can install it manually with:

poetry run pip install nafflib
poetry install

Conda compilers

If you encounter an error while installing the dependencies, you may need to install the compilers and cmake with conda. You can do so by running the following commands:

poetry shell
conda install compilers cmake

Finally, you can make xsuite faster by precompiling the kernel, with:

poetry run xsuite-prebuild regenerate

To run any subsequent Python command, either activate the virtual environment (activate a shell within Poetry) with:

poetry shell
# you then run a command as simply as `python my_script.py`

or run the command directly with Poetry:

poetry run python my_script.py

At this point, the only step left is to install xmask (which is normally already cloned), which is an external dependency that is not handled by Poetry since it requires cloning submodules. You can do so by running the following commands:

poetry shell
cd external_dependencies
pip install -e xmask

Installing locally without Poetry

For local installations, it is strongly recommended to use Poetry as it will handle all the packages dependencies and the virtual environment for you. However, if you prefer to install the dependencies manually, you can do so by running the following commands (granted that you have Python installed along with pip):

pip install -r requirements.txt

# Now install xmask
cd external_dependencies
pip install -e xmask