The GateLab

Preparing your simulation

A GATE simulation is composed of several files (macros files, but also data files. Your simulation folder must be organized as followed : all input files (including the GateMaterials.db file) must be in a "data" folder, all macro files in a "mac" folder and all output files in a "output" folder. All of these three folders must be in the same parent folder from which GATE will be executed. Your macro files must therefore refer to the inputs as "data/..." to macros as "mac/..." and outputs as "output/...". Note that your GateMaterials.db file has to be present in your data folder.

Simulation splitting and merging

The original GateLab application (since 2011 to June 2025) used to handle both the splitting and merging of one GATE simulation. Since the first of July 2025, the two operations (splitting and merging) are handled separately. The GATE application will generate a folder containing partial results, that you can then merge with the GATE_Merger application on VIP. Please note that the GATE_Merger takes as input both the output folder and the input zip archive generated by the GATE application at launch time.

Supported simulation types

Currently, only some types of simulations can be submitted with the GateLab. Remember that a simulation is composed of a (generally large) number of Events (primary particles) that are sequentially tracked. Some simulations also required several Runs, that are "group" of Events : the geometry is rebuild between each Run. Generally, several Runs are used when time is taken into account in the simulation. When a simulation requires more than one Run, it is a little bit less easy to be paralelized.

To determine if your simulation can be submitted, three cases can be determined

• Case 1. Your simulation contains only one Run and all Events are strictly equivalent, no matter of the order in which there are simulated. Typical examples are in the field of Radiation Therapy.
  • you should use the "dynamic parallelization", this is the most efficient situation.
• Case 2a. Your simulation contains only one Run and the order of Events is important, requiring timing information. Typical examples are PET/SPECT simulations with TimeSlice = TimeStop-TimeStart (only one Run).
  • you have to use the "static parallelization"
• Case 2b. Your simulation contains several Run and the order of Events is important, requiring timing information. Typical examples are SPECT simulations, but not PET simulation because, in that cases, coincidences will be biased. For typical PET simulation with several Runs, the proper way to split simulation should be to divide the TotalTime into different parts (for a dynamic scan : i frames with Ni processors per frame), each of them being an independent job. This is currently not implemented in the GateLab (mostly because it requires special care when a job fails), but we are working on it. Other examples of simulations falling in that case are Radiation Therapy simulations with motion (IMRT).
  • you have to use the "static parallelization"
• Case 3. All other cases.
  • you cannot (yet) use GateLab otherwise your results will be biased.

Remember to always use the "setTotalNumberOfPrimaries" macro command, which is the number of the events for PET/SPECT simulations. Just add this command before the commands of setting the TimeSlice, TimeStart and TimeStop. eg.

Launching your GATE simulation

Click on the "GATE" icon in your Home tab:

A new tab opens.

• Fill in the simulation name.
• Click on the LoadMac button.
• Select your main macro file using the file browser opened by the LoadMac button
  • Your main mac file is the one that contains the initialization line (e.g. "/gate/application/setTotalNumberOfPrimaries")
  • Your main mac file has to be on your local PC in a "mac/" folder as explained in the first remark below
  • Your main macro file is automatically parsed and uploaded on the distant storage space (see also the file transfer page) together with your other input data
• Fill in the rest of the form:
  • The number of parallel jobs into which your simulation is automatically split. If you choose one, you will get a single output. If not, you will get multiple partial outputs that can be merged with the GATE_Merger application.
• Before you launch the simulation, you can use the "Save Inputs" button to save the form and reload it for a future simulation
• Click on the launch button to launch the simulation.

Important Remarks

• Please note that in order for the parsing to be accurate, all input files (including your GateMaterials.db file) must be in a "data" folder, all macro files in a "mac" folder and all output files in a "output" folder, and all of these folders must be in the same parent folder from which GATE will be executed. Your macro files should therefore refer to the inputs as "data/..." to macros as "mac/..." and outputs as "output/..."
• If you have header-file inputs (e.g. hdr/img hdr/bin file "couples") the data file must have the same name as the header file (for ex: input1.hdr and input1.img)
• The initialization line "/gate/application/setTotalNumberOfPrimaries" must be present in the submitted macro file.
• Primary particle number must be an integer number. Formats like "20e9" are not supported.

Launching GATE_Merger

Click on the "GATE_Merger" icon to open the merger form.

Monitoring your simulations

All your simulations

In your Home tab you have a 'Monitor GateLab' icon:

• Click on the 'Monitor GateLab' icon. A new tab with the list of all your simulations opens.
• The small icon on the left gives the status of the simulation.
  • Green wheel = the simulation is running
  • Red wheel = the simulation has failed
  • Blue tick = the simulation has completed successefully
• For each simulation you can
  • Click on the simulation you want to monitor. The simulation will open in a new tab
  • Kill the simulation. This will stop all the jobs and the workflow
  • Clean the simulation. Attention, this will delete the simulation output and log files!

One of your simulations

• Click on the simulation you want to monitor. The simulation will open in a new tab
• On you left hand side, you have three available tabs
  • General Information tab (default): gives access to general information, as well as on the simulation logs (output and error files). The "total particles simulated" field corresponds to what has been computed (more than requested in the case of dynamic parallelization)
  • Jobs Summary tab: list of jobs submitted by the platform. Error and stalled jobs are automatically resubmitted.
  • Performance statistics: graphs ans stats on executed jobs

Retrieving outputs

In the General Information tab of you simulation, you have access to a list of the simulation's inputs and outputs. In order to retrieve the output, simply click on the output link and download it. For more information on file transfer see also the file transfer page.