----------------------------------------------------------------------
INSTALLATION - BASIC
1) Once you have unpacked your tarball into a new (sub)directory, the
first step is to run the "configure" script. If you accept the
default compiler options, and plan to run PYTHIA 8 standalone, you
only have to type "./configure". This will create the file
Makefile.inc. Actually, running this script by hand is optional
since "make" will run "configure" anyway, but possible errors in
the paths will be less clearly visible.
2) Type "gmake" or "make". This will create an archive library.
On Linux systems gmake and make are usually equivalent. For others,
in case of doubt, use gmake. This applies below as well.
3) The library should now be ready for use. To study some examples,
go to the "examples" subdirectory. The README file in that
subdirectory contain further instructions how executables can
be built and run.
4) At any time, typing "gmake clean" will remove all files related to
the library compilation, including the library itself, but it will
not reset the configure selections. With "gmake distclean" additionally
the configure selection is reset, and many other temporary files are
removed. Output files you may have created during your test runs are
not affected. (A "gmake clean" is also available in the examples
subdirectory, see the README there.)
----------------------------------------------------------------------
INSTALLATION - ADVANCED OPTIONS
1) If you want to set various compilation options, the following two options
are available.
1.1) You can use command-line arguments to the configure script for
finer grain control of the installation. A full description of
the options is given by running "configure --help". Here additional
clarification is provided.
--enable-debug : turns on debugging flags and turns off optimization.
(This makes program execution much slower. If you later want to
switch optimization back on you have to rerun configure without
this option, since default is to allow optimization.)
--enable-optdebug : turns on debugging flags but allow optimization.
--enable-shared : turns on shared-library creation,
in addition to the archive libraries always built.
--enable-64bit : turns on 64 bits compilation flag
(is automatic on many 64-bit installations, but just in case).
--lcg=PLATFORM : allows you to specify the platform assumed for
compilation, which also affects the assumed location of the
libraries below; default is x86_64-slc5-gcc43-opt while other
supported values for name include slc4_ia32_gcc34,
slc4_amd64_gcc34 and slc3_ia32_gcc323 (deprecated).
--prefix=DIR : absolute path to a directory where the "bin",
"lib", "include", and "share" directories will be copied, by
a "gmake install" command subsequent to the "gmake" one.
Note that the files in the current working directory are
kept.
--prefix-COMPONENT=DIR : finer grain control over where the "bin", "lib",
"include", and "share" directories are copied for installation.
--arch=ARCH : sets the architecture to be used. The two options
are either "Darwin" for OS X, or "Linux" for other *nix
platforms. The architecture is used to set automatically the
"--cxx-shared", "--cxx-soname", and "--lib-suffix" flags but
otherwise has no effect.
--cxx=COMPILER : the compiler to be used. Currently PYTHIA 8 has
been successfully compiled with GCC and LLVM
(i.e. CLANG). Most systems will by default have "g++" aliased
or linked to the appropriate compiler for your program.
--cxx-common='FLAGS' : the flags that are passed for all
compilation statements. This is equivalent to the GNU
configuration variable CXXFLAGS, which is not supported here.
--cxx-shared='FLAGS' : the flags that are passed when building
shared dynamic libraries. These are only used when building
"lib/libpythia8.[so,dylib]" and
"lib/libpythia8lhapdf[5,6].so".
--cxx-soname='FLAGS' : these flags are passed to the linker when
setting the shared library names. Normally this should not
need to be changed.
--lib-suffix=SUF : the shared library suffix to use. This only
effects the name of "lib/libpythia8.SUF". Typically for *nix
systems this is ".so" and for OS X this is ".dylib".
1.2) All of the options listed above are formatted into
"Makefile.inc", which is also copied to
"examples/Makefile.inc" whenever "gmake" is run and
a change has been made. The "Makefile.inc" file can be simply
modified to change any of these options after "configure" is
run. Each option corresponds to a variable in this file as
follows: "--option-foo-bar" is translated to "OPTION_FOO_BAR".
2) If you have two CPUs or cores on your computer then using the "-j"
option on make/gmake may speed up compilation.
3) Necessary data are automatically loaded when you use the default
PYTHIA installation directory structure and run the main programs in
the examples subdirectory. However, in the general case, you must
provide the path to the .xml files, originally stored in the xmldoc
directory, where default settings and particle data are found. This
can be done in two ways.
3.1) You can set the environment variable PYTHIA8DATA to contain the
location of the xmldoc directory. In the csh and tcsh shells this
could e.g. be
setenv PYTHIA8DATA /home/myname/pythia81xx/share/Pythia8/xmldoc
while in other shells it could be
export PYTHIA8DATA=/home/myname/pythia81xx/share/Pythia8/xmldoc
where xx is the subversion number.
Recall that environment variables set locally are only defined in
the current instance of the shell. The above lines should go into
your .cshrc and .bashrc files, respectively, if you want a more
permanent assignment.
3.2) You can provide the path as argument to the Pythia constructor in
your main program, e.g.
Pythia pythia("/home/myname/pythia81xx/share/Pythia8/xmldoc");
where again xx is the subversion number.
When PYTHIA8DATA is set it takes precedence, else the path in the
constructor is used, else one defaults to the ../share/Pythia8/xmldoc
directory, which works fine when you run the examples/mainNN programs.
----------------------------------------------------------------------
INSTALLATION - EXTERNAL PACKAGES
1) PYTHIA 8 is designed to run out-of-the-box without any external
package dependencies. However, a variety of interfaces to external
packages is available. The building and linking to external
interfaces can be controlled via the same two options as the
advanced installation options.
1.1) Command-line arguments can be passed to "configure" using the
arguments that begin with "--with". When an external package
interface is enabled, "configure" takes the following steps.
a) It looks for the necessary binaries, headers, and libraries
that are needed for the external package. If no paths for the
package have been defined it looks along the default paths
for the system. If it can not find the necessary files, it
disables the external package and issues a warning as to why.
b) It looks for any external packages that this package might
require, and enables them if needed. It then checks to see if
these packages fulfill a). If not, it disables both packages.
If any "--with-PACKAGE" option is passed to "configure" it will
attempt to enable the package. For example, "--with-lhapdf6" will
enable LHAPDF6, while "--with-lhapdf6-lib=/lib/foo" will also
enable LHAPDF6. The available "--with" arguments are
described by "./configure --help", but further details are given
here.
--with-PACKAGE=[DIR] : enables a package and if "DIR" is
provided, then looks for the package at this root path. For
example, if the command "--with-lhapdf6=/foo/bar" is passed,
then "configure" will look for the library LHAPDF along the
path "/foo/bar/lib" and the LHAPDF headers along the path
"/foo/bar/include".
--with-PACKAGE-bin=DIR : specifies where to look for the package
binaries, and will ignore the root path from
"--with-PACKAGE=DIR" and the default system paths. This can
be used for non-standard installations of packages, where the
"bin", "lib", and "include" directories are scattered across
the system. In the example "--with-lhapdf6=/foo
--with-lhapdf6-bin=/foo/bar" the "configure" script will look
for libraries and headers on the paths "/foo/lib" and
"/foo/include", but the binaries on the path "/foo/bar" and
not "/foo/bin".
--with-PACKAGE-lib=DIR : same as above for bin, but now for
libraries.
--with-PACKAGE-include=DIR : same as above for bin, but now for
headers.
--with-PACKAGE-version=VER : is used when the "--lcg=PLATFORM"
option is specified, and will cause "configure" to look for
version "VER" of the package in the default LCG location.
1.2) All of the options above can also be set in "Makefile.inc" after
"configure" has been run. For each package the variable
"PACKAGE_USE" sets whether the package is used ("true" is used,
while "false" is not). The variables "PACKAGE_BIN",
"PACKAGE_INCLUDE", and "PACKAGE_LIB" then specify what paths are
used when building, for the binaries, headers, and libraries,
respectively.
2) A variety of external packages can be enabled, with details given here.
FASTJET3) The industry standard package to build jets,
http://fastjet.fr/. An interface to FastJet is provided in the
"include/Pythia8Plugins/FastJet3.h" header and a variety of
examples in "examples" link against the FastJet libraries.
HEPMC2) An interface to the HepMC event record, version 2:
http://lcgapp.cern.ch/project/simu/HepMC/. The interface
between PYTHIA 8 and HepMC is provided via the
"include/Pythia8Plugins/HepMC2.h" header.
HEPMC3) An interface for the upcoming HepMC 3 format. Currently this
package does nothing, as the record does not exist yet.
LHAPDF5) Provides an interface to the FORTRAN version of LHAPDF,
details can be found here:
http://lhapdf.hepforge.org/lhapdf5/. Because PDF sets are an
integral part of PYTHIA 8, the LHAPDF interface is handled
differently than for the other external packages. If LHAPDF5
support is enabled, then the shared library
"lib/pythia8lhapdf5.so" is built (even for OS X systems because
this library is not used for linking). This library is NOT
linked with PYTHIA, but rather is dynamically loaded at
runtime. Consequently, PYTHIA is no longer linked against
LHAPDF, but rather attempts to load it at runtime if an LHAPDF
set is requested. Note that the plugin library
"pythia8lhapdf5.so" must exist along the current library load
path. This can be set by the environment variable
"LD_LIBRARY_PATH" or at compile time using the "--Wl,-rpath"
linker flag.
LHAPDF6) The details for this package are the same as for LHAPDF5,
but now for the modern C++ version of LHAPDF,
http://lhapdf.hepforge.org/. There are three important things to
note here. First, the LHAPDF6 package provides the exact same C
interface as the LHAPDF5 package, and so technically supplying
LHAPDF6 libraries to the LHAPDF5 package option will work. This
is not recommended except for checking that the new C++
interface works properly. Second, both LHAPDF5 and LHAPDF6 can
be used simultaneously, technically. This behavior has not
been tested and is not recommended. Third, if using a version
earlier than 6.2, BOOST is required and can be specified using
"--with-boost".
ROOT) The ROOT HEP package used for data analysis and
visualization, http://root.cern.ch. This package is only used
for the "examples/main9[1,2].cc" examples.
BOOST) Advanced C++ libraries, http://www.boost.org/, which are needed
when using the C++ interface for LHAPDF6 with version < 6.2.
GZIP) Support for the reading of gzipped LHE files. It relies upon
zlib to function. The "--with-gzip=PATH" provides the location
for "zlib.h" and "libz.[so,dylib]". Note that when compiling a
final PYTHIA executable, the zlib library must also be
included, e.g.: "-lz". This is done automatically for the
examples in "examples/" when GZIP support is enabled.
PYTHON) Provides a Python interface to Pythia. To build this interface,
the executable "python" must be available, as well as the
Python system header "Python.h". Typically this can be found
under "/usr/include/pythonX.Y". Note that the interface
includes this header as "#include <Python.h>" so the user will
typically need to explicitly set the include path with
"--with-python-include=/usr/include/pythonX.Y" or something
similar. The interface works both with Python 2 and 3.
----------------------------------------------------------------------
COMPILING PROGRAMS AGAINST PYTHIA 8
Generally compiling programs against the PYTHIA 8 libraries requires
that the PYTHIA 8 header and library directories be specified via the
usual -I and -L compiler flags, and that at least the -lpythia8 option
be provided to link against the PYTHIA 8 library.
Extra compiler flags will be needed if you are making use of PYTHIA 8's
external package features. To make this simpler,
and so that an identical compilation recipe can be used with different
builds of PYTHIA (e.g. for inclusion in shared Makefiles), a pythia8-config
script will be installed into PREFIX_BIN/bin by the "make install" build
target. A typical usage of this script is as follows:
g++ myprog.cc -o myprog `pythia8-config --cppflags --libs`
The --cppflags option to this script makes pythia8-config write out
the necessary -I flags corresponding to the installed headers, and
--libs adds the required -L and -l flags.
The pythia8-config script may also be used at runtime to generate the
data directory environment variable if needed, e.g.:
PYTHIA8DATA=`pythia8-config --xmldoc` ./myprog
----------------------------------------------------------------------
FOR WINDOWS USERS
PYTHIA 8 is primarily intended to be run in a Unix-based environment,
such as Linux or Mac OS X. Unfortunately it is not currently supported
for Windows platforms. If you want to experiment, and do not have the
knowledge to set everything up from scratch yourself, we are aware of
three possible approaches to take.
1) Install Linux in a Virtual Machine (VM) on your Windows system,
and then work within this virtual environment as on any regular
Linux platform. You could e.g. download the VirtualBox
https://www.virtualbox.org/
and install either Ubuntu or CernVM (Scientific Linux)
http://cernvm.cern.ch/
on it. Make sure your installation includes the g++ compiler.
2) Install the Cygwin package, intended to allow Linux apps to run
under Windows, see
https://www.cygwin.com/
Be sure to install the Dev tools, which appears in the list of options
to include, but won't be installed by default. Then put the Pythia
folder in the Cygwin/home directory, and compile and work with it
as usual. (The include/Pythia8Plugins/execinfo.h file provides dummy
versions of methods needed for proper compilation.)
3) The nuget.org website
http://www.nuget.org/packages/Pythia8/
contains pre-built PYTHIA packages ready to be used under Windows
Visual Studio.
We take no responsibility for either of these solutions.
Also note that linking with other libraries may involve further
problems, in particular for the dynamic loading of LHAPDF.
----------------------------------------------------------------------
LEARN MORE
To learn more about the current program:
A) A brief self-contained introduction is found in the
share/Pythia8/pdfdoc/pythia8200.pdf file.
B) Details can be found by opening a web browser on the
share/Pythia8/htmldoc/Welcome.html file, and then navigating among
the pages in the index there.
----------------------------------------------------------------------
decibelcooper/pythia8
Pythia8 mirror, as used in ALICE experiment. Please refer to http://home.thep.lu.se/~torbjorn/pythia81html/Welcome.html for the official mirror.
C++GPL-2.0