TreeLevelTreeLevel Tools
TreeLevel's event generators, on your machine: TreeLevel Tools for the Mac and the PC, the iPad's Pythia 8 module, the Docker image — what each one contains, how to install it, and to whom we owe the physics.
TreeLevel writes a job into a local folder; TreeLevel Tools hands it to Pythia 8, Herwig 7, Sherpa 3, WHIZARD 3 or CalcHEP 3 — shower and hadronisation of its events, or whole collisions of a machine — and writes the result back in HepMC3, which TreeLevel reads. Nothing goes over the network, no account, no service. On the iPad, Pythia 8 compiled to WebAssembly plays the same part.
These tools are distributed separately because the generators are under the GPL: TreeLevel Tools is under the GPL v3, and TreeLevel contains none of their code. Their sources are on GitHub.
Downloads
| system | download | what it contains |
|---|---|---|
| macOS 13 or later, Apple Silicon and Intel | TreeLevelTools-0.5.0.dmg | Pythia 8, Herwig 7, Sherpa 3 and CalcHEP 3, ready to run |
| Windows 10 and 11 | x64 · ARM64 | Pythia 8; the others through the Docker image |
| iPad | from TreeLevel's settings | Pythia 8 in WebAssembly |
| Docker, any system | docker pull ghcr.io/gpasa/treelevel-tools:latest | the five generators, WHIZARD 3 included |
All the versions and their notes: the releases page. Step-by-step installation, and what TreeLevel does with it: Installation.
TreeLevel Tools for Mac
The GPL tools that TreeLevel cannot contain, on your machine — nothing leaves it. TreeLevel is sandboxed and launches no program; this package is what is allowed to run them.
New in 0.5.0
- Pythia 8 places the particles in the interaction zone when TreeLevel 1.4 asks for it (the positions in the interaction zone box): where each hadron is born, to the femtometre, the colour flow and the status of the partons, and a single offset of the luminous region for the whole event. TreeLevel shows it at the femtometre, in the cross-sections and in 3D.
- TreeLevel 1.3 asks for none of this and receives the same events as with 0.4.0; same generators, same versions.
- Tried on an Apple Silicon Mac and on an Intel iMac: each bundled generator runs a real job.
Install
For Apple Silicon and Intel Macs, macOS 13 or later. Drag TreeLevel Tools.app into /Applications and launch it once. Four generators are already inside, nothing else to install:
- Pythia 8 and Herwig 7 dress TreeLevel's events between two leptons: shower, hadronisation, decays. Pythia 8 also drives the Machine source: two beams, an energy, and everything the collision produces.
- Sherpa 3 and CalcHEP 3 compute the process described by the diagram themselves.
TreeLevel then offers them in the Generation workspace. The cards of all the generators are written by the same C++ engine as inside the Docker image: the same job gives the same card on the Mac and on Linux.
WHIZARD 3 is not included: it compiles each process with gfortran, which neither macOS nor Xcode provides. Two ways to have it, to tick in the TreeLevel Tools window: the Docker image, which carries the five tools — when ticked, it runs all the jobs, and the generators bundled here stay silent —, or your own installation (MacPorts, Homebrew), if you have one. Neither is used by default: out of the box, only the generators bundled here are offered, so that the same document gives the same result on two machines.
Signed and notarised by Apple. Checksums in SHA256SUMS.txt, next to each archive.
TreeLevel Tools for Windows
The engine and the Pythia 8 module compiled for your machine. Take the archive for your architecture — arm64 for a Copilot+ PC or an ARM tablet, x64 everywhere else; when in doubt, the x64 one also works on ARM, under emulation — and unfold it into %LOCALAPPDATA%\Programs. No installer, nothing in the registry. To update: close TreeLevel, then unfold the new archive in the same place, replacing the files.
Herwig, Sherpa, WHIZARD and CalcHEP go through the Docker image, which requires Docker Desktop.
The iPad's Pythia module
On the iPad, Pythia 8.318 compiled to WebAssembly is installed from TreeLevel's settings, card Pythia 8 module. TreeLevel 1.3 downloads it from the page ipad-pythia-8.318 and checks every file against the fingerprint it knows for it; it runs it in a web view, without sending anything anywhere.
On the iPad, Pythia 8.318 compiled to WebAssembly, with the common driver of TreeLevel Tools, installs from TreeLevel's settings, card Pythia 8 module. The app downloads it from the module's page, which always keeps the same name: TreeLevel 1.4 and later takes the latest version from it, reads its number in module.json and shows it in its settings, offers the update when a newer version is published, and checks every file against the fingerprint that module.json gives for it. It runs the module in a web view, without sending anything anywhere.
The module has its own number, separate from Pythia's — today, module 0.5.0. What it can do is written in module.json: “spacetime”, for instance, places partons and hadrons in the interaction zone, which TreeLevel shows at the femtometre.
| file | role |
|---|---|
module.json | version of the module and of Pythia, what it can do, the fingerprint of every file |
treelevel-pythia-web.wasm, .js | Pythia 8.318 and the driver, in WebAssembly |
runner.js | runs a TreeLevel job: plan, parts, merge |
leptons.pack | Pythia data (xmldoc, tunes, setups) — lepton beams |
pdfdata.pack | parton densities — hadron beams, optional |
pythia8318-sources.tgz | the sources of Pythia 8.318, as published on pythia.org |
COPYING.pythia8 | the Pythia licence (GPL v2 or later) |
TreeLevel 1.3 downloads its module from ipad-pythia-8.318, whose fingerprints it fixes: that page does not change. The module remains a program separate from TreeLevel: the app hands it a job and reads back the result.
The Docker image
The image carries the five generators — Pythia 8, Herwig 7, Sherpa 3, WHIZARD 3 and CalcHEP 3 — and the same engine as TreeLevel Tools. It is built for Intel and AMD (linux/amd64) and ARM (linux/arm64) processors, and runs under Docker Desktop on the Mac as on Windows. Once Docker is installed:
docker pull ghcr.io/gpasa/treelevel-tools:latestTreeLevel Tools checks whether the image is already there; it never pulls it by itself: a gigabyte is not downloaded behind someone's back. When it is present, the generators that no module offers appear, followed by “(conteneur)”, and a job that asks for them is run in the image, with its job folder mounted as it is. The installed modules take precedence: they run without a virtual machine and do not require Docker to be started. On the Mac, a box in the TreeLevel Tools window hands every job to the image.
The same command updates the image. Images from before 0.5.0 do not place the particles in the interaction zone: TreeLevel 1.4's box only appears with image 0.5.0 or later. Each new image still runs the jobs of earlier versions of TreeLevel.
Links and credits
TreeLevel Tools only drives these programs: it hands them a job and reads back what they return. The physics — showers, hadronisation, matrix elements, integration — is entirely theirs, the fruit of decades of work by their authors. They are distributed as they are, under their own licences, with their sources. When you publish a result obtained with one of them, cite it: that is what its authors ask, and it is what allows them to carry on.
The generators
| program | authors | licence | to cite |
|---|---|---|---|
| Pythia 8 | © Torbjörn Sjöstrand and the Pythia collaboration | GPL v2 or later | C. Bierlich et al., “A comprehensive guide to the physics and usage of PYTHIA 8.3”, SciPost Phys. Codebases 8 (2022), arXiv:2203.11601 |
| Herwig 7 | © the Herwig collaboration | GPL v3 | J. Bellm et al., “Herwig 7.0 / Herwig++ 3.0 release note”, Eur. Phys. J. C 76 (2016) 196, arXiv:1512.01178 |
| Sherpa 3 | © the Sherpa authors (SHERPA-MC Authors) | GPL v3 or later | E. Bothmann et al., “Event generation with Sherpa 3”, arXiv:2410.22148 |
| WHIZARD 3 | © 1999–2025 Wolfgang Kilian, Thorsten Ohl, Jürgen Reuter and their contributors | GPL v2 or later | W. Kilian, T. Ohl, J. Reuter, “WHIZARD: Simulating Multi-Particle Processes at LHC and ILC”, Eur. Phys. J. C 71 (2011) 1742, arXiv:0708.4233 |
| CalcHEP 3 | Alexander Pukhov, Alexander Belyaev, Neil Christensen, with code from the CompHEP group | GPL v3 | A. Belyaev, N. Christensen, A. Pukhov, “CalcHEP 3.4 for collider physics within and beyond the Standard Model”, Comput. Phys. Commun. 184 (2013) 1729, arXiv:1207.6082 |
What they bundle
| component | in | authors | to cite |
|---|---|---|---|
| O'Mega (optimised amplitudes) | WHIZARD | Mauro Moretti, Thorsten Ohl, Jürgen Reuter | M. Moretti, T. Ohl, J. Reuter, “O'Mega: An Optimizing Matrix Element Generator”, arXiv:hep-ph/0102195 |
| CompHEP (from which CalcHEP descends) | CalcHEP | E. Boos, V. Bunichev, M. Dubinin, L. Dudko, V. Ilyin, A. Kryukov, V. Edneral, V. Savrin, A. Semenov, A. Sherstnev | E. Boos et al., “CompHEP 4.4”, Nucl. Instrum. Meth. A 534 (2004) 250, arXiv:hep-ph/0403113 |
| StdHEP / mcfio (event formats) | WHIZARD | Fermilab | — |
The libraries
| library | authors | licence | to cite |
|---|---|---|---|
| ThePEG (the foundation of Herwig) | © the Herwig collaboration | GPL v3 | see Herwig 7 above |
| LHAPDF 6 (parton densities) | Andy Buckley, Mike Whalley et al. | GPL v3 | A. Buckley et al., “LHAPDF6: parton density access in the LHC precision era”, Eur. Phys. J. C 75 (2015) 132, arXiv:1412.7420 |
| HepMC3 (event format) | the HepMC collaboration | GPL v3 | A. Buckley et al., “The HepMC3 event record library for Monte Carlo event generators”, Comput. Phys. Commun. 260 (2021) 107310, arXiv:1912.08005 |
| FastJet (jet algorithms) | Matteo Cacciari, Gavin P. Salam, Grégory Soyez | GPL v2 or later | M. Cacciari, G. P. Salam, G. Soyez, “FastJet user manual”, Eur. Phys. J. C 72 (2012) 1896, arXiv:1111.6097 |
| GSL (numerical computing) | the GNU Scientific Library and its contributors | GPL v3 | M. Galassi et al., GNU Scientific Library Reference Manual |
The formats
| format | to cite |
|---|---|
| Les Houches (parton-level events, between TreeLevel and the generators) | J. Alwall et al., “A standard format for Les Houches Event Files”, Comput. Phys. Commun. 176 (2007) 300, arXiv:hep-ph/0609017 |
| HepMC3 (showered events, on the way back) | see HepMC3 above |
The tools that build and run them
Docker (the image), MacPorts and Homebrew (the dependencies on the Mac), GCC and gfortran (Herwig, Sherpa, WHIZARD, CalcHEP), OCaml (O'Mega), Emscripten (Pythia in WebAssembly for the iPad), CMake and Microsoft Visual C++ (Pythia and the engine on Windows).
Versions shipped with TreeLevel Tools 0.5.0 and image 0.5.0: Pythia 8.318, Herwig 7.3.0 (ThePEG 2.3.0), Sherpa 3.0.5, WHIZARD 3.1.6 (image only), CalcHEP 3.9.2, LHAPDF 6.5.3, HepMC3 3.2.5, FastJet 3.4. The iPad module carries Pythia 8.318 alone.