Gsim Generators¶
Gsim creates the initial particles simulated in the event using ‘’generators’‘, which are enabled in the macro file. A generator decides how often a particular kind of event occurs, where it happens, and what kind of particles and energies the event starts with. Multiple generators can be used at once, and different events will be interleaved according to their rates, or even pile up if they occur in coincidence.
Generators are activated in the macro file using the command:
/generator/add gen_name generator_options
The first parameter, ‘’gen_name’‘, identifies the kind of event generator being added. For example, the ‘’combo’’ generators allows you to piece together separate vertex, position, and time generators. The second parameter, ‘’generator_options’’ is a string which is passed to the generator itself to configure it. For example:
/generator/add combo gun:point:poisson
adds a new combo generator to the simulation which will be comprised of a particle gun with events filling a detector volume and poisson-distributed random times.
Once a generator has been added, you can configure the vertex, position, and time components. For example, we can generate isotropic positrons in the center with 1 MeV of kinetic energy at a mean rate of 1 per second with the commands:
/generator/vtx/set 0 0 0 1.0
/generator/pos/set 0 0 0
/generator/rate/set 1.0
Top-level generators¶
Top-level generators are understood by the /generator/add command.
combo¶
/generator/add combo VERTEX:POSITION:TIME
or
/generator/add combo VERTEX:POSITION
Creates a new combo generator using the vertex, position, and time generators described below. If the variant without a TIME parameter is used, it implies the “poisson” time generator.
decaychain¶
/generator/add decaychain ISOTOPE:POSITION:TIME
or
/generator/add decaychain ISOTOPE:POSITION
Creates a new decaychain generator using the position, and time generators described below. If the variant without a TIME parameter is used, it implies the “poisson” time generator.
The ISOTOPE parameter can be any chain or element found in the file data/beta_decay.dat. The alpha, beta, and gamma particles emitted by the radioactive decay chain will be included in the event, with times and kinetic energies randomly generated according to the physics of the decay. In the current implementation, the times are set such the final decay occurs at t=0, so that earlier decays are at negative times.
Californium source¶
/generator/add cf 252:POSITION:TIME
or
/generator/add cf 252:POSITION
Creates a new Cf252 generator using the position, and time generators described below. If the variant without a TIME parameter is used, it implies the “poisson” time generator.
The syntax of the command may lead you to think that other isotopes of Cf252 (e.g., Cf255) are supported. One day that may happen, but right now only the value 252 can occur in the command, otherwise you’ll get an error message.
This generator models the products of the spontaneous fission of Cf252: neutrons and prompt photons. It does not model the radioactive decay of Cf252; neither does the ‘’decaychain’’ generator above (though that could be added by revising the data/beta_decay.dat file). Note: Geant4 models the fission of nuclei due to de-excitation from radioactive decays, and has its own implementation of radioactive decay chains, but it does not include a model for the spontaneous fission of nuclei; the only way to include that is by writing a separate event generator.
external¶
This top-level generator creates one or more particles with type, momentum, and optional time offset, spatial offset, and polarization, based on lines read from a text file. Synax:
/generator/add external VERTEX:TIME:INPUT
VERTEX is either ‘external’ or a vertex generator. If ‘external’ is specified, vertex positions in INPUT are used.
TIME is a time generator.
INPUT is either a file or a program which outputs text in the format described below(*). INPUT should be surrounded by quotes.
Examples:
/generator/add external external:poisson:"muons.dat"
Generates events listed in muons.dat using vertex locations specified in that file and times generated by the poisson time generator.
/generator/add external point:poisson:"/some/path/generateMuons 10 |"
/generator/pos/set 0 0 0
Calls the program /some/path/generateMuons and generates the events output by this program with position 0 0 0.
The format of the text input is:
NHEP
ISTHEP IDHEP JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP5 DT X Y Z PLX PLY PLZ
ISTHEP IDHEP JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP5 DT X Y Z PLX PLY PLZ
ISTHEP IDHEP JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP5 DT X Y Z PLX PLY PLZ
... [NHEP times]
NHEP
ISTHEP IDHEP JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP5 DT X Y Z PLX PLY PLZ
ISTHEP IDHEP JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP5 DT X Y Z PLX PLY PLZ
ISTHEP IDHEP JDAHEP1 JDAHEP2 PHEP1 PHEP2 PHEP3 PHEP5 DT X Y Z PLX PLY PLZ
... [NHEP times]
where:
ISTHEP == status code
IDHEP == HEP PDG code
JDAHEP == first daughter
JDAHEP == last daughter
PHEP1 == px in GeV
PHEP2 == py in GeV
PHEP3 == pz in GeV
PHEP5 == mass in GeV
DT == vertex _delta_ time, in ns (**)
X == x vertex in mm
Y == y vertex in mm
Z == z vertex in mm
PLX == x polarization
PLY == y polarization
PLZ == z polarization
PHEP5, DT, X, Y, Z, PLX, PLY, and PLZ are all optional. If omitted, the respective quantity is left unchanged. If DT is specified, the time offset of this and subsequent vertices is increased by DT: (**) note DT is a relative shift from the previous line. (This is because there is often a very large dynamic range of time offsets in certain types of events, e.g., in radioactive decay chains, and this convention allows such events to be represented using a reasonable number of significant digits.) If X, Y, Z, PLX, PLY, and/or PLZ is specified, then the values replace any previously specified.
vertexfile¶
The VertexFile generator is used to take event vertices generated by RAT or any other program (for example GENIE), and simulate them in RAT. Unlike the InROOT event producer which only runs RAT processors on fully simulated events, this generator starts from just the MCParticle and MCParent information and runs the full Geant4 simulation as well.
The syntax is
/generator/add vertexfile filename[:POSITION][:TIME][:NEVENTS][:NOFFSET]
where filename points to any RAT root file that at least has MC particle information. POSITION and TIME arguments can be used to override the position and time of vertices in the file by giving any position or time generator listed below instead. If they are set to ‘default’, the positions / times given in the root file will be used. It will simulate NEVENTS of the events in the file, starting with event NOFFSET. If NEVENTS is less than the total number of events to simulate set by /run/beamOn, the simulation will exit after NEVENTs.
Vertex generators¶
Vertex generators select the initial particle types, number, momenta, and polarization.
gun¶
/generator/vtx/set pname px py pz [ke] [polx poly polz]
Single particle gun. Creates a particle identified by pname with initial momentum (px, py, pz) given in MeV/c. The optional parameter ke sets the kinetic energy of the particle in MeV and overrides the magnitude of the momentum vector. (If you use ke, you can treat px, py, and pz as just a direction vector.) The optional polarization vector of the particle is given by (polx, poly, polz).
If px=py=pz=0, then the gun generates particles with isotropic initial directions. Similarly, if polx=poly=polz=0, or the polarization vector is left out, the particles will be randomly polarized.
Valid particle names include:
GenericIon, He3, alpha, anti_kaon0
anti_lambda, anti_neutron, anti_nu_e, anti_nu_mu
anti_omega-, anti_proton, anti_sigma+, anti_sigma-
anti_sigma0, anti_xi-, anti_xi0, chargedgeantino
deuteron, e+, e-, eta
eta_prime, gamma, geantino, kaon+
kaon-, kaon0, kaon0L, kaon0S
lambda, mu+, mu-, neutron
nu_e, nu_mu, omega-, opticalphoton
pi+, pi-, pi0, proton
sigma+, sigma-, sigma0, triton
xi-, xi0,
(This list comes from the /particle/list command.)
gun2¶
/generator/vtx/set pname px py pz angle E1 E2 [polx poly polz]
Modification of gun, the single particle gun. Creates a particle identified by pname (as above) with initial momentum (px, py, pz) given in arbitrary units for pointing. The angle parameter sets the opening angle of a ‘cone of fire’ such that angle = 90 fires particles evenly into the hemisphere along the [px,py,pz] direction. Setting angle to 0 gives the same behavior as gun.
E1 and E2 determine the range of particle kinetic energies in MeV. Setting E1 and E2 the same results in the same behavior as gun. If E2 != E1 the particle energy is randomly drawn from a flat distribution between E1 and E2.
The optional polarization vector of the particle is given by (polx, poly, polz).
If px=py=pz=0, then the gun generates particles with isotropic initial directions. Similarly, if polx=poly=polz=0, or the polarization vector is left out, the particles will be randomly polarized.
ibd¶
/generator/vtx/set dir_x dir_y dir_z
Inverse beta decay events caused by the interaction of a neutrino with a stationary proton. The event is initialized with the products of the reaction, a positron and a free neutron. The initial direction of the neutrino is along the (dir_x, dir_y, dir_z) vector. The neutrino energy is drawn from the spectrum given in the [wiki:RATDB_IBD IBD table], and the positron direction distribution is weighted by the differential cross section of the interaction.
reacibd ‘’‘
/generator/vtx/set dir_x dir_y dir_z
Inverse beta decay events caused by the interaction of a reactor neutrino with a stationary proton. The initial energy of the neutrino for each event is selected from a probability density function dependent on the total neutrino flux from a reactor and the inverse beta-decay cross-section. The initial direction of the neutrino is along the (dir_x, dir_y, dir_z) vector. The positron direction is currently randomized relative to the neutrino’s incident direction.
The relative isotopic abundances of U235, U238, Pu239, and Pu241 can be controlled using macro commands:
/generator/reacibd/U235 U235Amp #Default is 0.496
/generator/reacibd/U238 U238Amp #Default is 0.087
/generator/reacibd/Pu239 Pu239Amp #Default is 0.391
/generator/reacibd/Pu241 Pu241Amp #Default is 0.066
The abundances should be provided for all four isotopes and should add to 1. The addition of other isotopes and elements is currently not supported.
es¶
/generator/vtx/set dir_x dir_y dir_z
Elastic-scattering events caused by the interaction of a neutrino with an electron. The event is initialized with the product of the reaction, an electron. The initial direction of the neutrino is along the (dir_x, dir_y, dir_z) vector. The neutrino energy is drawn from the spectrum given in the [wiki:RATDB_IBD IBD table], and the electron direction distribution is weighted by the differential cross section of the interaction.
Note that the flux for elastic scattering is taken from the [wiki:RATDB_IBD IBD table] values; that is, it’s the same neutrinos that cause both types of events.
There are two parameters that control the elastic-scattering cross-section that can be controlled by macro commands:
/generator/es/wma sin_squared_theta
This command sets the value of sine-squared of the weak mixing angle; the default is 0.2277.
/generator/es/vmu neutrino_magnetic_moment
This command sets the value of the neutrino magnetic moment (units are Bohr magnetons); the default is 0.
pbomb¶
Generate a photon bomb, i.e. an isotropic distribution of photons, of a given number and wavelength.
Example:
/generator/vtx/set 1000 385
Produces events where each contains 1000 photons, each with a wavelength of 385 nanometers.
spectrum¶
Generates particles with isotropic momentum and kinetic energy drawn from a user-defined spectrum stored in a SPECTRUM table in RATDB. The spectrum is linearly interpolated between points, which do not have to be uniformly spaced.
Example:
/generator/vtx/set e- flat
Produces electron events drawn from the spectrum stored in the SPECTRUM[flat] table:
{
name: "SPECTRUM",
index: "flat",
valid_begin: [0, 0],
valid_end: [0, 0],
// default spectrum is flat
spec_e: [ 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00], // (MeV)
// (Note that first point is minimum of spectrum, last is maximum)
spec_mag: [ 1.00, 1.00, 1.00, 1.00, 1.00, 1.00, 1.00, 1.00, 1.00], // don't worry about normalisation
}
Position generators¶
Position generators select points in space for the initial particles.
fill¶
/generator/pos/set x y z
Events uniformly fill a physical volume containing the point (x, y, z) (mm).
regexfill¶
/generator/pos/set volume_pattern
Events uniformly fill all physical volumes with names matching the POSIX regular expression (regex) given as volume_pattern.
In general volume names correspond to the index of GEO table entries, but complex geometry factories may generate other volumes as sub components, many volumes for arrays, or both.
For a concrete example, this can be used to generate events in the wall (glass) of all PMTs built with a pmtarray type geometry factory.
If the index of the GEO table for the pmtarray was inner_pmts the PMTID number of the physical PMT would be appended to the volume name as it is created, so an appropriate regex would be inner_pmts[0-9]+
/generator/pos/set inner_pmts[0-9]+
Note that the volume name is considered a match if the regex matches any part of the volume name, e.g. the regex mts1 would match the volume name inner_pmts100.
This can be avoided by using start ^ and end $ of line characters when specifying a unique ^volume$ by name.
fillshell¶
/generator/pos/set X Y Z Ri Ro volname
Events uniformly fill a shell centered at (X, Y, Z) (mm) with inner radius Ri and outer radius and are contained only in the volume named “volname.”
Note that the old syntax (old as of r1188) still works, for backwards compatibility. The old syntax is:
/generator/pos/set Vx Vy Vz X Y Z Ro Ri
where points are contained only within the same volume as the point (Vx, Vy, Vz).
paint¶
/generator/pos/set x y z
Events a distributed uniformly over the surface of the logical volume containing the point (x, y, z) (mm).
multipoint¶
/generator/pos/set number_of_locations inner_radius outer_radius
Generates events at different locations in the detector between two radii. For a given value of number_of_locations, the points are unique and fixed for all runs on all platforms. The generator will cycle between the different points as the event number increments, so the number of events you generate in each job should be a multiple of number_of_locations. This generator is typically used to benchmark reconstruction, as you can fit events at each generated location to compute a bias and resolution.