KAHIBARO
43.3. Material Errors
Table of Contents
Unknown materials
Material errors in GATE almost always show up as Python exceptions or Geant4 log messages that mention material names. These problems are specific to how materials are defined and referenced, not to general geometry or physics configuration.
The most common situation is that a volume refers to a material name that GATE or Geant4 does not know. In OpenGATE, materials are created in the simulation object and then assigned to volumes by name. If the name in the volume does not exactly match any defined material, you will typically see messages such as:
- “Material not found”
- “G4Material::GetMaterial: WARNING: material X not found”
- A Python error when building the geometry that mentions an invalid material or missing key
In many cases, the problem is a simple spelling or capitalization mismatch. GATE and Geant4 treat material names as case sensitive, so "Water", "G4_WATER", and "water" are three different names. A geometry that uses material = "water" will fail if you only defined "Water".
It is also easy to confuse Geant4 NIST material names with your own names. For instance, Geant4 provides "G4_WATER" and "G4_AIR", but does not provide "Water" or "Air" unless you created them explicitly. If your simulator script relies on NIST materials, you must use their exact NIST names.
To debug an unknown material error, first search your script for where you define materials in the simulation object. Check the dictionary keys or attributes where the names are stored. Then search for every place you assign a material to a volume and compare the strings. It can help to temporarily print the list of all available materials in your simulation. If your framework exposes something like a simulation.dump_materials() or a materials dictionary, use this to check exactly what is defined before the geometry is built.
Sometimes the material is not unknown to Geant4 itself, but is simply defined too late for the volume that needs it. For example, if you define a material after you already created and initialized the world and its daughters, GATE might have already tried to resolve the material names. In that case, re-order your script so that all custom or NIST materials are created before any volumes that use them. The safe pattern is to finish material creation and mapping, then define the geometry, then initialize and run.
If you are using a custom material database or a helper function that registers materials, verify that it is actually called. A common problem in more complex scripts is to forget to import or call the material setup function for the current simulation. The geometry then refers to material names that were never defined in this run.
Finally, pay attention to error messages about “default material” or “material missing, using G4_AIR”. These do not always stop the simulation, but they indicate that some volume did not get the material you intended, which can completely change transport and dose. When you see such warnings, do not ignore them. Replace every implicit fallback with an explicit material definition that you have checked.
Always ensure that every material name assigned to a volume exactly matches a defined material, with correct spelling and capitalization, and that all materials are created before the geometry is built.
Density problems
Density problems arise when a material exists, but its density is incorrect or inconsistent with the rest of the simulation. This affects particle ranges, interaction probabilities, and dose, so it is a critical class of debugging issues.
In a typical GATE workflow, density is specified when you define a material. For simple single-element materials, you give the element and a density. For mixtures and compounds, you provide components and a total density. Problems can appear in several ways.
The first and most basic problem is using the wrong numerical value or the wrong unit for density. For example, water should have a density of approximately $1 \, \text{g/cm}^3$. If you mistakenly give $1$ without the correct unit, or treat it as $1 \, \text{kg/m}^3$, the material will be about $1000$ times too light. In a unit-aware Python interface, you must multiply by the correct density unit. If you use something like 1 * g / cm3, you must be sure that both g and cm3 are the unit constants provided by the simulation framework. If you accidentally divide by the wrong length unit, you can easily end up with $1 \, \text{g/mm}^3$ instead of $1 \, \text{g/cm}^3$, which is off by a factor of $1000$.
You can diagnose density problems by checking simple physics outputs. A classic method is to simulate a monoenergetic proton or photon beam in a water box and compare the depth at which the dose or attenuation matches known values. If the range or attenuation length is too short or too long by a large factor, suspect a density or composition error in the material. For more basic checks, print the material density from the simulation after initialization, if the interface allows it. Geant4 internally stores density in $\text{g/cm}^3$, so this is often what you will see.
Another frequent source of issues is inconsistent density in voxelized or CT based materials. When mapping Hounsfield units to materials and densities, one often uses a conversion table or function. If the mapping is wrong, soft tissue may be assigned a density that is closer to lung or bone. The simulation will still run, but the calculated dose and attenuation will be incorrect. When debugging these cases, inspect a few representative voxels and print or visualize their assigned density and material name. Compare them to expected clinical densities, such as approximately $1.0 \, \text{g/cm}^3$ for soft tissue, $0.3 \, \text{g/cm}^3$ for lung, and $1.8 \, \text{g/cm}^3$ for dense bone.
There are also more subtle problems where the density is physically unrealistic. For example, if you define a mixture with a total density that is incompatible with its components, Geant4 may still accept it numerically, but you may see odd behavior, such as unexpectedly high stopping power or interaction rates. If you suspect this, compare your density to published reference values or to the density used in standard NIST materials. When possible, prefer using the existing NIST materials for common substances like water, air, and tissue equivalent plastics, since they come with validated densities.
During debugging, keep an eye on log messages that mention “volume mass”, “material density”, or extremely small or large mass values for volumes. If you have a phantom that should weigh about 70 kg, but the simulated total mass is 7 kg or 700 kg, your densities are off by an order of magnitude. Use simple volume and density calculations to estimate the expected mass. For a uniform box, the mass is $m = \rho V$, with $V$ the geometric volume in $\text{cm}^3$ or $\text{m}^3$ and $\rho$ in consistent units. Comparing this to what the simulation reports is a powerful sanity check.
Finally, be careful when editing density of an existing material in the middle of script development. If you change a density but forget that other parts of your code assume the old value, you may invalidate previous validation or comparisons. When you debug density, document any changes you make and rerun key test cases to ensure consistency.
Always define density with the correct numerical value and unit, verify it against reference values, and check that voxel or CT based materials receive realistic densities for each tissue class.
Views: 11