Prometheus

Welcome to Prometheus, an open-source neutrino telescope simulation.

https://github.com/Harvard-Neutrino/prometheus

Introduction

Prometheus is a Python-based package for simulating neutrino telescopes. It balances ease of use with performance and supports simulations with arbitrary detector geometries deployed in ice or water.

Prometheus simulates neutrino interactions in the volume surrounding the detector, computes the light yield of hadronic showers and the outgoing leptons, propagates photons in the medium, and records their arrival times and positions in user-defined regions. Events are then serialized to Parquet files, a compact and interoperable format that enables efficient access for downstream analysis.

For a detailed description of the package, see arXiv:2304.14526.

Authors

1. Jeffrey Lazar
2. Stephan Meighen-Berger
3. Christian Haack
4. David Kim
5. Santiago Giner
6. Carlos Argüelles Delgado

Terms of Use

Prometheus is open-source. You are free to copy, modify, and distribute it with attribution under the terms of the GNU Lesser General Public License. See the LICENSE file for details.

Getting Started

To work with Prometheus, you will need:

• Python 3.11 or higher
• pip for Python package management. It usually comes with installing Python, so you should already have it.

Additional prerequisites depend on your installation method and are detailed in the Installation section below.

Installation

There are two options to install Prometheus:

• Download and compile dependencies from source/PyPI
• Use provided Docker or Singularity containers with prebuilt dependencies

Install from Source

If you have Python and pip installed, this would be the most straightforward installation method.

To start, clone this repository onto your machine:

git clone git@github.com:Harvard-Neutrino/prometheus.git

Prerequisites

To work with Prometheus, you need to install the following packages:

1. LeptonInjector - Required for selecting neutrino interaction quantities. Installation instructions are available in the project repository.

2. PROPOSAL - Used to propagate charged leptons resulting from neutrino interactions. PROPOSAL installation is included in the Prometheus setup script, but some users reported issues on certain operating systems. If needed, you can install it separately, following its installation guide.

3. Photon Propagation Code (ppc) - Required for ice-based detector simulations. Two versions are available:

   • CPU version
   • GPU/CUDA version

   Both of these use a modified version of the official ppc code. Prometheus-specific compilation instructions are available in the ppc executables README.

4. LeptonWeighter (optional) - Required for event weighting. Installation instructions are available in the project repository.

Compilation

Important

The Prometheus setup script is currently under review to ensure its steps are up to date. We are working to make it available as soon as possible.

After installing the prerequisites, run the setup script from the Prometheus base directory:

python3 python -m pip setup.py install

This will install all remaining dependencies needed to run simulations.

Tip

If you encounter issues installing PROPOSAL through the setup script, install it separately before running the script. See PROPOSAL's advanced installation guide for instructions.

Install with Containers

If you need to run simulations on a computing cluster or the source installation doesn't work for you, Docker and Singularity images with all dependencies prebuilt are available in this public Google drive folder.

Warning

The Docker and Singularity images we provide are not currently compatible with ARM-based system architectures, which causes issues when running them on computers with Mac M-series chips. If you are a Mac user, consider installing Prometheus from source.

Using Docker

If you need help getting started with Docker, see the Docker documentation. Here is the outline of the steps you need to take to set things up:

1. Load the image

Download the latest version .tar.gz file from the Google Drive folder, navigate to the directory where you downloaded the file, and run:

docker load < prometheus_v_<VERSION>.tar.gz

Replace <VERSION> with the actual version number (e.g., 1_0_2). This will load the image into Docker. To learn more about loading images and available options, refer to the Docker documentation.

2. Run the container and launch a shell:

docker run -it prometheus_v_<VERSION>:latest sh

For more container running options, refer to the Docker containers documentation.

GPU Support with Docker

For GPU-accelerated simulations, you will need to build a custom Docker image from the GPU Dockerfile provided in the repository. After building and starting the image, compile ppc with GPU support by running make gpu in the PPC_CUDA directory within the container.

Note

You may need to modify the architecture version in the ppc makefile to match your GPU hardware.

Using Singularity

If you need help getting started with Singularity, see the Singularity documentation.

Singularity is particularly useful for running simulations on computing clusters. To use the Singularity container:

1. Clone this repository

The Singularity setup is still under construction, and there may be issues running software using only the files in the container. To avoid these issues, clone the repository onto your machine and navigate into the project directory:

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

2. Download the container image

Download the latest version .sif file (currently v1.0.2) from the Google Drive folder

Note

We use Boost libraries for file structure management. Some systems with older kernels may not be compatible with newer Boost versions. If you encounter compatibility issues, use the .sif files with the "old" keyword: prometheus_old_<VERSION>.sif.

3. Launch a Singularity shell within the container

singularity shell <FILENAME>.sif

Replace <FILENAME> with the actual name of your downloaded .sif file.

Source the Environment File

Tip

The remaining setup steps and running the software should all be done within your container shell.

Before running simulations, you may need to source the environment file to ensure all dependencies load correctly:

source /opt/.bashrc

Once this is done, still in your container shell, navigate into the Prometheus directory:

cd /home/myuser/prometheus

After that, you should be able to start running simulation scripts.

Running Simulations

The examples directory contains example scripts for running simulations.

As a first-time user, you will need example_ppc.py for ice-based simulations and example_olympus.py for water-based ones. Other scripts cover more specific use case scenarios.

To execute a script, run:

python3 python -m pip <SCRIPT_NAME>.py

Replace <SCRIPT_NAME> with the name of your simulation script.

To learn more about how Prometheus scripts work, refer to the API documentation in the docs directory.

Citation

Please cite Prometheus using this entry:

@article{Lazar:2023rol,
    author = {Lazar, Jeffrey and Meighen-Berger, Stephan and Haack, Christian and Kim, David and Giner, Santiago and Arg\"uelles, Carlos A.},
    title = "{Prometheus: An Open-Source Neutrino Telescope Simulation}",
    eprint = "2304.14526",
    archivePrefix = "arXiv",
    primaryClass = "hep-ex",
    month = "4",
    year = "2023"
}

Please also consider citing the packages that Prometheus uses internally: LeptonInjector, PROPOSAL, ppc, and LeptonWeighter with the following citations:

LeptonInjector and LeptonWeighter

@article{IceCube:2020tcq,
    author = "Abbasi, R. and others",
    collaboration = "IceCube",
    title = "{LeptonInjector and LeptonWeighter: A neutrino event generator and weighter for neutrino observatories}",
    eprint = "2012.10449",
    archivePrefix = "arXiv",
    primaryClass = "physics.comp-ph",
    doi = "10.1016/j.cpc.2021.108018",
    journal = "Comput. Phys. Commun.",
    volume = "266",
    pages = "108018",
    year = "2021"
}

PROPOSAL

@article{koehne2013proposal,
    title     = {PROPOSAL: A tool for propagation of charged leptons},
    author    = {Koehne, Jan-Hendrik and
                Frantzen, Katharina and
                Schmitz, Martin and
                Fuchs, Tomasz and
                Rhode, Wolfgang and
                Chirkin, Dmitry and
                Tjus, J Becker},
    journal   = {Computer Physics Communications},
    volume    = {184},
    number    = {9},
    pages     = {2070--2090},
    year      = {2013},
    doi       = {10.1016/j.cpc.2013.04.001}
}

ppc

@misc{chirkin2022kpl,
    author = {D. Chirkin},
    title = {ppc},
    year = {2022},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/icecube/ppc}},
    commit = {30ea4ada13fbcf996c58a3eb3f0b1358be716fc8}
}

API Documentation

Detailed API documentation on Prometheus' modules and classes is available in the docs directory.

Contributing

Prometheus is open-source, and we always appreciate contributions that can make it better.

Read our contribution guidelines to learn more about contributing to Prometheus.

Getting Help

If you encounter any installation or setup issues, feel free to create a discussion and we will address it as soon as we can.

If you found a bug in this software or want to suggest a change, feel free to open an issue.

More information on opening issues and getting help is available in our contribution guidelines.