<chapter name="Python Interface"> 
 
<h2>Python Interface</h2> 
 
<a href="https://www.python.org/" target="_top">Python</a> is a 
powerful, high-level interpreted language that is widely used within 
the particle physics community. It is particularly useful as an 
interactive language that provides fast proto-typing of code. A Python 
interface to PYTHIA is available. This interface is automatically 
generated with <a href="https://github.com/RosettaCommons/binder" 
target="_top">Binder</a> using the <a 
href="https://github.com/pybind/pybind11" target="_top">PyBind11</a> 
template library. Please note that this interface has not been 
extensively tested and consequently issues may arise. If bugs are 
found or additional features are required, as usual, please report 
them to the PYTHIA authors. This interface is a significant departure 
from the previous interface generated with SWIG, which does not 
support C++11. 
 
<p/> 
A complete interface ships with PYTHIA. However, in some cases this 
interface might be more than needed by users and so a simplified 
lightweight interface can also be generated.  Note, not all PYTHIA 
classes are available through this simplified interface. It is also 
possible for users to automatically generate their own interface. This 
is particularly useful if users modify the PYTHIA source code and need 
to update the interface. When generating the interface there are three 
options: the simplified interface, a full interface, and a user 
defined interface. The process of generating these interfaces is 
described in more detail below. 
 
<p/> 
There are some idiosyncrasies when working with standard template 
library classes. One of the notable examples are maps with keys as 
strings. In many cases, it is useful to be able to access the settings 
maps from the <code>Settings</code> class of a <code>Pythia</code> 
instance. Rather than calling something like 
<code>getFlagMap()</code>, <code>getFlagMap("")</code> must be called 
so the interface knows how to map the keys. A full working example is 
given below. 
<pre> 
import pythia8 
pythia = pythia8.Pythia("", False) 
settings = pythia.settings 
flags = settings.getFlagMap("") 
for key, val in settings.getFlagMap("").items(): print(key) 
</pre> 
 
<p/> 
The following points highlight some of the features of the interface. 
<ul> 
<li>Documentation through the built-in help function in Python 
provides the relevant mappings between the Python interface and the 
C++ code. For documentation on the purpose of the code, see the user 
HTML manual and Doxygen.</li> 
<li>Templated C++ types are returned as native Python types, 
e.g. vectors are returned as lists, etc. Similarly, native Python 
types can be passed as arguments and are converted to their equivalent 
C++ templates.</li> 
<li>No difference is made between passing by reference or pointer; 
methods in C++ which take a pointer as an argument in Python 
simply take the object, e.g. <code>foo(Vec4*)</code> and 
<code>foo(Vec4&amp;)</code> are the same in the Python interface.</li> 
<li>All operators defined in C++, e.g. <code>Vec4*double</code> are 
available. Note that reverse operators are not, 
e.g. <code>double*Vec4</code>.</li> 
<li>Classes with defined <code>[]</code> operators are iterable, using 
standard Python iteration, e.g. <code>for prt in 
pythia.event</code>.</li> 
<li>Classes with a <code>&lt;&lt;</code> operator can be printed via 
the built-in print function in Python. Note this means that a string 
representation via <code>str</code> is also available for these 
classes in Python.</li> 
<li>Derived classes in Python can be passed back to PYTHIA, and should 
be available for all classes. See <code>main293.py</code> for a direct 
Python translation of the C++ <code>main242.cc</code> example which 
uses a derived class from the <code>UserHooks</code> class to veto 
events.</li> 
<li>Events can be generated in parallel using 
<code>PythiaParallel</code> and providing an analysis function written 
in Python. This is demonstrated in <code>main292.py</code>.</li> 
<li>Events can be generated in batch using Awkward arrays, see below 
for more details as well as <code>main247.py</code> and 
<code>main248.py</code>.</li> 
<li>The constant <code>Pythia::info</code> member is available as 
<code>Pythia::infoPython</code>. Note, this creates a new instance of 
the <code>Info</code> class, and so needs to be called each time the 
information might be updated.</li> 
</ul> 
 
<p/> 
In general, most code using PYTHIA implemented through C++ is also 
possible in the Python interface. There are a number of issues, such 
as passing streams, which cannot be handled in the Python 
interface. Additionally, protected members of classes are exposed as 
fully public members in the Python interface. 
 
<h3>Batch Generation</h3> 
 
Individually generating events and then accessing each particle by the Python 
interface can slow things down considerably with respect to running directly 
in C++. This is because the Python interface must translate the C++ PYTHIA 
event record into Python as each particle is accessed by the user. Similarly, 
using <code>PythiaParallel</code> where a Python function is passed back to 
the Pythia C++ code to perform an analysis can result in a slow down. Another 
option is to batch translate events to Python using the 
<a href="https://awkward-array.org" target="_top">Awkward array 
library</a>. In this way, the event translation is all done in a 
single C++ call for a group of events, rather than on a per particle 
basis. An example on how to generate events with the Awkward interface 
are given in <code>main297.py</code>. 
 
<p/> 
For this batch interface to work, your Python version must be greater 
than <code>3.5</code> and the Awkward module must be available in 
Python. This can be installed via pip or the Python package manager of 
your choice. 
<pre> 
python -m pip install awkward 
</pre> 
It should then be possible to use the <code>nextBatch</code> method of 
the <code>Pythia</code> class which is called with two arguments 
<code>nextBatch(nEvents, errorMode)</code>, where the second argument is 
optional. In the following code, 100 events are generated and returned via the 
Awkward array named <code>events</code>. 
<pre> 
pythia = pythia.Pythia() 
pythia.readString("HardProcess:all = on") 
pythia.init() 
events = pythia.nextBatch(100) 
</pre> 
 
<p/> 
For a single Pythia instance, failed events can be treated in 
different ways using the optional <code>errorMode</code> argument that 
can be passed to <code>nextBatch</code>. 
<ul> 
<li><code>"none"</code> - events that fail to generate are included 
in the Awkward array as <code>None</code> objects.</li> 
<li><code>"skip"</code> - this is the default behavior, and is similar 
to what <code>PythiaParallel</code> also does. Events that fail to 
generate are skipped, and events are generated until the requested 
<code>nEvents</code> is reached.</li> 
<li><code>"fail"</code> - if an event fails to generate, then an 
exception is thrown.</li> 
<li><code>fac</code> - here, <code>fac</code> is a real number greater 
than <code>1</code>. This is the same as <code>"skip"</code> but event 
generation will terminate after <code>fac*nEvents</code> attempts have 
been made to generate an event and an exception will be thrown.</li> 
</ul> 
Some examples are given in <code>main298.py</code>. 
 
<p/> 
There are two other features for batch generation. First, 
<code>nextBatch</code> can also be called from a 
<code>PythiaParallel</code> instance, but without the optional 
<code>errorMode</code> as <code>PythiaParallel</code> handles failed 
events internally. Second, the momentum and production vertex 
four-vectors can automatically be translated into a four-vector class 
using the 
<a href="https://vector.readthedocs.io/en/latest/index.html" target="_top"> 
scikit-hep/vector library</a>. 
<pre> 
python -m pip install vector 
</pre> 
Translating automatically to this library can then be accomplished 
with the following code. 
<pre> 
import vector 
vector.register_awkward() 
</pre> 
This allows for analyses to be performed on the event record with 
slicing. Some examples can be found in the <a 
href="https://awkward-array.org/doc/main/getting-started/jagged-ragged-awkward-arrays.html" target="_top"> 
Awkward array documentation</a>, as well as in <code>main297.py</code>. 
 
Some older C++ compiler versions are not compatible with the C++11 
templating that is required for the Awkward array bindings. However, 
it is possible to generate the Python interface without the Awkward 
array bindings by passing the <code>--no-batch</code> flag to the 
<code>generate</code> script. See below for more details on how to 
generate the Python interface. 
 
<h3>Simplified Interface</h3> 
 
An attempt has been made to provide the everyday functionality of 
PYTHIA through the simplified interface. However, if classes or 
methods appear to be missing, please contact the PYTHIA authors; 
additional functionality can be included upon request. The following 
list highlights the available classes and methods in this interface, 
roughly categorized by function. Note that <code>help(pythia8)</code> 
will return all the available classes and methods in the interface. 
<ul> 
<li>top level: <code>Pythia</code></li> 
 
<li>event access: <code>Event</code>, <code>Particle</code>, 
<code>Vec4</code>, <code>RotBstMatrix</code></li> 
 
<li>particle data: <code>ParticleData</code>, 
<code>ParticleDataEntry</code>, <code>DecayChannel</code></li> 
 
<li>settings and information: <code>Info</code>, <code>HIInfo</code>, 
<code>Settings</code>, <code>Flag</code>, <code>Mode</code>, 
<code>Parm</code>, <code>Word</code>, <code>FVec</code>, 
<code>MVec</code>, <code>PVec</code>, <code>WVec</code></li> 
 
<li>user interface pointers: <code>Rndm</code>, <code>PDF</code>, 
<code>DecayHandler</code>, <code>RndmEngine</code>, 
<code>UserHooks</code>, <code>MergingHooks</code>, 
<code>BeamShape</code>, <code>SigmaProcess</code>, 
<code>TimeShower</code>, <code>SpaceShower</code>, 
<code>HeavyIons</code>, <code>PartonVertex</code></li> 
 
<li>analysis tools: <code>Hist</code>, <code>HistPlot</code>, 
<code>CellJet</code>, <code>ClusterJet</code>, <code>SlowJet</code>, 
<code>SlowJetHook</code>, <code>Sphericity</code>, 
<code>Thrust</code></li> 
 
<li>kinematic functions: <code>m</code>, <code>m2</code>, 
<code>dot3</code>, <code>cross3</code>, <code>cross4</code>, 
<code>theta</code>, <code>costheta</code>, <code>phi</code>, 
<code>cosphi</code>, <code>RRapPhi</code>, <code>REtaPhi</code></li> 
</ul> 
 
<h3>Installation</h3> 
 
To install the Python interface, the Python system header 
<code>Python.h</code> must be available. By default when configuring 
using <code>--with-python</code> the system <code>python-config</code> 
script will be used to determine the location of 
<code>Python.h</code>. In some cases, users might wish to use a 
different version of Python, and so <code>--with-python-config</code> 
can be used to set the Python configuration script used to pick up 
paths. Alternatively, the directory containing <code>Python.h</code> 
can be set manually with the option 
<code>--with-python-include</code>. Some example configurations could be 
as follows, 
<pre> 
    ./configure --with-python 
    ./configure --with-python-config=python3-config 
    ./configure --with-python-include=/usr/include/python2.7 
</pre> 
where the Python configuration script and path must be changed 
accordingly for the local system. 
 
<p/> 
After configuring the Python interface for PYTHIA to be built and 
running <code>make</code> as usual, the following files should be 
generated in the directory <code>lib</code>. 
<ul> 
<li><code>pythia8.so</code>: compiled Python module.</li> 
<li><code>libpythia8.[so,dylib]</code>: the standard shared PYTHIA 
library.</li> 
</ul> 
 
<p/> 
To ensure that the <code>pythia8.so</code> module is available to 
Python, the system variable <code>PYTHONPATH</code> should be set 
similar to 
<pre> 
    export PYTHONPATH=$(PREFIX_LIB):$PYTHONPATH 
</pre> 
where <code>PREFIX_LIB</code> is the directory <code>lib</code> which 
contains <code>pythia8.so</code>. Generally, the library paths should 
be set correctly, but it also may be necessary to set 
<pre> 
    export LD_LIBRARY_PATH=$(PREFIX_LIB):$LD_LIBRARY_PATH 
</pre> 
where <code>DYLD</code> should be substituted for <code>LD</code> in 
OS X. Alternatively, it is also possible to define the Python path 
from within Python, as is done within the provided examples. Note that 
the Python module is always compiled as <code>pythia8.so</code>, even 
in OS X. This is because older versions of Python in OS X do not 
correctly recognize modules ending with the <code>dylib</code> suffix. 
 
<h3>Examples</h3> 
 
To use the Python interface for PYTHIA, start Python 
and <code>import pythia8</code>. The provided examples can be run 
by <code>python mainNNN.py</code> where <code>NNN</code> is the number 
of the example. 
 
<h3>Interface Generation</h3> 
 
A script for automatically generating the Python interface, 
<code>generate</code>, is available in <code>plugins/python/</code> 
and should be run from this directory. This script requires that the 
user has Docker installed. A small Docker image of roughly 80 MB will 
be pulled to run the necessary generation code. There are a number of 
command line arguments which can be passed. 
<ul> 
<li><code>--help</code> prints the help message for the script.</li> 
<li><code>--part</code> generates the simplified interface. When 
<code>generate</code> is run without arguments, then this is the 
default behaviour. Note that this requires running the interface 
generation twice. The first time the required classes are interfaced, 
the second time additional classes are removed.</li> 
<li><code>--full</code> generates the full interface.</li> 
<li><code>--no-batch</code> exclude the Awkward-array batch interface.</li> 
<li><code>--user=FILE</code> generates a user defined interface using 
the Binder configuration given by <code>FILE</code>.</li> 
<li><code>--debug</code> can be specified with any of the options 
above and stops the temporary files used in generation from being 
removed.</li> 
</ul> 
Whenever PYTHIA headers are modified, the Python interface is 
invalidated, and so this automatic generation is particularly useful 
in such a situation. An example of generating the full Python 
interface is as follows. 
<pre> 
    cd plugins/python 
    ./generate --full 
</pre> 
 
</chapter> 
 
<!-- Copyright (C) 2025 Torbjorn Sjostrand --> 
