44.7. Version Control
Table of Contents
Git
For GATE projects, version control is as important as correct physics lists or geometry. Git is the standard tool you will meet in almost all research and development environments, and using it early will keep your simulations organized and traceable.
At its core, Git records snapshots of your project directory over time. Each snapshot is a commit, identified by a hash. When you change a simulation, Git lets you see exactly what changed, when, and why.
You typically start by creating a repository in the directory that contains your simulation scripts, configuration files, and possibly analysis notebooks. From that point, every meaningful change is committed with a short message that explains the purpose of the change. This message should describe the intent, not the mechanics. For example, “Adjust PET energy window to 350–650 keV” is more useful than “Update script.”
Git allows you to create branches, which are separate lines of development. For GATE work, branches are very useful when you want to test an alternative geometry, a new physics configuration, or a different source model without disturbing a stable baseline. You can, for example, keep a main branch that contains a validated scanner model and create feature branches for new ideas, such as a different detector material or a modified collimator design.
When you are satisfied with an experimental branch, you merge it back into the main branch. This keeps the history clear: the main branch remains close to what you would use for production runs or publications, and branches embody specific experiments and developments.
Using Git remotes, such as GitHub, GitLab, or an institutional server, allows you to back up your repository and collaborate with others. Pushing your commits to a remote server ensures that your simulation history is not lost if your local machine fails. It also allows collaborators to clone the repository, run the same simulations, and propose improvements through branches and merge requests.
It is important to decide what you track with Git. Source files, configuration files, and documentation belong in the repository. Large generated files such as ROOT outputs, dose images, and temporary logs usually do not. Instead, you keep small text files that describe how to regenerate those outputs. You can instruct Git to ignore certain files using a dedicated ignore file so that your repository remains focused on code and configuration, not massive datasets.
Git history becomes valuable when you need to understand past decisions. If a later result looks suspicious, you can examine older commits to see which geometry or physics settings were used. You can also check out an older commit and re-run the simulation exactly as it was at that time, provided that the environment and external conditions are preserved, which ties directly into reproducible simulations.
Treat Git commits as scientific records: commit small, logical changes with clear messages, keep large output files out of the repository, and use branches to isolate new ideas from validated baselines.
Reproducible simulations
Reproducibility means that you, or someone else, can rerun a GATE simulation at a later time and obtain statistically consistent results, given the same configuration. Version control is a key part of this, but it is not sufficient by itself. You must also capture all elements that influence the simulation outcome.
First, the exact version of your simulation code must be identifiable. Using Git, you can refer to a specific commit hash. In your simulation logs, you can record this hash, either manually or by having your Python script query Git when the simulation starts. This directly links each run to a precise state of the code.
Second, the software environment must be known. This includes the GATE version, the Geant4 version, the compiler used to build them, and the Python library versions that you use for pre and post processing. One common approach is to keep environment description files under version control, such as a list of Python dependencies. This allows others to reconstruct a compatible environment. For more controlled setups, you may also use containerization, but the technical details of that are covered elsewhere.
Third, random number seeds must be controlled and recorded. Monte Carlo simulations rely on random sampling, so even with identical code, different seeds will produce different random histories. If you set the random seed explicitly in your configuration and log its value, you can reproduce the exact sequence of events. If you want runs to be independent but still reproducible, you can base seeds on a simple rule, for example, different integer seeds per job, and record those in your metadata.
Fourth, all input data must be versioned or at least clearly referenced. This includes CT images, voxelized activity maps, material maps, and any external parameter files. Ideally, small inputs are stored in the repository. For large clinical datasets, you may not store them in Git, but you should record unambiguous identifiers, such as patient IDs, acquisition dates, or dataset checksums, so that the same data can be located later.
Fifth, simulation parameters that are not in code should be documented. This includes things like the intended number of primary events, acquisition time, dose actor resolution, energy windows, and coincidence settings. Using configuration files instead of hard coded parameters helps keep these settings explicit and readable. These configuration files are then tracked with Git so their evolution over time is known.
Finally, link simulation runs to outputs through metadata. For every run, you can create a small text or JSON file that records the Git commit hash, random seeds, key parameters, environment description, date and time, and paths to main output files. This file should be stored alongside the output, and ideally the template for it belongs in the repository. This way, when you inspect a ROOT file or a dose image months later, you can find out exactly how it was produced.
A simulation is reproducible only if you can reconstruct the code version, environment, random seeds, input data, and configuration parameters. Use Git to track the first two, configuration files for the third and fourth, and small metadata files to connect each simulation run to its outputs.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction to GATE
- ☰ 1.1. What Is GATE?
- ☰ 1.2. Applications of GATE
- ☰ 1.3. GATE vs Geant4
- ☰ 1.4. GATE Simulation Workflow
-
- ☰ 2. Installing GATE
- ☰ 2.1. GATE Requirements
- ☰ 2.2. Creating a Python Environment
- ☰ 2.3. Installing GATE
- ☰ 2.4. Verifying the Installation
- ☰ 2.5. GATE Example Simulations
-
- ☰ 3. Python Basics for GATE
- ☰ 3.1. Variables and Data Types
- ☰ 3.2. Conditional Statements
- ☰ 3.3. Loops
- ☰ 3.4. Functions
- ☰ 3.5. Python Modules
- ☰ 3.6. NumPy Basics
- ☰ 3.7. Working with Files
-
- ☰ 4. Creating Your First GATE Simulation
- ☰ 4.1. Importing GATE
- ☰ 4.2. Creating a Simulation
- ☰ 4.3. Adding the World
- ☰ 4.4. Adding a Particle Source
- ☰ 4.5. Adding an Actor
- ☰ 4.6. Running the Simulation
- ☰ 4.7. Inspecting the Results
-
- ☰ 5. Units in GATE
- ☰ 5.1. Physical Units
- ☰ 5.2. Length Units
- ☰ 5.3. Energy Units
- ☰ 5.4. Time Units
- ☰ 5.5. Radioactivity Units
- ☰ 5.6. Using Units Correctly
-
- ☰ 6. Geometry Fundamentals
- ☰ 6.1. The World Volume
- ☰ 6.2. Creating Volumes
- ☰ 6.3. Box Geometry
- ☰ 6.4. Cylindrical Geometry
- ☰ 6.5. Spherical Geometry
- ☰ 6.6. Position and Translation
- ☰ 6.7. Rotation
-
- ☰ 7. Building Complex Geometry
- ☰ 7.1. Nested Volumes
- ☰ 7.2. Repeated Volumes
- ☰ 7.3. Ring Geometry
- ☰ 7.4. Boolean Geometry
- ☰ 7.5. Geometry Overlap
- ☰ 7.6. Reusable Geometry Functions
-
- ☰ 8. Materials
- ☰ 8.1. Material Definitions
- ☰ 8.2. Geant4 Material Database
- ☰ 8.3. Common Medical Materials
- ☰ 8.4. Detector Materials
- ☰ 8.5. Shielding Materials
- ☰ 8.6. Creating Custom Materials
-
- ☰ 9. Geometry Visualization
- ☰ 9.1. Enabling Visualization
- ☰ 9.2. Displaying Volumes
- ☰ 9.3. Changing the View
- ☰ 9.4. Volume Appearance
- ☰ 9.5. Visualizing Particle Tracks
- ☰ 9.6. Debugging with Visualization
-
- ☰ 10. Particle Sources
- ☰ 10.1. Generic Sources
- ☰ 10.2. Particle Types
- ☰ 10.3. Source Position
- ☰ 10.4. Source Direction
- ☰ 10.5. Source Energy
- ☰ 10.6. Source Activity
-
- ☰ 11. Radioactive Sources
- ☰ 11.1. Radioactive Decay
- ☰ 11.2. Medical Radionuclides
- ☰ 11.3. Positron Emitters
- ☰ 11.4. Gamma Emitters
- ☰ 11.5. Activity Distribution
- ☰ 11.6. Time-Dependent Activity
-
- ☰ 12. Physics Lists
- ☰ 12.1. What Is a Physics List?
- ☰ 12.2. Electromagnetic Physics
- ☰ 12.3. Gamma Physics
- ☰ 12.4. Electron Physics
- ☰ 12.5. Positron Physics
- ☰ 12.6. Hadronic Physics
- ☰ 12.7. Choosing Physics Models
-
- ☰ 13. Production Cuts and Transport Parameters
- ☰ 13.1. What Are Production Cuts?
- ☰ 13.2. Range Cuts
- ☰ 13.3. Region-Based Cuts
- ☰ 13.4. Accuracy vs Performance
-
- ☰ 14. Actors
- ☰ 14.1. What Is an Actor?
- ☰ 14.2. Simulation Statistics Actor
- ☰ 14.3. Energy Deposition Actor
- ☰ 14.4. Dose Actor
- ☰ 14.5. Phase Space Actor
- ☰ 14.6. Particle Fluence
- ☰ 14.7. Actor Filters
-
- ☰ 15. Dose Calculation
- ☰ 15.1. Energy Deposition
- ☰ 15.2. Absorbed Dose
- ☰ 15.3. Creating a Dose Actor
- ☰ 15.4. Dose Images
- ☰ 15.5. Statistical Uncertainty
- ☰ 15.6. Dose Profiles
-
- ☰ 16. Hits and Detector Response
- ☰ 16.1. Particle Interactions in Detectors
- ☰ 16.2. Hits
- ☰ 16.3. Hit Collections
- ☰ 16.4. Hit Attributes
- ☰ 16.5. Hits vs Detector Signals
-
- ☰ 17. Digitizers
- ☰ 17.1. What Is Digitization?
- ☰ 17.2. Digitizer Chain
- ☰ 17.3. Energy Summation
- ☰ 17.4. Readout
- ☰ 17.5. Energy Blurring
- ☰ 17.6. Spatial Blurring
- ☰ 17.7. Energy Thresholds
- ☰ 17.8. Time Blurring
-
- ☰ 18. Singles
- ☰ 18.1. What Are Singles?
- ☰ 18.2. Creating Singles
- ☰ 18.3. Detector Identification
- ☰ 18.4. Energy Windows
- ☰ 18.5. Analyzing Singles
-
- ☰ 19. Coincidences
- ☰ 19.1. What Are Coincidences?
- ☰ 19.2. Coincidence Sorting
- ☰ 19.3. True Coincidences
- ☰ 19.4. Scattered Coincidences
- ☰ 19.5. Random Coincidences
- ☰ 19.6. Coincidence Timing
- ☰ 19.7. Coincidence Output
-
- ☰ 20. Data Output
- ☰ 20.1. Simulation Output
- ☰ 20.2. ROOT Output
- ☰ 20.3. Image Output
- ☰ 20.4. Text-Based Output
- ☰ 20.5. Organizing Simulation Results
-
- ☰ 21. GATE and ROOT
- ☰ 21.1. Reading GATE ROOT Files
- ☰ 21.2. Inspecting Output
- ☰ 21.3. Energy Histograms
- ☰ 21.4. Time Histograms
- ☰ 21.5. Detector Maps
- ☰ 21.6. Filtering Events
-
- ☰ 22. GATE and Python Data Analysis
- ☰ 22.1. Reading Simulation Output with Python
- ☰ 22.2. Energy Spectra
- ☰ 22.3. Position Distributions
- ☰ 22.4. Timing Analysis
- ☰ 22.5. Statistical Analysis
- ☰ 22.6. Visualization
-
- ☰ 23. Voxelized Geometry
- ☰ 23.1. Introduction to Voxelized Geometry
- ☰ 23.2. Image-Based Volumes
- ☰ 23.3. Material Mapping
- ☰ 23.4. CT-to-Material Conversion
- ☰ 23.5. Patient Geometry
- ☰ 23.6. Visualizing Voxelized Geometry
-
- ☰ 24. Image and DICOM Data
- ☰ 24.1. Medical Image Formats
- ☰ 24.2. Reading CT Images
- ☰ 24.3. DICOM CT Data
- ☰ 24.4. RT Structure Sets
- ☰ 24.5. RT Plans
- ☰ 24.6. Coordinate Systems
-
- ☰ 25. Motion and Time-Dependent Simulations
- ☰ 25.1. Time in GATE
- ☰ 25.2. Moving Sources
- ☰ 25.3. Moving Detectors
- ☰ 25.4. Respiratory Motion
- ☰ 25.5. Scanner Rotation
- ☰ 25.6. Dynamic Imaging
-
- ☰ 26. PET Simulation Fundamentals
- ☰ 26.1. PET Physics
- ☰ 26.2. PET Scanner Components
- ☰ 26.3. PET Detector Geometry
- ☰ 26.4. PET Source
- ☰ 26.5. PET Physics Configuration
- ☰ 26.6. PET Detector Response
-
- ☰ 27. Building a PET Scanner
- ☰ 27.1. Creating the Detector Ring
- ☰ 27.2. Creating Detector Blocks
- ☰ 27.3. Creating Detector Crystals
- ☰ 27.4. Assigning Detector IDs
- ☰ 27.5. Adding a PET Source
- ☰ 27.6. Configuring the Digitizer
- ☰ 27.7. Running the PET Simulation
-
- ☰ 28. PET Coincidence Analysis
- ☰ 28.1. Coincidence Events
- ☰ 28.2. Energy Selection
- ☰ 28.3. Coincidence Time Window
- ☰ 28.4. Lines of Response
- ☰ 28.5. True Events
- ☰ 28.6. Scatter Events
- ☰ 28.7. Random Events
- ☰ 28.8. PET Performance Metrics
-
- ☰ 29. Time-of-Flight PET
- ☰ 29.1. TOF PET Principles
- ☰ 29.2. Detector Timing Resolution
- ☰ 29.3. Time Difference
- ☰ 29.4. Timing Blurring
- ☰ 29.5. Analyzing TOF Events
-
- ☰ 30. SPECT Simulation Fundamentals
- ☰ 30.1. SPECT Physics
- ☰ 30.2. SPECT Scanner Components
- ☰ 30.3. SPECT Radionuclides
- ☰ 30.4. Gamma Camera Geometry
- ☰ 30.5. SPECT Source
-
- ☰ 31. Building a Gamma Camera
- ☰ 31.1. Detector Head
- ☰ 31.2. Collimator
- ☰ 31.3. Shielding
- ☰ 31.4. Energy Resolution
- ☰ 31.5. Energy Window
- ☰ 31.6. Projection Data
-
- ☰ 32. SPECT Acquisition
- ☰ 32.1. Rotating Gamma Camera
- ☰ 32.2. Projection Angles
- ☰ 32.3. Acquisition Time
- ☰ 32.4. Energy Windows
- ☰ 32.5. Projection Images
- ☰ 32.6. SPECT Data Analysis
-
- ☰ 33. CT and X-Ray Simulation
- ☰ 33.1. X-Ray Physics
- ☰ 33.2. X-Ray Source
- ☰ 33.3. CT Geometry
- ☰ 33.4. Detector Array
- ☰ 33.5. Rotating CT Geometry
- ☰ 33.6. CT Projection Data
-
- ☰ 34. Radiation Therapy Simulation
- ☰ 34.1. External Beam Radiotherapy
- ☰ 34.2. Photon Beams
- ☰ 34.3. Electron Beams
- ☰ 34.4. Dose Calculation
- ☰ 34.5. Beam Geometry
- ☰ 34.6. Dose Validation
-
- ☰ 35. Proton Therapy Simulation
- ☰ 35.1. Proton Physics
- ☰ 35.2. Proton Beam
- ☰ 35.3. Water Phantom
- ☰ 35.4. Bragg Peak
- ☰ 35.5. Spread-Out Bragg Peak
- ☰ 35.6. Proton Dose Analysis
-
- ☰ 36. Internal Dosimetry
- ☰ 36.1. Radioactive Sources in the Body
- ☰ 36.2. Voxelized Activity Maps
- ☰ 36.3. Energy Deposition
- ☰ 36.4. Dose Maps
- ☰ 36.5. Radionuclide Therapy
- ☰ 36.6. Dose Analysis
-
- ☰ 37. Optical Photon Simulation
- ☰ 37.1. Optical Physics
- ☰ 37.2. Scintillation
- ☰ 37.3. Optical Properties
- ☰ 37.4. Optical Surfaces
- ☰ 37.5. Photodetectors
- ☰ 37.6. Optical Photon Detection
-
- ☰ 38. Phase-Space Data
- ☰ 38.1. What Is a Phase Space?
- ☰ 38.2. Recording Phase-Space Data
- ☰ 38.3. Phase-Space Files
- ☰ 38.4. Phase-Space Sources
- ☰ 38.5. Applications
-
- ☰ 39. Random Numbers and Reproducibility
- ☰ 39.1. Monte Carlo Random Numbers
- ☰ 39.2. Random Seeds
- ☰ 39.3. Independent Simulations
- ☰ 39.4. Reproducible Research
-
- ☰ 40. Multithreading and Performance
- ☰ 40.1. Multithreaded Simulation
- ☰ 40.2. Selecting the Number of Threads
- ☰ 40.3. Simulation Speed
- ☰ 40.4. Optimizing Geometry
- ☰ 40.5. Optimizing Output
- ☰ 40.6. Large Simulations
-
- ☰ 41. Running GATE on HPC Systems
- ☰ 41.1. Why Use HPC?
- ☰ 41.2. Running GATE Without Visualization
- ☰ 41.3. Job Scripts
- ☰ 41.4. Running with Slurm
- ☰ 41.5. Running Multiple Simulations
- ☰ 41.6. Combining Results
-
- ☰ 42. Simulation Validation
- ☰ 42.1. Why Validate a GATE Simulation?
- ☰ 42.2. Geometry Validation
- ☰ 42.3. Physics Validation
- ☰ 42.4. Comparing with Analytical Models
- ☰ 42.5. Comparing with Experimental Data
- ☰ 42.6. Statistical Validation
-
- ☰ 43. Debugging GATE Simulations
- ☰ 43.1. Python Errors
- ☰ 43.2. Geometry Problems
- ☰ 43.3. Material Errors
- ☰ 43.4. Source Problems
- ☰ 43.5. Physics Problems
- ☰ 43.6. Actor Problems
- ☰ 43.7. Digitizer Problems
- ☰ 43.8. Performance Problems
-
- ☰ 44. Writing Better GATE Simulations
- ☰ 44.1. Organizing Simulation Scripts
- ☰ 44.2. Configuration Files
- ☰ 44.3. Avoiding Hard-Coded Values
- ☰ 44.4. Reusable Components
- ☰ 44.5. Output Organization
- ☰ 44.6. Documentation
- ☰ 44.7. Version Control
-
- ☰ 45. Practical Example: Gamma-Ray Detector
- ☰ 45.1. Project Overview
- ☰ 45.2. Creating the World
- ☰ 45.3. Creating the Detector
- ☰ 45.4. Creating a Gamma Source
- ☰ 45.5. Configuring Electromagnetic Physics
- ☰ 45.6. Recording Energy Deposition
- ☰ 45.7. Adding Energy Resolution
- ☰ 45.8. Creating an Energy Spectrum
- ☰ 45.9. Analyzing the Spectrum
-
- ☰ 46. Practical Example: Radiation Shielding
- ☰ 46.1. Project Overview
- ☰ 46.2. Creating the Source
- ☰ 46.3. Creating the Shield
- ☰ 46.4. Selecting Shielding Materials
- ☰ 46.5. Changing Shield Thickness
- ☰ 46.6. Recording Transmitted Photons
- ☰ 46.7. Calculating Transmission
- ☰ 46.8. Calculating Attenuation
- ☰ 46.9. Comparing with the Exponential Attenuation Law
-
- ☰ 47. Practical Example: PET Scanner
- ☰ 47.1. Project Overview
- ☰ 47.2. Creating the PET Ring
- ☰ 47.3. Creating Detector Modules
- ☰ 47.4. Creating Detector Crystals
- ☰ 47.5. Adding an F-18 Source
- ☰ 47.6. Configuring PET Physics
- ☰ 47.7. Recording Hits
- ☰ 47.8. Creating Singles
- ☰ 47.9. Applying Energy Blurring
- ☰ 47.10. Applying the PET Energy Window
- ☰ 47.11. Sorting Coincidences
- ☰ 47.12. Identifying True Coincidences
- ☰ 47.13. Identifying Scattered Coincidences
- ☰ 47.14. Creating Lines of Response
- ☰ 47.15. Saving PET Data
-
Comments
Please login to add a comment.
Don't have an account? Register now!