TreeLevelInstallation
The application first, the generators afterwards — and only if you want them. TreeLevel computes and generates events on its own; the external generators serve to dress them with a shower and hadronisation, or to compare.
One application, and nothing else to set up: TreeLevel computes and generates its events itself.
The application
TreeLevel is bought on the Mac App Store. It asks for macOS 14 Sonoma or later, and runs natively on Apple silicon as on Intel. The purchase is universal: the iPad version is included.
TreeLevel is bought on the App Store. It asks for iPadOS 17 or later. The purchase is universal: the Mac version is included.
On the iPad there is a single external generator: Pythia 8, compiled to WebAssembly and run inside the app, with nothing sent anywhere. It is not part of the app: you download it from the settings — see below. Herwig, Sherpa, WHIZARD, CalcHEP and the container stay on the Mac and the PC: they are separate programs, which the iPad does not allow to run. TreeLevel's own generation, at parton level, works everywhere.
TreeLevel is bought on the Microsoft Store. It asks for Windows 10 version 2004 or later, or Windows 11, and runs natively on x64 as on ARM64 — a Copilot+ PC gets the ARM64 version, not emulation.
Why the generators are separate
Pythia, Herwig, Sherpa, WHIZARD and CalcHEP are published under the GPL. Linking them into an application sold in a store would raise a licence problem, and distributing them together would raise another. So they live in a separate program, TreeLevel Tools, which you install yourself and which TreeLevel detects if it is there.
Nothing goes over the network: TreeLevel writes a job folder on your disk, the program reads it, computes, and writes the events next to it. If no generator is installed, TreeLevel keeps to its own parton level, which is enough for everything the Compute workspace does.
TreeLevel ToolsPythia 8 module
A single download, which brings the engine and four generators compiled for your machine: Pythia 8 and Herwig 7, which dress the events computed by TreeLevel — shower, hadronisation, decays —, together with Sherpa 3 and CalcHEP 3, which compute the process described by the diagram themselves. Nothing else to install.
A single download, which brings the engine and the Pythia 8 module compiled for your machine. The other generators go through the container, below.
Take the .dmg from the releases page and drag TreeLevel Tools into your Applications. The application is signed and notarised by Apple: macOS checks it silently and only asks, the first time, for confirmation to open a downloaded program.
Take the archive that matches your machine from the releases page — TreeLevelTools-version-x64.zip or -arm64.zip, about 45 MB — and unfold it into:
%LOCALAPPDATA%\ProgramsThat is the whole installation: no installer, nothing in the registry. TreeLevel looks there, then on the PATH. To remove it, delete the folder.
If you do not know which architecture you have: Settings › System › About, line System type. When in doubt, the x64 version works everywhere, under emulation on ARM.
No TreeLevel Tools on the iPad: Pythia 8 installs there as a module, from the settings (the gear in the toolbar), card Pythia 8 module. Pythia is free software under the GPL: the app does not contain it, it downloads it from the TreeLevel Tools releases page and checks every file against its SHA-256 fingerprint before installing it. Two parts:
| Pythia 8.318 | about 14 MB, button Download: parton shower, hadronisation, decays, and the Machine source |
|---|---|
| Hadron data | about 55 MB, optional, button Add: the parton densities, which say how a proton's energy is shared among its quarks and gluons; without them, a proton or pion beam is refused |
Either can be removed from the same card, button Remove.
What each package contains, its versions and the authors of the generators: TreeLevel Tools.
The container
An already-built image, which carries the five generators in one coherent environment. On a Mac it brings WHIZARD 3, the only one that cannot be shipped with TreeLevel Tools: it rewrites each process in Fortran and compiles it at run time.
Herwig, Sherpa, WHIZARD and CalcHEP demand a complete build chain and hours of building. Rather than impose them on you, they come in an already-built container image, the same for every system.
Install Docker Desktop, then, once only:
docker pull ghcr.io/gpasa/treelevel-tools:0.3.0docker pull ghcr.io/gpasa/treelevel-tools:latestTreeLevel Tools uses it as soon as it is present and Docker answers. The image weighs about two gigabytes deployed.
The container is not a silent stand-in. A natively installed generator and the same generator in the image carry neither the same versions nor the same settings, and therefore do not give exactly the same cross section. TreeLevel Tools never switches from one to the other without saying so: it is a checkbox, unticked out of the box.
Since 1.3, on the Mac, the box reads tout faire tourner dans l'image Docker (“run everything in the Docker image”): ticked, the image runs every job and the generators shipped with TreeLevel Tools stay silent; if Docker or the image is missing, nothing is offered rather than a quiet fallback to the native ones.
Docker Desktop asks for virtualisation. On a physical machine it is nearly always available; in a virtual machine, the host has to allow nested virtualisation, which not all of them do. Without it, the native Pythia module still works — which is precisely why it ships separately.
Checking that everything answers
Open the Generation workspace. The list of generators gives what answered, with the version numbers:
A generator that appears in the list has answered the call: it is not enough for it to be installed, it has to speak. A damaged module does not show up there.
Help › About TreeLevel gives the same numbers, and that is what to attach to a report: a physics result is worth the versions that produced it.
TreeLevel › About gives the same numbers, and that is what to attach to a report: a physics result is worth the versions that produced it.
It also gives the version of TreeLevel Tools, and its Copy versions button puts everything on the clipboard, ready to paste into a message.
On the iPad, the Pythia 8 module card in the settings shows what is installed — Pythia, the hadron data — and what each part weighs.
The module has its own number, separate from Pythia's: the card shows it — Pythia 8.318 (WebAssembly, module 0.5.0) —, and the bottom of the settings repeats it next to the version of the app, with the Copy versions button for a support message. When a newer version is published, the card offers Update; the app also takes it by itself at launch, when not on a cellular network, and checks every file before installing it.
Where the files live
| Your documents | wherever you save them, as .feyndiag |
|---|---|
| Settings | %LOCALAPPDATA%\TreeLevel |
| Engine jobs | next to treelevel-tools.exe, in MCJobs\ |
| A job's log | engine.log, in the job folder |
Past jobs are seen again in the Generation workspace, dated and with what they weigh: a sample of ten thousand showered events runs to a few hundred megabytes, and one accumulates a dozen without noticing. Load reads one back without running anything, Delete removes it.
| Your documents | wherever you save them, as .feyndiag |
|---|---|
| Engine jobs | in TreeLevel's sandbox, under ~/Library/Containers/org.pasahome.Feyn/Data/Library/Application Support/MCJobs |
Past jobs are seen again in the Generation workspace, dated and with what they weigh.
Your documents are wherever you save them, as .feyndiag: in the Files app, on the iPad or in iCloud Drive.
Pythia's jobs stay inside the app; Past jobs, in the Generation workspace, dates them, shows their size, reloads or deletes them.
Restore settings puts a job's settings back into the document — generator, number of events, seed, and its machine if it had one — without reading its events: all that is left is to run the generation again.
When something goes wrong
The list offers nothing but “TreeLevel — parton level”
TreeLevel Tools was not found, or did not answer. Check the location above, then Check again in the Generation workspace. The Point to the location… button lets you designate it by hand.
On the iPad, the Pythia module is not installed, or was removed: settings (the gear), card Pythia 8 module, Download. The other generators do not exist on the iPad.
The job fails straight away
The message carries the reason, and the See the log… button opens what the generator wrote, scrolled to its end — that is where the cause is. The most frequent refusals are beams that cannot do what is asked of them: two leptons carry no partons, an electron and a proton do not annihilate.
On the iPad, a proton or pion beam needs the Hadron data: without them the job is refused at once, and the message says so. They are added from the same card in the settings.
The formulas do not appear
The rendering goes through a web view. Close and reopen the document; if it persists, report it with the version of the system.
For the rest, the Support page answers the most frequent questions and says how to report a problem.