30.2. Geometry Errors

Understanding Geometry Errors

Geometry errors occur when the logical description of your detector geometry does not match what Geant4 expects for a valid, navigable world. They often appear when you build or modify detector geometry, especially when you work with many volumes, Boolean solids, or parameterized structures. Recognizing their typical signatures and fixing them early will save significant debugging time.

Geometry errors usually do not mean a compiler problem. They are about how shapes, positions, and materials are arranged in the simulation. Most of them only show up at runtime, when Geant4 navigates particles through the geometry.

Typical Symptoms of Geometry Errors

Many geometry problems manifest as confusing runtime behaviors rather than explicit error messages. Some frequent symptoms are:

Particles get stuck or never leave a region. You may see infinitely long tracks, large step counts in the stepping verbose output, or the simulation apparently hanging during particle transport. This usually hints at overlapping volumes or ill-defined boundaries.

Particles appear to start inside solid material when you expect them to be in air or vacuum. This suggests that the source position is inside a different volume than you intended, or that the shape or position of your volumes is different from what you think.

Energy deposition appears in unexpected places. For example, you might see hits in a detector that should be shielded, or no hits where you expect many. This often indicates wrong placement, wrong rotations, or misaligned coordinate systems.

Visualization shows missing or strangely distorted objects. If parts of your geometry are not visible or have unexpected shapes, this might indicate that solids were defined with invalid parameters, or that world size is too small and clips geometry.

Sensitive detectors never record hits. Sometimes the cause is not the sensitive detector logic, but the fact that particles never actually enter the intended volume, or that the intended detector volume is not inside the world or parent volume as you expect.

The simulation crashes or reports navigation errors when a particle hits certain regions. These crashes may be linked to invalid Boolean solids, zero or negative dimensions, or volumes placed outside their mother volume.

When you see any of these symptoms, the first suspect should be geometry, not physics or random numbers. Inspect the shapes, sizes, and placements.

Common Sources of Geometry Errors

Several typical mistakes lead to geometry problems. They are especially frequent when you manually compute sizes and positions, or when you significantly modify an existing geometry.

One of the most common issues is using inconsistent units. For example, defining a box with half-lengths in meters but placing it with offsets in millimeters will produce a very different geometry than expected. Because Geant4 uses an internal unit system, you must always multiply dimensions by explicit units like mm or cm. Forgetting the unit turns numbers into pure multiples of the internal base units and can create absurdly large or small objects.

Another frequent source of errors is defining solids with invalid or extreme dimensions, such as negative radii, zero thickness, or absurdly thin shells that are then combined with Booleans. Some solids accept parameters in specific ranges only, such as start and end angles between 0 and 2π, or inner radius less than outer radius. Violating these expectations can cause run-time warnings or even navigation failures.

Many geometrical problems arise from positioning mistakes. Translating or rotating a volume relative to the wrong coordinate system is easy. For example, you might compute a position assuming a local coordinate system, then use it as a global translation, so the placed volume ends up far away or embedded into another region. Similar confusion can happen with rotations: using degrees where radians are expected, or misinterpreting axes of rotation.

Boolean solids are another frequent source of geometry errors. When you subtract or intersect solids, small numerical tolerances can create thin leftover slivers that confuse navigation, or mismatched operations can produce self-intersecting solids. If you place Boolean solids inside other volumes, the resulting shapes must still be valid and non-self-overlapping.

Hierarchical mistakes are also common. A daughter volume must fit entirely within its mother volume. If the daughter is larger or placed so that it extends outside, Geant4 will usually complain about overlaps. This is especially easy to do when scaling or reusing dimensions from one level of the hierarchy in another without careful checks.

Repeated geometry, such as replicas and parameterizations, can introduce errors when indices are used incorrectly to compute positions or sizes. Small off-by-one mistakes or incorrect displacement formulas can lead to overlaps between neighboring repeated elements or to gaps that break the intended continuous structure.

Finally, insufficient world size is an often overlooked source of errors. The world volume must contain all other volumes and must be large enough to accommodate all possible particle paths. A world that is too small can clip geometry or terminate tracks at the boundary in unexpected ways.

Detecting Geometry Problems

Geant4 provides tools and runtime messages that help you detect geometry problems before they silently distort your simulation results. You should use these tools regularly, especially after changes to your detector model.

The first line of defense is text output. When geometry construction finishes, Geant4 prints information about the number of volumes, materials, and regions. Pay attention to any warnings related to geometry, such as messages about overlapping volumes, invalid parameters, or navigation errors. If you see repeated warnings during event processing, especially about being back in the same volume at the same point, treat them as serious hints that something is wrong with your geometry.

Visualization is a powerful way to reveal contradictions between your intended design and the actual geometry. By opening a visualization driver and drawing the full geometry or selected subregions, you can check whether solids appear in the right place and shape. Rotating and zooming in reveals misplacements and unexpected interpenetrations. Wireframe and surface views can show unexpected intersections.

Geant4 has built-in overlap checking routines. You can ask the geometry system to search for overlapping daughter volumes inside a mother. This algorithm samples random points on the surfaces and in the volumes, and reports any discovered overlaps with their locations. Even if your geometry visually looks fine, this numeric overlap check often discovers subtle overlaps or boundary conflicts.

Printing detailed information about volumes can also help. Listing the logical volumes, their materials, and their number of placements can expose volumes that you think you use but are never actually placed in the geometry. You can similarly print the depth of the geometry tree to understand the hierarchy of mothers and daughters.

At the step level, stepping verbose output is useful. By enabling detailed stepping information, you can examine which volume a particle is in, which boundary it crossed, and where the step starts and ends. If the volume names or boundaries do not match your expectations, this indicates a geometry problem rather than a physics or tracking issue.

In summary, you should habitually use three kinds of detection methods: visual inspection, numeric overlap checks, and detailed navigation logs. Combined, they let you quickly narrow down where a geometry error is located.

Using Verbose Geometry and Navigator Output

Geant4 can provide detailed runtime information about navigation, which is the process that determines which volume a particle is in and how it moves from one volume to another. When geometry behaves strangely, verbose navigation output is one of the best tools to understand what the kernel thinks your geometry is.

The navigator keeps track of the current volume, the next boundary along the step, and the distance to that boundary. If something is wrong, such as an overlap or a zero-distance boundary, the navigator can produce warning messages. By controlling the verbosity level, you can ask for more or less detail about these calculations.

Increasing geometry verbosity at construction time makes Geant4 print all volumes, with their names, copy numbers, and positions. This is particularly useful when you suspect that a volume is not placed where you expect, or that you have accidentally created many overlapping copies of the same logical volume.

During tracking, you can enable detailed step-by-step printing of navigation decisions. For each step, Geant4 can tell you the pre-step volume, post-step volume, and any boundaries crossed. If particles appear to cross directly from one distant detector element to another without traveling through the expected shielding, verbose navigation output will immediately show where Geant4 thinks the real boundaries are.

The navigator can sometimes produce specific error or warning messages that contain useful hints. Messages that repeat phrases like "Passenger stuck" or "Step length too small" indicate that the particle is trapped at a boundary due to overlapping volumes or numerical precision issues. Messages that mention a specific volume name are particularly valuable clues, because you can then inspect that solid or placement directly.

You should not leave verbose navigation enabled for large production runs, because it produces a lot of output and slows down the simulation. Instead, use it in short, controlled runs with a small number of events, targeted at the problematic geometry region. By adjusting the primary particle source so that particles probe the suspicious region, verbose navigation output will show exactly what is going on there.

Fixing Invalid Geometry

Once you have identified the region where problems occur, you need to correct the underlying geometry definitions and placements. Several systematic strategies help turn an invalid geometry into a valid one.

The first strategy is to check and correct units. Make sure that every dimension in your solids, such as lengths and radii, explicitly multiplies a Geant4 unit like mm or cm. Similarly, ensure that positions used in placements are also expressed with explicit units. Inconsistent units can easily produce solids that are enormous or microscopic compared to the rest of your geometry.

Next, verify that all solids use valid parameter values. For example, for cylindrical shapes, check that inner radius is less than outer radius, that half-lengths are positive, and that angular ranges make sense. For spherical and other curved solids, ensure that angle limits stay within allowed ranges and do not wrap around improperly. If necessary, simplify the shape to a more basic solid to confirm that it behaves as expected before reintroducing complexity.

For hierarchy consistency, confirm that every daughter volume fits entirely inside its mother volume. Compare the dimensions of the mother solid with those of the daughter, and calculate the allowed range of placement positions. If the daughter is too large, either shrink it or enlarge the mother. If placement translations push the daughter outside, correct those offsets.

Overlaps are often resolved by slightly adjusting dimensions or positions. For example, if a cylindrical detector is exactly as wide as the cavity in which it sits, tiny floating point errors can produce tiny overlaps or gaps. Introducing small safety margins such as making the cavity slightly larger or the detector slightly smaller helps avoid boundary ambiguities. Just ensure that these margins are small enough that they do not change the physics relevant to your study.

When dealing with Boolean solids, consider whether you can simplify the design. Complex nested Booleans can generate numerical issues and self-intersections. You can test the intermediate solids step by step: first verify that a simple subtraction behaves correctly, then add more complex operations. If a Boolean result is causing trouble, try changing the order of operations or switching to a different combination that yields the same final shape.

In repeated geometry, such as detector arrays, review the formulas that compute positions and dimensions. Check index ranges and increments, and verify with simple examples that neighboring elements do not overlap or leave unexpected gaps. A common technique is to build a small array with only a few elements and inspect it visually to confirm correctness before scaling up.

Finally, consider your world volume. Make sure it is significantly larger than the entire detector and any regions where particles may travel. If you extend detector components or move sources, do not forget to increase the size of the world and adjust its placement. The world should provide a generous buffer so that physics takes place comfortably away from the outer boundary.

By combining careful dimensional checks, simplified test cases, and incremental reintroduction of complexity, you can systematically fix invalid geometry and restore a stable and physically meaningful simulation.

Views: 14