10.2.  Basic Examples

10.2.1.  Basic Examples Summary

Descriptions of the 4 basic examples are provided here along with links to source code documentation automatically generated with Doxygen.

Example B1 (see also Doxygen page )

  • Simple geometry with a few solids
  • Geometry with simple placements (G4PVPlacement)
  • Scoring total dose in a selected volume in user action classes
  • Geant4 physics list (QBBC)

Example B2 (see also Doxygen page )

  • Simplified tracker geometry with uniform magnetic field
  • Geometry with simple placements (G4PVPlacement) and parameterisation (G4PVParameterisation)
  • Scoring within tracker via G4 sensitive detector and hits
  • Geant4 physics list (FTFP_BERT) with step limiter
  • Started from novice N02 example

Example B3 (see also Doxygen page )

  • Schematic Positron Emission Tomography system
  • Geometry with simple placements with rotation (G4PVPlacement)
  • Radioactive source
  • Scoring within Crystals via G4 scorers
  • Modular physics list built via builders provided in Geant4

Example B4 (see also Doxygen page )

  • Simplified calorimeter with layers of two materials
  • Geometry with replica (G4PVReplica)
  • Scoring within layers in four ways: via user actions (a), via user own object (b), via G4 sensitive detector and hits (c) and via scorers (d)
  • Geant4 physics list (FTFP_BERT)
  • Saving histograms and ntuple in a file using new analysis tools
  • UI commans defined using G4GenericMessenger
  • Started from novice/N03 example

Table 10.1 and Table 10.2 display the "item charts" for the examples currently prepared in the basic level.

Example B1 Example B2
Description Simple application for accounting dose in a selected volume Fixed target tracker geometry
Geometry
  • solids: box, cons, trd
  • simple placements with translation
  • solids: box, tubs
  • simple placements with translation (a)
  • parameterised volume (b)
  • uniform magnetic field
Physics Geant4 physics list: QBBC Geant4 physics list: FTFP_BERT
Primary generator Particle gun Particle gun
Scoring User action classes Sensitive detector & hits
Vis/GUI Detector & trajectory drawing
  • Detector, trajectory & hits drawing
  • GUI
Stacking - -
Analysis - -

Table 10.1.  The "item chart" for basic level examples B1 and B2.


Example B3 Example B4
Description Schematic Positron Emitted Tomography system Simplified calorimeter with layers of two materials
Geometry
  • solids: box, tubs
  • simple placements with rotation
  • solids: box
  • simple placements with translation
  • replica
  • uniform magnetic field
Physics Modular physics list with Geant4 builders Geant4 physics list: FTFP_BERT
Primary generator Radioactive source (particle gun with Fluor ions) Particle gun
Scoring Multi functional (sensitive) detector & scorers
  • (a) User action classes
  • (b) User own object (runData)
  • (c) Sensitive detector & hits
  • (d) Multi functional (sensitive) detector & scorers
Vis/GUI Detector, trajectory & hits drawing
  • Detector, trajectory & hits drawing
  • GUI
Stacking Killing all neutrina -
Analysis - Histograms 1D, ntuple

Table 10.2.  The "item chart" for basic level examples B3 and B4.


10.2.2.  Basic Examples Macros

All basic examples can be run either interactively or in a batch mode (see section Section 2.1 and Section 2.9) and they are provided with the following set of macros:

  • init.mac, init_vis.mac
  • vis.mac
  • [gui.mac]
  • run1.mac, run2.mac
  • exampleBN.in

One of the macros init.mac or init_vis.mac is always executed just after the Geant4 kernel initialization. The selection is done automatically according to the application build configuration. If the example is built with any visualization driver, the init_vis.mac macro, which calls the vis.mac macro, is executed, otherwise it is the init.mac macro with no reference to visualization.

The vis.mac macros in each of the examples all have the same structure - except for example B1, see below. There are only a few lines in each example with a setting different from the other examples and so they can be easily spotted when looking in the macro. Various commands are proposed in commented blocks of lines with explanations so that a user can just uncomment lines and observe the effect. Additionally, in example B4, there are some visualization tutorial macros in macros/visTutor/. See more on visualization in section Section 2.10 and chapter Chapter 8.

From Release 9.6 the vis.mac macro in example B1 has additional commands that demonstrate additional functionality of the vis system, such as displaying text, axes, scales, date, logo and shows how to change viewpoint and style. Consider copying these to your favourite example or application. To see even more commands use help or ls or browse the available UI commands in section Section 7.1.

The gui.mac macros are provided in examples B2 and B4. This macro is automatically executed if Geant4 is built with any GUI session. See more on graphical user interfaces in section Section 2.8.

When running interactively, the example program stops after processing the Geant4 kernel initialization and the init.mac or init_vis.mac macro with the prompt Idle>. At this stage users can type in the commands from run1.mac line by line (recommended when running the example for the first time) or execute all commands at once using the "/control/execute run1.mac" command.

The run2.mac macros define conditions for execution a run with a larger number of events and so they are recommended to be executed in a batch. The exampleBN.in macros are also supposed to be run in a batch mode and their outputs from the Geant4 system testing are available in the files exampleBN.out.

10.2.3.  Example B1

Basic concept:

This example demonstrates a simple (medical) application within which users will familiarize themselves with simple placement, use the NIST material database, and can utilize electromagnetic and/or hadronic physics processes. Two items of information are collected in this example: the energy deposited and the total dose for a selected volume.

This example uses the Geant4 physics list QBBC, which is instantiated in the main() function. It requires data files for electromagnetic and hadronic processes. See more on installation of the datasets in Geant4 Installation Guide, Chapter 3.3: Note On Geant4 Datasets . The following datasets: G4LEDATA, G4LEVELGAMMADATA, G4NEUTRONXSDATA and G4SAIDXSDATA are mandatory for this example.

Classes:

  • B1DetectorConstruction

    The geometry is constructed in the B1DetectorConstruction class. The setup consists of a box shaped envelope containing two volumes: a circular cone and a trapezoid.

    Some common materials from medical applications are used. The envelope is made of water and the two inner volumes are made from tissue and bone materials. These materials are created using the G4NistManager class, which allows one to build a material from the NIST database using their names. Available materials and their compositions can be found in the Appendix Section 10.

    The physical volumes are made from Constructive Solid Geometry (CSG) solids and placed without rotation using the G4PVPlacement class.

  • B1PrimaryGeneratorAction

    The default kinematics is a 6 MeV gamma, randomly distributed in front of the envelope across 80% of the transverse (X,Y) plane. This default setting can be changed via the Geant4 built-in commands of the G4ParticleGun class.

  • B1SteppingAction

    It is in the UserSteppingAction() function that the energy deposition is collected for a selected volume.

  • B1EventAction

    The statistical event by event accumulation of energy deposition and total dose is done within this class.

  • B1RunAction

    Information about the primary particle is printed in this class along with the computation of the dose. An example of creating and computing new units (e.g., dose) is also shown in the class constructor.

10.2.4.  Example B2

This example simulates a simplified fixed target experiment. To demonstrate alternative ways of constructing the geometry two variants are provided: B2a (explicit construction) and B2b (parametrized volumes).

The set of available particles and their physics processes are defined in the FTFP_BERT physics list. This Geant4 physics list is instantiated in the main() function. It requires data files for electromagnetic and hadronic processes. See more on installation of the datasets in Geant4 Installation Guide, Chapter 3.3: Note On Geant4 Datasets . The following datasets: G4LEDATA, G4LEVELGAMMADATA and G4SAIDXSDATA are mandatory for this example.

This example also illustrates how to introduce tracking constraints like maximum step length via G4StepLimiter, and minimum kinetic energy, etc., via the G4UserSpecialCuts processes. This is accomplished by adding G4StepLimiterBuilder to the physics list.

Classes:

  • B2[a, b]DetectorConstruction

    The setup consists of a target followed by six chambers of increasing transverse size at defined distances from the target. These chambers are located in a region called the Tracker region. Their shape are cylinders constructed as simple cylinders (in B2aDetectorConstruction) and as parametrised volumes (in B2bDetectorConstruction) - see also B2bChamberParameterisation class.

    In addition, a global, uniform, and traverse magnetic field can be applied (see B2MagneticField, B2aDetectorMessenger and B2bDetectorMessenger classes) and set via interactive command. An instance of the B2TrackerSD class is created and associated with each logical chamber volume (in B2a) and with the one G4LogicalVolume associated with G4PVParameterised (in B2b).

    One can change the materials of the target and the chambers interactively via the commands defined in B2aDetectorMessenger (or B2bDetectorMessenger).

    This example also illustrates how to introduce tracking constraints like maximum step length, minimum kinetic energy etc. via the G4UserLimits class and associated G4StepLimiter and G4UserSpecialCuts processes. The maximum step limit in the tracker region can be set by the interactive command defined in B2aDetectorMessenger (or B2bDetectorMessenger).

  • B2PrimaryGeneratorAction

    The primary generator action class employs the G4ParticleGun. The primary kinematics consists of a single particle which hits the target perpendicular to the entrance face. The type of the particle and its energy can be changed via the G4 built-in commands of the G4ParticleGun class.

  • B2EventAction

    The event number is written to the log file every requested number of events in BeginOfEventAction() and EndOfEventAction(). Moreover, for the first 100 events and every 100 events thereafter information about the number of stored trajectories in the event is printed as well as the number of hits stored in the G4VHitsCollection.

  • B2RunAction

    The run number is printed at BeginOfRunAction(), where the G4RunManager is also informed how to SetRandomNumberStore for storing initial random number seeds per run or per event.

  • B2TrackerHit

    The tracker hit class is derived from G4VHit. In this example, a tracker hit is a step by step record of the track identifier, the chamber number, the total energy deposit in this step, and the position of the energy deposit.

  • B2TrackerSD

    The tracker sensitive detector class is derived from G4VSensitiveDetector. In ProcessHits() - called from the Geant4 kernel at each step - it creates one hit in the selected volume so long as energy is deposited in the medium during that step. This hit is inserted in a HitsCollection. The HitsCollection is printed at the end of each event (via the method B2TrackerSD::EndOfEvent()), under the control of the "/hits/verbose 2" command.

10.2.5.  Example B3

This example simulates a Schematic Positron Emission Tomography system.

Classes:

Geant4 Installation Guide, Chapter 3.3: Note On Geant4 Datasets
  • B3DetectorConstruction

    Crystals are circularly arranged to form a ring. A number rings make up the full detector (gamma camera). This is done by positionning Crystals in Ring with an appropriate rotation matrix. Several copies of Ring are then placed in the full detector.

    The Crystal material, Lu2SiO5, is not included in the G4Nist database. Therefore, it is explicitly built in DefineMaterials().

    Crystals are defined as scorers in DetectorConstruction::CreateScorers(). There are two G4MultiFunctionalDetector objects: one for the Crystal (EnergyDeposit), and one for the Patient (DoseDeposit).

  • B3PhysicsList

    The physics list contains standard electromagnetic processes and the radioactiveDecay module for GenericIon. It is defined in the B3PhysicsList class as a Geant4 modular physics list with registered Geant4 physics builders:

    • G4DecayPhysics
    • G4RadioactiveDecayPhysics
    • G4EmStandardPhysics

  • B3PrimaryGeneratorAction

    The default particle beam is an ion (F18), at rest, randomly distributed within a zone inside a patient and is defined in GeneratePrimaries().

  • B3EventAction , B3RunAction

    Energy deposited in crystals is summed by G4Scorer. B3EventAction::EndOfEventAction() collects information event by event from the hits collections, and accumulates statistics for B3RunAction::EndOfRunAction().

  • B3StackingAction

    Beta decay of Fluorine generates a neutrino. One wishes not to track this neutrino; therefore one kills it immediately, before created particles are put in a stack.

10.2.6.  Example B4

This example simulates a simple Sampling Calorimeter setup. To demonstrate several possible ways of data scoring, the example is provided in four variants: B4a, B4b, B4c, B4d. (See also examples/extended/electromagnetic/TestEm3).

The set of available particles and their physics processes are defined in the FTFP_BERT physics list. This Geant4 physics list is instantiated in the main() function. It requires data files for electromagnetic and hadronic processes. See more on installation of the datasets in Geant4 Installation Guide, Chapter 3.3: Note On Geant4 Datasets . The following datasets: G4LEDATA, G4LEVELGAMMADATA and G4SAIDXSDATA are mandatory for this example.

Classes:

  • B4[c, d]DetectorConstruction

    The calorimeter is a box made of a given number of layers. A layer consists of an absorber plate and of a detection gap. The layer is replicated. In addition a transverse uniform magnetic field can be applied and set via the interactive command defined using the G4GenericMessenger class.

  • B4PrimaryGeneratorAction

    The primary generator action class uses G4ParticleGun. It defines a single particle which hits the calorimeter perpendicular to the input face. The type of the particle can be changed via the G4 built-in commands of the G4ParticleGun class.

  • B4RunAction

    It accumulates statistics and computes dispersion of the energy deposit and track lengths of charged particles with the aid of analysis tools. H1D histograms are created in BeginOfRunAction() for the energy deposit and track length in both Absorber and Gap volumes. The same values are also saved in an ntuple. The histograms and ntuple are saved in the output file in a format accoring to a selected technology in B4Analysis.hh. In EndOfRunAction(), the accumulated statistics and computed dispersion are printed.

Classes in B4a (scoring via user actions):

  • B4aSteppingAction

    In UserSteppingAction() the energy deposit and track lengths of charged particles in each step in the Absober and Gap layers are collected and subsequently recorded in B4aEventAction.

  • B4aEventAction

    It defines data members to hold the energy deposit and track lengths of charged particles in the Absober and Gap layers and the data member to define the frequency of printing the accumulated quantities. Its value can be changed via the interactive command defined using the G4GenericMessenger class.

Classes in B4b (via user own object):

  • B4bRunRata

    A data class which defines data members to hold the energy deposit and track lengths of charged particles in the Absober and Gap layers. The data are collected step by step in B4bSteppingAction, and the accumulated values are entered in histograms and an ntuple event by event in B4bEventAction.

  • B4bSteppingAction

    In UserSteppingAction() the energy deposit and track lengths of charged particles in Absorber and Gap layers are collected and subsequently recorded in B4bRunData.

  • B4bEventAction

    In EndOfEventAction(), the accumulated quantities of the energy deposit and track lengths of charged particles in Absorber and Gap layers are printed and then stored in B4bRunData. It defines a data member to define the frequency of printing the accumulated quantities. Its value can be changed via a command defined in the B4bEventActionMessenger class.

Classes in B4c (via Geant4 sensitive detector and hits):

  • B4cDetectorConstruction

    In addition to materials, volumes and uniform magnetic field definitions as in B4DetectorConstruction, in DefineVolumes() two instances of the B4cCalorimeterSD class are created and associated with Absorber and Gap volumes.

  • B4cCalorHit

    The calorimeter hit class is derived from G4VHit. It defines data members to store the energy deposit and track lengths of charged particles in a selected volume.

  • B4cCalorimeterSD

    The calorimeter sensitive detector class is derived from G4VSensitiveDetector. Two instances of this class are created in B4cDetectorConstruction and associated with Absorber and Gap volumes. In Initialize(), it creates one hit for each calorimeter layer and one more hit for accounting the total quantities in all layers. The values are accounted in hits in the ProcessHits() function, which is called by the Geant4 kernel at each step.

  • B4cEventAction

    In EndOfEventAction(), the accumulated quantities of the energy deposit and track lengths of charged particles in Absorber and Gap layers are printed and then stored in the hits collections. It defines a data member to define the frequency of printing the accumulated quantities. Its value can be changed via a command defined in the B4cEventActionMessenger class.

Classes in B4d (via Geant4 scorers):

  • B4dDetectorConstruction

    In addition to materials, volumes and uniform magnetic field definitions as in B4DetectorConstruction, in DefineVolumes() sensitive detectors of G4MultiFunctionalDetector type with primitive scorers are created and associated with Absorber and Gap volumes.

  • B4dEventAction

    In EndOfEventAction(), the accumulated quantities of the energy deposit and track lengths of charged particles in Absober and Gap layers are printed and then stored in the hits collections. It defines a data member to define the frequency of printing the accumulated quantities. Its value can be changed via a command defined in the B4dEventActionMessenger class.