Gmc trans
gmc_trans is a Monte Carlo generator for semi-inclusive deep inelastic scattering (SIDIS). It simulates single hadron production from the scattering of a lepton on a transversely polarised hadron. It includes the hadron transverse spin ("transversity") distribution and transverse-momentum-dependent (TMD) distributions, such as the Sivers distribution function.
Overview
The code was originally written for the HERMES experiment, with a 27.57 GeV electron or positron beam incident on a fixed proton target. The code has been rewritten by the EIC collaboration to function for collider kinematics with arbitrary lepton and proton beam energies. The code is written almost entirely in Fortran, with a small amount of C used to interface with the Gnu Scientific Library (GSL) VEGAS integration routine.
Outline of generation procedure
The unpolarised and helicity distributions (f1 and g1) and the unpolarised fragmentation functions (D1) are provided by parameterisations of data (for example the Kretzer fragmentation functions). The transversity (h1) and TMD functions are provided using either relations to the unpolarised (or helicity) distributions, or via parameterisations of data. The parameterisations available for each are detailed below. A Gaussian ansatz is used for all transverse momentum dependence i.e. for any function F(x,kT2)
F(x,kT2) = F(x)[kT2/⟨kT2⟩].
Before generating events, gmc_trans checks that all distributions that have been turned on for the event generation obey positivity.
The code analytically calculates the scattering cross section as a function of Bjorken x, Q2 and z. To generate an event, first the flavour of the struck quark is randomly chosen according to the (integrated) unpolarised cross section. The kinematic variables Bjorken x, Q2 and z are then randomly generated according to the unpolarised cross section. The transverse momentum (PT) of the produced hadron is generated according to a Gaussian ansatz. The polarised cross section is then used to generate two angles with respect to the lepton scattering plane (in the virtual-photon-proton centre of mass frame): φ, the azimuthal angle of the produced hadron; and φS, the angle of the transverse spin of the incident hadron. These are illustrated in figure 1. These angles allow construction of the scattered lepton and produced hadron momenta. The output for each event is the scattered beam lepton and the produced hadron in the lab frame. Note that the same hadron species is produced for every event in a single run of the programme.
Running the code
An installation of the gmc_trans code is located in the EIC AFS region, at
/afs/rhic.bnl.gov/eic/PACKAGES/gmc_trans/
The executable, also called gmc_trans, is located in this directory. To run the code simply type
> gmc_trans
Status, warnings and other information about the generation procedure will be printed to the screen. To retain it, simply direct it to a file:
> gmc_trans > logfile
The code can be run from any directory, so long as the directory contains a file named options.dat, which sets the configuration parameters for the run. An example options.dat file is provided in the gmc_trans/ directory. Each line in options.dat contains a variable name and a value to assign to it. Most of these settings need not be changed under normal circumstances; the most important ones are explained below. For the code to function, all the lines are required and must remain in the order given in the example. Comment lines are not allowed, but inline comments following the variable/value pair are allowed.
Obtaining your own copy of the code
If you wish to compile your own copy of the code then everything you require is contained in the compressed archive gmc_trans.tar.bz2 in the gmc_trans/ directory. To decompress and extract the archive type
> tar -jxf gmc_trans.tar.bz2
The code can then be compiled by running make in the gmc_trans/src/ directory:
> cd gmc_trans/src/ > make
This will produce the executable gmc_trans in the gmc_trans/ directory. The package requires the CERN library, the Gnu Scientific Library (GSL) and the Monte Carlo generator PEPSI. If compiling at RCF, you don't need to specify where to look for these libraries; these are already set for the EIC computing environment. However if you are compiling on another computer system, the directories in which to search for these libraries must be specified. This can be done in the Makefile lcoated in the directory src/trans/. The variables to set are cernlibrary, gsllibrary and pepsilibrary.
Generator options
The behavior of gmc_trans is configured by providing a file called options.dat. Each line contains a variable name and a value to assign it. The most important of these are:
| Variable | Description |
|---|---|
| installationDirectory | The location of the gmc_trans directory. This is required to allow gmc_trans to locate the parton distribution and fragmentation function files it needs. |
| outputFileName | The name of the event file to generate. The format of the event file is described below. |
| numberOfEvents | The number of events (after cuts) to generate. |
| hadronBeamIsForward | Specifies which beam defines the positive z direction. If set to .TRUE. the hadron beam direction defines positive (forward) z. If set to .FALSE. the lepton beam direction defines positive z. |
| leptonPythiaId | Set the lepton beam species via its PYTHIA ID number. Currently only the electron (ID = 11) is supported. |
| leptonBeamEnergy | The energy of the lepton beam in GeV. |
| hadronPythiaId | Set the hadron beam species via its PYTHIA ID number. Currently only the proton (ID = 2212) is supported. |
| hadronBeamEnergy | The energy of the hadron beam in GeV. A fixed target setup can be obtained by setting this to zero. |
| genSet_PartonSet | Integer code setting the PEPSI polarised parton distribution to use. |
| genSet_TransvSet | Integer code to select the transversity (h1) parameterisation to use (see table). |
| genSet_CollinsSet | Integer code to select the Collins fragmentation function (H1⊥) parameterisation to use (see table). |
| genSet_SiversSet | Integer code to select the Sivers distribution function (f1T⊥) parameterisation to use (see table). |
| genSet_BoerMSet | Integer code to select the Boer-Mulders distribution function (h1⊥) parameterisation to use (see table). |
| genSet_HadronType | Type of the produced hadron: 1 = pion, 2 = kaon, 3 = proton (see table). |
| genSet_HadronCharge | Charge of the produced hadron: -1 = negative, 0 = neutral, 1 = positive (see table). |
| genSet_FragSet | Unpolarised fragmentation function parameterisation to use (see table). |
| genSet_FragOrder | Order of fragmentation parameterisation. 0 = leading-order, 1 = next-to-leading-order. |
| genSet_MeanpT | The mean intrinsic transverse momentum (pT) of the quarks in the Gaussian ansatz for TMD parton distributions. |
| genSet_MeankT | The mean fragmentation transverse momentum (kT) of the hadrons in the Gaussian ansatz for TMD fragmentation functions. |
| mcSet_CutVertex | If set to .TRUE., reject events whose kinematic quantities (Q2, ν, W2, x and y) lie outside the ranges specified by the next ten variables. |
| mcSet_Q2Min | Minimum Q2 to accept. |
| mcSet_Q2Max | Maximum Q2 to accept. |
| mcSet_NuMin | Minimum ν to accept. |
| mcSet_NuMax | Maximum ν to accept. |
| mcSet_W2Min | Minimum W2 to accept. |
| mcSet_W2Max | Maximum W2 to accept. |
| mcSet_XMin | Minimum Bjorken x to accept. |
| mcSet_XMax | Maximum Bjorken x to accept. |
| mcSet_YMin | Minimum y to accept. |
| mcSet_YMax | Maximum y to accept. |
| mcSet_CutScat | If set to .TRUE., reject events in which the scattered lepton's momentum and angles lie outside the ranges specified by the next eight variables. |
| mcSet_Pmin | Minimum momentum to accept. |
| mcSet_Pmax | Maximum momentum to accept. |
| mcSet_TheMin | Minimum polar angle to accept. |
| mcSet_TheMax | Maximum polar angle to accept. |
| mcSet_TheXMin | Minimum angle in the x direction to accept. |
| mcSet_TheXMax | Maximum angle in the x direction to accept. |
| mcSet_TheYMin | Minimum angle in the y direction to accept. |
| mcSet_TheYMax | Maximum angle in the y direction to accept. |
Species of produced hadron
Which species of hadron to produce is selected via the combination of genSet_HadronType and genSet_HadronCharge. genSet_HadronType can take the values 1 (pion), 2 (kaon) or 3 (proton). genSet_HadronCharge can take the values -1 (negative), 0 (neutral) or 1 (positive). The following hadron species are supported: π+, π-, π0, K+, K-, proton, anti-proton. These correspond to the following combinations of type and charge:
| genSet_HadronType | genSet_HadronCharge | Hadron |
|---|---|---|
| 1 | 1 | π+ |
| 1 | 0 | π0 |
| 1 | -1 | π- |
| 2 | -1 | K+ |
| 2 | 0 | n/a |
| 2 | -1 | K- |
| 3 | 1 | Proton |
| 3 | 0 | n/a |
| 3 | -1 | Anti-proton |
Note that production of neutral kaons or neutrons is not currently supported.
Fragmentation functions
There are four choices of parameterisation of the unpolarised fragmentation functions (D1), selected by genSet_FragSet. These are listed in table 3 with the species of produced hadron for which they are available.
| genSet_FragSet | Parameterisation | Supported species |
|---|---|---|
| 1 | S. Kretzer, Phys. Rev. D 62, 054001, 2000. | π± and K±; inclusive charged hadrons. |
| 2 | B.A. Kniehl, G. Kramer and B. Pötter, Nucl. Phys. B 582, 514, 2000. | Charge-summed π±, K±, anti(proton). |
| 3 | L. Bourhis, M. Fontannaz, J. P. Guillet and M. Werlen, Eur. Phys. J C 19, 89, 2001. | Inclusive charged hadrons. |
| 4 | D. de Florian, R. Sassot and M. Stratmann, Phys. Rev. D 75, 114010, 2007 and Phys. Rev. D 76, 074033, 2007. | π±,0, K±, (anti)protons; inclusive charged hadrons. |
Transverse spin and TMD distributions
The following distributions can be applied in the simulation:
- Transversity distribution, h1: the transverse spin polarisation of the quarks in the incident hadron.
- Sivers distribution, f1T⊥: the correlation between the transverse spin of the incident hadron and the intrinsic transverse momentum (kT) of the struck quark.
- Collins fragmentation function, H1⊥: the correlation between the transverse spin of the struck quark and the azimuthal distribution of its fragmentation products.
- Boer-Mulders distribution, h1⊥: the correlation between the transverse spin of the struck quark and its kT.
| mcSet_TransvSet | Description of parameterisation |
|---|---|
| 0 | No transversity distribution: h1 = 0. |
| 1 | The transversity distribution equals the helicity distribution: h1 = g1. |
| 2 | The transversity distribution equals the Soffer bound: h1 = ( f1 + g1 ) / 2. |
| 3-6 | Fits by Boglione and Leader (valence quarks only: sea quark h1 = 0). |
| 7 | Fit by Anselmino et al., PRD 75, 054032, 2007 using BELLE A12 asymmetry. |
| 8 | Fit by Anselmino et al., PRD 75, 054032, 2007 using BELLE A0 asymmetry. |
| 9 | Fit by Prokudin et al., DIS 2008. |
| mcSet_CollinsSet | Description of parameterisation |
|---|---|
| 0 | No Collins distribution: H1⊥ = 0. |
| 1 | The collins distribution equals the unpolarised fragmentation function: H1⊥ = D1. |
| 2 | ABM parameterisation. |
| 3 | Leader parameterisation. |
| 4 | Bacchetta parameterisation. |
| 5 | The first moment of the Collins distribution equals the unpolarised fragmentation function: H1⊥(1) = D1. |
| 6 | The Collins distribution follows the unpolarised distribution multiplied by a power of z: H1⊥ = zpD1 (p can be set via the variable genSet_CollinsZPow). |
| 7 | Fit by Anselmino et al., PRD 75, 054032, 2007 using BELLE A12 asymmetry (corresponds to transversity set 7). |
| 8 | Fit by Anselmino et al., PRD 75, 054032, 2007 using BELLE A0 asymmetry (corresponds to transversity set 8). |
| 9 | Fit by Prokudin et al., DIS 2008 (corresponds to transversity set 9). |
| mcSet_SiversSet | Description of parameterisation |
|---|---|
| 0 | No Sivers distribution: f1T⊥ = 0. |
| 1 | The Sivers distribution equals the unpolarised parton distribution: f1T⊥ = f1. |
| 2 | The sivers distribution equals the quark helicity distribution: f1T⊥ = g1. |
| 3 | "Rosetta Stone" fit by Mulders: f1T⊥ ∝ xα(1-x)βf1. |
| 4 | The first moment of the Sivers distribution equals the unpolarised parton distribution: f1T⊥(1) = f1. |
| 5 | Not currently used |
| 6 | "Broken sea" fit by Anselmino et al., EPJ A 39, 89-100, 2009. |
| mcSet_BoerMSet | Description of parameterisation |
|---|---|
| 0 | No Boer-Mulders distribution: h1⊥ = 0. |
| 1 | The Boer-Mulders distribution equals the unpolarised quark distribution: h1⊥ = f1. |
| 2 | The Boer-Mulders distribution equals the quark helicity distribution: h1⊥ = g1. |
| 3 | The first moment of the Boer-Mulders distribution equals the unpolarised quark distribution: h1⊥(1) = f1. |
| 4 | Fit by Zhang et al., PRD 77, 054011, 2008. |
Event file format
gmc_trans outputs the events in a plain text file. The data format is comparable to that produced by the other EIC Monte Carlo packages, to maintain a uniform data format across event generators. The file contains a header, followed by the generated events.
Event file header
The first six lines of the file comprise a header that gives the type of event generator, names the variables stored in each event, and marks the beginning of the events.
- The first two lines of the file header identify the file as gmc_trans output:
GMCTRANS EVENT FILE ============================================
- The third line names the event-wise variables stored in each event (still to be documented).
- The fourth line divides the names of event-wise variables from those of the track-wise variables:
============================================
- The fifth line names the track-wise variables, which are identical to those produced by the EIC group's PYTHIA output and are documented there.
- The sixth line ends the file header and marks the start of the events with
=BEGIN EVENTS================================
Event format
Each event contains a line of event information and four or more lines of track information, separated by the line
============================================
Each event has at least four tracks:
- The incident lepton
- The incident hadron
- The scattered lepton
- The produced hadron
In the case that the produced hadron is a neutral pion, two more lines follow (giving a total of six tracks). These describe the pair of decay photons of the pion. Events are separated by the line
=============== Event finished ===============
Therefore each event uses either nine (π0) or seven (other species) lines.
Analysing events in ROOT
The EIC group uses ROOT for its large-scale data analysis. A C++ class called TGmcTransEvent has been written to allow analysis of gmc_trans events in ROOT. The class is included in the gmc_trans package as a shared library, located in the directory gmc_trans/root/lib/.
Converting gmc_trans output to ROOT format
To convert the plain text gmc_trans output to a ROOT TTree, a macro named createGmcTransTree.C is provided in gmc_trans/root/macros/. This will produce a ROOT file containing a TTree, each entry of which is a single TGmcTransEvent. To run the macro, open ROOT and at the prompt type:
root [0] gROOT->LoadMacro("/afs/rhic.bnl.gov/eic/PACKAGES/gmc_trans/root/macros/createGmcTransTree.C")
root [1] createGmcTransTree("inputFile.txt","outputFile.root","treeName")
The first line loads the macro into ROOT and the second line runs it. The function createGmcTransTree takes three arguments, the first two of which are mandatory and the third of which is optional:
- inputFile.txt is the name of the gmc_trans event file.
- outputFile.root is the name you wish to give to the produced ROOT file.
- treeName is the name you wish to give to the TTree in outputFile.root. This is optional and by default is "events".
Analysing events
Before opening the TGmcTransEvent TTree file in ROOT, you must always load the TGmcTransEvent shared library to make the class available to ROOT. To do this, a macro named loadLibraries.C is provided in gmc_trans/root/macros/. To run the macro, open ROOT and at the prompt type:
root [0] gROOT->Macro("/afs/rhic.bnl.gov/eic/PACKAGES/gmc_trans/root/macros/loadLibraries.C")
The TGmcTransEvent class will now be available in ROOT.