<chapter name="HepMC Interface"> 
 
<h2>HepMC Interface</h2> 
 
An interface to both the legacy HepMC2 <ref>Dob01</ref> and current 
HepMC3 <ref>Buc19</ref> standard event record format has been provided 
by M. Kirsanov and the HepMC3 collaboration. The code is stored in 
<code>include/Pythia8Plugins/HepMC2.h</code> and 
<code>include/Pythia8Plugins/HepMC3.h</code>, respectively. To use it, 
the relevant libraries need to be linked, as explained in the 
<code>README</code> file.  Only version 2.06 (or later) of HepMC2 is 
supported, and all version of HepMC3 are supported, by agreement with 
the LHC experimental community. All examples use the HepMC3 interface, 
with the exceptions of <code>main144.cc</code> and optionally 
<code>main134.cc</code> which still utilise the HepMC2 interface and 
are provided as legacy examples. 
 
<p/> 
The (simple) procedure to translate PYTHIA 8 events into HepMC ones 
is illustrated in the <code>main131.cc</code>, <code>main132.cc</code> 
and <code>main133.cc</code> main programs. At the core is a call to the 
<pre> 
HepMC3::Pythia8ToHepMC3::fill_next_event( pythia, hepmcevt, ievnum = -1) 
</pre> 
which takes a reference of the generator object and uses it, on the one 
hand, to read out and convert the event record in <code>pythia.event</code> 
and, on the other hand, to extract and store parton-density (PDF), 
cross section and other information for the hard subprocess from 
<code>pythia.info</code>. There is also an alternative form that 
does not requires access to the full <code>pythia</code> object, 
but only the event record, at the expense of a reduced information 
storage, see below. 
 
<p/> 
While PYTHIA always stores momenta in units of GeV, with <ei>c = 1</ei>, the 
<code>HepMC3::GenEvent</code> event record class may be created with units of 
MeV or GeV and mm or cm, see e.g. the  <code>main131.cc</code> code. When 
filling the HepMC event record,  PYTHIA will switch the current HepMC event 
record units to GeV and mm. This can be switched back by the user with the 
<code>HepMC3::GeneEvent::set_units</code> method. Note, the default 
units in HepMC3 are GeV and mm. This differs from HepMC2 where the 
library is built with user specified default units. 
 
<p/> 
The status code is now based on the new standard introduced for HepMC 2.05, 
see the <aloc href="EventRecord">Event::statusHepMC(...)</aloc> 
conversion routine for details. 
 
<p/> 
The current values from <code>pythia.info.sigmaGen()</code> and 
<code>pythia.info.sigmaErr()</code> are stored for each event, 
multiplied by <ei>10^9</ei> 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, this weight is in units of pb. 
 
<h3>Direct output to HepMC via plugin</h3> 
 
A PYTHIA plugin is available, <code>HepMC3Hooks</code> defined in 
<code>Pythia8Plugins/HepMC3Hooks.h</code>, which allows for the easy 
writing of PYTHIA output to HepMC3 files. The plugin works with 
<code>PythiaParallel</code>, and HepMC3 output is written out to a 
different text file for each thread. 
 
For the plugin to be available, PYTHIA must be configured with the 
<code>--with-hepmc3</code> flag before being built. 
<pre> 
  ./configure --with-hepmc3 
</pre> 
If successful, the plugin library <code>lib/pythia8hepmc3.so</code> 
will be built. 
 
<p/>The example <code>main225</code> and corresponding command file 
<code>main225.cmnd</code> demonstrate how to use the plugin. The 
general usage is as follows. First, load the plugin. 
<pre> 
  Init:plugins = {libpythia8hepmc3.so::HepMC3Hooks} 
</pre> 
None of the options described below is available if the plugin is not 
successfully loaded. Once the plugin is loaded, a number of additional 
settings will be available. To begin, set the output HepMC3 file name. 
<pre> 
  HepMC3:fileName = NAME 
</pre> 
If directory structure is included in the HepMC3 file name, an attempt 
will be made to create that directory structure. If the 
<code>HepMC3Hooks</code> are run with more than one thread in 
<code>PythiaParallel</code>, the given file name will be appended by 
the thread number. Multiple threads writing into a single HepMC3 file 
is currently not supported. 
 
Additional options control what is written to the HepMC file, as well 
as warnings that are printed by HepMC. 
<pre> 
  ! Warn if there are inconsistencies. 
  HepMC:printInconsistency = true 
  ! Warn if there are final partons. 
  HepMC:freePartonWarnings = true 
  ! Flag to store the PDF information. 
  HepMC:storePDF = true 
  ! Flag to store the process information. 
  HepMC:storeProcess = true 
</pre> 
 
<h3>Direct output to HepMC</h3> 
 
Provided that PYTHIA is properly linked to HepMC, implementation of the 
most common user case (run PYTHIA with a runcard, output HepMC) exists. 
The example <code>main144.cc</code> implements this. 
The sample command file <code>main144.cmnd</code> provides a good starting 
point. The line: 
<pre> 
    Main:writeHepMC = on 
</pre> 
is the switch needed to write a HepMC file. 
The example is then run with: 
<pre> 
    ./main144 -c main144.cmnd 
</pre> 
and a HepMC file is then written. Note that this example currently 
uses the legacy HepMC2 library to maintain Rivet compatability. 
 
<p/> 
There are several other useful command line options to <code>main144</code>. 
They are all displayed by running <code>./main144 -h</code>. 
 
<h3>The HepMC3 public methods</h3> 
 
Here comes a complete list of all public methods of the 
<code>Pythia8ToHepMC3</code> class in the <code>HepMC3</code> 
(<i>not</i> <code>Pythia8</code>!) namespace. 
 
<method name="Pythia8ToHepMC3::Pythia8ToHepMC()"> 
</method> 
<methodmore name="virtual Pythia8ToHepMC3::~Pythia8ToHepMC3()"> 
the constructor and destructor take no arguments. 
</methodmore> 
 
<method name="bool Pythia8ToHepMC3::fill_next_event( Pythia8::Pythia& pythia, 
GenEvent* evt, int ievnum = -1)"> 
convert a <code>Pythia</code> event to a <code>HepMC</code> one. 
Will return true if succeeded. 
<argument name="pythia"> 
the input <code>Pythia</code> generator object, from which both the 
event and other information can be obtained. 
</argument> 
<argument name="evt"> 
the output <code>GenEvt</code> event, in its standard form. 
</argument> 
<argument name="iev"> 
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. 
</argument> 
</method> 
 
<method name="bool Pythia8ToHepMC3::fill_next_event( Pythia8::Event& pyev, 
GenEvent* evt, int ievnum = -1, Pythia8::Info* pyinfo = 0, 
Pythia8::Settings* pyset = 0)"> 
convert a <code>Pythia</code> event to a <code>HepMC</code> one. 
Will return true if succeeded. 
<argument name="pyev"> 
the input <code>Pythia</code> event that is to be converted to HepMC 
format. 
</argument> 
<argument name="evt"> 
the output <code>GenEvt</code> event, in its standard form. 
</argument> 
<argument name="iev"> 
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. 
</argument> 
<argument name="pyinfo"> 
pointer to the <code>Pythia Info</code> object, which is used to 
extract PFD values, and process and cross section information. 
Without such a pointer this information therefore cannot be stored, 
i.e. it is equivalent to the three <code>set_store</code> methods 
below being set false. 
</argument> 
<argument name="pyset"> 
pointer to the <code>Pythia Settings</code> object, which is used to 
decide whether hadronization is carried out, and therefore whether 
to warn about unhadronized partons. Without such a pointer the 
<code>set_free_parton_warnings</code> method below uniquely controls 
the behaviour. 
</argument> 
</method> 
 
<p/> 
The following paired methods can be used to set and get the status of 
some switches that 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. 
 
<method name="void Pythia8ToHepMC3::set_print_inconsistency(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC3::print_inconsistency()"> 
print a warning line, on <code>cerr</code>, when inconsistent mother 
and daughter information is encountered. 
</methodmore> 
 
<method name="void Pythia8ToHepMC3::set_free_parton_warnings(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC3::free_parton_warnings()"> 
check for when unhadronized gluons or quarks are encountered in the 
event record, and issue a warning when encountered. Does not apply 
when Pythia hadronization is switched off. Default is to do this 
check. If <code>set_crash_on_problem()</code> is true, then the 
program will abort. 
</methodmore> 
 
<method name="void Pythia8ToHepMC3::set_crash_on_problem(bool b = false)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC3::crash_on_problem()"> 
when set to true, <code>free_parton_warnings()</code> is true, and 
unhadronized gluons or quarks are encountered in the event record then 
the program will abort. 
</methodmore> 
 
<method name="void Pythia8ToHepMC3::set_convert_gluon_to_0(bool b = false)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC3::convert_gluon_to_0()"> 
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. 
</methodmore> 
 
<method name="void Pythia8ToHepMC3::set_store_pdf(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC3::store_pdf()"> 
for each event store information on the two incoming flavours, their 
x values and common factorization scale, and the values of the two 
parton distributions, <ei>xf(x,Q)</ei>. 
</methodmore> 
 
<method name="void Pythia8ToHepMC3::set_store_proc(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::store_proc()"> 
for each event store information on the Pythia process code, the 
renormalization scale, and <ei>alpha_em</ei> and <ei>alpha_s</ei> 
values used for the hard process. 
</methodmore> 
 
<method name="void Pythia8ToHepMC3::set_store_xsec(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC3::store_xsec()"> 
for each event store information on the Pythia cross section and its error, 
in pb, and the event weight. If events also come with a dimensional weight, 
like in some Les Houches strategies, this weight is in units of pb. 
</methodmore> 
 
<h3>The HepMC2 public methods</h3> 
 
These methods are very similar to the HepMC3 methods but now all 
public methods of the <code>Pythia8ToHepMC</code> class in the 
<code>HepMC</code> namespace are given. 
 
<method name="Pythia8ToHepMC::Pythia8ToHepMC()"> 
</method> 
<methodmore name="virtual Pythia8ToHepMC::~Pythia8ToHepMC()"> 
the constructor and destructor take no arguments. 
</methodmore> 
 
<method name="bool Pythia8ToHepMC::fill_next_event( Pythia8::Pythia& pythia, 
GenEvent* evt, int ievnum = -1, bool append = false, 
GenParticle* rootParticle = 0, int iBarcode = -1)"> 
convert a <code>Pythia</code> event to a <code>HepMC</code> one. 
Will return true if succeeded. 
<argument name="pythia"> 
the input <code>Pythia</code> generator object, from which both the 
event and other information can be obtained. 
</argument> 
<argument name="evt"> 
the output <code>GenEvt</code> event, in its standard form. 
</argument> 
<argument name="iev"> 
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. 
</argument> 
<argument name="append"> 
if <code>true</code> then the input event is appended to the current 
<code>HepMC</code> event record, rather than starting a new one. 
</argument> 
<argument name="rootParticle"> 
the root particle that defines the new production vertex for the 
particles to be added in the <code>append = true</code> option. 
</argument> 
<argument name="iBarcode"> 
used to set the bar code when <code>append = true</code>. 
If positive then start from <code>iBarcode</code> itself, if negative 
then start from the current size of the <code>HepMC</code> event record, 
and if 0 then set all bar codes to vanish. 
</argument> 
</method> 
 
<method name="bool Pythia8ToHepMC::fill_next_event( Pythia8::Event& pyev, 
GenEvent* evt, int ievnum = -1, Pythia8::Info* pyinfo = 0, 
Pythia8::Settings* pyset = 0, bool append = false, 
GenParticle* rootParticle = 0, int iBarcode = -1)"> 
convert a <code>Pythia</code> event to a <code>HepMC</code> one. 
Will return true if succeeded. 
<argument name="pyev"> 
the input <code>Pythia</code> event that is to be converted to HepMC 
format. 
</argument> 
<argument name="evt"> 
the output <code>GenEvt</code> event, in its standard form. 
</argument> 
<argument name="iev"> 
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. 
</argument> 
<argument name="pyinfo"> 
pointer to the <code>Pythia Info</code> object, which is used to 
extract PFD values, and process and cross section information. 
Without such a pointer this information therefore cannot be stored, 
i.e. it is equivalent to the three <code>set_store</code> methods 
below being set false. 
</argument> 
<argument name="pyset"> 
pointer to the <code>Pythia Settings</code> object, which is used to 
decide whether hadronization is carried out, and therefore whether 
to warn about unhadronized partons. Without such a pointer the 
<code>set_free_parton_warnings</code> method below uniquely controls 
the behaviour. 
</argument> 
<argument name="append"> 
if <code>true</code> then the input event is appended to the current 
<code>HepMC</code> event record, rather than starting a new one. 
</argument> 
<argument name="rootParticle"> 
the root particle that defines the new production vertex for the 
particles to be added in the <code>append = true</code> option. 
</argument> 
<argument name="iBarcode"> 
used to set the bar code when <code>append = true</code>. 
If positive then start from <code>iBarcode</code> itself, if negative 
then start from the current size of the <code>HepMC</code> event record, 
and if 0 then set all bar codes to vanish. 
</argument> 
</method> 
 
<p/> 
The following paired methods can be used to set and get the status of 
some switches that 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. 
 
<method name="void Pythia8ToHepMC::set_print_inconsistency(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::print_inconsistency()"> 
print a warning line, on <code>cerr</code>, when inconsistent mother 
and daughter information is encountered. 
</methodmore> 
 
<method name="void Pythia8ToHepMC::set_free_parton_exception(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::free_parton_exception()"> 
check and throw an exception when unhadronized gluons or quarks are 
encountered in the event record. Does not apply when Pythia hadronization 
is switched off. Default is to do this check. If an exception is thrown the 
<code>PartonEndVertexException</code> class will return a warning message. 
The calling code can choose action to take, also having access to the 
location (<code>index()</code>) and species (<code>pdg_id()</code>) of a 
bad parton. 
</methodmore> 
 
<method name="void Pythia8ToHepMC::set_convert_gluon_to_0(bool b = false)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::convert_gluon_to_0()"> 
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. 
</methodmore> 
 
<method name="void Pythia8ToHepMC::set_store_pdf(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::store_pdf()"> 
for each event store information on the two incoming flavours, their 
x values and common factorization scale, and the values of the two 
parton distributions, <ei>xf(x,Q)</ei>. 
</methodmore> 
 
<method name="void Pythia8ToHepMC::set_store_proc(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::store_proc()"> 
for each event store information on the Pythia process code, the 
renormalization scale, and <ei>alpha_em</ei> and <ei>alpha_s</ei> 
values used for the hard process. 
</methodmore> 
 
<method name="void Pythia8ToHepMC::set_store_xsec(bool b = true)"> 
</method> 
<methodmore name="bool Pythia8ToHepMC::store_xsec()"> 
for each event store information on the Pythia cross section and its error, 
in pb, and the event weight. If events also come with a dimensional weight, 
like in some Les Houches strategies, this weight is in units of pb. 
</methodmore> 
 
</chapter> 
 
<!-- Copyright (C) 2025 Torbjorn Sjostrand --> 
