35.5. Configure the Particle Source

Table of Contents

Choosing an Appropriate Source for Your Final Project

Configuring the particle source is where you connect your physics goal to the simulation. At this stage of the final project you already know what you want to study and you have a basic geometry and materials. Now you must decide what particles to generate, with which energies, from where, and in which directions, so that the simulation actually probes your detector or phantom in a meaningful way.

Begin from your project goal. If you are reproducing a measurement or published result, look carefully at the experimental conditions: particle type, energy spectrum, beam geometry, and angular distribution. If you are designing a detector, think about the range of energies and angles that are relevant for its intended use. The more closely your source configuration matches the real or intended scenario, the more useful your simulated data will be.

For many final projects, it is reasonable to start with a simple, idealized source such as monoenergetic particles with a fixed direction, and then refine toward more realistic distributions only once the rest of the setup is working. Keep that strategy in mind to avoid overcomplicating the early debugging phase.

Your particle source configuration must always be consistent with your physics list and geometry, or the results will be misleading even if the code runs correctly.

Choosing Between a Particle Gun and GPS

In Geant4 you typically implement the primary source in your PrimaryGeneratorAction class. Inside this class, you usually choose between two main tools: G4ParticleGun and G4GeneralParticleSource (GPS).

G4ParticleGun is simple and controlled from C++ code. It is ideal when you need a single particle type with a fixed or programmatically defined energy, position, and direction. It is often the best first choice for a final project, especially if you are still becoming comfortable with C++ and Geant4. You configure it once in the constructor of your PrimaryGeneratorAction, then use it in GeneratePrimaries to shoot particles into each event.

G4GeneralParticleSource is much more flexible and is configured primarily through macro commands. It can produce complicated spatial, angular, and energy distributions, and it can manage multiple components within a single logical source. This makes GPS very useful when your final project requires realistic beams, extended sources, or user-defined spectra, and when you want to explore different source configurations without recompiling.

A practical strategy for the final project is to implement the logic for selecting between these two options. For example, you can add a configuration flag or a macro command that switches between a simple particle gun mode and a GPS mode, so that you can easily test your geometry and physics with a basic source before moving to a more complex, realistic one.

Use G4ParticleGun if you want simplicity and full C++ control. Use G4GeneralParticleSource if you need complex distributions and flexible macro-based configuration.

Defining Particle Type and Energy Range

Once you have chosen the tool, you must define which particles you are going to generate and with what energies. This should come directly from your final project’s physics question. For example, a PET-like project will mainly use positrons or 511 keV gamma rays, a radiotherapy project will use megavolt photons or hundreds-of-MeV protons, and a shielding project will require gamma rays or neutrons over a specific energy range.

In C++, you obtain the particle definition from the Geant4 particle table. With a particle gun this is normally done once in the PrimaryGeneratorAction constructor by asking the G4ParticleTable for the desired particle name, then setting it on the gun. With GPS, you select the particle type from a macro command such as /gps/particle gamma. In either case, make sure that the chosen particle is supported by your physics list. If you require ions or exotic particles, confirm that the corresponding constructors or physics options are present in your physics configuration.

Energy is equally important. Decide whether your final project needs monoenergetic particles, a narrow band around a nominal energy, or a broad spectrum. For simple detector response or depth-dose studies, a single energy or a few discrete energies can be sufficient. For realistic background or medical imaging sources, you may need a known spectrum, which you can approximate with a histogram or user-defined distribution in GPS.

When specifying energies, always use the Geant4 unit system. For example, use 1.0*MeV in C++ or 1 MeV in a macro. This keeps your code and scripts clear and avoids subtle mistakes from mixing units.

Always match your particle type and energy range to your project goal and to the capabilities of your chosen physics list.

Setting Source Position and Geometry

The spatial configuration of your source strongly influences the outcome of the simulation. You must define where the particles are created relative to your geometry, and whether the source is a point, a surface, or a volume distribution.

For a simple beam entering a detector or phantom, you can use a point source located just outside the entrance face. In C++, with a particle gun, you set a fixed position vector as the gun position, typically in the lab (world) coordinate system. With GPS you can define a point source directly from macro commands. This is often sufficient for preliminary studies and for verifying that your detector records hits where you expect.

If your final project describes an extended beam or a radioactive sample with a finite size, consider a surface or volume source. With GPS you can define a plane or a disk and restrict emission to that surface, or define a cylinder or box volume within which primary vertices are randomly distributed. When using such sources, make sure that the defined source region is entirely inside or properly aligned with your world and detector geometry to avoid particles being generated in empty space or outside the world volume.

It is good practice to visualize the source location using the Geant4 visualization system. Draw your geometry and then display a few events to check that primaries are generated where you expect. Misplaced sources are a very common cause of puzzling “no hits” or “no energy deposition” problems.

Carefully align the source position with your detector geometry and verify it visually before trusting the simulation results.

Configuring Angular and Spatial Distributions

In many final projects the angular distribution of the source matters as much as its position. For a narrow beam you typically want all particles to travel in the same direction, usually along a coordinate axis directed toward your detector or phantom. With the particle gun you enforce this by setting a fixed momentum direction vector. With GPS you configure a directional distribution that points in the desired direction.

If your project is about isotropic or quasi-isotropic radiation, such as environmental background, scattered radiation, or uniformly emitting radioactive material, you should explicitly configure an isotropic angular distribution. GPS makes this straightforward through dedicated macro commands that describe angular distributions. If you keep the default settings of a particle gun or GPS without checking, you might unintentionally create a pencil beam instead of an isotropic source, or vice versa.

Spatial distributions are similarly important. For example, in a PET-related project, the annihilation point distribution within the object is key, while in a shielding project the lateral extent of the incident beam can change the observed transmission if the detector has a finite size. Use volume and surface source definitions in GPS or, if necessary, custom sampling in C++ to match the spatial characteristics of the physical situation you are modeling.

When designing these distributions, think about whether the details will influence the quantity you plan to analyze. If your final observable is integrated over a large detector area, a small beam spot versus a larger beam may not matter. On the other hand, if you are studying spatial resolution, the exact shape and spread of the source become critical.

Define angular and spatial distributions that reflect the physical scenario you want to study, and verify that they are correctly implemented.

Using Macro Commands for Source Configuration

For a flexible final project, you should avoid hard-coding all source parameters into C++. Instead, expose as much as possible through macro commands so that you can change particle type, energy, positions, and directions without recompiling. This makes it easier to perform parameter scans and systematic studies.

When using GPS, most configuration is naturally done from macros. You will typically create a macro file that sets the particle, energy distribution, position distribution, and angular distribution using /gps/... commands. You can then run different macros for different configurations within the same compiled application. It is helpful to keep these macro files well organized and to name them according to their purpose, for example source_mono_1MeV.mac or source_isotropic_spectrum.mac.

Even if you rely on a particle gun, you can still connect macro commands to your PrimaryGeneratorAction. For instance, you can implement user interface commands, or read parameters from environment variables or configuration files before the run starts, and use them to set the gun’s energy or direction. This takes more C++ work than using GPS, but gives you complete control over the generation logic.

As you refine your final project, you will probably want to compare different source conditions, such as several energies or geometries. Prepare a small library of macro files that differ only in the source commands and keep the rest of the run configuration, such as physics and analysis, identical. This simplifies comparisons and reduces the chance of accidental inconsistencies.

Use macro commands to control your source wherever possible, so you can change configurations without recompiling and maintain a clean, reproducible workflow.

Testing and Validating the Source Configuration

Before collecting large statistics for your final project, invest time in testing and validating the source configuration itself. This step is crucial because errors in the source setup can invalidate the entire study even if everything else is implemented correctly.

Use a small number of events to check the following points. First, visualize particle trajectories in your geometry. Turn on track visualization and run a few tens of events. Confirm that primaries appear at the correct positions, with the correct directions, and that they interact with the expected parts of the geometry. Second, print diagnostic information from your PrimaryGeneratorAction for the first few events. You can temporarily log the particle name, energy, position, and direction to the console to confirm that they match your intended configuration.

Next, compare the effective source behavior with simple expectations. For a monoenergetic narrow beam, you should see a well-defined entry region and roughly uniform energy deposition along that line, modulated by material interactions. For an isotropic source, your detected events should be distributed over solid angle as you expect. If you have defined an energy spectrum, build a quick histogram of the primary energies using the analysis system and confirm that it matches the input shape.

Finally, think about reproducibility. For debugging and validation runs, set a fixed random seed so that you can repeat exactly the same sequence of events if you need to investigate something. Once you are satisfied that your source configuration is correct, you can vary the seed for production runs to obtain independent statistics.

Never start a long final project run before you have visually and numerically confirmed that your particle source behaves exactly as intended.

With a correctly designed and validated particle source, your final project simulation will produce data that meaningfully reflects your physics question. The next steps will connect this source to the chosen physics list, sensitive detectors, and analysis, so that you can extract and interpret the quantities of interest.