KAHIBARO
30.7. Sensitive Detector Problems
Table of Contents
Typical Symptoms of Sensitive Detector Problems
Sensitive detector problems usually show up as missing or obviously wrong detector responses. In a working setup you expect to see hits, energy deposits, or timing information in your output. When there is a problem, you may observe:
No hits at all in one or more detectors, even though particles clearly cross the volumes in the visualization. This often appears as empty hit collections, flat zero histograms, or no entries in ntuples.
Hits only in some detector elements of an array, for example only one strip or crystal shows activity out of many identically defined ones.
Non-physical values in hits, such as negative times, unrealistically large energies, or positions outside the detector volume.
A sudden change in detector response after you modify geometry, materials, or IDs, even though the physics and source did not change.
When you see these symptoms, the problem is almost always in the connection between volumes, sensitive detectors, and hits, not in the physics list or primary generator.
Always verify that hits exist where you expect them, and that their energy, time, and position values are physically reasonable.
Verifying Sensitive Detector Registration
A frequent issue is that the sensitive detector object is never created, or created but never registered, or registered but never attached to any logical volume.
In most applications, sensitive detectors are created and registered inside the method that configures detectors, often ConstructSDandField() in your user detector construction class. At minimum, you must:
Create a new instance of your sensitive detector class with new.
Register it with the G4SDManager, usually with G4SDManager::GetSDMpointer()->AddNewDetector(sd).
Attach it to one or more logical volumes using SetSensitiveDetector on the logical volume or an equivalent helper.
If any of these steps is missing, your ProcessHits method will never be called, even though your class compiles and links.
You can verify registration at runtime by printing from the sensitive detector constructor and from ConstructSDandField. If those messages do not appear, the code path is never executed. Also check that ConstructSDandField is actually overridden in your detector class and that your run manager uses this detector construction when you initialize the simulation.
If your sensitive detector is not added to G4SDManager and bound to a logical volume, ProcessHits() will never be called and no hits will be created.
Checking Volume to Sensitive Detector Assignment
Even if your sensitive detector is registered correctly, it may not be attached to the volume you think it is. Common problems include:
Attaching the sensitive detector to the wrong logical volume. For example, you might attach it to an outer support instead of the active crystal, or to the world volume by mistake.
Attaching to a logical volume that is never actually placed in the world or in the geometry hierarchy, so the volume exists in code but no physical copy exists.
Assigning the sensitive detector to a logical volume pointer that changes or is shadowed by another local variable, so you bind the wrong instance.
If you are using arrays or parameterized volumes, verify that all copies use the same logical volume that has the sensitive detector attached. You can check this by naming your logical volume meaningfully and using visualization to confirm that the active volume is what you think it is.
To debug, print the pointers and names of the logical volumes when you attach the sensitive detector, and compare them to what you see in geometry debug output or in verbose stepping. If the volume name at the interaction point does not match the one you attached, your assignment is incorrect.
Always attach the sensitive detector to the logical volume of the active detector material, not to the world or to a mechanical support volume.
Ensuring `ProcessHits()` Is Called
Once the sensitive detector is registered and assigned, the next question is whether ProcessHits is being invoked for each step in the sensitive volume. If ProcessHits is never called, no hits can be recorded, even though the particle crosses the volume.
You can test this quickly by adding a simple print statement at the start of ProcessHits. For example, print the particle name, kinetic energy, or step length when the method is entered. Run a small number of events with verbose output and verify that these messages appear when particles pass through the detector in the visualization.
If your print never appears, check the following points:
Confirm that your class name exactly matches the declaration in the header and the type you use when allocating the object. A mismatch in types can result in the wrong class being instantiated.
Check that ProcessHits has the correct signature, including argument types and G4bool return type, and that it correctly overrides the base class method. If the signature is wrong, the base class method is called instead of your implementation, and you may not see an obvious error.
Verify that the steps you expect to generate hits actually occur in the sensitive volume. Use stepping verbose to print the volume name at each step and check that the track really enters and traverses the target logical volume.
If you use step conditions to filter hits, for example only when energy deposition is nonzero or when the step crosses a boundary, confirm that these conditions are not too strict. In thin or low density materials, many steps may have zero energy deposition.
If ProcessHits() is not entered for steps in the sensitive volume, no hits will be recorded regardless of how you handle hit objects or collections.
Debugging Hit Creation and Storage
Even when ProcessHits is called, hits may not be created or stored correctly. Problems often come from how you create hit objects, how you manage their lifetime, and how you add them to collections.
In ProcessHits, you usually create a new hit with new, fill it with data from the G4Step, and then insert it into a G4THitsCollection attached to the current event. If you forget to insert the hit into the collection, or if you create it on the stack instead of with new, the hit is lost or destroyed at the end of the method.
Make sure that in your sensitive detector, you properly create the hits collection in Initialize for each event, store the collection ID, and add the collection to the event. Then, in ProcessHits, you always access the current collection and call insert(hit) on it.
You can debug hit storage by printing the number of hits in the collection at the end of the event action, using G4SDManager to retrieve the hit collection by name or ID, and checking that the count matches your expectations. You can also inspect the contents of the first few hits to confirm that energy, time, and position fields are populated.
Table: common hit storage issues and symptoms
| Problem | Symptom |
|---|---|
Hits created on stack, not with new | No hits, or hits with invalid data |
| Hits never inserted into collection | Empty hit collections |
Collection not created in Initialize | Null pointer or segmentation fault |
| Wrong collection ID used | Data appears in unexpected place |
Always allocate hits with new, insert them into the correct hits collection, and ensure the collection is attached to the current event in Initialize().
Handling Multiple Detector Elements and IDs
When you have an array of detectors, for example multiple crystals, strips, or pixels, you usually want to distinguish between them using a copy number or detector ID. Problems here often cause hits to appear in the wrong element, or all in a single element.
In many geometries, the copy number is associated with the physical volume that is replicated or parameterized. In ProcessHits, you can obtain the copy number from the touchable associated with the step. This number is then stored in the hit and used later to identify the detector element.
If you use multi-level hierarchies, be careful about which depth in the touchable you query. The active detector volume may not be the deepest level. If you query the wrong level, you may get the same copy number for all detectors, or a meaningless number that does not correspond to your mapping.
Another frequent issue is that the logical volume is shared, so the same sensitive detector sees hits from many elements, but you never store the copy number in the hit. All hits then look identical and you cannot reconstruct an image or profile.
To debug, print the copy number, volume name, and hit position for several hits. Verify that different physical elements have distinct copy numbers and that the mapping matches your geometry definition. If necessary, adjust your method for computing detector IDs from the touchable information.
For detector arrays, always record a detector ID, usually the copy number from the touchable, in each hit so that you can distinguish individual elements later.
Ensuring Hits Are Accessible in User Actions
Even if hits are created and stored correctly inside the sensitive detector, you must still retrieve them in your user actions, often in EndOfEventAction, for analysis or output. Many users encounter empty or null collections when they try to access hits, even though ProcessHits is called.
To access hits, use G4SDManager to obtain the collection ID by name, usually once at the beginning of a run, and then call GetHC on the event to get the hits collection pointer. If you request a collection with the wrong name, or before it has been created for the first event, you may get an invalid ID or a null pointer.
You should always check that the hits collection pointer is nonnull before using it. If it is null, print a warning with the collection ID and event ID, then check your sensitive detector configuration. If it is valid but the number of hits is zero, inspect ProcessHits and the conditions you use to create hits.
When you use multiple threads, remember that each thread has its own events and hit collections. Ensure that your analysis manager and event action handle per-thread data correctly, and that you do not attempt to share hit collections directly across threads.
Never assume that a hit collection exists. Always obtain its ID from G4SDManager, retrieve it from the event, and check for null before reading hits.
Common Pitfalls with Geometry Changes
Sensitive detector problems often appear suddenly after you change the geometry. The same sensitive detector code may work before a geometry change and then stop seeing hits afterward, without any compilation error.
Some common situations are:
You change a logical volume name or rebuild the geometry with new pointers, but your sensitive detector code still uses the old pointer or old name. As a result, you attach the sensitive detector to an obsolete volume that is no longer placed.
You move the detector volume so that the primary particles no longer intersect it. In visualization, the geometry may look similar, but the beam or source direction no longer crosses the active region.
You add additional layers or supports that shield the detector, absorbing particles before they reach the sensitive volume. The sensitive detector then sees fewer or no hits, which may look like a software bug but is actually a physical change.
Whenever detector response changes after geometry edits, verify that the active volume is still in the particle path, and that the sensitive detector is reattached to any new logical volumes you created. If you reconstruct geometry dynamically, confirm that ConstructSDandField is called after you rebuild the geometry when it is needed.
After any geometry change, recheck that your sensitive detector is attached to the correct logical volume and that particles still pass through that volume.
Using Verbose Output to Trace Sensitive Detector Issues
Verbose output is one of the most powerful tools to debug sensitive detector problems. By enabling detailed stepping and event printouts, you can trace particles step by step and see exactly which volume they are in and what energy they deposit.
You can enable verbose tracking with macro commands to print step information, including volume names, positions, and energy deposition. Combine this with simple prints in ProcessHits to see how many of the steps in the sensitive volume actually produce hits.
If the verbose stepping shows that the track enters the expected volume and deposits energy, but ProcessHits is not called, the issue is in the sensitive detector registration or attachment. If ProcessHits is called but no hits are stored, the problem is in hit creation and collection handling. If steps never reach the sensitive volume at all, the issue is in geometry or source configuration.
Keep the number of events low and the primary source simple during debugging, so that you can follow the output by eye. A single particle incident on a small detector is usually enough to reveal what is going wrong.
Use stepping verbose output together with prints in ProcessHits() and EndOfEventAction() to follow a particle from entry into the detector volume to the creation and storage of a hit.
Views: 10