KAHIBARO
5.6. Using Units Correctly
Table of Contents
Unit-aware simulation parameters
In GATE, every physical quantity must be provided with an explicit unit. This applies to geometry, sources, physics settings, and actors. The goal is to make the simulation self-documenting and to avoid guessing whether a value is in millimeters, centimeters, seconds, or any other unit.
In Python GATE (OpenGATE), units are usually imported as symbols from the opengate module or from the underlying Geant4 units package. You typically write parameters in the form value unit. For example, you specify a 10 cm length as 10 cm and a 5 MeV energy as 5 * MeV. The multiplication produces an internally consistent quantity that GATE can interpret.
Below is a typical unit import pattern you will see in GATE scripts:
import opengate as gate
from opengate import g4_units
m = g4_units.m
cm = g4_units.cm
mm = g4_units.mm
deg = g4_units.deg
rad = g4_units.rad
keV = g4_units.keV
MeV = g4_units.MeV
s = g4_units.s
ns = g4_units.ns
Bq = g4_units.Bq
MBq = g4_units.MBq
Once you have aliases like cm, MeV, and s, you use them directly when setting parameters. The following examples show how to attach units to typical simulation quantities.
Geometry sizes and positions use length units:
sim.world.size = [1 * m, 1 * m, 1 * m]
detector.size = [5 * cm, 5 * cm, 2 * cm]
detector.translation = [0 * mm, 50 * mm, 0 * mm]Particle energies and spectra use energy units:
source.particle = "gamma"
source.energy.mono = 140 * keVTime-related parameters such as source duration and acquisition windows use time units:
source.activity = 10 * MBq
source.start_time = 0 * s
source.end_time = 60 * sAngles in GATE are unit-aware as well. Rotations and directions should be expressed with degrees or radians, but never with raw unqualified numbers:
detector.rotation = [0 * deg, 90 * deg, 0 * deg]
Always write physical quantities as numeric_value unit, for example 10 cm, 511 keV, 1 s. Never use bare numbers for lengths, energies, times, or angles.
You can also build composite units when needed. For instance, dose is energy per unit mass and is expressed in gray, but gray itself is defined in Geant4 units as joule per kilogram. You usually use the predefined gray unit:
from opengate.g4_units import gray
dose_limit = 2 * gray
Similarly, you can create event rates or fluxes by combining units, although in basic GATE scripts this is less common. For example, a count rate might be described as counts per second conceptually, but numerically you would often handle counts as dimensionless and time separately with s.
Internally, GATE converts everything to a consistent set of base units. As long as you always multiply by the appropriate unit symbol, you can combine different units in a natural way. A typical example is specifying a voxel size in millimeters while giving the world size in centimeters. GATE will handle the necessary conversions automatically, as long as the units are explicit.
Avoiding unit errors
Unit mistakes are one of the most common sources of incorrect results in Monte Carlo simulations. In GATE, errors usually arise when users forget units, mix incompatible units, or misinterpret documentation examples.
Several typical error patterns deserve special attention.
The first is forgetting to multiply by units and providing plain numbers. For example, writing:
detector.size = [50, 50, 20]instead of
detector.size = [50 * mm, 50 * mm, 20 * mm]leads to an object with nonsensical dimensions in the default internal units. This can distort geometries and break physical interpretation. It can also cause geometry overlaps if other volumes are created with properly scaled units.
The second common issue is using the wrong magnitude of unit. Lengths that physically should be millimetres are accidentally given in centimetres, or energies that should be expressed in keV are given in MeV. For example, specifying 140 MeV instead of 140 keV will produce photons that are a thousand times more energetic than those from a typical Tc 99m source and will radically change interaction probabilities.
A similar pitfall appears with time units, where nanoseconds and seconds can be confused. Coincidence timing windows in PET are usually specified in nanoseconds. If you mistakenly write 4 s instead of 4 ns in a timing window, almost every pair of events will be judged coincident. Conversely, writing 4 * ns when the intended real time window is of the order of microseconds will reject most physically valid coincidences.
To systematically avoid these issues, adopt some strict habits when writing and reviewing simulations.
First, never type a bare number for any quantity that has a physical unit. This rule includes world sizes, phantom dimensions, energies, activity, acquisition times, dose thresholds, transport cuts, and angles. If the value does not multiply by a unit symbol, treat it as a bug.
Second, verify units against typical values from medical physics. A simple reality check can reveal obvious mistakes. Ask yourself whether a world of 1 m makes sense for your scanner, whether a source energy of 120 keV is realistic for a SPECT photon, or whether a 30 * s acquisition for a whole body PET is reasonable. If a number looks unusual, double check both the value and the unit.
Third, match units to their context in GATE configuration parameters. If the documentation states that a parameter is a distance, always use length units. If it is a time parameter, always use time units. Do not reuse symbols like cm accidentally for angles or for dimensionless quantities.
The table below summarizes some common GATE parameter categories and the units you should normally apply.
| Quantity type | Typical GATE parameter examples | Recommended unit symbols |
|---|---|---|
| Length and position | World size, detector thickness, voxel size, offsets | mm, cm, m |
| Energy | Source energy, thresholds, physics cuts | keV, MeV |
| Time | Acquisition duration, coincidence window, decay time | ns, us, ms, s |
| Activity | Source activity, total injected activity | Bq, kBq, MBq |
| Angle | Rotations, collimator angle, scanner rotations | deg, rad |
| Dose | Dose constraints, reference doses | gray |
Another important source of unit mistakes appears when converting from external data such as clinical protocols or literature values. Often, clinical documents give beam energies in MV or detector dimensions in cm, while you might be thinking in mm and keV inside your script. Before implementing such values, explicitly convert them to the units you are actually going to use in your code and write them clearly. For instance, instead of writing 0.511 MeV, decide whether you want to represent the same value in keV as 511 keV and use one style consistently.
When working with activity and time, be careful to understand what your source parameters represent. In time based source definitions, GATE will generate events based on activity as decays per second. Make sure that values such as 10 MBq correspond to realistic clinical or experimental activities and that the associated acquisition duration, for example 600 s, matches the intended experiment. If you mistakenly write 600 * ms, you will simulate a much shorter acquisition and your statistics will be lower than expected.
Angle units deserve a specific note because some users are used to degrees, while others think in radians. In GATE, both deg and rad are available. Choose one, state it clearly in your script through comments, and stick to it consistently. Do not mix radians and degrees in the same block of code, because this makes unit errors harder to notice by eye.
When you encounter unexpected results, for example strange dose levels, unusual count rates, or geometry objects that seem too large in the visualization, inspect the corresponding parameters for missing or mismatched units. Many puzzling behaviors are resolved when a value like 100 is corrected to 100 cm or 100 keV.
Finally, include basic checks or assertions in your scripts for critical parameters. You can use Python to verify that some lengths are within plausible ranges or that energies lie in realistic windows. This does not replace careful thinking about units, but it provides an extra layer of protection.
Never use bare numbers for physical quantities. Always attach the correct unit symbol, verify that the magnitude is realistic for the application, and keep units consistent across the entire script.
By always associating units explicitly and by cross checking them against the physical context, you greatly reduce the chance of silent but serious unit errors and improve the reliability of your GATE simulations.
Views: 9