43.1. Python Errors

Table of Contents

Syntax errors

In GATE, your simulations are regular Python programs. Before GATE or Geant4 ever start running, Python checks that your script is syntactically correct. If there is a syntax error, the program stops immediately, often before any geometry or simulation objects are created.

A syntax error means that the structure of the Python code is invalid. Typical examples include missing colons, missing parentheses, incorrect indentation, or stray characters. When Python encounters such a problem, it prints a traceback that ends with a message like SyntaxError: invalid syntax or a more specific description, and it points to the line where it noticed the problem.

Python usually marks the error location with a caret ^ under the offending part of the line. For example:

python

sim = gate.Simulation(      # ok
print("starting simulation") # error, missing closing parenthesis above

will produce something similar to:

text

  File "mysim.py", line 1
    sim = gate.Simulation(
                          ^
SyntaxError: '(' was never closed

In this case the last line of the file is where Python finally realizes something is unclosed, although the real mistake is the missing closing parenthesis earlier. For GATE users, this often happens when building long configuration blocks for geometry, sources, or actors.

Indentation problems are another very common issue, especially when you copy and paste code for simulation configuration. Python requires consistent indentation, typically 4 spaces per level. Mixed tabs and spaces or misaligned blocks cause errors like IndentationError: unexpected indent or IndentationError: expected an indented block. A typical situation is:

python

sim = gate.Simulation()
if debug:
print("Debug mode")  # not indented

which leads to:

text

  File "mysim.py", line 3
    print("Debug mode")
    ^
IndentationError: expected an indented block after 'if' statement on line 2

Since GATE simulations often contain nested functions for geometry and sources, and long if blocks for different configurations, it is important to keep indentation consistent. Most editors can be configured to show whitespace or to convert tabs to spaces automatically.

Another classic syntax problem in GATE scripts is incorrect use of colons with control structures. For instance, if you configure actors only when a flag is true:

python

if enable_dose_actor
    add_dose_actor(sim)

Python will fail with:

text

  File "mysim.py", line 1
    if enable_dose_actor
                        ^
SyntaxError: expected ':'

This kind of mistake is easy to miss when you are focused on simulation details instead of basic Python rules.

You may also run into syntax errors when using f-strings or complex expressions in logging or print statements. For example:

python

print(f"Dose actor size: {dose_actor.size[0], dose_actor.size[1]}")

is valid, but accidentally omitting a closing brace or quote:

python

print(f"Dose actor size: {dose_actor.size[0], dose_actor.size[1]")

will produce a SyntaxError: f-string: expecting '}'. Carefully check the balance of parentheses, brackets, and braces in these lines, especially when combining several variables into a single message.

A simple procedure to debug syntax errors in GATE scripts is to try running a very small part of the file. You can temporarily comment out large blocks of code until the syntax error disappears, then gradually re-enable code until you identify the exact line. Using an editor with Python syntax highlighting also helps because unbalanced brackets or strings are often highlighted.

For absolute beginners, it is useful to remember that syntax errors happen before any simulation-specific error. If your script does not even reach the point where opengate is imported or the simulation is created, look carefully at the traceback: if the last line mentions SyntaxError or IndentationError, you are still in the Python language layer, not in GATE itself.

A SyntaxError or IndentationError always means that Python could not even start running your GATE simulation. Fix the code structure (parentheses, colons, indentation, quotes) before looking for problems in geometry, sources, physics, or actors.

Import errors

Import errors occur when Python cannot find a module you are trying to use. In the context of GATE, the most important case is when Python fails to locate the opengate package or other scientific libraries needed for your analysis, such as NumPy, Pandas, or uproot. These problems appear as exceptions like ModuleNotFoundError or ImportError when the script starts.

The typical pattern in a GATE script is:

python

import opengate as gate
import numpy as np

If the GATE package is not installed in the current Python environment, you will see something like:

text

Traceback (most recent call last):
  File "mysim.py", line 1, in <module>
    import opengate as gate
ModuleNotFoundError: No module named 'opengate'

This message means that Python searched all directories in sys.path and did not find a package called opengate. It does not mean that your code is wrong, but that the environment where you run the script does not have GATE installed or active.

When debugging such an error, first confirm that you are using the correct environment. If you created a virtual environment or a Conda environment specifically for GATE, you must activate it before running the script. For example, if you installed GATE in a Conda environment called gate_env, your terminal session must have that environment active; otherwise Python will not see the installed package.

You can test directly in an interactive shell by running:

python

import opengate
print(opengate.__version__)

If this works, the package is available in the current environment. If it fails with ModuleNotFoundError, either GATE is not installed there or the installation failed.

Import errors can also appear for standard scientific packages used in GATE examples and analysis notebooks, such as NumPy or uproot. For instance:

python

import numpy as np

may give:

text

ModuleNotFoundError: No module named 'numpy'

if NumPy is not installed. This can happen if you installed GATE but forgot to install the full scientific stack. In that case, you need to add the missing packages using your environment manager, always inside the same environment where GATE is installed.

Another frequent import issue in larger GATE projects involves your own Python modules. Suppose you separate geometry, sources, and actors into different files:

python

from my_geometry import create_geometry
from my_sources import create_sources

If the files my_geometry.py or my_sources.py are not in the same directory as your main script or not in a directory listed in sys.path, Python will fail with a ModuleNotFoundError: No module named 'my_geometry'. This is a regular Python packaging issue, not specific to GATE. Keeping related files in the same project folder and running the main script from that folder usually avoids this problem.

Import errors can also happen when module names are typed incorrectly, for example import OpenGate instead of import opengate, or import root instead of import ROOT. Python distinguishes between lowercase and uppercase letters, so use the names exactly as specified in the documentation.

Sometimes you will see an ImportError with additional information, for example if a compiled extension for GATE or Geant4 cannot be loaded due to missing shared libraries. These messages can mention things like cannot open shared object file or missing libG4*.so. These are environment and installation problems: Python found opengate but failed to load its internal components. The solution usually involves checking that the Geant4 and GATE libraries are correctly installed and that your runtime environment variables, such as LD_LIBRARY_PATH on Linux, are set appropriately.

If your script imports several modules, a good debugging approach is to comment out imports and re-enable them one by one. Start with the core GATE import, verify that it works, then reintroduce analysis and helper modules. This isolates which module actually causes the error.

A ModuleNotFoundError: No module named 'opengate' indicates that Python cannot see a GATE installation in the current environment. Verify that the correct environment is activated and that GATE and its dependencies are installed there before running your simulation script.

43.1. Python Errors

Syntax errors

Import errors

Comments

Where to Move