Install with Built-in Installer

The built-in installer sets up Prometheus and all its dependencies automatically. It works on Linux, macOS, and WSL2 — if you're on Windows (without WSL2), use containers instead.

Platform Status
Linux x86-64 Supported
Linux aarch64 Supported
macOS Supported
Windows Use containers
WSL2 Supported

Requirements

Caution

For the built-in installer to work, you will need 4-5GB of free space on your machine. This is due to the size of external dependencies necessary to run Prometheus.

Before you start, make sure you have:

  • Python 3.11 or higher
  • A POSIX-compatible shell, such as bash or zsh
  • curl - used by the installer to download dependencies
  • Homebrew - package manager, only needed for macOS

Installation Steps

1. Clone and Navigate into the Prometheus Repository

git clone https://github.com/Harvard-Neutrino/prometheus.git && cd prometheus

2. Run the Installer

bash install.sh

This sets up a water-based simulation environment, which is the recommended starting point. If you also need ice-based simulations, run:

bash install.sh --with-ppc

What Gets Installed

The installer takes care of everything automatically:

  • Creates an isolated environment in the .prometheus_env directory.
  • Installs all Python dependencies.
  • Builds the required scientific libraries:
  • PROPOSAL — lepton propagation
  • LeptonInjector — neutrino interaction generation
  • Optionally builds ppc — photon propagation for ice simulations (when run with --with-ppc).

Activate the Environment

Once the installation is done, activate the environment:

source scripts/activate.sh .prometheus_env

Note

You'll need to activate the environment in every new terminal session. To avoid this, add the command above to your shell profile (~/.bashrc or ~/.zshrc).

Verify the Installation

With the environment active, run an example:

python examples/01_basic_water.py

If everything went well, you should see simulation output without errors. If you run into problems, check that the environment is active first.

Troubleshooting

  • Build failures (PROPOSAL / LeptonInjector): Install with Containers instead.
  • Missing optional Python packages: Some examples require uproot (for reading ROOT files) or pandas (for data manipulation). If you see an ImportError for either, install them with pip install uproot or pip install pandas.

Getting Help

If you're having issues installing Prometheus, feel free to create a discussion on GitHub and we'll get back to you as soon as we can.