Why Documentation Matters

Clear documentation is as important to a Geant4 project as correct physics and geometry. It allows you, collaborators, and future maintainers to understand what the simulation does, how it does it, and what the results mean. A well documented Geant4 application is easier to validate, extend, and debug. It also makes published results more credible, because reviewers and readers can see what was really simulated.

In practice, documentation for a Geant4 application should exist at several levels. You need high level project documentation that explains the purpose and design, in code comments that clarify implementation details, and user facing documentation that explains how to build, configure, and run the application. For beginners, it is tempting to skip documentation while experimenting. This creates serious problems later, when you no longer remember why a particular cut value or geometry parameter was chosen, or exactly which configuration produced a given plot.

Good documentation does not have to be long, but it must be precise, up to date, and located where users expect to find it.

Layers of Documentation in a Geant4 Project

A typical Geant4 application can be documented in several complementary layers, each with a different purpose and audience.

At the highest level, a short project overview file explains the goal of the simulation, the main components of the geometry, what physics is modeled, and which outputs are produced. This is often a single text file in the top level directory, such as README.md. It answers questions like "What is this code for?" and "How do I start it?".

Inside the source code, comments and small design notes explain how classes work together and why certain implementation choices were made. This is for developers who read and modify the code. They need to know, for example, which class owns which object, how user actions are registered, and where analysis code is attached.

Configuration and macro files can also serve as documentation. Well named macros, with brief comments above critical commands, tell users how to run standard scenarios and what each scenario represents physically. For example, one macro may correspond to a specific detector configuration that was used to produce figures in a paper.

Finally, user guides and analysis notes describe how to reproduce specific studies, which input parameters should be used, and how to interpret the output. These are important for scientific results and collaborations, where more detailed explanation is expected than what fits into code comments.

Documenting the Simulation Design

Design documentation explains what you are simulating and how the simulation is structured, without going into every line of code. It connects the real detector or experimental concept to the abstract Geant4 objects.

For a Geant4 application, it is useful to explicitly describe at least the following design aspects: the overall purpose of the simulation and the physical questions it addresses, the main detector components and their approximate dimensions and materials, the logical arrangement of user classes such as detector construction, physics list, and user actions, and the main analysis outputs that will be produced.

This information can be written as a short design document, or placed in the top of a README. A typical beginner friendly description might state that the geometry consists of a world filled with air that contains a single scintillator block and a simplified photodetector volume, that photons are generated from a point source with defined energy, and that energy deposited in the scintillator is recorded per event.

Whenever you make important design decisions, such as simplifying a complex detector into a few volumes, or choosing to ignore certain processes, those simplifications must be documented. The documentation should say clearly what has been neglected and why this is acceptable for the intended use. Without this, it is impossible to judge whether the simulation is appropriate for a given analysis.

Documenting Geometry and Materials

Geometry and material choices are central to any Geant4 simulation, so they require careful and explicit documentation. For beginners, it is often easiest to summarize them twice: once in code comments near the relevant classes, and once in a higher level description or table.

In code, you can document geometry by explaining what each logical volume represents in the real detector. Above the construction of a volume, briefly state whether it is a shielding layer, a detector crystal, a support structure, or some other component. Include the nominal dimensions in human readable form and their physical meaning, such as crystal length, diameter, or gap thickness.

Materials should be described not only by their Geant4 names but also by their physical meaning and origin. For NIST materials, you can note the corresponding material name and any assumptions. For custom materials and mixtures, it is important to record the composition, density, and the source of those values, for example from a paper or a datasheet.

A simple text table in your documentation can summarize key geometry parameters. For example:

Such tables complement the code and help readers understand the detector structure without reading C++.

Documenting Physics Lists and Cuts

Physics configuration is not obvious from visual inspection of the geometry. If you select a particular physics list or adjust production cuts, the reasons and implications must be recorded.

At minimum, you should document which reference physics list you are using, such as FTFP_BERT, and why it is appropriate for your energy range and particles. If you derive a custom physics list or add or remove processes, describe this in both code comments and a short physics configuration section in your project documentation.

Production cuts and other thresholds can strongly affect results. Whenever you change default cuts, write down the values used, the units, and the physical motivation. For example, you may reduce electron cuts inside a detector to better resolve low energy deposits, or increase them in distant shielding to speed up computation. A small note that states "gamma cut reduced to 0.1 mm inside the crystal to improve energy resolution modeling" is far more useful than leaving the numbers unexplained.

You should also document any physics that you know is not simulated, such as neglecting optical photons or ignoring certain hadronic processes. This helps prevent users from misusing the simulation for questions it cannot answer.

Documenting Primary Sources and Configurations

Particle sources are often configured through macro commands, which are easy to change but also easy to forget. For reproducible studies, each important source configuration must be documented.

First, clearly describe the primary particle type, energy or spectrum, spatial distribution, and angular distribution used for the standard runs. This can be done with a short text description and a pointer to the macro file that implements it. For example, you might define a "collimated 662 keV gamma beam" configuration and reference the macro that sets up the primary generator accordingly.

If you use the General Particle Source, the configuration can become complex. In this case, it is helpful to keep separate macros for different source types and to include comments in the macros that explain each block of commands. The top level documentation should then list the available macros and what physical scenario each represents.

For parameter studies, such as varying source energy or position, describe the parameter ranges and step sizes used, particularly if the results will be compared with measurements or reported in a publication.

Documenting Analysis and Output

Analysis code in Geant4 applications often contains important decisions about how energy, timing, and other quantities are selected and combined into final observables. These decisions need clear documentation to avoid misinterpretation of results.

You should document what histograms and ntuples are created, what each column or bin represents, and which units are used. For example, if you store deposited energy per event in MeV and positions in millimeters, this should be explicitly stated. Names like E_dep_crystal or t_global_ns are self documenting, but a short explanation in the documentation or in a separate analysis note adds clarity.

Cuts and selections applied in analysis, such as energy windows for detector hits, coincidence timing windows, or spatial fiducial cuts, should be described in terms of both numerical values and physical meaning. For instance, you might specify that hits between 400 keV and 700 keV are considered full energy events, and that this corresponds to an energy window around a particular gamma line.

If the Geant4 application writes ROOT or CSV files that are later processed by external scripts, document the structure of these files. A simple table that lists each ntuple column and its meaning can save time for every future user.

Using Comments Effectively

Code comments are the most immediate form of documentation and are especially helpful for beginners who may struggle to remember why they wrote something in a particular way. However, comments must be used thoughtfully.

Focus comments on explaining intent and design rather than restating obvious C++ syntax. For example, instead of commenting that a variable stores the world volume pointer when the variable name already makes this clear, comment on what physical region the world represents and why its size is chosen as it is. Comments should clarify the mapping between code and physics.

For each major user class, a short comment near the class definition can describe its role in the simulation. Inside methods such as Construct() or user action callbacks, briefly describe the sequence of important operations, such as constructing the main detector volumes, attaching sensitive detectors, or filling histograms.

Whenever you implement a non trivial algorithm or workaround, document the reason and, if applicable, point to external references such as a Geant4 manual section, a physics paper, or an example application that inspired the approach.

Finally, treat comments as part of the code. When you change behavior, update or remove outdated comments. Incorrect comments are worse than no comments, because they actively mislead readers.

Writing User Guides and Usage Instructions

User facing documentation explains how to build, configure, and run the application. This is separate from code comments and is often written as a short guide in a text or Markdown file.

For a Geant4 application, a minimal user guide should include build prerequisites such as Geant4 version and required compilers, build instructions that show the typical steps to configure and compile with CMake, and run instructions that explain how to start the application in interactive and batch mode.

You should also list the main macro files and describe what each one does. For example, one macro may set up a default visualization run, another may run a long statistics production without graphics, and another may be dedicated to a specific study.

It is also useful to document typical analysis workflows. If the user is expected to run a ROOT macro or a Python script on the output files, provide the command line examples and a short sentence describing what the script produces.

For beginners in a teaching context, the user guide can also mention common issues and where to look when runs fail, such as missing environment variables or incorrect paths to data libraries, although detailed debugging is covered elsewhere.

Keeping Documentation Up to Date

Documentation is only useful if it reflects the current code. As a project evolves, geometry, physics, and analysis often change. Without a process to update documentation, it will slowly diverge from reality.

To reduce this risk, try to keep documentation close to the things it describes. Geometry descriptions belong near the detector construction code and in a top level overview. Physics choices should be documented where you configure the physics list and in a central physics section. Macro descriptions should be near the macros themselves.

It is also helpful to maintain a simple change log that records major modifications, such as new detector components, changes in materials, or important adjustments in cuts or source definitions. Each entry should include a short description, a date, and a reason for the change.

For larger projects and collaborations, documentation can be managed like code, using version control and possibly a generated documentation system. Even for simple teaching examples, a small but consistent effort to keep documentation accurate will save time for everyone who uses or studies the application.

Views: 10