Notice:

This is the old KLG4sim page.

If you are a KamLANDer looking for the new KLG4sim page, you want http://kamland.lbl.gov/internal/Computing/MC/.
If you want to simulate another antineutrino detector, you want the Generic Liquid-scintillator AntiNeutrino Detector ("GenericLAND") Geant4 simulation, GLG4sim, found at http://neutrino.phys.ksu.edu/~GLG4sim.

General Information

The KamLAND comprehensive Monte Carlo effort is collaboration-wide, involving all institutions, especially Tohoku, Caltech, Stanford, Berkeley, UTK, UH, TUNL, LSU, UA, Drexel, and the rest, not necessarily in that order. We hope to develop one complete Monte Carlo which is abundantly tested, validated, documented, and available to all collaborators.
KLG4sim is a Geant4-based simulation for the particle shower and tracking part of the Monte Carlo. KLG4sim per se is one part of the comprehensive Monte Carlo effort. Current KamLAND Monte Carlo Working Structure and Philosophy is my attempt to summarize the overall structure of the Monte Carlo, and who is working on what,
This page is meant to be a central resource for KLG4sim information.

How to Get

The latest source can be gotten from the CVS repository. If you want the latest source, or if you think you will develop new code for KLG4sim, you should get the source from CVS.
There is now cvsweb access to the KLG4sim repository! (Actually, a US-based read-only mirror of the Tohoku repository, which is even better.)
CVS is the only way to get an up-to-date version of the simulation.
If you do not have access to the KamLAND pages or CVS source and just want a starting point for your own simulation, please look at GLG4sim.
How to compile the source.

Geant4 Bugs (and how to fix them)

No known bugs in Geant4 release 6.2 patchlevel 2 and later.

Geant4-5.0-patch-01 should work okay if this patch is applied. The patch fixes one problem:

Occasionally, a funny surface normal can lead to an infinite loop in G4OpBoundary::GetFacetNormal(). I have seen this in the case where it hits on the inside lower corner of the M3 chimney. (Note the M3 chimney is a G4Tubs, not a KLTorusStack!) I have not been able to reproduce this in a simple test case, so it has not been reported yet, but the patch fixes it.

Note that the patch below used to eliminate the "assert" in G4Navigator in version 4.1 might still be necessary as well, but it might not be, so it is currently omitted from the patch file noted above.

Geant4-4.1-patch-01 should work okay if this patch is applied. The patch fixes three problems:

In default G4 and KLG4sim all neutrons are captured on carbon in LS. This is a dumb G4 bug -- see bug report 401 -- and has been fixed in version 5.0 and later.
For optical photon tracking, occasionally G4Navigator gets completely confused and dies on G4Navigator.cc:685 assert( shiftOriginSafSq <= sqr(safetyPlus) ); It's not clear whether this is a true G4 bug or just a geometry problem in KLG4sim. The simplest Kludge is to ignore the problem by commenting this line in G4Navigator.cc. The tracking continues and eventually ends safely (I hope) without it.
The patch to G4OpBoundaryProcess::GetFacetNormal() is also included. (See explanation above under Geant4-5.1-patch-01.)

Note: all of the bugs noted below are fixed in Geant4-4.1.

Do not use Geant4-4.0

Geant4-3.2 should work okay if the patches below are applied.

There is a bug in the calculation of normal vectors on the surface of "G4IntersectionSolid"'s. You can fix it with this patch. This bug has been reported (#314).
There is a missing feature in the batch file reader (G4batch.cc, called by /control/execute): misspelled or unparsable commands are silently ignored! You can fix it with this patch. This bug has been reported (#294) and fixed in Geant4 4.0.
There is a bug in the initialization code for tracks that causes segment violations whenever another rare bug or inaccuracy in the geometry code results in a track outside the world volume (happens a few times per 100,000 events). You can fix it with this patch. This bug has been reported (#265) and fixed in Geant4 4.0.
There is bad formatting and the wrong data for our application in the G4NDL0.2 neutron data library distributed on the Geant4 downloads page. These problems have been reported via the Geant4 bug-tracking mechanism (report #197) and discussed directly with the author, Hans-Peter Wellisch, who has kindly provided us with G4NDL3.1.tar.gz, which should be used instead of G4NDL0.2. (Note: a few lingering formatting problems were found in some files in G4NDL3.1 and have been corrected by yours truly, except for one file containing the gamma levels for Thulium 169.) Jason Detwiler has found that using this data library apparently solves all obvious problems with Geant4/neutron_hp, and leaves only a few discrepencies between Geant4/neutron_hp and Geant3/GCALOR. (These last few discrepencies may in fact be legitimate physics issues and not code bugs.)
There was a bug in the setting of track vertex information for "suspended" tracks in Geant4.3.1 and earlier. (The bug is that the vertex information is reset when tracking of the suspended track is resumed, instead of being left equal to the track creation point as specified in the description of the GetVertexXXX() functions.) You can fix it with this patch. This bug was reported (#240), and the responsible author fixed it. (This patch is not necessary for Geant4.3.2)
There was a bug in the calculation of real velocities of gammas and optical photons in Geant4.3.0 and earlier. You can fix it with this patch. This bug was reported (#218), and the responsible author fixed it. (This patch is not necessary for Geant4.3.1 and later)
Other patches:
- A patch for the G4MaterialPropertiesTable::Dump() function to make it print the whole material property name instead of just the first character of the name, and to avoid coredumps when an entry has no MaterialPropertyVector. Also corrects a mistake in a warning message in the RemoveEntry function. This bug has been reported (#295).
- A patch for G4NeutronHPNames.cc to make it print informational messages about what files it is substituting, instead of just silently proceeding.
- A patch for G4UnionSolid.cc to make it print warning messages when it encounters an unexpected case, instead of aborting program execution.

How to Use

Geant4 applications like KLG4sim are controlled by user commands either entered interactively or loaded from a "macro" (script) file. One of the commands is "help".
After unpacking or "cvs checkout"-ing KLG4sim, you will find a number of macros in the mac/ subdirectory containing example scripts for doing various useful things. Many of them even have comments!
There is general documentation on Geant4 available from the Geant4 home page, the most useful of which (after the Installation Guide) is the Geant4 User's Guide For Application Developers.
Two notes on specific topics of interest are KamLAND Coordinate System and Information on generators for the KamLAND simulation. These will eventually be incorporated into the reference manuals.
Please contact me by e-mail or phone if you have any questions.

Picture gallery

[Long captions should be added someday. Move mouse over picture for short, cryptic description. Click for enlarged view.]

Sample data sets

Link to directory used to store links to various output files.

This page used to be maintained by G. Horton-Smith. Discontinued January 1, 2004 -- see links at top of page for successor pages. Last previous update of content September 27, 2002.