Home

==Documentation of g4sbs: Overview==

This page is maintained by the UConn group (Andrew Puckett) and as of July 22, 2015 is specific to the "uconn_dev" branch of g4sbs on github.

===Coordinate System(s)=== The ''global'' coordinate system of the simulation has

• +X horizontal to beam left
• +Y vertically up
• +Z along the beam direction There are several "local" coordinate systems specific to different detectors in the simulation. These are discussed in the "ROOT tree structure" section below.

===System of units===

The standard GEANT4 system of units is used. See [http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch03s03.html GEANT4 user's guide] for details. The default units assumed unless otherwise specified in the code are ''mm'', ''ns'' and ''MeV'' for distance, time and energy-dimensioned quantities, respectively. Commands defined below that require units may be specified using any of the units in the standard [http://www-zeuthen.desy.de/geant4/clhep-2.0.4.3/SystemOfUnits_8h-source.html CLHEP] unit definitions.

'''Note: All quantities written to the ROOT tree that constitutes the main output of g4sbs (see below) are expressed in meters, ns, GeV for distance, time and energy. Angles in the ROOT tree are expressed in radians'''

==Getting the code and building the program==

===Prerequisites===

*Working [https://root.cern.ch/drupal/ ROOT] installation. '''g4sbs is not yet compatible with root version 6!''' *Working [http://geant4.web.cern.ch/geant4/ GEANT4] installation. '''For the uconn_dev branch (as of January 14, 2016), g4sbs is only compatible with GEANT4 version 10.1 and later. Other branches (except for the "geant4.10" branch), including the master branch, are only compatible with GEANT4 version 9.x and earlier'''

• [http://cmake.org/ cmake] (also required in any case to build GEANT4).

Note on GEANT4 build options:

• GEANT4_INSTALL_DATA=ON is needed for installations on new machines.
• '''Qt note:''' On Mac OS X, I have built GEANT4 against Qt version 5.3.2. Your mileage may vary with newer versions of Qt. On Linux, the open-source version of Qt provided by the package manager of your distribution is recommended.

===Downloading the repository===

The code is hosted on a github repository owned by JLab. To clone via ssh (preferred method on JLab batch farm), do:

{| class="wikitable" style="background: #BFBFBF;" |- | '''git clone [email protected]:JeffersonLab/g4sbs.git''' |- |}

For this method to work, the ssh public key on the machine where you want to get the code must be added to your github account (see [https://help.github.com/articles/generating-ssh-keys/ Guide] to generating ssh keys and adding to your github.com account.)

Cloning the repository defaults to the "master" branch. This page documents the "uconn_dev" branch, which will soon be merged into the master branch. To change to the "uconn_dev" branch, do: {| class="wikitable" style="background: #BFBFBF;" |- | '''git checkout uconn_dev''' |- |}

===Building the program===

Create a "build" directory that is parallel to the "g4sbs" source directory (this is not strictly required, but the build directory must be separate from the "g4sbs" directory in any case). The following instructions assume that "build" is parallel to "g4sbs": {| class="wikitable" style="background: #BFBFBF;" |- | '''mkdir build''' |- | '''cd build''' |- | '''cmake ../g4sbs''' |- | '''make''' |} If successful, the g4sbs executable and several other files and folders will be created in the "build" directory.

===Configuring the environment on the JLab batch farm===

'''Updated January 14, 2016''':

To use the standard versions of ROOT and GEANT4 supported by JLab on the batch farm, add the following lines to the ".login" file on your JLab CUE home directory:

{| class="wikitable" style="background: #BFBFBF;" |- | setenv JLAB_VERSION 1.3 |- | setenv JLAB_ROOT /site/12gev_phys |- | source $JLAB_ROOT/$JLAB_VERSION/ce/jlab.csh |}

As of January 14, 2016, the JLab version "1.3" software versions on the JLab batch farm are:

• ROOT version 5.34.34
• GEANT4 version 4.10.01.p02

==How to run the program==

g4sbs works in two different modes, batch mode or interactive mode. In interactive mode, visualization of the geometry and events is possible. To run in interactive mode, do

{| class="wikitable" style="background: #BFBFBF" |- | '''./g4sbs''' |}

This will launch an interactive g4sbs session which, depending on your GEANT4 build, might be a csh terminal, a Qt GUI, or something in between. The Qt GUI in particular has a complete help menu:

Image:G4sbs_QtGUI.png

In an interactive g4sbs session, individual commands can be invoked, or macros with many commands can be executed using: {| class="wikitable" style="background: #BFBFBF" |- | '''/control/execute file.mac''' |} Due to the structure of the program, all commands invoked in an interactive session are executed after initialization of the GEANT4 kernel; i.e., after the invocation of G4RunManager::Initialize(). At the command prompt or in macros, all standard GEANT4 commands are available as well as g4sbs-specific commands (see below).

To run g4sbs in batch mode, do one of the following: {| class="wikitable" style="background: #BFBFBF" |- | '''./g4sbs file.mac''' ''OR'' |- | '''./g4sbs preinit.mac postinit.mac''', |} where each ".mac" file is a text file containing valid GEANT4 and/or g4sbs commands, used to configure the simulation. If g4sbs is invoked with one command-line argument as in the first example, it will execute all the commands in "file.mac" ''after'' G4RunManager::Initialize(). If g4sbs is invoked with two command line arguments as in the second example, it will execute the commands in "preinit.mac" ''before'' G4RunManager::Initialize() and the commands in "postinit.mac" ''after'' G4RunManager::Initialize(). As detailed below, this feature was added to make it possible for the user to disable optical photon production via the Cherenkov and Scintillation processes without re-compiling the code, and a long-standing GEANT4 bug prevents disabling of the scintillation process via the standard /process/inactivate command.

'''Update January 25, 2016: New command-line options'''

Several options were added to the command-line arguments to g4sbs to allow the user more flexible control. Macro filenames may now be prefixed with keywords "preinit=" or "postinit=" to indicate that the commands are to be executed before or after initialization, respectively. These keywords can also be used to override the default ordering of command-line arguments. The optional "batch=X" argument was added (where X=0,1 or false,true) to force g4sbs to run in batch or interactive mode. In practice, only the "batch=0" or "batch=false" case is necessary, since in all cases where it makes sense to run in batch mode, batch mode is selected by default. Some combinations of these arguments are nonsensical; for example, if only pre-initialization commands are given, then only interactive mode makes sense, since the "/g4sbs/run" command which builds the geometry and generates events can only be executed after the initialization phase. Here are some examples of valid command-line invocations of ''g4sbs'': *'''./g4sbs file.mac''': execute the commands in '''file.mac''' after initialization, run in batch mode by default. *'''./g4sbs file1.mac file2.mac''': execute the commands in '''file1.mac'''('''file2.mac''') before (after) initialization, run in batch mode by default. *'''./g4sbs preinit=file.mac''': execute the commands in '''file.mac''' before initialization, run in interactive mode. *'''./g4sbs file.mac batch=0''': execute the commands in '''file.mac''' after initialization, but force running in interactive mode ('''batch=false''' also works). *'''./g4sbs file1.mac file2.mac batch=0''': execute the commands in '''file1.mac''' ('''file2.mac''') before (after) initialization; run in interactive mode. *'''./g4sbs postinit=file1.mac preinit=file2.mac''': run in batch mode, execute '''file2.mac''' ('''file1.mac''') before (after) initialization.

==g4sbs commands==

===Documentation of all commands=== This section documents all g4sbs commands defined in the uconn_dev branch as of July 23, 2015. '''Command names are case-sensitive!'''

• '''/g4sbs/run''': Starts a simulation run. Requires one integer argument defining the number of events to simulate (which is allowed to be zero). Note that this command forces building or rebuilding of the geometry, in contrast to '''/run/beamOn''', which does not re-initialize the G4 kernel. ''Presently, g4sbs will crash if the '''/g4sbs/run''' command is invoked more than once in a g4sbs session (bug is under investigation), meaning that configuration changes require separate simulation jobs.''
• '''/g4sbs/gemconfig''': expects one integer argument, defines BigBite GEM layout, possible values are 1 (default), 2, 3. Currently, option 1 is the only option that is compatible with the GRINCH geometry and is therefore recommended.
• '''/g4sbs/CDetconfig''': defines configuration of the coordinate detector. '''''This command is obsolete and currently has no effect'''''
• '''/g4sbs/flipGEM''': requires one boolean argument. Defaults to false. If true, reverses orientation of GEM materials front to back within each GEM chamber. Currently the command applies to ALL GEMs in the simulation.
• '''/g4sbs/ECALmap''': Accepts one string argument which is the name of a text file listing active ECAL cells (rows, columns). File is assumed to be located in the "database/" subdirectory. '''''This command is obsolete and currently has no effect'''''
• '''/g4sbs/filename''': Define output ROOT file name.
• '''/g4sbs/sigmafile''': File containing GEM coordinate resolutions by chamber ID number. '''''This command is obsolete and currently has no effect'''''
• '''/g4sbs/target''': Choose target type. Possible values currently include: ** '''LH2''': liquid hydrogen target with scattering chamber and vacuum snout. Density fixed at 0.071 g/cm^3 ** '''LD2''': liquid deuterium target with scattering chamber and vacuum snout. Density fixed at 0.1624 g/cm^3 ** '''H2''': Hydrogen gas target, fixed pressure of 10.5 atm at 300 K ** '''3He''': Helium-3 gas target, fixed pressure of 10.77 atm at 300 K. ** '''neutron''': Free neutron target, fixed pressure of 10.5 atm at 300 K. ** '''''Note:''''' All gas targets are currently enclosed in a GE180 glass cell with endcap thickness of 0.126 mm and wall thickness of 1.61 mm
• '''/g4sbs/kine''': Choose kinematics for event generator. In all cases, unless otherwise noted, interaction vertex is generated flat assuming a rectangular, uniform raster pattern centered at (x,y)=(0,0) with user-defined raster size in x and y, and z along the target length. No "internal" or "pre-vertex" external radiative corrections are included in any of the event generators so far. Currently available kinematics types are: ** '''elastic''': elastic electron-nucleon scattering. Electron polar and azimuthal angles are generated flat in \cos \theta and \phi within user-defined limits, everything else calculated from energy-momentum conservation. Cross section according to Kelly fit for GEp, GMp, GMn and Hall A GEn collaboration fit of GEn data. No radiative corrections. Behavior depends on target type: *** For H2 or LH2 or neutron targets: elastic electron scattering from free proton (or neutron) at rest *** For LD2 or ^3He targets: Quasi-elastic electron-nucleon scattering with Fermi motion simulated by sampling the initial nucleon momentum from the momentum distribution in deuterium or ^3He. ** '''inelastic''': Inclusive inelastic electron-proton or electron-deuteron scattering. Generates electron scattering angles flat in \cos \theta and \phi within user-defined limits and generates electron energy flat from zero up to the full beam energy. Requires energy-momentum conservation. Uses Christy-Bosted parametrizations of inclusive p(e,e') (http://arxiv.org/abs/0712.3731v4) and inclusive d(e,e') (http://arxiv.org/abs/0711.0159v4) to compute inclusive inelastic cross sections for proton and neutron. Generates a final-state nucleon by assuming that the hadronic final state is N\pi and that the pion momentum is generated isotropically in the rest frame of the virtual-photon-nucleon system. ** '''flat''': Generate electron angles flat in \cos \theta, \phi, and E'. Generate final nucleon assuming that the outgoing nucleon absorbs all of the three-momentum transfer from the electron. Not clear how much sense this makes physically. ** '''dis''': Deep inelastic scattering. Generate scattered electron angles flat within user-defined limits, generate E' flat in 0 \le E' \le E. Reject event if not kinematically allowed. Don't generate any final hadrons. Cross section based on CTEQ6 PDFs and neglect of longitudinal structure function F_L = 0 ** '''beam''': Beam kinematics. Generate beam electrons 5 meters upstream of the target with (x,y) according to normal raster size definitions. This option is the "minimum bias" generator that throws beam electrons at the target, and is typically used for background rates/detector occupancies/etc. ** '''sidis''': Single-hadron semi-Inclusive deep inelastic electron-nucleon scattering (SIDIS) N(e,e'h)X. Generate outgoing electron and hadron angles flat in \cos \theta and \phi within user-defined limits. Generate outgoing electron and hadron energies flat within user-defined limits. Check four-momentum conservation and reject event/try again until a kinematically allowed event is returned. Compute cross section according to CTEQ6 PDFs and DSS2007 fragmentation functions. Assume flavor-independent Gaussian transverse momentum widths for PDF and fragmentation function. Neglect the longitudinal cross section for SIDIS. On output, normalize phase-space volume for event generation according to the efficiency for generating kinematically allowed events. Hadron h = \pi^+, by default. See '''/g4sbs/hadron''' for available hadrons in the event generator. ** '''wiser''': Single inclusive hadron production. Generate outgoing hadron angles and energy flat within user-defined limits, compute "Wiser" cross section. See '''/g4sbs/hadron''' for available hadrons for this generator. Cross section calculation only defined for \pi^\pm, \pi^0. ** '''gun''': Generic particle gun. Generate outgoing particle angles and energy according to user-defined limits. Vertex is generated according to usual prescription. Any valid GEANT4 particle type can be selected. ** '''pythia6''': PYTHIA6.4 events. This generator actually does not call the ROOT-PYTHIA6.4 event generation interface directly. Instead, it reads primary events from a ROOT tree in a pre-defined format, documented below (see /g4sbs/pythia6file command). Any event generator that prepares events in this format can be used in ''g4sbs'' directly, without modifying the source code. An example macro that generates events in the format required by ''g4sbs'' using ROOT's built in interface to PYTHIA6 can be found in ''root_macros/Pythia6_minbias_gen.C''. ** '''gmnelasticcheck''': Same as "elastic", but generates both a proton and a neutron with identical kinematics, in order to compare proton/neutron acceptances. Particularly useful for the GMN experiment.
• '''/g4sbs/pythia6file''': Name of ROOT file containing events from PYTHIA6 (or other arbitrary event generators) in a predefined format. ** ''PYTHIA6 event format:'' The "pythia6" generator expects events in a ROOT tree with the following branch structure (see ''root_macros/Pythia6_minbias_gen.C'' and ''root_macros/Pythia6_tree.h'' for more details). Some of the branches and kinematic variables are specific to electron scattering, but the branches defining primary particles in the event are completely general. *** '''Int_t Nparticles''': (type int) Total number of particles in the event. This is the size of the particle arrays. *** '''Float_t Q2''': (type float) Four-momentum transfer squared or invariant mass squared of the virtual photon *** '''Float_t xbj''': (type float) Bjorken x variable *** '''Float_t y''' : (type float) fractional energy lost by the scattered electron *** '''Float_t W2''': (type float) Invariant mass squared of virtual photon-nucleon system. *** '''vector *status''': LUND status code of primary particles. "status==1" indicates final-state particles that will actually be generated. "status==21" indicates initial-state particles and "header" information in the event record. Other status codes indicate virtual and intermediate-state particles that have decayed. *** '''vector *pid''': LUND particle ID code. Particle numbers are according to the scheme documented by [http://pdg.lbl.gov/2015/reviews/rpp2015-rev-monte-carlo-numbering.pdf PDG]. *** '''vector *parent''': index in the particle array of the parent of this particle (''NOTE: the "parent" index starts at 1, with particle 1 always being the primary beam electron in the case of PYTHIA6 events. In C++ the array index starts with 0, so to access the parent particle one would use array index parent-1]'') *** '''vector *fchild''': Array index (starting at 1) of the first child particle of the current particle. *** '''vector *lchild''': Array index (starting at 1) of the last child particle of the current particle. *** '''vector *px''': x-component of particle three-momentum (in the same coordinate system as ''g4sbs''). Units are GeV/c *** '''vector *py''': y-component of particle three-momentum (in the same coordinate system as ''g4sbs''). Units are GeV/c *** '''vector *pz''': z-component of particle three-momentum (in the same coordinate system as ''g4sbs''). Units are GeV/c *** '''vector *vx''': x-component of vertex where particle was produced (same coordinate system as ''g4sbs''). Units are mm. *** '''vector *vy''': y-component of vertex where particle was produced (same coordinate system as ''g4sbs''). Units are mm. *** '''vector *vz''': z-component of vertex where particle was produced (same coordinate system as ''g4sbs''). Units are mm. *** '''vector *E''': Total energy of particle (in GeV). *** '''vector *M''': Invariant mass of particle (in GeV/c^2) *** '''vector *theta''': Polar angle of particle trajectory in radians *** '''vector *phi''': Azimuthal angle of particle trajectory in radians *** '''vector *t''': Time since start of event at which particle was produced, in lab frame, in units of mm/c. *** '''vector *tau''': Time since start of event at which particle was produced, in particle rest frame (i.e., proper time), in units of mm/c.
• '''/g4sbs/exp''': Choose experiment configuration. This defines which detectors/magnets/target/etc. will be built. Expects string argument. Valid choices are: ** '''gep''': GEP experiment. Geometries are: *** GEP-specific downstream beamline elements *** GEP electron arm: **** ECAL **** CDET. *** GEP hadron arm: **** SBS magnet, pole shims, field clamps (optional), lead inserts (optional). **** HCAL: Remember to offset HCAL vertically by a 49.7 cm (see /g4sbs/hcalvoffset command), so that it is centered within the magnet acceptance for (upbending) elastically scattered protons. **** FPP: GEMs and CH_2 analyzers ** '''gmn''': GMN experiment. Geometries are: *** GMN electron arm: BigBite with standard detector package *** GMN hadron arm: SBS magnet (no pole shims or field clamps), Default is HCAL vertically centered with respect to SBS magnet gap (change via /g4sbs/hcalvoffset command as necessary). ** '''gen''': GEN experiment. Detector configuration same as GMN. ** '''a1n''': A1n experiment. Detector configuration same as GMN (should it be? Actual experiment uses HRS). ** '''sidis''': SIDIS experiment. *** SIDIS electron arm: BigBite with standard detector package. *** SIDIS hadron arm: SBS magnet without pole shims or field clamps. Default is HCAL vertically centered. Additional SBS trackers and RICH detector. ** '''C16''': C16 prototype test in Hall A. Includes C16 calorimeter and Hall A DVCS scattering chamber, as well as simplified descriptions of downstream beamline.
• '''/g4sbs/particle''': Defines particle type for ''gun'' generator. Requires string argument. Any valid GEANT4 particle name is accepted. See [http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch05s03.html Particles] chapter in GEANT4 user's guide.
• '''/g4sbs/hadron''': Choose hadron type for SIDIS and/or Wiser generators. Valid choices are: ** '''pi+''': positive pion, valid for sidis, wiser ** '''pi-''': negative pion, valid for sidis, wiser ** '''pi0''': neutral pion, valid for sidis, wiser ** '''K+''': positive kaon, valid for sidis (Wiser will generate but not calculate cross section) ** '''K-''': negative kaon, valid for sidis (Wiser will generate but not calculate cross section) ** '''p''': proton, valid for sidis (Wiser will generate but not calculate cross section) ** '''pbar''': antiproton, valid for sidis (Wiser will generate but not calculate cross section)
• '''/g4sbs/48d48field''': Expects integer argument. Turn on (1) or off (0) SBS uniform magnetic field. ** Turning ON (1) adds a uniform magnetic field located in the gap of the SBS magnet, and adds it to the "global field" object in G4SBSDetectorConstruction. If the "fUseGlobalField" flag of "G4SBSDetectorConstruction" is false, which is the case by default, the "fUseLocalField" flag is set for the "G4SBSHArmBuilder" class which defines the SBS geometry, which causes a local magnetic field to be associated with the air gap inside the SBS dipole magnet. '''Note: This command should never be used in combination with ''/g4sbs/tosfield'' below, as it will cause the uniform magnetic field to be added in superposition with the TOSCA field, approximately doubling or canceling the magnetic field in the gap, depending on the overall scale factors applied.'''. See "Setting up the magnetic field" below for a more detailed discussion of the way magnetic fields are handled. ** Turning OFF (0) deletes the uniform magnetic field from the global field if it exists, and sets the "local field" flag for "HArmBuilder" to false if and only if the "fUseGlobalField" flag of G4SBSDetectorConstruction is true, which prevents the uniform field from being created in "HArmBuilder"
• '''/g4sbs/bbfield''': Expects integer argument. Turn on (1) or off (0) BigBite magnetic field. Requires BigBite field map file (see "setting up the magnetic field" below). '''Note: g4sbs currently requires map file to be named "map_696A.dat", as this file name is hard-coded'''. ** Turning ON (1) creates a new "G4SBSBigBiteField" object and adds it to the global field. If the "fUseGlobalField" flag of "G4SBSDetectorConstruction" is false, which is the case by default, the "fUseLocalField" flag is set for the "G4SBSEArmBuilder" class which defines the BigBite geometry. The bigbite magnetic field map is then assigned to the mother logical volume containing the BigBite magnet and detectors. ** Turning OFF (0) deletes the bigbite field from the global field object, and sets the "local field" flag for "EArmBuilder" to false iff the "global field" flag is set.
• '''/g4sbs/tosfield:''' Use global field from TOSCA field map file. Expects string argument equal to file name of map file. Requires SBS TOSCA field map file. See "setting up the magnetic field" below for more details. '''Note: invoking /g4sbs/tosfield is currently the only mechanism to set the "global field" flag to true.''' Invoking this command sets the "local field" flags for "EArmBuilder" and "HArmBuilder" to false.
• '''/g4sbs/shootgeantino''': Expects a boolean argument. If true, shoot a geantino instead of an electron.
• '''/g4sbs/invertfield''': Expects a boolean argument. If true, changes the sign of all global magnetic fields (also changes the sign of local magnetic fields).
• '''/g4sbs/totalabs''': Expects boolean argument. If true, causes BigBite and SBS magnet materials to be total absorbers using G4UserLimits. Useful to speed up the simulation in applications such as acceptance and rate calculations. Default value is false.
• '''/g4sbs/targlen''': Sets target length along beam direction. Requires a value and a unit.
• '''/g4sbs/targden''': Sets target density. Requires a value and a unit. ''Note: the current behavior of the code is that this command has no effect, because the densities of target materials are hard-coded in G4SBSDetectorConstruction::ConstructMaterials()''
• '''/g4sbs/targpres''': Sets target pressure. Applies to gas targets. Requires a value and a unit. ''Note: the current behavior of the code is that this command has no effect, because the densities of target materials are hard-coded in G4SBSDetectorConstruction::ConstructMaterials()''.
• '''/g4sbs/beamcur''': Beam current. Requires a value and a unit. Currently used in the normalization of events from a cross-section to an event rate.
• '''/g4sbs/runtime''': Run duration Requires a value and a unit. Used to normalize events from cross section --> rate --> number of counts. Unit must be a valid time unit defined in G4SystemOfUnits.hh ("hour" "day" "year" do NOT work).
• '''/g4sbs/rasterx''': Define horizontal raster size. Requires a value and a unit.
• '''/g4sbs/rastery''': Define vertical raster size. Requires a value and a unit.
• '''/g4sbs/beamE''': Define beam energy. Requires a value and a unit.
• '''/g4sbs/bbang''': Define BigBite/electron arm angle (also applies to ECAL in the GEP configuration). Requires a value and a unit.
• '''/g4sbs/bbdist''': Define BigBite/electron arm distance from target. Requires a value and a unit. ** In experiments using BigBite, this defines the distance from the target center (origin of global coordinates) to the front face of the magnet yoke. ** In the GEP experiment using ECAL, this defines the distance from the target center to the '''''front''''' of the lead-glass blocks of ECAL. The front of the lead-glass is therefore 40 cm closer to the target than the value defined using this command.
• '''/g4sbs/sbsang''': Define SBS angle. Requires a value and a unit.
• '''/g4sbs/hcaldist''': Distance from the target center to the ''front'' surface of HCAL. Requires value and unit.
• '''/g4sbs/hcalvoffset''': Vertical displacement of the center of HCAL with respect to target vertical center. Requires value and unit.
• '''/g4sbs/48D48dist''': Distance from target center to front face of SBS magnet yoke. Requires value and unit.
• '''/g4sbs/gemres''': Set GEM coordinate resolution globally for all planes (1\sigma). Local x and y coordinates of hits in GEM detectors are subject to Gaussian smearing with this \sigma. Requires value and unit. ''Note: default value is \sigma = 70 \mum''
• '''/g4sbs/cerdist''': Defines distance from front GEM of BigBite to entry window of BigBite Cherenkov. Requires value and unit. ''Note: default value is 7 cm''
• '''/g4sbs/cerdepth''': Defines depth of BigBite Cherenkov gas. Requires value and unit. ''Note: default value is 92 cm, defined by planned GRINCH depth.''
• '''/g4sbs/gemsep''': GEM separation from front to back set (for BigBite GEMs). Requires value and unit. ''Note: Default value is cerdepth + 10 cm''. This is the z distance between the midpoints of the two sets of GEMs (before and after GRINCH). GEM planes within each set are separated by 5 cm in z.
• '''/g4sbs/bbcaldist''': Distance from BigBite front GEM to BigBite calorimeter surface (preshower). Requires value and unit. ''Note: Default value is 20 cm + cerdepth''.
• '''/g4sbs/thmin''': Minimum polar angle for electron generation. Requires value and unit.
• '''/g4sbs/thmax''': Maximum polar angle for electron generation. Requires value and unit. ** For all generators with scattered electrons (elastic, inelastic, flat, dis, sidis), ''thmin'' and ''thmax'' refer to the ''electron'' polar angle generation. For the ''beam'' and ''wiser'' generators, these are ignored. For the ''gun'' generator, ''thmin'' and ''thmax'' refer to the polar angles of the generated particle, regardless of type.
• '''/g4sbs/phmin''': Minimum azimuthal angle for electron generation. Requires value and unit.
• '''/g4sbs/phmax''': Maximum azimuthal angle for electron generation. Requires value and unit. ** For all generators with scattered electrons (elastic, inelastic, flat, dis, sidis), ''phmin'' and ''phmax'' refer to the ''electron'' azimuthal angle generation. For the ''beam'' and ''wiser'' generators, these are ignored. For the ''gun'' generator, ''phmin'' and ''phmax'' refer to the azimuthal angles of the generated particle, regardless of type.
• '''/g4sbs/hthmin''': Minimum hadron generation polar angle. Requires value and unit.
• '''/g4sbs/hthmax''': Maximum hadron generation polar angle. Requires value and unit.
• '''/g4sbs/hphmin''': Minimum hadron generation azimuthal angle. Requires value and unit.
• '''/g4sbs/hphmax''': Maximum hadron generation azimuthal angle. Requires value and unit. ** Note: hadron angle generation limits apply only to the ''sidis'' and ''wiser'' generators, and are otherwise ignored.
• '''/g4sbs/ehmin''': Minimum generated hadron energy. Requires value and unit.
• '''/g4sbs/ehmax''': Maximum generated hadron energy. Requires value and unit. ** Note: hadron energy generation limits apply only to the ''sidis'' and ''wiser'' generators, and are otherwise ignored.
• '''/g4sbs/eemin''': Minimum generated electron energy. Requires value and unit.
• '''/g4sbs/eemax''': Maximum generated electron energy. Requires value and unit. ** Note: "electron" energy generation limits apply only to the ''sidis'' and ''gun'' generators, and are otherwise ignored. When used with the ''gun'' generator, these limits refer to the energy of the generated particle, regardless of particle ID. ** '''Note: For now, the energy generation limits for both hadrons and electrons refer to the ''total'' energy of particles, not their kinetic energy. Therefore, the minimum generated energy must be greater than the mass of the particle type being generated. Perhaps this should be changed to refer to the particle kinetic energy.'''
• '''/g4sbs/richdist''': Distance from the target center to the RICH entry window. Requires value and unit.
• '''/g4sbs/sbsmagfield''': Defines SBS uniform magnetic field value. Requires value and unit. Can be positive or negative. Should be invoked '''''before''''' ''/g4sbs/48d48field''.
• '''/g4sbs/scalebbfield''': Defines an overall scale factor which is applied to BigBite magnetic field value. Expects one dimensionless double argument.
• '''/g4sbs/scalesbsfield''': Defines an overall scale factor which is applied to the SBS magnetic field value. Expects one dimensionless double argument.
• '''/g4sbs/sbsclampopt''': Flag controlling SBS field clamp geometry. Expects integer argument. Valid choices are: ** '''0''': No field clamps for SBS. ** '''1''': Field clamps for BigBite experiments (default). ''Note: The geometry represented by this option is obsolete and does not reflect any current or planned experiment design.'' ** '''2''': Field clamps for GEP experiment. ''Note: The geometry represented by this option is based on the final field clamp design for the GEP (and GMN??) experiments.''
• '''/g4sbs/uselead''': Flag controlling lead shielding of the beamline and SBS. Expects integer argument. Valid choices are ** '''0''': no extra lead shielding on downstream beamline or in front of SBS apertures. ** '''1''': Yes--builds lead shielding of the downstream beamline and/or SBS apertures. Geometry is experiment-dependent.
• '''/g4sbs/treeflag''': Flag controlling filling of the ROOT tree. Requires integer argument. Valid choices are: ** '''0''': Keep all events, regardless of detector status. '''''This option is very expensive disk-wise for beam background simulations in which the vast majority of events have no hits in sensitive volumes.''''' ** '''1''' (recommended in most cases): Keep only events with hits in sensitive volumes.
• '''/g4sbs/keepcalparticles''': Flag to keep calorimeter-specific particle information in the ROOT tree for sensitive volumes defined with "calorimeter" sensitivity. Requires string and boolean arguments. ** The first argument is a sensitive detector name. If this argument does not correspond to the name of a sensitive detector with "calorimeter" sensitivity type, then the command has no effect. ** The second argument is a boolean. If true, calorimeter-specific particle history information will be kept (see ROOT tree documentation below). Defaults to false.
• '''/g4sbs/keephistory''': Flag to keep generic particle history information in the ROOT tree for sensitive volumes with arbitrary sensitivity. See ROOT tree documentation below for details). Requires string and boolean arguments. ** The first argument is a sensitive detector name. If this argument does not correspond to the name of a sensitive detector that exists in the simulation, the command has no effect. ** The second argument is a boolean, which if true, causes the ROOT tree branches containing the generic particle history info to be created and also causes this information to be written to the ROOT tree for each event. Defaults to false.
• '''/g4sbs/steplimit''': Flag to limit step length to zero for particles entering a given sensitive volume. Makes detectors effectively total absorbers that kill particles entering them and record their information using the calorimeter "hit" classes. This command is only implemented for a subset of sensitive detectors defined in the simulation, limited to calorimeters and/or scintillation detectors that produce large numbers of secondaries. Useful for heavy, showering detectors to speed up the simulation when full details of the response aren't needed. Requires string and (optional) boolean arguments: ** The first argument must be either the name of an existing sensitive detector in the list of implemented detectors OR the name of a mother volume enclosing such detectors. The current list of sensitive detectors for which this option is implemented: *** '''Harm/HCalScint''': Scintillator plates of HCAL. Turning on the step limiter prevents production of large number of optical photons which then have to be tracked. *** '''lHCalo''': Mother box entirely containing HCAL. Step-limiting this volume makes HCAL a total absorber with "calorimeter" sensitivity (sensitive detector name = "Harm/HCAL_box") that kills and records all particles entering it. *** '''bbcal_mother_log''': Mother box entirely containing the BigBite shower, preshower and timing hodoscope. Step-limiting this volume makes the BigBite calorimeter a total absorber with "calorimeter" sensitivity (sensitive detector name = "Earm/BBCal"). *** '''Earm/BBSHTF1''': Lead-glass of the BigBite calorimeter (shower layer) *** '''Earm/BBPSTF1''': Lead-glass of the BigBite calorimeter (pre-shower layer) *** '''earm_mother_log''': Mother volume containing ECAL and CDET (only applicable in GEP). Makes "earm_mother_log" a sensitive "calorimeter" volume with sensitive detector name = "Earm/ECAL_box". ** The second (optional) argument is boolean (true/false) to toggle this option for a given volume. If the volume name is not in the list of supported detectors above, the command has no effect
• '''/g4sbs/useckov''': Toggle optical photon production via the Cerenkov process on/off in G4SBSPhysicsList (and therefore for the entire setup). Takes one (optional) boolean argument. The Cerenkov process is ON by default for all detectors with a refractive index defined in their material properties tables. '''''Note: Must be invoked in the pre-initialization phase (see below) to have an effect'''''
• '''/g4sbs/usescint''': Toggle optical photon production via the Scintillation process on/off in G4SBSPhysicsList (and therefore for the entire setup). Takes one (optional) boolean argument. The Scintillation process is ON by default for all detectors with scintillation properties correctly defined in their material properties tables. '''''Note: Must be invoked in the pre-initialization phase (see below) to have an effect'''''
• '''/g4sbs/fluxcalc''': Expects Boolean argument. When enabled, computes particle flux as a function of angles and energy for a given target, by defining a spherical sensitive volume with the step limiter turned ON and "kCAL" sensitivity.
• '''/g4sbs/gunpol''': Sets particle polarization orientation vector for "gun" generator. Requires three double arguments, which define the three-vector components (x,y,z) of the particle polarization in "TRANSPORT" coordinates for the SBS. The components are automatically converted to a unit vector internally to the code.
• '''/g4sbs/segmentTF1''': Integer argument. Longitudinally segments the TF1 lead-glass for ECAL and/or C16 into ''N'' segments for implementation of the thermal annealing model. '''''Must be invoked in the pre-initialization phase to have the intended effect!''''' ** '''0''': Setting to zero turns OFF longitudinal segmentation, and all lead-glass modules have their optical properties defined according to the baseline scenario with no radiation damage and room temperature. ** '''1-N''': Divides each lead-glass module into ''N'' segments, optical properties are computed assuming a linear temperature profile from front to back. Implements thermal annealing model for equilibrium transparency under expected radiation dose rate conditions for GEP/C16 experiments.
• '''/g4sbs/segthickTF1''': Requires a double and a unit. Defines longitudinal segment thickness for TF1 lead-glass in ECAL/C16 simulations. Default value is 4 cm. '''''Must be invoked in the pre-initialization phase to have the intended effect'''''.
• '''/g4sbs/doserate''': Requires a double argument. Defines an overall scale factor for the radiation dose rate in lead-glass for ECAL/C16 simulations. For the ECAL (C16) simulation, the scale factor applies to "reference" dose rate calculations that are hard-coded in ''g4sbs''. This factor enters the calculation of the equilibrium transparency under thermal annealing and radiation damage. '''''Must be invoked in the pre-initialization phase to have the intended effect'''''.

==="Pre-init" vs "Post-init" commands=== Most ''g4sbs'' commands can be invoked pre-initialization or post-initialization, with several exceptions:

• '''/g4sbs/usescint''' and '''/g4sbs/useckov''' ''must'' be invoked in the pre-initialization phase to have any effect. These commands may cause ''g4sbs'' to crash if invoked post-initialization.
• '''/g4sbs/segmentTF1''', '''/g4sbs/segthickTF1''' and '''/g4sbs/doserate''' ''must'' be invoked in the pre-initialization phase to have the intended effect, and may cause ''g4sbs'' to crash if invoked post-initialization
• '''/g4sbs/run''' can only be invoked in the post-initialization phase. May cause g4sbs to crash if invoked pre-initialization.

When running g4sbs in interactive mode, G4RunManager::Initialize() is invoked before passing control of the program to the user interface. Therefore all commands executed in an interactive g4sbs session are post-initialization commands. This means that it is presently not possible to disable Cherenkov and Scintillation processes in interactive sessions, which is undesirable. A fix that allows these processes to be toggled in interactive mode is in the works.

===Setting up the magnetic field===

This section describes proper procedures and command sequences to achieve the desired results when configuring the magnetic field in g4sbs. The magnetic field description in g4sbs is somewhat complicated by the need to optimize the program for speed. As detailed [https://twiki.cern.ch/twiki/bin/view/Geant4/Geant4PerformanceTips#DescribingField here], defining a global magnetic field when only small regions of the setup have significant magnetic field makes the tracking unnecessarily expensive, because tracking in a magnetic field costs the same number of CPU cycles whether the field is large or zero. Therefore, g4sbs is designed to treat different situations differently.

Several points are useful to keep in mind in approaching the g4sbs magnetic field definition:

*TOSCA field maps for the SBS magnet are not portable from one experiment configuration to the next; i.e., the TOSCA field map does not translate with the SBS magnet in angle or distance. This is because each experiment configuration involves a separate layout of active and passive magnetic shielding on the downstream beamline to protect the beam from the stray field of the SBS magnet, and these shielding elements do not translate/rotate with the magnet. Therefore, a separate field map is required for each configuration. *The physical region covered by the typical SBS TOSCA map is too large to easily implement as a ''local'' field, because it wholly or partially overlaps too many other logical volumes at the same level of the geometry hierarchy. Therefore, the use of SBS TOSCA maps necessitates the use of a global magnetic field. *The standard BigBite field map (http://hallaweb.jlab.org/12GeV/SuperBigBite/downloads/map_696A.dat), on the other hand, encompasses a small enough physical region that it can be confined to a logical volume enclosing the BigBite magnet and detectors without interfering with other logical volumes at the same level of the volume hierarchy. Therefore, it is possible to use the BigBite field map both globally and locally. *For configurations of SBS for which a final TOSCA map is not yet available, a reasonable first approximation is to use a uniform dipole field in the SBS magnet gap. This can be treated as a local field and combined with a local BigBite field. *Presently, the only experiment configuration with a more-or-less final TOSCA map available that can be used with g4sbs is the 12 GeV^2 setting of the GEP experiment, with SBS at 16.9 degrees and 1.6 meters from the target.

====Command sequences for typical magnetic field permutations====

• BigBite only: ** '''/g4sbs/bbfield 1''' ** '''/g4sbs/48d48field 0''' (optional since SBS uniform field is OFF by default).
• BigBite and SBS uniform field with a magnitude of 1.8 T: ** '''/g4sbs/bbfield 1''' ** '''/g4sbs/sbsmagfield 1.8 tesla''' ''Note: it is recommended, but not strictly required, to set the field value before turning on the SBS uniform field. The only ill effect of setting the field value after turning it on is that the diagnostic plots written to the root file will show the default field value of 1.4 T instead of the user's choice. The actual field used in the simulation will always be overridden by "/g4sbs/sbsmagfield"'' ** '''/g4sbs/48d48field 1'''
• SBS TOSCA field only: ** '''/g4sbs/tosfield /path/to/GEP_12map0_newheader.table'''
• SBS TOSCA field and BigBite field (''Note: To the extent that the BigBite and TOSCA field maps overlap in any region of the global coordinate space, the superposition principle is applied and the two fields as interpolated from the two maps will be vector-added at any point in the overlap region''): ** '''/g4sbs/bbfield 1 ** '''/g4sbs/tosfield /path/to/GEP_12map0_newheader.table'''

Any time "/g4sbs/tosfield" is invoked, g4sbs is forced to use a global magnetic field definition. In all other cases, the code is written so that local fields are used for SBS and BigBite, which makes the simulation noticeably faster.

====Links to field map files====

[http://hallaweb.jlab.org/12GeV/SuperBigBite/downloads/map_696A.dat BigBite] field map. [http://hallaweb.jlab.org/12GeV/SuperBigBite/downloads/GEP_12map0_newheader.table TOSCA map] for GEP Q^2 = 12 GeV^2

These files can be retrieved from the command line with e.g.

{|class="wikitable" style="background: #BFBFBF" |- | '''wget http://hallaweb.jlab.org/12GeV/SuperBigBite/downloads/map_696A.dat''' (for the BigBite field map) |- | '''wget http://hallaweb.jlab.org/12GeV/SuperBigBite/downloads/GEP_12map0_newheader.table''' (TOSCA map for GEP 12 GeV^2 configuration) |}

'''The BigBite field map must be located in the same directory as the g4sbs executable and have the name "map_696A.dat" to work correctly. This is because the file name is hard-coded.'''

'''New header format for SBS TOSCA map:'''

In the ''uconn_dev'' branch of g4sbs, the code that reads the TOSCA map file is modified to expect three rotation angles to be read in from the header, interpreted as \alpha_x, \alpha_y, \alpha_z. The rotation matrix for the magnetic field is then defined by applying these three rotations in the order ''xyz''; i.e.,

• First, rotate the field by \alpha_x about the original ''x'' axis. Positive angles are defined as '''''clockwise''''' rotations as viewed from the ''+x'' direction (in other words, if I am sitting at x = +\infty and looking in the ''-x'' direction, a positive \alpha_x corresponds to a ''clockwise'' rotation.
• Second, rotate the field by \alpha_y about the ''new y'' axis.
• Third, rotate the field by \alpha_z about the ''new z'' axis.

The new header format means that the code in ''uconn_dev'' cannot read the TOSCA maps with the old header format that only has one rotation angle. The only TOSCA map file at http://hallaweb.jlab.org/12GeV/SuperBigBite/downloads/ that is presently compatible with ''uconn_dev'' is '''''GEP_12map0_newheader.table'''''.

====Notes on field maps====

The SBS TOSCA map for the GEP 12 GeV^2 configuration uses trilinear interpolation of a uniform rectangular grid with a lattice spacing of 2.5 cm defined at 161 z points from -200\ cm \le z \le 200\ cm, and 121 x/y points from -150\ cm \le x,y \le 150\ cm. The +z axis of the SBS TOSCA map is opposite the direction of particle motion, and the origin of the field map is located at a distance of 221 cm from the target along the line making an angle of 16.9 degrees to beam right with respect to the beam direction.

The BigBite field map also uses trilinear interpolation on a 2 cm grid with (N_x, N_y, N_z)=(26, 96, 116), with (\Delta x, \Delta y, \Delta z)=(\pm 25\ cm, \pm 75\ cm, \pm 160\ cm). The BigBite field map has a "natural" orientation with the ''+z'' axis in the direction of particle motion, and its origin is always at a fixed position relative to the "mother" logical volume containing the BigBite magnet and detectors. Unlike the SBS TOSCA map, the BigBite field map is "portable" and moves with the BigBite spectrometer.

==Output ROOT file structure==

The output of ''g4sbs'' is a ROOT file containing metadata about the run, diagnostic plots of the magnetic field layout in Hall A, and a ROOT tree with the data from simulated events, including global event properties and data from individual detectors.

===Run metadata=== The run metadata is stored in an object of class "G4SBSRunData" which inherits from ROOT's "TObject". The object is always written to the file with the key/name "run_data". The information stored in this object includes:

• '''git repository info''': This includes the commit identifier (source code version) and commit message, as well as change tracking information.
• '''Geant4 version'''; version of the GEANT4 toolkit against which ''g4sbs'' was built
• '''ROOT version'''; version of the ROOT libraries against which ''g4sbs'' was built
• '''cmake version''': version of cmake used to build ''g4sbs''
• '''Time stamp''': includes the date and time of the simulation run and the name of the host machine on which the simulation was executed.
• Directory in which g4sbs was executed on the host machine
• '''N generated:''' Number of events generated: This is the actual number of primary events generated.
• '''N tried:''' Number of events "tried". This is the number of "attempted" event generations. For most of the event generators in ''g4sbs'', ''N tried = N generated''. In all cases, the simulated yield should be normalized to "N tried" to get the correct event rate, since the generated phase space volume includes kinematically forbidden regions of phase space. Here is the behavior for each currently available generator: ** ''elastic'': N tried = N generated ** ''inelastic'': Returns false if generated event not kinematically allowed. Ntried >= Ngenerated. ** ''flat'': N tried = N generated ** ''dis'': Returns false if generated event not kinematically allowed. Ntried >= Ngenerated. ** ''beam'': Always generates an event. Ntried = Ngenerated ** ''sidis'': Returns false if generated event not kinematically allowed. Ntried >= Ngenerated. ** ''wiser'': Always generates an event. Ntried = Ngenerated ** ''gun'': Always generates an event. Ntried = Ngenerated ** ''pythia6'': Always generates an event. Ntried = Ngenerated
• '''Experiment:''' Experiment type. Corresponds to valid experiment types chosen via ''/g4sbs/exp'' command.
• '''Generator:''' Event generator type. Corresponds to one of the valid event generators chosen via ''/g4sbs/kine'' command.
• '''Field maps:''' information about TOSCA field map file(s) used by the simulation (if any)
• '''Pre-Init Macro run:''' Contents of macro file containing commands executed prior to initialization (if any).
• '''Macro run:''' Contents of macro file containing commands executed after initialization (if any).
• '''External macros called:''' Contents of external macro files invoked by either of the pre-/post-initialization macros. ===Diagnostic Magnetic Field Plots=== All of the magnetic field plots are two-dimensional histograms showing the projection onto the ''xz'' plane at ''y = 0'' in the global coordinate system of the individual field components and the field magnitude: *'''field_x''' (type TH2F): x-component of the magnetic field (Tesla). *'''field_y''' (type TH2F): y-component of the magnetic field (Tesla). *'''field_z''' (type TH2F): z-component of the magnetic field (Tesla). *'''field''' (type TH2F): total magnitude of the magnetic field (Tesla).

===Sensitive Detector Overview=== There are presently four different sensitive detector "types" defined in ''g4sbs'': "GEM" (kGEM), "Calorimeter" (kCAL), "RICH" (kRICH), and "ECAL" (kECAL). These sensitive detector types are distinguished by what kinds of information are stored in their "hit" classes and what information is written to the ROOT tree for each event. When the experiment geometry is constructed, logical volumes defined as sensitive detectors are grouped according to unique sensitive detector names, that are typically hard-coded in the geometry construction routines. The naming convention for sensitive detectors is chosen such that all unique physical placements of one or more logical volume(s) corresponding to a set of detectors that function as a single logical unit have the same unique sensitive detector name. An example is the SBS front tracker, which consists of six unique physical placements of a single logical volume representing one layer of GEMs. These six GEM layers function together as a single tracking unit in the code. Moreover, the naming scheme adopted in the code attaches the prefix "Earm/" or "Harm/" to sensitive detectors belonging to the electron arm (BigBite or ECAL) or hadron arm (SBS) of an experiment. For each uniquely named sensitive detector in the ''g4sbs'' code, a corresponding set of branches is created in the ROOT tree, as described below. This means that different experiment configurations will result in different ROOT tree structures. For example, the output root trees from a simulation of the GEP experiment will not have the branches corresponding to the BigBite detectors, since they are not used by the experiment. This means that separate analysis macros need to be written to accommodate the different ROOT tree structures of the different experiments. This is easily done using ROOT's utility [https://root.cern.ch/doc/master/classTTree.html#ac4ceaf4ae0b87412acf94093043cc2de TTree::MakeClass()], which generates a skeleton analysis macro from the TTree.

All array-valued branches in the ''g4sbs'' ROOT tree (such as "hits" and "tracks") are in fact pointers to STL vectors, which are dynamically sized arrays. This practice avoids the pitfall of using the standard method of declaring simple array-valued tree branches using e.g.,

:'''int nhits;''' :'''Tree->Branch("nhits",&nhits, "nhits/I");''' :'''double hit_edep[1000];''' :'''Tree->Branch("edep",hit_edep,"edep[nhits]/D");'''

When array-valued branches are created using this "standard" method, TTree::MakeClass() computes the maximum array size using the maximum size of that particular array-valued branch occurring within an individual file and then declares a fixed-size array corresponding to the computed maximum array size as a data member in the automatically generated header file of the skeleton class. The standard method cannot accommodate all possible array sizes in a large TChain of many ROOT files when used to analyze a high-statistics simulation, and would therefore have to be regenerated using the entire TChain for every new analysis. On the other hand, with our method of replacing all array-valued branches with pointers to STL vectors, the array-valued tree branches are completely dynamically sized, and the header files generated using TTree::MakeClass() with a single ROOT tree from a single file can be used to analyze an arbitrarily large TChain without any loss of generality. Note, however, that the syntax for accessing these STL vectors in an analysis macro is somewhat clumsy.

Consider the following example of a loop over a chain of g4sbs root files, assuming that the class "g4sbs_tree" was created using TTree::MakeClass() to process the trees. Suppose I want to access the energy deposition of all the hits in the front tracker in a loop over all hits in all events. The correct syntax to access the STL vector-valued branches of the ''g4sbs_tree'' object is:

:'''TChain *C = new TChain("T");''' :'''C->Add( "g4sbs_job_number*.root" );''' :'''g4sbs_tree *T = new g4sbs_tree(C);''' :'''long nevent=0;''' :'''while ( T->GetEntry(nevent++) ){''' ::'''for( int hit=0; hitHarm_FT_hit_nhits; hit++ ){''' ::: '''double Edep = (*(T->Harm_FT_hit_edep))[hit];''' ::'''}''' :'''}'''

In this example, since '''T->Harm_FT_hit_edep''' accesses a data member of the class "g4sbs_tree" of type '''vector *'''; i.e., a ''pointer'' to vector, that pointer has to be dereferenced to access the underlying STL vector (i.e., dynamically sized array). The parentheses in this example are used to disambiguate the targets of the dereferencing operator and the array subscript operator.

The following is a list of sensitive detector names currently available in ''g4sbs'' with abbreviated descriptions of the purpose and relevant experiments in which they are used:

• '''Electron arm sensitive detectors''': ** '''BigBite GEMs:''' (experiments = GEn, GMn, SIDIS) *** '''Earm/BBGEM''' (type kGEM): BigBite GEM-based tracking detectors. Records energy deposition and coordinates in primary ionization region of GEM modules. ** '''BigBite GRINCH:''' (experiments = GEn, GMn, SIDIS) *** '''Earm/GRINCH''' (type kRICH): BigBite Gas Ring-Imaging Cherenkov Detector (GRINCH) PMTs. Records number of photoelectrons. ** '''BigBite Calorimeter:''' (experiments = GEn, GMn, SIDIS) *** '''Earm/BBCal''' (type kCAL): BigBite calorimeter mother volume. Only active when ''/g4sbs/steplimit bbcal_mother_log 1'' is invoked, which effectively turns a mother box enclosing the entire BigBite shower and preshower calorimeters (and timing hodoscope) into a total absorber of all particles that enter it, recording the properties of those particles at the time they enter the box. *** '''Earm/BBSHTF1''' (type kCAL): BigBite shower calorimeter lead-glass. Records total energy deposition in lead-glass. *** '''Earm/BBSH''' (type kECAL): BigBite shower calorimeter PMTs. Records number of photoelectrons ejected by the PMT photocathode. *** '''Earm/BBPSTF1''' (type kCAL): BigBite preshower calorimeter lead-glass. Records total energy deposition in lead-glass. *** '''Earm/BBPS''' (type kECAL): BigBite preshower calorimeter PMTs. Records number of photoelectrons ejected by the PMT photocathode. ** '''C16 Prototype:''' (experiments = C16) *** '''Earm/C16''' (type kECAL): C16 PMTs. records number of photoelectrons. *** '''Earm/C16TF1''' (type kCAL): C16 lead-glass. Records total energy deposition in lead-glass. ** '''ECAL/CDET:''' (experiment = GEP) *** '''Earm/ECAL_box''' (type kCAL): ECAL/CDet mother volume. Only active when ''/g4sbs/steplimit earm_mother_box 1'' is invoked, which effectively turns a mother box enclosing the entire electron arm of the GEP experiment (including ECAL and CDet) into a total absorber which stops and records the properties of all incident particles. *** '''Earm/ECalTF1''' (type kCAL): ECAL lead-glass. Records total energy deposition in lead-glass. *** '''Earm/ECAL''' (type kECAL): ECAL PMTs. records number of photoelectrons. *** '''Earm/CDET''' (type kECAL): Coordinate detector maPMTs. Records number of photoelectrons. *** '''Earm/CDET_Scint''' (type kCAL): Coordinate detector scintillator strips. Records energy deposition in scintillator strips of coordinate detector.
• '''Hadron arm sensitive detectors:''' ** '''HCAL''' (experiments = ALL): *** '''Harm/HCalScint''' (type kCAL): HCAL scintillator. Records energy deposition in HCAL scintillator tiles. *** '''Harm/HCal''' (type kECAL): HCAL PMTs. Records number of photoelectrons in HCAL PMT photocathodes. *** '''Harm/HCAL_box''' (type kCAL): mother box enclosing entire HCAL volume, only active when ''/g4sbs/steplimit lHCalo 1'' is invoked, which turns the HCAL mother box into a total absorber that stops and records the properties of all entering particles. ** '''GEM trackers for GEP''' (experiment = GEP): *** '''Harm/FT''' (type kGEM): SBS front-tracker GEMs. Records energy deposition in primary ionization region and coordinates. *** '''Harm/FPP1''' (type kGEM): SBS front polarimeter GEMs, located between first and second CH2 analyzers. Records energy deposition in primary ionization region and coordinates. *** '''Harm/FPP2''' (type kGEM): SBS back polarimeter GEMs, located between second CH2 analyzer and HCAL. Records energy deposition in primary ionization region and coordinates. ** '''GEM tracker for SIDIS''' (experiment = SIDIS): *** '''Harm/SBSGEM''' (type = kGEM): large-area GEM-based tracker for SIDIS, based on UVA polarimeter GEM trackers, located in front of SBS RICH. Records energy deposition in primary ionization region and coordinates. ** '''RICH''' (experiments = SIDIS): *** '''Harm/RICH''' (type kRICH): RICH PMTs. Records number of photoelectrons.

====Sensitive Detector Maps====

All four sensitive detector classes in ''g4sbs'' have a public data member "detmap" of type "G4SBSDetMap". The G4SBSDetMap is a simple data structure that uses [http://www.cplusplus.com/reference/map/map/ STL maps] to keep track of useful information corresponding to the physical location of individual detector channels. It is up to the user to meaningfully populate the detector map information (and document the meaning of the information contained therein) when creating a new sensitive detector in ''g4sbs''. It is intended that the ''key'' value in each ''map<key_type,value_type>'' be a unique integer identifier corresponding to each unique physical placement/copy of a sensitive detector's logical volume. The maps should be filled in the source code that constructs the geometry. Presently, the information stored in the "detmap" for each sensitive detector instance is limited to the following items. Each can be defined in any way the user sees fit (or not at all), but the names are meant to be suggestive of something like the "usual" definitions:

• '''G4String SDname''': Sensitive detector name. Name of the sensitive detector of which this detmap is a data member. Presently it is initialized by the sensitive detector constructor and never used.
• '''G4int depth''': "Depth" parameter. This parameter defines how many levels up the logical volume hierarchy the relevant "copy number" information is located. This parameter was introduced to accommodate detectors in which the sensitive volume is placed once inside a mother logical volume, of which many copies are then placed. For example, in the GEP ECAL, the lead-glass block is a sensitive volume of type kCAL, which is placed inside a mother volume of air called a "module", which also contains a highly reflective Mylar wrapping for optical isolation of the blocks. The actual sensitive volume (lead-glass) is placed only once inside the "module", and the "module" is then placed many times. It is the copy number of each physical placement of "module" that is of interest for mapping individual lead-glass blocks to physical locations, and therefore the ECAL lead-glass sensitive detector instance has ''detmap.depth = 1'', since it is the physical placement of the immediate ''mother'' volume of the lead-glass that contains the relevant copy ID information. In the G4SBSCalSD::ProcessHits() routine, the information is then accessed and copied to the relevant "hit" array via '''hit->SetCell( hist->GetVolume( detmap.depth )->GetCopyNo() );''', where ''hist->GetVolume( detmap.depth )'' returns a pointer to the physical volume in which the hit occurred at ''depth'' levels up the logical volume hierarchy relative to the sensitive volume itself. Presently, the code only allows for a single ''depth'' parameter to be defined for each instance of a sensitive detector, meaning that it cannot correctly handle arbitrarily complicated geometry hierarchies. Code for new detectors should thus be written with this limitation in mind if the user intends to use the detmap to keep track of physical detector locations.
• '''map<G4int,G4int> Plane''': Mapping between copy number and "plane number". "Plane" typically refers to some kind of stacking order along the direction of particle motion, and has a natural definition for planar drift chambers, GEM chambers, or any other detector with "longitudinal" segmentation along the direction of particle motion.
• '''map<G4int,G4int> Wire''': Mapping between copy number and "wire number". Natural to define for wire chambers.
• '''map<G4int,G4int> Row''': Mapping between copy number and "row number". Natural for calorimeters and other "array" or "matrix" type detectors with transverse segmentation, with or without longitudinal segmentation.
• '''map<G4int,G4int> Col''': Mapping between copy number and "column number". Natural for calorimeters and other "array" or "matrix" type detectors with transverse segmentation and with or without longitudinal segmentation.
• '''map<G4int,G4ThreeVector> LocalCoord''': Mapping between copy number and a '''G4ThreeVector''' object that defines the "local" coordinates of the center/origin of the sensitive volume with respect to some mother volume in a convenient reference frame. For example: ** In '''''ECAL''''', the local "x" and "y" coordinates are defined as the horizontal and vertical coordinates of the center of each cell at the surface of ECAL, relative to the center of the mother box containing ECAL, which gets placed in Hall A. ** In the '''''RICH''''' and '''''GRINCH''''' detectors, which both use planar matrices of PMTs, the "local" X and Y coordinates of the PMT photocathodes are relative to the planar surfaces of the respective PMT matrices, which are placed inside mother boxes containing the entire RICH/GRINCH detectors, which in turn are placed appropriately within the SBS/BigBite detector packages.

The detmap classes will be expanded and improved as a result of near-future efforts to move toward "full digitization" of all detectors; i.e., to implement in a quasi-realistic way the total readout chain from energy deposition/photon detection --> voltage as a function of time --> digitized ADC and/or TDC and/or FADC values. ====Coming soon: Documentation of individual sensitive detector maps and local coordinate systems====

===ROOT Tree Structure=== The output ROOT Tree is the main result of the simulation, and contains global properties of each event as well as the individual detector responses. The tree is always written to the ROOT file with the name/identifier "T".

===="ev" data structure==== This data structure contains global properties of the event. ('''''Note: count, rate, solid angle, sigma and other variables in this data structure have different definitions, meanings and/or units for each generator, and are NOT vetted or checked for correctness or meaningfulness across all generators. Interpret with care!'''''). Contains global properties of the event:

• '''count/D:''' Projected event yield. Product of event rate and run duration. Event rate is determined by the product of the calculated differential cross section, the luminosity, and the phase space generation volume divided by the total number of generated events, while run duration is defined via ''/g4sbs/runtime''.
• '''rate/D:''' Projected event rate in Hz. Product of differential cross section, luminosity and phase space generation volume, divided by total number of generated events.
• '''solang/D:''' phase space generation volume divided by number of generated events.
• '''sigma/D:''' differential cross section in \frac{d\sigma}{d\Omega_e} in cm^2/sr. ** For ''DIS'' and ''inelastic'' generators, the cross sections are actually \Delta E'_e \frac{d^2\sigma}{d\Omega_e dE'_e}, where \Delta E'_e is the energy interval for generation of the scattered electron's energy. ** For the ''SIDIS'' generator, ''sigma'' is actually \frac{d\sigma}{d\Omega_e d\Omega_h dE'_e dE'_h} in units of \frac{cm^2}{GeV^2 \times sr^2}
• '''W2/D:''' Invariant mass squared of virtual photon-nucleon system. Units are GeV^2
• '''xbj/D:''' Bjorken ''x'' variable according to standard definition.
• '''Q2/D:''' Invariant four-momentum transfer squared from electron to target, in GeV^2
• '''th/D:''' Polar angle of scattered electron (radians)
• '''ph/D:''' azimuthal angle of scattered electron (radians)
• '''Aperp/D:''' Perpendicular asymmetry. Defined in the context of elastic or quasi-elastic electron nucleon scattering from a polarized target, this is the beam-target double-spin asymmetry for the component of the target polarization parallel to the electron scattering plane but '''''perpendicular''''' to the momentum transfer direction.
• '''Apar/D:''' Parallel asymmetry: Defined in the context of elastic or quasi-elastic electron nucleon scattering from a polarized target, this is the beam-target double-spin asymmetry for the component of the target polarization parallel to the electron scattering plane and '''''parallel''''' to the momentum transfer direction. *'''Pt/D:''' Transverse component of transferred polarization. Only meaningful in the context of elastic or quasi-elastic ep or en scattering. *'''Pl/D:''' Longitudinal component of transferred polarization. Only meaningful in the context of elastic or quasi-elastic ep or en scattering *'''vx/D:''' x-coordinate of primary particle generation vertex in ''meters''. *'''vy/D:''' y-coordinate of primary particle generation vertex in ''meters''. *'''vz/D:''' z-coordinate of primary particle generation vertex in ''meters''. *'''ep/D:''' Initial momentum of generated primary final-state electron in GeV. For ''gun'' generator, this is the generated initial momentum of the primary particle, regardless of type. *'''np/D:''' Initial momentum of generated primary final-state nucleon in GeV. For ''sidis'' and ''wiser'' generators, this is the initial momentum of the generated primary final-state hadron. *'''epx/D:''' x-component of final-state electron momentum in GeV. *'''epy/D:''' y-component of final-state electron momentum in GeV. *'''epz/D:''' z-component of final-state electron momentum in GeV. *'''npx/D:''' x-component of final-state nucleon/hadron momentum in GeV. *'''npy/D:''' y-component of final-state nucleon/hadron momentum in GeV. *'''npz/D:''' z-component of final-state nucleon/hadron momentum in GeV. *'''nth/D:''' Polar angle of generated nucleon/hadron in radians (if applicable). *'''nph/D:''' azimuthal angle of generated nucleon/hadron in radians (if applicable). *'''pmperp/D:''' Missing perpendicular momentum in GeV (only meaningful in the context of quasi-elastic and/or inelastic generators) *'''pmpar/D:''' Missing parallel momentum in GeV (only meaningful in the context of quasi-elastic and/or inelastic generators) *'''pmparsm/D:''' "Smeared" missing parallel momentum in GeV, where the smearing is due to time-of-flight resolution (only meaningful in the context of quasi-elastic and/or inelastic event generators). *'''z/D:''' Fraction of virtual photon energy carried by observed hadron. Only meaningful for SIDIS generator. *'''phperp/D:''' Hadron transverse momentum in GeV. Only meaningful for SIDIS generator. *'''phih/D:''' Azimuthal angle between hadron production plane and lepton scattering plane in radians. Defined according to the "Trento convention". Only meaningful for SIDIS generator. *'''MX/D:''' Missing mass of unobserved final-state hadrons in GeV. Only meaningful for SIDIS generator. *'''Sx/D:''' x-component of initial particle polarization in fixed SBS TRANSPORT coordinates. Only meaningful for particle gun generator. *'''Sy/D:''' y-component of initial particle polarization in fixed SBS TRANSPORT coordinates. Only meaningful for particle gun generator. *'''Sz/D:''' z-component of initial particle polarization in fixed SBS TRANSPORT coordinates. Only meaningful for particle gun generator. *'''nucl/I:''' Initial (struck) nucleon type: 1 = proton, 0 = neutron. Meaningful for nuclear targets. *'''fnucl/I:''' Final-state (detected) nucleon type: 1 = proton, 0 = neutron. Meaningful for nuclear targets. *'''hadr/I:''' Final-state hadron type (meaningful for SIDIS generator): ** \pm 1 = \pi^\pm ** 0 = \pi^0 ** \pm 2 = K^\pm ** +3 = p ** -3 = \bar{p} *'''earmaccept/I:''' flag indicating event passed acceptance criteria for detection in electron arm. Not currently implemented in a meaningful way across experiments/generators. *'''harmaccept/I:''' flag indicating event passed acceptance criteria for detection in hadron arm. Not currently implemented in a meaningful way across experiments/generators.

===="gen" data structure==== Contains some global experiment parameters on an event-by-event basis:

• '''thbb/D:''' Central angle of electron arm (BigBite or ECAL) in radians. ''Assumed to be on beam left''.
• '''thsbs/D:''' Central angle of hadron arm (SBS) in radians. ''Assumed to be on beam right''.
• '''dbb/D:''' Distance from target center to front surface of BigBite magnet yoke (GEn/GMn/SIDIS) or ECAL lead-glass (GEp), in meters.
• '''dsbs/D:''' Distance from target center to front surface of SBS magnet yoke, in meters.
• '''dhcal/D:''' Distance from target center to front surface of HCAL, in meters.
• '''voffhcal/D:''' Vertical offset of HCAL center relative to beamline, in meters.
• '''drich/D:''' Distance from target center to RICH entry window, in meters. Only applicable to "SIDIS" configuration.
• '''dsbstrkr/D:''' Distance from target center to SBS GEM tracker focal plane in meters. Only applicable to "SIDIS" configuration.
• '''Ebeam/D:''' Beam energy in GeV. ====Sensitive detector tree branches====

The detector response information is written to the ROOT tree in the form of branches containing "hit" arrays and, depending on the sensitive detector type, certain auxiliary information about particle tracks depositing energy in sensitive detectors. The naming convention for the hit array branches in the ROOT tree is always '''''"SDname.hit.variable"''''', where ''SDname'' is the full path name of the sensitive detector (with all "/"'s replaced by "."'s; i.e., the first polarimeter GEMS, which have the name "Harm/FPP1" in the code, would have tree branches prefixed with "Harm.FPP1") and ''variable'' is the name of the variable stored in the branch. The branches specific to each sensitive detector type are described below: =====GEM sensitive detector branches=====

• '''GEM hit branches:''' These are the branches containing the arrays of all GEM hits. In GEANT4, each "hit" is actually a unique tracking step of an individual particle that deposits energy in a sensitive volume. In G4SBSEventAction::EndOfEventAction(), all tracking steps by the same particle in a GEM layer are grouped into a single ''logical hit'' and averaged before writing to the ROOT tree, in order to avoid double-counting of individual particles. In this way, one particle depositing energy in a GEM = one "hit" in the ROOT tree. ** '''SDname.hit.nhits''' (type int): Number of hits in the array for all sensitive volumes of type kGEM with name SDname. Equals the array size for all of the hit array variables. ** '''SDname.hit.plane''' (type vector *): Plane index of hit. Starts at 1. ** '''SDname.hit.strip''' (type vector *): Strip index of hit. Not currently used. ** '''SDname.hit.x''' (type vector *): "Smeared" x-coordinate of hit in ''meters'', expressed in local spectrometer TRANSPORT coordinates (+x along the dispersive direction in the direction of increasing momentum (down), +y along the non-dispersive direction and +z along the direction of particle motion, such that ''xyz'' is right-handed, Cartesian). '''Note: "true" hit coordinates are defined as the energy deposition-weighted average coordinates of all tracking steps belonging to the same unique particle track depositing energy in the primary ionization region of the GEM layer. "Smeared" coordinates are equal to true coordinates plus a random measurement error that is Gaussian-distributed with a mean of zero and \sigma = 70 \mum''' ** '''SDname.hit.y''' (type vector *): "Smeared" y-coordinate of hit in ''meters'', expressed in local spectrometer TRANSPORT coordinates. ** '''SDname.hit.z''' (type vector *): "True" z-coordinate of hit in ''meters'', expressed in local spectrometer TRANSPORT coordinates (the ''z = 0'' plane is defined differently and arbitrarily for each grouping of GEM layers into a logical tracking unit in the simulation, but is typically a plane located a few ''cm'' upstream of the first GEM layer in a tracker. See code for details) ** '''SDname.hit.polx''' (type vector *): x-component of the polarization of the particle that produced this hit, if applicable, in TRANSPORT coordinates. ** '''SDname.hit.poly''' (type vector *): y-component of the polarization of the particle that produced this hit, if applicable, in TRANSPORT coordinates. ** '''SDname.hit.polz''' (type vector *): z-component of the polarization of the particle that produced this hit, if applicable, in TRANSPORT coordinates. ** '''SDname.hit.t''' (type vector *): Average global time since the start of the event of this hit, in ''ns''. ** '''SDname.hit.trms''' (type vector *): RMS deviation from the mean of hit times (meaningful only if multiple tracking steps are averaged in this hit), in ''ns''. ** '''SDname.hit.tmin''' (type vector *): Global time since the start of the event of first tracking step in this hit, in ''ns''. ** '''SDname.hit.tmax''' (type vector *): Global time since the start of the event of last tracking step in this hit, in ''ns''. ** '''SDname.hit.tx''' (type vector *): "True" x-coordinate in ''meters'' of the track that caused this hit, in TRANSPORT coordinates. ** '''SDname.hit.ty''' (type vector *): "True" y-coordinate in ''meters'' of the track that caused this hit, in TRANSPORT coordinates. ** '''SDname.hit.txp''' (type vector *): ''dx/dz'' of the track that caused this hit, in TRANSPORT coordinates, averaged over all tracking steps in the GEM layer. ** '''SDname.hit.typ''' (type vector *): ''dy/dz'' of the track that caused this hit, in TRANSPORT coordinates, averaged over all tracking steps in the GEM layer. ** '''SDname.hit.trid''' (type vector *): GEANT4 global track ID number of track that caused this hit. ** '''SDname.hit.mid''' (type vector *): GEANT4 global track ID number of mother particle of track that caused this hit. ** '''SDname.hit.pid''' (type vector *): GEANT4 particle ID code (according to PDG particle numbering scheme) of particle that caused this hit. ** '''SDname.hit.vx''' (type vector *): Global ''x''-coordinate in ''meters'' of vertex where the particle responsible for this hit was created. ** '''SDname.hit.vy''' (type vector *): Global ''y''-coordinate in ''meters'' of vertex where the particle responsible for this hit was created. ** '''SDname.hit.vz''' (type vector *): Global ''z''-coordinate in ''meters'' of vertex where the particle responsible for this hit was created. ** '''SDname.hit.p''' (type vector *): Momentum (GeV) of the particle prior to the first tracking step in which it deposited energy in the GEM. ** '''SDname.hit.edep''' (type vector *) Total energy deposited (GeV) by the particle in this GEM hit; equals the sum of energy depositions over all tracking steps of the particle in this GEM layer. ** '''SDname.hit.beta''' (type vector *) ''v/c'' of the particle responsible for this hit prior to the first tracking step in which it deposited energy in the GEM.
• '''GEM "Track" branches''': Each GEM tracker functions as a logical tracking unit; each GEM plane measures both an ''x'' coordinate and a ''y'' coordinate. In all SBS experiments, the GEM trackers are located in nominally field-free regions, such that particle tracks of sufficiently high energy can be assumed to move in straight lines. G4SBSEventAction::EndOfEventAction() creates "Track" information for each set of GEM trackers by fitting straight lines to the coordinates of hits created by the same particle in three or more GEM layers organized as a part of a "tracker". While these track arrays do not represent the realistic expected performance of pattern recognition and track reconstruction algorithms, they serve as a useful benchmark for testing of tracking algorithms, and are also useful for providing estimates of the resolution of track parameters and reconstructed kinematic quantities such as scattering angles, interaction vertex coordinates, and charged-particle momenta. The track branches are named according to "SDname.Track.variable" and are described below: ** '''SDname.Track.ntracks''' (type int): Number of unique particle tracks causing hits in three or more GEM layers in a single logical tracking unit. Equal to the array size for all array variables starting with "SDname.Track". ** '''SDname.Track.TID''' (type vector *): GEANT4 global track ID number of this track. ** '''SDname.Track.PID''' (type vector *): GEANT4 particle ID code (according to PDG particle numbering scheme). ** '''SDname.Track.MID''' (type vector *): GEANT4 global track ID of the mother particle of this track (MID==0 indicates that this track was made by a primary particle). ** '''SDname.Track.NumHits''' (type vector *): Number of hits included in track. ** '''SDname.Track.NumPlanes''' (type vector *): Number of planes included in track. Identical to NumHits since all tracking steps by the same particle in a GEM layer are grouped into a single logical hit. ** '''SDname.Track.NDF''' (type vector *): Degrees of freedom for the straight-line fit to this track. NDF = 2N_{planes} - 4 since each plane measures both an ''x'' and a ''y'' coordinate. ** '''SDname.Track.Chi2fit''' (type vector *): \chi^2 of the straight-line fit to the ''smeared'' hit coordinates. ** '''SDname.Track.Chi2true''' (type vector *): \chi^2 of the straight-line fit to the "true" hit coordinates. '''''Note: Since real tracks in GEANT4 are not perfectly straight lines, but are modified by multiple-scattering effects, even the straight-line fit to "true" hit coordinates is not perfect.''''' ** '''SDname.Track.X''' (type vector *): ''x''-coordinate of the straight-line track fitted to the "true" hit positions in ''meters'', projected to the ''z = 0'' plane, in local spectrometer TRANSPORT coordinates. ** '''SDname.Track.Y''' (type vector *): ''y''-coordinate of the straight-line track fitted to the "true" hit positions in ''meters'', projected to the ''z = 0'' plane, in local spectrometer TRANSPORT coordinates. ** '''SDname.Track.Xp''' (type vector *): ''dx/dz'' of straight-line track fitted to the "true" hit positions, in TRANSPORT coordinates. ** '''SDname.Track.Yp''' (type vector *): ''dy/dz'' of straight-line track fitted to the "true" hit positions, in TRANSPORT coordinates. ** '''SDname.Track.T''' (type vector *): Global time since the start of the event, in ''ns'', when the "true" track crosses the ''z = 0'' plane. This is computed as an average of global times of hits on the track, corrected for particle time-of-flight from the ''z=0'' plane to the ''z'' location of the plane where the hit occurred: t_{fp}^{(i)} = t_{hit}^{(i)} - \frac{z_{hit}^{(i)}}{\beta c} \sqrt{1+\left(\frac{dx}{dz}\right)^2+\left(\frac{dy}{dz}\right)^2}, ** '''SDname.Track.P''' (type vector *): Track "true" momentum (GeV), defined as the track momentum averaged over all hits on the track, and where the momentum of each "hit" is the true particle momentum prior to the first tracking step in which it deposits energy in the GEM layer. ** '''SDname.Track.Sx''' (type vector *): ''x''-component of particle polarization in TRANSPORT coordinates. Applicable only to primary particles produced by the elastic and gun generators in the case where the initial polarization of these primary particles is assigned and then tracked through the magnetic field. ** '''SDname.Track.Sy''' (type vector *): ''y''-component of particle polarization in TRANSPORT coordinates. ** '''SDname.Track.Sz''' (type vector *): ''z''-component of particle polarization in TRANSPORT coordinates. ** '''SDname.Track.Xfit''' (type vector *): ''x''-coordinate in ''meters'' of the straight-line track fitted to the "smeared" hit positions, projected to ''z = 0'', in TRANSPORT coordinates. ** '''SDname.Track.Yfit''' (type vector *): ''y''-coordinate in ''meters'' of the straight-line track fitted to the "smeared" hit positions, projected to ''z = 0'', in TRANSPORT coordinates. ** '''SDname.Track.Xpfit''' (type vector *): ''dx/dz'' of the straight-line track fitted to "smeared" hit positions, in TRANSPORT coordinates. ** '''SDname.Track.Ypfit''' (type vector *): ''dy/dz'' of the straight-line track fitted to "smeared" hit positions, in TRANSPORT coordinates.

=====Calorimeter Sensitive Detector Branches===== The "calorimeter" sensitive detector type is designed to aggregate all the energy deposition by all particle tracks in a given sensitive volume within a given event. This type of sensitivity is useful for heavy, showering detectors that absorb the total energy of particles and produce large numbers of secondaries, and for scintillation detectors that produce large numbers of optical photons in proportion to the energy deposition, the tracking of which is very computationally expensive. The calorimeter sensitive detector class is also capable of optionally recording all of the individual particles depositing energy in the sensitive volume during an event.

• '''Calorimeter "hit" branches''': ** '''SDname.hit.nhits''' (type int): Number of "hits" in this sensitive detector for this event. Equals array size for all "hit" variables. ** '''SDname.hit.row''' (type vector *): Row number of "cell" in which hit occurred. "Row" is defined according to the "detector map" (see below) defined when the geometry is constructed. ** '''SDname.hit.col''' (type vector *): Column number of "cell" in which hit occurred. "Column" defined according to "detector map". ** '''SDname.hit.cell''' (type vector *): Cell number in which hit occurred. "Cell" is a generic term referring to a unique integer-valued identifier of the physical volume in which the hit occurred. The ''cell'' index is used as the unique ''key'' value in maps that keep track of information describing the physical location of a detector, such as ''row'', ''col'', ''plane'', ''xcell'', ''ycell'', etc. ** '''SDname.hit.plane''' (type vector *): Plane number of "cell" in which hit occurred. "Plane" is defined according to the "detector map". ** '''SDname.hit.xcell''' (type vector *): Local ''x''-coordinate of the ''center'' of the cell in which the hit occurred, in ''meters''. ** '''SDname.hit.ycell''' (type vector *): Local ''y''-coordinate of the ''center'' of the cell in which the hit occurred, in ''meters''. ** '''SDname.hit.zcell''' (type vector *): Local ''z''-coordinate of the ''center'' of the cell in which the hit occurred, in ''meters''. ('''Note: "local" cell coordinates are user-defined using the detector map (see below), and their meaning varies according to the specific design and geometry features of the detector in question. Typically, these coordinates are defined relative to a mother volume enclosing the detector itself, relative to which the detector does not move, but in order to ascertain the specific meaning of these coordinates, it is best to consult the source code defining the geometry of the detector in question. The "center" coordinates of a "cell" correspond to the origin of coordinates of the GEANT4 solid defining the geometry of the sensitive volume, such as ''G4Box''''') ** '''SDname.hit.xcellg''' (type vector *): Global ''x''-coordinate of the ''center'' of the cell in which the hit occurred, in ''meters''. ** '''SDname.hit.ycellg''' (type vector *): Global ''y''-coordinate of the ''center'' of the cell in which the hit occurred, in ''meters''. ** '''SDname.hit.zcellg''' (type vector *): Global ''z''-coordinate of the ''center'' of the cell in which the hit occurred, in ''meters''. ** '''SDname.hit.xhit''' (type vector *): Energy-deposition-weighted average global ''x''-coordinate of all tracking steps by all particles in the hit, in ''meters''. ** '''SDname.hit.yhit''' (type vector *): Energy-deposition-weighted average global ''y''-coordinate of all tracking steps by all particles in the hit, in ''meters''. ** '''SDname.hit.zhit''' (type vector *): Energy-deposition-weighted average global ''z''-coordinate of all tracking steps by all particles in the hit, in ''meters''. ** '''SDname.hit.sumedep''' (type vector *): Total energy deposition in the hit (GeV), summed over all tracking steps of all particles in the sensitive volume. ** '''SDname.hit.tavg''' (type vector *): Energy-deposition-weighted average global time since the start of the event (ns), averaged over all steps of all tracks. ** '''SDname.hit.trms''' (type vector *): Energy-deposition-weighted RMS deviation from the average global hit time (ns). ** '''SDname.hit.tmax''' (type vector *): Global time since the start of the event of ''first'' tracking step depositing energy in the volume (ns). ** '''SDname.hit.tmin''' (type vector *): Global time since the start of the event of ''last'' tracking step depositing energy in the volume (ns).
• '''Calorimeter-specific "particle" branches''': These branches contain information about all individual particles depositing energy in a calorimeter-type sensitive detector in an event. Note that the same track/particle may deposit energy in more than one "cell" of a calorimeter, and may therefore be recorded more than once in this array. Each particle track is recorded once in this array for every calorimeter "hit" in which it is involved. Because these branches can become very large, they are only active if ''/g4sbs/keepcalparticles SDname 1'' is invoked. ** '''SDname.npart_CAL''' (type int): Total number of particle/cell combinations depositing energy in this sensitive detector. Equals array size for all particle variables below: ** '''SDname.ihit''' (type vector *) Hit index of this particle entry. Equals the position in the hit array of the hit in which this particle was involved. ** '''SDname.x''' (type vector *): Energy deposition-weighted average local ''x''-coordinate (m) of this particle track while in the cell corresponding to hit index ''ihit''. ('''Note: "local" in this context means the internal coordinates within the cell itself, and are distinct from the "local" coordinates of the cell center relative to the calorimeter mother volume!''') ** '''SDname.y''' (type vector *): Energy deposition-weighted average local ''y''-coordinate (m) of this particle track while in the cell corresponding to hit index ''ihit''. ** '''SDname.z''' (type vector *): Energy deposition-weighted average local ''z''-coordinate (m) of this particle track while in the cell corresponding to hit index ''ihit''. ** '''SDname.t''' (type vector *): Energy deposition-weighted average global time (ns) since start of event of this particle track during hit ''ihit''. ** '''SDname.E''' (type vector *): Total energy (GeV) of the particle track prior to its first tracking step in cell corresponding to hit ''ihit''. ** '''SDname.dt''' (type vector *): Total duration (ns) of the particle's trajectory in hit ''ihit''. ** '''SDname.L''' (type vector *): Total path length (m) of the particle's trajectory in hit ''ihit''. ** '''SDname.vx''' (type vector *): Global ''x''-coordinate of particle creation vertex (m). ** '''SDname.vy''' (type vector *): Global ''y''-coordinate of particle creation vertex (m). ** '''SDname.vz''' (type vector *): Global ''z''-coordinate of particle creation vertex (m). ** '''SDname.trid''' (type vector *): GEANT4 global track ID number of particle. ** '''SDname.mid''' (type vector *): GEANT4 global track ID number of mother particle of the current particle. ** '''SDname.pid''' (type vector *): GEANT4 particle ID code of the current particle, according to PDG numbering scheme. ** '''SDname.p''' (type vector *): Initial momentum of particle (GeV), prior to its first tracking step in hit ''ihit''. ** '''SDname.px''' (type vector *): ''x''-component of initial particle momentum (GeV), prior to first tracking step in hit ''ihit''. ** '''SDname.py''' (type vector *): ''y''-component of initial particle momentum (GeV), prior to first tracking step in hit ''ihit''. ** '''SDname.pz''' (type vector *): ''z''-component of initial particle momentum (GeV), prior to first tracking step in hit ''ihit''. ** '''SDname.edep''' (type vector *): Total energy deposition of this particle track in the cell corresponding to hit ''ihit''.

=====RICH Sensitive Detector Branches===== The RICH sensitive detector type is designed for detectors of small numbers of optical photons such as the GRINCH and the SBS RICH detector, for which the typical signal size in a single PMT is of order 1-50 photoelectrons, and for which it is desirable to preserve information about the trajectories of the detected photons as well as the absolute number. It is not well-suited to describe detectors for which the average number of photoelectrons is large, on the order of hundreds to several thousand, such as the ECAL or HCAL PMTs. For these detector types, the ECAL sensitive detector is the appropriate choice, as a more limited set of information is retained in the ROOT tree.

• '''RICH hit branches''': ** '''SDname.hit.nhits''' (type int): Total number of hits in this sensitive detector. Equals array size for all array-valued branches starting with ''SDname.hit.''. ** '''SDname.hit.PMT''' (type vector *): PMT number of hit. Equivalent to "cell" for the calorimeter sensitive detector type, "PMT" is the unique integer identifier used to map physical location information such as ''row'', ''col'', ''xpmt'', ''ypmt'', etc. ** '''SDname.hit.row''' (type vector *): Row number of hit. Definition depends on sensitive detector. Defined via detector map. ** '''SDname.hit.col''' (type vector *): Column number of hit. Definition depends on sensitive detector. Defined via detector map. ** '''SDname.hit.xpmt''' (type vector *): "local" ''x''-coordinate of center of PMT photocathode (m). Detector-dependent definition via detector map. ** '''SDname.hit.ypmt''' (type vector *): "local" ''y''-coordinate of center of PMT photocathode (m). Detector-dependent definition via detector map. ** '''SDname.hit.zpmt''' (type vector *): "local" ''z''-coordinate of center of PMT photocathode (m). Detector-dependent definition via detector map. ** '''SDname.hit.xgpmt''' (type vector *): "global" ''x''-coordinate of center of PMT photocathode (m). ** '''SDname.hit.ygpmt''' (type vector *): "global" ''y''-coordinate of center of PMT photocathode (m). ** '''SDname.hit.zgpmt''' (type vector *): "global" ''z''-coordinate of center of PMT photocathode (m). ** '''SDname.hit.NumPhotoelectrons''' (type vector *): Number of detected photoelectrons. ** '''SDname.hit.Time_avg''' (type vector *): Average global detection time (ns) since start of event, of all optical photons detected by this PMT in this event. ** '''SDname.hit.Time_rms''' (type vector *): RMS deviation from the mean of global detection time (ns) since start of event (only meaningful for hits with multiple photon detections). ** '''SDname.hit.Time_min''' (type vector *): Detection time of first optical photon in this PMT (ns). ** '''SDname.hit.Time_max''' (type vector *): Detection time of last optical photon in this PMT (ns). ** '''SDname.hit.mTrackNo''' (type vector *): Mother track ID number of the ''first'' photon detected by this PMT in this event. '''Note: This is the GEANT4 track ID of the charged particle that emitted the optical photon that was detected, NOT the track ID of the optical photon itself.''' ** '''SDname.hit.xhit''' (type vector *): Average global ''x''-coordinate of all photons detected by this PMT at the time of '''''detection''''' (m) ** '''SDname.hit.yhit''' (type vector *): Average global ''y''-coordinate of all photons detected by this PMT at the time of '''''detection''''' (m) ** '''SDname.hit.zhit''' (type vector *): Average global ''z''-coordinate of all photons detected by this PMT at the time of '''''detection''''' (m) ** '''SDname.hit.pxhit''' (type vector *): Average ''x''-component (in global coordinates) of unit direction vector of photon trajectories detected by this PMT at '''''detection time'''''. ** '''SDname.hit.pyhit''' (type vector *): Average ''y''-component (in global coordinates) of unit direction vector of photon trajectories detected by this PMT at '''''detection time'''''. ** '''SDname.hit.pzhit''' (type vector *): Average ''z''-component (in global coordinates) of unit direction vector of photon trajectories detected by this PMT at '''''detection time'''''. ** '''SDname.hit.pvx''' (type vector *): Average global ''x'' coordinate (m) of '''''emission vertex''''' of photons detected by this PMT. ** '''SDname.hit.pvy''' (type vector *): Average global ''y'' coordinate (m) of '''''emission vertex''''' of photons detected by this PMT. ** '''SDname.hit.pvz''' (type vector *): Average global ''z'' coordinate (m) of '''''emission vertex''''' of photons detected by this PMT. ** '''SDname.hit.ppx''' (type vector *): Average ''x''-component (in global coordinates) of unit direction vector of trajectories of photons detected by this PMT at '''''emission time'''''. ** '''SDname.hit.ppy''' (type vector *): Average ''y''-component (in global coordinates) of unit direction vector of trajectories of photons detected by this PMT '''''emission time'''''. ** '''SDname.hit.ppz''' (type vector *): Average ''z''-component (in global coordinates) of unit direction vector of trajectories of photons detected by this PMT '''''emission time'''''. ** '''SDname.hit.volume_flag''' (type vector *): Integer flag indicating in which volume the ''first'' photon detected by this PMT was emitted. This variable is presently only meaningful for the SBS RICH detector. *** 1 = Aerogel tile *** 2 = C4F10 gas (or whichever radiator gas is in use). *** 3 = UVT lucite exit window of aerogel containment vessel. *** 4 = "UV-glass" window of PMT

=====ECAL Sensitive Detector Branches===== The "ECAL" sensitive detector class in ''g4sbs'' is designed to record the signals from PMTs coupled to heavy, showering detectors or scintillation detectors that produce and collect large numbers of optical photons. It is similar, but retains a reduced amount of information compared to the RICH class.

• '''ECAL hit branches''' ** '''SDname.hit.nhits''' (type int). Number of hits, equal to array size for all "hit" variables. ** '''SDname.hit.PMT''' (type vector *). PMT number of hit. Equivalent to "cell" for the calorimeter sensitive detector type, "PMT" is the unique integer identifier used to map physical location information such as ''row'', ''col'', ''xpmt'', ''ypmt'', etc. ** '''SDname.hit.row''' (type vector *). Row number of hit. Detector-dependent definition via detector map. ** '''SDname.hit.col''' (type vector *). Column number of hit. Detector-dependent definition via detector map. ** '''SDname.hit.plane''' (type vector *) Plane number of hit. Detector-dependent definition via detector map. ** '''SDname.hit.xcell''' (type vector *) Local ''x''-coordinate of center of cell in which hit occurred (m). Detector-dependent definition via detector map. ** '''SDname.hit.ycell''' (type vector *) Local ''y''-coordinate of center of cell in which hit occurred (m). Detector-dependent definition via detector map. ** '''SDname.hit.zcell''' (type vector *) Local ''z''-coordinate of center of cell in which hit occurred (m). Detector-dependent definition via detector map. ** '''SDname.hit.xgcell''' (type vector *) Global ''x''-coordinate of center of cell in which hit occurred (m). ** '''SDname.hit.ygcell''' (type vector *) Global ''y''-coordinate of center of cell in which hit occurred (m). ** '''SDname.hit.zgcell''' (type vector *) Global ''z''-coordinate of center of cell in which hit occurred (m). ** '''SDname.hit.NumPhotoelectrons''' (type vector *): Total number of photoelectrons detected. ** '''SDname.hit.Time_avg''' (type vector *): Average global arrival time (ns) since start of event of photon detections by this PMT. ** '''SDname.hit.Time_rms''' (type vector *): RMS deviation from the mean of global arrival times (ns) of photons detected by this PMT. ** '''SDname.hit.Time_min''' (type vector *): Arrival time (ns) of first photon detected by this PMT. ** '''SDname.hit.Time_max''' (type vector *): Arrival time (ns) of last photon detected by this PMT.

=====Generic Particle History Branches (memory/disk intensive)===== The generic particle history branches have the same structure for all sensitive detectors, and are designed to keep track of the entire history of every particle involved in making hits in a given sensitive detector in a given event, all the way back to the primary particles generated in the event. To create these branches and retain this information, the GEANT4 command ''/tracking/storeTrajectory 1'' must be invoked prior to starting the run, and then ''/g4sbs/keephistory SDname bool'' to toggle storing of the information in the ROOT tree for sensitive detector with name ''SDname''. Storing the trajectories is very expensive in terms of memory usage of the simulation and disk space, especially in experiments/simulations in which large numbers of secondaries are created, so it is advisable to use this feature sparingly. The feature is not currently implemented for sensitive detectors of type kECAL. The branches are as follows:

• '''SDname.part.npart''' (type int): Total number of particles involved in making hits in this sensitive detector. Equals array size for all array-valued branches under ''SDname.part''
• '''SDname.part.PID''' (type vector *): GEANT4 particle ID code (according to PDG convention).
• '''SDname.part.MID''' (type vector *): GEANT4 track ID of the mother particle of the current particle.
• '''SDname.part.TID''' (type vector *): GEANT4 track ID number of the current particle.
• '''SDname.part.nbounce''' (type vector *): Number of "bounces" (interactions producing daughter particles) between the current particle and the particle responsible for the presence of the hit in the sensitive volume. In most cases, ''nbounce = 0'' corresponds to the particle that deposits energy (kGEM and kCAL), whereas in the kRICH case, the particle history starts at ''nbounce = 0'' with the charged particle that emitted a photon that was detected.
• '''SDname.part.hitindex''' (type vector *): Hit index (position in the "hit" array) of the first hit in which the current particle was involved.
• '''SDname.part.vx''' (type vector *): Global x-coordinate (meters) of interaction vertex at which current particle was created.
• '''SDname.part.vy''' (type vector *): Global y-coordinate (meters) of interaction vertex at which current particle was created.
• '''SDname.part.vz''' (type vector *): Global z-coordinate (meters) of interaction vertex at which current particle was created.
• '''SDname.part.px''' (type vector *): x-component (in GeV) of initial momentum of current particle.
• '''SDname.part.py''' (type vector *): y-component (in GeV) of initial momentum of current particle.
• '''SDname.part.pz''' (type vector *): z-component (in GeV) of initial momentum of current particle.

====Primary particle branches for "pythia6" generator==== These branches are created whenever ''/g4sbs/kine pythia6'' is invoked to use the "pythia6" event generator. Branches labeled "primaries" are global event properties, and branches labeled "Primaries" contain the arrays of all primary particles in the event.

• '''Event-level variables''': ** '''primaries.Sigma''' (type double): Total cross section calculated by Pythia6. ** '''primaries.Ebeam''' (type double): Beam energy (GeV) ** '''primaries.Eprime''' (type double): Scattered electron energy (GeV). ** '''primaries.theta_e''' (type double): Scattered electron polar angle (rad) ** '''primaries.phi_e''' (type double): Scattered electron azimuthal angle (rad) ** '''primaries.px_e''' (type double): x-component of scattered electron momentum (GeV) ** '''primaries.py_e''' (type double): y-component of scattered electron momentum (GeV) ** '''primaries.pz_e''' (type double): z-component of scattered electron momentum (GeV) ** '''primaries.vx_e''' (type double): Global x-coordinate of interaction vertex of scattered electron (meters) ** '''primaries.vy_e''' (type double): Global y-coordinate of interaction vertex of scattered electron (meters) ** '''primaries.vz_e''' (type double): Global z-coordinate of interaction vertex of scattered electron (meters) ** '''primaries.Egamma''' (type double): Energy of real or virtual photon (GeV). ** '''primaries.theta_gamma''' (type double): Polar angle of real or virtual photon (rad) ** '''primaries.phi_gamma''' (type double): Azimuthal angle of real or virtual photon (rad) ** '''primaries.px_gamma''' (type double): x-component of real or virtual photon momentum (GeV) ** '''primaries.py_gamma''' (type double): y-component of real or virtual photon momentum (GeV) ** '''primaries.pz_gamma''' (type double): z-component of real or virtual photon momentum (GeV) ** '''primaries.vx_gamma''' (type double): Global x-coordinate of interaction vertex of real or virtual photon (meters) ** '''primaries.vy_gamma''' (type double): Global y-coordinate of interaction vertex of real or virtual photon (meters) ** '''primaries.vz_gamma''' (type double): Global z-coordinate of interaction vertex of real or virtual photon (meters)
• '''Primary particle arrays''': The primary particle array includes the first four particles (PYTHIA6 header information) and all final-state particles, along with a flag to indicate particles that are actually generated. The first four particles (assuming the file was produced by the PYTHIA6 generator) are always the beam electron (0), the target nucleon (1), the scattered electron (2), and the (real or virtual) photon (3) ** '''Primaries.Nprimaries''' (type int): Total number of particles in the array, including "header" information. ** '''Primaries.PID''' (type vector *): GEANT4 particle ID code (according to PDG convention) ** '''Primaries.genflag''' (type vector *): Flag indicating whether this particle was actually generated in the GEANT4 event; 1 = yes, 0 = no. All final state particles (PYTHIA status code 1) with angles/energies falling within the user-defined angle and energy ranges for ''either'' the "electron" or the "hadron", regardless of particle type, will be generated and have ''genflag = 1''. ** '''Primaries.Px''' (type vector *): x-component of particle momentum (GeV). ** '''Primaries.Py''' (type vector *): y-component of particle momentum (GeV). ** '''Primaries.Pz''' (type vector *): z-component of particle momentum (GeV). ** '''Primaries.vx''' (type vector *): Global x-coordinate of particle creation vertex (m) ** '''Primaries.vy''' (type vector *): Global y-coordinate of particle creation vertex (m) ** '''Primaries.vz''' (type vector *): Global z-coordinate of particle creation vertex (m) ** '''Primaries.M''' (type vector *): Primary particle mass (GeV) ** '''Primaries.E''' (type vector *): Primary particle ''total'' energy (GeV) ** '''Primaries.P''' (type vector *): Magnitude of primary particle momentum (GeV) ** '''Primaries.t''' (type vector *): Primary particle creation time (ns) ** '''Primaries.theta''' (type vector *): Polar angle of primary particle (rad). ** '''Primaries.phi''' (type vector *): Azimuthal angle of primary particle (rad).

==Useful links==

*[http://git-scm.com/documentation Git Documentation] *[https://github.com/JeffersonLab/g4sbs Github.com] homepage for g4sbs *[http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ GEANT4 User's Guide] for application developers