Deductor A parton shower event generator

Version 1

Zoltan Nagy and Davison E. Soper

We present here c++ code to generate events at hadron-hadron collider (and also electron-positron colliders and electron-hadron colliders). The code creates a hard scattering event and then generates parton showers for both the incoming and outgoing partons.

This code is for versions 1.0.0 and 1.0.2 of Deductor

Version 1.0.2 was used for the paper Effects of subleading color in a parton shower. The results for the figures in that paper were produced using the user files in deductor-user-1.0.2. The code is in the file deductor-1.0.2.tar.gz. We also provide a collection of sample user code in the file deductor-user-1.0.2.tar.gz. Probably the best way to get these is with the curl command as described below.

Version 1.0.1 was not released.

The code for the original version of Deductor is in the file deductor-1.0.0.tar.gz. We also provide a collection of sample user code in the file deductor-user-1.0.0.tar.gz.

Version 1.0.0 was used for the paper A parton shower based on factorization of the quantum density matrix, published in JHEP 06 (2014) 097.

Installing the code

Note that you need cmake plus C and C++ compilers. Your C++ compiler needs to comply with the C++11 standard. The deductor code is self contained. Deductor was tested with g++-4.8.1 and clang-3.3 on linux and MacOSX platforms. We also supply a sample of user routines. Some of these make use of FastJet. We include a copy of fjcore by M. Cacciari, G.P. Salam and G. Soyez for your convenience.

In this section, x.y.z = 1.0.2 for the current code. In the following sections, we assume that we are working with the current version, 1.0.2.

1. Create a working directory where you want the code to go and cd to that directory.
2. Download a copy of the code and a sample of user files with
   curl -O http://pages.uoregon.edu/soper/deductor/deductor-x.y.z.tar.gz
curl -O http://pages.uoregon.edu/soper/deductor/deductor-user-x.y.z.tar.gz
3. Unpack the files with
   tar -zxvf deductor-x.y.z.tar.gz
tar -zxvf deductor-user-x.y.z.tar.gz
4. This will create directories deductor-x.y.z and deductor-user-x.y.z inside your working directory.
5. Compile the main code with
   mkdir bld-duct
cd bld-duct
cmake ../deductor-x.y.z/
make install
cd ..
6. This should give you a working copy of Deductor. To check, execute deductor --help. This should print some useful information.
7. By default, the compiled code and libraries will be in the directories bin and lib in your home directory.

Initializing the code

1. deductor --module kernelname kernel7.cc
2. deductor --kernel kernelname

Running the code

You will need some user code to tell Deductor what to do. The idea is that Deductor generates events according to the collider that you specified and the hard scattering process that you want. Then it sends each event to an analyser routine of your devising, which accumulates the histograms that you want. You set up the histograms in an "init" function that is called when Deductor starts and then analyse each event in a "user" function.

Let us suppose that you would like to generate the distribution of gap fractions in a gap-between-jets problem. There is a directory AtlasGap in deductor-user-1.0.2 that is set up for this. So just change directory to deductor-user-1.0.2/AtlasGap and then follow these steps.

1. Create a Deductor module that could have any name you like but that you might like to call mod-AtlasGap. Use the code in mod-AtlasGap.cc and analyser-AtlasGap.cc for this. You will also need the FastJet code fjcore.cc, which we include. Execute
   deductor --module mod-AtlasGap mod-AtlasGap.cc analyser-AtlasGap.cc fjcore.cc
2. This will result in the creation of some files in a "bundle" directory mod-AtlasGap.bundle in deductor-user-1.0.2/AtlasGap.
3. Now invent a name for your run and run your code:
   deductor --calculate mod-AtlasGap -n runname
4. After a few minutes, Deductor will inform you that it has generated a certain number of events, 500000 in this case. (You may want to change 500000 to 50000 if you want to see some results faster.) That means that Deductor has put results for these events in a file in a subdirectory output in mod-AtlasGap.bundle. The results are there, but you don't want to read them in this form.
5. Instead, open a shell in the deductor-user-1.0.2/AtlasGap directory and excecute
   deductor --add mod-AtlasGap runname
6. This will create a directory results in deductor-user-1.0.2/AtlasGap. Here you will find files with results in tabular form, suitable for examining with, for example, gnuplot.
7. The mod-AtlasGap.cc code that you used specified that Deductor should generate 55000000 events. You can just execute deductor --add mod-AtlasGap runname from time to time and, when you think you have enough events, stop your run with control-C.
8. Later on, if you have multiple runs, say run1, run2, and run3, you can accumulate the results by executing
   deductor --add mod-AtlasGap run1 run2 run3

Learning more

Now that you have seen how Deductor runs, and enjoyed lunch and a cappuccino, you are ready to learn more about how the various user files operate. For this, please see the brief manual "Deductor version 1: How to use it."

Originally from 25 December 2014; Last updated 16 May 2016