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::Cache cache;
0024 Acts::Geant4DetectorSurfaceFactory::Options options;
0025 options.sensitiveSurfaceSelector = nameSelector;
0026
0027 Acts::Geant4DetectorSurfaceFactory factory;
0028 factory.construct(cache, nominal, *cylinderPV, options);
0029
0030 BOOST_CHECK_EQUAL(cache.sensitiveSurfaces.size(), 1u);
0031 BOOST_CHECK_EQUAL(cache.passiveSurfaces.size(), 0u);
0032
0033 auto [ element, surface ] = cache.sensitiveSurfaces.front();
0034 BOOST_CHECK_EQUAL(surface->type(), Acts::Surface::SurfaceType::Cylinder);
0035 ```
0036
0037 #### Inspecting surface conversion within python
0038
0039 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)
0040
0041 ```python
0042 # import the necessary modules
0043 import acts, acts.examples
0044 from acts.examples import geant4 as acts_g4
0045
0046 # The match criteria
0047 sensitive_matches = [ 'Sensitive' ]
0048 passive_matches = [ 'Passive' ]
0049 [ elements, ssurfaces, psurfaces ] = acts_g4.convertSurfaces('detector.gdml', sensitive_matches, passive_matches)
0050
0051 # Some screen output
0052 print('* Conversion yielded', len(ssurfaces))
0053
0054 # Write them to an obj file
0055 drawContext = acts.GeometryContext()
0056 sensitiveRgb = [ 0, 150, 150 ]
0057 passiveRgb = [ 150, 150, 0]
0058 segments = 64 # how many segments to approximate a full circle
0059 # Draw the sensitive surfaces
0060 acts.examples.writeSurfacesObj(ssurfaces, drawContext, sensitiveRgb, segments, 'detector-sensitives.obj')
0061 # Draw the passive surfaces
0062 acts.examples.writeSurfacesObj(psurfaces, drawContext, passiveRgb, segments, 'detector-passives.obj')
0063 ```
0064
0065 ## Building a Detector from Geant4 input
0066
0067 In order to build an `Acts::Detector` object from `Geant4` input, the following steps needs to be done
0068  * a conversion of `Geant4PhysVolume` objects into `Acts::Surface`  and `Acts::DetectorVolume` objects (see before)
0069  * a build sequence needs to be defined and the converted objects identified
0070
0071 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:
0072
0073 ```python
0074 # Create a KDTree from all surfaces binned in z and r
0075 surfacesKdt = acts.KdtSurfaces2D(buildContext, surfaces, [acts.Binning.z, acts.Binning.r])
0076
0077 # Define a query range and select
0078 qrange = acts.Range2D( [-580,580], [0,200])
0079 selected = surfacesKdt.surfaces(qrange)
0080
0081 # Draw, inspect the surfaces
0082 ```
0083
0084 Selected surfaces can be put as a layer structure into a volume