KAHIBARO
41.2. Running GATE Without Visualization
Table of Contents
Batch mode
On high performance computing systems you typically run GATE in batch mode, which means the simulation runs from start to finish without any interactive prompts or on-screen graphics. For OpenGATE with Python this is very natural, because your simulation is already a Python script. The key idea is that everything required for the run must be defined inside the script itself: geometry, sources, physics, actors, digitizers, and output paths.
In batch mode you never open interactive visualization windows, you never pause to type commands, and you do not rely on a graphical user interface. Instead, you prepare a self-contained script, submit it as a job to the HPC scheduler, and examine the output files once the job finishes.
From the perspective of your Python script, there is usually no special “batch mode” flag. The script simply starts, configures the simulation, calls the run function, then exits. What makes it “batch” is how you launch it on the cluster. You run it with a non-interactive command such as:
python my_gate_simulation.pyinside a job script submitted with the scheduler, for example with Slurm or another batch system. Because there is no user present, you must make sure that the script can be executed from the command line without any manual input.
It is good practice to parameterize your batch simulations using command line arguments or configuration files. For example, you might pass the random seed, number of events, or geometry variant as arguments. This allows you to launch many similar batch jobs with different settings. In Python you can access these arguments via the sys or argparse modules.
Batch mode is also where you usually enable multithreading. You select the number of threads programmatically inside the script, sometimes based on environment variables provided by the scheduler. In this mode you do not want to share the same job node among many interactive applications, so you match the number of threads to the CPU cores allotted to your job.
Finally, remember that in batch mode all feedback comes from log files and terminal output. Arrange your script so that important messages, parameters, and summary statistics are printed to standard output or written into a log file. This is often your only way to understand what happened during the run once the job has left the queue.
In batch mode you must ensure that:
- The simulation runs from start to finish without any user interaction.
- All visualization calls and GUI components are disabled.
- Important settings and results are written to files or logs, not to interactive windows.
Headless execution
Headless execution means running GATE on a system without any graphical display, such as a compute node on an HPC cluster. Even if your account allows remote login, compute nodes typically have no access to a graphical desktop or X server. If your simulation attempts to open a visualization window, it will usually fail or hang.
To run headless, your GATE Python script must never try to load visualization drivers or start interactive viewers. Any code that creates graphical viewers, windows, or interactive user interfaces must be removed or executed only when a display is available. A simple pattern is to control visualization through a Python flag, for example a boolean variable called use_vis. When this flag is false, you skip all visualization setup, and the simulation runs headless.
On a local development machine you might use visualization to debug geometry and sources. Before sending the simulation to the cluster, you edit or configure the script so that the visualization section is turned off. You can then verify that the script still runs correctly on your local machine in a terminal without opening any windows. If this non-graphical run is successful, it is usually safe to use the same script on an HPC compute node.
Headless execution also affects how you inspect results. On a workstation, you might open graphic user interfaces or plotting windows directly from the simulation code. On a cluster, you typically write all relevant output into files, then transfer those files back to a workstation for inspection. That means your headless script should focus on generating complete, self-describing output: simulation configuration, logs, statistics, and data files that can be read later by Python, ROOT, or imaging tools.
A common source of errors in headless mode is the environment itself. Even if you do not use visualization explicitly, underlying libraries might attempt to connect to a display. If you see errors related to display variables or X connections, you may need to adjust environment variables so that no graphical backend is used. In Python, for plotting libraries such as Matplotlib, this often means selecting a non-interactive backend that writes directly to image files instead of opening a window.
From the point of view of the scheduler, headless execution is the normal way to run Monte Carlo simulations. There is no keyboard, mouse, or screen. Your job receives CPU time, memory, and access to the filesystem, and it is expected to complete autonomously. Design your GATE scripts so they behave correctly in this environment and you will be able to scale simulations to large clusters without modification.
For successful headless execution:
- Disable all visualization and GUI calls in your simulation.
- Ensure plotting and analysis write files instead of opening windows.
- Test the script in a non-graphical environment before submitting to the HPC cluster.
Views: 9