HOWTO force hdgeant4 to decay particles in certain channels
Geant4 defines all of the common particles that one would want to propagate through an experimental setup as instances of the G4ParticleDefinition class. Common particle types that are derived from G4ParticleDefinition include singleton classes G4Electron, G4Positron, G4PionPlus, G4Eta, and G4JPsi. Nested under subclass G4Ions are additional singleton classes such as G4Proton, G4Neutron, G4Deuteron, G4Alpha, and G4GenericIon for any non-lived isotope with Z>4. In addition to anti-particles like G4AntiProton, there are also so-called "adjoint" particles like G4AdjointElectron and G4AdjointGamma. These adjoint particles are not anti-particles, they are introduced into the G4 framework as particles that are simulated backwards in time. These are not currently used in the GlueX simulation, but I include them in this overview for completeness.
Particle decays are handled in two distinct ways within the hdgeant4 simulation framework. In some cases, the decay takes place in the Monte Carlo generator at the primary event vertex, before the list of final-state particles from the primary vertex is written out for input into the hdgeant4 simulation. In this case, complete control over the permissible decays and branching fractions is assigned to the generator, with simple hooks provided through the generator configuration file to allow the user to change them. In many cases, however, full control over the allowed decays and branching fractions is not possible outside of hdgeant4,
- when the decaying particle has a proper lifetime > 1um / c, so there is the possibility of a displaced decay vertex that might be resolved by the detector;
- even if the decaying particle has a proper lifetime << 1um / c, it might be itself the decay product of a parent particle that might have a displaced vertex.
In such cases, it is imperative that the user have control over the in-flight decays of all unstable particles in the hdgeant4 simulation. All of the pre-defined particle types in Geant4 (and Geant3) are preconfigured with an extensive set of known decays taken from the Particle Data Group tables. These data are contained within instances of G4DecayTable, one for each unstable particle type which, when combined with the proper lifetime and a stable/unstable flag, control how in-flight decays are generated during particle tracking. Normally one should not need to modify these tables for any of the standard particles that would be tracked in a detector simulation. Exceptions occur, however, when an analysis is designed to target one specific branch of a decay chain from a primary particle. Only events from that one branch are of interest in estimating the acceptance for such an analysis, and simulating the entire decay tree to study just the events from one branch can be a major waste of resources.
In the instructions that follow, I assume that the user want to turn off certain decay modes of an unstable particle, so as to isolate a set of events that belong to a specific branch of the decays of one type of particle. It is easy to generalize these instructions to cover a case where more than one decay in the decay sequence needs to be specified. In each case, one or more singleton G4ParticleDefinition objects is selected corresponding to the particle type whose decays are to be modified, and the G4DecayTable for that object is modified. One caveat is that this method does not permit the selection of specific instances of a list of final-state particles to be overwritten. In the example below, modifying the G4KaonZero decay table will affect all neutral kaons in the simulation, including all that come from the primary vertex and those that emerge further down the chain as decay products or as products of interactions in the detector material. Normally this is not a problem for reactions of interest to GlueX analyses, but users should bear this in mind whenever employing this technique.
In the example below, I consider a simulation of exclusive Sigma+,kshort production in which I want to isolate events in which the kshort decays to 2pi0. The branching ratio for this decay is less than 1/3, so to avoid wasting time simulating irrelevant events I decide to turn off the dominant decay mode of the kshort to charged pions. The simplest way to do this is to start hdgeant4 in interactive mode and wait for it to stop at the Idle prompt. I then enter a few interactive commands to examine the standard decay modes of the kshort particle, turn off the unwanted decay modes, and dump the modified decay table to make sure that the changes were accepted. I then need to change the proper lifetime of the kshort to reflect its longer decay length due as a consequence of disabling the unwanted decay modes. Once this is done, any events simulated in this session will be processed with the modified kshort particle.
$ hdgeant4 -i [ several lines of printout suppressed here ] Setting up cross section tables, please wait... finished. Idle> /particle/select kaon0S Idle> /particle/property/decay/dump G4DecayTable: kaon0S 0: BR: 0.692 [Phase Space] : pi+ pi- 1: BR: 0.3069 [Phase Space] : pi0 pi0 Idle> /particle/property/decay/select 0 Idle> /particle/property/decay/br 0 Idle> /particle/property/decay/select 1 Idle> /particle/property/decay/br 1 Idle> /particle/property/decay/dump G4DecayTable: kaon0S 0: BR: 0 [Phase Space] : pi+ pi- 1: BR: 1 [Phase Space] : pi0 pi0 Idle> /particle/property/lifetime 0.2918 ns Idle> /run/beamOn 1000 Idle> exit
The above prescription assumes that the desired decay mode is already included in the predefined list for the unstable particle type. It is also possible to add new decay modes to the predefined list for a particle type, but that is not possible using the interactive interface. To see how to do that, refer to the static method G4KaonZeroShort::Definition for an example of how to construct new G4VDecayChannel instances and add them to the G4DecayTable for an unstable particle type. The new code should be added to the main program hdgeant4.cc right after the section "Initialize the G4 kernel" and before "Start the user interface". Do not forget to invoke G4ParticleDefinition::SetPDGLifeTime to set the new particle lifetime whenever you change the branching ratios away from their predefined values.