KAHIBARO
20.1. Macro Files
Table of Contents
`.mac` files
Geant4 macro files are plain text files that contain a sequence of Geant4 UI commands, exactly the same commands you would type interactively in a Geant4 session. Their filename usually ends with .mac, but the extension is only a convention and not technically required by Geant4. Using macros lets you control and repeat simulations without recompiling your C++ code.
Inside a .mac file, each line is either a command or a comment. Commands always start with a slash character, such as /run/initialize or /gps/energy 1 MeV. Comments begin with the # character. Everything after # on a line is ignored by Geant4, so you can document what each part of the macro does. Empty lines are allowed and simply skipped.
Geant4 processes macro files line by line, from top to bottom. Commands are executed in the order they appear. This means that some commands must appear before others. For example, geometry and physics must be fully defined and initialized before you start a run, and source configuration must be complete before /run/beamOn.
Important rule: A macro file is just a sequence of UI commands, executed in order, as if you had typed them interactively. There is no C++ code inside a .mac file, only commands understood by the Geant4 UI.
You can create macros with any text editor. For beginners it is useful to keep macros short and focused on a single purpose. For example, you might have one macro that sets up visualization, another that configures and starts a run, and a third that scans over a parameter. Later, you can nest macros by having one macro call another using /control/execute.
A typical simple macro might first initialize the run manager, then configure the primary particle source, set up visualization commands, and finally start a run. The exact commands belong to other chapters, but here it is important to understand that the macro is only a script that collects them in one place and makes them easy to repeat. If you edit the macro, you change the behavior of your simulation without changing or recompiling the C++ source code.
Macro files are especially useful for beginners because they separate two tasks. Your C++ code defines the structure and capabilities of the simulation. Your macro files define how to use that simulation in a particular run, for example which particle you shoot, with what energy, how many events to simulate, and which visualizations to show.
Running macros
To run a macro, you must first start your Geant4 application, usually the executable you built from your project. Once the application is running and the Geant4 UI is active, you can ask Geant4 to read and execute a macro file with the /control/execute command followed by the macro filename.
If you start in an interactive session with a GUI or terminal UI, you can type a command like
/control/execute init.mac
on the Geant4 command line. Geant4 then opens init.mac, reads each line, and executes the commands in sequence. If a command is invalid or appears at the wrong time, the UI will print an error message and usually skip that command, then continue with the next line.
You can also give a macro file to your application directly on the operating system command line. The typical pattern is
./myApp init.mac
for an executable named myApp. In this case, Geant4 automatically runs the specified macro as soon as the application starts, without waiting for additional user input. This is convenient for batch runs or automated scripts. Many Geant4 example applications use this pattern, often providing a default macro that initializes geometry and physics, then runs a small number of events.
Important rule: Use /control/execute filename.mac to run a macro from inside Geant4, or pass the macro name as a command line argument to run it automatically at startup.
When a macro is running, Geant4 usually does not accept further interactive commands until it finishes that macro. However, a macro itself can execute other macros using /control/execute other.mac. This allows you to build layered configurations, where a top level macro calls general setup macros and then run specific macros. For example, you might have a global initialization macro that sets physics and geometry, and then many small run macros that change only the source energy or geometry parameters.
If Geant4 cannot find the macro file, you will see an error message indicating that the file could not be opened. In that case, check the working directory from which you launched the executable and the path or name you gave to /control/execute. It is often useful to keep all your macros in a dedicated directory and use relative paths like macros/run1.mac.
By combining .mac files with the /control/execute command and command line arguments, you can control almost every aspect of your simulation from the outside. This approach will let you reuse the same compiled application for many different studies, and you will only need to edit and rerun macro files when you change parameters or sequences of commands.
Views: 9