KAHIBARO
6.2. Creating Volumes
Table of Contents
Adding volumes
In GATE, every object that particles can traverse or interact with is a volume. After the world has been defined, you add inner volumes to represent detectors, phantoms, shielding blocks, or any other component of the setup. Each volume has three basic ingredients: a shape, a material, and a placement in a parent volume. You will meet the details of different shapes in later sections on box, cylindrical, and spherical geometry, so here the focus is on how volumes are created conceptually and how they fit into the hierarchy.
In OpenGATE with Python you typically work with a geometry manager accessible through the main simulation object. To add a new volume you first choose a logical name, then specify its type, size parameters, material, and placement. Internally, GATE creates a logical volume, which combines the shape and material, and a physical volume, which is the actual placed instance in the world.
A typical creation procedure follows this pattern. You define the parent volume where the new object will live. Then you provide the geometrical parameters such as half dimensions for a box or inner and outer radii for a cylinder, and finally you set the translation and rotation relative to the parent. By separating creation and placement, GATE lets you reuse the same logical description in several locations if needed.
When building even a simple setup, it is important to plan the list of volumes before coding. Start with the world as the root, then identify major components, like a phantom volume and a detector housing, and only then add smaller internal parts. This top down strategy keeps the volume tree clear and avoids confusion later when you inspect or debug the geometry.
In GATE every volume must have:
- A unique name.
- A well defined shape with valid size parameters.
- A parent volume that already exists.
- A material.
Without all four, the geometry will be incomplete or invalid.
Naming volumes
Names are the primary way you interact with volumes in a GATE Python simulation. You will use volume names not only when you define geometry, but also when you attach actors, define regions for production cuts, or set digitizer readout mappings. Poorly chosen names quickly lead to confusion, while a clear naming scheme makes even complex scanners manageable.
A good volume name is descriptive, stable, and structured. Descriptive means it hints at the role of the object, such as phantom_body, det_head, or shield_lead. Stable means that once you choose a name, you do not change it casually, because a change forces you to update every reference in sources, actors, and analysis scripts. Structured means that related components share a consistent pattern, for example ring_module_0, ring_module_1, or crystal_row3_col5.
It is common to include hierarchy hints directly in the names. For example, in a PET scanner you might choose names such as pet_ring, pet_ring_block_0, pet_ring_block_0_crystal_15. This does not replace the formal parent child relationships, but it helps you see where a volume belongs simply by reading the name.
Avoid generic or ambiguous names like box1 or volA. In a small test these might seem acceptable, but as soon as you refine the simulation they become uninformative. Also avoid embedding physical units in the name, such as phantom_20cm, because you will likely change the size later. Instead, the size should be specified only in the geometry parameters, and you can track it in comments or configuration files.
GATE treats volume names as identifiers, so they must be unique across the whole simulation. If you try to create two volumes with the same name, the geometry definition can become inconsistent and later configuration steps, such as attaching actors, may silently refer to the wrong object.
Important rules for volume names:
- Every volume name must be globally unique.
- Use descriptive, stable, and consistent naming patterns.
- Do not rely on generic names like
vol1orbox. - Avoid encoding numerical values, such as dimensions, directly in the name.
Parent volumes
Every volume in GATE, except the world, has a parent volume. This parent defines the reference coordinate system for placement and the environment material that surrounds the child. The parent child relationship forms a tree, with the world at the root and all other volumes as descendants.
Understanding this hierarchy is essential, because many geometry issues arise from selecting the wrong parent. When you place a detector crystal inside a detector housing, the crystal volume should use the housing as its parent, not the world. Its position is then defined relative to the center and axes of the housing. If you choose the world instead, the crystal will be positioned relative to the world origin, likely ending up outside the housing even if the numeric coordinates look reasonable.
The parent volume must already exist before you create the child. This requirement affects how you structure your geometry functions. You must define the world first, then higher level components, then internal parts. When you attach an actor or define a region, you can select a parent volume so that the actor or region automatically covers all children.
The material of a parent volume defines the surrounding medium for the child. For instance, if your parent is a water phantom and you place a bone insert as a child, then outside the insert the region still contains water. The shapes of parent and child volumes must be defined so that the child fits inside. If any part of a child extends outside its parent, you create an overlap that can cause incorrect particle tracking or warnings during initialization.
For repeated structures, such as detector arrays, a parent volume often represents a logical grouping, like a module. You then repeat the module around the scanner ring, and each module contains several children, for example crystals, photodetectors, or electronics. This multi level hierarchy helps you scale up the geometry without handling every small volume directly at the world level.
When debugging geometry, always keep the parent relation in mind. If an actor that scores energy deposition inside a phantom returns zero, it might be because the volume you thought was inside the phantom is actually attached to a different parent and lies outside. Interactive visualization tools usually display the volume tree, which lets you confirm that each child appears under the expected parent node.
Key points about parent volumes:
- Every volume except the world must have exactly one parent.
- The parent defines the reference frame for position and rotation.
- The child must be fully contained inside its parent to avoid overlaps.
- The parent’s material surrounds the child wherever the child is absent.
Views: 13