Gmc trans

From EIC
Jump to navigation Jump to search

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.

Figure 1: Definition of azimuthal angles in a SIDIS event.

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:

Table 1: gmc_trans configuration parameters
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:

Table 2: Produced hadron species supported by gmc_trans.
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.

Table 3: Paramterisations of unpolarised fragmentation functions:
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.


Table 4: Transversity parameterisations available in gmc_trans:
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.


Table 5: Collins fragmentation function parameterisations available in gmc_trans:
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).


Table 6: Sivers function parameterisations available in gmc_trans:
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.


Table 7: Boer-Mulders function parameterisations available in gmc_trans:
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:

  1. The incident lepton
  2. The incident hadron
  3. The scattered lepton
  4. 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:

  1. inputFile.txt is the name of the gmc_trans event file.
  2. outputFile.root is the name you wish to give to the produced ROOT file.
  3. 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.

Retrieved from "https://wiki.bnl.gov/eic/index.php?title=Gmc_trans&oldid=7632"