Outline of G4DS Functions and Structure

Summary: The simulation tool uses the DarkSide program’s detectors (DarkSide-10,
DarkSide-20k, Darkside-50) to describe the energy and time responses. G4DS attempts
to calibrate the energy responses in S1 and S2, as well the time response expressed by
the f​90 . G4DS calibration is controlled mainly through the modification of the mac file
that is used to change parameters, and if necessary, modification of the ​g4ds.cc file in the
main folder. This is not recommended, but I am not yet experienced with this software,
so if the coder is well-versed with Geant4 and its coding tendencies, then it should be
the file where large adjustments to the way the simulation runs can be made. The
output of G4DS is a binary file (.fil) as well as a log file (.log).

The Physics Lists: ​The provided ​G4EmLivermorePhysics List is the primary Physics List

used in G4DS because Darkside fits perfectly within its energy range and precision.
However, for the Hadronic Physics Lists (need very high accuracy in low energy
neutron propagation with a 10​6 range from eV to MeV), a custom made Physics List was
developed. The standard Geant4 Physics Lists can be substituted in for the purpose of
studying different non-Darkside specific events (cosmic muon propagation and
production of cosmogenic isotopes.) Here are the main Physics Lists used in G4DS:
● Electromagnetic:
○ Standard Geant4
○ Livermore
● Hadronic:
○ HP
○ QGSP_BERT_HP
○ QGSP_BIC_HP
○ FTF_BIC_HP
○ FTFP_BERT_HP
○ Shielding

The Main Method: The C++ class that controls the simulation and calls the other
methods as necessary is named ​g4ds.cc and is located in the “/g4ds directory. A quick
overview of it is that it imports all the other necessary header files it needs in G4DS,
such as the ​DSLogger, DSManager, etc and then inherits the other classes in order, using
them to run the simulation. There are global variables defined to count the amount of
photons, handle the Physics Lists, and work with the Detector Construction.
The main method finds any filenames related to the output. These are the log files. If
there are any, it stacks onto them, if not, then it will create a new one. Then, it outputs
to the log file clearly stating the simulator and the input given, then starts to print out
the output produced by the program. The output file is well formatted with large
spaces and divisions so it can be quickly read and understood.

It begins by calling each of the other classes in the simulation, and letting them handle
their own tasks. In order, the classes that are called are: ​DSDetectorConstruction,
DSPhysicsList, DSPrimaryGeneratorAction, DSRunAction, DSEventAction,
DSTrackingAction, DSSteppingAction, DSStackingAction (if stacking action is turned on
only)​.

After calling the other classes, there is a block dedicated to handling the visualization
manager if that is being used. It uses the provided G4VisManager and the
G4TrajectoryDrawByParticleID classes, sets the colors and names of the model, then
registers them with the visManager classes, and finally has the trajectory drawn with
the earlier mentioned class.

There is another block of code for if GDML (Geometry Description Markup Language)
is being utilized in the program. This language is a specialized XML-based language
designed to be used in describing the geometries of the detectors used in simulations. It
helps to more easily define solids in “geometry trees”, which are used to define the
model in a hierarchy of different solids to construct them in more accessible regions.

Finally, there are two methods at the end to print out more information about the
program. These can be easily modified to display whatever ending messages/variables
are desired as output.

Other Classes and their descriptions: ​A quick overview of the classes mentioned

above, and others not yet mentioned, and their primary function. These classes are
located in “/g4ds/src”. This is a simple overview as there are many classes and some
can be quite vast. The classes that are mentioned above are underlined below.

DSDetectorCalibrationDevice: This class handles the construction of the calibration device

(a collimator) for the DarkSide detector. The configuration commonly used by the
Princeton staff is provided, but commented out, so that the programmer may use
whatever configuration they require.
DSDetectorConstruction​: This is one of the important classes that draws upon many
others in the program. It handles the various cases for the “fDetectorConfiguration”
value. The class uses if-else statements to set up the specific combinations of detectors
used in Darkside. For example, 0 indicates that the entire detector should be
constructed. 2 indicates only the TPC (Time Projection Chamber) should be constructed,
and specific numbers such as 808 indicate that the WT, NV, DS50 TPC, and collimator
should be constructed.

DSDetectorConstructionMessenger: Simple class using if statements and several

pre-existing Geant4 functions to define the measurements of the Detector Construction
and any necessary messages required.

DSDetectorDart: Class used to define the colors and visual attributes of the Dart, then
construct the geometry of the Dart by each part. Rather complicated code, can’t say I
completely understand it at the moment.

DSDetectorDS5k: Similar class to the one above, used to constructor the DS5k geometry.
Contains both the definition for visual attributes as well as the actual geometry building
parts of the code.

DSDetectorDS10​: Same as above except for DS10 instead of DS5k.

DSDetectorDS20k:​ Same as above, for DS20k.

DSDetectorDS50​: Same as above, for DS50.

DSDetectorDSG2: This class constructs the geometry for the G2 detector of DarkSide.
Several parts of code, such as the code for the PMT (PhotoMultiplier Tube) construction,
have been commented out. There is also a set of values declared to be “completely
wrong” in the beginning in the comments. They appear to be the distances from the
center (0,0,0) or origin of the geometry to the top for different parts of the contructor,
such as Liquid Argon, and their variable names. However, I have no idea why they're
labeled as wrong. It’s presumable that the PMT and other commented out parts of the
code are in the process of being debugged and re-enabling them would cause the
program to crash for now.

DSDetectorDSG3​: Similar class to above, but for the G3 detector. However, this one does
not have any values labeled as completely wrong, but it does have a few pieces of code
that are being debugged, as above.
 *​ Several other detector classes, that all follow basically the above format and do their specific
constructions. The function can be inferred from the names for these. Here is a list of all of them:
● DSDetectorLicorne
● DSDetectorNeutronLicorne
● DSDetectorNeutronVeto
● DSDetectorNeutronVetoG3
● DSDetectorPET
● DSDetectorPMTDS50
● DSDetectorPMTDSG2
● DSDetectorPMTDSG3
● DSDetectorPMTNeutronVeto
● DSDetectorPMTNeutronVeto20k
● DSDetectorReD
● DSDetectorTester
● DSDetectorWaterTank

DSDetectorSource: ​Constructs the geometry for the Source holder in the detector.
Curiously, has the same values commented in the beginning as ​DSDetectorDSG2​.
However, this time, the values have not been listed to be completely wrong. Assuming
that the edit for them to be wrong was made later in ​DSDetectorDSG2​, it is probably best
to assume these values are not accurate in this class either.

DSEventAction​: Standard class for the obtaining of events that occur during the
simulation. It is basically used for getting the values of the simulation, such as
photoelectron deposit amounts, and then another class, which is called by this one, is
used to handle them.

DSEventActionMessenger: ​Very small class just used to grab the event actions from the
last class and message them.

DSEventHandler​: The class that actually handles the data from the events. This class first
writes all of the obtained values to the log, then clears all of the variables and sets their
values back to 0, setting everything back to default for the next run of the simulation.

DSG4DSReader: Class used to get the G4DS files and read them. Has several parts of
code commented out that actually change values, leaving only the commands that read
the code active. Unsure whether in debugging or optional for user to change.
After this, there are several generator classes (and their messenger classes), akin to the
several detectors above. They are used to actually shoot energy from the source with
several settings (no gamma, 1 ‘Gamma’, 2 ‘Gammas’, etc.). Their overall function can be
easily understood by reading the class name so I will list them as I did before:
● DSGeneratorAmBeSource
● DSGeneratorAmBeSourceMessenger
● DSGeneratorAmCSource
● DSGeneratorAmCSourceMessenger
● DSGeneratorCosmicRayMuons
● DSGeneratorCosmicRayMuonsMessenger
● DSGeneratorEnergyDesposit
● DSGeneratorEnergyDespositMessenger
● DSGeneratorG4Gun
● DSGeneratorG4GunMessenger
● DSGeneratorKr85m
● DSGeneratorLicorne
● DSGeneratorLicorneMessenger
● DSGeneratorMultiEvent
● DSGeneratorMultiEventMessenger
● DSGeneratorNeutronsAtGS
● DSGeneratorNeutronsAtGSMessenger
● DSGeneratorRDMDecayGun
● DSGeneratorRDMDecayGunMessenger
● DSGeneratorRDMNucleus
● DSGeneratorRDMUIcmdWithNucleusAndUnit
● DSGeneratorSCS
● DSGeneratorSCSMessenger

DSIO: Class defining several fstreams(filestreams) used to read and write into files for
recording G4DS values. Probably stands for DarkSide InputOutput.

DSLight​: Class used for the implementation of S1 and S2 light classes.

DSLight2: Second version of the ​DSLight ​class above, seems to be still in development
and not working. The default version, ​DSLight​, should still be used.

DSLight3: An alternate third version, with different important parameters, LAr

scintillation properties from a specific file, and with the drift time calculated based on
the fLArGArBoundaryZ value. This value was set in ​DSDetectorConstruction​.
DSLogger​: The logger class.

DSLScintillation​: The class that handles the scintillation generation. The code here is
honestly rather complex so I cannot provide more insight into the processes as of yet.

DSManager: Manager class that calls the next class, which handles most of the work,
and then deletes it once the process is complete.

DSManagerMessenger: This class imports several header files to do with handling the
run actions, values and constants, a Randomizer, and time values. It controls the
Logger, IO, and unit values for the program, setting the parameters and such.

DSMaterial​: Class to define the various elements and compounds used in the simulation
and give them identifiers and properties.

DSOpWLS​: Highly complicated class that has something to do with the WLS. No real
ideas what it does. Perhaps Op stands for optical?

DSParameters: Controls a large number of parameters throughout the program. This is

the program to modify if any parameters need to be changed.

DSPhysicsList​: Constructs the special Physics Lists developed specifically for DarkSide,
and compiles all of them to be used for the simulation.

DSPhysisListMessenger​: Messenger class for the class above.

DSPrimaryGeneratorAction​: Simple class that calls the generation of the Primary Events,
the rest is handled by the other generator classes.

DSPrimaryGeneratorActionMessenger:​ Messenger class for the class above.

DSRunAction​: Makes sure all required log and binary files are present before running
the simulation with a random seed and stopping it when the timer finishes.

DSRunActionMessenger:​ Messenger class for the class above.

DSScintCell: Test class to test the 3” cells that Shawn (don’t know who that is) is
working with in Princeton. Probably not that useful for UMass.
DSStackingAction​: Controls the stack manager for the simulation, and prepares new
events to be stacked on one another as the simulation continues, if enabled.

DSStackingActionMessenger: ​Implied.

DSStackingDefault: Adds a default stacking for killing particles from long living nucleus
decays.

DSStackingRDM and DSStackingRDMChain​: Adds radioactive decay and radioactive

decay chain generators. These require the correspondent stacking actions.

DSStackingRDMMessenger and DSStackingRDMChainMessenger: ​As usual.

DSSteppingAction​: ​Class to keep track of the step sizes throughout the simulation. It uses
DSEventHandler​ as necessary to set the step sizes for various values.

DSStorage: Seems to be a class to store all non-unit based values for the simulation, with
a few bits of commented out code that are still being debugged.

DSTrackingAction: ​Tracks both Primaries and Secondaries throughout the simulation

and uses ​DSEventHandler to get the needed values for several parameters (time,
position, volume, etc.) and store them.

These next classes are virtual base classes that are not actually used, but rather are given
as templates for building new classes. The template to which they correspond can be
easily inferred:
● DSVGenerator
● DSVGeneratorMessenger
● DSVStackingAction

DSVisManager​: Handles the visManager for the simulation.

There are a few other classes used, but these are given by Geant4 already, so I’ll just list
them: ​G4Cerenkov, G4OpBoundaryProcess, G4OpticalPhoton, G4ParticleDefinition,
G4ProcessManager, G4RadioactiveDecay, G4Scintillation.

I realize this writeup is in no way in-depth, and there are lots of pieces I have not
covered, the numerous header files for example. However, this code is highly complex
and beyond the skill level of anything I have dealt with up to this point. Therefore, I
will continue to add to this outline and hopefully be able to clarify anything that was
missing. If there any questions, feel free to contact me:

Shashank Jayakumar
sjayakumar@umass.edu
(330)-988-7666