gtracr - A GPU-accelerated Tracking Simulation for Cosmic Ray Trajectories

Introduction

This package is a high-performance 3-D tracking simulation of cosmic ray trajectories for different locations around the globe. The code can simulate cosmic ray trajectories that are detected at a certain altitude from some detector location, be it at Super-K in Kamioka, Japan or IceCube at the South Pole. The code utilizes the International Geomagnetic Reference Field (IGRF) model to represent the main magnetic field from Earth's outer core.

The cosmic ray trajectories are described by a set of coupled ordinary differential equations based on the Lorentz force (F = q(v x B)). The equations are expressed in spherical coordinates, the canonical coordinate system for performing calculations with spherical objects (i.e. the Earth).

Since the analytical expression of the coordinate and momentum vector cannot be obtained, the evaluation of the trajectories are performed numerically by a 4th-order Runge-Kutta algorithm. This is considered one of the most simplest yet accurate methods used for numerical integration of all kinds. There are more accurate techniques that can be implemented to improve the accuracy of the results, but with a truncation error of O(h^5), we can consider this algorithm already pretty good.

Installation

The package can be installed by using pip:

pip install gtracr

This allows module-level usage of the package.

Alternative methods are available to download this package.

The first method is to use setup.py with python:

python setup.py install --user

Note: The --user flag is required for installing the package in this manner.

The lastest (unstable) version can be obtained by cloning the repository from the master branch in GitHub.

Dependencies

  • Python 3 and above
  • NumPy
  • SciPy
  • datetime (for obtaining the current date)
  • tqdm

All such dependencies will be installed with the package.

Optional requirements

These packages are required to observe plots and test different trajectory cases:

  • matplotlib, plotly for plots
  • pytest, pytest-benchmark for testing

Quickstart

Evaluating a single trajectory

Here we present a simple example that can be run in a Python script:

from gtracr.trajectory import Trajectory

# initialize a cosmic ray trajectory that arrives at the horizon
# from the West at 100km above sea level at the Kamioka site with
# a rigidity of 30 GV:

traj = Trajectory(
        location_name="Kamioka",
        zenith_angle=90.,
        azimuth_angle=90.,
        particle_altitude=100.,
        rigidity=30.
    )

# evaluate the trajectory and get the trajectory data
trajectory_data = traj.get_trajectory(get_data=True)

# plot the results
# below module requires matplotlib and plotly to run
from gtracr.plotting import plot_3dtraj

plot_3dtraj(
        trajectory_data,
        file_name = "plot.html",
        plot_path="../gtracr_plots"
    )

This will return a PlotLy interactive plot that will display on the default web browser, and saves the html for future access.