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.