Frequentry Asked Questions

Geant4 Collaboration

Version: geant4 10.3

9 December 2016

Table of Contents

1. Installation
2. Run Time Problems
3. Geometry
4. Tracks and steps
5. Physics and cuts
6. Visualization
7. User Support Policy

Chapter 1.  Installation


When I download the source from the web, and unpack the tar file, some files unpack into the top level directory.


The problem you describe usually is the result of using "UNIX" tar to unpack the gtar ("GNU-tar") file, or vice versa, or using zip on either the gtar or tar file. Please make certain that you download the correct file for your system, and that you use the correct unpacking tool. Note that for Linux you must download the gtar.gz file.


I cannot find CLHEP files or library and I have it installed in my system.


If the standard CLHEP installation procedure has been adopted, the variable CLHEP_BASE_DIR should point to the area where include/ and lib/ directories for CLHEP headers & library are installed in your system. In case the library file name is different than the one expected (libCLHEP.a), you should either create a symbolic link with the expected name, or define the variable CLHEP_LIB in your environment which explicitly sets the name of the CLHEP library. If a non-standard CLHEP installation has been adopted, define variables CLHEP_INCLUDE_DIR, CLHEP_LIB_DIR (and CLHEP_LIB) to refer explicitly to the place where headers, library (and library-name) respectively are placed in your system. On Windows systems, the full library file name (with extension) should be specified as CLHEP_LIB, while for UNIX-like systems, just the name is required (i.e. CLHEP for libCLHEP.a).


While installing the Geant4 libraries I get the following message printed:

         gmake[1]: cernlib: Command not found

Has Geant4 been installed properly ? What to do to solve this error ?


The message:

         gmake[1]: cernlib: Command not found

shows that you don't have the 'cernlib' command installed in your system; 'cernlib' is a command from the CERN program library (cernlib) returning a list of libraries needed to link a cernlib application. This command is only used in the 'g3tog4' module, however, if you do not make use of the 'g3tog4' tool, it's harmless. The cernlib script (and the needed cernlib libraries) are available from


Trying building the Geant4 libraries I see several of these errors appearing and my installation fails:

         .....G4Exception.d:1: *** missing separator. Stop.
         ...../G4DalitzDecayChannel.d:1: *** missing separator. Stop.

Has Geant4 been installed properly ? What to do to solve this error ?


It looks like some file dependencies (.d) are corrupted, possibly due to previous build attempts which failed for some reason. You need to remove each of them. A quick recipe for doing this is to:

  • Configure the environment with the installation to be repaired

  • Unset the G4WORKDIR environment variable (in case it is eventually set)

  • Type:

            gmake clean dependencies=''

    from the affected module (i.e. for this case, from $G4INSTALL/source/global/management and $G4INSTALL/source/particles/management) and rebuild. Alternatively, you may use:

            gmake clean dependencies=''

    from $G4INSTALL/source and rebuild.

Chapter 2.  Run Time Problems


On Linux, I get a segmentation fault as soon as I run one of the official examples.


Check that the CLHEP library has been installed and compiled coherently with the same compiler you use for installing Geant4 and for the same version of Linux distribution. For example, a binary object produced with Red-Hat 7.X is not fully compatible with binaries running on RH 9.X or higher, due to different libc used in the two configurations.


I installed Geant4 libraries and built my application, when I try to run it I get:

         error in loading shared libraries: cannot open shared object file:
         No such file or directory.


Your installation of CLHEP includes shared libraries. You need to specify the path where is installed through your environment variable LD_LIBRARY_PATH. For example, in tcsh UNIX shell:



On my system I get a Floating Point Exception (FPE) since some physics processes sometimes return DBL_MAX as interaction length and this number is afterwards multiplied by a number greater than 1.


Geant4 coding conventions and installation setup explicitly follow the ANSI/IEEE-754 Standard for the initialization of floating-point arithmetic hardware and portability. The Standard foresees floating-point arithmetic to be nonstop and underflows to be gradual. On DEC platforms, for example, the ANSI/IEEE-754 Standard compliance needs to be explicitly set (since deactivated by default); in this case we use infact the option "-ieee" on the DEC/cxx native C++ compiler to achieve this. You should check if your compiler provides compilation options for activating Standard initialization of FP arithmetic (it may be platform specific).

Chapter 3.  Geometry


I have a generic point and I would like to know in which physical volume I'm located in my detector geometry.


The best way of doing this is by invoking the G4Navigator. First get a pointer of the navigator through the G4TransportationManager, and then locate the point. i.e.

     #include "G4TransportationManager.hh" 
     #include "G4Navigator.hh" 
     G4ThreeVector myPoint = ....;
     G4Navigator* theNavigator = G4TransportationManager::GetTransportationManager()
     G4VPhysicalVolume* myVolume = theNavigator->LocateGlobalPointAndSetup(myPoint); 


by using the navigator for tracking as shown above, the actual particle gets also -relocated- in the specified position. Therefore, if this information is needed during tracking time, in order to avoid affecting tracking, you should either use an alternative G4Navigator object (which you then assign to your world-volume), or you access the information through the track or touchable as specified in the FAQ for tracking and steps.


How can I access the daughter volumes of a specific physical volume?


Through the associated logical volume.

      G4VPhysicalVolume* myPVolume = ....; 
      G4LogicalVolume* myLVolume = myPVolume->GetLogicalVolume(); 
      for (G4int i=0; iGetNoDaughters(); i++)  
        myPVolume = myLVolume->GetDaughter(i); 


How can I identify the exact copy-number of a specific physical volume in my mass geometry? I tried with GetCopyNo() from my physical volume pointer, but it doesn't seem to work!


The correct way to identify -uniquely- a physical volume in your mass geometry is by using the touchables (see also chapter 4.1.5 of the User's Guide for Application Developers), as follows:

      G4Step* aStep = ..;
      G4StepPoint* preStepPoint = aStep->GetPreStepPoint();
      G4TouchableHandle theTouchable = preStepPoint->GetTouchableHandle();
      G4int copyNo = theTouchable->GetCopyNumber();
      G4int motherCopyNo = theTouchable->GetCopyNumber(1);

where Copy here stays for any duplicated instance of a physical volume, either if it is a G4PVPlacement (multiple placements of the same logical volume) or a G4PVReplica/G4PVParameterised. The method GetCopyNo() is meant to return only the serial number of placements not duplicated in the geometry tree.


How can I determine the exact position in global coordinates in my mass geometry during tracking and how can I convert it to coordinates local to the current volume ?


You need again to do it through the touchables (see also chapter 4.1.5 of the User's Guide for Application Developers), as follows:

      G4Step* aStep = ..;
      G4StepPoint* preStepPoint = aStep->GetPreStepPoint();
      G4TouchableHandle theTouchable = preStepPoint->GetTouchableHandle();
      G4ThreeVector worldPosition = preStepPoint->GetPosition();
      G4ThreeVector localPosition = theTouchable->GetHistory()->

where worldPosition here stays for the position related to the world volume, while localPosition refers to the coordinates local to the volume where the particle is currently placed.

Chapter 4.  Tracks and steps


How can I access the track information through the step object and what information am I allowed to access ?


A G4Step object consists of two points:

      G4StepPoint* point1 = step->GetPreStepPoint();
      G4StepPoint* point2 = step->GetPostStepPoint();

To get their positions in the global coordinate system:

      G4ThreeVector pos1 = point1->GetPosition();
      G4ThreeVector pos2 = point2->GetPosition();

Hereafter we call current volume the volume where the step has just gone through. Geometrical informations are available from preStepPoint. G4VTouchable and its derivates keep these geometrical informations. We retrieve a touchable by creating a handle for it:

      G4TouchableHandle touch1 = point1->GetTouchableHandle();

To get the current volume:

       G4VPhysicalVolume* volume = touch1->GetVolume();

To get its name:

      G4String name = volume->GetName();

To get the physical volume copy number:

      G4int copyNumber = touch1->GetCopyNumber();

To get logical volume:

      G4LogicalVolume* lVolume = volume->GetLogicalVolume();

To get the associated material: the following statements are equivalent:

      G4Material* material = point1  ->GetMaterial();
      G4Material* material = lVolume ->GetMaterial();

To get the geometrical region:

      G4Region* region = lVolume->GetRegion();

To get its mother volume:

      G4VPhysicalVolume* mother = touch1->GetVolume(depth=1);
      grandMother: depth=2 ...etc...

To get the copy number of the mother volume:

      G4int copyNumber = touch1->GetCopyNumber(depth=1);
      grandMother: depth=2 ...etc...

To get the process which has limited the current step:

      G4VProcess* aProcess = point2->GetProcessDefinedStep();

To check that the particle has just entered in the current volume (i.e. it is at the first step in the volume; the preStepPoint is at the boundary):

      if (point1->GetStepStatus() == fGeomBoundary) 

To check that the particle is leaving the current volume (i.e. it is at the last step in the volume; the postStepPoint is at the boundary):

      if (point2->GetStepStatus() == fGeomBoundary)

In the above situation, to get touchable of the next volume:

      G4TouchableHandle touch2 = point2->GetTouchableHandle();

From touch2, all informations on the next volume can be retrieved as above.

Physics quantities are available from the step (G4Step) or from the track (G4Track).

To get the energy deposition, step length, displacement and time of flight spent by the current step:

      G4double eDeposit      = step->GetTotalEnergyDeposit();
      G4double sLength       = step->GetStepLength();
      G4ThreeVector displace = step->GetDeltaPosition();
      G4double tof           = step->GetDeltaTime();

To get momentum, kinetic energy and global time (time since the beginning of the event) of the track after the completion of the current step:

      G4Track* track         = step->GetTrack();
      G4ThreeVector momentum = track->GetMomentum();
      G4double kinEnergy     = track->GetKineticEnergy();
      G4double globalTime    = track->GetGlobalTime();


To transform a position from the global coordinate system to the local system of the current volume, use the preStepPoint transformation, as described in the geometry chapter above.


How can I get and store (or plot) informations at tracking time from a given volume ?


To get the information at tracking time in a given volume A, one can adopt either one or a combination of the following strategies:

  1. If the geometry is simple enough, and wish to score some commonly used physics quantities (e.g. energy deposition, dose, flux, etc.), just activate G4ScoringManager in your main program, and use the scorer-based UI commands to transform volume A into a scorer.

    See Option 6 below, and the example examples/extended/runAndEvent/RE03.

  2. Through the SteppingAction, check that the particle is inside volume A and do whatever needed. Hints can be found in the previous chapter of this FAQ document.

    Usually, the hits containers and histograms are attributes of a Track, Event or Run and can be managed through either a TrackingAction, EventAction and/or RunAction and eventually messaging their pointer to the SteppingAction.

    A similar approach is illustrated in examples/basic/B2, B4, extended/electromagnetic, optical, and many others...

  3. In DetectorConstruction, by declaring volume A as a SensitiveDetector. At stepping time, the Geant4 kernel will automatically check that a particle is inside volume A and will handle the control to a specific function G4VSensitiveDetector::ProcessHits(). It is just necessary to instanciate a class inherited from G4VSensitiveDetector, say VolumeA_SD, and do whatever needed by implementing the function VolumeA_SD::ProcessHits(), as described in Option 2 above.

  4. In addition to Option 3 above, should create a HitsCollection to store the information. A HitsCollection can be created in VolumeA_SD::Initialize(). A Hit can be created or filled in VolumeA_SD::ProcessHits(). Additional operations on HitsCollection can be performed in VolumeA_SD::EndOfEvent().

    This approach is illustrated in examples/basic/B2, B4 and extended/analysis, extended/runAndEvent/RE01, etc...

  5. In DetectorConstruction, volume A can be declared as SensitiveDetector, and one or several pre-defined scorers can be attached to volume A. In this case, neither a SteppingAction nor a spcific VolumeA_SD sensitive detector is needed any longer. It is just necessary to create a dedicated scorer, e.g. MyRunScorer, inherited from G4Run, and handle the HitsCollections within MyRunScorer::RecordEvent(). MyRunScorer itself can be instanciated from RunAction::GenerateRun().

    This approach is illustrated in examples/novice/N07, extended/runAndEvent/RE02.

  6. A set of build-in scorer-based UI commands allows to perform most possible operations described through the previous Option 5 directly from run-time macros.

    See example extended/runAndEvent/RE03.

Chapter 5.  Physics and cuts


How do production cuts (in range) work in Geant4 ? Are they also used in tracking ? If a particle has an energy lower than the converted cut in energy for the given material and the distance to the next boundary is smaller than the cut in range, is the particle killed ?


Geant4 does NOT have a "tracking cut". The toolkit's default behaviour is to track particles down to zero range (i.e. zero energy). Of course, it is possible for the user to create and register a process that kills particles below a certain energy or range; this is however NOT provided by default in Geant4. So there's NO "tracking cut". For example, suppose a particle that is nearing zero energy will at some point be proposed by its Ionisation process to undergo one final step, from its current energy down to zero energy. This is still only a proposal. If during this step the particle crosses a boundary, then the transportation will limit the step at a length smaller than the Ionisation -- so the particle will still see and cross the relevant boundary, and another step will occur on the other side of that boundary. In summary the "production threshold" range and its equivalent in energy are not utilised as a "tracking cut". A particle is not abandoned by Geant4 below a certain range/energy unless the user registers a process to do this by him/her-self.

Chapter 6.  Visualization


I have set G4VIS... environmental variables but visualization does not appear to be enabled.


This might be because you set the environment variables after already compiling. The environment variables control C-pre-processor macros of the same name and therefore influence what code gets compiled. It is suggested to proceed with the following manual procedure to correct the current installation:

  • Configure the environment according to the installation making sure to -unset- the G4WORKDIR environment variable, if set.

  • Verify and eventually set the environment variables of the visualization module [name] concerned (setenv or export both G4VIS_BUILD_[name]_DRIVER and G4VIS_USE_[name] variables according to the UNIX shell used), and then proceed as follows:

          cd $G4INSTALL/source/visualization
          gmake clean
          cd $G4INSTALL/source/interfaces
          gmake clean
          cd $G4INSTALL/source
          gmake libmap
          setenv G4WORKDIR [your working directory]   (or export)
          cd [your application directory]
          gmake clean


While visualizing my geometry setup I often see the following error message printed out:

  BooleanProcessor: boolean operation failed . 


There is a known limitation for the visualization of Boolean solids in the so-called BooleanProcessor which is used to make polyhedra for visualisation. It does not affect the tracking which is done through such solids. So the error message you see does not affect the simulation in any way. The workaround is to move one of the affected solids by a small distance in order to avoid shared surfaces.

Chapter 7.  User Support Policy


How do I contribute an FAQ to this page?


This is done manually at the moment. Please send your FAQ with solution to the Documentation Working Group.


If I need to discuss technical matters specific to my simulation application or ask for first-aid help, who can I contact?


Every institute and experiment participating in Geant4 has a G4 Technical Steering Board (TSB) representative who may be contacted for help with problems relating to simulations. Please contact the TSB representative closest to your project or to your laboratory. To find out who your TSB representative is go to G4 Technical Board. You may also post your question in the Geant4 HyperNews Forum.


If I find a bug or other problem with the code, who should be informed?


The Geant4 problem tracking system will forward the bug report to the person responsible for the affected Geant4 domain. The Geant4 web makes available a database of open incident reports, tagging the ones already fixed and showing their status. An acknowledgement of the bug report will be sent.


If I propose a fix, who is responsible for approving it?


The responsible person is the working group coordinator of the domain in which the fix is to be applied. This person is usually also a TSB member. If the fix affects more than one domain, the matter will be addressed by the TSB.


To whom should I send a proposal for an improvement in Geant4 functionality?


Any new requirement should be submitted via the automatic web system. It will be discussed at the Geant4 TSB. You may also ask your TSB representative to forward your requirement to the TSB. A new requirement will trigger a cycle of analysis, design, implementation, testing and documentation, which may involve different working groups. Any new software or enhancement which will become a part of Geant4 must be agreed upon by the TSB, which is charged with ensuring the consistency of the entire toolkit.


Is there a regular user meeting which I should attend?


There is one Geant4 Collaboration Workshop per year, and one or two Geant4 Technical Forum meetings. These will be announced in the Events section of the Geant4 Web. However, many experiments and institutes in the Geant4 collaboration organize their own regular and/or special Geant4 user workshops.


Where can I find solutions to particular problems as well as general user support?


Solutions and tips for solving practical problems can be found on the current FAQ page. General and specific user support information is available at the User Support page.


What is the proper way to cite GEANT4 in my journal or conference paper?


The two main reference papers for Geant4 are published in Nuclear Instruments and Methods in Physics Research A 506 (2003) 250-303, and IEEE Transactions on Nuclear Science 53 No. 1 (2006) 270-278.