KAHIBARO
10.2. Particle Gun
Table of Contents
`G4ParticleGun`
In Geant4, the G4ParticleGun class provides a very simple primary particle source that you can control completely from C++ code. It is ideal for a first application, for simple test setups, and whenever you want a fixed, well defined beam or point source.
You typically create and configure a G4ParticleGun inside your PrimaryGeneratorAction class. In the constructor of your PrimaryGeneratorAction, you allocate the gun and give it default settings that will be used at the beginning of every event. A common pattern is to specify the number of primary particles per event, the particle definition, the energy, the initial position, and the momentum direction.
A minimal example looks like this, placed in the PrimaryGeneratorAction constructor:
PrimaryGeneratorAction::PrimaryGeneratorAction()
: G4VUserPrimaryGeneratorAction(),
fParticleGun(nullptr)
{
G4int nParticles = 1;
fParticleGun = new G4ParticleGun(nParticles);
// Set default particle definition, energy, position, direction later
}
The integer argument given to the G4ParticleGun constructor sets how many primary particles will be created per event by this gun. For beginners, the value is usually 1, which means one primary track per event. You can increase it if you want an event to contain several primary particles, such as two back to back particles, or a small bunch.
In the constructor or in a helper method, you then configure the gun:
auto particleTable = G4ParticleTable::GetParticleTable();
auto particle = particleTable->FindParticle("gamma");
fParticleGun->SetParticleDefinition(particle);
fParticleGun->SetParticleEnergy(1.0 * MeV);
fParticleGun->SetParticlePosition(G4ThreeVector(0., 0., -10.*cm));
fParticleGun->SetParticleMomentumDirection(G4ThreeVector(0., 0., 1.));
This defines a 1 MeV gamma starting at z = -10 cm, moving along the positive z axis.
The actual creation of primary vertices for each event happens in the GeneratePrimaries method of your PrimaryGeneratorAction class. Geant4 calls this method automatically at the beginning of every event. Inside it, you simply request the gun to generate a vertex:
void PrimaryGeneratorAction::GeneratePrimaries(G4Event* event)
{
fParticleGun->GeneratePrimaryVertex(event);
}
Each call to GeneratePrimaryVertex uses the current settings of the gun. If you change any gun parameter between events, for example to scan energies or positions, the new settings will be used for the following events.
You can combine C++ configuration with macro commands. For instance, you may set reasonable defaults in C++, then allow macro commands to overwrite them before a run starts. This lets you reuse the same code while varying particle energy, position, or direction from the command line or a macro file, without recompiling.
Important rule: Always create and configure your G4ParticleGun in the PrimaryGeneratorAction constructor (or its initialization methods), and use GeneratePrimaries only to call GeneratePrimaryVertex. Do not allocate or delete the gun inside GeneratePrimaries.
Particle type
The first essential setting of a G4ParticleGun is the particle type. Geant4 provides many predefined particle types such as photons, electrons, positrons, protons, neutrons, and ions. You choose the type with SetParticleDefinition, using the G4ParticleTable to find the particle you want.
The typical pattern is:
auto particleTable = G4ParticleTable::GetParticleTable();
auto particle = particleTable->FindParticle("e-");
fParticleGun->SetParticleDefinition(particle);
Here "e-" is the name of the particle. Common names include "gamma", "e-", "e+", "proton", "neutron", "mu+", "mu-", and many others. The G4ParticleTable stores every particle that is defined by your physics list, so you can only select particle types that your chosen physics list has already registered.
For convenience, G4ParticleTable::FindParticle also accepts the PDG integer code and pointers to existing particle definitions. For beginners, using the string names is usually the clearest method.
If you want to change the particle type during a simulation, for example to study gamma and electron response in separate runs, you can do it in several ways. One option is to modify the C++ code, change the particle name in FindParticle, and recompile. A more flexible approach is to connect the gun settings to UI commands and control them from macro files. That topic is handled elsewhere in the course, but it is useful to know that the particle type chosen through SetParticleDefinition can be updated without changing the core code.
When you change the particle type, remember that other parameters such as energy and initial direction might need to be adjusted to stay physically meaningful. For instance, a 1 MeV gamma and a 1 MeV proton behave very differently in matter, and some very low energies might be inappropriate for heavy ions or might lead to strong multiple scattering. The gun itself does not check whether your settings are realistic, it only uses them to create primary particles.
Important rule: Always ensure that the particle type you pass to SetParticleDefinition exists in the current G4ParticleTable. If FindParticle returns nullptr, the program will crash when the gun tries to generate primaries.
You are free to use multiple guns or more complex sources in advanced applications, but for a first Geant4 project the combination of a single G4ParticleGun plus a correctly chosen particle type is usually sufficient to start exploring how your detector responds to different kinds of radiation.
Views: 9