JEWEL Docker Tutorial

Description

JEWEL is a Monte Carlo event generator simulating QCD jet evolution in heavy-ion collisions. It treats the interplay of QCD radiation and re-scattering in a medium with fully microscopic dynamics in a consistent perturbative framework with minimal assumptions.

Please refer to official page for more information: https://jewel.hepforge.org/

Docker Instructions

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

Linux Prerequisites

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 prerequisites

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.

Please use the docker webpage to obtain up-to-date information about possible Mac install issues.

Obtaining a Docker Image for JEWEL

The command is simply:

docker pull steepspace/jewel

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 steepspace/jewel 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.

Running JEWEL through Docker

In the following, a proposed way of working with JEWEL 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:

-u `id -u $USER`:`id -g` -v <path/to/PDFsets>:/usr/local/share/lhapdf/PDFsets -v $PWD:$PWD -w $PWD

IMPORTANT INFORMATION ABOUT PDF SETS

Due to the increasing number and size of PDF data files, LHAPDF no longer bundles PDF set data in the package tarball. The sets are instead all stored online at: https://lhapdf.hepforge.org/downloads?f=pdfsets//5.9.1

The default PDF data files for JEWEL to run are already provided in ./PDFsets.

Optional

Should you wish to add more, add the PDF data files to ./PDFsets. A script lhapdf-generate-list.py has been provided which will retrieve all of the links for the PDF data files and store them in lhapdf_link.txt. Generate the lhapdf_link.txt as follows:

./lhapdf-generate-list.py

You can choose to edit the lhapdf_link.txt file and keep only the links to the files which you wish to download. Next, using the lhapdf-getdata.sh script as follows will download all of the links from the lhapdf_link.txt within ./PDFsets:

./lhapdf-getdata.sh

Note: In the event that the script fails midway you can restart the script using the same command as above and it will skip the files that are already downloaded and proceed to download the rest.

WARNING: Total size of all pdf sets is ~16 Gb.

Useful Aliases

A very efficient way of using JEWEL 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 JEWEL and generate events:

alias jewel-simple='docker run -i --rm -u `id -u $USER`:`id -g` -v <path/to/PDFsets>:/usr/local/share/lhapdf/PDFsets -v $PWD:$PWD -w $PWD steepspace/jewel jewel-2.2.0-simple'
alias jewel-vac='docker run -i --rm -u `id -u $USER`:`id -g` -v <path/to/PDFsets>:/usr/local/share/lhapdf/PDFsets -v $PWD:$PWD -w $PWD steepspace/jewel jewel-2.2.0-vac'

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

Usage

Now to run the JEWEL generator using the default settings where no parameter file is needed:

jewel-simple

or

jewel-vac

Note, however, that also in the latter case nuclear PDF’s will be used.

A parameter file can to be passed to change the setting:

jewel-simple <params.dat>

Examples

An example of a parameter file is given in ./examples. To use the parameters from the examples:

cd examples
jewel-simple params/params-without-recoils.dat

or

cd examples
jewel-simple params/params-with-recoils.dat