29.7. Parameter Scans

Table of Contents

Why Do Parameter Scans?

In many Geant4 studies you are not interested in a single configuration, but in how a result changes when a parameter changes. This can be a detector dimension, a material property, a threshold, a beam energy, or a physics setting. Exploring how observables depend on such parameters is called a parameter scan.

Parameter scans help you to find optimal detector designs, to tune physics settings, or to study systematics. Instead of manually changing a value, recompiling, and rerunning, you should design your application so that scans are easy and mostly automated.

Important: Never hide important simulation parameters as fixed numbers in your C++ code. Make them configurable so that you can change them from macros or from the command line without recompilation.

Making Parameters Configurable

To run useful scans you must first expose the parameters that you want to vary. In Geant4 this is usually done through:

C++ configuration variables in your user classes, for example in the detector construction or primary generator.
Geant4 UI commands that can modify those variables at run time.
Optional command line arguments that select or override macro files.

A common pattern is to add data members to your detector or source classes, with setter methods that UI commands can call. For example, you might store a detector thickness in the detector construction class as a G4double and use it when you build the geometry.

To change parameters safely you must understand when it is valid to modify them. Geometry and physics cannot change in the middle of a run. If you change a parameter that affects geometry or physics, you must reinitialize the run manager before starting the next run.

Rule: If a parameter affects geometry or physics, you must:

Finish the current run.
Change the parameter through a UI command.
Call /run/initialize before the next /run/beamOn.

Using Macros for Simple Scans

For beginners the most straightforward way to perform parameter scans is to use Geant4 macro files. A macro is a sequence of UI commands stored in a text file with extension .mac. You can run a macro at start up or from within another macro.

A typical manual scan workflow looks like this:

Create a base macro that defines visualization, physics list selection, output file naming pattern, and analysis settings.
Create one macro per parameter value, each of which:

Sets the parameter through UI commands.
Calls /run/initialize if needed.
Starts a run with /run/beamOn N.

Run the application repeatedly with different macro files.

You can also write a main macro that calls other macros with /control/execute. For example, you can create scan.mac that executes config_1.mac, runs some events, then executes config_2.mac, and so on. This is very convenient for scans that do not require changing the executable or recompiling.

Rule: In a macro scan, always separate parameter changes by a new /run/initialize plus a new /run/beamOn. Do not try to change geometry or physics during a run.

Although manual macro scans are simple, they become tedious and error prone when you need many parameter points. To handle large scans you should use scripting outside Geant4.

Automating Scans with External Scripts

For more than a few parameter values it is best to drive Geant4 from an external script. Common choices are shell scripts, Python scripts, or simple batch systems. The idea is always the same:

Prepare a template macro that contains placeholder values.
For each parameter value:

Create a concrete macro from the template, or pass the value to Geant4 as a command line argument that your main macro uses.
Choose a unique output file name, for example by encoding the parameter value in the file name.
Run the Geant4 executable in batch mode with that macro.
Optionally run simulations in parallel on multiple CPU cores or on a cluster.

One simple approach is to pass macro file names as arguments to main() and write a short script that loops over a list of macro files. Another approach is to call a single macro and pass parameters through environment variables or extra command line options, then use those values in your UI commands.

Although the scripting details are outside this chapter, the key idea is that Geant4 does not need to know about the scan. It only needs to read a parameter value from a macro and produce output labeled with that value. The outer script controls which values are used and collects the results.

Important: When automating scans, ensure every job writes to a unique output file. Never let multiple runs or threads write to the same file name if you intend to keep their results separate.

Reinitializing Between Parameter Points

Whenever a parameter change affects geometry, materials, fields, or the physics list, the internal state of the run manager must be updated. Geant4 provides two main reinitialization commands:

/run/initialize which reinitializes geometry and physics.
/run/reinitializeGeometry which tells Geant4 that only the geometry has changed.

For simple scans it is usually safe to call /run/initialize after setting new parameter values and before starting the next beam. For scans that only change source properties, such as particle energy or direction, you do not need to reinitialize. You can simply issue new /gps or /gun commands before calling /run/beamOn again.

A typical macro that scans a geometry parameter follows this pattern:

Set the parameter value with a UI command.
Call /run/initialize.
Set the run specific quantities such as the number of events and output file name.
Call /run/beamOn.
Repeat steps 1 to 4 for the next parameter.

Rule: Changing geometry or materials without reinitialization leads to undefined behavior. Always reinitialize after such changes before the next run.

Ensuring correct reinitialization is an important part of performance as well. Reinitializing too often wastes time, while reinitializing too rarely can give incorrect results. In a scan over many parameter values, group changes so that you only reinitialize when absolutely necessary.

Managing Output and Analysis for Scans

Parameter scans produce many separate simulation runs, each with its own output. You must organize this output so that later analysis is simple and reliable. There are two main approaches:

One output file per parameter value. For example, spectrum_E10MeV.root, spectrum_E20MeV.root, and so on. This is simple and easy to understand.
One combined file that contains results from all parameter values, stored in different histograms or in an ntuple with an extra column that identifies the parameter value. This can be more convenient for interactive analysis.

When you use G4AnalysisManager, you can control output file names and histogram IDs through UI commands or configuration variables. Combine this with macro parameters or scripting so that each run tags its results with the correct parameter values.

Rule: Always record the parameter values used in each run together with the simulation output. Without this, you cannot later interpret your scan results correctly.

For beginners it is often easiest to use one output file per parameter, named in a way that encodes that parameter. For larger scans and more advanced workflows, you might add a column to your ntuple that stores the parameter value for every event.

Good bookkeeping is part of simulation performance. If your scan generates hundreds of files but you cannot remember which file corresponds to which configuration, you effectively lose the benefit of your computation time.

Performance Considerations in Parameter Scans

A parameter scan multiplies the cost of a single simulation by the number of parameter points. To keep the total time feasible, you must consider performance more carefully than in a single run.

You can combine several techniques from other parts of this chapter of the course:

Use a physics list that is appropriate for your study and not more complex than necessary.
Simplify the geometry as far as your study allows.
Use production cuts that balance accuracy and speed.
Reduce unneeded verbose output and avoid writing huge amounts of detail for every event.

In a parameter scan you also have scan specific tradeoffs. For example, you might use fewer events per parameter point to obtain a coarse overview, then rerun only the most interesting values with more statistics. You might also arrange your scanning order so that you can inspect intermediate results early and adjust the scan if necessary.

Multithreading can be especially valuable when you run many independent simulations. You can either run each parameter point with multiple threads or run several parameter points in parallel, each with single threaded Geant4. The optimal choice depends on your hardware and analysis tools.

Guideline: Treat the total number of particle histories in the entire scan as your main cost. Adjust both the number of parameter points and the number of events per point so that the total is manageable and statistically meaningful.

By designing your application with configurable parameters, by controlling reinitialization correctly, and by automating scan execution and output organization, you can explore complex parameter spaces efficiently and reproducibly.