Use

While PYTHIA-CONTRIB packages can be installed separately, per individual package documentation, this repository provides a unified set of tools to install PYTHIA-CONTRIB packages. A simple workflow for installing packages is as follows.

Install Pythia 8, if not already installed, and ensure that the command pythia8-config is available.
Check out the use repository. bash git clone git@gitlab.com:pythia8-contrib/use.git cd use
Use the enable script to enable the requested packages. bash ./enable PACKAGE[/VERSION] ... [OPTIONS]
Run the configure script to configure all the enabled packages. bash ./configure [OPTIONS]
Build and install the packages to a location known by Pythia at run time. This location can be configured for Pythia by setting the environment variable PYTHIA8CONTRIB. bash make make install

Details on steps 3–5 are given in the dedicated sections of this documentation. Packages can also be configured individually. To do this, use the same workflow as above, but, in step 4, first configure each package by hand and then run configure at the top level. Any packages that have already been configured will not be configured when running the top level configure.

As an example, consider an installation of the SimpleCluster package, which provides a hadronization plugin using a simplified cluster model. To begin, Pythia 8 must already be installed.

PYTHIA=<installation path for Pythia 8>
git clone git@gitlab.com:Pythia8/releases.git pythia83
cd pythia83
./configure --prefix=$PYTHIA
make
make install

Next, pythia8-config must be available on PATH. If it is not, update the PATH environment variable.

export PATH="$PATH:$PYTHIA/bin"

Note, it is also possible to use the options starting with --with-pythia8 as part of the configure script to set the installed location of Pythia 8.

Now that Pythia 8 is available, we can enable, configure, and build the SimpleCluster package.

git clone git@gitlab.com:pythia8-contrib/use.git
cd use
./enable SimpleCluster
./configure
make
make install

Here, we install the enabled PYTHIA-CONTRIB packages along the same $PYTHIA prefix as the Pythia 8 installation, the default behavior when pythia8-config is available.

Finally, we can run one of the examples provided by the SimpleCluster package. For most packages, examples should be provided by the package authors and will be copied into the share/Pythia8Contrib directory of the Pythia 8 installation when make install is called. Here, the examples will have been copied to the directory share/Pythia8Contrib/SimpleCluster/examples in the Pythia 8 installation.

export PYTHIA8CONTRIB=$(pythia8-config --datadir)/../Pythia8Contrib
cd $PYTHIA8CONTRIB/SimpleCluster/examples
make testPlugins
./testPlugins testPlugins.cmnd UserFrag.cmnd

Here, testPlugins is an executable where files containing Pythia settings can be passed as arguments.

Enabling Packages

Enabling a package checks out the package source code from gitlab.com/pythia8-contrib/packages so that it can be configured, built, and installed. The usage of enable is as follows:

./enable PACKAGE[/VERSION] ... [OPTIONS]

A help message can be printed by passing the option --help. Any number of packages with name PACKAGE can be enabled, with the optional /VERSION passed after each PACKAGE to specify the package version. If VERSION for a package is not specified, then the largest tagged version number for that package will be used. For example,

./enable SimpleCluster/v8317.01 Hdsense

will enable the SimpleCluster package, using v8317.01 if this version is available, and enable the Hdsense package with the largest tagged version. If a requested version is not available, then the largest tagged version number of the package will be used. If there are no tagged version numbers for the package, then the head of the package is used. The head of the package, tagged or otherwise, can also be requested explicitly by setting VERSION to HEAD.

The enable script can be run multiple times. However, if a package has already been enabled, then enable will skip that package, unless the --force option is used. In that case, enable deletes the enabled package and checks out a new copy of the package.

Passing the --list option to enable will print all available packages and disregard all other arguments. An example of the output (at the time of writing) is given below.

The following packages are available from pythia8-contrib.
SherpaShower
Hdsense
IRCExplorer
SherpaFrag
SimpleCluster
ExampleML

The --all option will enable all the packages listed by --list, using the most recent version available for each package.

The available versions for a package can be listed by passing the --tags option to enable. The tagged versions will then be printed for each requested PACKAGE[/VERSION], without enabling any of them. For example the command,

./enable SimpleCluster Hdsense --tags

will produce the following example output (at the time of writing).

SimpleCluster:
    v8317.00
    v8312.00
Hdsense:
    v8316.00

Here, SimpleCluster has two tagged versions, while Hdsense has one tagged version. The version tagging depends upon the convention adopted by the package author, but it is suggested that the major version, e.g., v8317, specifies the Pythia version the package was developed for, while the minor version, e.g., 00, specifies the package version. The tag does not generally specify compatibility with Pythia versions. Instead, Pythia version compatibility can be checked either at contrib.pythia.org or through the configure script.

Configuring Packages with External Dependencies

Packages may have external dependencies that must be configured before building. PYTHIA-CONTRIB does not require a specific build configuration system be used for every package, and leaves this as a choice to the package authors. However, a default build configuration system is provided. The configure script uses this common system to allow a user to configure the dependencies for packages with a single command. For packages that do not use this system, please refer to the documentation for that package and configure it directly.

The configure command has the following usage.

./configure [OPTIONS]

The --help option prints the documentation for configure. Running configure will configure all packages that have been enabled with the enable command and that are not already configured. A package is marked as configured if the file Makefile.inc is present at the top level of the package, i.e., PACKAGE/Makefile.inc. If the package is already configured, configure will skip configuring that package and print a warning. Passing the --force option will configure all packages, even if already configured. The --versions option will print the compatible Pythia 8 versions for each package, without configuring the package.

By convention, options starting with --with-DEP allow the dependency DEP to be configured, where DEP is all lowercase. For example, the options starting with --with-fastjet3 configure the FastJet package. The following --with-DEP options allow for fine-grained control over finding the relevant dependency.

--with-DEP=DIR: look for DEP at the top directory DIR.
--with-DEP-bin=DIR: look for DEP's binaries along the path DIR.
--with-DEP-lib=DIR: look for DEP's libraries along the path DIR.
--with-DEP-include=DIR: look for DEP's headers along the path DIR.
--with-DEP-config=BIN: use BIN as the configuration script for DEP.

Note that the base Pythia build will have its own configuration. Any packages configured there have no impact on a PYTHIA-CONTRIB package.

An example of enabling external dependencies is as follows.

./enable Hdsense
./configure --with-fastjet3=<path to FastJet3>

No checks are made by configure to ensure that the dependency options passed this way are valid. Additionally, by convention the package-level configurations will also not issue warnings for invalid options. This is because one package might require a FastJet dependency, while another may require HepMC but not FastJet.

Options other than those beginning with --with-DEP can also be passed to configure. In this way, CMake or other build-system options can be passed, like -DBUILD_SHARED_LIBS=ON, for example. By necessity, all options are passed to the configuration system for each enabled package. This means that configure does not allow different versions of a dependency for different packages. For example, to configure one package using FastJet 3.5.0 and all other packages with FastJet 3.5.1, configure the first package manually to use FastJet 3.5.0 and then run configure, passing FastJet 3.5.1 as a dependency, to configure all the other packages.

All packages can be installed after being built. The --prefix and --prefix-COMPONENT options specify where the packages are installed. If no --prefix options are passed, configure will use pythia8-config, if available, to determine the installation paths. If pythia8-config is not available, --prefix defaults to the current working directory. The pythia8-config script can be made available by placing it on PATH.

export PATH="$PATH:<directory containing pythia8-config>"

If pythia8-config is available, configure will also check if the package is compatible with the version of Pythia 8 obtained by the command pythia8-config --version. If the package is not compatible, a warning will be printed.

It is also possible to directly specify the installation path using --prefix=DIR which places all PYTHIA-CONTRIB components along the common path DIR. Fine-grained installation control is also available with the --prefix-bin, --prefix-lib, --prefix-include, and --prefix-share options. For example,

./configure --prefix-share=SHAREDIR

will install the shared data for each package to the directory SHAREDIR but all other components to the paths determined from pythia8-config. Note that for the plugins in most packages to be usable by Pythia 8, only the plugin library and share data need to be installed.

Building Packages

To build all the packages, make should be called after calling configure, as done in the initial workflow above. Any standard options can be passed to make, for example use all available cores to build.

make -j

Before calling make, configure should be run and a Makefile.inc should be present in the top-level directory. This Makefile.inc is read by the top-level Makefile and sets the packages to build. If a package has not been successfully configured, then that package will be skipped. The top-level Makefile calls make in each enabled and configured package with the argument contrib and also passes all options given by the user to make at the top level.

There are a number of targets that can be passed to the make command at the top level. Individual packages can be built by calling make PACKAGE, again with whatever additional options are needed. Calling make clean removes the local build directories (bin, include, lib, and share) but does not call clean on each package. Calling make cleanpkgs will run make clean for each package while make distclean will remove all enable- and configure-generated files, including the local build directories and every successfully configured package directory. Calling make install installs the contents of the local build directories to the locations specified with the --prefix options passed to configure.

Specifying XML Paths for Package Settings

Some PYTHIA-CONTRIB packages use the Pythia 8 XML framework to specify settings and provide documentation. If this is the case, the package will typically look for the file PACKAGE/xmldoc/Index.xml along the following paths.

Relative to the PYTHIA8CONTRIB environment variable, i.e., $PYTHIA8CONTRIB/PACKAGE/xmldoc/Index.xml.
Relative to the PYTHIA8DATA environment variable, i.e., $PYTHIA8DATA/../../PACKAGE/xmldoc/Index.xml.
The path itself (whether relative or absolute), i.e., PACKAGE/xmldoc/Index.xml.

If the relevant XML index for the package cannot be found, Pythia 8 will issue the following warning message.

Settings::init: settings file PACKAGE/xmldoc/Index.xml not found

If this is the case, then set PYTHIA8CONTRIB such that $PYTHIA8CONTRIB/PACKAGE/xmldoc/Index.xml points to the XML index for that package.

export PYTHIA8CONTRIB=<path to share/Pythia8Contrib>

In many cases, Pythia 8 may be installed via a package manager (dnf, apt, PyPI, Anaconda, etc.). In these cases the environment variable PYTHIA8DATA might be set by the Pythia 8 setup from the package manager and may override the XML path for local versions of Pythia 8, resulting in incompatible versions of the XML framework being loaded. If this occurs, the PYTHIA8DATA environment variable needs to be set explicitly to reference the folder containing the top-level Index.xml needed by Pythia.