ProtosGenerator < Sandbox

---+ Protos - PROgram for TOp Simulations

*Protos* is a *leading order (LO) generator* for some new physics processes involving the top quark.

Special attention is devoted to providing theoretical values of observables such as *angular asymmetries*, *spin correlations*, *polarizations*, etc.

The program also provide event output in *raw text format*, which can be interfaced to a *parton shower generator* as external processes.

This Twiki is based on the [[http://jaguilar.web.cern.ch/jaguilar/protos/manual.ps][Protos manual]].

---++ <span style="line-height: 1em;">Compiling Protos</span>

Download Protos from the <span style="text-decoration: underline;">[[http://jaguilar.web.cern.ch/jaguilar/protos/][author website]]</span>.

For *last* version =Protos2.2=, you can wget it with:

=wget <span style="text-decoration: underline;">http://jaguilar.web.cern.ch/jaguilar/protos/Protos22.tar.gz</span> && tar -xf Protos22.tar.gz=

Edit =extlib.mk= to link with the <span style="text-decoration: underline;">[[http://lhapdf.hepforge.org/][LHAPDF]]</span> libraries that are needed, on *lxplus* machines:

=EXTLIB = -L/afs/cern.ch/sw/lcg/external/MCGenerators/lhapdf/5.8.5/x86_64-slc5-gcc43-opt/lib/ -lLHAPDF=

Furthermore, one needs to set the =PATH= and =LD_LIBRARY_PATH= environment variables, with: [[%ATTACHURL%/export.sh][export.sh]]

Now, you can compile Protos with =make=.

---++ <span style="color: #630000; font-size: 19px; line-height: 1em;">Running Protos</span>

---++ Subdirectory Structure
 
   * =Red=: Generators for single top and top pair production with anomalous Wtb couplings. 
      * Available processes: tj, tbj, tb, tW, tWb and tt.
   * =White=: Generators for single top production through top flavour-changing neutral (FCN) couplings and top pair production with top FCN decay. 
      * Available processes: Zqt, Zt, Aqt, At, gqt, t, Hqt and Ht.
   * =Green=: Top processes with four-fermion effective operators. 
      * Available processes: llqt and ttlike.
   * =Rose=: Heavy vector-like quark production. 
      * Available processes: BB, Bbj, Bj, Tbj, Tj, TT, Ttj, Xtj, XX, Ybj, Yj and YY.

In each Protos subdirectory, the different generators are found in the folders of the form xx (tj, tbj, tt, etc.). 

The different running settings are:
   * *Running parameters* selected in =input/run.dat=.
   * *Standard Model parameters* selected in =input/smpar.dat=.
   * *Special features* for some processes are available in =input/tweak.dat=.
   * *Couplings values* are stored in =input/template.ini=.

After running the program with =./Protos-xx=, results are found in:
   * If *plots* are generated (see *running parameters*), they are found in the main Protos directory =Protos22/plots=.
   * If *log files* are generated (see *running parameters*), they are found in the main Protos directory =Protos22/output=.
   * If *raw text events* are generated (see *running parameters*), they are found in the main Protos directory =Protos22/events=.

---++++ A quick example - single top production

<strong>1. </strong>Go to =Red/tj= directory

<strong>2. </strong>Set common [[%SCRIPTURL{"view"}%auth/AtlasProtected/McProductionCommonParameters#Default_mass_and_width_values_co][ATLAS Standard Model parameters]] in =input/smpar.dat=: [[%ATTACHURL%/smpar.dat][smpar.dat]]

<strong>3. </strong>One has to provide to Protos the right values of the following couplings: =VL=, =VR=, =gR= and =gL=.
These values (which yield the W helicities) depend on the top quark mass. 

For a top-quark mass of 172.5, one has to modify the =input/template.ini= file:
=cp ../../DATA/template-172.5.ini input/template.ini=

*4.* Also, one can edit =input/run.dat= with the appropiate run parameters: [[%ATTACHURL%/run.dat][run.dat]]
   * In addition, one can choose the decay of final state W boson, i.e. the electron or muon channel, with the =ILEP= variable: 
      * =ILEP= - 1, 2, 3 selects decay of the W boson to enu, munu and taunu, respectively.
<strong>5. </strong>To generate the weighted events, do: =./Protos-tj=

<strong>6. </strong>When it is finished, the results will be found on the events directory (in the Protos main directory).

Two files are created: =tj.wgt= containing all weighted events and =tj.par= containing the process parameters.

If one wants to cover the whole phase space, has to simulate millions of events in order to cover the less probable regions of the phase space.

<strong>7. </strong>To unweight the events using the =unw= program which can be found in the =unw= directory.

Just edit =unw/input/run.dat= and set =PROCNAME= to the correct value and do: =./Protos-unw=

This creates two new files in the events directory: =tj.unw= with the unweighted events and =tj_unw.par= with the corresponding parameters.
---++++ Running parameters

In =input/run.dat= one can set the following entries:

   * =PROCNAME= - This is the name that will label all generated files (events, plots and log files)
   * =CM energy=
   * =IPPBAR= - Set to 0 for pp collisions and to 1 for ppbar collisions.
   * =NRUNS= - In order to enable iterative runs this must be set to =NRUNS= &gt;1. Maximum is 99.
Phase space integration is done using VEGAS in two steps.

First, a "warm-up" integration is done to build adequate grids for the integration of the different subprocesses. In this phase, the relative weight of these subprocesses (determined by the cross sections) are also calculated. Second, the final integration is performed.

The parameters which control this are:

   * =ILOADGRID= - If 0, it generates a new grid. If 1, it reads a previously stored grid (from input subdir.)
   * =ISAVEGRID= - If 1, it saves the grid for later use. If 0, it does not.
   * =NCALL1= - Approximate number of points of warm-up integration.
   * =ITMX1= - Number of iterations of the warm-up integration.
   * =NCALL2= - Approximate number of points of final integration.
   * =ITMX2= - Number of iterations for the final integration.
   * =idum0= - Initial random seed used.
Usually, =ILOADGRID= is set to 1 and =ISAVEGRID= to 0.

   * =ILEP= - Decay channel for one or two W (or =ILEP1= and =ILEP2= for one W and one Z). These values depend on the process.
   * =ICUT= - Allows to activate plase space cuts in the subroutine =PSCUT= of the file =evtgen.f=. By default, phase space cuts are not included but can be set by the user. The executable must be recompiled then.
Following parameters control generated outputs (activated if set to 1, deactivated if set to 0).

   * =EVTOUT= - Output of weighted events.
   * =IPLOT= - Plots in ASCII format.
   * =ILOG= - Log files generation.
   * =IVERB= - Verbose information from each VEGAS iteration.
   * =IPRSUB= - Print the contribution to the cross section of the different subprocesses at the end of the run.
   * =IPRAS= - Print the value of selected asymmetries at the end of the program run.

After these flags, top anomalous couplings are set, dicussed for each process separately (see *[[http://jaguilar.web.cern.ch/jaguilar/protos/manual.ps][Protos manual]]* for further references).

The following parameters are:

   * =ISCAN= - If set to -1, it makes the initial random seed change by one unit in each run of =NRUNS=.
   * =SCANSTEP= - If =ISCAN= different of -1, anomalous couplings are changed by adding a quantity =SCANSTEP= each run.
   * =IPDFSET= - Allows to select a =LHAPDF= set.
   * =QFAC= - or =QFAC1= and =QFAC2=, are the numerical values multiplying the factorisation scale(s).
For each process, one can find special features to set.
---+ 
---+ 
---+ <span style="line-height: 1em;">Protos Documentation</span>

---++ Single Top Production Genera<span style="line-height: 1em;">tors</span>

<span style="line-height: 1em;"> </span><span style="line-height: 1em; font-size: 12px; font-weight: bold;">These generators are described with more detail [[http://arxiv.org/abs/0803.3810][here]]</span><span style="line-height: 1em; font-size: 12px; font-weight: bold;">.</span>
---+++++ Running parameters
---++++++ Decay channel

=ILEP= <span style="color: #000000; font-size: small;"> - Chooses the decay channel of the final state W boson(s):</span>
   * For tj, tbj and tb: =ILEP= = 1, 2, 3 selects decay of the W boson to enu, munu and taunu, respectively. =ILEP= = 4 is used to include all three channels.
   * For tW and tWb: =ILEP= = 1,2,3 selects decay of the W boson to enu, munu and taunu, respectively, and the other W decays hadronically. =ILEP= = 4 includes all three semileptonic channels. =ILEP= = 5 selects a fully hadronic channel for both W bosons, and =ILEP= = 6 selects the dilepton channel.
---++++++ Vertex couplings

These generators include the most general Wtb vertex arising from dimension-six gauge-invariant effective operators, parameterised as *[[http://arxiv.org/abs/0811.3842][here]]*.

The four couplings VL, VR, gL and gR can be set in =run.dat=.

The first two parameters found in the file =input/tweak.dat= allow to switch on and off the anomalous couplings independently in top production and top decay.

A further option is to fix the helicity of W in the top decay, this can be done by selecting a =scenario= in =tweak.dat=: setting this parameter to 1, 2 or 3 ocerrides the values VL, VR, gL and gR in =run.dat= and replaces them by values which give a W boson with helicity of -1, 0 or 1. This option can be used in combination with the other tweaks to generate templates with a fixed single top cross section (and kinematical distributions) and different W helicities if anomalous couplings are deactivated in the production but not in the decay.

For tj and tW generators, the =tweak.dat= last option selects the flavour of the initial d/s/b quark.

=WARNING=: The values of the couplings depend on the top-quark mass. Values for masses of 175 and 172.5 are found in the Protos directory /data. The values for other top masses can be calculated by using the full analytic expressions for helicity fractions (see [[http://arxiv.org/abs/hep-ph/0605190][ *here* ]]).

When running the program iteratively, the anomalous couplings can be varied in each run:

   * =ISCAN= = 1, 2, 3, 4, 5, 6, 7 varies VL, Re(VR), Re(gL), Re(gR), Im(VR), Im(gL) or Im(gR), respectively, by a quantity =SCANSTEP=.
---++++++ Factorisation scales

For each process the factorization scales are:

   * tj: =Q^2 = -p(W)^2= for the light quark and =Q^2 = -p(W)^2 + m(top)^2= for the b quark. This values are multiplied by =QFAC1= and =QFAC2= in =run.dat=.
   * tbj: =Q^2 = -p(W)^2= for the light quark and =Q^2 = p(b)^2 + m(b)^2= for the gluon. This values are multiplied by =QFAC1= and =QFAC2= in =run.dat=.
   * tb: =Q = sqrt(s)=, multiplied by =QFAC=.
   * tW and tWb: =Q = m(top) + M(W)=, multiplied by =QFAC=.
These scales can only be changed by rewriting the code in =evtgen.f=, in the subroutine =MSQ=.
---++++++ Double counting removal

For tj/tbj and tW/tWb, a matching can be done to remove double counting.

Matching options for tj/tbj are:

   * =IMATCH= = 0, does not perform any matching.
   * =IMATCH= = 1, applies subtraction to the b quark PDF for tj. It has no effect on tbj.
   * =IMATCH= = 2, performs a matching based on the transverse momentum of the extra b quark. This procedure has no effect on tj at the generational level (the correction is applied later on the parton shower Monte Carlo). For tbj, the b quark transverse momentum is required to hace a minimun transverese momentum, whose value is determined by the parameter =PTbmin=, set by default to 10.
The matching options for tW are:

   * =IMATCH= = 0, does not perform any matching.
   * =IMATCH= = 1, applies subtraction to the b quark PDF, like the tj process.
For tWb the options are:

   * =IMATCH= = 0, does not perform any matching.
   * =IMATCH= = 1, subtracts the resonant tt contribution at the differential cross section level.
   * =IMATCH= = 2, performs an invariant mass cut on the Wb invariant mass to remove the resonant tt contribution.
---++++++ Program output

The program log provides the top and antitop cross sections in the channel specified, their ratio, and some observables at the generator level:

   * The spin-independent asymmetries =A_{FB}=, =A_{±}= and W helicity fractions. The later are calculated from the former using analytical expressions (see in [[http://arxiv.org/abs/hep-ph/0605190][<strong>here</strong>]]), and for low statistics it may happen that the calculated =F_{R}= is negative.
   * The spin asymmetries =A_{l}=, =A_{nu}= and =A_{b}=.
   * Their ratios (which are independent of the top polarisation and only depend on Wtb anomalous couplings).
Definitions of these quantities are in Table 1 of [[http://jaguilar.web.cern.ch/jaguilar/protos/manual.ps][Protos manual]]. See <strong>[[http://arxiv.org/abs/0803.3810][here]] </strong>and *[[http://arxiv.org/abs/0811.3842][here]]*, for details.

The program also provides several distributions, each has a suffix number that distiguishes them in Table 2 of the [[http://jaguilar.web.cern.ch/jaguilar/protos/manual.ps][Protos manual]]. The format is raw text in two columns, ready to be plotted with [[http://www.gnuplot.info/][<strong>gnuplot</strong>]], for example.
---++ Ttbar Generator
---++++++ Decay Channel

The =ILEP= parameter chooses the decay channel:

   * =ILEP= = 1, 2, 3 selects the semileptonic channel with one W decaying to enu, munu or taunu, respectively, and the other W decaying hadronically.
   * =ILEP= = 4 includes the three semileptonic channels.
   * =ILEP= = 5, selects the full hadronic channel.
   * =ILEP= = 6, selects the dilepton channel.

---++++++ Vertex couplings

Similar to the Single Top Production, but since this process is about two nearly on-shell top quarks and a Wtb vertex is not involved in the production, the options in =tweak.dat= are different.

The first parameter switches on and off these features:

   * When off, the Wtb coupling is read from =run.dat=.
   * When on, the Wtb coupling is overrided.
The other two parameters set the helicity for both the W bosons decaying leptonically and hadronically, respectively. In the full hadronic and dilepton channel, these variables set the helicities of the W+ and W-, respectively.

=WARNING=: The values of the couplings depend on the top-quark mass (see previous section and documentation in [[http://arxiv.org/abs/hep-ph/0605190][<strong>here</strong>]]).

When running the program iteratively, the anomalous couplings can be varied in each run:

   * =ISCAN= = 1, 2, 3 varies VL, gL and gR, respectively, by a quantity =SCANSTEP=.
---++++++ Factorisation scale

The default factorisation scale is =Q = m(top)=, multiplied by =QFAC=. It only can be changed in the subroutine =MSQ= of =evtgen.f=.
---++++++ Program output

The program log provides the tt cross section in the channel specified, as well as som observables at generator level, and also generates several distributions of interest (see *[[http://jaguilar.web.cern.ch/jaguilar/protos/manual.ps][Protos manual]]* for further references).

<span style="font-size: 12px; line-height: 12px;"> </span>
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who
sh	export.sh	r2 r1	manage	0.2 K	2013-08-27 - 12:58	PatriciaFernandez
dat	run.dat	r1	manage	0.8 K	2013-08-27 - 12:20	PatriciaFernandez
dat	smpar.dat	r1	manage	0.6 K	2013-08-27 - 12:22	PatriciaFernandez
Topic revision: r7 - 2014-07-24 - PatriciaFernandez
Account
- Log In
- Cern Search
- TWiki Search
- Google Search
Sandbox All webs
Edit
Attach
Copyright &© 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback