[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8145 / htmldoc / HadronLevelStandalone.html

<html>
<head>
<title>Hadron-Level Standalone</title>
<link rel="stylesheet" type="text/css" href="pythia.css"/>
<link rel="shortcut icon" href="pythia32.gif"/>
</head>
<body>

<h2>Hadron-Level Standalone</h2>

The Les Houches Accord allows external process-level configurations
to be fed in, for subsequent parton-level and hadron-level generation
to be handled internally by PYTHIA. There is no correspondingly 
standardized interface if you have external events that have also 
been generated through the parton-level stage, so that only the 
hadron-level remains to be handled. A non-standard way to achieve this
exists, however, and can be useful both for real applications and
for various tests of the hadronization model on its own. 

<p/>
The key trick is to set the flag <code>ProcessLevel:all = off</code>.
When <code>pythia.next()</code> is called it then does not try to
generate a hard process, and therefore also cannot do anything on the
parton level. Instead only the <code>HadronLevel</code> methods are
called, to take the current content of the event record stored in
<code>pythia.event</code> as a starting point for any hadronization 
and decays that are allowed by the normal parameters of this step. 
Often the input would consist solely of partons grouped into colour 
singlets, but also (colour-singlet) particles are allowed.

<p/>
To set up all the parameters, a <code>pythia.init()</code> call has
to be used, without any arguments. In brief, the structure of the
main program therefore should be something like
<pre>
  Pythia pythia;                               // Declare generator.
  Event& event = pythia.event                  // Convenient shorthand.
  pythia.readString("ProcessLevel:all = off"); // The trick!
  pythia.init();                               // Initialization.
  for (int iEvent = 0; iEvent < nEvent; ++iEvent) {
    // Insert filling of event here!
    pythia.next();                             // Do the hadron level.
  }
</pre> 
Of course this should be supplemented by analysis of events, error checks,
and so on, as for a normal PYTHIA run. The unique aspect is how to fill
the <code>event</code> inside the loop, before <code>pythia.next()</code> 
is called.

<h3>Input configuration</h3>

To set up a new configuration the first step is to throw away the current
one, with <code>event.reset()</code>. This routine will also reserve
the zeroth entry in the even record to represent the event as a whole. 

<p/>
With the <code>event.append(...)</code> methods a new entry is added at the
bottom of the current record, i.e. the first time it is called entry 
number 1 is filled, and so on. The <code>append</code>  method basically
exists in four variants, either without or with history information,
and with four-momentum provided either as a <code>Vec4</code> four-vector 
or as four individual components:
<pre>
  append( id, status, col, acol, p, m)
  append( id, status, col, acol, px, py, pz, e, m)
  append( id, status, mother1, mother2, daughter1, daughter2, col, acol, p, m)
  append( id, status, mother1, mother2, daughter1, daughter2, col, acol, px, py, pz, e, m)
</pre> 
The methods return the index at which the entry has been stored,
but normally you would not use this feature. 

<p/>
You can find descriptions of the input variables 
<a href="ParticleProperties.html" target="page">here</a>. 
The PDG particle code <code>id</code> and the Les Houches Accord colour 
<code>col</code> and anticolour <code>acol</code> tags must be set
correctly. The four-momentum and mass have to be provided in units of GeV; 
if you omit the mass it defaults to 0. 

<p/>
Outgoing particles that should hadronize should be given status code 23.
Often this is the only status code you need. You could e.g. also fill in 
incoming partons with -21 and intermediate ones with -22, if you so wish.
Usually the choice of status codes is not crucial, so long as you recall 
that positive numbers correspond to particles that are still around, while
negative numbers denote ones that already hadronized or decayed. However,
so as not to run into contradictions with the internal PYTHIA checks
(when <code>Check:event = on</code>), or with external formats such as 
HepMC, we do recommend the above codes. When <code>pythia.next()</code> 
is called the positive-status particles that hadronize/decay get the sign 
of the status code flipped to negative but the absolute value is retained. 
The new particles are added with normal PYTHIA status codes.

<p/>
For normal hadronization/decays in <code>pythia.next()</code> the
history encoded in the mother and daughter indices is not used. 
Therefore the first two <code>append</code> methods, which set all these 
indices vanishing, should suffice. The subsequent hadronization/decays 
will still be properly documented.

<p/>
The exception is when you want to include junctions in your string 
topology, i.e. have three string pieces meet. Then you must insert in
your event record the (decayed) particle that is the reason for the
presence of a junction, e.g. a baryon beam remnant from which several
valence quarks have been kicked out, or a neutralino that underwent a
baryon-number-violating decay. This particle must have as daughters 
the three partons that together carry the baryon number. 
 
<p/>
The sample program in <code>main21.cc</code> illustrates how you can work
with this facility, both for simple parton configurations and for more
complicated ones with junctions.

<h3>Repeated hadronization or decay</h3>

An alternative approach is possible with the 
<code>pythia.forceHadronLevel()</code> routine. This method does
a call to the <code>HadronLevel</code> methods, irrespective of the
value of the <code>HadronLevel:all</code> flag. If you hadronize
externally generated events it is equivalent to a 
<code>pythia.next()</code> call with 
<code>ProcessLevel:all = off</code>. 

<p/>
The real application instead is for repeated hadronization of the same
PYTHIA process- and parton-level event. This may for some studies
help to save time, given that these two first step are more 
time-consuming than the hadronization one. 

<p/>
For repeated hadronization you should first generate an event as usual, 
but with <code>HadronLevel:all = off</code>. This event you can save
in a temporary copy, e.g. <code>Event savedEvent = pythia.event</code>.
Inside a loop you copy back with <code>pythia.event = savedEvent</code>, 
and call <code>pythia.forceHadronLevel()</code> to obtain a new 
hadronization history.

<p/>
A more limited form of repetition is if you want to decay a given kind 
of particle repeatedly, without having to generate the rest of the event 
anew. This could be the case e.g. in <i>B</i> physics applications. 
Then you can use the <code>pythia.moreDecays()</code> method, which 
decays all particles in the event record that have not been decayed 
but should have been done so. The 
<code>pythia.particleData.mayDecay( id, false/true)</code> method 
may be used to switch off/on the decays of a particle species 
<code>id</code>, so that it is not decayed in the 
<code>pythia.next()</code> call but only inside a loop over a number of
tries. 

<p/>
Between each loop the newly produced decay products must be 
removed and the decayed particle status restored to undecayed.
The former is simple, since the new products are appended to the
end of the event record: <code>event.saveSize()</code> saves the
initial size of the event record, and <code>event.restoreSize()</code>
can later be used repeatedly to restore this original size, which means
that the new particles at the end are thrown away. The latter is more
complicated, and requires the user to identify the positions of all
particles of the species and restore a positive status code with
<code>event[i].statusPos()</code>.

<p/>
The <code>main15.cc</code> program illustrates both these methods,
i.e. either repeated hadronization or repeated decay of PYTHIA
events.

</body>
</html>

<!-- Copyright (C) 2010 Torbjorn Sjostrand -->
Commit	Line	Data
9419eeef	1	<html>
	2	<head>
	3	<title>Hadron-Level Standalone</title>
	4	<link rel="stylesheet" type="text/css" href="pythia.css"/>
	5	<link rel="shortcut icon" href="pythia32.gif"/>
	6	</head>
	7	<body>
	8
	9	<h2>Hadron-Level Standalone</h2>
	10
	11	The Les Houches Accord allows external process-level configurations
	12	to be fed in, for subsequent parton-level and hadron-level generation
	13	to be handled internally by PYTHIA. There is no correspondingly
	14	standardized interface if you have external events that have also
	15	been generated through the parton-level stage, so that only the
	16	hadron-level remains to be handled. A non-standard way to achieve this
	17	exists, however, and can be useful both for real applications and
	18	for various tests of the hadronization model on its own.
	19
	20	<p/>
	21	The key trick is to set the flag <code>ProcessLevel:all = off</code>.
	22	When <code>pythia.next()</code> is called it then does not try to
	23	generate a hard process, and therefore also cannot do anything on the
	24	parton level. Instead only the <code>HadronLevel</code> methods are
	25	called, to take the current content of the event record stored in
	26	<code>pythia.event</code> as a starting point for any hadronization
	27	and decays that are allowed by the normal parameters of this step.
	28	Often the input would consist solely of partons grouped into colour
	29	singlets, but also (colour-singlet) particles are allowed.
	30
	31	<p/>
	32	To set up all the parameters, a <code>pythia.init()</code> call has
	33	to be used, without any arguments. In brief, the structure of the
	34	main program therefore should be something like
	35	<pre>
	36	Pythia pythia; // Declare generator.
	37	Event& event = pythia.event // Convenient shorthand.
	38	pythia.readString("ProcessLevel:all = off"); // The trick!
	39	pythia.init(); // Initialization.
	40	for (int iEvent = 0; iEvent < nEvent; ++iEvent) {
	41	// Insert filling of event here!
	42	pythia.next(); // Do the hadron level.
	43	}
	44	</pre>
	45	Of course this should be supplemented by analysis of events, error checks,
	46	and so on, as for a normal PYTHIA run. The unique aspect is how to fill
	47	the <code>event</code> inside the loop, before <code>pythia.next()</code>
	48	is called.
	49
	50	<h3>Input configuration</h3>
	51
	52	To set up a new configuration the first step is to throw away the current
	53	one, with <code>event.reset()</code>. This routine will also reserve
	54	the zeroth entry in the even record to represent the event as a whole.
	55
	56	<p/>
	57	With the <code>event.append(...)</code> methods a new entry is added at the
	58	bottom of the current record, i.e. the first time it is called entry
	59	number 1 is filled, and so on. The <code>append</code> method basically
	60	exists in four variants, either without or with history information,
	61	and with four-momentum provided either as a <code>Vec4</code> four-vector
	62	or as four individual components:
	63	<pre>
	64	append( id, status, col, acol, p, m)
65	append( id, status, col, acol, px, py, pz, e, m)
66	append( id, status, mother1, mother2, daughter1, daughter2, col, acol, p, m)
67	append( id, status, mother1, mother2, daughter1, daughter2, col, acol, px, py, pz, e, m)
68	</pre>
69	The methods return the index at which the entry has been stored,
70	but normally you would not use this feature.
71
72	<p/>
73	You can find descriptions of the input variables
74	<a href="ParticleProperties.html" target="page">here</a>.
75	The PDG particle code <code>id</code> and the Les Houches Accord colour
76	<code>col</code> and anticolour <code>acol</code> tags must be set
77	correctly. The four-momentum and mass have to be provided in units of GeV;
78	if you omit the mass it defaults to 0.
79
80	<p/>
81	Outgoing particles that should hadronize should be given status code 23.
82	Often this is the only status code you need. You could e.g. also fill in
83	incoming partons with -21 and intermediate ones with -22, if you so wish.
84	Usually the choice of status codes is not crucial, so long as you recall
85	that positive numbers correspond to particles that are still around, while
86	negative numbers denote ones that already hadronized or decayed. However,
87	so as not to run into contradictions with the internal PYTHIA checks
88	(when <code>Check:event = on</code>), or with external formats such as
89	HepMC, we do recommend the above codes. When <code>pythia.next()</code>
90	is called the positive-status particles that hadronize/decay get the sign
91	of the status code flipped to negative but the absolute value is retained.
92	The new particles are added with normal PYTHIA status codes.
93
94	<p/>
95	For normal hadronization/decays in <code>pythia.next()</code> the
96	history encoded in the mother and daughter indices is not used.
97	Therefore the first two <code>append</code> methods, which set all these
98	indices vanishing, should suffice. The subsequent hadronization/decays
99	will still be properly documented.
100
101	<p/>
102	The exception is when you want to include junctions in your string
103	topology, i.e. have three string pieces meet. Then you must insert in
104	your event record the (decayed) particle that is the reason for the
105	presence of a junction, e.g. a baryon beam remnant from which several
106	valence quarks have been kicked out, or a neutralino that underwent a
107	baryon-number-violating decay. This particle must have as daughters
108	the three partons that together carry the baryon number.
109
110	<p/>
111	The sample program in <code>main21.cc</code> illustrates how you can work
112	with this facility, both for simple parton configurations and for more
113	complicated ones with junctions.
114
115	<h3>Repeated hadronization or decay</h3>
116
117	An alternative approach is possible with the
118	<code>pythia.forceHadronLevel()</code> routine. This method does
119	a call to the <code>HadronLevel</code> methods, irrespective of the
120	value of the <code>HadronLevel:all</code> flag. If you hadronize
121	externally generated events it is equivalent to a
122	<code>pythia.next()</code> call with
123	<code>ProcessLevel:all = off</code>.
124
125	<p/>
126	The real application instead is for repeated hadronization of the same
127	PYTHIA process- and parton-level event. This may for some studies
128	help to save time, given that these two first step are more
129	time-consuming than the hadronization one.
130
131	<p/>
132	For repeated hadronization you should first generate an event as usual,
133	but with <code>HadronLevel:all = off</code>. This event you can save
134	in a temporary copy, e.g. <code>Event savedEvent = pythia.event</code>.
135	Inside a loop you copy back with <code>pythia.event = savedEvent</code>,
136	and call <code>pythia.forceHadronLevel()</code> to obtain a new
137	hadronization history.
138
139	<p/>
140	A more limited form of repetition is if you want to decay a given kind
141	of particle repeatedly, without having to generate the rest of the event
142	anew. This could be the case e.g. in <i>B</i> physics applications.
143	Then you can use the <code>pythia.moreDecays()</code> method, which
144	decays all particles in the event record that have not been decayed
145	but should have been done so. The
146	<code>pythia.particleData.mayDecay( id, false/true)</code> method
147	may be used to switch off/on the decays of a particle species
148	<code>id</code>, so that it is not decayed in the
149	<code>pythia.next()</code> call but only inside a loop over a number of
150	tries.
151
152	<p/>
153	Between each loop the newly produced decay products must be
154	removed and the decayed particle status restored to undecayed.
155	The former is simple, since the new products are appended to the
156	end of the event record: <code>event.saveSize()</code> saves the
157	initial size of the event record, and <code>event.restoreSize()</code>
158	can later be used repeatedly to restore this original size, which means
159	that the new particles at the end are thrown away. The latter is more
160	complicated, and requires the user to identify the positions of all
161	particles of the species and restore a positive status code with
162	<code>event[i].statusPos()</code>.
163
164	<p/>
165	The <code>main15.cc</code> program illustrates both these methods,
166	i.e. either repeated hadronization or repeated decay of PYTHIA
167	events.
168
169	</body>
170	</html>
171
172	<!-- Copyright (C) 2010 Torbjorn Sjostrand -->