MetalOpticalPhoton

A TOPAS/Geant4 optical-photon simulation engine that keeps Geant4's optical physics and offloads only the photon propagation to the Apple Metal GPU.

This repository holds the GPU optical-photon extension for TOPAS, the OpenTOPAS source patch it needs, a user manual, and the complete benchmark suite of the paper Hardware ray-traced optical-photon Monte Carlo for radiation detector simulation: a TOPAS extension on Apple Silicon: the TOPAS input decks, the runners, the deposited results and the scripts that compute the tables and figures of the paper from them.

Overview

In a Monte Carlo simulation of an optical detector, such as a scintillator viewed through mirrors and lenses by a camera, the optical photons decide the result. Geant4, and TOPAS on top of it, models their physics process by process: Fresnel reflection and Snell refraction, Rayleigh and Mie scattering, wavelength shifting (WLS) and surface reflection. One charged particle can make tens to hundreds of thousands of photons, and Geant4 tracks each of them as a separate G4Track, so photon tracking (g4optical) dominates the CPU time of a realistic detector setup.

Each photon propagates independently of every other, and the work reduces to ray tracing through the geometry, which is what a GPU, and Metal ray tracing on Apple Silicon in particular, does well. The extension therefore splits the roles. Geant4 keeps charged-particle transport and energy deposition on the CPU; at each step that makes optical photons it records a genstep (where, how many and with what distribution) instead of creating the photons. The Metal kernels expand the gensteps into photons and propagate them through the geometry, triangle meshes through the hardware BVH and registered solids through analytic intersection, applying Geant4's boundary and bulk physics up to the scorer.

The optical models follow Geant4 process by process; the places where the GPU approximates Geant4 are listed in the paper (Table 4), and the manual states the limits that a user must respect. The build also patches two OpenTOPAS defects that affect optical accuracy on the CPU as well.

Key features

• Optical physics as in Geant4: Fresnel/Snell, total internal reflection, Rayleigh and Mie scattering, WLS, the UNIFIED surface model and per-photon polarisation.
• Analytic geometry: boxes, spheres, cylinders, tori and polyhedra are intersected analytically instead of through meshes, which removes the inscribed-polygon bias of curved solids.
• OpenTOPAS patches: two defects of OpenTOPAS 4.2.3 that affect optical accuracy (a stuck parallel-world envelope and a primary-polarisation typo) are fixed at build time.
• GPU beam mode: an optical-photon beam source generated on the GPU, for very large photon counts (10⁹ and more per run).
• Drop-in use: the extension is switched on in the TOPAS parameter file; no user C++ code.

Repository layout

Path	Contents
src/, shaders/, include/	the Metal GPU engine: host code, kernels, shared data types
topas_extension/	the TOPAS extension: physics module, GPU scorers, photon-list source
topas_patches/, topas_patches_summary.md	the OpenTOPAS 4.2.3 source patch and what it fixes
build_topas_gpu.sh, INSTALL.md	build script and installation guide
architecture.md	system architecture: components and the CPU–GPU flow
manual/	user manual: parameters, scorers, materials, phase space, statistics, figures
benchmark/	the benchmarks of the paper with their decks, runners, deposited results and analysis scripts
data/	supporting records of the deposited results: run logs and provenance
FIXLOG.md	summary of the corrections made to the engine, the decks and the analysis during the revision
LICENSE, NOTICE	licence and third-party notices
SHA256SUMS.txt	checksums of the files at this level and in the engine folders; benchmark/, data/ and manual/ carry their own

Quick start

OpenTOPAS, Geant4 and the toolchain are public software that you install yourself (INSTALL.md §1).

Requirements

• macOS on Apple Silicon (M series; a GPU with Metal ray tracing)
• Xcode with the Metal toolchain (the Command Line Tools alone do not include the Metal compiler; INSTALL.md §1-1)
• Homebrew cmake, gdcm and qt (Qt6)
• OpenTOPAS 4.2.3 source tree (the build patches it; other versions are refused unless ALLOW_UNTESTED_TOPAS=1 is set)
• Geant4 11.3.2 or later, built and installed as for OpenTOPAS (see OpenTOPAS_quickStart_MacOS.md in the OpenTOPAS source), with its data sets
• For the analysis and figure scripts: Python 3 with NumPy, SciPy and Matplotlib (pandas for some scripts of benchmark/04_stage_separation/ and benchmark/11_sensor_phase_space/)

Build

From this folder:

./build_topas_gpu.sh full       # patch OpenTOPAS 4.2.3 + build shaders, engine dylib, TOPAS + install

The script finds Geant4, the OpenTOPAS source and GDCM by itself; point it at other locations with environment variables, for example

Geant4_DIR=/path/to/geant4-install TOPAS_SRC=/path/to/OpenTOPAS ./build_topas_gpu.sh full

The OpenTOPAS source patch (topas_patches/) is applied automatically. If it does not apply cleanly, or the source is not OpenTOPAS 4.2.3, the build stops before anything is compiled, so an unpatched build is never produced.

Where the binary ends up

The build installs OpenTOPAS with the GPU extension into TOPAS_INSTALL, by default <OpenTOPAS source>-install-gpu next to the source tree, and writes the run wrapper <TOPAS_INSTALL>/bin/topas-gpu, which sets the Geant4 data and library paths and starts the patched topas. The script prints the exact path at the end.

Run

export TOPAS=<TOPAS_INSTALL>/bin/topas-gpu      # used by the benchmark runners
export PATH="<TOPAS_INSTALL>/bin:$PATH"         # optional: lets you type topas-gpu directly
topas-gpu your_sim.txt

Switch the GPU optical module on in the TOPAS parameter file:

s:Ph/ListName = "Optical"
sv:Ph/Optical/Modules = 2 "g4em-standard_opt4" "gpuoptical"

The parameters of the extension are described in manual/; every benchmark folder holds working parameter files.

Reproducing the paper

All tables and figures of the paper are computed from files in benchmark/, whose README maps every folder to its benchmark, figure and table.

From the deposited results (no TOPAS needed):

cd benchmark
python3 tables/table2_stats.py       # Table 2 and the list of all its endpoints
python3 tables/gen_table3.py         # Table 3

Each figure is drawn by a script in its benchmark folder (for example python3 04_stage_separation/plot.py from benchmark/ for Figure 3); Figure 2 is joined by benchmark/figures/make_combined_b2b3.py. The folder READMEs give the exact commands.

Running the simulations again: every benchmark folder has runners (run_gpu.sh, run_cpu.sh, or the runner its README names) that find the binary through TOPAS or PATH. The deposited results live in the same results/ folders, so work on a copy of benchmark/ when rerunning. benchmark/run_smoke_test.sh checks an installation by running every benchmark at a reduced event count in a temporary copy.

Documentation

Document	Contents
INSTALL.md	prerequisites, build script, manual build, version requirements
manual/	how to use the extension from a TOPAS parameter file
architecture.md	system architecture: components and the CPU–GPU flow
topas_patches_summary.md	the OpenTOPAS patches and why they are needed
benchmark/README.md	the benchmarks, the runners and the reproduction of Tables 2–3 and Figures 1–8
data/README.md	what the supporting records are and which results they belong to
FIXLOG.md	summary of the corrections made during the revision

Verify the checksums of a folder with shasum -a 256 -c SHA256SUMS.txt inside it.

Citation

If you use this software or the benchmark data, please cite the paper: Y. Goh, U.-S. Lee, G. M. Back, J. Kwak, J. Jung and S. Y. Song, Hardware ray-traced optical-photon Monte Carlo for radiation detector simulation: a TOPAS extension on Apple Silicon (the full reference will be added on publication), together with Geant4 and TOPAS/OpenTOPAS.

License

MetalOpticalPhoton is under the MIT License (LICENSE). As a TOPAS extension it is built with OpenTOPAS (MIT) and Geant4 (Geant4 Software License), which are not included here; the third-party notices are collected in NOTICE. Keep the NOTICE statements, in particular the Geant4 Collaboration acknowledgement, when redistributing, and cite Geant4 and TOPAS/OpenTOPAS when publishing results obtained with this software.