Integration Into Geant4 Applications

AdePT is consumed as a CMake package.

CMake Integration

find_package(AdePT REQUIRED)

For targets that use AdePT:

cuda_rdc_target_include_directories(example_target <SCOPE>
  <TARGET INCLUDE DIRECTORIES>
  ${AdePT_INCLUDE_DIRS})

cuda_rdc_target_link_libraries(example_target <SCOPE>
  <TARGET LINK LIBRARIES>
  ${AdePT_LIBRARIES})

cuda_rdc_* is required to keep CUDA device-link behavior consistent with the VecGeom/AdePT build model.

Geant4 Physics Integration

After linking AdePT, integrate it into your Geant4 physics setup with the approach that matches your EM physics configuration.

Case 1: Complete AdePT Physics List

If you use the FTFP_BERT physics list as is, with G4EmStandardPhysics option 0 and no specializations such as Woodcock tracking, use the complete AdePT physics list FTFP_BERT_AdePT.

Case 2: AdePT EM Constructor

If you use a different hadronic physics setup, but still use G4EmStandardPhysics option 0 without special EM customizations, register G4EmStandardPhysics_AdePT instead of G4EmStandardPhysics.

The public headers for this integration are under AdePT/g4integration. For example, a physics-list wrapper can include and register the AdePT EM physics constructor as:

#include <AdePT/g4integration/G4EmStandardPhysics_AdePT.hh>

RegisterPhysics(new G4EmStandardPhysics_AdePT(ver));

Case 3: Direct Tracking-Manager Integration

If you use another EM configuration, such as a different G4EmStandardPhysics option, Woodcock tracking, or experiment-specific G4HepEm settings, register AdePTTrackingManager directly for electrons, positrons, and gammas. This is the pattern to use when wrapping an existing custom EM physics constructor.

The direct tracking-manager integration needs both the AdePT public integration headers and the G4HepEm configuration header:

#include <AdePT/g4integration/AdePTConfiguration.hh>
#include <AdePT/g4integration/AdePTTrackingManager.hh>

#include <G4HepEmConfig.hh>
#include <G4HepEmParameters.hh>

#include "G4Electron.hh"
#include "G4Gamma.hh"
#include "G4Positron.hh"
#include "G4SystemOfUnits.hh"

In the physics constructor, keep the AdePTConfiguration alive for the lifetime of the tracking manager. Configure AdePT first, construct the tracking manager, then configure the underlying G4HepEm tracking settings and attach the manager to the particle definitions:

// Required: In the physics-constructor constructor or equivalent setup:
fAdePTConfiguration = new AdePTConfiguration();

// Optional AdePT-side defaults. If these are set in ConstructProcess(), they override the usual /adept/* macro commands, since those are normally processed before /run/initialize. This might be useful to avoid having to call many UI commands for a fixed setup.
fAdePTConfiguration->SetCUDAStackLimit(8192);
fAdePTConfiguration->SetTrackInAllRegions(true);
fAdePTConfiguration->SetCallUserTrackingAction(true);

// Required: In ConstructProcess(), after registering the EM processes for the custom
// EM constructor, create an AdePTTrackingManager:
fTrackingManager = new AdePTTrackingManager(fAdePTConfiguration, /*verbosity=*/0);

// Optional: change the G4HepEm configuration
auto *g4hepemConfig = fTrackingManager->GetG4HepEmConfig();

// Optional: Match the G4HepEm behavior to the EM constructor that is being replaced.
g4hepemConfig->SetMultipleStepsInMSCWithTransportation(false);
g4hepemConfig->SetEnergyLossStepLimitFunctionParameters(0.8, 1.0 * CLHEP::mm);

// Optional: enable Woodcock tracking for the relevant detector regions.
g4hepemConfig->SetWoodcockTrackingRegion("ECALRegion");

// Optional: tune low-energy tracking cuts or other G4HepEm parameters.
auto *g4hepemParameters = g4hepemConfig->GetG4HepEmParameters();
g4hepemParameters->fElectronTrackingCut = 1.0 * CLHEP::MeV;
g4hepemParameters->fGammaTrackingCut    = 1.0 * CLHEP::MeV;

// Required: Attach the tracking manager to e-/e+ and gamma.
G4Electron::Definition()->SetTrackingManager(fTrackingManager);
G4Positron::Definition()->SetTrackingManager(fTrackingManager);
G4Gamma::Definition()->SetTrackingManager(fTrackingManager);

Only the construction of AdePTConfiguration, AdePTTrackingManager, and the three SetTrackingManager calls are mandatory. The G4HepEmConfig calls should mirror the custom EM setup that is being replaced. For example, an ATLAS-like setup may add Woodcock regions and disable multiple MSC transportation steps, while an LHCb-like option-2 setup may set the energy-loss step-limit function and tracking cuts.

This step enables the AdePT transport/tracking integration in the Geant4 application.

Runtime Configuration

At runtime, AdePT parameters are configured through Geant4 UI commands in the /adept/ directory. See:

In practice this means your Geant4 macro configures /adept/* before /run/initialize.

Reference Integration Examples

See repository examples and regression integration test:

  • examples/Example1

  • test/regression/IntegrationTest