Tutorial on MC event generators

Held by the MCnet collaboration at the CTEQ / MCnet School 2021.

Container Option (preferred)

This tutorial uses containers. Please install Docker on your personal computer prior to the tutorial. If you have questions on installing Docker or on testing the Docker environment, please ask the lecturers before the tutorial. Due to time constraints we cannot assist everyone with setting up Docker during the tutorial itself. A common problem is an error message like docker: Got permission denied while trying to connect ... In this case, try adding your user to the docker group. On Linux, for example, run sudo usermod -aG docker $USER && reboot

Download

The Docker containers can be pulled directly from dockerhub. In case of the Sherpa container, the command line would read

docker pull cteqschool/tutorial:sherpa-2.2.7

The tutorial is obtained from GitLab. You can clone the repository using

git clone https://gitlab.com/shoeche/tutorials.git

Running the containers

We recommend to run the container for the MC tutorial with your home directory mounted and using your actual userid. For the custom rivet analysis to work you will also need to set the RIVET_ANALYSIS_PATH environment variable. In order to simplify the docker call you may define an alias. In case of the Sherpa container the definition would read

alias docker-run-sherpa='docker run -it -u $(id -u $USER) -v $HOME:$HOME \ -w $PWD --env="RIVET_ANALYSIS_PATH=." cteqschool/tutorial:sherpa-2.2.7'

You may consider adding the --rm flag to automatically clean up after your container exits. Note that in this case all modifications you may have made to the container will be lost.

Running the tutorials

Instructions for the tutorials are found online and in the tutorials/ folder checked out from GitLab. There are three main directories, ll/, mc/ and ps/, corresponding to the resummation tutorial, Monte Carlo usage and Monte Carlo development tutorial. For the resummation and developers tutorial, please refer to the worksheets in the ll/ and ps/ folders. Within the mc/ folder, there is a directory sherpa/. Please refer to the generator-specific instructions in this directory.

Virtual Machine Option (deprecated)

In case of insurmountable problems with Docker you may use a legacy virtual machine. In this case, please install Oracle Virtual Box on your personal computer prior to the tutorial. If you have questions on installing VirtualBox, please ask the lecturers before the tutorial. Due to time constraints we cannot assist everyone with setting up the environment during the tutorial itself.

Download

The virtual machine disk can be downloaded from here. Unarchive the disk using 7-Zip. If 7-Zip is missing on your Linux system, install the package p7zip. On Windows, download the executable from here. On MacOS, use the unarchiver.

Creating the Virtual Machine

Create a new machine with VirtualBox using the GUI. In the first step, VirtualBox will ask for the name of the machine and its OS. For the latter choose Linux -> Ubuntu (64 bit). In the next step, set the size of the memory. About 1GB should be fine. In the last step, select the virtual disk. Choose 'Use an existing virtual hard drive file' and open the *.vdi file you just downloaded and extracted.

Before starting the virtual machine, enter its settings and increase the video RAM size to at least 48MB (Settings -> Display -> Video). If you have more than two processor cores on your host system, allow the VM to use two cores (Settings -> System -> Processor). You must enable hardware virtualization in your BIOS to do this!

Starting the Virtual Machine

We are booting a lightweight Linux, which you can customize.

The login name is student, the password is 2019.

The keyboard layout can be set using the layout switcher in the task bar, or by running setxkbmap LC in the terminal, where LC is your language code (us, de,...).

Common tools which are installed include xterm, lxterminal, vi, emacs, gv, evince and firefox. If you need root privileges to install further programs of your choice, use sudo. Note that the package information has been purged, and you need to run sudo aptitude update before any other command.

Running the tutorial

Instructions for the tutorials are found online and in the ~/tutorials/ folder of the virtual machine. There are three main directories, ll/, mc/ and ps/, corresponding to the resummation tutorial, Monte Carlo usage and Monte Carlo development tutorial. For the resummation and developers tutorial, please refer to the worksheets in the ll/ and ps/ folders. Within the mc/ folder, there is a directory sherpa/. Please refer to the generator-specific instructions in this directory.