Setup

Setup for users

With Python 3 locally available

The library is available for installation as a PyPI package and can be installed from the terminal with pip:

pip install hepdata_lib (--user)

The --user flag lets you install the package in a user dependent location, and thus avoids writing to the location of your system’s main python installation. This is useful because in many cases you, the user, do not have writing permissions to wherever the system keeps its python.

If you are running on your own computer or laptop, it’s up to you to decide where you want to install the package. However, we recommended to install it inside a virtual environment (see Setting up a virtual environment)

This setup naturally restricts you to use the latest stable version of the package in pypi. If you would like to use the code as it is the github repository, please follow the instructions in Setup for developers.

Using Apptainer

On LXPLUS and many other local computing sites with CVMFS and Apptainer (previously called Singularity) available, you can use the library without having to install anything:

apptainer run /cvmfs/unpacked.cern.ch/ghcr.io/hepdata/hepdata_lib:latest /bin/bash

This opens a new shell with hepdata_lib, ROOT, and Python 3 available. Your home directory and most other user directories on the machine on which you execute Apptainer will also be accessible from within this shell.

Using SWAN

SWAN requires a CERN account. hepdata_lib should already be installed in most recent LCG Releases used by SWAN. The latest LCG Release might not contain the latest hepdata_lib version. The LCG Nightly, possibly containing a more recent hepdata_lib version, can be used by selecting the “Bleeding Edge” software stack in the SWAN configuration. Alternatively, you can upgrade hepdata_lib by adding a local installation path to the $PYTHONPATH in a startup script specified as the “Environment script” in the SWAN configuration (see Install packages in CERNBox). Then execute !pip install hepdata_lib --user --upgrade in your Jupyter notebook to upgrade hepdata_lib to the latest version.

Setup for developers

The general comments about installing a python package (see Setup for users) apply here, too. Use a virtual environment (see Setting up a virtual environment)!

If you would like to develop the code, you need to install the package from the up-to-date GitHub repository rather than the stable release in PyPI. To do this, you can use the pip -e syntax. The GitHub repository can be cloned using either an HTTPS URL (git clone https://github.com/HEPData/hepdata_lib.git) or an SSH URL:

cd $SOMEPATH
git clone git@github.com:HEPData/hepdata_lib.git
cd $SOMEPATH/hepdata_lib

python3 -m venv myhepdata
source myhepdata/bin/activate  # activate virtual environment!
pip install -e $SOMEPATH/hepdata_lib

Any changes you now make in your local copy of the repository (editing files, checking out different branches…) will be picked up by the python installation in your virtual environment.

Setting up a virtual environment

The goal of a virtual environment is to have a clean python copy to work with for each of possibly many projects you work on. This makes it easy to keep track of which python packages you installed for what purpose and gives you a way of installing different versions of the package.

For documentation on how to set up and work with virtual environments, please check out Installing packages using pip and virtual environments. The venv module has been provided in the standard Python library since Python 3.3, avoiding the need to install separate virtualenv and virtualenvwrapper packages as was the case with earlier Python versions.

You can create a virtual environment to work in:

python3 -m venv hepdata_pypi
source hepdata_pypi/bin/activate
pip install hepdata_lib

You can then have a second virtual environment for installing the development branch:

python3 -m venv hepdata_git
source hepdata_git/bin/activate
pip install -e $SOMEPATH/hepdata_lib

You can always activate the virtual environment in another shell by sourcing the relevant activate script, which also allows you to easily switch between the two instances:

source hepdata_pypi/bin/activate
python myscript.py  # Execute script using pypi package

Setup on lxplus with CMSSW

The hepdata_lib library is shipped with CMSSW via cmsdist. However, please make sure that you are using a recent CMSSW release, since otherwise you might be using an outdated version of the library. After running cmsenv, you can check the installed version as follows:

python3 -m pip list | grep hepdata-lib

(mind the use of hepdata-lib above, when importing, the package is still called hepdata_lib). If the version is significantly older than the one on PyPI, please use the Apptainer container as described at Setup for users above.