SHiP Geometry Service

A framework-agnostic C++20 library that wraps the SHiP GeoModel geometry behind a stable interface. The design follows the patterns of DD4HEP's IGeoSvc (LHCb/key4hep) and ALICE O2's GeometryManager.

Documentation

An automatic class reference is built using Doxygen from comments in the C++ code.

Architecture

┌─────────────────────────────────────────┐
│  IGeometryService  (abstract interface) │
│  • geoModelWorld()  → GeoVPhysVol*      │
│  • geant4WorldLogical() → G4LogicalVol* │  ← lazy, call_once
│  • getLogicalVolume(name)               │
└───────────────────┬─────────────────────┘
                    │ implements
┌───────────────────▼─────────────────────┐
│  SHiPGeometryService                    │
│  ::fromSource()   — SHiPGeometryBuilder │
│  ::fromFile(db)   — GeoModelIO::Read    │
└─────────────────────────────────────────┘

Design decisions:

• IGeometryService has no framework headers — can be used standalone or from any framework.
• GeoModel tree construction is eager (in the factory functions) to surface geometry errors at startup.
• GeoModel→Geant4 conversion (geant4WorldLogical()) is lazy (guarded by std::call_once) because ExtParameterisedVolumeBuilder::Build() requires a G4RunManager to exist on the calling thread. Call it from within G4VUserDetectorConstruction::Construct().

Prerequisites

The easiest setup is pixi, which provisions the full toolchain from conda-forge and the SHiP channel at prefix.dev/ship. For manual builds you'll need:

• CMake 3.24+
• C++20 compiler
• SHiPGeometry installed (from geometry/ repository)
• GeoModel 6.22+ (GeoModelCore, GeoModelIO, GeoModelG4)
• Geant4 11.x

Building

With pixi (recommended)

pixi run test

That single command provisions the env, configures with CMake/Ninja (RelWithDebInfo), builds, and runs ctest — the same chain CI uses.

For iteration, the individual tasks defined in pixi.toml are:

pixi run configure   # cmake -S . -B build -G Ninja ...
pixi run build       # cmake --build build -j
pixi run test        # ctest --test-dir build --output-on-failure

Use pixi shell to drop into an interactive shell with the env activated (useful for running individual binaries, debuggers, etc.).

Manual build

If you already have GeoModel, Geant4, and SHiPGeometry installed (e.g. via spack or a system package manager), you can build directly with CMake:

cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="/path/to/GeoModel/install;/path/to/SHiPGeometry/install"
cmake --build build
cmake --install build --prefix /path/to/install

API

Building geometry from source

#include <GeometryService/SHiPGeometryService.h>

auto svc = ship::SHiPGeometryService::fromSource();
const GeoVPhysVol* world = svc->geoModelWorld();

Loading geometry from a .db file

auto svc = ship::SHiPGeometryService::fromFile("/path/to/ship_geometry.db");

Accessing Geant4 geometry

Call geant4WorldLogical() from within G4VUserDetectorConstruction::Construct():

G4VPhysicalVolume* Construct() override {
    G4LogicalVolume* worldLV = geoSvc_.geant4WorldLogical();
    return new G4PVPlacement(nullptr, G4ThreeVector(), worldLV,
                             "World", nullptr, false, 0);
}

Volume look-up

// Valid after geant4WorldLogical() has been called
G4LogicalVolume* lv = svc->getLogicalVolume("MuonShield");

Using from CMake

find_package(SHiPGeometryService CONFIG REQUIRED)
target_link_libraries(myapp PRIVATE SHiPGeometryService::SHiPGeometryService)

The package config pulls in SHiPGeometry, GeoModelCore, GeoModelIO, GeoModelG4, and Geant4 automatically.

Licence

LGPL-3.0-or-later. Copyright CERN for the benefit of the SHiP Collaboration.