View on GitHub

GEARS | 齿轮组

Geant4 Example Application with Rich features and Small footprints

Download this project as a .zip file Download this project as a tar.gz file

YouTube alpha beta gamma muon neutron optical decay X-ray


  1. physics model: what happens in a certain energy range
  2. physics process: model + cross section (how often it happens)
  3. physics list: a list of processes for common particles
  4. modular lists: lists of processes that can be used as building blocks to construct a more complex list
  5. pre-packaged lists: official modular lists shipped with Geant4
  6. reference lists: a subset of the pre-packaged lists that are well-maintained and tested
  7. factory: a Geant4 class that can be used to call pre-packaged lists by their names

How to choose a physics list

GEARS uses to allow the user to select one from the pre-packaged lists by its name:

  # select a pre-packaged physics list. For example,
  # LBE: low background experiment
  # LIV: EM model based on Livermore data
  /physics_lists/select LBE_LIV
  # initialize physics based on the list
  # dump the lists on screen

The available names are listed in The naming scheme is introduced on page 24 in this tutorial. A guidance on how to choose a proper physics list is also available in the tutorial.

Physics processes

Major categories of processes provided in Geant4 include:

A unique process id is assigned to each process in a GEARS output.

Run /process/list after /run/initialize, you will get something like this:

     Transportation,              Decay,   RadioactiveDecay,                msc
              hIoni,            ionIoni,             hBrems,          hPairProd
        CoulombScat,              eIoni,              eBrem,            annihil
               phot,              compt,               conv,             muIoni
            muBrems,         muPairProd,         hadElastic,   neutronInelastic
           nCapture,           nFission,    protonInelastic,       pi+Inelastic
       pi-Inelastic,     kaon+Inelastic,     kaon-Inelastic,    kaon0LInelastic
    kaon0SInelastic,    lambdaInelastic,anti-lambdaInelastic,   sigma-Inelastic
anti_sigma-Inelastic,    sigma+Inelastic,anti_sigma+Inelastic,     xi-Inelastic
  anti_xi-Inelastic,       xi0Inelastic,  anti_xi0Inelastic,    omega-Inelastic
anti_tritonInelastic,  anti_He3Inelastic,anti_alphaInelastic

Now you can use, for example, /process/inactivate nCapture to disable neutron capture process in your simulation. And you can use, for example, /process/setVerbose 20 RadioactiveDecay to change the verbosity of the radioactive decay process.

Radioactive decay


Radioactive decay processes can be enabled after a reference list is chosen:

 # choose a reference physics list
 /physics_lists/select QGSP_BERT_EMV
 # cmd below becomes available only when the cmd above is used
 # must be run after the cmds above

 /process/list Decay
   Decay    RadioactiveDecay

Detailed control of radioactive decay is provided by the /grdm/ command, for example,

/grdm/deselectVolume chamber # disabled radioactive decay in volume "chamber"
/grdm/nucleusLimits 1 80 # enabled radioactive decay only when z in [1, 80]

Here is an example to create Pb210 on the surface of a cylindrical CsI detector:

 /gps/particle ion
 /gps/ion 82 210
 # default energy is 1 MeV, must be set to zero to let it decay at rest
 /gps/energy 0

 /gps/pos/type Surface
 /gps/pos/shape Cylinder
 /gps/radius 7 cm
 /gps/halfz 2.5 cm

Split decay chain

Some isotopes in a radioactive decay chain have long half lives. They decay long after the first decay on top of the chain. However, Geant4 simulate the whole chain in one event. It is the user’s task to split different decays in the chain to different events based on the times when they happen.

GEARS provides a macro command /grdm/setTimeWindow for you to split the chain based on a time window specified by you:

 # choose a reference physics list
 /physics_lists/select QGSP_BERT_EMV
 # cmd below becomes available only when the cmd above is used
 # must be run after the commands above

 # If a decay that happens 1 second after its previous one,
 # it is saved to another event in the output n-tuple
 # The command can be run before or after /run/initialize,
 # but only becomes available after radioactive decay is enabled
 /grdm/setTimeWindow 1 s

 # a time window <= 0 will disable splitting:
 # /grdm/setTimeWindow 0
 # show detailed instruction of this command:
 help /grdm/setTimeWindow

 # turn on tracking and event verbose
 # to understand Geant4 tracking and stacking processes
 /tracking/verbose 2
 /event/verbose 2
 # record output to check the splitting result
 /analysis/setFileName output
 # simulate just one or a few events to check result
 /run/beamOn 1

Example macro and detector definition files can be found in GEARS/tutorials/physics/decay folder. The following is an example analysis code to show the recorded events in ROOT:

root [] t->Scan("pdg:trk:pid:stp:dt/1e9:t/1e9","","colsize=10 precision=10")

For people who want to understand how this is done, please check the GEARS doxygen page of StakingAction and the following Geant4 help pages:

For the impatient, new particles created after the specified time window in a decay process will be tagged as fWaiting in G4UserStackingAction::ClassifyNewTrack(). This postpones the tracking of them after the call of G4UserStackingAction::NewStage(). One can then save and reset the current event in the NewStage() function so that the postponed tracks will be saved in a separate event.

Stop decay chain

If the half life of a daughter nucleus is longer than a measurement duration, there is no need to simulate its decay anymore. In this case, instead of splitting its decay to another event, we should simply stop its radioactive decay completely. This is done using a Geant4 macro command /grdm/nucleusLimits, for example,

# enable radioactive decay physics
/physics_lists/select QGSP_BERT


# start with the alpha decay of Am-241
/gps/particle ion
/gps/ion 95 241
/gps/energy 0
# since Np-237, the daughter of Am-241, is not in the following range,
# it will not alpha-decay into its daughter nucleus in this simulation.
# The simulation will stop when Np-237 decays into its ground state.
/grdm/nucleusLimits 241 241 95 95

Optical processes


Optical processes can be enabled after a reference list is chosen:

 # based on Geant4 example OpNovice2 (EMZ: option4 of EM)
 /physics_lists/select QGSP_BERT_EMZ
 # cmd below becomes available only when the cmd above is used
 # must be run after the cmds above

 /process/list Electromagnetic
   phot,              compt,               conv,                msc
   eIoni,              eBrem,        CoulombScat,            annihil
   muIoni,            muBrems,         muPairProd,              hIoni
   hBrems,          hPairProd,            ionIoni,           Cerenkov

 /process/list Optical
   OpAbsorption,   OpRayleigh,            OpMieHG,         OpBoundary

Individual optical processes can be toggled by the following commands:

/process/optical/processActivation Cerenkov true/false
/process/optical/processActivation Scintillation true/false
/process/optical/processActivation OpAbsorption true/false
/process/optical/processActivation OpRayleigh true/false
/process/optical/processActivation OpMieHG true/false
/process/optical/processActivation OpBoundary true/false
/process/optical/processActivation OpWLS true/false

More built-in commands related to optical processes can be found here. Example usages can be found here.

It is useful to categorize the processes the following way:

It is also important to understand that optical photons are treated differently from gamma and x-rays in Geant4, since completely different physics processes are assigned to them.

Optical properties of materials and surfaces

To generate Cerenkov light, one HAS TO specify the refractive index of the material where the light is generated. In GEARS, this is done in the detector geometry description file.

At least two parameters need to be specified to generate scintillation light: the light yield, i.e., the number of photons per unit energy deposition (SCINTILLATIONYIELD), and the variation of the number of generated photons (RESOLUTIONSCALE). The parameters need to be attached to the material that scintillates, they are hence specified in the detector geometry description file as well.

The parameter, RAYLEIGH and ABSLENGTH, related to the transportation of optical photons in a mertial also have to be attached to the material.

In an ideal optical interface, the transportation of optical photons can be calculated given the refractive indices of the matierials on both sides. To simulate more complicated interfaces, please see here.

Example macros