[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / htmldoc / HepMCInterface.html

<html>
<head>
<title>HepMC Interface</title>
<link rel="stylesheet" type="text/css" href="pythia.css"/>
<link rel="shortcut icon" href="pythia32.gif"/>
</head>
<body>

<h2>HepMC Interface</h2>

An interface to the HepMC [<a href="Bibliography.html" target="page">Dob01</a>] standard event record 
format has been provided by M. Kirsanov. To use it, the relevant 
libraries need to be linked, as explained in the <code>README</code> 
file. Only version 2 of HepMC is supported. (Version 1 requires 
a different interface structure, which was only supported up until 
Pythia 8.107.) 

<p/>
The (simple) procedure to translate PYTHIA 8 events into HepMC ones 
is illustrated in the <code>main41.cc</code>, <code>main42.cc</code>
<code>main61.cc</code> and <code>main62.cc</code>   
main programs. At the core is a call to the
<pre>
HepMC::I_Pythia8::fill_next_event( pythia, hepmcevt, ievnum = -1, convertGluonTo0 = false ) 
</pre>
which takes a reference of the generator object and uses it, on the one
hand, to read out and covert the event record in <code>pythia.event</code> 
and, on the other hand, to extract and store parton-density (PDF) 
information for the hard subprocess from <code>pythia.info</code>. 
The optional last argument, if <code>true</code>, allows you to store 
gluons as "PDG" code 0 rather than the normal 21; this only applies to 
the PDF information, not the event record. 

<p/>
The earlier version of this routine,
<pre>
HepMC::I_Pythia8::fill_next_event( pythia.event, hepmcevt, ievnum = -1 ) 
</pre>
is retained (for now) for backwards compatibility. It takes a PYTHIA event 
as input and returns a HepMC one, but without storing the PDF information. 
The latter could then instead be stored by a separate call
<pre>
HepMC::I_Pythia8::pdf_put_info( hepmcevt, pythia, convertGluonTo0 = false ) 
</pre>
or not, as wished.

<p/>
While PYTHIA stores momenta in units of GeV, with <i>c = 1</i>, 
the HepMC standard originally did not specify which units to use, 
unfortunately. Later versions allow units to be specified either as
MeV or as GeV. The dividing line goes with the introduction of the
<code>HEPMC_HAS_UNITS</code> environment variable in HepMC 2.04.
When PYTHIA is linked to older versions, which do not have this
environment variable, the default behaviour of 
<code>fill_next_event</code> is to convert momenta to MeV. 
To store momenta in GeV instead, you must call 
<pre>
HepMC::I_Pythia8::set_convert_to_mev( false ) 
</pre>
beforehand. When linked to newer HepMC versions, PYTHIA will adapt
to the unit specified for the HepMC event record. A default unit
is chosen when HepMC is built, but this choice can be overridden
in the constructor of a <code>HepMC::GenEvent</code>, to be either
GeV or MeV. The <code>main41.cc</code> code illustrates these 
possibilities. 

<p/>
Also for length units there could exist ambiguities, but the mm
choice of PYTHIA seems to be shared by most other programs. 
When linked to older HepMC versions there is never a conversion, 
while for newer versions the PYTHIA interface will convert to the 
units set for the HepMC event record, as for momenta.

<p/>
By agreement with the LHC experimental community, support for the
older behaviour will be dropped for all versions released after 
the end of 2012.

<p/>
The status code is now based on the new standard for HepMC 2.05,
see the <a href="EventRecord.html" target="page">Event::statusHepMC(...)</a> 
conversion routine for details. The earlier behaviour, where all
final particles had status 1 and all initial or intermediate ones 
status 2, is available as a commented-out line in the   
<code>I_Pythia8::fill_next_event(...)</code> method, and so is simple
to recover.

<p/>
In HepMC 2.05 it also becomes possible to store the generated cross 
section and its error. The environment variable
<code>HEPMC_HAS_CROSS_SECTION</code> is used to check whether this
possibility exists and, if it does the current values from 
<code>pythia.info.sigmaGen()</code> and 
<code>pythia.info.sigmaErr()</code> are stored for each event,
multiplied by <i>10^9</i> to convert from mb to pb. Note that
PYTHIA improves its accuracy by Monte Carlo integration in the course
of the run, so the values associated with the last generated event
should be the most accurate ones. (If events also come with a dimensional 
weight, like in some Les Houches strategies, conversion from mb to fb 
for that weight must be set by hand, see the last method below.)

<h2>The public methods</h2>

Here comes a complete list of all public methods of the 
<code>I_Pythia8</code> class in the <code>HepMC</code> 
(<i>not</i> <code>Pythia8</code>!) namespace.

<a name="method1"></a>
<p/><strong>I_Pythia8::I_Pythia8() &nbsp;</strong> <br/>
  
<strong>virtual I_Pythia8::~I_Pythia8() &nbsp;</strong> <br/>
the constructor and destructor take no arguments.
  

<a name="method2"></a>
<p/><strong>bool I_Pythia8::fill_next_event( Pythia8::Pythia& pythia, GenEvent* evt, int ievnum = -1, bool convertGluonTo0 = false) &nbsp;</strong> <br/>
convert a <code>Pythia</code> event to a <code>HepMC</code> one.
Will return true if succeeded.
<br/><code>argument</code><strong> pythia </strong>  : 
the input <code>Pythia</code> generator object, from which both the 
event and the parton density information can be obtained.
   
<br/><code>argument</code><strong> evt </strong>  : 
the output <code>GenEvt</code> event, in its standard form.
   
<br/><code>argument</code><strong> iev </strong>  : 
set the event number of the current event. If negative then the 
internal event number is used, which is incremented by one for
each new event.
  
<br/><code>argument</code><strong> convertGluonTo0 </strong>  : 
the normal gluon identity code 21 is used also when parton density
information is stored, unless this optional argument is set true to
have gluons represented by a 0. This choice does not affect the 
normal event record, where a gluon is always 21. 
  
  

<a name="method3"></a>
<p/><strong>bool I_Pythia8::fill_next_event( Pythia8::Event& pyev, GenEvent* evt, int ievnum = -1 ) &nbsp;</strong> <br/>
convert a <code>Pythia</code> event to a <code>HepMC</code> one.
Will return true if succeeded. Do not store parton-density information.
<br/><code>argument</code><strong> pyev </strong>  : 
the input <code>Pythia</code> event, in its standard form.
   
<br/><code>argument</code><strong> evt </strong>  : 
the output <code>GenEvt</code> event, in its standard form.
   
<br/><code>argument</code><strong> iev </strong>  : 
set the event number of the current event. If negative then the 
internal event number is used, which is incremented by one for
each new event.
  
  

<a name="method4"></a>
<p/><strong>bool I_Pythia8::put_pdf_info( GenEvent* evt, Pythia8::Pythia& pythia, bool convertGluonTo0 = false ) &nbsp;</strong> <br/>
append parton-density information to an event already stored
by the previous method.
<br/><code>argument</code><strong> evt </strong>  : 
the output <code>GenEvt</code> event record, in its standard form.
   
<br/><code>argument</code><strong> pythia </strong>  : 
the input <code>Pythia</code> generator object, from which both the 
event and the parton density information can be obtained.
   
<br/><code>argument</code><strong> convertGluonTo0 </strong>  : 
the normal gluon identity code 21 is used also when parton density
information is stored, unless this optional argument is set true to
have gluons represented by a 0. 
  
  

<p/>
The following methods can be used to set, and in some cases interrogate,
the status of some switches that can be used to modify the behaviour
of the conversion routine. The <code>set</code> methods have the 
same default input values as the internal initialization ones, so
that a call without an argument (re)stores the default.

<a name="method5"></a>
<p/><strong>void I_Pythia8::set_trust_mothers_before_daughters( bool b = true ) &nbsp;</strong> <br/>
  
<strong>bool I_Pythia8::trust_mothers_before_daughters() &nbsp;</strong> <br/>
if there is a conflict in the history information, then trust the 
information on mothers above that on daughters. Currently this is
the only option implemented. 
  

<a name="method6"></a>
<p/><strong>void I_Pythia8::set_trust_both_mothers_and_daughters( bool b = false ) &nbsp;</strong> <br/>
  
<strong>bool I_Pythia8::trust_both_mothers_and_daughters() &nbsp;</strong> <br/>
currently dummy methods intended to resolve conflicts in the event
history.
  

<a name="method7"></a>
<p/><strong>void I_Pythia8::set_print_inconsistency_errors( bool b = true ) &nbsp;</strong> <br/>
  
<strong>bool I_Pythia8::print_inconsistency_errors() &nbsp;</strong> <br/>
print a warning line, on <code>cerr</code>, when inconsistent mother 
and daughter information is encountered.
  

<a name="method8"></a>
<p/><strong>void I_Pythia8::set_crash_on_problem( bool b = false ) &nbsp;</strong> <br/>
if problems are encountered then the run is interrupted by an
<code>exit(1)</code> command. Default is not to crash.
  

<a name="method9"></a>
<p/><strong>void I_Pythia8::set_freepartonwarnings( bool b = true ) &nbsp;</strong> <br/>
interrupt the run by an <code>exit(1)</code> command if unhadronized 
gluons or quarks are encountered in the event record, unless 
hadronization is switched off. Default is to crash.
  

<a name="method10"></a>
<p/><strong>void I_Pythia8::set_convert_to_mev( bool b = false ) &nbsp;</strong> <br/>
convert the normal GeV energies, momenta and masses to MeV.
  

</body>
</html>

<!-- Copyright (C) 2012 Torbjorn Sjostrand -->
Commit	Line	Data
63ba5337	1	<html>
	2	<head>
	3	<title>HepMC Interface</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>HepMC Interface</h2>
	10
	11	An interface to the HepMC [<a href="Bibliography.html" target="page">Dob01</a>] standard event record
	12	format has been provided by M. Kirsanov. To use it, the relevant
	13	libraries need to be linked, as explained in the <code>README</code>
	14	file. Only version 2 of HepMC is supported. (Version 1 requires
	15	a different interface structure, which was only supported up until
	16	Pythia 8.107.)
	17
	18	<p/>
	19	The (simple) procedure to translate PYTHIA 8 events into HepMC ones
	20	is illustrated in the <code>main41.cc</code>, <code>main42.cc</code>
	21	<code>main61.cc</code> and <code>main62.cc</code>
	22	main programs. At the core is a call to the
	23	<pre>
	24	HepMC::I_Pythia8::fill_next_event( pythia, hepmcevt, ievnum = -1, convertGluonTo0 = false )
	25	</pre>
	26	which takes a reference of the generator object and uses it, on the one
	27	hand, to read out and covert the event record in <code>pythia.event</code>
	28	and, on the other hand, to extract and store parton-density (PDF)
	29	information for the hard subprocess from <code>pythia.info</code>.
	30	The optional last argument, if <code>true</code>, allows you to store
	31	gluons as "PDG" code 0 rather than the normal 21; this only applies to
	32	the PDF information, not the event record.
	33
	34	<p/>
	35	The earlier version of this routine,
	36	<pre>
	37	HepMC::I_Pythia8::fill_next_event( pythia.event, hepmcevt, ievnum = -1 )
	38	</pre>
	39	is retained (for now) for backwards compatibility. It takes a PYTHIA event
	40	as input and returns a HepMC one, but without storing the PDF information.
	41	The latter could then instead be stored by a separate call
	42	<pre>
	43	HepMC::I_Pythia8::pdf_put_info( hepmcevt, pythia, convertGluonTo0 = false )
	44	</pre>
	45	or not, as wished.
	46
	47	<p/>
	48	While PYTHIA stores momenta in units of GeV, with <i>c = 1</i>,
	49	the HepMC standard originally did not specify which units to use,
	50	unfortunately. Later versions allow units to be specified either as
	51	MeV or as GeV. The dividing line goes with the introduction of the
	52	<code>HEPMC_HAS_UNITS</code> environment variable in HepMC 2.04.
	53	When PYTHIA is linked to older versions, which do not have this
	54	environment variable, the default behaviour of
	55	<code>fill_next_event</code> is to convert momenta to MeV.
	56	To store momenta in GeV instead, you must call
	57	<pre>
	58	HepMC::I_Pythia8::set_convert_to_mev( false )
	59	</pre>
	60	beforehand. When linked to newer HepMC versions, PYTHIA will adapt
	61	to the unit specified for the HepMC event record. A default unit
	62	is chosen when HepMC is built, but this choice can be overridden
	63	in the constructor of a <code>HepMC::GenEvent</code>, to be either
	64	GeV or MeV. The <code>main41.cc</code> code illustrates these
65	possibilities.
66
67	<p/>
68	Also for length units there could exist ambiguities, but the mm
69	choice of PYTHIA seems to be shared by most other programs.
70	When linked to older HepMC versions there is never a conversion,
71	while for newer versions the PYTHIA interface will convert to the
72	units set for the HepMC event record, as for momenta.
73
74	<p/>
75	By agreement with the LHC experimental community, support for the
76	older behaviour will be dropped for all versions released after
77	the end of 2012.
78
79	<p/>
80	The status code is now based on the new standard for HepMC 2.05,
81	see the <a href="EventRecord.html" target="page">Event::statusHepMC(...)</a>
82	conversion routine for details. The earlier behaviour, where all
83	final particles had status 1 and all initial or intermediate ones
84	status 2, is available as a commented-out line in the
85	<code>I_Pythia8::fill_next_event(...)</code> method, and so is simple
86	to recover.
87
88	<p/>
89	In HepMC 2.05 it also becomes possible to store the generated cross
90	section and its error. The environment variable
91	<code>HEPMC_HAS_CROSS_SECTION</code> is used to check whether this
92	possibility exists and, if it does the current values from
93	<code>pythia.info.sigmaGen()</code> and
94	<code>pythia.info.sigmaErr()</code> are stored for each event,
95	multiplied by <i>10^9</i> to convert from mb to pb. Note that
96	PYTHIA improves its accuracy by Monte Carlo integration in the course
97	of the run, so the values associated with the last generated event
98	should be the most accurate ones. (If events also come with a dimensional
99	weight, like in some Les Houches strategies, conversion from mb to fb
100	for that weight must be set by hand, see the last method below.)
101
102	<h2>The public methods</h2>
103
104	Here comes a complete list of all public methods of the
105	<code>I_Pythia8</code> class in the <code>HepMC</code>
106	(<i>not</i> <code>Pythia8</code>!) namespace.
107
108	<a name="method1"></a>
109	<p/><strong>I_Pythia8::I_Pythia8()  </strong> <br/>
110
111	<strong>virtual I_Pythia8::~I_Pythia8()  </strong> <br/>
112	the constructor and destructor take no arguments.
113
114
115	<a name="method2"></a>
116	<p/><strong>bool I_Pythia8::fill_next_event( Pythia8::Pythia& pythia, GenEvent* evt, int ievnum = -1, bool convertGluonTo0 = false)  </strong> <br/>
117	convert a <code>Pythia</code> event to a <code>HepMC</code> one.
118	Will return true if succeeded.
119	<br/><code>argument</code><strong> pythia </strong> :
120	the input <code>Pythia</code> generator object, from which both the
121	event and the parton density information can be obtained.
122
123	<br/><code>argument</code><strong> evt </strong> :
124	the output <code>GenEvt</code> event, in its standard form.
125
126	<br/><code>argument</code><strong> iev </strong> :
127	set the event number of the current event. If negative then the
128	internal event number is used, which is incremented by one for
129	each new event.
130
131	<br/><code>argument</code><strong> convertGluonTo0 </strong> :
132	the normal gluon identity code 21 is used also when parton density
133	information is stored, unless this optional argument is set true to
134	have gluons represented by a 0. This choice does not affect the
135	normal event record, where a gluon is always 21.
136
137
138
139	<a name="method3"></a>
140	<p/><strong>bool I_Pythia8::fill_next_event( Pythia8::Event& pyev, GenEvent* evt, int ievnum = -1 )  </strong> <br/>
141	convert a <code>Pythia</code> event to a <code>HepMC</code> one.
142	Will return true if succeeded. Do not store parton-density information.
143	<br/><code>argument</code><strong> pyev </strong> :
144	the input <code>Pythia</code> event, in its standard form.
145
146	<br/><code>argument</code><strong> evt </strong> :
147	the output <code>GenEvt</code> event, in its standard form.
148
149	<br/><code>argument</code><strong> iev </strong> :
150	set the event number of the current event. If negative then the
151	internal event number is used, which is incremented by one for
152	each new event.
153
154
155
156	<a name="method4"></a>
157	<p/><strong>bool I_Pythia8::put_pdf_info( GenEvent* evt, Pythia8::Pythia& pythia, bool convertGluonTo0 = false )  </strong> <br/>
158	append parton-density information to an event already stored
159	by the previous method.
160	<br/><code>argument</code><strong> evt </strong> :
161	the output <code>GenEvt</code> event record, in its standard form.
162
163	<br/><code>argument</code><strong> pythia </strong> :
164	the input <code>Pythia</code> generator object, from which both the
165	event and the parton density information can be obtained.
166
167	<br/><code>argument</code><strong> convertGluonTo0 </strong> :
168	the normal gluon identity code 21 is used also when parton density
169	information is stored, unless this optional argument is set true to
170	have gluons represented by a 0.
171
172
173
174	<p/>
175	The following methods can be used to set, and in some cases interrogate,
176	the status of some switches that can be used to modify the behaviour
177	of the conversion routine. The <code>set</code> methods have the
178	same default input values as the internal initialization ones, so
179	that a call without an argument (re)stores the default.
180
181	<a name="method5"></a>
182	<p/><strong>void I_Pythia8::set_trust_mothers_before_daughters( bool b = true )  </strong> <br/>
183
184	<strong>bool I_Pythia8::trust_mothers_before_daughters()  </strong> <br/>
185	if there is a conflict in the history information, then trust the
186	information on mothers above that on daughters. Currently this is
187	the only option implemented.
188
189
190	<a name="method6"></a>
191	<p/><strong>void I_Pythia8::set_trust_both_mothers_and_daughters( bool b = false )  </strong> <br/>
192
193	<strong>bool I_Pythia8::trust_both_mothers_and_daughters()  </strong> <br/>
194	currently dummy methods intended to resolve conflicts in the event
195	history.
196
197
198	<a name="method7"></a>
199	<p/><strong>void I_Pythia8::set_print_inconsistency_errors( bool b = true )  </strong> <br/>
200
201	<strong>bool I_Pythia8::print_inconsistency_errors()  </strong> <br/>
202	print a warning line, on <code>cerr</code>, when inconsistent mother
203	and daughter information is encountered.
204
205
206	<a name="method8"></a>
207	<p/><strong>void I_Pythia8::set_crash_on_problem( bool b = false )  </strong> <br/>
208	if problems are encountered then the run is interrupted by an
209	<code>exit(1)</code> command. Default is not to crash.
210
211
212	<a name="method9"></a>
213	<p/><strong>void I_Pythia8::set_freepartonwarnings( bool b = true )  </strong> <br/>
214	interrupt the run by an <code>exit(1)</code> command if unhadronized
215	gluons or quarks are encountered in the event record, unless
216	hadronization is switched off. Default is to crash.
217
218
219	<a name="method10"></a>
220	<p/><strong>void I_Pythia8::set_convert_to_mev( bool b = false )  </strong> <br/>
221	convert the normal GeV energies, momenta and masses to MeV.
222
223
224	</body>
225	</html>
226
227	<!-- Copyright (C) 2012 Torbjorn Sjostrand -->