A Python Interface
Python 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. An experimental Python interface
to PYTHIA is available. This interface has been generated
using SWIG
(Simplified Wrapper and Interface Generator). 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.
Features
An attempt has been made to translate all PYTHIA classes and functions
to the Python interface as directly as possible. The following
features are included in the Python interface:
- The interface is compatible with Python version
2.1
and beyond, including 3.5
, the current version of Python.
- All PYTHIA classes and functions are
available. See
main01.py
for a direct Python translation
of the C++ main01.cc
example.
- Most of the plugin classes are also available in the
interface. See
main34.py
for a direct Python translation
of the C++ main34.cc
example which uses
the LHAupMadgraph
class
from include/Pythia8Plugins/LHAMadgraph.h
.
- When available, documentation through the
built-in
help
function in Python is provided. Please note
that this documentation is automatically generated, similar to
the Doxygen
documentation. Consequently, the inline Python documentation is not a
replacement for this manual.
- All operators defined in C++, e.g.
Vec4*double
, as
well as reverse operators, e.g. double*Vec4
, are
available.
- Classes with defined
[]
operators are iterable, using
standard Python iteration, e.g. for prt in
pythia.event
.
- Classes with a
<<
operator or a list
function can be printed via the built-in print
function
in Python. Note this means that a string representation
via str
is also available for these classes in
Python.
- Specific versions of templates needed by PYTHIA classes are
available where the naming scheme is the template class name followed
by its arguments (stripped of namespace specifiers); pointers to
classes are prepended with
Ptr
. For
example, vector<int>
is available via the interface
as VectorInt
, map<string, Mode>
as MapStringMode
,
and vector<ProcessContainer*>
as VectorProcessContainerPtr
.
- Derived classes in Python, for a subset of PYTHIA classes, can be
passed back to PYTHIA. This is possible for all classes that can be
passed to the
Pythia
class via the setXPtr
functions and includes the following classes: BeamShape
,
DecayHandler
, LHAup
,
MergingHooks
, PDF
, PhaseSpace
,
ResonanceWidths
, RndmEngine
,
SigmaProcess
, SpaceShower
, TimeShower
,
and UserHooks
. The protected functions and members of
these classes are available through the Python
interface. See main10.py
for a direct Python translation
of the C++ main10.cc
example which uses a derived class
from the UserHooks
class to veto events.
Limitations
A variety of methods to interface C++ code with Python exist, each
with its own advantages and disadvantages, some of which are being
rapidly developed. Currently, for the purposes of an interface to
PYTHIA, SWIG provides the best option. However, this may not remain
the case, and the technical interface may be changed to some other
method, e.g.
cppyy,
in the future. The Python interface to PYTHIA currently suffers the
following limitations:
- In the
CoupSUSY
class all public members that are
3-by-3 arrays cannot be accessed, these
include LsddX
, LsuuX
, LsduX
,
LsudX
, LsvvX
, LsllX
,
LsvlX
, LslvX
, as well as the
equivalent R
versions of these
members. Additionally, rvLLE
, rvLQD
,
and rvUDD
cannot be accessed.
- In the
MergingHooks
class, the protected
methods orderHistories
, allowCutonRecState
,
and doWeakClustering
with bool
return values
have been renamed
as getOrderHistories
, getAllowCutonRecState
,
and getDoWeakClustering
, respectively, in the Python
interface.
- The public
headerStream
, initStream
,
and eventStream
members of the Writer
class,
used for writing LHEF output, cannot be accessed from the Python
interface.
- For derived Python classes of the PYTHIA class
LHAup
,
the protected member osLHEF
cannot be accessed.
- The wrapper generated by SWIG is large (10 MB), and
consequently the compile time can be significant. The only way to
reduce the size of the wrapper is to remove functionality from the
interface.
- Creating a derived Python class from a PYTHIA class, as described
above in the features, is only possible for a subset of PYTHIA
classes. However, if this feature is needed for specific classes, they
can be added in the future upon request. This feature is not enabled
by default for all classes to reduce the generated wrapper size.
- Python interfaces have not been generated for plugins
within
include/Pythia8Plugins
which have direct external
dependencies. This means there are no Python interfaces for any of the
classes or functions defined
in EvtGen.h
, FastJet3.h
, HepMC2.h
,
or LHAFortran.h
. However, interfaces are available for
all remaining plugins, including both LHAMadgraph.h
and PowhegProcs.h
.
Installation
To install the Python interface, both the python
command,
as well as the Python system header Python.h
must be
available. The directory containing the python
command
can be passed to the PYTHIA configuration via the
option --with-python-bin
, while the directory
containing Python.h
can be set with the
option --with-python-include
. An example configuration
could be as follows,
./configure --with-python-include=/usr/include/python2.7 \
--with-python-bin=/usr/bin
where the paths must be changed accordingly for the local
system. If the location of Python.h
is unknown,
oftentimes the command python-config --includes
will
supply the correct path. Please note that the Python versions for
the python
command and Python.h
header must
match. This is of particular importance when compiling against Python
3. Many systems will provide the Python 3 command
via python3
rather than python
, so either a
temporary alias should be made, or a soft link of
the python3
command to python
could also be
made. However, take care, as many systems rely on Python 2 for things
such as package managers, etc. Also note that if one wishes to utilize
GZIP support (needed for the LHAupMadgraph
plugin) then
the option --with-gzip
should also be provided.
After configuring the Python interface for PYTHIA to be built and
running make
as usual, the following files should be
generated in the directory lib
.
pythia8.py
: the Python code for the interface.
pythia8.pyc
: the byte-compiled Python code for the
interface.
_pythia8.so
: the C++ library needed for the interface.
libpythia8.[so,dylib]
: the standard shared PYTHIA
library.
To ensure that the pythia8.py
module is available to
Python, the system variable PYTHONPATH
should be set similar to
export PYTHONPATH=$(PREFIX_LIB):$PYTHONPATH
where PREFIX_LIB
is the directory lib
which
contains pythia8.py
. Generally, the library paths should
be set correctly, but it also may be necessary to set
export LD_LIBRARY_PATH=$(PREFIX_LIB):$LD_LIBRARY_PATH
where DYLD
should be substituted for LD
in
OS X. Alternatively, it is also possible to define the Python path from
within Python, as is done within the provided examples.
Examples
To use the Python interface for PYTHIA, start Python
and import pythia8
. The provided examples can be run
by python mainXX.py
where XX
is the number
of the example.