KAHIBARO
43.4. Source Problems
Table of Contents
No particles generated
A very common debugging situation is that your simulation runs, but no particles are actually produced. You may see zero tracks in the statistics actor, empty hit or dose files, or no events in ROOT output. When this happens, focus on a few typical causes that are specific to GATE sources.
First, confirm that you actually created a source and added it to the simulation object. In OpenGATE Python scripts, you typically create a source with a function like add_source or similar. If the source is defined in a function, make sure the function is called before sim.run() and that you are not accidentally overwriting the simulation object afterward.
Next, check that the source is enabled and that its activity or number of particles is strictly positive. A zero activity, a zero number of particles, or a zero simulation time will all result in no particles being created. For time based sources, verify that the acquisition duration is long enough compared to the activity. For event based setups, confirm that you configured the number of events. If you use separate parameters for "number of primaries" and "activity based" modes, mixing them or leaving them at default values can silently lead to zero emission.
Make sure the particle type is valid. If you use a typo in the particle name or a particle that is not registered by the chosen physics list, the simulation might skip generation. Typical particle names are "gamma", "e-", "e+", "proton", or ion specifications. If your script reads particle type from a configuration file, verify the exact strings and capitalization.
A frequent source of trouble is the use of incorrect units when defining the activity or the simulation time. If you forget units, GATE often interprets bare numbers as Geant4 internal units, which are usually not what you intended. This can yield extremely small activities or vanishingly short times that effectively give no particles. Make sure you multiply by explicit units, for instance 10 Bq or 1 s.
Always define activity and time with explicit units, for example $A = 10 \,\text{MBq}$ as 10 MBq, and $t = 1 \,\text{s}$ as 1 s. Missing or wrong units can result in effectively zero emission.
If you use a radioactive source, verify that the radionuclide name is supported and properly spelled, and that you selected the appropriate decay physics. Without the right decay physics, no decay particles are produced. Also check that the half life and start time definitions are correct. For time windows that occur long after the start of a short lived source, the activity may have decayed to almost zero.
Another subtle problem appears when the source position is outside the world volume or inside a volume with zero or extremely small dimensions. In such a case, particles can still be generated, but they may be immediately killed by geometry navigation or may never reach the region where you record data. If you think particles are generated but not seen, use visualization or a simple phase space actor attached close to the source to check that particles actually appear in the expected region.
Finally, verify that the run is not trivially empty because the number of events is zero. For some configurations, you can specify n_events = 0 or forget to set it, which results in an immediate end of the simulation. Always check the terminal output from GATE, which usually prints the number of events and often reveals that zero events were processed.
Incorrect activity
When your source does generate particles, another common issue is that the activity is not what you expect. You might see far too few or far too many events, or the count rates differ significantly from simple analytical estimates. Most of the time this is caused by confusion between activity based and event based definitions, as well as incorrect units.
In GATE, an activity based source relates a physical activity $A$ and an acquisition time $T$ to an expected number of decays $N$. The basic relation is
$$
N = A \times T.
$$
Here $A$ is measured in becquerels and $T$ in seconds. If you misinterpret milliseconds as seconds or kilobecquerels as megabecquerels, the number of emitted particles can differ by orders of magnitude. Always check that your code explicitly uses Bq, kBq, MBq, and s, ms, or other time units where appropriate.
Use the relation $N = A \times T$ with consistent SI units, for example $A$ in Bq and $T$ in s. Incorrect unit combinations for activity and time are one of the most frequent causes of wrong event statistics.
If you configure both an explicit number of events and an activity, understand which option GATE actually uses in your script. Some frameworks ignore the activity when the number of events is explicitly set. In that case, changing the activity value will have no effect on the total number of simulated events, which can be confusing. Decide whether you want to control the simulation through activity and time or through a fixed number of events, and configure only one of them.
Check also the time profile of the source. If you use a time dependent activity curve, make sure that the total integrated activity over the acquisition time matches what you expect. Mistakes in time units or in the normalization of the time function can produce an effective activity that is much higher or lower than the nominal value. Verify the time axis of your profile and that you assign the correct simulation time window.
For radioactive sources, the decay of the activity with half life must be considered. The instantaneous activity at time $t$ is
$$
A(t) = A_0 \, e^{-\lambda t}
$$
with $\lambda = \ln(2)/T_{1/2}$. If your simulation runs for a long duration compared to the half life, the mean activity over the acquisition interval is lower than the initial activity. If you compare simulated counts to a measurement at a specific time, be sure you use the same reference time and decay correction.
Sometimes, activity issues are actually geometric or detection issues. For example, the total number of emitted particles may be correct, but only a tiny fraction reaches your detector because the source is far away or inside shielding. If the discrepancy is between true emission and detected counts, use a phase space actor around the source to confirm the total number of generated particles. If the count at the source matches $N = A \times T$, then any further difference is due to transport or detection efficiency, not the activity itself.
Finally, remember that Monte Carlo results are statistical. If you simulate a small number of events, the relative uncertainty can be large. The standard deviation in the number of observed decays follows approximately $\sigma \approx \sqrt{N}$. To reduce statistical fluctuations in observed count rates, you often need to increase the number of simulated events or repeat runs with different random seeds and combine the results.
Incorrect direction
The last common class of source problems relates to the direction of emitted particles. You may see particles apparently "going the wrong way," missing the detector, or not producing expected patterns. These errors can be subtle because the simulation still runs and produces data, but the geometry is irradiated incorrectly.
First, clarify how your source direction is defined. A fixed direction is typically specified by a three component vector $(d_x, d_y, d_z)$ in the simulation coordinate system. To emit particles towards the positive $z$ direction, you might use (0, 0, 1). If you accidentally swap coordinates, change sign, or use a non normalized vector that GATE interprets differently, the beam can point away from the intended target. Always double check the coordinate convention, especially if you rotate the world or other volumes.
If you use isotropic emission or angular distributions, make sure that you actually configured the option you intended. For example, you may think you created a parallel beam, but the source is still configured as isotropic because a specific flag was not set. In this case, only a small fraction of particles will go in the nominal "beam" direction and most will spread over 4$\pi$ steradians, greatly reducing the effective fluence on the detector or phantom.
A common trap occurs when both source position and direction are defined in a local coordinate system of a volume, but you interpret them as global coordinates, or vice versa. If your simulation uses rotated or translated parent volumes, the actual global direction can differ significantly from the vector you set. For debugging, use visualization and display a few particle tracks from the source region. This immediately shows if the direction aligns with the intended beam axis or radial direction.
Another category of directional error involves cone or fan beams. When you set an opening angle or an angular spread, check whether it is specified in degrees or radians, and confirm that the azimuth and polar angles are defined in the expected order. Reversing polar and azimuth angles, or misinterpreting units, can deflect the beam into an unexpected region of space. If possible, start with a very narrow cone, visualize tracks, and then gradually increase the opening angle.
Sometimes, the appearance of an incorrect direction is due to misunderstanding of the coordinate system used by the detector model. For example, in a PET scanner, the ring might be aligned along the $z$ axis, but you define a source that emits along the $x$ axis. The simulation will still be correct, but the beam will not be aligned with the scanner as you intended. Sketching the geometry on paper with explicit axes and source vectors can prevent this type of confusion.
Finally, remember that physical effects can change particle directions. Scattering in matter will randomize or deflect trajectories. If you see tracks bending or spreading, distinguish between source direction errors and physical scattering. One way to check is to temporarily remove the material between the source and detector and see whether particles travel in straight lines along the expected direction. If they do, then your source direction is correct and the apparent deviation in the full simulation is due to interactions, not a configuration bug.
Views: 11