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

Terminology

  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. reference lists: official modular lists shipped with Geant4
  6. factory: a Geant4 class that can be used to call reference lists by their names

How to choose a physics list

GEARS uses G4PhysListFactory.cc to allow the user to select one from the reference lists using an environment variable PHYSLIST before the gears executable:

$ PHYSLIST=FTFP_BERT_EMZ gears

**************************************************************
 Geant4 version Name: geant4-11-03 [MT]   (6-December-2024)
                       Copyright : Geant4 Collaboration
                      References : NIM A 506 (2003), 250-303
                                 : IEEE-TNS 53 (2006), 270-278
                                 : NIM A 835 (2016), 186-225
                             WWW : http://geant4.org/
**************************************************************

G4PhysListFactory::GetReferencePhysList <FTFP_BERT_EMZ>  EMoption= 4
<<< Geant4 Physics List simulation engine: FTFP_BERT
...
PreInit> /run/initialize
Idle> /run/beamOn

where /run/initialize initializes physics based on the list, and /run/beamOn dumps the list on screen.

Available reference lists can be found in G4PhysListFactory.cc. 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_omega-Inelastic,anti_protonInelastic,anti_neutronInelastic,anti_deuteronInelastic
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

YouTube

Radioactive decay processes can be enabled before run/initialize:

PreInit> /physics_lists/factory/addRadioactiveDecay
PreInit> /run/initialize
Idle> /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/pos/radius 7 cm
 /gps/pos/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
 /physics_lists/factory/addRadioactiveDecay
 # must be run after the commands above
 /run/initialize

 # 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
/physics_lists/factory/addRadioactiveDecay

/run/initialize

# 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

YouTube

Optical processes can be enabled before /run/initialize:

 /physics_lists/factory/addOptical
 /run/initialize

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

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

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 MUST 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