Introduction

HepMC3 is a new version of the HepMC event record. It uses shared pointers for in-memory navigation and the POD concept for persistency. Visit the home page of the project http://hepmc.web.cern.ch/hepmc/ or the CERN GitLab repository https://gitlab.cern.ch/hepmc/HepMC3 for more information. A short information on the compatibility between the HepMC3 versions and deprecation of some functionality see below. You can also send bug reports, feature requests and questions about HepMC3 to hepmc-devATcern.ch.

Quick-start (applicable to recent versions):

On the Linux platform HepMC3 is available from the standard repositories of multiple many linux distributions: Fedora, CentOS(EPEL), Arch Linux, Mageia, openSUSE Tumbleweed, Debian (outdated) etc. It is recommended to use the system package manager to install HepMC3 for these systems. The following commands will install the HepMC3 in the corresponding systems:

Fedora: The package is available from the standard repository. To install:
```
sudo dnf install HepMC3 HepMC3-devel HepMC3-search HepMC3-search-devel HepMC3-interfaces-devel HepMC3-doc
```
To have a full installation of the HepMC3-doc package, add an option --setopt=tsflags=''

RHEL, CentOS and compatible The package is available from the EPEL repository. To install:

sudo yum install epel-release
sudo yum install HepMC3 HepMC3-devel HepMC3-search HepMC3-search-devel HepMC3-interfaces-devel HepMC3-doc

For the Fedora and CentOS the ROOT interface packages HepMC3-rootIO and HepMC3-rootIO-devel can be installed in the same way, but will bring root as a dependency. The python binding packages could have different names depending on the used system, e.g. these are python36-HepMC3, python36-HepMC3-rootIO and python36-HepMC3-rootIO for the CentOS7. Therefore, the simplest solution is to install bindings for all the available python version in the system using

  sudo yum install python*-HepMC3

openSUSE/Leap The HepMC3 package is available from the standard repositories https://build.opensuse.org/package/show/openSUSE:Leap:15.2:Update/HepMC. To install:
```
sudo zypper install HepMC3
```
The package does not include ROOT interface.
Arch linux The package is available from https://www.archlinux.org/packages/community/x86_64/hepmc/. To install:
```
sudo pacman -Syu hepmc
```
The dependencies can vary.
Gentoo linux The package is available in the standard repository https://packages.gentoo.org/packages/sci-physics/hepmc. To install:
```
sudo emerge --ask hepmc:3
```
MacOSX The HepMC3 package is available in the homebrew-hep repository https://davidchall.github.io/homebrew-hep/. To install:
```
brew tap davidchall/hep
brew install hepmc3
```
The package optionally includes ROOT interface.
Windows The precompilled HepMC3 packages are available in for Windows and other platforms also in PyPi. The Windows users can use pip to install HepMC3. pip install HepMC3 The packages from pip do not include ROOT interface.
LCG platforms The HepMC3 package is available in the LCG from multiple platforms. The HepMC3 cmake files are located under /cvmfs/sft.cern.ch/lcg/views/LCG_97/${LCG_PLATFORM}/share/HepMC3/cmake, e.g. in /cvmfs/sft.cern.ch/lcg/views/LCG_97/x86_64-centos7-gcc8-opt/share/HepMC3/cmake for the x86_64-centos7-gcc8-opt platform.

If for any reason the instalation from the repositories is not possible or is not desired, the instructions to build HepMC3 from the sources The minimal requirements for the installation from sources are

C++ compiler with c++11 standard support.
CMake version 3.X.

It is strongly recommended to read this documentation completely before the installation. However, if for some reason that is not possible, here is a set of commands for the instalation that can be copied and pasted into a Unix terminal. In some cases this action might result in a fully functional installation.

  wget http://hepmc.web.cern.ch/hepmc/releases/HepMC3-3.2.6.tar.gz
  tar -xzf HepMC3-3.2.6.tar.gz
  mkdir hepmc3-build
  cd hepmc3-build
  cmake -DCMAKE_INSTALL_PREFIX=../hepmc3-install   \
        -DHEPMC3_ENABLE_ROOTIO:BOOL=OFF            \
        -DHEPMC3_ENABLE_PROTOBUFIO:BOOL=OFF        \
        -DHEPMC3_ENABLE_TEST:BOOL=OFF              \
        -DHEPMC3_INSTALL_INTERFACES:BOOL=ON        \
        -DHEPMC3_BUILD_STATIC_LIBS:BOOL=OFF        \
        -DHEPMC3_BUILD_DOCS:BOOL=OFF     \
        -DHEPMC3_ENABLE_PYTHON:BOOL=ON   \
        -DHEPMC3_PYTHON_VERSIONS=3.12     \
        -DHEPMC3_Python_SITEARCH312=../hepmc3-install/lib/python3.12/site-packages \
        ../HepMC3-3.2.6
  make
  make install

The full explanation for the installation options is given below.

The first step of the installation is to a)Checkout the HepMC from GIT repository:

git clone https://gitlab.cern.ch/hepmc/HepMC3.git

or b) download the tarball with wget or any other tool

wget http://hepmc.web.cern.ch/hepmc/releases/HepMC3-3.2.6.tar.gz
tar -xzf HepMC3-3.2.6.tar.gz

Create a workspace area on which to perform the builds

mkdir hepmc3-build
cd hepmc3-build

Configure the HepMC3 features to build and install: a)

cmake -DHEPMC3_ENABLE_ROOTIO=OFF -DCMAKE_INSTALL_PREFIX=../hepmc3-install ../HepMC3

or b)

cmake -DHEPMC3_ENABLE_ROOTIO=OFF -DCMAKE_INSTALL_PREFIX=../hepmc3-install ../HepMC3-3.2.6

To disable compilation of the search engine (enabled by default) add

-DHEPMC3_ENABLE_SEARCH=OFF

Please note, in case of using the search engine, the easiest way to link against HepMC3search could be to use static version of the library.

To disable compilation of Python bindings (enabled by default) add

-DHEPMC3_ENABLE_PYTHON=OFF

See points 10a and 10b below for more details on configuring the Python extension for installation into non-system areas (e.g. in a virtual environment) and for compatibility with PyPy.

Please note that on some RedHat-like systems the executable of CMake version 3 is called cmake3.

In order to build with ROOTIO put the following flags and define LD_LIBRARY_PATH:

-DHEPMC3_ENABLE_ROOTIO=ON -DROOT_DIR=path_to_ROOT6_installation
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:path_to_ROOT6_libraries

In order to build with HepMC3 example put

-DHEPMC3_BUILD_EXAMPLES=ON

Please note that some examples are disabled on Windows.

For tests and for development purposes HepMC3 uses extra packages, e.g. GrpahViz, binder. On Windows, most extra packages have no default location.

In order to build and run tests put

-DHEPMC3_ENABLE_TEST=ON

and run

make test

after compilation is completed

Build and install HepMC3

make -jN install

where N denotes a number of desired parallel jobs. On Windows (in Unix-compatible shell) one can use

cmake --build ./

instead.

Please note that you have to have permissions to install HepMC3 into the selected directory.

To run the tests do

ctest .

On Windows/MSVC the build type should be specified

ctest . -C Debug

HepMC3 packages are available from standard repositories of Debian, Redhat/Fedora, Arch, hep-homebrew and others. To build Windows installer use NSIS and run

cpack.exe -G NSIS -C Debug

The primary supported development chains are gcc@Linux, clang@Linux, gcc@OSX, clang@OSX and MSVC@Windows10, however the code has been tested on other compilers and systems, e.g. clang@FreeBSD, Sun@Solaris11, gcc@Solaris11, Sun@Linux, PGC@Linux etc. Only a limiter support can be offered for these systems.

HepMC3 is supplied with Python bindings codes that can be build on multiple systems. The number of potential combinations of compiler suites, Python versions and operation systems is quite large, therefore it is recommended to install the HepMC3 form the default repositories of the used operating system. If not possible, the following options are available

compile the Python package from sources
use the precompiled binaries from PyPi: https://pypi.org/project/HepMC3/
use the https://anaconda.org/conda-forge/hepmc3 In addition to that part of the bindings are implemented in the pyhepmc project

https://github.com/HDembinski/pyhepmc.

Please note that only the PyPi packages are officially supported.

10.1

The installation path for the Python modules can be tweaked with a set of dynamically named CMake variables:

HEPMC3_Python_SITEARCH${Python_VERSION_MAJOR}${Python_VERSION_MINOR}

For example, the variable is called HEPMC3_Python_SITEARCH36 for Python version 3.6. So, to set the installation path of the HepMC3 modules for Python 3.6, add this to the arguments of cmake:

-DHEPMC3_Python_SITEARCH36=/path/where/I/want/my/python/of/version/3.6/modules

By default the HEPMC3_Python_SITEARCH${Python_VERSION_MAJOR}${Python_VERSION_MINOR} variables are set to the path of the used installation of Python. In some cases you would not have permissions to install the Python modules to that directory, so the change of the installation path for the Python modules would be mandatory. A natural choice is the Python module directory inside your installation prefix, e.g.

cmake ...
   -DCMAKE_INSTALL_PREFIX=/my/install/path
   -DHEPMC3_Python_SITEARCH36=/my/install/path/lib/python3.6/site-packages

To specify the desired versions of Python to build the HepMC3 modules, pass the HEPMC3_PYTHON_VERSIONS option to cmake, e.g.

cmake ... -DHEPMC3_PYTHON_VERSIONS=3.6,3.12

will build Python modules for versions Python 3.6 and Python 3.12. By default CMake will attempt to build the Python modules for P

Hepmc3

Install / Use

README

Introduction

Quick-start (applicable to recent versions):