Mammoth

Mammoth is a package for analysis and interpretation of heavy-ion collision data. Analyses are performed using a (predominately) columnar based paradigm. The main analysis framework contains a collection of python based functionality, as well as c++ code bound to python (e.g. for jet finding via fastjet). I/O adapters for a variety of formats are implemented, enabling analysis of real measure data, as well as outputs from Monte Carlo generators.

This package has been used for a variety of analyses, and the framework is fully validated to reproduce e.g. the ALICE analysis framework. For example, mammoth was used for the measurement recently released from the ALICE collaboration to search for quasi-particle (i.e. Moliere) scattering using jet substructure.

Important

This package is developed for my own use. Framework and code is subject to change, and documentation is limited!

Installation

To install mammoth, we have to 1) install the dependencies, and then 2) actually install the package.

Dependencies

Although this is a python package, we also use c++ code, so we need to setup the proper dependencies (it's used for e.g. jet finding, that is then wrapped in python for use). This requires a compiler which supports c++17. We also have some setup steps that ease development. I'll assume you've setup your environment correctly, but you can also check this quick reference for some pointers.

We'll need to install:

1. pachyderm [python support package useful for development]
2. FastJet [c++ package for jet finding]
3. RooUnfold [optional - requires ROOT. Probably best to skip unless you know you need it]

Pachyderm

Pachyderm is a python physics support library that I maintain. When installing mammoth in development mode, pachyderm needs to be available in the external directory. You can do this via:

$ cd external; git clone https://github.com/raymondEhlers/pachyderm.git; cd -

FastJet

FastJet is the standard package for jet finding. It should be automatically installed when you install mammoth (see below). However, if that fails for some reason, your first step should be to ensure that fastjet is installed correctly. There's a dedicated script to install it:

$ ./mammoth-cpp/external/install_fastjet.sh

RooUnfold [Optional]

RooUnfold is used for unfolding. If you're not familiar with this, you can ignore this dependency. RooUnfold requires boost and ROOT to be installed and available in your environment. You can install RooUnfold via:

$ ./external/install_roounfold.sh

Installing mammoth

The easiest way to install mammoth for development is to use pdm. pdm is preferred because it handles local dependencies better than most other build managers, which is particularly useful for development. Once you've setup the dependencies, you can install mammoth with:

$ pdm install -d

Note that the pdm lock file (pdm.lock) is included in the repository, ensuring a reproducible environment.

Development helpers

Playing nicely with VSCode

VSCode is a helpful tool, but requires some configuration to make it useful for development. For example, it won't know how to access the pybind11 headers. I document a few possible approaches here to address these kinds of problems - you can try them out to see what works best for you (this has gotten easier with time - I expect the first option will be enough).

• Manually configure CMake for VSCode.
• Dedicated virtualenv for headers via nox

Manually configure CMake

Here, we'll configure VSCode to pick up some package info (e.g., the pybind11 headers used for accessing c++ functionality in python), which will make development easier. We'll also configure it to play nicely with scikit-build-core. It takes a bit of work and is a bit fragile, but isn't terrible. To set this up, you will need to add these values to your .vscode/settings.json:

"cmake.sourceDirectory": "${workspaceFolder}/mammoth-cpp",
"cmake.configureSettings": {
    "CMAKE_PREFIX_PATH":"${workspaceRoot}/.venv-3.13/lib/python3.13/site-packages/pybind11/share/cmake/pybind11",
},
"cmake.configureArgs": [
    "-DSKBUILD_PROJECT_NAME=mammoth-cpp"
],

You will need to adjust the virtualenv path in CMAKE_PREFIX_PATH (part of cmake.configureSettings) as necessary. This should allow the CMake plugin to configure properly¹. This is the approach RJE uses as of May 2025.

Dedicated virtualenv for headers

Alternatively, you can create a dedicated virtualenv to contain the pybind11 headers. You can do this via nox (also useful for testing across python versions). An example is available at this issue, which you will have to adapt for this project.

Footnotes

1. Configuring with CMake used to fail due to missing scikit-build-core variables, but they're now (May 2025) defined in the CMakeLists.txt when needed, so this should not be an issue anymore. ↩