Introduction

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. The workflow is as follows.

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 plugin packages. bash ./enable PACKAGE[/VERSION] ... [OPTIONS]
Run the configure script to configure all the enabled packages. bash ./configure [OPTIONS]
Build and install the packages. bash make make install

Details on steps 2 - 4 are given in the dedicated sections of this documentation. Packages can also be configured individually. To do this the same workflow as above is used but now in step 3 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.

Below in this introduction is an example for installing 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 --with-pythia8 options 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 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.

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

Enabling Packages

The usage of enable is as follows.

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

Help 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 enable script can be run multiple times. However, if a package has already been enabled, then enable will skip that package. The --force option will cause enable to delete the enabled package and check 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 projects 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.

Configuring Packages

Because packages may have complex dependencies, PYTHIA-CONTRIB does not require a specific build configuration system be used for every package, and leaves this as a choice to the developers. However, a default build configuration system is provided which many packages use. 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 allows the dependency DEP to be configured, where DEP is all lowercase. For example, --with-fastjet3 options 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.

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 dependency for FastJet, 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 with configure it is not possible to use different versions of a dependency for different packages. As an example, consider using FastJet 3.5.0 for one package and FastJet 3.5.1 for all other packages. To accomplish this, configure the first package by hand 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. 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-grain 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 most packages to function as plugins to Pythia 8, only the library and share data need to be installed.

Building Packages

To build all the packages, make should be called. 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, than 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; this means that all visible folders at the top level will be removed so this command should be treated with caution. Calling make install installs the contents of the local build directories to the locations specified with the --prefix options passed to configure.

XML Paths

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.

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>