------------------------------ README File ---------------------------------
This repository is a version of the example/tutorial included in the default
Geant4 distribution, called underground_physics. It started as a full copy of
the example found in Geant4-11.0.3. The objective to create this repository is
two-fold:
1) Make an accessible copy of the example for students learning to use Geant4,
easy to browse and read online.
2) Fix issues found in the example included in the Geant4 distribution, so that
it is ready to run "off-the-shelf" by any student.
It could also be used as a testing ground for implementing changes in geometry,
physics list, and output. However, any changes that are not essential to
running should be done in new branches, not in the master branch.
The rest of the README below is the original README for this example.
------------------------------Advanced Example--------------------------------- README FILE
Note: Due to the importation of data files during the initialisation stage of
Geant4, load-time may be in excess of 5 minutes.
UNDERGROUND PHYSICS
An example of a underground dark matter experiment.
Please see the UserRequirements.txt and related web-pages referred to
at the end of that document.
Over-view:
A single liquid xenon cell is simulated within Geant4 and the scintillation
light produced from interactions from various calibration species is recorded
as PhotoMultiplier hits. The output is then written to an ASCII file for
future off-line analysis.
Geometry:
Experimental set-up:
G4double worldWidth = 470.0*cm + 2.*wallThick; // "x"
G4double worldLength = 690.0*cm + 2.*wallThick; // "y"
G4double worldHeight = 280.0*cm + 2.*wallThick; // "z"
A "cavern" of dimensions 5.18m x 7.38m x 3.28m with concrete walls is defined
as the World Volume. A laboratory geometry is incorporated included desks,
cupboards, door and windows. For ease this is included in a separate ".icc"
file which can be removed should the code seem cumbersome. In the centre of
the cavern a steel vacuum vessel containing liquid and gaseous xenon is placed.
The internal construction of the vessel accurately reproduces an existing
prototype Dark Matter detector which allows experimental comparison. The active
detector volume is defined by a series of metal rings, complemented by
a cover mirror and a PMT immersed in the liquid. Two grids and a
thermalising copper shield are also incorporated. The liquid/gas
interface is located 6mm away from the mirror surface. A Am241
calibration source is suspended from one of the grids in the liquid
phase, above the PMT.
XXX================XXX mirror
XXX________________XXX gas phase
XXX XXX
XXX XXX liquid phase
XXX XXX
XXX.......U........XXX grid + calibrator
XXX................XXX grid
XXX| |XXX
| ___------___ |
|| PMT ||
|| ||
Hits Output (file "hits.out"):
An ASCII file containing the following information:
Evt # : event number
Etot, MeV : energy deposited in liquid xenon
LXe hits : number of hits in liquid xenon
LXeTime, ns : time of first hit in liquid xenon
PMT hits : number of hits in PMT (photocathode)
PmtTime, ns : average PMT hit time relative to LXeTime
First hit : first particle to hit liquid xenon
Flags : particles contributing to energy deposition
Seeds : the initial seed values for given hit events
Note:
The time information PmtTime is erroneous when forcing nuclear
decay with the RadioactiveDecay module due to the precision
required to detect nanosecond scintillation times on a global
time of 432 years (in the case of 241Am decay).
Pmt Output (file "pmt.out"):
Photon hit positions within the PMT face (overwritten every event):
"Hit# X, mm Y, mm Z, mm"
To Run:
Either run the macro files interactively or in batch with the command
DMX macro_name.mac.
Macros:
initInter.mac
Initialisation macro for interactive mode.
gamma.mac
Shoots one 60 keV gamma upwards from the calibrator and traces the
scintillation light produced in LXe to the PMT. All tracks are drawn
with custom colours. PMT hits in photocathode are also shown. Event
summary is writen to file "hits.out".
gamma_1000.mac
Similar to above, but 1000 gammas are emmited isotropically from the
source. No hits or tracks are draw, and the verbosity is reduced.
alpha.mac
Shoots one 5.486 MeV alpha particle upwards from the calibrator and
traces the scintillation light to the PMT. All tracks except
optical photons are drawn. Event summary is written to file
"hits.out" and PMT hits to file "pmt.out".
alpha_1000.mac
Similar to above, but 1000 alphas are emmited isotropically from the
source. No tracks are stored, and the verbosity is reduced. Event
summary is written to file "hits.out", PMT hits are not written out.
neutron.mac
Shoots one 2.48 MeV neutron inside the room aimed at the detector.
All tracks except scintillation photons are drawn (custom colours).
Gammas are not killed at the concrete wall. Event summery is written
to file "hits.out".
ambe_spectrum.mac
Produces a spectrum of neutrons according to an approximation of a Am/Be
neutron source. However, this uses the GPS and therefore will only work
after compilation with the DMXENV_GPS_USE environment variable (see below)
sourceAm241.mac
Forces the decay of 241Am nuclei in the calibrator and tracks the
resulting particles (237Np + alpha + gamma from 237Np
de-excitation). All tracks are drawn except scintillation photons.
Event summery is written to file "hits.out".
-> To be added for a future release
sourceAm241_1000.mac
Similar to above but for 1000 events. No tracks are stored.
-> To be added for a future release
Note:
The following environment variables need to be set:
G4RADIOACTIVEDATA : points to Radioactive Decay Data files
G4LEDATA : points to low energy data base
G4LEVELGAMMADATA : points to PhotoEvaporation data
NeutronHPCrossSections : points to neutron data files
In addition if you require to use the full General Particle Source then the
variable DMXENV_GPS_USE can be set. The DMX gun is still included in order to
allow forward compatibility should the GPS change.
ANALYSIS:
The program should produce ROOT-based histogram files. It is possible to
produce the output in XML-compliant format by changing the G4AnalysisManager default file type in DMXRunAction::Book().
SEEDS:
The seeds of event hits are stored in the hit record file. These can be used
to repeat events for visualisation, test crashes/idiosyncracies:
/random/setDirectoryName ./seeds
/random/resetEngineFrom currentEvent.rndm
/random/saveThisEvent
/random/setSavingFlag
The file currentEvent.rndm should contain the two seeds which were outputed in
the scintHit file.
ERRORS:
When running interactively the following error will be shown:
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor: boolean operation failed
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor: boolean operation failed
This is a "feature" of the visualisation of boolean volumes, but does not
affect functionality/performance so can be ignored.
NB:
If using explicit libraries (?) i.e. non-shared then compilation time with
neutrons in physics list is very long (>5 minutes) - check this.............
It is more efficient to use shared libraries that are loaded at run-time with
increased initialisation time (at run-time).
Also if using shared libraries the load time at run-time may be several minutes
- this is partially due to the neutron implementation requires full data sets
for each isotope being specified.
--------------------------------------
If running on Redhat 7.0 or above set G4SYSTEM to Linux-g++, alternatively you
can install backward compatibility to egcs, however, requires
config/sys/Linux-egcs.gmk to be altered so that CXX is set to kgcc
(compared to g++ in original file)
--------------------------------------
Alex Howard, 29/11/01
updated 18/06/02