LCDG4
A Geant4-based detector simulation package
for the Linear Collider Detector

Dhiman Chakraborty, Guilherme Lima, Jeremy McCormick, Vishnu Zutshi
Northern Illinois Center for Accelerator and Detector Design
Northern Illinois University



Contents

  1. Overview
  2. Getting the source code
  3. Build setup
  4. Building
  5. Running
  6. Shell scripting
  7. Input and output formats
  8. Analysis
  9. Event scanning and visualization
  10. Geometry format
  11. Customizing detector geometries
  12. Non-projective geometry studies
  13. Physics certification
  14. Future plans
  15. References and presentations
  16. Contributors and contacts

1. Overview

LCDG4 is a general purpose, full detector simulation package to support detector R&D for a future Linear Collider.   It is based on Geant4, which is becoming the current standard simulations toolkit for interactions of particles with matter.  But LCDG4 was developed with full Gismo-compliance in mind, so that Gismo users can transparently migrate to use LCDG4 data in their studies.

LCDG4 has a powerful and easy to use, XML-based interface for geometry representations, which allows one to alter a large number of geometrical and material parameters in the description of a HEP detector.  Even people not  familiar with XML will be able to open the XML files in a simple text editor, find the subcomponent they are interested in altering and change a few geometry parameters.  More details on this are given in the geometry section.

Input physics events to LCDG4 can be provided in binary StdHep-based format.  Such files can be typically produced using Pandora-Pythia or a JAS2-based single particle generator.  Binary output data files are in a LC-specific SIO-based format.  Both input StdHep and output SIO files can be analyzed and visualized using the LCD Plugin of Java Analysis Studio (JAS).

LCDG4 has been developed on Linux, therefore this is the recommended platform.  The next sections provide instructions for source code downloading, and for building and running.  We have reports that LCDG4 can be run on Windows OS as well, although some tweaking might be needed in the makefile.  No user support for Windows exists here at this page, sorry...

NICADD maintains an access point for browsing the source code, as well as source documentation generated by Doxygen.

2. Getting the source code

Current and old versions of LCDG4 can be checked out of either the NICADD CVS repository.

Check out the code using the anonymous access instructions for NICADD CVS with module name lcdg4.

On Linux, using bash, execute the following:

export CVSROOT=:ext:lcdguest@nicadd.niu.edu:/cvs
export CVS_RSH=ssh
[password: lcd_2004]
cvs co lcdg4

LCDG4 versions can also be accessed via NICADD's CVSWeb.

Some binary versions can be downloaded via anonymous sftp to nicadd's server in the pub/lcdprj/apps/lcdg4 directory.

For example, to login, retrieve a tar.gz and open it on Linux:

sftp scpuser@k2.nicadd.niu.edu 
[password: lcd_2004]
cd pub/lcdprj/apps/lcdg4
get lcdg4_v02-29.tar.gz
[after logout]
tar -zxvf lcdg4_v02-29.tar.gz

Now execute cd lcdg4 and follow the build instructions below.

3. Build Setup

User questions should be posted in the Full Simulations area of the forum.linearcollider.org homepage.

The rest of this section and the next assumes a Linux environment. Parts may work on Windows, but we do not run it on Windows at NICADD, so we can't support it. We recommend using a Linux system when possible.

Geant4 version 6.0 implemented some major changes from previous versions, so LCDG4 requires version 6.0 or higher for building.  Moreover, the Geant4 collaboration usually recommends the latest version, so we always plan to release new LCDG4 versions if needed, in order to keep the compatibility to new versions of Geant4.

In particular, LCDG4 uses by default the LHEP physics processes recommended by Geant4 for calorimetry studies.  The libraries can downloaded from http://cmsdoc.cern.ch/~hpw/GHAD/HomePage/Required libraries for Geant4 are libPackaging and libLHEP.  These can usually be built by typing gmake in the directory $G4INSTALL/hadronic_lists/lists. Unless G4LISTS_BASE is defined to another location, the list libraries will be built at $G4LIB/.lists_build/$G4SYSTEM.  For more technical details, look at the included hadronic_lists.gmk, which will check for the libraries within the default location or under G4LISTS_BASE/lists/.lists_build/$G4SYSTEM if G4LISTS_BASE is defined in the environment.

Other than Geant4 and CLHEP, LCDG4 has additional external dependencies:  Xerces-C++ (version 2.4.0) is used for XML parsing of geometry description files, and the standard Zlib library is used for file compression.

Zlib is usually installed at /usr/lib in all linux systems, so no additional setup should be needed.

Xerces-C++ installation is straightforward, follow the build instructions for your platform.  The library dependency will be satisfied by the correct definition of the environment variable XML_DIR after installation. XML_DIR should point at the root area for your installation, containing include and lib. This can usually be set to XERCESCROOT if you did a default build:

export XML_DIR=$XERCESCROOT

After installing the libraries, follow the LCDG4 build instructions below.

4. Building

Building depends on all libraries being correctly setup (see previous section). Additionally, the Geant4 variables G4INSTALL and G4SYSTEM should indicate the base Geant4 installation directory and OS, respectively.

The following environment variables should be set in the environment before building:

In bash, these would be setup in the following fashion:

. $G4INSTALL/.config/bin/$G4SYSTEM/env.sh [may require absolute path]
export XML_DIR=/path/to/xerces-c_install
export G4LISTS_BASE=/path/to/phys_lists [optional]

Of course, the above "/path/to" locations need to be replaced with your system-specific installations.

It is recommended to build the application statically to avoid runtime dependencies in your application directory:

export G4LIB_BUILD_STATIC=1
unset G4LIB_BUILD_SHARED

Now the build should be straightforward:

cd /path/to/lcdg4
export G4WORKDIR=`pwd`
gmake all

If the build succeeds, the binary should be found under bin/$G4SYSTEM/lcdg4.

5. Running

Depending on where and how you've installed the libraries, LD_LIBRARY_PATH may need to be set for the loader to find shared libraries needed at runtime.

For instance, assuming that all libraries are shared, LCDG4 is the root application area and STDHEP_DIR and XML_DIR were set according to the previous instructions:

# Geant4 libs, including hadronic physics use-cases
export LD_LIBRARY_PATH=$G4LIB/$G4SYSTEM:$G4LIB/.lists_build/$G4SYSTEM
# app dir, XML
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LCDG4/tmp/$G4SYSTEM/lcdg4:$XML_DIR/lib

Refer to template.sh for an example run script. As shown in this example, execute export PEGS4PATH=`pwd` from the LCDG4 base directory to setup the materials directory.

The general format for running LCDG4:

lcdg4 input_file.xml output_file.sio Detector_ID input_file.stdhep macro_file

Explanations for each of these arguments:

Currently, all of these are required arguments.

6. Shell Scripting

The major consideration when scripting LCDG4 for batch processing is to redirect standard error and output to log files. Also, LD_LIBRARY_PATH or its equivalent may need to be set depending on how libraries were installed.

Here is a minimal shell script to run LCDG4 using the SDJan03 geometry:

#!/bin/sh
cd /path/to/lcdg4
export PEGS4PATH=`pwd`
./bin/Linux-g++/lcdg4 ParFiles/SDJan03.xml test_output.sio SDJan03 \
inputfile run.macro 1> lcdg4.out 2> lcdg4.err

inputfile should be a symlink to a valid StdHep file.

Assuming the script is script.sh, run it using nohup script.sh &> /dev/null & and then tail the output files to check on the job's progress.

7. Input and Output Formats

The input to LCDG4 is a file containing MC events in StdHep format, and output is in SIO format.  ASCII output can also be produced for calorimeter hits, for debugging purposes.

StdHep input for LCDG4 is typically produced using either Pandora-Pythia (links to PP notes) or the JAS-based SingPartGen.java. The first produces complete hard scattering events while the second creates one or more MC particles.

Datasets available

Currently available LCDG4 datasets can be found at pub/lima/lcdg4 on the NICADD sftp server.  Usually the last version is recommended for general use.

Output Format

The output format is SIO, as required for transparent use of pre-existing reconstruction and analysis tools in the realm of the american LCD efforts. LCIO format has been increasingly adopted worldwide as the standard I/O format for LCD simulations, so it will likely replace SIO in the  near future.

The output data structure basically contains a run header record followed by many event records.  The run header contains a detector ID (i.e. "SDJan03", "SDMar01", etc. - refer to the LCD_Detector_ID class). The detector ID allows SIO-able tools like JAS to load the appropriate detector geometry for displays.

Each event record contains an MCParticle collection and one hit collection per subdetector:

If more than one particle goes through the same tracker channel, two or more hits are produced in order to save both contributions.

8. Analysis

Our experience at NICADD has been quite satisfying in using a java-based, object-oriented approach to analysis.

One uses standalone programs to analyze the SIO files and fill histograms and/or ntuples, which are then saved into aida files. This histogram-filling stage can easily be run in batch, and then a GUI-based analysis package is used later just to look at histograms and to perform a more interactive analysis using ntuples.  Moreover, the histograms saved in a file are very convenient, as a re-run is not necessary. The advantage of this approach is that it allows remote running over a slow dial-up connection, as no graphical interface is necessary during the histogram-filling run.  The .aida files are manageable to be transfered and studied locally, and the big .sio files are not needed locally, unless when user needs event visualization.

The analysis code currently used at NICADD is also available, in the subdirectory analysis of the CVS module lcdg4Please note that, at this point, there is no ntuple being filled, only histograms. But there are plans to use ntuples for higher productivity and more sophisticated analyses.

Running an analysis job

To run the analysis job, go to the subdirectory analysis, edit the file build to correctly define CLASSPATH according to your local installation, and then source it instead of just executing it, so that CLASSPATH can also be used at runtime:

> . build
> java AnalyzeSio file1.sio file2.sio file3.sio

The multiple files will be processed sequentially, and a single .aida file will be created with several histograms.  This file can then be loaded from JAS for easily looking through the histograms.

9. Event scanning and visualization

JAS3 is by far the best platform for analyzing SIO data, but its predecessor JAS2 can also be used. Because JAS2 is still considered the official release, and JAS3 is the beta version, we describe both of them below, as they are significantly different.

Launch JAS2 and install the lcd plugin if it is not already installed. Now load it from Edit->LoadPlugin:

JAS2 LCD Plugin Load

This plugin can show a simple event display, MC Particle Table and MC Particle Tree for each event in the SIO file:

JAS2 LCD Menu

The following figures use an e+e- to WW to qqbar at 500 GeV SIO file with 500 events.

A partial MC Particle Table:

MC Particle Table

The partially expanded MC Particle Tree:

MC Tree

Simple event display:

Event Display


JAS3 has similar MCParticle table and tree, but its event display uses the more flexible LCD WIRED 3 view. Select File->New->LCDWired View:


LCD Wired Menu

This gives a much more flexible and stateful display with MC hit information, rotational capabilities, etc. Individual hits can be selected by right-clicking on the display and setting Mouse Function->Pick Polygon. MC Particle information does not appear correctly for each hit as the Wired View is not programmed to extract and display it.

Here is the LCDWired View (side view) for the SIO file above:

LCD Wired Menu

Previous section shows how to use code-based analysis to produce AIDA histograms, display MC information for hits, etc. JetFinder algorithms may also be used for reconstruction.

10. Geometry Format

LCDG4 uses the lcdparm XML format described in the detParms.dtd ("Detector Parameters") Document Type Defition (DTD). This format can describe LCD components, including tracking or calorimeter barrels and their endcaps, and the magnetic coil. It does not currently have the capability to describe flat volumes, only tube-like barrels and disk-like or cone-like endcaps.

Several models are currently available for simulations:

A detailed example

The Silicon Detector (SDJan03), for instance, has the following volumes (roughly, from inner to outer):

PIPE_INNER
PIPE_INNER_SHIELD
PIPE_CONE
PIPE_OUTER
PIPE_SSCONE
PIPE_SSOUTER
M1_CONE
M2_DISK
LOWZ_CONE
LUM_CONE
LUM_ENDCAP
VERTEX_BARREL
VERTEX_BARREL_1
VERTEX_BARREL_2
VERTEX_BARREL_3
VERTEX_BARREL_4
VERTEX_BARREL_5
VERTEX_BARREL_OUTER_WALL
VERTEX_ENDPLATE
VERTEX_CRYO_BARREL
VERTEX_CRYO_ENDPLATE
TRACK_BARREL
TRACK_BARREL_1
TRACK_BARREL_2
TRACK_BARREL_3
TRACK_BARREL_4
TRACK_BARREL_5
TRACK_ENDCAP
TRACK_ENDCAP_1
TRACK_ENDCAP_2
TRACK_ENDCAP_3
TRACK_ENDCAP_4
TRACK_ENDCAP_5
TRACK_ENDCAP_6
TRACK_ENDCAP_7
TRACK_ENDCAP_8
TRACK_ENDCAP_9
TRACK_ENDCAP_10
TRACK_ENDCAP_INNER_DISK1
TRACK_ENDCAP_INNER_DISK2
TRACK_ENDCAP_INNER_DISK3
TRACK_ENDCAP_INNER_DISK4
TRACK_ENDCAP_INNER_DISK5
TRACK_BARREL_INNER_WALL
TRACK_BARREL_OUTER_WALL
TRACK_ENDCAP_OUTER_DISK
EM_BARREL
EM_BARREL_OUTER_WALL
EM_ENDCAP
EM_ENDCAP_OUTER_DISK
HAD_BARREL
HAD_BARREL_ENDRING
HAD_ENDCAP
HAD_ENDCAP_INNER_TUBE
HAD_ENDCAP_OUTER_TUBE
COIL
COIL_INNER_TUBE
COIL_OUTER_TUBE
COIL_OUTER_DISK
MUON_BARREL
MUON_BARREL_OUTER_WALL
MUON_ENDCAP

Each volume is defined as a cone, disk or tube. As an illustration, the definition of the hadronic calorimeter is:

    <volume id="HAD_BARREL" rad_len_cm="1.133" inter_len_cm="0.1193">
<tube>
<barrel_dimensions inner_r = "144.0" outer_z = "286.0" />
<layering n="34">
<slice material = "Stainless_steel" width = "2.0" />
<slice material = "Polystyrene" width = "1.0" sensitive = "yes" />
</layering>
<segmentation cos_theta = "600" phi = "1200" />
</tube>
<calorimeter type = "had" />
</volume>

All dimensions are in centimeters, and lengths are usually in half-lengths (Geant4 technicality).  There are 34 tube-like layers, each built as a 2cm-thick steel absorber followed by a 1.0cm-thick polystyrene active layer.  The inner layer starts at a radius of 144cm and the total length is 572cm (2*286cm).

The segmentation numbers are used as applied to the whole range of theta (not cos-theta!) and phi. The numbers above then describe a calorimeter where each HCal cell subtends a 180°/600 = 0.3° in polar angle, and 360°/1200 = 0.3° in azymuth.  In LCDG4, cell divisions are "virtual", whereby calculations of cell centers for hits counting is done within the sensitive detector code, based on the geometry segmentation information. This "virtual cells" approach yields a performance improvement in hits processing and tracking compared with individual "real cells".

11. Customizing Detector Geometries

Detector simulation

Simple changes to a pre-existing detector geometry are straightforward. Typical changes are altering the segmentation or changing the layering widths or total number of layers. Materials can also be changed quite easily, provided the new materials have a description file (ParFiles/material.mat). Take care to adjust subsequent volumes (inner_r or equivalent) so that no overlap occurs.  There are no checks in the code to prevent possible problems.  No recompilations are needed.

More complex changes, like shapes, can also be made without recompiling the code, although they are not so straigtforward as the changes listed above.  A limited number of possible shapes is available: cones, tubes and disks.

A cone is a single cone segment, defined by a starting radius, a maximum width and the applied width for the layer.

A disk defines an endcap.

A tube comprises multiple, nested layers, such as a calorimeter barrel. The barrel_dimensions element defines the starting inner radius for the tube. The outer_z attribute gives the halflength along the beam pipe. The real ending radius is defined by the combination of a layering element (number of layers) and its slices (slice). The slices are multipled n number of times from the layering's n attribute.

The segmentation element defines the projective divisions from (0,0) along theta and phi.

Note: For proper visualization in JAS, any changes to geometry must follow the steps described on next subsection.

Event scanning and visualization

Analyzing data from a custom geometry currently requires several steps:

  1. Alter the values in the xml file. You probably should rename the xml file to reflect the changes. (This was done before the job was run.)
  2. Run the job with the custom geometry.
  3. Make the corresponding changes to xml file in JAS's .ini file.
  4. Recompile lcd.jar.

As an example, I will walk through changing the hadronic calorimeter segmentation from 600 to 300 in theta and 1200 to 600 in phi:

  1. Locate the line <segmentation cos_theta="600" phi="1200"/> in HAD_ENDCAP and HAD_BARREL in your SDJan03.xml file.
  2. Change them to 600 and 300, respectively.
  3. Now open the file hep/lcd/detector/sdjan03/Detector.ini from the lcd codebase.
  4. Under HAD_Segmentation:, make the changes from the xml file.
  5. Recompile lcd.jar and analyze the SIO files in the usual fashion.

Suggestions or contributions for improving this procedure are welcome.


12. Non-projective geometry studies

We have developed at NICADD a new test geometry, named SDNPHJun04, based on SDJan03 but with a Non-Projective Hadron calorimeter (NPH).  This code has been available in the main LCDG4 codebase since version v03-00, in both NICADD and SLAC CVS repositories.

SDNPHJun04 replaces the projective HCal cells in SDJan03 with fixed-size cells. and writes out SIO output. Text format is also available, but only for calorimeters hits.

Note (July 2004): The projective and non-projective forks have been merged in LCDG4 version v03-00 and later, so that either projective or non-projective geometries can be used in the same executable.  We are currently working to make the hits visualization available from JAS.  When that task is complete, this documentation will be updated with the proper instructions.

The SIO output can be analyzed similarly to the projective version, except that the cell ids follow a different convention, compatible to the non-projective geometry.  The analysis code currently needs to receive the geometry information from a symbolic link geom.txt, which points to an ASCII file which is produced during the simulator processing (see an example).  This file contains the minimum geometry information used to correctly calculate the hit positions from the cell_id (layer,theta,phi indices).

Currently, it is up to the user to point geom.txt to the right file.  If an incorrect geometry is used, the hit positions will not be consistent with the simulator, or the job may even crash.  Therefore we recommend users to save the important ones for use during the analysis.  Check variable TXTGEOMFILEPATH in template.sh.

Please note: at this point it is not possible to correctly visualize the non-projective hits from JAS+Wired, because there is no .ini file compatible with the non-projective geometries.  Any suggestions on this issue are very welcome.

The source code is mostly identical to the standard (projective) version of LCDG4 described above.  A few files required changes:

include/LCDG4HDCalSD.hh
include/LCDXML2G4HDCal.hh
src/LCDG4EventAction.cc
src/LCDG4HDCalSD.cc
src/LCDtowerID.cc
src/LCDXML2G4HDCal.cc

while others were created anew:

include/LCDtowerIDNonProj.hh
include/NonProjCalGeometry.hh
include/NonProjCalGeomParams.hh
include/NonProjCalLayer.hh
include/NPCellID.hh
src/LCDtowerIDNonProj.cc
src/NonProjCalGeometry.cc
src/NonProjCalGeomParams.cc
src/NonProjCalLayer.cc

Some of these new classes have been also ported to java, in order to calculate the cell positions from the cell id (layer, theta and phi indices) in java analysis jobs.  For this purpose, an extra jar file is needed in your CLASSPATH: nicadd-NonProj.jar.

13. Physics certification

Ties Behnke ported LCDG4's XML processing and sensitive detector codes to Mokka v01-05. It reads the name of the XML file from the Mokka database. This is available (fully compiled for Linux) from the NICADD server at pub/lcdprj/apps/mokka/ties-lcdmokka.tar.gz.  Mokka package has since upgraded (current version is v02-03 or higher), but this new XML functionality has not been ported along to Mokka v02.

In the interests of brevity, one refers interested readers to G. Lima's Certifying Geant4-based calorimeter simulations for the LCD, which compares results from LCD Mokka with LCDG4. Various parameters such as hits per layer and energy depositions are found to be within +-5% between the two packages.

14. Future Plans

This is a list of possible plans, fixes and additions for LCDG4 and related tools:

Note: there are discussions under way to design a common package to be used worldwide within the linear collider collaboration, by trying to keep the best features of each current detector simulation package into a common product.  Current packages are Mokka, LCDG4, Jupiter and LCS.

15. References and Presentations

LCDG4 is frequently mentioned or featured in the following documents:

16. Contributors and Contacts

LCDG4 is based on the LCDRoot package, developed by Toshi Abe and Masako Iwasaki at SLAC.

Contributors to the LCDG4 codebase have included Guilherme Lima (NICADD), Jeremy McCormick (SLAC and NICADD), Rob McIntosh (NICADD), Mike Arov (now on Fermilab D0), Ties Behnke (DESY), Ryan Smith (original author while at SLAC), Ron Cassell (SLAC), Norman Graf (SLAC), and Tony Johnson (SLAC).

Active contributors are G. Lima, J. McCormick, N. Graf, R. Cassell and T. Johnson.

Comments and questions should be posted in the LCDG4 Forum of the LC Forum.


Guilherme Lima