A Python Interface

SETTINGS SAVED TO FILE

"; } else { echo "NO FILE SELECTED YET.. PLEASE DO SO HERE

"; } } ?>

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.