KAHIBARO
11.5. Configuring Sources with Macros
Table of Contents
`/gps/particle`
The General Particle Source (GPS) is almost always controlled from macro files rather than hard‑coding its configuration in C++. For an absolute beginner, you can think of the GPS as a very flexible “software source” that you steer with commands. The most basic setting is the particle type, which you choose with the /gps/particle command.
The general form is:
/gps/particle <particle_name>
Here <particle_name> must be a valid Geant4 particle name, for example gamma, e-, e+, proton, neutron, ion, and many others. The GPS must know the particle type before you start the run. A typical sequence in a macro looks like this:
/gps/particle gamma
/gps/energy 1 MeV
/run/beamOn 1000This macro tells Geant4 to shoot 1000 gamma rays with 1 MeV energy. You can change the particle type in the same session before another run:
/gps/particle e-
/gps/energy 2 MeV
/run/beamOn 500So the same executable can simulate different sources by editing the macro file only, with no recompilation.
Some particles, especially ions, need more detailed specifications. For ions you first set the “particle” to ion, then use additional GPS commands (covered in more advanced material) to specify the atomic number, mass number, and charge. For standard particles you only need the single /gps/particle line.
You can use this command interactively in a Geant4 session or inside a .mac file that you run with:
/control/execute yourSource.mac
The key idea is that /gps/particle decouples the particle choice from your C++ code, so you can switch between different beams or sources quickly just by changing the macro.
Important rule: Always set /gps/particle before starting a run with /run/beamOn. Changing the particle after events have already started does not retroactively affect completed events.
`/gps/energy`
Once the particle type is selected, you must define its energy. For a simple monoenergetic source, GPS makes this very easy with the /gps/energy command.
The general form is:
/gps/energy <value> <unit>For example:
/gps/particle gamma
/gps/energy 511 keV
/run/beamOn 10000
Here <unit> can be any valid Geant4 energy unit, such as eV, keV, MeV, GeV. Under the hood the GPS converts this value to internal Geant4 units, so the choice of unit is purely for readability. You can change the energy between runs by simply editing the macro:
/gps/energy 100 keV
/run/beamOn 5000
/gps/energy 1 MeV
/run/beamOn 5000
This is a common pattern when you scan over energy to build spectra or to study energy dependence. In more advanced uses, GPS also supports energy distributions through commands like /gps/ene/type, but for a beginner the key idea is that /gps/energy sets a single fixed energy for all primary particles in that run.
A very common beginner mistake is to forget the unit:
/gps/energy 1This is technically valid, but the value is interpreted in internal units, not in MeV. Always write an explicit unit in your macros, even if you think the default is obvious.
You can combine energy settings with other GPS features, for example to define separate sources in the same session by using “source” indices, but the simplest case is a single source with a single /gps/energy value.
Important rule: Always specify the energy unit in /gps/energy. A line like /gps/energy 1 MeV is safe. A bare /gps/energy 1 can lead to completely wrong energies without any visible error.
`/gps/position`
The third essential part of configuring a GPS source with macros is the particle starting position. The simplest use of /gps/position is to define a point source at a fixed location.
The general form is:
/gps/position <x> <y> <z> <unit>
The coordinates <x> <y> <z> are given in the global coordinate system of your geometry. For example, to place a point source at the origin:
/gps/position 0 0 0 cmTo move it 10 cm along the positive z axis:
/gps/position 0 0 10 cmYou can change the source position between runs very easily:
/gps/position 0 0 -5 cm
/run/beamOn 1000
/gps/position 0 0 5 cm
/run/beamOn 1000This is very useful when you want to probe different detector locations or simulate scans without modifying C++ code.
GPS supports more advanced position distributions, such as plane or volume sources, which are controlled by additional commands like /gps/pos/type and /gps/pos/shape. Even when you use these, the concept of units and coordinates remains the same. For an absolute beginner, starting with a fixed point source is the easiest way to validate geometry and physics before moving on to more complex setups.
As with energy, forgetting the unit is a common mistake. Always include a length unit such as mm, cm, or m at the end of the /gps/position line.
A simple, complete GPS configuration in a macro file for a point-like monoenergetic source might look like:
/gps/particle gamma
/gps/energy 1 MeV
/gps/position 0 0 -10 cm
/gps/direction 0 0 1
/run/beamOn 10000
Here /gps/position and /gps/direction together define a beam along the positive z axis starting from z = −10 cm.
Important rule: /gps/position uses the global coordinate system. Make sure the chosen coordinates actually lie inside the world volume and in a sensible location relative to your detector, otherwise particles may start outside your geometry or in unintended regions.
Views: 9