Docker container for Pythia 8 + Dire

A fully working Pythia 8 + Dire docker container is available from docker hub. The current version is 1.1.0 and uses Pythia 8.235 and Dire 2.002. It inherits from the Professor container version 2.2.2, which, in turn, inherits from the Rivet container version 2.5.4.

Installation instructions for docker can be found here. On Linux systems, create a group "docker" and add yourself to it to avoid having to run all docker commands as sudo.
sudo groupadd docker
sudo usermod -aG docker $USER

Obtaining the docker image

Simply execute
docker pull pythiatools/pythiadire:1.1.0
to download and store the docker container in /var/lib/docker.

Running the container

In the following we use the shorthand docker run to mean running the container with the following options
docker run --rm -u `id -u $USER` -v $PWD:$PWD -w $PWD.
The option -v will mount your current working directory $PWD to a container directory with the same name. This allows the container to access your local files and to write files to the current working directory.

Jupyter notebooks

One of the main purposes of the container is to give an introduction to the Pythia8 and Dire event generator framework. The container contains a few Jupyter notebooks, where each cell contains a couple of lines of Python code and can be executed by pressing SHIFT+ENTER.

Note that some notebooks attempt to show pdfs. Depending on your browser, this might not work, as enabling plugins inside a sandboxed frame is not allowed. However, you can still view the pdf locally on your machine.

To work with the notebooks, simply execute the command
docker run -p 8888:8888 pythiatools/pythiadire:1.1.0
to start the docker container. It will create the directory $PWD/notebooks on the host system, where all notebooks of the container will be copied into. If the directory is already present and contains a notebook named as a notebook present in the container, the corresponding notebook will not be copied. This way, you are able to store the status of the notebooks and re-use them at a later point.

The terminal will display a link you can copy to a browser and it will redirect to a list of Jupyter notebooks and a README file, which contains information about the different notebooks. Note: if you encounter a This site can't be reached the link is of the form http://10715c9c96bd:8888/?token=... (where ... is a lengthy combination of letters and numbers), replace it with http://localhost:8888/?token=... and try again.

If you want to use custom Rivet analyses and or LHAPDF sets, simply store the relevant information in /some/path. The container will automatically detect source files of Rivet analyses and compile them into a Rivet library.

Event Generator + Rivet

As an alternative to the Jupyter notesbooks above, you can run Pythia8 or Dire and Rivet directly via
docker run pythiatools/pythiadire:1.1.0 eventGeneratorRun info
where info is a plain text file, with exactly 6 lines. An example looks like this:

ALICE_2016 ATLAS_2011_S8971293

The first line indicates the generator to be used, valid options are "pythia" or "dire", followed by the settings file to be used. The third line specifies the number of events. The fourth and fifth line specify the name of the fifo, to which the HepMC events are written, and the name of the resulting yoda-file respectively. Finally, the last line is a comma and/or whitespace separated list of Rivet analyses.

All Rivet analyses in your current working directory $PWD will be compiled to a Rivet library and any present LHAPDF PDF sets can be used as well.

Instead of specifying a file, you can also give all input as command line parameters. Remember to put quotes around the list of Rivet analyses if it contains any whitespaces. Here is the command for the above example,
docker run pythiatools/pythiadire:1.1.0 eventGeneratorRun dire test.cmnd 1000 hepmctest test.yoda "ALICE_2016 ATLAS_2011_S8971293".

To run rivet-mkhtml with custom Rivet analyses, we provide a wrapper that takes as the first command line argument a directory, where the custom Rivet analyses are found on your local machine (has to be $PWD or a subdirectory), followed by the usual input for Rivet. Here is an example,
docker run pythiatools/pythiadire:1.1.0 rivet-mkhtml-custom $PWD/analyses --mc-errs out1.yoda out2.yoda .

Event Generator Tuning

The container also provides some facilities for tuning with Professor and Rivet. It essentially automates what is done in the Jupyter notebook on tuning. There you can also find examples for the files on which is the tuning is based. The command is
docker run pythiatools/pythiadire:1.1.0 tuning parameterRangesFile templateFile weightsFile limitsFile nPoints polynomialOrder runCombinations mcDirectory bestTuneDirectory runCombinationsFile ipolBase tuneBase runMCfile runIpolFile runTuneFile runBestTuneFile,
where the first four command line arguments are the input files needed for the tuning: a file containing the ranges of the parameters, a template command file for Pythia 8 / Dire, a file for the weights, and a file for the limits during tuning (all to be found in your current working directory $PWD). The next three arguments give additional input for the tuning: the number of parameter points to sample, the run combinations to produce, and the order of the polynomial used for the interpolation. The next two command line arguments are the name of the directory in which the sampled parameter points and Monte Carlo runs should be stored and the name of the directory where the results for the best tune should be stored. The last seven arguments specifiy the output files produced by the tuning: the filename for the run combinations, the basename for the interpolation and tuning files, and the filenames for the scripts to produce the Monte Carlo runs, the interpolation, the tuning, and setting up the best tune (all will be found in your current working directory $PWD upon execution). Here is a concrete example,
docker run pythiatools/pythiadire:1.1.0 tuning ranges.dat template.cmnd weights.dat limits.dat 100 3 "0:1 1:10" mc bestTune runcombs.dat interpolation/ipol tuning/tune
The files,, and, can be used to perform the more computationally intense tasks on a cluster. The file can be used for producing the Monte Carlo runs with the container as described in the Event Generator + Rivet section. The file can be used to perform the interpolation for all run combinations. The file can be used to perform the tuning for all run combinations. The file can be used to find the best tune, get the eigentunes, and perform the relevant Monte Carlo runs. You have to modify the scripts according to your needs, for instance add commands to send jobs to a cluster.

Rivet and Professor

In addition you can use the container to run Rivet as described here and Professor as described here.