# Documentation of g4sbs

## 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 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 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 ROOT installation. g4sbs is not yet compatible with root version 6!
• Working GEANT4 installation. For the uconn_dev branch, g4sbs is only compatible with GEANT4 version 10.0 and later. Other branches (except for the "geant4.10" branch), including the master branch, are only compatible with GEANT4 version 9.x and earlier
• 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. Newer versions of Qt seem to cause GEANT4 Qt-based visualization to crash. On Linux, the open-source version of Qt provided by the package manager of your distribution is recommended.

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

 git clone git@github.com: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 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:

 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. The following instructions assume that "build" is parallel to "g4sbs":

 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.

## 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

 ./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:

To run g4sbs in batch mode, do one of the following:

 ./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.

## g4sbs commands

This section documents all g4sbs commands. 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/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 $^3$He targets: Quasi-elastic electron-nucleon scattering with Fermi motion simulated by sampling the initial nucleon momentum from the momentum distribution in deuterium or $^3$He.
• 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.
• /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.
• SBS magnet, pole shims, field clamps (optional), lead inserts (optional).
• HCAL: In GEP, HCAL is offset vertically by a (hard-coded) 49.7 cm, 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), HCAL vertically centered with respect to SBS magnet gap.
• 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. HCAL vertically centered. Additional SBS trackers and RICH detector.
• /g4sbs/particle: Defines particle type for gun generator. Requires string argument. Any valid GEANT4 particle name is accepted.
• /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 back of the lead-glass blocks of ECAL (currently all assumed to be 40 cm thick). 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/48D48dist: Distance from target center to front face of SBS magnet yoke. Requires value and unit.
• /g4sbs/gemres: Set GEM coordinate resolution ($1\sigma$). Local x and y coordinates of hits in GEM detectors are subject to Gaussian smearing with this $\sigma$. Requires value and unit.
• /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/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.
• 1: 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

### "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/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.