KAHIBARO
Documentation
Table of Contents
Comments
Writing clear comments in your GATE Python scripts is the first and simplest form of documentation. Comments should explain why the code is written in a particular way, not repeat what the code already states. For absolute beginners, it is tempting to annotate every line, but this quickly becomes noise and is hard to maintain. Instead, comment at the level of logical blocks, functions, and non-obvious parameter choices.
Use short comments at the top of each script to describe the purpose of the simulation, the main components created, and the expected outputs. This helps you and others remember what the script does without reading every line. For example, a brief header comment can mention the scanner type, physics configuration, and what is being measured.
Within the script, place comments at the beginning of each major section such as geometry creation, source configuration, physics setup, actor configuration, and digitizer setup. When a parameter is not obvious, like a numerical cut value or a specific energy window, add a short explanation that links it to a physical concept or to a reference, for instance a publication or a standard.
Whenever you compute or use important formulas, add a comment that includes the formula and its meaning. If you implement a dose normalization, an attenuation correction, or a unit conversion that is easy to misinterpret, write a clear explanation next to it and, if possible, mention the units of all terms.
Always document:
- Non-trivial numerical values and where they come from.
- Any approximation or simplification you make.
- Any place where default GATE behavior is intentionally overridden.
Function and class docstrings are particularly useful in larger GATE projects. When you write helper functions to build geometry, configure sources, or add actors, include a docstring that briefly describes what the function does, the meaning and units of its arguments, and what it returns. This avoids confusion when you or your collaborators reuse these functions in new simulations.
As your simulation evolves, update comments when you change the logic or parameters. Outdated comments are worse than missing comments because they actively mislead the reader. A good practice is to review comments whenever you refactor geometry, physics lists, or output configuration.
Finally, remember that comments complement, not replace, clear code structure. Break long scripts into smaller, logically named functions so that the code expresses the structure of the simulation. Comments then serve to clarify scientific intent and specific GATE-related choices, not to decode tangled code.
README files
A README file provides high level documentation for an entire simulation project. While comments describe parts of the code, the README explains the purpose of the project, how to run it, and how to interpret the results. For GATE simulations, a well written README is crucial for reproducibility and for collaboration.
Place a README file at the top level of your project directory and write it in a simple format such as Markdown so it is easy to read on most platforms. Start with a short overview that states the scientific or technical goal of the simulation, for example modeling a specific PET scanner, evaluating shielding performance, or computing patient dose. Mention the main GATE components you use only very briefly, since other chapters explain them in detail.
Document the software environment required to run the project. Specify the GATE or OpenGATE version, Geant4 version, Python version, and any important Python packages with minimal version constraints. If you use a particular physics list variant, mention it and provide a pointer to the corresponding configuration file or code section.
Include a concise description of the project structure so that a new user can find key scripts and data. For example, describe which file creates the geometry, which script runs standard simulations, and where output is written. If you separate configuration from code with JSON, YAML, or Python config files, point to them and explain their role.
A practical README should contain a short, explicit run guide. Describe the basic commands needed to execute the simulation from a fresh environment. Show how to launch a typical simulation, including required arguments such as configuration file paths, output directories, or number of events. If running on a local machine differs from running on a cluster, include separate instructions.
Many beginners forget to document how to analyze the results. Add a section that lists the main output files and their formats, such as ROOT files, dose images, or CSV tables. Explain what each contains at a high level, and reference any analysis scripts you provide. For example, state that a script reads singles from a ROOT file and produces an energy spectrum, or that another script creates dose profiles from a 3D dose map.
Whenever you apply important formulas or performance metrics in your analysis, such as sensitivity, scatter fraction, or transmission, summarize them in the README. For instance, define transmission $T$ for a shielding study as
$$
T = \frac{N_{\text{with shield}}}{N_{\text{without shield}}}
$$
and state how $N_{\text{with shield}}$ and $N_{\text{without shield}}$ are obtained from your simulation.
A useful README must explain:
- The purpose of the simulation and its main assumptions.
- How to install the required environment and run the scripts.
- What the key outputs are and how to perform the basic analysis.
Finally, treat the README as a living document. Each time you make an important change to geometry, physics options, sources, or analysis workflows, update the README to reflect the new behavior. If you perform validation against measurements or analytical models, briefly describe what was compared and where to find the corresponding data or figures. This practice keeps your GATE simulations understandable, shareable, and scientifically transparent.
Views: 12