Installation

Installation #

The easiest way to start using Rivet is via the Docker system (see https://www.docker.com/), which is like a lightweight Linux virtual machine that’s easily installed and run on Mac, Linux and Windows machines. See the dedicated Docker tutorial page for more detail.

The rest of these instructions are mainly aimed at users who want to natively install and run a release of Rivet on their machine.

Native installation of Rivet and all dependencies ##

The simplest Rivet installation uses a “bootstrap” script to install Rivet and all its dependencies from release tarballs.

Prerequisites ##

Python header files are required. On Ubuntu and other Debian Linux derivatives, you can use this command to install the necessary files system-wide: sudo apt-get install python-dev. You will also need a C++ compiler capable of building the C++14 dialect: on systems like CERN lxplus you can get such an environment with:

source /cvmfs/sft.cern.ch/lcg/releases/LCG_99/ROOT/v6.22.06/x86_64-centos7-gcc10-opt/ROOT-env.sh

(OBSOLETE? A different LaTeX setup can be similarly acquired from CVMFS by setting e.g. export PATH=/cvmfs/sft.cern.ch/lcg/external/texlive/2016/bin/x86_64-linux:$PATH)

Installation ##

1. Download the bootstrap script into a temporary working directory, and make it executable:

  cd /scratch/rivet
  wget https://gitlab.com/hepcedar/rivetbootstrap/raw/3.1.6/rivet-bootstrap
  chmod +x rivet-bootstrap

(Replace the version string as appropriate if you want to install other versions of Rivet.)

2. Check the options. Look at the header of the script to see all variables which you can set, e.g. to skip installation of certain dependencies if they are available in your system:

  less rivet-bootstrap ## and read...

3. Run the script. By default it will install the whole suite of Rivet dependencies and Rivet itself to $PWD/local, where $PWD is the current directory. We will refer to this installation root path as ROOT: where the word ROOT appears below, in commands for you to type in, you should replace it with the actual installation prefix you used when running rivet-bootstrap

If you need to change that, specify the corresponding values on the command line. Other variables used by the script can be set at the same time if you wish. Examples:

# To install to $PWD/local:
./rivet-bootstrap

or

# To install to ~/software/rivet
INSTALL_PREFIX=$HOME/software/rivet MAKE="make -j8" ./rivet-bootstrap

Other variables used in the script, such as version numbers, can be overridden this way. Those other than INSTALL_PREFIX and MAKE are mainly of interest to developers, though. It is possible that you will need a developer-style setup of the Rivet development version rather than a released version: in this case you will need to have essential developer tools like autotools and Cython already installed, then pass INSTALL_RIVETDEV=1 as a command-line variable.

Setting up the environment ##

After the script grinds away for a while, it will tell you that it is finished and how to set up a runtime environment (similar to that used inside the build script) for running Rivet. A sourceable rivetenv.(c)sh script is provided for (c)sh shell users to help set up this environment. Here’s how to set up the environment and then test the rivet program’s help feature and analysis listing:

  source ROOT/rivetenv.sh
  rivet --help
  rivet --list-analyses

If that works, everything is installed correctly. If you are using the bash shell in your terminal, then Rivet will offer you programmable tab completion: try typing rivet and pressing the Tab key! Note the space before pressing Tab: if you just type rivet + Tab, without a space, you’ll get a handy list of all the Rivet tool programs.

You may wish to add the environment variable settings to your ~/.bashrc shell config file, so that Rivet will work without needing any special session setup.

Troubleshooting ##

PYTHONPATH and other path-search issues ##

The main things that can go wrong during Rivet installation and setup are related to the Python interface. Rivet relies heavily on Python interfaces to the C++ libraries for its user-facing command-line scripts, but this requires a suitable Python environment before installation.

If you hit problems, a good first idea is to make sure that the installation prefix is treated as a valid location for Python to load packages from before running the installation process. If installing into a system location like /usr/local this should be automatic, but if doing something more custom, you may need to set or append to the PYTHONPATH environment variable. (This, and equivalent additions to the PATH and (DY)LD_LIBRARY_PATH environment variables for executable and shared-library loading respectively, is done post-build by the rivetenv.(c)sh setup script.)

The usual install path for Rivet’s Python package is in $INSTALL_PREFIX/lib/pythonX.Y/site-packages, but it’s best to check your system for variations. Once confirmed, put export PYTHONPATH=$INSTALL_PREFIX/lib/pythonX.Y/site-packages:$PYTHONPATH into your shell environment, and then run the installer.

Mac: untrusted binaries ##

The second Python issue is specific to Macs, on which the system Python is configured to refuse to load modules that load “untrusted” binary libraries… like libRivet. We have not found a satisfactory workaround for this restriction, which seems designed under the assumption that Mac users will not be developers of Python extensions to compiled non-system libraries. Since this is unrealistic for HEP use, we recommend avoiding the Mac-system Python and compiler suite entirely, in favour of developer packages from e.g. Homebrew or Conda.

Mac: Rivet cannot find HepMC2 lib ##

On recent version macOS, the bootstrap script fails to install Rivet against HepMC2 with an error message similar to:

from rivet.core import * 
ImportError: dlopen(/.../rivet/core.so, 10): Library not loaded: libHepMC.4.dylib

This issue seems to have disappeared with HepMC3, so unless HepMC2 is strictly required, a simple workaround is to change HEPMC_VERSION to a recent HepMC3 version in the bootstrap script.