KAHIBARO
44.5. Output Organization
Table of Contents
Simulation IDs
A clear, consistent way to identify simulations is essential once you move beyond tiny test runs. A “simulation ID” is a short label that uniquely identifies a specific run or configuration so that you can recover exactly what was done, even months later.
A simple simulation ID usually combines a project tag, a configuration tag, and a timestamp. For example, pet_ring_v2_2026-08-18_1430 already tells you which scanner model you used, which configuration version, and when the run started. For more complex projects, you might also want to include the physics setting, number of events, or a short label describing the parameter being varied, such as shielding_lead_5cm_1e7events_2026-08-18_1430.
In Python-based GATE simulations, it is good practice to create the simulation ID once at the beginning of the script and reuse it everywhere. One typical pattern is to build it from simple strings and a time stamp, then use that variable to name directories, log files, and main output files. This avoids accidental mismatches between directory names and file names and makes it easy to find everything related to a given run.
You can also separate the human-friendly simulation ID from a more rigid internal identifier. Some users generate a short hash, such as from a configuration file, then combine both. For example, pet_tof_v3_ab12cd_2026-08-18_1430. The hash can help you verify that two runs used exactly the same settings even if they were executed at different times or on different machines.
For parameter studies, simulation IDs become even more important. You might run dozens or hundreds of simulations with small changes, for example varying a detector thickness or a beam energy. In that case, encode the varied parameter and its value explicitly inside the ID, such as proton_E150MeV, proton_E160MeV, and so on. This makes it straightforward to map simulation results to the parameter that was changed, without having to open configuration files each time.
Always use a unique simulation ID for each distinct run, and reuse that ID consistently for directory names, main output files, and logs. This is crucial for reproducibility and for avoiding accidental overwriting of previous results.
As projects grow, you may want to record simulation IDs and their key characteristics in a separate index file, for example a simple CSV table where each row contains the ID, date, main parameters, and maybe a short description. This index acts as a compact catalog of all runs and makes it easier to select the right data later for analysis, publications, or re-running a particular case.
Result directories
Organizing result directories is about defining a predictable folder structure so that every output file has a clear place and meaning. A good structure makes it easy to answer questions like “Where are the singles for this PET run?” or “Where is the dose map for that CT-based simulation?” without opening the script.
A practical starting point is to have one top-level folder per project, such as pet_scanner_project or shielding_study. Inside this project folder, collect simulations in a dedicated results or runs directory. Then, for each simulation, create a subdirectory whose name is the simulation ID. For example, you might have results/pet_ring_v2_2026-08-18_1430 and results/pet_ring_v3_2026-08-19_1015. This pattern ties the simulation ID directly to its directory and keeps runs separate.
Within each simulation directory, it is helpful to separate raw simulation outputs from processed data and from logs. A simple convention is to create subfolders like output, analysis, and logs. The output folder contains raw GATE outputs such as ROOT files, dose images, and voxel data. The analysis folder collects files produced by later scripts, for example spectra, profiles, and CSV summaries. The logs folder holds text logs, captured terminal output, and any error reports that are useful for debugging or verification.
Tables can help you think about how to distribute typical files. A simple example is:
| Subdirectory | Typical contents |
|---|---|
output | ROOT files, MHD or NIfTI images, CSV outputs written directly by the simulation |
analysis | Processed spectra, dose profiles, plots, summary tables created after the run |
logs | Simulation log files, error messages, standard output captured to text |
You can refine this further for specific applications. For PET or SPECT simulations, you might create additional folders inside output such as hits, singles, coincidences, or projections when you write separate ROOT or image files for each data type. For dose studies, you might prefer separate dose and phsp subfolders for dose images and phase space data. The exact layout is flexible, but the key idea is consistency: once you choose a scheme, use it for all runs in the project.
To make this robust, construct directory paths programmatically in your Python scripts, starting from a base results path and your simulation ID. Create directories at the beginning of the run, before you configure actors and outputs. This ensures that GATE can always write to valid locations and that your output is never scattered into unexpected default folders.
It is also useful to store a copy of the simulation configuration inside the result directory. This might be the full Python script, a separate configuration file, or a serialized form of key parameters. Place these copies in a dedicated subfolder, for example config, so that each result directory is self-contained. If you revisit a simulation later, you can reconstruct exactly what was done from within that directory alone.
Finally, when you run many simulations on HPC systems, a clear directory organization helps with automated post-processing. For example, you can write scripts that search all run directories under results for certain output files, combine them, and generate summary plots for entire parameter scans. This becomes much easier when every simulation follows the same directory layout and naming rules tied to its simulation ID.
Views: 11