Detailed Description

The main class to store the Geant4 simulation conditions that will be used by restG4.

TRestGeant4Metadata is the main class used to interface with restG4 (a REST based Geant4 code distributed with REST) used to launch Geant4 based simulations, and store later on the simulation conditions as metadata information inside the output generated file. The simulations produced by restG4 will write to disk the event data generated as a TRestGeant4Event type. The tutorials page includes a tutorial describing on detail how to launch a restG4 simulation and retrieve basic simulation results.

There are few helper classes that aid to organize and access the information that TRestGeant4Metadata contains, TRestGeant4Particle, TRestGeant4BiasingVolume, TRestGeant4ParticleSource.

After installation of restG4, some basic working examples can be found at $REST_PATH/examples/. We use this class to store restG4 rml parameters like particle type, energy, direction, gdml definition, etc. In addition, we have a class TRestGeant4PhysicsLists in parallel to define the necessary physics processes, EM, hadronic, etc, that will be active in our Geant4 simulation.

In general terms, an RML file to be used with restG4 must define the following sections, and structures.

// We must, as usual, define the location where the REST output files will
// be stored
<globals>
   <parameter name="mainDataPath" value="${REST_DATAPATH}" />
   <searchPath value="/path/to/geometry" />
</globals>
 
// A TRestRun section to define few run parameters with a general run
// description.
<TRestRun>
    ...
</TRestRun>
 
//A TRestGeant4Metadata section defining few parameters, generator, and detector.
<TRestGeant4Metadata>
    ...
</TRestGeant4Metadata>
 
//A TRestGeant4PhysicsLists section def-inning the physics processes active.
<TRestGeant4PhysicsLists>
    ...
</TRestGeant4PhysicsLists>

Note: Wherever 3 dots (...) are provided means a redundant code format, or that additional fields might be required.; The runTag inside the TRestRun class will be overwritten by the name of TRestGeant4Metadata section defined in the RML.

This page describes in detail the different parameters, particle generator types, detector, and other features implemented in restG4, that can be defined inside the section TRestGeant4Metadata. The description of other required sections, as TRestRun or TRestGeant4PhysicsLists, will be found in their respective class documentation.

We can sub-divide the information provided through TRestGeant4Metadata in different parts,

the main parameters related to the simulation conditions, such as number of events to be simulated, random seed, or GDML geometry definitions file,
the definition of the primary particle generator, using the <generator> section, to define which particles will be generated, from where they will be generated, and which energies and direction distributions they will follow,
the definition of what event hits will be written to disk, using the <detector> section,
and the (optional) definition of biasing volumes to simulate particle transmission through extended detector shieldings, using the <biasing> section.

1. Basic simulation parameters

The following list presents the common parameters that must be defined inside TRestGeant4Metadata section to define few simulation conditions in restG4, as important as the detector geometry, or the number of events to be simulated.

nEvents: The number of primary particles to be generated. The number of registered events might differ from nEvents due to detector definitions. The number of events registered could be even larger than the number of primaries, as for example when launching full decay chain simulations, where different isotope decays are stored in different events.
gdmlFile: The path and name of the main GDML file. Both relative and absolute path is supported. In principle, the user has full freedom to create any detector setup geometry using a GDML description.

Warning: The only requirement is that the gas logical volume (implemented in a single physical volume on the geometry) must be named gasVolume.

subEventTimeDelay: This parameter defines the event time window. If a Geant4 energy deposit takes place after this time, those hits will be registered as a fully independent event. Therefore, the total number of registered events could be higher than the initial number of events.
saveAllEvents: If enabled, this parameter will mark all the volumes of the geometry as active, and it will ignore the energy range definition in the detector section. Any Geant4 simulated track from any event or subevent will be registered even if no energy deposition have been produced. In future, this parameter would be better implemented inside <detector definition.
printProgress: if enabled, a message showing the progress of the simulation will be printed periodically. This option is enabled by default.

The following example illustrates the definition of the common simulation parameters.

<parameter name="nEvents" value="100" />
<parameter name="gdmlFile" value="/path/to/mySetupTemplate.gdml"/>
<parameter name="maxTargetStepSize" value="200" units="um" />
<parameter name="subEventTimeDelay" value="100" units="us" />

2. The primary particle generator section

The generator section describes from where we will launch our primary particles, which particles we will launch, the energy of these particles, their angular distribution and other required functions needed to cover different physics cases.

The complete structure of the primary particle generator follows this scheme.

<generator type="generatorType" ... >
 
    <source use="geant4" particle="particleName" ... >
        <angular type="angularDistribution" />
        <energy type="energyDistribution" energy="energyValues" units="MeV" />
    </source>
 
    <source particle="particleName" ... >
        ...
    </source>
 
    // Add any number of sources.
 
</generator>

The generator type definition

The different generator types determine the spatial origin of the primaries that will be generated.

We can define any number of primary particles (sources) that will be used to construct an initial event. All primary particles that build an event will have a common position(*). The spatial origin of these sources, or primaries, is specified in the definition of the generator. We have 4 major types of generator, namely:

custom: Uses positions specified in the generator file of the particle source. (NOT IMPLEMENTED)
volume: Launch the events from random positions inside a volume of certain shape.
surface: Launch the events from random positions upon the surface of certain shape.
point: Launch the events from a single point of given position.
// We launch particles at a fix position at the XY origin and z=-15cm

<generator type="point" position="(0,0,-150)" units="mm" >

Together with the generator type, we need to define the shape, size and position. Both size and position are in TVector3 form. The following shapes are supported:

gdml: Bound the generator to a certain gdml component. No need to define size and position. Needs another "from" parameter. If the "from" parameter is defined, we can omit shape="gdml" parameter.
// We launch particles from random positions inside the vessel volume defined in our GDML geometry

<generator type="volume" from="vessel" > ... </generator>
box: Bound the generator to a virtual box area. "position" defines the center of the box, while the three elements of "size" defines respectively x, y, z length of the box.
<generator type="volume" shape="box" size="(10,20,20)" position="(0,0,5)" > ... </generator>
cosmic: This is a special type of generator that is used to simulate cosmic particles. It takes no parameters. It uses the world size to produce an homogeneous cosmic ray flux (according to energy and angular distribution, which can be correlated) in the whole world volume. It is recommended to use this instead of other approaches such as an infinite plane above as this generator will be significantly more efficient since all particles are directed roughly towards the detector. To retrieve the surface term for computing the equivalent surface area (to use for equivalent simulation time calculation etc.), use the helper method TRestGeant4PrimaryGeneratorInfo::GetSpatialGeneratorCosmicSurfaceTermCm2(), which can be called (from this class) via GetGeant4PrimaryGeneratorInfo().GetSpatialGeneratorCosmicSurfaceTermCm2(). A working example can be found in the restG4/examples/12.Generators directory
<generator type="cosmic"> ... </generator>
cylinder: Bound the generator to a virtual cylinder area. "position" defines the center of the cylinder, while the three elements of "size" defines respectively radius, length, nothing of the cylinder.
sphere: Bound the generator to a virtual sphere area. "position" defines the center of the sphere, while the three elements of "size" defines respectively radius, nothing, nothing of the sphere. In future we may implement ellipsoid support for the sphere and uses all three elements.
circle: Bound the generator to a virtual circle area. "position" defines the center of the circle, while the three elements of "size" defines respectively radius, nothing, nothing of the circle. "circle" shape works only for "surface" generator type. The initial direction of the circle is in parallel to x-y plane.
// We launch particles from random positions on a virtual circle

<generator type="surface" shape="circle" size="(10,0,0)" position="(0,0,0)" > ... </generator>
wall: Bound the generator to a virtual rectangle area. "position" defines the center of the rectangle, while the three elements of "size" defines respectively x, y, nothing length the rectangle. "rectangle" shape works only for "surface" generator type. The initial direction of the rectangle is in parallel to x-y plane.
source: The positions of the particles will be defined by the particle source generator, see for example TRestGeant4ParticleSourceCry.

Rotation of the virtual body defined previously is also supported. We need to define parameter "rotationAxis" and "rotationAngle" to do this job. The TVector3 parameter "rotationAxis" is a virtual axis passing through the center of the virtual body, with its three elements representing its direction. "rotationAngle" defines the rotation angle in the view of the axis direction. It is in radian unit.

// We launch particles from random positions on a virtual wall leaned to 45 deg
<generator type="surface" shape="wall" size="(10,10,0)" position="(0,0,0)"
rotationAxis="(1,0,0)" rotationAngle="0.78539816" > ... </generator>

By default all the primaries will be launched homogeneously from the volume or the surface. We can define additional density function to customize the particle origin distribution. The function is a TF3 function with x, y, z the absolute position(position of gdml frame instead of generator frame) of the particle in unit mm. The returned value should be in range 0-1, indicating the relative probability in this position. For example, we simulate some radio isotopes placed on a chip with doping which follows exponential density distribution near the surface:

<generator type="volume" shape="box" size="(10,10,1)mm" position="(0,0,0.5)"

densityFunc="exp(-z/0.01)" > ... </generator>

The source definition

Three type of source definitions can be used to generate primary particles in our simulation. The different types are introduced through the parameter use.

A pre-generated decay0 file,
// 1. generator file

<source use="Xe136bb0n.dat" />
the geant4lib encoded generators, such as decay0 or cry generators
// 2. decay0 package

<source use="decay0" particle="Xe136" decayMode="0vbb" daughterLevel="3" />
and the traditional geant4 particle description integrated in REST.
// 3. geant4 internal

<source use="geant4" particle="Na22" excitedLevel="0.0" fullChain="on">

<angular type="isotropic" />

<energy type="mono" energy="0.0" units="MeV" />

</source>

For the third case, which is the default if use field is not defined, we can define any pre-defined particle name existing in Geant4 in the particle field, as leptons or ions. Additionally, we can define any radioactive isotope by using the element name symbol and the number of nucleons (i.e. Rn222, Co60, U238 ). For the radioactive decays we can also define an additional field fullchain="on/off". This parameter specifies if we want to simulate the full radiative chain or a single decay to the next de-excited isotope.

In summary we can use the following options inside the source definition:

particle="G4_Particle": A particle name understood by Geant4 (i.e. e-, e+, gamma, etc).
// We launch gammas

<source particle="gamma">
particle="Xn" fullchain="off": A radioactive isotope. Where X is the element name and n the number of nucleons (I.e. Rn222, Xe137, Co60, etc).
// We launch a single chain Rn222 decay

<source particle="Rn222" fullChain="off" >

Note: For ions, we can also define its electric charge (signed integer) and excited level value in eV, by using the additional fields excitedLevel and charge.

fromFile="Xe136bb0n.dat": The particles, energies, and direction are fully described by an input file. <energyDistribution> and <angularDistribution> source specifiers have no effect here. Everything will be defined through the generator file. The file Xe136bb0n.dat is a pre-generated Decay0 file that can be found at REST_PATH/data/generator, together with other generator examples.
// We launch pre-generated 136Xe NLDBD events

<source fromFile="Xe136bb0n.dat">

// The energy and angular

// definitions here will be just

// ignored with this type of source

</source>

The source energy distribution

A source, or particle, associated kinetic energy is defined by using.

There are different energy distribution types we can use to define the energy of the primary particles. Depending on the type of energy distribution we will be required to add additional parameters. The types we can use in REST are the following types.

mono: All the particles from this source will be launched with the same energy for each simulated event. It requires to define the parameter energy="E", where E is the kinetic energy of the particle in keV.
// A mono energetic particle with 10keV.

<energy type="mono" energy="10" units="keV" />
flat: All the particles from this source will be launched in a specified energy range using a uniform energy distribution. It requires to define the parameter range="(Ei,Ef)", where Ei is the minimum energy and Ef is the maximum energy (in keV).
// A random uniform generation between 1 and 10 keV

<energy type="flat" range="(1,10)" units="keV" />
log: All the particles from this source will be launched in a specified energy range using a logarithmic energy distribution. It requires to define the parameter range="(Ei,Ef)", where Ei is the minimum energy and Ef is the maximum energy (in keV). Ei needs to be > 0.
// A random logarithmic generation between 1 and 10 keV

<energy type="log" range="(1,10)" units="keV" />
TH1D: It will use a TH1D histogram from a ROOT file with a user defined spectrum. It requires to define the parameters file="mySpectrum.root" name="histName" and range="(Ei,Ef)". The ROOT file should contain a TH1D histogram with name histName. Only the region of the spectrum inside the range Ei-Ef will be considered. If range is not specified inside the RML, the full TH1D range definition will be used. The energy units of the spectrum must be specified in the x-axis label of the TH1D object. If no units are given in the x-label, the default units considered will be keV.
// A TH1D input spectrum to produce underground muons in the range

// between 150 and 400 GeV

<energy type="TH1D" file="Muons.root" name="LSCMuon"

range="(150,400)" units="GeV" />
Formula: It will use one of the predefined formulas to generate the primaries. The available formulas are: "CosmicNeutrons". A range parameter can be specified to limit the energy range of the generated primaries. It will not go over or under the predefined range for the formula range=(100,200)MeV. A parameter nPoints can be defined to set the random sampling of the formula. The default value should be enough for most cases. Increasing this value (max is 10000) will cause an increase to the initialization time but will not cause an increase in time for primary generation so in a long simulation its recommended to increase this value.
<energy type="Formula" name="CosmicNeutrons" range="(10,100)MeV" nPoints=1000 />
Formula2: It will use one of the predefined formulas to generate the primaries with correlated energy and angular distribution (ROOT TF2). The available formulas are: "CosmicMuons". Since the energy and angular distributions are correlated its necessary to use formula2 in both energy and angular distributions. name parameter only needs to be defined in either of the distributions, as one cannot use different formula2 for energy and angular distributions. The rest of the parameters (range, nPoints) are the same as in formula.
<energy type="formula2" name="CosmicMuons" range="(0,10)GeV" nPoints="1000"/>

<angular type="formula2" direction="(0,-1,0)" nPoints="200"/>

The source angular distribution

The momentum direction of a particle is specified by using.

We can use different types of angular distributions to define the initial direction of the particle. We can choose between the following types inside REST.

flux: It defines a fixed direction for the particle momentum. We must specify the additional parameter direction="(pX,pY,pZ)" as the cartesian components of the momentum direction (not required to be normalized).
// Particles will be launched in the positive y-axis direction.

<angular type="flux" direction="(0,1,0)" />
isotropic: The momentum direction of each particle will be generated homogeneously. In case of virtualSphere and virtualBox only the particles travelling towards the inside of the virtual volume will be considered.
// Particles will be launched without preferred direction.

<angular type="isotropic" />
backtoback: The source momentum direction will be opposite to the direction of the previous source. If it is the first source the angular distribution type will be re-defined to isotropic.
// Particles will be launched without preferred direction.

<angular type="backtoback" />
TH1D: It will use a TH1D histogram from a ROOT file with a user defined angular distribution. It requires to define the additional parameters as file="mySpectrum.root" and name="histName". The file we give should be stored in "data/distributions/" and contain a TH1D histogram with name "histName".
// A TH1D input angular distribution used for cosmic rays

<angular type="TH1D" file="CosmicAngles.root" name="Theta2" />
Formula: It will use one of the predefined formulas to generate the primaries. The available formulas are: "Cos2", "Cos3". A range parameter can be specified to limit the zenith angular range of the generated primaries. It will not go over or under the predefined range for the formula range=(10,45)deg. A parameter nPoints can be defined to set the random sampling of the formula. The default value should be enough for most cases. Increasing this value (max is 10000) will cause an increase to the initialization time but will not cause an increase in time for primary generation so in a long simulation its recommended to increase this value.
<angular type="Formula" name="Cos2" direction="(0,-1,0)" nPoints="500" range="(10,70)deg" />
Formula2: It will use one of the predefined formulas to generate the primaries with correlated energy and angular distribution (ROOT TF2). The available formulas are: "CosmicMuons". Since the energy and angular distributions are correlated its necessary to use formula2 in both energy and angular distributions. name parameter only needs to be defined in either of the distributions, as one cannot use different formula2 for energy and angular distributions. The rest of the parameters (range, nPoints) are the same as in formula.
<energy type="formula2" name="CosmicMuons" range="(0,10)GeV" nPoints="1000"/>

<angular type="formula2" direction="(0,-1,0)" nPoints="200"/>

3. The detector section definition

The information we store in the ROOT file can be defined using the detector section. The detector section is defined as follows

<detector>
   <parameter name="energyRange" value="(0,5)" units="MeV" />
    <volume name="gas" sensitive="true" chance="1" />
    <volume name="shielding" chance="1" />
    // Add as many active volumes as needed
</detector>

The detector section defines the sensitive volumes, and the active volumes where data will be stored.

The sensitive, or active, volumes can be any physical volume defined on the GDML geometry. If an event did not produce an energy deposit in the sensitiveVolume, the event will not be stored at all. Therefore, the sensitive volume will serve as a trigger volume to decide when an event should be stored. For the moment we can only define a single sensitive volume, but it might be desirable to introduce boolean operations with different geometry volumes.

We can define the energy range we are interested in by defining the parameter energyRange. The event will be written to disk only if the total energy deposited in all the active volumes of the detector is in the Ei-Ef range.

This energy range implies that only events that produced an energy deposit at the sensitive volume, and produced a total energy deposit between Ei and Ef, integrated to all the active volumes, will be stored.

We should define inside the <detector> definition all the physical volumes where we want hits to be stored using <volume> definition.

maxTargetStepSize: This is the maximum integration step size allowed to Geant4 when approximating the interaction of particles in a medium. Lower values will provide a more accurate description of the particle tracks, but will also require an additional computation time.
Note
The parameter maxTargetStepSize has only effect on the target volume, that is the physical volume corresponding to the logical volume named gasVolume in the geometry.
In general, we will always want to store all the hits in the gas volume of the TPC. But the gas being the sensitive volume does not mean that hits on the gas volume will be stored. This volume should be activated for storage even if we defined it as the sensitive volume. The user may decide to do not store the hits in the gas volume. For example, we may want to track events that deposit something on the gas volume, through the hits in another volume, but not be interested to study the hits inside the gas for a particular case.

Each active volume defines a chance parameter. This parameter gives the probability to store the hits of an event in a particular volume. For example,

will store all the hits produced in the gas, and 10% of the events will include information of the hits in the vessel. This may be used as a control volume to allow further study of events depositing energy in the vessel, but saving some space in disk in case we do not need to use all the event population.

Note: If we do not specify any volume, then all volumes found in the GDML geometry will be marked as active volumes. If the chance parameter is not given, the chance will be 1 by default.

On top of that, each volume may define a user limit on the maximum step size of particles in that particular volume specifying the maxStepSize parameter.

Smaller values will provide a higher amount of detail, but it will require additional computational time and storage.

Note: If maxStepSize is not defined, the default value will be 0, and user limits will not be applied for that particular active volume.

We are still allowed to define a default step size for all the active volumes, using:

The option removeUnwantedTracks can optionally be enabled inside detector section:

This option will remove all tracks that do not deposit energy in any of the sensitive volumes or in any of the volumes marked as 'keepTracks' (for instance <volume name="veto" keepTracks="true" >).

By default tracks are removed if they do not deposit energy in these volumes but the parameter 'keepZeroEnergyTracks' can be set to true so that all processes are registered, for example a neutron capture taking place in one of the volumes which does not result in energy deposition.

The kill="true" option can be used in the volume definition (<volume name="shield" kill="true" >) to stop a track after entering the volume. The track will be immediately killed and its energy deposition won't be computed. This is useful to speed up certain kinds of simulations.

4. The biasing volumes section (optional)

The REST Geant4 toolkit (restG4) implements a particular biasing technique to simulate external radiation contributions in extensive shieldings. The technique consists in spatially placing biasing volumes between the initial particle generator and the detector (or sensitive volume).

The largest biasing volume must be fully contained inside the original event generator. And the smaller biasing volume should fully contain all the volumes where hits will be stored. The different biasing volumes must be fully contained one in each other (in other words, the biasing volumes should not overlap).

In practice, restG4 will run a total of N+1 Geant4 simulations, being N the number of biasing volumes defined. The first simulation will just count the number of particles of the specified type traversing the biasing volume, registering also their energy and angular distribution. In the second simulation, the number of particles that traversed the biasing volume will be multiplied by a factor, that is defined independently at each biasing volume, using the recorded energy spectrum from the previous simulation. This will continue until the last smaller biasing volume is reached. Only in the last simulation, when events are launched from the smaller biasing volume, hits will be stored.

This biasing technique has been already tested using a virtualBox generator and virtualBox biasing volumes, leading to compatible results if compared to non biased simulations. When using this technique it is recommended that you first do a small scale version of your simulation to compare biased and non-biased results. If both results (from biased and non-biased) agree then you will be more confident you will not obtain misleading results.

In order to obtain the best results using this technique you should try to keep the same number of events reaching each biasing volume. First, some optimization is required. You will need to empirically test the number of events reaching each biasing volume, and adjust the factors according to these results. In order to have reasonable good results you should assure to have at least 10,000 events reaching each of the biasing volumes. If some energies are very unlikely, and not enough statistics exist at the biasing volume the error will be much higher. This should be solved in a future implementation by using weighting factors.

The biasing technique needs to be activated using the following scheme

<biasing value="on" type="virtualBox,virtualSphere" >
 
    <biasingVolume particle="particleName" size="L" position="(X,Y,Z)"
    factor="F" energyRange="(Ei,Ef)" />
    // Add as many biasing volumes as desired
 
</biasing>

Note: The biasing is optional, and only required in exceptional circumstances, most of the times will be disabled by using value="off".

We can use two spatial generators to define the biasing volumes (virtualBox and virtualSphere). It is recommended to use the same type as the original generator. But it is left to the user to make his choice.

Warning: The volumes should be placed in increasing order. From smaller to larger volume.

A biasing volume is defined as follows

<biasingVolume particle="particleName" size="L" position="(X,Y,Z)"

factor="F" energyRange="(Ei,Ef)" />

The particle name may be any particle name defined in Geant4. The biasing particle we define is the only particle that will be transferred to the next biasing volume. Therefore, this biasing method is used to study the transmission of a given particle gamma, neutron, etc through a shielding). The size defines the side of the virtualBox or the radius of the virtualSphere, its position X, Y, Z and a factor F that is the multiplication factor to be used in the next run (In other words, the number of particles launched from a biasing volume will be the number of particles that reached the volume times F). Only the particles in the specified energyRange (Ei,Ef) will be considered in the transmission to the next biasing volume.

RESTsoft - Software for Rare Event Searches with TPCs

History of developments:

2015-July: First concept and implementation of TRestG4 classes.

Author: Javier Galan

Definition at line 47 of file TRestGeant4Metadata.h.

#include <TRestGeant4Metadata.h>

Inheritance diagram for TRestGeant4Metadata:

Public Member Functions
void	AddParticleSource (TRestGeant4ParticleSource *src)
	Adds a new particle source.

	ClassDefOverride (TRestGeant4Metadata, 15)

Int_t	GetActiveVolumeID (const TString &name)
	Returns the id of an active volume giving as parameter its name.

TString	GetActiveVolumeName (Int_t n) const
	Returns a std::string with the name of the active volume with index n.

std::vector< TString >	GetActiveVolumes () const

TRestGeant4BiasingVolume	GetBiasingVolume (int n)
	Return the biasing volume with index n.

Double_t	GetCosmicFluxInCountsPerCm2PerSecond () const
	Reads the biasing section defined inside TRestGeant4Metadata. More...

Double_t	GetCosmicIntensityInCountsPerSecond () const

Double_t	GetEquivalentSimulatedTime () const

TString	GetGdmlFilename () const
	Returns the main filename of the GDML geometry.

TString	GetGdmlReference () const
	Returns the reference provided at the GDML file header.

const TRestGeant4GeometryInfo &	GetGeant4GeometryInfo () const
	Returns an immutable reference to the geometry info.

const TRestGeant4PhysicsInfo &	GetGeant4PhysicsInfo () const
	Returns an immutable reference to the physics info.

const TRestGeant4PrimaryGeneratorInfo &	GetGeant4PrimaryGeneratorInfo () const
	Returns an immutable reference to the primary generator info.

TString	GetGeant4Version () const
	Returns a std::string with the version of Geant4 used on the event data simulation.

size_t	GetGeant4VersionMajor () const

TString	GetGeometryPath () const
	Returns the local path to the GDML geometry.

std::vector< std::string >	GetKillVolumes () const

TVector3	GetMagneticField () const
	Returns the world magnetic field in Tesla.

TString	GetMaterialsReference () const
	Returns the reference provided at the materials file header.

Double_t	GetMaximumEnergyStored () const
	Returns the maximum event energy required for an event to be stored.

Double_t	GetMaxStepSize (const TString &volume)
	Returns the maximum step at a particular active volume.

Double_t	GetMaxTargetStepSize () const
	Returns the value of the maximum Geant4 step size in mm for the target volume.

Double_t	GetMinimumEnergyStored () const
	Returns the minimum event energy required for an event to be stored.

unsigned int	GetNumberOfActiveVolumes () const
	Returns the number of active volumes, or geometry volumes that have been selected for data storage.

size_t	GetNumberOfBiasingVolumes () const
	Returns the number of biasing volumes defined.

Long64_t	GetNumberOfEvents () const
	Returns the number of events to be simulated.

Long64_t	GetNumberOfRequestedEntries () const

size_t	GetNumberOfSensitiveVolumes () const

Int_t	GetNumberOfSources () const
	Returns the number of primary event sources defined in the generator.

TRestGeant4ParticleSource *	GetParticleSource (size_t n=0) const
	Returns the name of the particle source with index n (Geant4 based names).

bool	GetRemoveUnwantedTracks () const

bool	GetRemoveUnwantedTracksKeepZeroEnergyTracks () const

std::vector< std::string >	GetRemoveUnwantedTracksVolumesToKeep () const

Bool_t	GetSaveAllEvents () const
	It returns true if save all events is active.

Long_t	GetSeed () const
	// Used for faster lookup More...

TString	GetSensitiveVolume (int n=0) const
	Returns a std::string with the name of the sensitive volume.

const std::vector< TString > &	GetSensitiveVolumes () const

Int_t	GetSimulationMaxTimeSeconds () const

Long64_t	GetSimulationTime () const

Double_t	GetStorageChance (const TString &volume)
	Returns the probability of an active volume being stored. More...

Double_t	GetStorageChance (Int_t n) const
	Returns the probability per event to register (write to disk) hits in the storage volume with index n.

Double_t	GetSubEventTimeDelay () const
	Returns the time gap, in us, required to consider a Geant4 hit as a new independent event. It is used to separate simulated events that in practice will appear as such in our detector. I.e. to separate multiple decay products (sometimes with years time delays) into independent events.

void	InsertSensitiveVolume (const TString &volume)
	Sets the name of the sensitive volume.

bool	IsActiveVolume (const char *volumeName) const

Int_t	isBiasingActive () const
	Returns the number of biasing volumes defined. If 0 the biasing technique is not being used.

Bool_t	isFullChainActivated () const
	Returns true in case full decay chain simulation is enabled.

bool	IsKeepTracksVolume (const char *volumeName) const

bool	IsKillVolume (const char *volumeName) const

Bool_t	isVolumeStored (const TString &volume) const
	Returns true if the volume named volName has been registered for data storage.

void	Merge (const TRestGeant4Metadata &)

TRestGeant4Metadata &	operator= (const TRestGeant4Metadata &metadata)

void	PrintMetadata () override
	Prints on screen the details about the Geant4 simulation conditions, stored in TRestGeant4Metadata.

Bool_t	PrintProgress () const
	It returns true if `printProgress` parameter was set to true.

Bool_t	RegisterEmptyTracks () const
	It returns false if `registerEmptyTracks` parameter was set to false.

void	RemoveParticleSources ()
	Remove all the particle sources.

void	SetActiveVolume (const TString &name, Double_t chance, Double_t maxStep=0)
	Adds a geometry volume to the list of active volumes. More...

void	SetFullChain (Bool_t fullChain)
	Enables/disables the full chain decay generation.

void	SetGdmlFilename (std::string gdmlFile)
	It sets the main filename to be used for the GDML geometry.

void	SetGdmlReference (std::string reference)
	Returns the reference provided at the GDML file header.

void	SetGeant4Version (const TString &versionString)
	Sets the value of the Geant4 version.

void	SetGeometryPath (std::string path)
	It sets the location of the geometry files.

void	SetMaterialsReference (std::string reference)
	Returns the reference provided at the materials file header.

void	SetNumberOfEvents (Long64_t n)
	Sets the name of the sensitive volume.

void	SetNumberOfRequestedEntries (Long64_t n)

void	SetSaveAllEvents (const Bool_t value)
	Enables or disables the save all events feature.

void	SetSeed (Long_t seed)
	Used exclusively by restG4 to set the value of the random seed used on Geant4 simulation.

void	SetSimulationMaxTimeSeconds (Int_t seconds)

void	SetSimulationTime (Long64_t time)

	TRestGeant4Metadata ()
	Default constructor.

	TRestGeant4Metadata (const char *configFilename, const std::string &name="")
	Constructor loading data from a config file. More...

	TRestGeant4Metadata (const TRestGeant4Metadata &metadata)

	~TRestGeant4Metadata ()
	Default destructor.

Public Member Functions inherited from TRestMetadata
void	AddLog (std::string log="", bool print=true)
	Add logs to messageBuffer.

void	DoNotStore ()
	If this method is called the metadata information will not be stored in disk.

TVector2	Get2DVectorParameterWithUnits (std::string parName, TVector2 defaultValue=TVector2(-1, -1))

TVector3	Get3DVectorParameterWithUnits (std::string parName, TVector3 defaultValue=TVector3(-1, -1, -1))

TString	GetCommit ()
	Returns the REST commit value stored in fCommit.

std::string	GetConfigBuffer ()
	Returns the config section of this class.

std::string	GetDataMemberValue (std::string memberName)
	Get the value of data member as string. More...

std::vector< std::string >	GetDataMemberValues (std::string memberName, Int_t precision=0)
	Get the value of datamember as a vector of strings. More...

TString	GetDataPath ()
	Returns a std::string with the path used for data storage.

Double_t	GetDblParameterWithUnits (std::string parName, Double_t defaultValue=PARAMETER_NOT_FOUND_DBL)
	Gets the value of the parameter name parName, after applying unit conversion. More...

Bool_t	GetError () const
	It returns true if an error was identified by a derived metadata class.

TString	GetErrorMessage ()
	Returns a std::string containing the error message.

TString	GetLibraryVersion ()
	Returns the REST libraty version stored in fLibraryVersion.

TString	GetMainDataPath ()
	Gets a std::string with the path used for data storage.

Int_t	GetNumberOfErrors () const

Int_t	GetNumberOfWarnings () const

std::string	GetParameter (std::string parName, TString defaultValue=PARAMETER_NOT_FOUND_STR)
	Returns corresponding REST Metadata parameter from multiple sources. More...

std::string	GetSectionName ()
	Returns the section name of this class, defined at the beginning of fSectionName.

TRestStringOutput::REST_Verbose_Level	GetVerboseLevel ()
	returns the verboselevel in type of REST_Verbose_Level enumerator

TString	GetVerboseLevelString ()
	returns the verbose level in type of TString More...

TString	GetVersion ()
	Returns the REST version stored in fVersion.

Int_t	GetVersionCode ()

UInt_t	GetVersionMajor () const

UInt_t	GetVersionMinor () const

UInt_t	GetVersionPatch () const

Bool_t	GetWarning () const
	It returns true if an error was identified by a derived metadata class.

TString	GetWarningMessage ()
	Returns a std::string containing the warning message.

TRestMetadata *	InstantiateChildMetadata (int index, std::string pattern="")
	This method will retrieve a new TRestMetadata instance of a child element of the present TRestMetadata instance based on the `index` given by argument, which defines the element order to be retrieved, 0 for first element found, 1 for the second element found, etc. More...

TRestMetadata *	InstantiateChildMetadata (std::string pattern="", std::string name="")
	This method will retrieve a new TRestMetadata instance of a child element of the present TRestMetadata instance based on the `name` given by argument. More...

Bool_t	isCleanState () const

Bool_t	isOfficialRelease () const

Int_t	LoadConfigFromBuffer ()
	Initialize data from a string element buffer. More...

Int_t	LoadConfigFromElement (TiXmlElement eSectional, TiXmlElement eGlobal, std::map< std::string, std::string > envs={})
	Main starter method. More...

Int_t	LoadConfigFromFile (const std::string &configFilename, const std::string &sectionName="")
	Give the file name, find out the corresponding section. Then call the main starter.

virtual void	Merge (const TRestMetadata &)

TRestMetadata &	operator= (const TRestMetadata &)

void	Print ()
	Implementing TObject::Print() method.

void	PrintConfigBuffer ()
	Print the config xml section stored in the class. More...

void	PrintMessageBuffer ()
	Print the buffered message.

void	PrintTimeStamp (Double_t timeStamp)
	Print the current time on local machine. More...

void	SetConfigFile (std::string configFilename)
	set config file path from external

void	SetError (std::string message="", bool print=true, int maxPrint=5)
	A metadata class may use this method to signal that something went wrong.

void	SetHostmgr (TRestManager *m)
	Set the host manager for this class.

void	SetSectionName (std::string sName)
	set the section name, clear the section content

void	SetVerboseLevel (TRestStringOutput::REST_Verbose_Level v)
	sets the verbose level

void	SetWarning (std::string message="", bool print=true, int maxPrint=5)
	A metadata class may use this method to signal that something went wrong.

void	Store ()
	If this method is called the metadata information will be stored in disk.

	TRestMetadata (const TRestMetadata &)

virtual void	UpdateMetadataMembers ()
	Method to allow implementation of specific metadata members updates at inherited classes.

virtual Int_t	Write (const char *name=nullptr, Int_t option=0, Int_t bufsize=0)
	overwriting the write() method with fStore considered

void	WriteConfigBuffer (std::string fName)
	Writes the config buffer to a file in append mode.

	~TRestMetadata ()
	TRestMetadata default destructor.

Data Fields
std::set< std::string >	fActiveVolumesSet = {}

Private Member Functions
void	InitFromConfigFile () override
	Initialization of TRestGeant4Metadata members through a RML file.

void	Initialize () override
	Initialization of TRestGeant4Metadata members.

void	ReadBiasing ()

void	ReadDetector ()
	Reads the storage section defined inside TRestGeant4Metadata. More...

void	ReadGenerator ()
	Reads the generator section defined inside TRestGeant4Metadata. More...

void	ReadParticleSource (TRestGeant4ParticleSource src, TiXmlElement sourceDefinition)
	It reads the <source definition given by argument.

Private Attributes
Bool_t	fActivateAllVolumes = false
	Sets all volume as active without having to explicitly list them.

std::vector< TString >	fActiveVolumes
	A std::vector to store the names of the active volumes.

std::vector< TRestGeant4BiasingVolume >	fBiasingVolumes
	A std::vector containing the biasing volume properties.

std::vector< Double_t >	fChance
	A std::vector to store the probability value to write to disk the hits in a particular event.

TVector2	fEnergyRangeStored = {0, 1E20}
	A 2d-std::vector storing the energy range, in keV, to decide if a particular event should be written to disk or not.

Bool_t	fFullChain = true
	Defines if a radioactive isotope decay is simulated in full chain (fFullChain=true), or just a single decay (fFullChain=false).

TString	fGdmlFilename
	The filename of the GDML geometry.

TString	fGdmlReference
	A GDML geometry reference introduced in the header of the GDML main setup.

TRestGeant4GeometryInfo	fGeant4GeometryInfo
	Class used to store and retrieve geometry info.

TRestGeant4PhysicsInfo	fGeant4PhysicsInfo
	Class used to store and retrieve physics info such as process names or particle names.

TRestGeant4PrimaryGeneratorInfo	fGeant4PrimaryGeneratorInfo
	Class used to store and retrieve Geant4 primary generator info.

TString	fGeant4Version
	The version of Geant4 used to generate the data.

TString	fGeometryPath
	The local path to the GDML geometry.

bool	fIsMerge = false

std::set< std::string >	fKillVolumes

TVector3	fMagneticField = TVector3(0, 0, 0)
	The world magnetic field.

TString	fMaterialsReference
	A GDML materials reference introduced in the header of the GDML of materials definition.

std::vector< Double_t >	fMaxStepSize
	A std::vector to store the maximum step size at a particular volume.

Double_t	fMaxTargetStepSize = 0
	The maximum target step size, in mm, allowed in Geant4 for the target volume (usually the gas volume). It is obsolete now. We define it at the active volume.

Int_t	fNBiasingVolumes = 0
	The number of biasing volumes used in the simulation. If zero, no biasing technique is used.

Long64_t	fNEvents = 0
	The number of events simulated, or to be simulated.

Long64_t	fNRequestedEntries = 0
	The number of events the user requested to be on the file.

std::vector< TRestGeant4ParticleSource * >	fParticleSource
	It the defines the primary source properties, particle type, momentum, energy, etc.

Bool_t	fPrintProgress = false
	If this parameter is set to 'true' it will print out on screen every time 10k events are reached.

Bool_t	fRegisterEmptyTracks = true
	If this parameter is enabled it will register tracks with no hits inside. This is the default behaviour. If it is disabled then empty tracks will not be written to disk at the risk of loosing traceability, but saving disk space and likely improving computing performance for large events.

Bool_t	fRemoveUnwantedTracks = false
	If activated will remove tracks not present in volumes marked as "keep" or "sensitive".

Bool_t	fRemoveUnwantedTracksKeepZeroEnergyTracks = false
	Option for 'removeUnwantedTracks', if enabled tracks with hits in volumes will be kept event if they deposit zero energy (such as neutron captures)

std::set< std::string >	fRemoveUnwantedTracksVolumesToKeep
	A container related to fRemoveUnwantedTracks.

Bool_t	fSaveAllEvents = false
	If this parameter is set to 'true' it will save all events even if they leave no energy in the sensitive volume (used for debugging purposes). It is set to 'false' by default.

Long_t	fSeed = 0
	The seed value used for Geant4 random event generator. If it is zero its value will be assigned using the system timestamp.

std::vector< TString >	fSensitiveVolumes
	The volume that serves as trigger for data storage. Only events that deposit a non-zero energy on this volume will be registered.

Int_t	fSimulationMaxTimeSeconds = 0
	Time before simulation is ended and saved.

Long64_t	fSimulationTime = 0
	The time, in seconds, that the simulation took to complete.

Double_t	fSubEventTimeDelay = 100
	A time gap, in us, determining if an energy hit should be considered (and stored) as an independent event.

Friends
class	DetectorConstruction

class	SteppingAction

class	TRestGeant4Hits

Additional Inherited Members
Protected Member Functions inherited from TRestMetadata
std::string	ElementToString (TiXmlElement *ele)
	Convert an TiXmlElement object to string. More...

TVector2	Get2DVectorParameterWithUnits (std::string parName, TiXmlElement *e, TVector2 defaultValue=TVector2(-1, -1))

TVector3	Get3DVectorParameterWithUnits (std::string parName, TiXmlElement *e, TVector3 defaultValue=TVector3(-1, -1, -1))

Double_t	GetDblParameterWithUnits (std::string parName, TiXmlElement *e, Double_t defaultVal=PARAMETER_NOT_FOUND_DBL)

TiXmlElement *	GetElement (std::string eleDeclare, TiXmlElement *e=nullptr)
	Get an xml element from a given parent element, according to its declaration.

TiXmlElement *	GetElementFromFile (std::string configFilename, std::string NameOrDecalre="")
	Open an xml encoded file and find its element. More...

TiXmlElement *	GetElementWithName (std::string eleDeclare, std::string eleName)
	Get an xml element from the default location, according to its declaration and its field "name".

TiXmlElement *	GetElementWithName (std::string eleDeclare, std::string eleName, TiXmlElement *e)
	Get an xml element from a given parent element, according to its declaration and its field "name".

std::string	GetFieldValue (std::string fieldName, std::string definition, size_t fromPosition=0)
	Gets field value in an xml element string by parsing it as TiXmlElement.

std::string	GetFieldValue (std::string parName, TiXmlElement *e)
	Returns the field value of an xml element which has the specified name. More...

std::string	GetKEYDefinition (std::string keyName)
	Gets the first key definition for keyName found inside buffer starting at fromPosition. More...

std::string	GetKEYDefinition (std::string keyName, size_t &Position)

std::string	GetKEYDefinition (std::string keyName, size_t &Position, std::string buffer)

std::string	GetKEYDefinition (std::string keyName, std::string buffer)

std::string	GetKEYStructure (std::string keyName)
	Gets the first key structure for keyName found inside buffer after fromPosition. More...

std::string	GetKEYStructure (std::string keyName, size_t &Position)

std::string	GetKEYStructure (std::string keyName, size_t &Position, std::string buffer)

std::string	GetKEYStructure (std::string keyName, size_t &Position, TiXmlElement *ele)

std::string	GetKEYStructure (std::string keyName, std::string buffer)

TiXmlElement *	GetNextElement (TiXmlElement *e)
	Get the next sibling xml element of this element, with same eleDeclare.

std::string	GetParameter (std::string parName, size_t &pos, std::string inputString)
	Returns the value for the parameter name parName found in inputString. More...

std::string	GetParameter (std::string parName, TiXmlElement *e, TString defaultValue=PARAMETER_NOT_FOUND_STR)
	Returns the value for the parameter named parName in the given section. More...

std::pair< std::string, std::string >	GetParameterAndUnits (std::string parname, TiXmlElement *e=nullptr)
	Returns the unit string of the given parameter of the given xml section. More...

std::map< std::string, std::string >	GetParametersList ()
	It retrieves a map of all parameter:value found in the metadata class.

TString	GetSearchPath ()

virtual void	InitFromRootFile ()
	Method called after the object is retrieved from root file.

virtual Int_t	LoadSectionMetadata ()
	This method does some preparation of xml section. More...

void	ReadAllParameters ()
	Reflection methods, Set value of a datamember in class according to TRestMetadata::fElement. More...

void	ReadParametersList (std::map< std::string, std::string > &list)
	It reads a parameter list and associates it to its corresponding metadata member. par0 --> fPar0.

std::string	ReplaceConstants (const std::string buffer)
	Identifies "constants" in the input buffer, and replace them with corresponding value. More...

std::string	ReplaceVariables (const std::string buffer)
	Identifies environmental variable replacing marks in the input buffer, and replace them with corresponding value. More...

void	ReSetVersion ()
	Resets the version of TRestRun to REST_RELEASE. Only TRestRun is allowed to update version.

std::string	SearchFile (std::string filename)
	Search files in current directory and directories specified in "searchPath" section. More...

void	SetLibraryVersion (TString version)
	Set the library version of this metadata class.

TiXmlElement *	StringToElement (std::string definition)
	Parsing a string into TiXmlElement object. More...

	TRestMetadata ()
	TRestMetadata default constructor.

	TRestMetadata (const char *configFilename)
	constructor

void	UnSetVersion ()
	Resets the version of TRestRun to -1, in case the file is old REST file. Only TRestRun is allowed to update version.

Protected Attributes inherited from TRestMetadata
std::string	configBuffer
	The buffer where the corresponding metadata section is stored. Filled only during Write()

std::string	fConfigFileName
	Full name of the rml file. More...

std::map< std::string, std::string >	fConstants
	Saving a list of rml constants. name-value std::pair. Constants are temporary for this class only.

TiXmlElement *	fElement
	Saving the sectional element together with global element.

TiXmlElement *	fElementGlobal
	Saving the global element, to be passed to the resident class, if necessary.

Bool_t	fError = false
	It can be used as a way to identify that something went wrong using SetError method.

TString	fErrorMessage = ""
	A std::string to store an optional error message through method SetError.

TRestManager *	fHostmgr
	All metadata classes can be initialized and managed by TRestManager.

Int_t	fNErrors = 0
	It counts the number of errors notified.

Int_t	fNWarnings = 0
	It counts the number of warnings notified.

std::string	fSectionName
	Section name given in the constructor of the derived metadata class.

Bool_t	fStore
	This variable is used to determine if the metadata structure should be stored in the ROOT file.

std::map< std::string, std::string >	fVariables
	Saving a list of rml variables. name-value std::pair.

TRestStringOutput::REST_Verbose_Level	fVerboseLevel
	Verbose level used to print debug info.

Bool_t	fWarning = false
	It can be used as a way to identify that something went wrong using SetWarning method.

TString	fWarningMessage = ""
	It can be used as a way to identify that something went wrong using SetWarning method.

std::string	messageBuffer
	The buffer to store the output message through TRestStringOutput in this class.

endl_t	RESTendl
	Termination flag object for TRestStringOutput.

Constructor & Destructor Documentation

◆ TRestGeant4Metadata()

TRestGeant4Metadata::TRestGeant4Metadata	(	const char *	configFilename,
		const std::string &	name = `""`
	)

Constructor loading data from a config file.

If no configuration path is defined using TRestMetadata::SetConfigFilePath the path to the config file must be specified using full path, absolute or relative.

The default behaviour is that the config file must be specified with full path, absolute or relative.

Parameters

configFilename	A const char* giving the path to an RML file.
name	The name of the specific metadata. It will be used to find the corresponding TRestGeant4Metadata section inside the RML.

Definition at line 764 of file src/TRestGeant4Metadata.cxx.

Member Function Documentation

◆ GetCosmicFluxInCountsPerCm2PerSecond()

Double_t TRestGeant4Metadata::GetCosmicFluxInCountsPerCm2PerSecond ( ) const

Reads the biasing section defined inside TRestGeant4Metadata.

This section allows to define the size and properties of any number of biasing volumes. Biasing volume properties include the multiplicity factor and the range of energies that particles will be propagated to the next biasing volume.

<biasing value="off" type="virtualBox">
  <biasingVolume size="2850mm" position="(0,0,0)mm" factor="2" energyRange="(0,5)MeV" />
  <biasingVolume size="2450mm" position="(0,0,0)mm" factor="2" energyRange="(0,5)MeV" />
  <biasingVolume size="2050mm" position="(0,0,0)mm" factor="2" energyRange="(0,5)MeV" />
</biasing>

Check for more details in the general description of this class.

Definition at line 914 of file src/TRestGeant4Metadata.cxx.

◆ GetSeed()

Long_t TRestGeant4Metadata::GetSeed ( ) const

inline

// Used for faster lookup

Returns the random seed that was used to generate the corresponding geant4 dataset.

Definition at line 175 of file TRestGeant4Metadata.h.

◆ GetStorageChance()

Double_t TRestGeant4Metadata::GetStorageChance ( const TString & volume )

Returns the probability of an active volume being stored.

Returns the probability per event to register (write to disk) hits in a GDML volume given its geometry name.

Definition at line 1550 of file src/TRestGeant4Metadata.cxx.

◆ ReadDetector()

void TRestGeant4Metadata::ReadDetector ( )

private

Reads the storage section defined inside TRestGeant4Metadata.

This section allows to define which hits will be stored to disk. Different volumes in the geometry can be tagged for hit storage. At least one volume must be tagged as sensitive

<detector>
  <parameter name="energyRange" value="(0,5)MeV" />
  <volume name="gas" sensitive="true" chance="1" maxStepSize="2mm" />
</detector>

Definition at line 1270 of file src/TRestGeant4Metadata.cxx.

◆ ReadGenerator()

void TRestGeant4Metadata::ReadGenerator ( )

private

Reads the generator section defined inside TRestGeant4Metadata.

This section allows to define the primary particles to be simulated. The generator will allow us to define from where we will launch the primary particles, their energy distribution, and their angular momentum.

<generator type="volume" from="gas" >
  <source use="Xe136bb0n.dat"/>
 
  <!--<source use="decay0" particle="Xe136" decayMode="0vbb" daughterLevel="3" />-->
 
  <!--<source use="geant4" particle="Na22" excitedLevel="0.0" fullChain="on">
    <angular type="isotropic" />
    <energy type="mono" energy="0.0" units="MeV" />
  </source>-->
</generator>

Definition at line 1026 of file src/TRestGeant4Metadata.cxx.

◆ SetActiveVolume()

void TRestGeant4Metadata::SetActiveVolume	(	const TString &	name,
		Double_t	chance,
		Double_t	maxStep = `0`
	)

Adds a geometry volume to the list of active volumes.

Parameters

name	The name of the volume to be added to the active volumes list for storage. Using GDML naming convention.
chance	Probability that for a particular event the hits are stored in that volume.
maxStep	It defines the maximum integration step at the active volume.

The aim of this parameter is to define control volumes. Usually the volume of interest will be always registered (chance=1).

Definition at line 1521 of file src/TRestGeant4Metadata.cxx.

The documentation for this class was generated from the following files: