## 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.