Rivet is hosted by Hepforge, IPPP Durham

Docker instructions

Obtaining docker is explained here: https://docs.docker.com/engine/installation/

Note: on linux systems, make sure to create a group "docker" and add yourself to it. Otherwise you will need to run all docker commands as sudo.

sudo groupadd docker
sudo usermod -aG docker $USER

After that you need to logout and log back in for the group change to take effect. Now you are able to use docker without sudo.

These steps need only be done once.

MAC requirements

Quote from docker webpage: Docker for Mac requires OS X El Capitan 10.11 or newer macOS release running on a 2010 or newer Mac, with Intel’s hardware support for MMU virtualization. The app will run on 10.10.3 Yosemite, but with limited support. Please see What to know before you install for a full explanation and list of prerequisites.

Obtaining a docker image for rivet

The command is simply

docker pull hepstore/rivet:2.5.4

This will download and store the docker container in /var/lib/docker on your linux or mac system.

Running the container interactively

The most basic thing to do is to simply run bash inside the container as such:

docker run -it --rm hepstore/rivet:2.5.4 bash

This gives you full access to anything inside the container. This is probably a good cross-check to see if your docker permissions are correct.

To see a list of available rivet analysis you can now do this:

docker run -i --rm hepstore/rivet:2.5.4 rivet --list-analyses

Running Rivet through docker

In the following, a proposed way of working with rivet through docker is given.

To mount your current directory on the host system into the container and making it the current directory inside the container as well and set the same user and group ids as on the host system, we add this to the command line:

 -v $PWD:$PWD -w $PWD -u `id -u $USER`:`id -g`

A very efficient way of using rivet through docker is to use aliases as the command line does get quite lengthy.

If you set the following aliases in your shell, you have everything set up to run rivet, compile your own analysis code and make plots:

alias             rivet='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet'
alias  rivet-mkanalysis='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet-mkanalysis'
alias rivet-buildplugin='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet-buildplugin'
alias      rivet-mkhtml='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet-mkhtml'

# for yoda tools ...
alias      yodamerge='docker run -i --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 yodamerge'

You might want to put these alias definitions into your bashrc for persistence.

Note on SELinux systems, an additional docker run flag --privileged is sometimes required for read/write permissions:

alias             rivet='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet'
alias  rivet-mkanalysis='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet-mkanalysis'
alias rivet-buildplugin='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet-buildplugin'
alias      rivet-mkhtml='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 rivet-mkhtml'

# for yoda tools ...
alias      yodamerge='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.4 yodamerge'

You now can use the following commands from your host system's terminal:

rivet              --- this is the main program
rivet-mkanalysis   --- this creates analysis code templates 
rivet-buildplugin  --- this compiles your own analysis code
rivet-mkhtml       --- this is used for plotting the output histograms

Example run

We provide some hepmc events (input for rivet) for download: http://www.hepforge.org/archive/rivet/Z-hadronic-LEP.hepmc

mkdir testRivet && cd testRivet
wget http://www.hepforge.org/archive/rivet/Z-hadronic-LEP.hepmc
## Or on MAC
curl -O http://www.hepforge.org/archive/rivet/Z-hadronic-LEP.hepmc

To run a few analyses on these 10k LEP events, you can do something like this:

rivet Z-hadronic-LEP.hepmc -a SLD_2002_S4869273 -a OPAL_1998_S3780481 -a ALEPH_2001_S4656318 -a DELPHI_2011_I890503

To plot the resulting output file Rivet.yoda the following command suffices:

rivet-mkhtml --mc-errs Rivet.yoda:"MC Simulation"

A new folder rivet-plots will have appeared in your current directory on the host system ready for inspection with your browser, e.g.

google-chrome rivet-plots/index.html

Easy, right?

Running on gzip compressed HepMC files

Running on gzip compressed files requires a slight modificaition of the command line:

gunzip -c Ztautau_mue_100k.hepmc.gz | rivet -a MC_GENERIC --pwd -H BG.yoda

If you encounter this error: cannot enable tty mode on non tty input make sure you do not use -it in the docker run command but -i.

I.e. you alias should look like this:

alias  rivet='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:2.5.3 rivet'

Running with generator output (under construction)

If you have a generator able to write hepmc to STDOUT, you can do:

mkfifo hepmc.fifo
MYGENERATOR -o hepmc.fifo &
rivet -a MC_GENERIC hepmc.fifo

just as well.

Last modified 5 weeks ago Last modified on Oct 15, 2017, 11:27:17 PM