8 Existing DDG4 components

In the introduction the longterm goal was expressed, that with DDG4 users should be able to pick components from a growing palette and connect the selected components using the setup mechanisms described in Section 4.

Such a palette based approach obviously depends on the availability of documentation for existing components describing the properties of each component and the interaction of each component within the DDG4 framework.

All components defer from the basic type Geant4Action. This means all components have the default properties described in the table below:




Component Properties:

default




OuputLevel [int]

Output level of the component to customize printouts

Name [string]

Component name [read-only]

Control [boolean]

Steering of the Geant4 Messenger creation





Important notice for developers:

Since the documentation of developed components is VERY important, please never forget to supply the corresponding documentation.

At least supply the minimal documentation ash shown below in the appended examples for the ”Simple” detector response and I/O components.


8.1 Generic Action Modules

8.1.1 Geant4UIManager

The Geant4UIManager handles interactivity aspects between Geant4, its command handlers (i.e. terminal) and the various components the actions interact.

The Geant4UIManager is a component attached to the Geant4Kernel object. All properties of all Geant4Action instances may be exported to Geant4 messengers and may hence be accessible directly from the Geant4 prompt. To export properties from any action, call the enableUI() method of the action. The callback signature is: void operator()(G4Event* event).



Class name

Geant4UIManager

File name

DDG4/src/Geant4UIManager.cpp

Type

Geant4Action



Component Properties:

defaults apply



SessionType (string)

Session type (csh, tcsh, etc.

SetupUI (string)

Name of the UI macro file

SetupVIS (string)

Name of the visualization macro file

HaveVIS (bool)

Flag to instantiate Vis manager (def:false, unless VisSetup set)

HaveUI (bool)

Flag to instantiate UI (default=true)

8.1.2 Geant4Random

Mini interface to the random generator of the application. Necessary, that on every object creates its own instance, but accesses the main instance available through the Geant4Context.

This is mandatory to ensure reproducibility of the event generation process. Particular objects may use a dependent generator from an experiment framework like GAUDI.

internally the engine factory mechanism of CLHEP is used. Please refer there within for valid engine names and the random seeding mechanism, which may vary between different engines.

Any number of independent random objects may be created and used in parallel. This however, is not advised to ensure reproducibility.

The first instance of the random action is automatically set to be the Geant4 instance. If another instance should be used by Geant4, use setMainInstance(Geant4Random* ptr) class method to override this behavior. Provision, steered by options, is taken to ensure the gRandom of ROOT uses the same random number engine.



Class name

Geant4Random

File name

DDG4/src/Geant4Random.cpp

Type

Geant4Random



Component Properties:

defaults apply



File (string)

File name if initialized from file.

If set, engine name and seeds are ignored

Engine (string)

Engine type name.

All engines defined in the CLHEP::EngineFactory class are available. If no type is supplied the engine from the HepRandom generator instance is taken.

Seed (long)

Initial random seed.

Default: 123456789.

If not ZERO terminated, termination is added.

Replace_gRandom (bool)

Flag to replace the ROOT gRandom instance with this random number engine. This ensures ROOT and Geant4 use the same random number engine, hence the same random sequence.

8.2 Geant4UserInitialization Implementations

8.2.1 Geant4PythonInitialization

Please see Section 7.5 for an illustration of the usage. The configuration by construction must be performed using setter-functions rather than properties.



Class name

Geant4PythonInitialization

File name

DDG4/src/python/Geant4PythonInitialization.cpp

Type

Geant4Action



Component Properties:

defaults apply

8.2.2 Geant4PythonDetectorConstruction

Please see Section 7.5 for an illustration of the usage. The configuration by construction must be performed using setter-functions rather than properties.



Class name

Geant4PythonDetectorConstruction

File name

DDG4/src/python/Geant4PythonDetectorConstruction.cpp

Type

Geant4Action



Component Properties:

defaults apply

8.3 Predefined Geant4 Physics List Objects

The physics list may be defined entirely data driven using the factory mechanism using a variety of predefined objects. Though users are free to define private physics lists, typically the predefined physics lists from Geant4 are used.

The inventory changes over time, new lists appear and obsolete lists are purged, hence we will not list them explicitly here. For the inventory of available physics lists, please refer to the implementation files:

8.4 Geant4 Generation Action Modules

Here we discuss modules, which are intrinsically part of DDG4 and may be attached to the Geant4GeneratorActionSequence.

8.4.1 Base class: Geant4GeneratorAction

The Geant4GeneratorAction is called for every event. During the callback all particles are created which form the microscopic kinematic action of the particle collision. This input may either origin directly from an event generator program or come from file.

The callback signature is: void operator()(G4Event* event) See also: Geant4EventAction in the doxygen documentation.



Class name

Geant4GeneratorAction

File name

DDG4/src/Geant4GeneratorAction.cpp

Type

Geant4Action, Geant4GeneratorAction



Component Properties:

defaults apply



8.4.2 Geant4GeneratorActionSequence

The sequence dispatches the callbacks at the beginning of an event to all registered Geant4GeneratorAction members and all registered callbacks.

See also: The Geant4GeneratorActionSequence is directly steered by the single instance of the G4VUserPrimaryGeneratorAction, the Geant4 provided user hook, which is private.
See also: Geant4UserGeneratorAction and Geant4GeneratorActionSequence in the doxygen documentation.



Class name

Geant4Geant4GeneratorActionSequence

File name

DDG4/src/Geant4GeneratorAction.cpp

Type

Geant4Action



Component Properties:

defaults apply



8.4.3 Geant4GeneratorActionInit

Initialize the Geant4Event objects to host generator and MC truth related information Geant4 actions to collect the MC particle information. This action should register all event extension required for the further processing. We want to avoid that every client has to check if a given object is present or not and than later install the required data structures.

These by default are extensions of type:

  • Geant4PrimaryEvent with multiple interaction sections, one for each interaction This is the MAIN and ONLY information to feed Geant4
  • Geant4PrimaryInteraction containing the track/vertex information to create the primary particles for Geant4. This record is build from the Geant4PrimaryEvent information.
  • Geant4PrimaryMap a map of the Geant4Particles converted to G4PrimaryParticles to ease particle handling later.
  • Geant4ParticleMap the map of particles created during the event simulation. This map has directly the correct particle offsets, so that the merging of Geant4PrimaryInteraction particles and the simulation particles is easy....



Class name

Geant4Geant4GeneratorActionInit

File name

DDG4/src/Geant4GeneratorActionInit.cpp

Type

Geant4GeneratorAction



Component Properties:

defaults apply

Angle (double)

Lorentz-Angle of boost

Mask (int.bitmask)

Interaction identifier



8.4.4 Geant4InteractionVertexBoost

Boost the primary vertex and all particles outgoing the primary interaction in X-direction.

The interaction to be processed by the component is uniquely identified by the Mask property. Two primary interaction may not have the same mask.

Note [special use case]:
If all contributing interactions of the one event registered in the primary event at the time the action is called should be handled by one single component instance, set the Mask property to -1.



Class name

Geant4InteractionVertexBoost

File name

DDG4/src/Geant4InteractionVertexBoost.cpp

Type

Geant4GeneratorAction



Component Properties:

defaults apply

Angle (double)

Lorentz-Angle of boost

Mask (int.bitmask)

Interaction identifier



8.4.5 Geant4InteractionVertexSmear

Smear the primary vertex and all particles outgoing the primary interaction.

The interaction to be processed by the component is uniquely identified by the Mask property. Two primary interaction may not have the same mask.

Note [special use case]:
If all contributing interactions of the one event registered in the primary event at the time the action is called should be handled by one single component instance, set the Mask property to -1.



Class name

Geant4InteractionVertexSmear

File name

DDG4/src/Geant4InteractionVertexSmear.cpp



Component Properties:

defaults apply

Offset (PxPyPzEVector)

Smearing offset

Sigma (PxPyPzEVector)

Sigma (Errors) on offset

Mask (int.bitmask)

Interaction identifier



8.4.6 Geant4InteractionMerger

Merge all interactions created by each Geant4InputAction into one single record. The input records are taken from the item Geant4PrimaryEvent and are merged into the Geant4PrimaryInteraction object attached to the Geant4Event event context.



Class name

Geant4InteractionMerger

File name

DDG4/src/Geant4InteractionMerger.cpp

Type

Geant4GeneratorAction



Component Properties:

defaults apply



8.4.7 Geant4PrimaryHandler

Convert the primary interaction (object Geant4PrimaryInteraction object attached to the Geant4Event event context) and pass the result to Geant4 for simulation.



Class name

Geant4PrimaryHandler

File name

DDG4/src/Geant4PrimaryHandler.cpp

Type

Geant4GeneratorAction



Component Properties:

defaults apply



8.4.8 Geant4ParticleGun

Implementation of a particle gun using Geant4Particles.

The Geant4ParticleGun is a tool to shoot a number of particles with identical properties into a given region of the detector to be simulated.

The particle gun is a input source like any other and participates in the general input stage merging process like any other input e.g. from file. Hence, there may be several particle guns present each generating its own primary vertex. Use the mask property to ensure each gun generates its own, well identified primary vertex.

There is one ’user lazyness’ support though: If there is only one particle gun in use, the property ’Standalone’, which by default is set to true invokes the interaction merging and the Geant4 primary generation directly.

The interaction to be created by the component is uniquely identified by the Mask property. Two primary interaction may not have the same mask.



Class name

Geant4PrimaryHandler

File name

DDG4/src/Geant4PrimaryHandler.cpp

Type

Geant4GeneratorAction



Component Properties:

default

particle (string)

Particle type to be shot

energy (double)

Particle energy in MeV

position (XYZVector)

Pole position of the generated particles in mm

direction (XYZVector)

Momentum direction of the generated particles

isotrop (bool)

Isotropic particle directions in space.

Mask (int.bitmask)

Interaction identifier

Standalone (bool)

Setup for standalone execution

including interaction merging etc.



8.4.9 Geant4ParticleHandler

Extract the relevant particle information during the simulation step.

This procedure works as follows:

  • At the beginning of the event generation the object registers itself as Monte-Carlo truth handler to the event context.
  • At the begin of each track action a particle candidate is created and filled with all properties known at this time.
  • At each stepping action a flag is set if the step produced secondaries.
  • Sensitive detectors call the MC truth handler if a hit was created. This fact is remembered.
  • At the end of the tracking action a first decision is taken if the candidate is to be kept for the final record.
  • At the end of the event action finally all particles are reduced to the final record. This logic can be overridden by a user handler to be attached.

Any of these actions may be intercepted by a Geant4UserParticleHandler attached to the particle handler. See class Geant4UserParticleHandler for details.



Class name

Geant4ParticleHandler

File name

DDG4/src/Geant4ParticleHandler.cpp

Type

Geant4GeneratorAction



Component Properties:

defaults apply

KeepAllParticles (bool)

Flag to keep entire particle record without any reduction. This may result in a huge output record.

SaveProcesses (vector(string))

Array of Geant4 process names, which products and parent should NOT be reduced.

MinimalKineticEnergy (double)

Minimal energy below which particles should be ignored unless other criteria (Process, created hits, etc) apply.



8.5 Geant4 Event Action Modules

8.5.1 Base class: Geant4EventAction

The EventAction is called for every event.

This class is the base class for all user actions, which have to hook into the begin- and end-of-event actions. Typical use cases are the collection/computation of event related properties.

Examples of this functionality may include for example:

  • Reset variables summing event related information in the begin-event callback.
  • Monitoring activities such as filling histograms from hits collected during the end-event action.

See also: Geant4EventAction in the doxygen documentation.



Class name

Geant4EventAction

File name

DDG4/src/Geant4EventAction.cpp

Type

Geant4EventAction



Component Properties:

defaults apply



8.5.2 Geant4EventActionSequence

The Geant4EventActionSequence is directly steered by the single instance of the G4UserEventAction, the Geant4 provided user hook, which is private.
See also: Geant4UserEventAction in the doxygen documentation.



Class name

Geant4EventAction

File name

DDG4/src/Geant4EventAction.cpp

Type

Geant4EventAction



Component Properties:

defaults apply



8.5.3 Geant4ParticlePrint

Geant4Action to print MC particle information.



Class name

Geant4ParticlePrint

File name

DDG4/src/Geant4ParticlePrint.cpp

Type

Geant4EventAction



Component Properties:

defaults apply

OutputType (bool)

Flag to steer output type.

1: Print table of particles.

2: Print table of particles.

3: Print table and tree of particles.

PrintHits

Print associated hits to every particle (big output!)



8.6 Sensitive Detectors

8.6.1 Geant4TrackerAction

Simple sensitive detector for tracking detectors. These trackers create one single hit collection. The created hits may be written out with the output modules described in Section 8.7.1 and 8.7.2.
The basic specifications are:



Basics:



Class name

Geant4SensitiveAction<Geant4Tracker>

File name

DDG4/plugins/Geant4SDActions.cpp

Hit collection

Name of the readout object

Hit class

Geant4Tracker::Hit

File name

DDG4/include/Geant4Data.h



Component Properties:

defaults apply



8.6.2 Geant4CalorimeterAction

Simple sensitive detector for calorimeters. The sensitive detector creates one single hit collection. The created hits may be written out with the output modules described in Section 8.7.1 and 8.7.2.
The basic specifications are:



Basics:



Class name

Geant4SensitiveAction<Geant4Calorimeter>

File name

DDG4/plugins/Geant4SDActions.cpp

Hit collection

Name of the readout object

Hit class

Geant4Calorimeter::Hit

File name

DDG4/include/Geant4Data.h



Component Properties:

defaults apply



8.7 I/O Components

8.7.1 ROOT Output ”Simple”

8.7.2 LCIO Output ”Simple”