36.3. Common Geant4 Macro Commands

Table of Contents

Overview

Geant4 macro commands let you control most aspects of a simulation from text files, without recompiling your C++ code. This appendix collects frequently used commands in one place so that you can quickly look them up when writing or reading .mac files.

Macros are executed either at startup or interactively during a session. They affect geometry, physics initialization, particle sources, visualization, and analysis, depending on which command directories you use.

Important: Many commands are only valid in specific states of the run manager, for example before or after /run/initialize, or before starting /run/beamOn. Watch for error messages indicating that a command is used in the wrong state.

Running Macro Files

You typically store commands in files with extension .mac. The main ways to run them are:

Use this command in an interactive Geant4 session:

tcl

/control/execute init.mac

This reads and executes commands from init.mac as if you typed them line by line.

You can also ask your executable to start with a macro:

bash

./exampleApp init.mac

In many standard examples, the main() program detects the argument and runs /control/execute automatically.

To include one macro inside another, use:

tcl

/control/execute vis.mac

inside e.g. init.mac. This lets you separate initialization, visualization, and production runs into different files.

Run Control Commands

Run control commands live under /run. They initialize the run manager and start event loops.

The most common commands are:

tcl

/run/initialize
/run/beamOn 1000

/run/initialize tells Geant4 to build geometry, set up the physics list, and prepare the run manager. You must call it at least once before using most physics or source commands. If you change geometry or physics via commands, Geant4 may require you to reinitialize.

/run/beamOn N starts a run of N events with the current configuration. After beamOn completes, you can adjust macro parameters and call beamOn again.

Useful additional commands include:

tcl

/run/verbose 1
/run/printProgress 1000
/run/abort

/run/verbose sets how much information the run manager prints. /run/printProgress prints a progress line every given number of events. /run/abort stops the current run, which is handy in interactive sessions if something is wrong.

For multithreaded runs, you can control the number of worker threads before initialization:

tcl

/run/numberOfThreads 4

Rule: Set /run/numberOfThreads and other run configuration options before /run/initialize. Changing them after initialization is often ignored or causes errors.

Geometry and Physics Configuration Commands

Some geometry and physics options are controlled by user-defined commands under /detector/, /geom/, /physics/, or other directories. Their exact names depend on how the example or your own code is written, but many reference examples follow a similar pattern.

A typical pattern looks like:

tcl

# Geometry configuration before initialization
/detector/setWorldSize 1.0 m
/detector/setMaterial G4_WATER
/run/initialize

After changing geometry parameters, you usually need to reinitialize:

tcl

/detector/setWorldSize 2.0 m
/run/reinitializeGeometry

or, depending on the application:

tcl

/run/reinitializeGeometry
/run/initialize

For physics, reference physics lists can be selected in some examples via commands such as:

tcl

/physics/selectPhysics FTFP_BERT

or physics options can be toggled:

tcl

/physics/addPhysics emstandard_opt3

The exact commands here are application-specific, but the principle is always the same: change the configuration, then reinitialize if required.

Rule: Any change that affects geometry or physics must be applied before event simulation, and usually followed by a suitable reinitialization command.

Primary Particle Source Commands

Primary particles can be controlled through the particle gun or the General Particle Source (GPS). Which commands are available depends on whether your application uses G4ParticleGun or G4GeneralParticleSource.

Particle gun commands

A common command directory is /gun/:

tcl

# Choose particle type
/gun/particle e-
# Set primary energy
/gun/energy 10 MeV
# Set initial position
/gun/position 0 0 -5 cm
# Set direction (unit vector)
/gun/direction 0 0 1

Some examples also provide commands for multiple guns or user-defined sources. These typically follow the same style.

General Particle Source (GPS) commands

If your application uses GPS, you control it through /gps/:

tcl

/gps/particle gamma
/gps/energy 1 MeV
/gps/position 0 0 -10 cm
/gps/direction 0 0 1

GPS can define position, angular, and energy distributions:

tcl

# Position: source on a plane disk
/gps/pos/type Plane
/gps/pos/shape Circle
/gps/pos/centre 0 0 -10 cm
/gps/pos/radius 5 cm
# Angular: isotropic emission
/gps/ang/type iso
# Energy: monoenergetic
/gps/ene/type Mono
/gps/ene/mono 511 keV

These commands let you build realistic sources entirely from macros.

Rule: For long or complex GPS configurations, keep them in a separate macro file such as source.mac, and include it with /control/execute source.mac. This makes it easier to change source definitions without touching other settings.

Visualization Commands

Visualization is controlled through commands under /vis and sometimes /control.

Opening a visualization driver

To start the default OpenGL viewer if available:

tcl

/vis/open OGL 600x600-0+0

Variants depend on how Geant4 was built, for example:

tcl

/vis/open OGL  # Generic OpenGL viewer
/vis/open OGLSQt  # OpenGL with Qt GUI (if enabled)

The exact driver name can vary, but most examples document recommended options in a vis.mac file.

After opening, initialize basic visualization:

tcl

/vis/drawVolume
/vis/viewer/setStyle surface
/vis/viewer/setBackground white

Changing the view

Camera and zoom are controlled through /vis/viewer commands:

tcl

# Rotate the view
/vis/viewer/set/viewpointThetaPhi 60 30 deg
/vis/viewer/zoom 1.2
# Reset view
/vis/viewer/reset

You can also control the field of view and the target point:

tcl

/vis/viewer/set/target 0 0 0 mm
/vis/viewer/set/fieldOfView 45 deg

Visualization attributes and models

To control how geometry and tracks appear, use:

tcl

/vis/scene/create
/vis/scene/add/volume
/vis/scene/add/axes 0 0 0 10 cm

Attributes such as wireframe, color, and transparency are often set by presets:

tcl

/vis/viewer/set/style surface
/vis/viewer/set/lineSegmentsPerCircle 100

Some examples expose geometry-specific commands, for example to hide or show detector parts using logical volume names.

Displaying trajectories and hits

To see particle tracks:

tcl

/vis/scene/add/trajectories smooth
/vis/scene/endOfEventAction accumulate
/tracking/verbose 1

Common commands to control track style include:

tcl

/vis/modeling/trajectories/create/drawByParticleID
/vis/modeling/trajectories/drawByParticleID-0/set gamma yellow
/vis/modeling/trajectories/drawByParticleID-0/set e- red

To draw hits and digits, you may use:

tcl

/vis/scene/add/hits

if your application defines visual models for them.

Rule: Always execute visualization commands after /vis/open. If the viewer is not open, many /vis commands have no effect or produce warnings.

Stepping, Tracking, and Verbose Output Commands

Verbose commands help you debug event and track behavior.

To control tracking and stepping printout:

tcl

/tracking/verbose 1
/stepping/verbose 1

Typical levels:

Level	Meaning (approximate)
0	Silent
1	One-line summary per track/step
2	More detailed information
3+	Very detailed, often only for debugging

You can also restrict tracking to certain particles or volumes in some examples through custom commands. For general debugging, built-in commands include:

tcl

/process/list
/process/verbose 1

which print available processes and their configuration.

For geometry navigation debugging, you can use:

tcl

/geometry/test/run
/geometry/test/verbose 1

in examples that provide those commands.

Rule: Use high verbose levels only for small numbers of events. Large runs with /stepping/verbose 3 can generate enormous output and slow the simulation dramatically.

Analysis and Output Commands

If your application uses G4AnalysisManager with command support, you can control histograms and ntuples via macro commands under /analysis.

Common patterns are:

tcl

/analysis/setFileName output
/analysis/setFileType root
/analysis/openFile
/analysis/h1/set 0 "Edep in detector" 100 0 10 MeV
/analysis/h1/print 0
/analysis/closeFile

The actual commands depend on how the analysis is implemented, but often include:

tcl

/analysis/verbose 1
/analysis/list

to manage analysis objects.

Applications often define their own analysis-related command directories, for example:

tcl

/myapp/setEnergySpectrumFile spectrum.root
/myapp/setOutputPrefix run1_

These are user commands described in the specific example documentation.

Rule: To avoid losing data, always ensure that macros close analysis files via an appropriate command, for example /analysis/closeFile, after the last /run/beamOn.

Controlling Parameters Without Recompiling

One of the main advantages of macro commands is the ability to adjust parameters without changing and recompiling C++ code. Typical workflows for production runs use separate macros for initialization, visualization, and production.

A simple pattern is:

tcl

# init.mac
/control/verbose 2
/run/verbose 1
# Geometry and physics configuration
/detector/setMaterial G4_WATER
/physics/selectPhysics FTFP_BERT
/run/initialize

tcl

# vis.mac
/vis/open OGL
/vis/drawVolume
/vis/scene/add/trajectories smooth
/vis/viewer/set/style surface

tcl

# run.mac
/control/execute init.mac
/gps/particle gamma
/gps/energy 1 MeV
/run/beamOn 10000

By editing only run.mac and possibly a source.mac, you can change the number of events, beam parameters, or output file names, while leaving compiled code untouched.

Key practice: Keep macro files under version control together with your C++ source. They are part of the definition of a simulation and are necessary to reproduce results.

This appendix covered common Geant4 macro commands and how they fit into typical workflows. When working with a specific example or your own application, always check the available command directories with:

tcl

/control/manual
/control/manual /myapp/