KAHIBARO
43.6. Actor Problems
Table of Contents
Empty output
Actors are central to GATE because they record what happens in your simulation. When an actor produces an empty file or no file at all, there is usually a small configuration mistake, not a deep physics problem. In this section you learn to think systematically about why an actor might record nothing, and how to check each possible cause.
The very first check is always: did the simulation actually run and produce events. If there were zero events, all actors will be empty. Use the simulation statistics actor or the terminal output to confirm that some primaries were generated and transported. If the total number of events or tracks is zero, fix the source or physics problem first rather than the actor.
Once you know that events exist, a common cause of empty output is that the actor type does not match what you want to record. For example, a dose actor that scores in a voxel grid will remain empty if you never defined a voxelized mesh for that actor, or if the mesh contains no voxels. Similarly, a hits actor will not produce data if there are no sensitive volumes that can produce hits. Confirm that the actor you chose is the correct one for dose, energy deposition, phase space, statistics, or detector hits, and that its configuration parameters are reasonable.
Volume and region problems are another frequent source of empty actors. Many actors score only in certain volumes. If you attach an actor to a volume that never sees particles, or that is not part of the geometry at all, you will see no data. Use geometry visualization to check that the volume name you requested actually exists, is visible, and is intersected by particle tracks. For voxel- or dose-type actors, check that the image origin, spacing, and size really overlap your beam or source region. A dose grid that sits far away from the beam will record zero dose even if the simulation runs perfectly.
Filters are a powerful way to restrict what an actor records, but they can easily be too strict. For example, a particle filter that only accepts photons with exactly 511 keV will reject all events with slightly blurred energies, and a volume filter that uses a wrong or misspelled volume name will reject all hits. Whenever you get empty output, temporarily remove all filters. If the actor then starts recording data, reintroduce filters one by one and verify each condition.
Time and activity settings can silently lead to empty actors if they exclude all events. A time filter that only accepts events in a very narrow time window, or a simulation time interval that ends before any decays occur, can both result in no recorded data. Double check your use of simulation time, activity, and time-related actor parameters. For radioactive simulations, verify that the number of decays and acquisition duration are large enough to produce detectable interactions.
Simulation output can also look empty because you are reading the wrong file or directory. Some actors write multiple files, or you may have changed the output path partway through development. Before assuming the actor failed, confirm that the file you are opening corresponds to the latest run, and that it actually contains branches or arrays for the actor. For ROOT files, use a simple browser or tree listing to check for branches; for images, check the header metadata. If the file is missing completely, then the actor may never have been created or attached.
A subtle but important source of problems is unit confusion when configuring an actor. For example, setting a voxel spacing in meters instead of millimeters may create a grid with one huge voxel that misses the patient geometry, or specifying an energy threshold with the wrong unit can throw away all interactions. Always confirm actor parameters against the unit system you defined.
When debugging any empty actor, it helps to start from a minimal example. Create a very simple geometry, one small water box, one point source, and a single actor without filters. Verify that this minimal actor records data. Then gradually add back your original geometry, filters, and complex setup. This stepwise approach isolates where the problem appears.
Finally, keep in mind that statistical uncertainty may make legitimate low-count regions look empty. A few events in a large dose grid can give many zero voxels even when the actor works correctly. The solution here is to increase the number of events, and to look at summary statistics before concluding that the actor is broken.
Always verify these points when an actor output is empty:
- The simulation produced nonzero events.
- The actor type matches the quantity you want to record.
- The actor is attached to a volume or region that particles actually traverse.
- Filters are not rejecting all events.
- Time, activity, and unit settings are consistent and realistic.
- You are inspecting the correct, most recent output file.
Incorrect attachment
Even if an actor is defined correctly, it will not record anything useful if it is not attached to the right place in the simulation. Incorrect attachment means that the actor exists, but listens to the wrong volumes, lacks the right scoring volume, or is created at the wrong moment in the script. Recognizing and fixing attachment issues is one of the most important debugging skills in GATE.
In GATE, actors often require a target volume or region. For detector related actors, this target is usually a particular crystal or detector assembly. For dose and energy deposition actors, it is a phantom or voxel grid. If you attach a detector actor to the world volume, or a dose actor to the wrong phantom, all your measurements will be misplaced or meaningless. Carefully check the names you pass when you attach the actor. These names must match the geometry object names created earlier in the script, including case sensitivity.
Attachment order in your Python script also matters. You must create the geometry first, then attach actors, and only then initialize and run the simulation. If you attach an actor to a volume before that volume exists, the attachment will silently fail or bind to a default region. When debugging, always confirm that the lines that create volumes precede the lines that define and attach actors. Avoid changing geometry after actors have already been created, because the actors may not automatically update their internal volume references.
Some actor types require more than a single volume name. For example, actors that define dose grids may need a mesh or image volume, while statistics actors may be global and not tied to a specific object. Attaching a global actor like a simulation statistics actor to a detailed detector crystal is not wrong, but it will not change its behavior. On the other hand, attaching a local actor that expects a specific scoring mesh to the world volume may prevent it from scoring correctly. Read the documentation for each actor type to understand whether it is global or volume based, and attach it accordingly.
Another subtle issue arises with nested and repeated volumes. If your detector is built from many repeated crystals inside modules and rings, you need to decide at which level of the hierarchy the actor should attach. For example, attaching a hits actor to a high-level ring volume might record interactions in the ring housing but not in the crystals where you expect them. Conversely, attaching to a single crystal will only capture events in that one element. When you see unexpected or missing data, review the volume tree of your geometry and verify that the actor is attached at the correct level of nesting.
Region based cuts and production parameters can interact with actor attachment in confusing ways. If you have defined transport regions and assigned only some volumes to those regions, an actor attached to a volume that is not properly assigned might not see the expected secondaries or interactions. When debugging, print out or log the list of regions and which volumes belong to them, then ensure your actor uses a volume that lies in the correct region for the physics you care about.
Timing of attachment relative to dynamic geometry can also cause problems. If you use motion or time dependent geometry, for example moving sources or rotating detectors, actors must be attached to the logical volumes, not to transient positions. Attaching to a specific placement that is later moved or replaced can lead to unexpected behavior. In practice, always attach actors to stable logical objects that exist for the whole simulation, rather than to temporary versions of those objects.
If you are unsure that an actor is attached at all, use initialization output and logs. Often, GATE will print information about which actors are created and to which volumes they are bound. You can also explicitly print the actor list from your Python script after configuration to verify that the actor appears with the expected name and target. If the actor is missing, it may never have been added to the simulation object.
When results look displaced or wrong but not completely empty, consider whether the actor is attached to a mirrored or rotated volume. For dose and energy maps, the orientation of the scoring grid must match the patient or phantom orientation. If you attach a dose actor to a different copy of the geometry, for example a test phantom rather than the patient phantom, you will record a valid dose map in the wrong place. Use visualization to confirm that the actor grid overlays the correct object.
As a general debugging strategy, start with a single, simple actor attached to a single, simple volume. Confirm that you understand exactly what that actor records and where. Then, as you add complexity, keep a mental map of which actors are attached to which volumes. If something seems off, draw the geometry tree on paper, mark which volumes are sensitive, and label where each actor sits. This mental model, combined with log messages, quickly reveals incorrect attachments.
To avoid incorrect actor attachment, always ensure:
- The volume name you use for attachment exactly matches an existing geometry object.
- Geometry objects are created before actors are defined and attached.
- You understand whether the actor is global or volume based, and attach it appropriately.
- For nested geometries, you attach the actor at the correct level of the hierarchy.
- For voxel or dose actors, the scoring grid is attached to and aligned with the intended phantom or patient volume.
- Any motion or rotation uses stable logical volumes, not ephemeral placements, as actor attachment targets.
Views: 13