35.13. Document the Simulation

Table of Contents

Why Documentation Matters

A Geant4 simulation is more than code and plots. It is a scientific instrument that others must be able to understand, reproduce, review, and extend. Good documentation explains what you built, why you made particular choices, and how to repeat or modify your work. It also protects you from your future self when you return to the project months later.

For the final project, treat documentation as part of the deliverable, not an optional extra. Aim for a level of detail that allows a competent Geant4 user, who has not seen your code before, to re-create your results.

A simulation that cannot be understood or reproduced is not scientifically useful, no matter how sophisticated the code or how nice the plots look.

Describing the Simulation Goal

Begin with a brief description of what your simulation is intended to do. Focus on the primary question or quantity you want to compute.

State the goal in one or two clear sentences, for example:

"Estimate the energy spectrum deposited in a NaI(Tl) detector by 662 keV gamma rays."
"Compute the depth dose curve in water for a 150 MeV proton pencil beam and identify the Bragg peak position."
"Simulate coincidence events in a simplified PET ring and reconstruct lines of response."

Then add a little context, such as why this is interesting or relevant, but do not turn it into a full literature review. This section anchors all later design choices and justifies simplifications.

Always document the primary observable(s) that your simulation is designed to produce, for example "energy spectrum at detector," "depth dose," or "coincidence rate." All design choices should be traceable to these observables.

Recording Geometry and Materials

Your report must include a precise description of the detector and world geometry. Someone should be able to reconstruct your geometry from the document, without seeing the code.

Describe the geometry verbally, and complement the text with simple figures or tables. For each important volume, explain:

What physical object it represents
Its shape and main dimensions
Its material
Its position and orientation relative to a clear reference (usually the world origin or beam axis)

A compact way to capture this information is a table.

Volume name	Shape	Main dimensions	Material	Position (x, y, z) [mm]	Notes
World	Box	2 m × 2 m × 2 m	Air	(0, 0, 0)	Contains all other volumes
WaterPhantom	Box	300 × 300 × 300	Water	(0, 0, 150)	Centered along +z beam axis
DetectorCrystal	Cylinder	r = 25, length = 50	NaI	(0, 0, 0)	Centered at origin
LeadShield	Box	200 × 200 × 50	Lead	(0, 0, 100)	Between source and detector

Include one or two schematic drawings or screenshots from the Geant4 visualizer to clarify the geometry, but do not rely on them alone. Text and numbers must be sufficient.

For materials, note whether you use NIST materials or custom definitions. For custom materials or mixtures, record:

Element composition (symbols or names)
Fraction by mass or by number of atoms
Density

For example:

"Soft tissue is modeled as G4_TISSUE_SOFT_ICRP from the Geant4 NIST database. The scintillator is a custom material representing LYSO, with density 7.1 g/cm$^3$, composed of Lu, Y, Si, O in the standard proportions used in [reference]."

Always document all non-standard materials. If you define a custom material in C++, reproduce its density and composition in the report.

Documenting Particle Sources and Conditions

Describe your primary particle sources in a way that decouples the physics idea from the specific Geant4 class you used.

Include, at minimum:

Particle type, for example gamma, proton, positron
Energy or energy spectrum
Angular distribution
Spatial distribution and extent
Number of primaries per event or per run

Provide both qualitative description ("monoenergetic pencil proton beam") and quantitative settings.

Example:

"The primary source is a monoenergetic beam of 150 MeV protons. The beam is represented by a point source at position (0, 0, −200 mm), directed along the +z axis. The beam has no divergence in this simplified model. In each event a single proton is generated using G4ParticleGun. A typical run uses $N = 10^6$ events."

If you use the General Particle Source, record the macro commands that define the source, or refer to a specific macro file stored in the repository, and describe the physical meaning of those commands in text.

If the source models a real experimental situation, note any idealizations. For example, "The real beam has a Gaussian energy spread with $\sigma_E = 1\%$, but here it is approximated as monoenergetic."

Always state energy, position, and direction distributions of your sources. These are critical for reproducing results and for understanding the validity of your conclusions.

Physics List, Models, and Cuts

Document which physics list and optional physics components you use, and why they are appropriate for your problem.

Typical documentation items include:

Name of the reference physics list, for example FTFP_BERT, QGSP_BIC_EMY
Any electromagnetic or hadronic options you enabled or disabled
Global production cuts (in range or energy) for different particle types
Any significant overrides for specific regions or volumes

Explain briefly why the chosen physics list is suitable. For absolute beginners it is enough to say something like:

"FTFP_BERT is used, since it is a standard general purpose list recommended for hadrons in the energy range from a few MeV to hundreds of GeV."

If you adjust production cuts, document the motivation and numeric values. For example:

"Global production cuts are set to 0.1 mm for gamma, electron, and positron, in order to better resolve the dose deposition near the Bragg peak. Default cuts were found to smear the steep gradient."

Whenever you change physics lists or production cuts from their defaults, record both the values and the reason. Do not leave these decisions hidden in code or macros.

Explaining Scoring and Analysis

Your documentation must identify what quantities are scored, how they are computed, and how they are analyzed. This is where you connect simulation steps to final plots.

Describe:

Which volumes are sensitive detectors
What a "hit" means in your simulation, for example one energy deposition step in a crystal element
What is accumulated per event, for example total energy deposit in each voxel, or number of coincidences between detectors
Which histograms and ntuples you define and what each axis represents

You can summarize the main observables in a table.

Observable name	Definition	Units	Where defined
`Edep_crystal`	Sum of $dE$ in crystal per event	keV	`EventAction` via hits
`DepthDose[z]`	Mean deposited energy per slice at depth $z$	MeV/cm$^3$	Ntuple column, indexed by slice
`CoincidenceRate`	Number of detector pair hits in 2 ns window	counts / run	Analysis of PET hits ntuple

If you apply detector effects, smearing, or thresholds, describe the model clearly, including any formulas. For example, for Gaussian energy smearing:

$$
E_{\text{smeared}} = \mathcal{N}\left(E_{\text{true}}, \sigma_E\right), \quad \sigma_E = a \sqrt{E_{\text{true}}} \oplus b E_{\text{true}},
$$

with the numeric values of $a$ and $b$.

Always distinguish between true simulation quantities (for example exact $dE$ from Geant4) and reconstructed or smeared quantities (for example detector-like energy). Make this explicit in the documentation.

Recording Software and Build Information

Your project should be reproducible on another system. Record the software environment and build steps in a short, explicit section.

At minimum, include:

Geant4 version and data library version
Compiler and version
Operating system
Required external packages, for example ROOT, Qt
Exact CMake options relevant to your simulation (for example multithreading on or off, visualization options)

An example statement:

"The simulation was built with Geant4 11.1.2 and the corresponding data libraries, using GCC 11.3.0 on Ubuntu 22.04. CMake 3.22 was used with GEANT4_USE_QT and GEANT4_BUILD_MULTITHREADED enabled."

Then describe how to build and run the code:

"Create a build directory with mkdir build && cd build."
"Configure with cmake -DGeant4_DIR=/path/to/geant4-install/lib/Geant4-11.1.2 ../."
"Compile with cmake --build .."
"Set environment variables using source /path/to/geant4-install/bin/geant4.sh."
"Run the application with ./MySim run.mac."

These steps can be placed in a README.md and referenced by your main document.

Without explicit version information and build instructions, other users may not be able to compile or run your code, even if you share the sources.

Documenting Macros and Run Configuration

Most final projects rely heavily on macro files to configure runs. Treat macros as part of your documented interface, not as hidden technical details.

For each important macro, record:

Its purpose, for example "production run at 150 MeV," "visualization only," "parameter scan over lead thickness"
The key commands it contains, particularly those that affect physics, geometry parameters, source configuration, and the number of events

You do not need to copy entire macros into the report, but you should highlight the important commands, such as:

/run/initialize
/gps/particle, /gps/energy, /gps/position, /gps/direction
/process/em/verbose if you change process options
/run/setCut or region-specific cut commands
/run/beamOn N with the value of $N$

If you perform parameter scans, describe how the parameter is changed from one macro to another, or how you use a script to generate multiple macros.

Presenting Results and Figures

Your documentation should include a concise set of key figures that correspond directly to your simulation goals. For each figure:

Provide a clear caption describing what is shown
Indicate which simulation configuration and which macro produced the figure
State what is plotted on each axis, including units
Explain any normalization, for example "histogram normalized to unit area"

Reference figures in the text when you make claims. For example:

"Figure 3 shows the simulated depth dose distribution. The Bragg peak is located at $(153 \pm 1)$ mm, in good agreement with the analytical range of 154 mm for 150 MeV protons in water."

If you export data to ROOT or CSV, note the output filenames and their structure, such as:

"Per event energy deposition in the crystal is stored in output/gamma_detector.root in the tree Events, with branches Edep (MeV) and EventID (int)."

Validation, Limitations, and Assumptions

A crucial part of documentation is stating where your simulation is reliable and where it is simplified. Identify:

What you validated, for example comparison to analytical attenuation, dose curves, or published data
The level of agreement, preferably with numbers
The main assumptions and idealizations

Typical assumptions include:

Monoenergetic sources instead of real spectra
Perfect alignment of detector components
No dead time or pileup
Ignored physics, for example not modeling optical photons

In your documentation, explicitly connect limitations to possible effects on results. For example:

"Since optical photon transport is not modeled, absolute detection efficiency in the PET example is not realistic. Only geometric acceptance and annihilation kinematics are studied."

Always state at least the two or three largest approximations in your model, and briefly discuss how they might bias the main observables.

Writing the Project README

In addition to a full report, include a short README file at the top of your project. It should answer:

What is this simulation? (one or two sentences)
How do I build it?
How do I run basic examples?
Where do I find the detailed documentation and results?

Example structure:

Project title and one-line description
Prerequisites (Geant4 version, ROOT, etc.)
Build steps
Example commands to run visualization and production macros
Pointer to the main report file and to the directory with plots and output files

This small file makes the difference between a project that is practically usable and one that is opaque.

Making Documentation Maintainable

Documentation should evolve with the code. To keep it maintainable:

Store documentation files in the same version control repository as the code
Update version numbers, important parameters, and major changes whenever you modify the simulation
Avoid copying long pieces of code into the report. Instead, describe behavior in words and reference specific filenames and classes

You can include short, focused code snippets only when they clarify an important design decision, such as how you define a sensitive detector or implement smearing, but keep the main flow of the document at the conceptual level.

By following the practices in this chapter, your final project will not only demonstrate that you can write and run a Geant4 simulation, but also that you can communicate your work in a form that is scientifically robust, understandable, and reusable.