docs/plugins/geant4.md

0001 # Geant4 plugin
0002
0003 The Geant4 plugin allows to build {class}`Acts::TrackingGeometry` and {class}`Acts::Experimental::Detector` directly from Geant4 geometry input.
0004 Both rely on the conversion of `G4VPhysicalVolume` into corresponding `Acts` objects.
0005
0006 ## Object conversion
0007
0008 ### Surface conversion
0009
0010 Converting physical volumes into {class}`Acts::Surface` objects that represent sensitive detector elements, is done via the {class}`Acts::Geant4DetectorSurfaceFactory`.
0011 This helper class allows to select volumes from the Geant4 geometry and convert them either into pairs of {class}`Acts::Geant4DetectorElement` and {class}`Acts::Surface` objects in case of sensitive elements, or simply surfaces objects in the case of passive surfaces.
0012
0013 The selection is hereby done by providing one or more {class}`Acts::IGeant4PhysicalVolumeSelector` objects to the surface factory.
0014
0015 Possible implementations of this type of conversions can be seen in the corresponding unit test `ActsUnitTestGeant4DetectorSurfaceFactory`
0016
0017 ```cpp
0018 // Get the box
0019 auto nameSelector =
0020     std::make_shared<Acts::Geant4PhysicalVolumeSelectors::NameSelector>(
0021         std::vector<std::string>{"yl"}, false);
0022
0023 Acts::Geant4DetectorSurfaceFactory::Config config;
0024 Acts::Geant4DetectorSurfaceFactory::Cache cache;
0025 Acts::Geant4DetectorSurfaceFactory::Options options;
0026 options.sensitiveSurfaceSelector = nameSelector;
0027
0028 Acts::Geant4DetectorSurfaceFactory factory(config);
0029 factory.construct(cache, nominal, *cylinderPV, options);
0030
0031 BOOST_CHECK_EQUAL(cache.sensitiveSurfaces.size(), 1u);
0032 BOOST_CHECK_EQUAL(cache.passiveSurfaces.size(), 0u);
0033
0034 auto [ element, surface ] = cache.sensitiveSurfaces.front();
0035 BOOST_CHECK_EQUAL(surface->type(), Acts::Surface::SurfaceType::Cylinder);
0036 ```
0037
0038 #### Inspecting surface conversion within python
0039
0040 The `ActsExamples` python bindings allow to conveniently test the conversion of `Geant4` volumes into sensitive and passive surfaces, assuming you have a GDML file called `detector.gdml` where `Geant4PhysVolume` objects can be identified by a certain string, e.g. names containing the flag `Sensitive`, or `Passive`. Also, multiple match strings are allowed. The converted surfaces can then be displayed with `.obj` (part of the Core functionality) or as `.svg` files (if `ACTS_BUILD_PLUGIN_ACTSVG` is switched on)
0041
0042 ```python
0043 # import the necessary modules
0044 import acts, acts.examples
0045 from acts.examples import geant4 as acts_g4
0046
0047 # The match criteria
0048 sensitive_matches = [ 'Sensitive' ]
0049 passive_matches = [ 'Passive' ]
0050 [ elements, ssurfaces, psurfaces ] = acts_g4.convertSurfaces('detector.gdml', sensitive_matches, passive_matches)
0051
0052 # Some screen output
0053 print('* Conversion yielded', len(ssurfaces))
0054
0055 # Write them to an obj file
0056 drawContext = acts.GeometryContext()
0057 sensitiveRgb = [ 0, 150, 150 ]
0058 passiveRgb = [ 150, 150, 0]
0059 segments = 64 # how many segments to approximate a full circle
0060 # Draw the sensitive surfaces
0061 acts.examples.writeSurfacesObj(ssurfaces, drawContext, sensitiveRgb, segments, 'detector-sensitives.obj')
0062 # Draw the passive surfaces
0063 acts.examples.writeSurfacesObj(psurfaces, drawContext, passiveRgb, segments, 'detector-passives.obj')
0064 ```
0065
0066 ## Building a Detector from Geant4 input
0067
0068 In order to build an `Acts::Detector` object from `Geant4` input, the following steps needs to be done
0069  * a conversion of `Geant4PhysVolume` objects into `Acts::Surface`  and `Acts::DetectorVolume` objects (see before)
0070  * a build sequence needs to be defined and the converted objects identified
0071
0072 There are several helper methods and tools that can be used, many of them accessible through python bindings. One core component is the selection and assignment of surfaces to dedicated volume. This can be done using e.g. a KDT structure, this can be tested with:
0073
0074 ```python
0075 # Create a KDTree from all surfaces binned in z and r
0076 surfacesKdt = acts.KdtSurfaces2D(buildContext, surfaces, [acts.Binning.z, acts.Binning.r])
0077
0078 # Define a query range and select
0079 qrange = acts.Range2D( [-580,580], [0,200])
0080 selected = surfacesKdt.surfaces(qrange)
0081
0082 # Draw, inspect the surfaces
0083 ```
0084
0085 Selected surfaces can be put as a layer structure into a volume