KAHIBARO
2.5 GATE Example Simulations
Table of Contents
Exploring example scripts
Once GATE is installed, the fastest way to learn is to look at the example simulations that come with OpenGATE. These are small, self‑contained Python scripts that demonstrate typical medical physics tasks, such as simple sources, basic detectors, PET or SPECT setups, and dose calculations.
Depending on how you installed OpenGATE, the examples are usually located in a directory similar to opengate/examples inside the Python package or in a cloned Git repository. You can locate them from Python by checking the module path. For example, after starting a Python prompt and importing the package, you can print opengate.__file__ which tells you where the module is installed. Inside that folder there is normally an examples subdirectory that contains multiple example scripts and, sometimes, subfolders for specific applications.
Each example typically follows the same overall structure. At the top, there is the import of opengate and sometimes other scientific Python modules, for instance NumPy. Then the script creates a simulation object, defines the world geometry, adds a few volumes, defines particle sources, chooses physics, attaches actors, and then runs the simulation. Many examples are very short, often less than 100 lines of code, which makes them convenient to read line by line.
For a beginner it is helpful to classify examples by their purpose. Some focus on basic geometry and units, for example a single box in air with a simple gamma source. Others are scanner examples, such as PET rings or SPECT gamma cameras, which combine geometry, sources, physics lists, and digitizers. There are also examples that focus on dosimetry in water or simple phantoms. When you open an example file, look at its header comments, which usually describe what the simulation is about, what kind of output it produces, and which actors or digitizers are used.
The input files for examples are not limited to Python. Some examples may reference external data, such as material files, spectra, or simple text configuration files. It is useful to inspect the whole example directory, not just the main script, so you understand all required inputs and where output will be written.
If you are completely new to GATE, focus first on the simplest example that runs quickly, for instance a small world with a single source and one actor. This helps you understand how the main steps of the OpenGATE simulation workflow appear in code, without the complexity of scanners or voxelized geometry, which are covered in later chapters.
Running examples
Once you have identified an example you want to try, you run it like a normal Python script. Make sure that your Python environment is the one where OpenGATE and its dependencies are installed, and that any required environment variables for Geant4 are set, as described earlier in the installation chapter.
Move into the example directory with a terminal and list the files. Most examples are simple Python files like example_basic.py or pet_ring.py. To run one of them, use a command in the terminal such as python example_basic.py, replacing the name with the actual example file. The script will start, initialize Geant4 through OpenGATE, print basic information about the simulation setup, and then process events.
In many examples you will see terminal output that indicates the progress of the simulation, for example the number of processed events or the current run status. Some examples run very quickly and may only print a short summary at the end. Others, especially those with many events or complex geometries, may take longer. It is a good practice to begin with examples that run in a few seconds, so you can iterate more easily.
Some example scripts accept command line arguments, such as the number of events or the output directory. These arguments are usually parsed with Python’s standard libraries. If the example supports this, it is documented near the top of the script or in a brief README in the same directory. To see available options, you can sometimes run python example_name.py --help and read the printed description.
Most examples produce at least one output file. The type of file depends on what the example demonstrates. You might see ROOT files that store hits, singles, or coincidences, or image files that store dose or activity distributions, for example in MHD or NIfTI formats. The location of the output is usually a subdirectory within the example folder, or a directory that the script creates, such as a folder named output or results. Open the script and read how it defines the output paths so you know where to look after the run finishes.
On some systems, examples that use geometry visualization might open a window that displays the detector or world volumes. These examples sometimes require you to run them from a terminal where visualization is enabled and a graphical environment is available. If visualization is not needed, or you are on a remote system without graphics, look for examples that run completely in batch mode and disable visualization in their code.
When you run an example for the first time, it can be instructive to keep the script open in a text editor at the same time. As the simulation prints messages, try to identify which part of the code is responsible for each step. This will help you later when you write your own scripts and want to understand how configuration, running, and output generation are connected.
Modifying examples
Working directly with the example scripts is an effective way to learn how to build your own simulations. A safe approach is to copy an example into a separate working directory and then change that copy, so that the original example stays intact. For instance, you might create a folder named my_gate_tests, copy example_basic.py into it, rename it to something like my_first_simulation.py, and work on that version.
Begin with very small modifications. You can, for example, change the number of simulated events, the size of the world, or the energy of a monoenergetic source. After each change, run the script again and check that it still executes correctly and that the output reflects your modifications. This step by step strategy reduces the chance of introducing several issues at once, which can make debugging more difficult for beginners.
An important early experiment is to modify geometry and units. For instance, you might change a detector box from a few millimeters to a few centimeters, or move a source along the z axis. Each time, reconstruct in your mind what the geometry should look like and then, if the example supports visualization, verify the placement visually. This helps you build intuition for coordinate systems and for how GATE uses units, which are discussed in a separate chapter.
You can also experiment with source definitions. Try changing the particle type from gamma to electron, or adjust the source position from a point source to a small volume source, in line with the source configuration options shown in later chapters. While modifying sources, be careful to keep units consistent, for example specifying energy in keV or MeV exactly as the example does. If you are uncertain about units, consult the units chapter of this course.
Another useful modification is to adjust or add actors. Choose an example that already uses a simple actor, such as one that records simulation statistics or energy deposition in a volume. Duplicate the actor configuration, change the target volume, or modify the output file name. By doing this you will see how multiple actors can be attached to one simulation, and how each produces separate outputs that you can analyze later.
As you become more comfortable, you can mix elements from different examples. For instance, you might take a geometry definition from one example and combine it with a source and actor configuration from another. To do that successfully, make sure that names of volumes and variables are consistent, and that you do not accidentally define the world volume or physics lists twice. Keeping your code organized into small functions, as discussed in later chapters on writing better simulations, helps a lot at this stage.
Whenever you apply a more substantial change, it is a good idea to check for simple problems first if something goes wrong. For example, make sure all imports are still valid, that paths to any input data are correct, and that volume names match between geometry definition and actor configuration. If a modified example fails, you can quickly compare it against the original to see exactly what you changed and then identify which change caused the issue.
As you continue to modify examples, aim to gradually move from minor edits toward building your own script where you recognize every component. By the time you finish working through several examples in this way, you will have an intuitive understanding of how the key pieces of a GATE simulation are combined in Python code. This foundation will prepare you for the later chapters that describe more specialized simulation setups and analysis workflows in detail.
Always keep a clean, unmodified copy of the original example scripts. Use copies for experiments and changes. This practice makes it easy to recover from mistakes and compare working and non‑working versions line by line.
Views: 16