Experimental geometry

remage does not implement or manage any experimental geometry. Instead, the user must provide a geometry definition. There are two supported approaches:

• Supply one or more GDML files via the command line or using the macro command /RMG/Geometry/IncludeGDMLFile.

• Override RMGHardware::DefineGeometry() in a subclass of RMGHardware and register it using RMGManager::SetUserInit(). A practical example is in tests/cosmogenics/surface.

See also

The pyg4ometry Python library provides powerful tools for building Monte Carlo geometries and exporting them as GDML. Relevant pyg4ometry-based packages include:

• legend-pygeom-tools – general geometry routines and GDML extensions for detector registration

• legend-pygeom-hpges – high-purity germanium detector models

• legend-pygeom-optics – optical properties for Geant4 materials

Full geometry implementations based on these tools:

• legend-pygeom-l200 – LEGEND-200

• legend-pygeom-l1000 – LEGEND-1000

Registering detectors

Detector volumes must be registered so that particle interactions are recorded in the output. Throughout this documentation, “detector” is used for what Geant4 itself calls a sensitive detector (or sensitive volume). In remage, this registration can be done in several ways. Each detector has a unique id (UID) and a type, which determines how hits in a physical volume (or in a group of them) are processed and stored. Detectors of type Germanium, Scintillator, Optical and Calorimeter are currently supported, see Output for more details.

Note

User-defined detector types cannot currently be registered at runtime.

The simplest method is to use the /RMG/Geometry/RegisterDetector macro command:

/RMG/Geometry/RegisterDetector Germanium B00000B 1
/RMG/Geometry/RegisterDetector Germanium C000RG1 2 1

This registers the physical volume B00000B, and the C000RG1 volume with copy number 1 as Germanium detectors with UIDs 1 and 2 respectively. Because for B00000B no copy number was specified, this will register all B00000B named volumes if there are multiple with different copy numbers. This command now also accepts regex patterns (respecting the default std::regex_match grammar):

/RMG/Geometry/RegisterDetector Germanium B.* 1

registers all physical volumes starting with B. If there are multiple volumes matching the pattern, they will all be registered alphabetically under incrementing UIDs. This means the first alphabetical B.* match will be registered under UID 1, the second match will be registered with UID 2 and so on. It is therefore the responsibility of the user to make sure that no UID will be duplicated, which is detected by remage and results in an error.

Alternatively, one might want to assign the same UID to multiple physical volumes, i.e. as if they constitute a single detector unit. In such a scenario, there would be no way to distinguish hits from different volumes in the simulation output (except from the coordinates in post-processing). In this case, the fifth argument (allow_uid_reuse) has to be set to true:

/RMG/Geometry/RegisterDetector Germanium .*_cu_.* 1 .* true

This would register any volume with name matching the regular expression .*_cu_.* under the UID 1. In this case the UIDs will not be incremented for multiple matches.

This alone might produce unexpected output, when /RMG/Output/NtupleUseVolumeName is enabled. To solve the problem, a sixth argument (ntuple_name) can be used to set the name of the resulting ntuple. The same fifth and sixth arguments must be used for all detectors that share a uid. In this case, the specified name will be used as the table name in the output file, instead of the volume name.

Last but not least, detectors can be imported from a GDML file that includes metadata, using the /RMG/Geometry/RegisterDetectorsFromGDML command.

Tip

The legend-pygeom-tools package automatically includes such metadata when writing GDML with pygeomtools.write.write_pygeom().

Inspecting geometry

To inspect the simulation geometry, use the following macro commands:

• /RMG/Geometry/PrintListOfLogicalVolumes

• /RMG/Geometry/PrintListOfPhysicalVolumes

Example session:

remage> /RMG/Geometry/IncludeGDMLFile geometry.gdml
remage> /run/initialize
G4GDML: Reading 'geometry.gdml'...
G4GDML: Reading definitions...
G4GDML: Reading materials...
G4GDML: Reading solids...
G4GDML: Reading structure...
G4GDML: Reading userinfo...
G4GDML: Reading setup...
G4GDML: Reading 'geometry.gdml' done!
Stripping off GDML names of materials, solids and volumes ...
[Summary -> Checking for overlaps in GDML geometry...
remage> /RMG/Geometry/PrintListOfPhysicalVolumes
[Summary ->  · B00000A  // 0 daugh. // 5.54635 g/cm3  // 488.951 g  // 8.81573 cL  // 1 atm // 293.15 K
[Summary ->  · B00000B  // 0 daugh. // 5.54635 g/cm3  // 700.096 g  // 1.26227 dL  // 1 atm // 293.15 K
...
[Summary ->  · wlsr_ttx // 1 daugh. // 350 mg/cm3 // 1.15983 kg // 3.3138 L   // 1 atm // 293.15 K
[Summary ->  · world    // 1 daugh. // 1e-22 mg/cm3 // 154028 kg // 1.54028e+18 km3 // 3e-18 Pa  // 2.73 K
[Summary ->
[Summary -> Total: 171 volumes

Step limits per volume

A maximum step length for charged particles can be imposed on individual physical volumes (matched by regular expression) with /RMG/Geometry/SetMaxStepSize. See Step limits for details and guidance.

Checking geometry

remage provides three distinct mechanisms to validate and profile a geometry, addressing different needs and offering different levels of detail:

1. an always-on overlap check using Geant4’s own sampled-point overlap test, a convenient first line of defense against basic geometry construction errors;

2. a deeper, opt-in navigation check based on geantinos, provided by the GeometryCheck output scheme and described below;

3. a performance benchmark of the geometry navigation, provided by the standalone remage-geombench tool (see Geometry benchmarking), which profiles the navigation speed rather than the correctness of a geometry.

Tip

As seen above, the Geant4 overlap checker is enabled by default if GDML input is provided. It can be disabled with the /RMG/Geometry/GDMLDisableOverlapCheck command.

The GeometryCheck output scheme fires geantino primaries (massless, chargeless, non-interacting Geant4 tracking particles used purely to probe navigation) through the geometry and verifies, at every step, that the pre- and post-step volume transitions reported by the navigator are consistent with the declared volume hierarchy. This catches subtler navigation bugs than a plain overlap test can, such as volumes that only overlap through coincident surfaces and not through their bulk.

The user has to initialize this test in a specialized macro, that needs to be adapted to the geometry dimensions:

/RMG/Output/ActivateOutputScheme GeometryCheck

/run/initialize

/RMG/Generator/Confine Volume
/RMG/Generator/Confinement/SampleOnSurface
/RMG/Generator/Confinement/FirstSamplingVolume Geometrical

/RMG/Generator/Confinement/Geometrical/AddSolid Box
/RMG/Generator/Confinement/Geometrical/CenterPositionX 0 m
/RMG/Generator/Confinement/Geometrical/CenterPositionY 0 m
/RMG/Generator/Confinement/Geometrical/CenterPositionZ 0 m
/RMG/Generator/Confinement/Geometrical/Box/XLength 10 m
/RMG/Generator/Confinement/Geometrical/Box/YLength 10 m
/RMG/Generator/Confinement/Geometrical/Box/ZLength 10 m

/RMG/Generator/Select GPS
/gps/particle     geantino
/gps/energy       1 MeV
/gps/ang/type     iso

/run/beamOn {n}

The sampling surface has to be adjusted so that it lies fully within a single volume and also fully contains all daughter volumes of that volume, otherwise the check will not be correctly performed.