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
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
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.
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:
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:
tar -zxvf lcdg4_v02-29.tar.gz
Now execute cd lcdg4 and follow the build instructions below.
User questions should be posted in the Full
Simulations area of the forum.linearcollider.org
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
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
LCDG4 has additional external dependencies: Xerces-C++ (version 2.4.0)
is used for XML parsing of geometry description files, and the standard
library is used for file compression.
Zlib is usually installed at
/usr/lib in all linux systems, so no additional setup should
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:
After installing the libraries, follow the LCDG4 build instructions
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 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:
Now the build should be straightforward:
If the build succeeds, the binary should be found under bin/$G4SYSTEM/lcdg4.
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
# app dir, XML
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.
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/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.
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.
Currently available LCDG4 datasets can be found at pub/lima/lcdg4
on the NICADD
sftp server. Usually the last version is recommended for
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:
Our experience at NICADD has been quite satisfying in using a
java-based, object-oriented approach to analysis.
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 lcdg4. Please 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.
is by far the best platform for analyzing SIO data, but its predecessor
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:
This plugin can show a simple event display, MC Particle Table and MC
Particle Tree for each event in the SIO file:
The following figures use an e+e- to WW to qqbar at 500 GeV SIO file with 500 events.
A partial MC Particle Table:
The partially expanded MC Particle Tree:
Simple event display:
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:
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.
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:
The Silicon Detector (SDJan03), for instance, has the following volumes (roughly, from inner to outer):
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">
<barrel_dimensions inner_r = "144.0" outer_z = "286.0" />
<slice material = "Stainless_steel" width = "2.0" />
<slice material = "Polystyrene" width = "1.0" sensitive = "yes" />
<segmentation cos_theta = "600" phi = "1200" />
<calorimeter type = "had" />
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".
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
or equivalent) so that no overlap occurs. There are no checks in
the code to prevent possible problems. No recompilations are
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.
Analyzing data from a custom geometry currently requires several steps:
As an example, I will walk through changing the hadronic calorimeter segmentation from 600 to 300 in theta and 1200 to 600 in phi:
Suggestions or contributions for improving this procedure are welcome.
We have developed at NICADD a new test geometry, named SDNPHJun04,
based on SDJan03 but with a Non-Projective Hadron calorimeter
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
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
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
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
The source code is mostly identical to the standard (projective)
version of LCDG4 described above. A few files required changes:
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.
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
This is a list of possible plans, fixes and additions for LCDG4 and related tools:
LCDG4 is frequently mentioned or featured in the following documents:
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.