Introduction

VecGeom is a geometry modeller library with hit-detection features as needed by particle detector simulation at the LHC and beyond. It was incubated by a Geant-R&D initiative and the motivation to combine the code of Geant4 and ROOT/TGeo into a single, better maintainable piece of software within the EU-AIDA program. As such it is close in scope to TGeo and Geant4 geometry modellers. Its main features are:

• Build a hierarchic detector geometry out of simple primitives and use it on the CPU or GPU(CUDA)
• Calculate distances and other geometrical information
• Collision detection and navigation in complex scenes
• SIMD support in various flavours:
  • True vector interfaces to primitives with SIMD acceleration when benefical
  • SIMD acceleration of navigation through the use of special voxelization or bounding box hierarchies
• Runtime specialization of objects to improve execution speed via a factory mechanism and use of C++ templates
• VecGeom also compiles under CUDA
• Few generic kernels serve many instanteations of various simple or vectored interfaces or the CUDA version.

Building/Installing VecGeom

Requirements

• CMake 3.16 or newer for configuration, plus a suitable build tool such as GNU make or Ninja
• C++ compiler supporting a minimum ISO Standard of 17
  • The library has been tested to compile with (but is not necessarily limited to):
    • GCC >= 8
    • Clang >= 10
• VecCore version 0.8.0 or newer
  • VecGeom can build/install its own copy of VecCore by setting the CMake variable VECGEOM_BUILTIN_VECCORE to ON
• Optional
  • Vc 1.3.3 or newer for SIMD support
  • Xerces-C for GDML support
  • CUDA Toolkit 11.0 or newer for CUDA support
    • An NVidia GPU with sufficient compute capability must be present on the host system
    • It is recommended to use CMake 3.18 or newer for the better native CUDA support

Quick Start

$ mkdir build && cd build
$ cmake ..
$ cmake --build .
$ cmake --build . --target install

Build Options

The table below shows the available CMake options for VecGeom that may be used to customize the build:

The following options are available for enabling, building, and running tests:

Please note that the Geant4 and ROOT options are only for testing and should not be enabled in builds for production use. Both Geant4 and ROOT provide their own interfaces for use of VecGeom by their consumers.

Documentation

• Doxygen reference guide

Note on using VecGeom CUDA Support

If VecGeom is built with VECGEOM_ENABLE_CUDA, then it is still usable by CPU-only code but you must link your binaries to both the vecgeom and vecgeomcuda libraries.

If your code uses VecGeom's CUDA interface in device code or kernels, then it must either:

1. Link and device-link to the vecgeomcuda_static target. In CMake, this is automatically handled by, e.g.

   find_package(VecGeom)
   add_executable(MyCUDA MyCUDA.cu)
   set_target_properties(MyCUDA PROPERTIES CUDA_SEPARABLE_COMPILATION ON)
   target_link_libraries(MyCUDA PRIVATE VecGeom::vecgeomcuda_static)

2. Link to the vecgeomcuda shared library, and device-link to the vecgeomcuda_static target, e.g. in CMake (only CMake 3.18 and newer):

   find_package(VecGeom)
   add_library(MyCUDA MyCUDA.cu)
   set_target_properties(MyCUDA PROPERTIES CUDA_SEPARABLE_COMPILATION ON)
   target_link_libraries(MyCUDA PRIVATE VecGeom::vecgeomcuda)
   # Requires CMake 3.18 or newer
   target_compile_options(MyCUDA PRIVATE $<DEVICE_LINK:$<TARGET_FILE:vecgeomcuda_static>>)

It is strongly recommended to use the first option unless you must use shared libraries. It is also the developer's responsibility to handle any further device-linking of vecgeomcuda using libraries that may be required if these libraries expose device/kernel interfaces.

Bug Reports

Please report all issues on our JIRA Issue tracking system