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 mammoth package. The expectation is that you are installing the package inside of a virtual environment. I won't cover it here, but if you're not familiar, you can try some older instructions that I wrote, or check with your favorite search engine.

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 (which is usually what you're doing), 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 -

(you could also use symlinks to store it elsewhere, but that's beyond the scope of this document).

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. In my approach to analysis, the unfolding itself performed with the alice-substructure package. 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're responsible for sorting that once (careful with potentially conflicting python versions). Once those are available, you can install RooUnfold via:

$ ./external/install_roounfold.sh

Installing mammoth

The easiest way to install mammoth for development is to use pdm or uv. I historically used pdm, but most packages, including my own, have moved towards uv since 2025. They each have their own quirks, but they generally support the features we need (namely, good handling of local editable dependencies). Once you've setup the dependencies, you can install mammoth (in editable mode) with:

# If using pdm
$ pdm install -d
# If using uv
$ uv pip install -e ".[dev,test]"

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

Using mammoth

There's a ton of functionality included in this repository, but it requires some background to use well. Please see the dedicated documentation. Some directories also have dedicated READMEs with details that are specific to particular projects - try browsing around in the projects/ and src/mammoth directories, and see what you find.

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. ↩