4.6 Running the Simulation

Table of Contents

Starting the simulation

Once your geometry, sources, physics, and actors are defined and the simulation object is fully configured, you trigger the run from Python. In OpenGATE this is almost always done with a single call on your simulation object, typically named sim.

A minimal pattern looks like:

python

import opengate as gate
sim = gate.Simulation()
# ... all your configuration goes here ...
sim.run()

The important points are:

You should call sim.run() only after all configuration steps are complete. If you modify geometry, sources, or actors after calling run, those changes will not affect the current run.
sim.run() is a blocking call. The Python script pauses while the simulation is running. You can think of it as “start and wait until GATE is finished.” When the method returns, all output files should be written and closed.
The typical life cycle in your script is:

Create the simulation object.
Configure world, geometry, materials, sources, physics, actors, digitizers.
Optionally print or save the configuration.
Call sim.run().
Postprocess or inspect the output.

You may also see options passed to run, for example a specific number of threads, if you do not set it earlier:

python

sim.run(start_new_process=False)

or by changing attributes before running:

python

sim.number_of_threads = 4
sim.run()

Details about multithreading and performance are handled in their own chapter, so here you only need to know that the run call is the single entry point that actually launches the Monte Carlo simulation.

Before calling run in larger scripts it is often practical to print a short message, for example:

python

print("Starting GATE simulation...")
sim.run()
print("Simulation finished.")

This helps you separate your own script messages from GATE terminal output.

Understanding terminal output

When you call sim.run(), Geant4 and GATE print information to the terminal. For a first simulation this output may look long and technical, but you only need to recognize a few key parts.

At the very beginning you usually see information about the Geant4 version, the physics list, and the number of threads. For example, lines that state the Geant4 version number or confirm which physics configuration is activated. This is a quick check that your installation is detected correctly and that the physics list you selected earlier is in use.

Next you often see messages about geometry initialization. There can be lines that mention “Constructing geometry” or “World volume,” sometimes followed by names of volumes you created in your script. If there is a geometry problem such as an overlap or a missing material, warning or error messages will appear here. For a simple first simulation you want to see no errors and no “overlap” warnings. If the program stops with a message here, the run did not start correctly and no useful output will be produced.

After geometry and physics initialization, the output moves to the event loop. GATE will indicate how many events or primary particles it is going to simulate. There may be a progress display, for instance periodic messages like:

### Run 0 starts.
... 
** Event 1000
** Event 2000
...
### Run 0 completed.

or a percentage completion indicator. These lines tell you that particles are actually being simulated and that your source and physics configuration are active. If the run seems to “hang” without any of these progress messages and without CPU usage, it is usually a sign of a configuration problem that must be checked in earlier parts of the output.

Near the end of the terminal log GATE prints a summary. This often includes the total number of events processed, the CPU time spent, and possibly the number of threads used. Some actors can also print brief summaries in the terminal, for example total energy deposited or number of hits recorded. These are very compact checks that the actors you added are active and collecting data.

If an error occurs during the run, GATE and Python will typically show a stack trace or a specific error message. The most common patterns for beginners are missing output paths, unknown materials, or actor configuration problems. For now, it is enough to know that a normal successful run ends with a clear completion message and returns control to your Python script without an exception.

To interpret terminal output efficiently, focus on three checkpoints in order:

Initialization lines without errors. This confirms that your simulation can be built.
Event loop messages that progress to the target number of events. This confirms that particles are generated and transported.
Final summary and a clean return to the Python prompt. This confirms that the simulation finished and that output files are complete.

Whenever you are in doubt about whether a run really completed, look at the last few lines of the terminal output and confirm that they show the end of the run, not an error.

4.6 Running the Simulation

Starting the simulation

Understanding terminal output

Comments

Where to Move