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:
/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:
./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:
/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:
/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:
/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:
/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:
# Geometry configuration before initialization
/detector/setWorldSize 1.0 m
/detector/setMaterial G4_WATER
/run/initializeAfter changing geometry parameters, you usually need to reinitialize:
/detector/setWorldSize 2.0 m
/run/reinitializeGeometryor, depending on the application:
/run/reinitializeGeometry
/run/initializeFor physics, reference physics lists can be selected in some examples via commands such as:
/physics/selectPhysics FTFP_BERTor physics options can be toggled:
/physics/addPhysics emstandard_opt3The 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/:
# 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 1Some 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/:
/gps/particle gamma
/gps/energy 1 MeV
/gps/position 0 0 -10 cm
/gps/direction 0 0 1GPS can define position, angular, and energy distributions:
# 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 keVThese 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:
/vis/open OGL 600x600-0+0Variants depend on how Geant4 was built, for example:
/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:
/vis/drawVolume
/vis/viewer/setStyle surface
/vis/viewer/setBackground whiteChanging the view
Camera and zoom are controlled through /vis/viewer commands:
# Rotate the view
/vis/viewer/set/viewpointThetaPhi 60 30 deg
/vis/viewer/zoom 1.2
# Reset view
/vis/viewer/resetYou can also control the field of view and the target point:
/vis/viewer/set/target 0 0 0 mm
/vis/viewer/set/fieldOfView 45 degVisualization attributes and models
To control how geometry and tracks appear, use:
/vis/scene/create
/vis/scene/add/volume
/vis/scene/add/axes 0 0 0 10 cmAttributes such as wireframe, color, and transparency are often set by presets:
/vis/viewer/set/style surface
/vis/viewer/set/lineSegmentsPerCircle 100Some 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:
/vis/scene/add/trajectories smooth
/vis/scene/endOfEventAction accumulate
/tracking/verbose 1Common commands to control track style include:
/vis/modeling/trajectories/create/drawByParticleID
/vis/modeling/trajectories/drawByParticleID-0/set gamma yellow
/vis/modeling/trajectories/drawByParticleID-0/set e- redTo draw hits and digits, you may use:
/vis/scene/add/hitsif 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:
/tracking/verbose 1
/stepping/verbose 1Typical 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:
/process/list
/process/verbose 1which print available processes and their configuration.
For geometry navigation debugging, you can use:
/geometry/test/run
/geometry/test/verbose 1in 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:
/analysis/setFileName output
/analysis/setFileType root
/analysis/openFile
/analysis/h1/set 0 "Edep in detector" 100 0 10 MeV
/analysis/h1/print 0
/analysis/closeFileThe actual commands depend on how the analysis is implemented, but often include:
/analysis/verbose 1
/analysis/listto manage analysis objects.
Applications often define their own analysis-related command directories, for example:
/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:
# init.mac
/control/verbose 2
/run/verbose 1
# Geometry and physics configuration
/detector/setMaterial G4_WATER
/physics/selectPhysics FTFP_BERT
/run/initialize# vis.mac
/vis/open OGL
/vis/drawVolume
/vis/scene/add/trajectories smooth
/vis/viewer/set/style surface# 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:
/control/manual
/control/manual /myapp/to discover additional, application-specific commands.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction to Geant4
- ☰ 1.1. What Is Geant4?
- ☰ 1.2. How Geant4 Works
- ☰ 1.3. Geant4 Simulation Structure
- ☰ 1.4. Geant4 and C++
-
- ☰ 2. Installing Geant4
- ☰ 2.1. Geant4 Requirements
- ☰ 2.2. Installing Geant4 on Linux
- ☰ 2.3. Installing Visualization Libraries
- ☰ 2.4. Verifying the Installation
- ☰ 2.5. Geant4 Example Applications
-
- ☰ 3. C++ Basics for Geant4
- ☰ 3.1. Classes and Objects
- ☰ 3.2. Inheritance
- ☰ 3.3. Pointers and References
- ☰ 3.4. Header and Source Files
- ☰ 3.5. Standard Library Containers
-
- ☰ 4. Creating Your First Geant4 Project
- ☰ 4.1. Project Structure
- ☰ 4.2. CMake Configuration
- ☰ 4.3. The Main Program
- ☰ 4.4. User Initialization Classes
- ☰ 4.5. Building and Running
-
- ☰ 5. Geant4 Units and Constants
- ☰ 5.1. Geant4 Unit System
- ☰ 5.2. Using Units in C++
- ☰ 5.3. Physical Constants
- ☰ 5.4. Printing Values with Units
-
- ☰ 6. Creating the Simulation World
- ☰ 6.1. DetectorConstruction
- ☰ 6.2. Solids
- ☰ 6.3. Logical Volumes
- ☰ 6.4. Physical Volumes
- ☰ 6.5. Creating the World Volume
-
- ☰ 7. Materials
- ☰ 7.1. Geant4 Materials
- ☰ 7.2. NIST Material Database
- ☰ 7.3. Common Materials
- ☰ 7.4. Creating Custom Materials
- ☰ 7.5. Detector Materials
-
- ☰ 8. Building Detector Geometry
- ☰ 8.1. Basic Geometrical Shapes
- ☰ 8.2. Boolean Solids
- ☰ 8.3. Positioning Volumes
- ☰ 8.4. Repeated Geometry
- ☰ 8.5. Detector Arrays
- ☰ 8.6. Geometry Overlap Checking
-
- ☰ 9. Geometry Visualization
- ☰ 9.1. Visualization in Geant4
- ☰ 9.2. Starting the Visualization System
- ☰ 9.3. Changing the View
- ☰ 9.4. Visualization Attributes
- ☰ 9.5. Displaying Particle Tracks
-
- ☰ 10. Primary Particle Generation
- ☰ 10.1. PrimaryGeneratorAction
- ☰ 10.2. Particle Gun
- ☰ 10.3. Particle Energy
- ☰ 10.4. Particle Position
- ☰ 10.5. Particle Direction
- ☰ 10.6. Common Particle Sources
-
- ☰ 11. General Particle Source
- ☰ 11.1. Introduction to GPS
- ☰ 11.2. Position Distributions
- ☰ 11.3. Angular Distributions
- ☰ 11.4. Energy Distributions
- ☰ 11.5. Configuring Sources with Macros
-
- ☰ 12. Physics Lists
- ☰ 12.1. What Is a Physics List?
- ☰ 12.2. Reference Physics Lists
- ☰ 12.3. Electromagnetic Physics
- ☰ 12.4. Gamma Interactions
- ☰ 12.5. Positron Physics
- ☰ 12.6. Hadronic Physics
- ☰ 12.7. Choosing a Physics List
-
- ☰ 13. Particle Tracking
- ☰ 13.1. Tracks
- ☰ 13.2. Steps
- ☰ 13.3. Energy Deposition
- ☰ 13.4. Track Status
- ☰ 13.5. Parent and Secondary Particles
-
- ☰ 14. User Actions
- ☰ 14.1. RunAction
- ☰ 14.2. EventAction
- ☰ 14.3. SteppingAction
- ☰ 14.4. TrackingAction
- ☰ 14.5. StackingAction
- ☰ 14.6. ActionInitialization
-
- ☰ 15. Sensitive Detectors
- ☰ 15.1. What Is a Sensitive Detector?
- ☰ 15.2. Creating a Sensitive Detector
- ☰ 15.3. Hits
- ☰ 15.4. Hit Collections
- ☰ 15.5. Assigning Sensitive Detectors
-
- ☰ 16. Recording Energy Deposition
- ☰ 16.1. Energy Deposition
- ☰ 16.2. Energy per Event
- ☰ 16.3. Energy per Detector
- ☰ 16.4. Energy Spectra
- ☰ 16.5. Detector Efficiency
-
- ☰ 17. Particle Position and Timing
- ☰ 17.1. Particle Position
- ☰ 17.2. Interaction Position
- ☰ 17.3. Global Time
- ☰ 17.4. Time of Flight
- ☰ 17.5. Detector Timing
-
- ☰ 18. Geant4 Analysis System
- ☰ 18.1. Introduction to G4AnalysisManager
- ☰ 18.2. Histograms
- ☰ 18.3. Ntuples
- ☰ 18.4. Filling Ntuples
- ☰ 18.5. Writing Output Files
- ☰ 18.6. Closing Analysis Files
-
- ☰ 19. Geant4 and ROOT
- ☰ 19.1. ROOT Output from Geant4
- ☰ 19.2. Reading Geant4 Output with ROOT
- ☰ 19.3. Plotting Energy Spectra
- ☰ 19.4. Event Analysis
- ☰ 19.5. Simulation-to-Analysis Workflow
-
- ☰ 20. Geant4 Macro Commands
- ☰ 20.1. Macro Files
- ☰ 20.2. Run Commands
- ☰ 20.3. Particle Source Commands
- ☰ 20.4. Visualization Commands
- ☰ 20.5. Controlling Simulations Without Recompiling
-
- ☰ 21. Random Numbers and Reproducibility
- ☰ 21.1. Monte Carlo Random Numbers
- ☰ 21.2. Setting Random Seeds
- ☰ 21.3. Running Independent Simulations
- ☰ 21.4. Reproducing an Event
-
- ☰ 22. Multithreading
- ☰ 22.1. Geant4 Multithreading
- ☰ 22.2. Running with Multiple Threads
- ☰ 22.3. Thread-Safe User Code
- ☰ 22.4. Analysis with Multithreading
- ☰ 22.5. Performance Considerations
-
- ☰ 23. Practical Example: Gamma-Ray Detector
- ☰ 23.1. Project Overview
- ☰ 23.2. Creating the World
- ☰ 23.3. Creating the Detector
- ☰ 23.4. Adding the Material
- ☰ 23.5. Creating a Gamma Source
- ☰ 23.6. Selecting Electromagnetic Physics
- ☰ 23.7. Recording Energy Deposition
- ☰ 23.8. Creating an Energy Spectrum
- ☰ 23.9. Simulating Detector Resolution
- ☰ 23.10. Analyzing the Spectrum with ROOT
-
- ☰ 24. Practical Example: Radiation Shielding
- ☰ 24.1. Project Overview
- ☰ 24.2. Creating the Source
- ☰ 24.3. Creating the Shield
- ☰ 24.4. Comparing Shielding Materials
- ☰ 24.5. Varying Shield Thickness
- ☰ 24.6. Recording Transmitted Particles
- ☰ 24.7. Calculating Transmission
- ☰ 24.8. Calculating Attenuation
- ☰ 24.9. Comparing Simulation Results
-
- ☰ 25. Practical Example: PET Scanner
- ☰ 25.1. Introduction to PET Simulation
- ☰ 25.2. Creating a PET Detector Ring
- ☰ 25.3. Creating Detector Crystals
- ☰ 25.4. Assigning Detector IDs
- ☰ 25.5. Creating a Positron Source
- ☰ 25.6. Simulating Positron Annihilation
- ☰ 25.7. Recording Detector Hits
- ☰ 25.8. Applying an Energy Window
- ☰ 25.9. Finding Coincidence Events
- ☰ 25.10. Recording Detector Positions
- ☰ 25.11. Creating Lines of Response
- ☰ 25.12. Saving PET Events to ROOT
- ☰ 25.13. Analyzing PET Data with ROOT
-
- ☰ 26. Practical Example: Proton Beam in Water
- ☰ 26.1. Project Overview
- ☰ 26.2. Creating the Water Phantom
- ☰ 26.3. Creating a Proton Beam
- ☰ 26.4. Selecting the Physics List
- ☰ 26.5. Recording Energy Deposition
- ☰ 26.6. Dividing the Phantom into Slices
- ☰ 26.7. Calculating Depth Dose
- ☰ 26.8. Observing the Bragg Peak
- ☰ 26.9. Plotting the Depth-Dose Curve
-
- ☰ 27. Detector Resolution and Smearing
- ☰ 27.1. Ideal vs Realistic Detector Response
- ☰ 27.2. Energy Resolution
- ☰ 27.3. Position Resolution
- ☰ 27.4. Time Resolution
- ☰ 27.5. Applying Detector Effects
- ☰ 27.6. Comparing Ideal and Smeared Results
-
- ☰ 28. Simulation Validation
- ☰ 28.1. Why Validate a Simulation?
- ☰ 28.2. Checking Geometry
- ☰ 28.3. Checking Energy Conservation
- ☰ 28.4. Comparing with Analytical Calculations
- ☰ 28.5. Comparing with Reference Data
- ☰ 28.6. Statistical Uncertainties
- ☰ 28.7. Number of Simulated Events
-
- ☰ 29. Improving Simulation Performance
- ☰ 29.1. Geometry Performance
- ☰ 29.2. Physics List Performance
- ☰ 29.3. Production Cuts
- ☰ 29.4. Reducing Unnecessary Output
- ☰ 29.5. Multithreading
- ☰ 29.6. Running Large Simulations
- ☰ 29.7. Parameter Scans
-
- ☰ 30. Debugging Geant4 Simulations
- ☰ 30.1. Compilation Errors
- ☰ 30.2. Geometry Errors
- ☰ 30.3. Overlapping Volumes
- ☰ 30.4. Missing Particles
- ☰ 30.5. Missing Energy Deposition
- ☰ 30.6. Physics List Problems
- ☰ 30.7. Sensitive Detector Problems
- ☰ 30.8. Empty Output Files
- ☰ 30.9. Segmentation Faults
- ☰ 30.10. Using Geant4 Verbose Output
-
- ☰ 31. Writing Better Geant4 Applications
- ☰ 31.1. Organizing Source Code
- ☰ 31.2. Separating Geometry and Analysis
- ☰ 31.3. Using Configuration Parameters
- ☰ 31.4. Avoiding Hard-Coded Values
- ☰ 31.5. Creating Reusable Detector Components
- ☰ 31.6. Naming Conventions
- ☰ 31.7. Documentation
- ☰ 31.8. Version Control with Git
-
- ☰ 32. Advanced Geometry
- ☰ 32.1. Parameterized Geometry
- ☰ 32.2. Replica Volumes
- ☰ 32.3. Nested Geometry
- ☰ 32.4. Complex Detector Arrays
- ☰ 32.5. Importing CAD Geometry
- ☰ 32.6. Exporting Geometry with GDML
-
- ☰ 33. Optical Photons
- ☰ 33.1. Introduction to Optical Physics
- ☰ 33.2. Optical Photons
- ☰ 33.3. Material Optical Properties
- ☰ 33.4. Scintillation Light
- ☰ 33.5. Optical Surfaces
- ☰ 33.6. Photodetectors
- ☰ 33.7. Counting Optical Photons
-
- ☰ 34. Medical Physics Applications
- ☰ 34.1. Geant4 in Medical Physics
- ☰ 34.2. Radiation Dose Simulation
- ☰ 34.3. PET Simulation
- ☰ 34.4. SPECT Simulation
- ☰ 34.5. Radiotherapy Simulation
- ☰ 34.6. Proton Therapy Simulation
- ☰ 34.7. Biological Tissue Materials
-
- ☰ 35. Final Project
- ☰ 35.1. Project Overview
- ☰ 35.2. Define the Simulation Goal
- ☰ 35.3. Create the Geometry
- ☰ 35.4. Define Materials
- ☰ 35.5. Configure the Particle Source
- ☰ 35.6. Select the Physics List
- ☰ 35.7. Implement Sensitive Detectors
- ☰ 35.8. Record Simulation Data
- ☰ 35.9. Run the Simulation
- ☰ 35.10. Analyze the Results with ROOT
- ☰ 35.11. Validate the Simulation
- ☰ 35.12. Create Scientific Figures
- ☰ 35.13. Document the Simulation
-
- ☰ 36. Appendices
- ☰ 36.1. Geant4 Class Cheat Sheet
- ☰ 36.2. Geant4 Units Cheat Sheet
- ☰ 36.3. Common Geant4 Macro Commands
- ☰ 36.4. Common Geometry Classes
- ☰ 36.5. Common Particle Definitions
- ☰ 36.6. Common Physics Lists
- ☰ 36.7. G4AnalysisManager Cheat Sheet
- ☰ 36.8. Common Visualization Commands
- ☰ 36.9. Common Geant4 Errors and Solutions
- ☰ 36.10. Recommended Geant4 Project Structure
- ☰ 36.11. Recommended Geant4 Simulation Workflow
-
Comments
Please login to add a comment.
Don't have an account? Register now!