TURTLE-perfs

Performance tests of the TURTLE library.

This repository contains a collection of utilities and scripts for testing the performances of the TURTLE library when navigating through a topography represented by a Digital Elevation Model (DEM). The detailed results of these tests can be found in arXiv:1904.03435. In addition to the optimistic algorithm included in TURTLE various alternative ray tracing algorithms are used for purpose of comparison. Based on these ray tracers four geometry wrappers of topography data have been implemented. The corresponding source files are:

1. src/bvh.cpp: the default BVH accelerated geometry using CGAL.

2. src/embree.c: an alternative BVH accelerated geometry using Embree.

   This is 10 times faster than the CGAL version but much less accurate as well. It uses two times less memory per topography node.

3. src/mesh.cpp: a polyhedral mesh using CGAL for geometry operations.

4. src/opti.c: the optimistic algorithm using a turtle_stepper.

The generic ray tracing algorithm is implemented in src/tracer.c. The PUMAS based simulation test is located in src/simulator.c. Note that PUMAS is patched in order to force all particles to follow a straight trajectory, even though detailed scattering is simulated.

Installation

The test suite was designed for Linux. There is no binary distribution. It must be built and installed from the source using CMake 3 or later. Most external dependencies will be automatically downloaded and installed as well. Yet the following executables and libraries are assumed to be already installed on your system:

• libboost-system-dev and libboost-thread-dev for CGAL.
• libpng-dev for topography maps with TURTLE.
• wget for downloading the Topography data. You can also do this manually from the releases page.

Installation can be done as following:

git clone https://github.com/niess/turtle-perfs.git && cd turtle-perfs
mkdir build && cd build
cmake .. && make install

By default the installation is done to the source directory with a Release build. Building the Geant4 test suite is optional with the USE_GEANT CMake flag. It requires an existing installation of Geant4. This can be done as:

source /path/to/geant4/bin/geant4.sh
cmake .. -DUSE_GEANT=ON && make install

Usage

The test environment can be initialised by sourcing the provided setup.sh files, as:

source setup.sh

The tests scripts are located under the scripts folder. Below is a listing of the available scripts as well as examples of usage illustrating their Command Line Interface (CLI). Extra informations can be obtained with the -h option of the CLI.

---

• trace.lua: do a ray tracing from a given point of view and along a given line of sight. The three algorithms are tested (BVH, polyhedral mesh & optimistic). For example:

  trace.lua CDC 26 10 --period=10 --embree

  does a ray tracing test starting from the CDC view and going along an azimuth of 26 deg and an elevation of 10 deg, with a map down-sampled by a factor of 10 (in x and y axis) and with Embree's BVH algorithm (default is CGAL's BVH).

---

• scan-trace.lua: do a rock depth scan from the given point of view and with the given algorithm. The down-sampling period of the DEM must be provided as well. For example:

  scan-trace.lua ULS opti 1

  does a rock depth scan from the Ulastai view point using the optimistic algorithm and the full DEM.

---

• simulate.lua: run a muography simulation from a given point of view and along a given line of sight. The three ray tracing algorithms are tested (BVH, polyhedral mesh & optimistic). For example:

  simulate.lua ULS 90 5 --period=100 --precompute

  does the simulation test with a map down-sampled by a factor of 100 along x and y axes and with a pre-computed geometry.

---

• scan-simulate.lua: run a muography scan from the given point of view and with the given ray tracing algorithm. The down-sampling period of the DEM must be provided as well. For example:

  scan-simulate.lua CDC BVH 30 --embree

  does the simulation from the Ulastai view point using Embree's rau tracing and a DEM down-sampled by 30 along x and y axes.

---

• geant4.lua: run a Geant4 simulation from a given point of view and along a given line of sight. The default simulation generates a 10 TeV Geantino primary and uses a G4Turtle geometry. This can be modified by command line options. For example:

  geant4.lua CDC 26 10 --particle=MuonMinus --tessellate

  generates a 10 TeV primary μ and uses a G4TessellatedSolid geometry.

---

• scan-geant4.lua: run a Geant4 scan from the given point of view and with the given down-sampling. For example:

  scan-geant4.lua CDC 1

  runs a Geantino scan with a G4Turtle geometry. As previously, the primary and the geometry can be overridden by command line options.

License

The tests procedures are unlicensed, i.e. freely available to the public domain. They can be copied, modified, etc. without any notice. The external dependencies have their own specific licences.