The ILC Detector Simulations FAQ
General
What tools are available for ILC Detector Simulations?
Many tools are available for the simulation of ILC detectors and the analysis of results. There are three differents toolchains that can be used. These have been developed separately in the US, European, and Asian (Japanese) regions.
The system used by SLAC and ALCPG has the SLIC Simulations Package (C++) with the org.lcsim for reconstruction and analysis using Java. This system also uses the JAS3 graphical analysis environment. Much of the functionality within org.lcsim comes from the FreeHep Java Library.
There is a C++ framework developed under ECFA that uses Mokka for the simulator with the MARLIN tool for analysis and reconstruction.
Finally, the ACFA group has a suite of softare based on the ROOT framework.
Where can I get additional information about software packages?
The LCSim Software Index has links to all the primary tools for ILC Detector Simulations. The Portals Section lists sites that cover full suites of software.
Why are SLIC and org.lcsim the recommended software tools?
SLIC is the recommended simulator because it allows great flexibility and power in the specification of the detector geometry. LCDD provides a 100% runtime description of the detector and its associated properties, including the detailed volume hierarchy, assignment and properties of sensitive detectors, and the specification of detector component identifiers, among many other features. In practice, writing files in this standardized format is much easier than trying to author custom C++ code for each proposed full detector design and their subdetectors.
The org.lcsim package is recommended, because it uses the Java programming language, which is generally much easier to get started with and use than C++, especially for those with only partial time to devote to ILC research. Additionally, JAS3 provides a number of integrated tools such as the WIRED event display and an AIDA-compliant plotter.
The remainder of this FAQ focuses (almost exclusively) on the US/ALCPG/SLAC software suite based on SLIC and org.lcsim. The LCIO file format and its different language implementations ensure a basic level of interoperability between the three disparate systems should you want to "mix and match".
Feedback
Is there an forum for ILC detector simulation issues?
The linearcollider.org forum is an appropriate place to post your questions on detector simulations and reconstruction and analysis.
How do I file a bug report or make a feature request related to ILC software?
The SLAC Jira Bugtracker allows users to submit bug reports or make feature requests.
The projects relavent to ILC are ...
Each package will be covered in more detail within this FAQ.
How do I file a bug report or make feature request for auxiliary ILC software?
Several packages are used by org.lcsim that are not specific to ILC simulations. There is a separate FreeHep bugtracker for these projects. These Jira projects include ...
How do I get an account on the ILC or FreeHep Jira?
Contact Tony Johnson <tony_johnson@slac.stanford.edu> to obtain an account on either of these systems.
SLIC
What is SLIC?
SLIC stands for "Simulator for the Linear Collider". It is a full simulation package that uses the Geant4 Monte Carlo toolkit to simulate the passage of particles through the detector. SLIC outputs LCIO files that can be analysed using a variety of language bindings, including Java, C++, FORTRAN, and Python. SLIC uses a separate backend for the input of detector data called Linear Collider Detector Description (LCDD), which itself is based on the GDML project from CERN.
Where is SLIC's homepage?
The SLIC Confluence page is the best source for up-to-date information on this software package.
Who is the primary maintainer of SLIC?
Jeremy McCormick <jeremym@slac.stanford.edu> is the primary author and maintainer of SLIC. The handling of MCParticles in SLIC was based on earlier work by Ron Cassell <cassell@slac.stanford.edu> from a package called Linear Collider Simulator (LCS). Much work has also been done by Ron to verify and debug the LCIO output files.
At which HEP sites and labs is SLIC installed?
Fermilab: Here are instructions for Fermilab users on getting started with SLIC.
SLAC: Here are instructions for SLAC users on running slic from the public Unix machines at the lab. SLIC can be used on any of the load-balanced interactive Linux clusters, including noric, iris, and yakut.
NICADD: A copy of SLIC is available on the NICADD Linux clusters at /k2data/APPS/SimDist.
Installing SLIC
Which operating systems and compilers does SLIC support?
These are known working configurations of platform and compiler.
platform |
compiler |
compiler version |
|---|---|---|
Linux |
g++ |
3.3, 3.4 |
OSX |
g++ |
4.0 |
Windows (Cygwin) |
g++ |
3.4 |
The only supported compiler is g++. Other versions may work, but these are the ones that are known to build successfully.
How do I get simulation binaries for my platform?
SimDist downloads contain binaries for Linux, OSX, and Windows.
These are located at ...
http://www.lcsim.org/dist/slic/
To download a Linux release, use these commands.
wget http://www.lcsim.org/dist/slic/slic-1_13_3-Linux-g%2B%2B-bin.tar.gz tar -zxvf slic-1_13_3-Linux-g++-bin.tar.gz
What is SimDist?
The SimDist package bundles together all the dependencies of SLIC into one project. This greatly simplifies the build process.
How do I run slic from SimDist?
SimDist has a run script at scripts/slic.sh which will setup the runtime dependency (Xerces) and execute the current slic binary from the packages/slic directory.
It is useable from anywhere on the host where it was installed.
/path/to/my/SimDist/scripts/slic.sh [options]
How can I compile simulation binaries for my platform?
Follow the build instructions for the SimDist project to make binaries for your platform.
How do I build SLIC and the packages it depends on from scratch?
Building SLIC and its dependencies "from scratch" is not encouraged now that the SimDist project can manage this build procedure.
There are separate instructions for building on Linux and building on Windws if you must do this.
Running SLIC
Does SLIC have any runtime dependencies?
If you installed SLIC in the recommended way, the only runtime dependency would be the Xerces C++ shared library. The Xerces library directory needs to be added to the LD_LIBRARY_PATH (bash), so that the loader can find this library when slic executes.
export LD_LIBRARY_PATH=/path/to/my/xerces/install/lib:$LD_LIBRARY_PATH
If you see this error, it means that the LD_LIBRARY_PATH has not been set correctly.
./slic/bin/Linux-g++/slic: error while loading shared libraries: libxerces-c.so.27: cannot open shared object file: No such file or directory
The SimDist run script will set this variable automatically.
How do I run the simulator binary?
Assuming you are within the slic package's top directory you would run it with this command.
./bin/$G4SYSTEM/slic [options]
The G4SYSTEM variable depends on your platform. For instance, on Linux, it is set to Linux-g++, so the command would be ...
./bin/Linux-g++/slic [options]
How do I run SLIC if I installed with SimDist?
Use the script at SimDist/scripts/slic.sh as you would the normal slic binary. This script will automatically locate Xerces and set the correct LD_LIBRARY_PATH for you.
How do I get help on the command-line syntax?
To see explanations of slic's command-line options, use the "-h" option.
slic -h
This will print slic usage and exit.
How do I find out about the SLIC version I am running?
How do I get help on SLIC's custom Geant4 commands?
SLIC commands are added into various directories within the Geant4 UI hierarchy. From interactive mode, use this command to print information on a SLIC or LCDD command.
help [command]
Those directories containing only SLIC or LCDD commands are marked with SLIC or LCDD.
/lcio/ LCIO output commands. [SLIC]
How do I run a macro containing UI commands?
You can put Geant4 UI commands into one or more macro files that slic can execute. This is done with the "-m" switch. There can be any number of these switches given to slic at the commandline. For instance, this command will execute the two macros init.mac and run.mac.
slic -m init.mac -m run.mac
The macros are executed in the order given at the command-line.
How do I run in interactive mode?
SLIC can be started in interactive mode using the "-n" option.
This command will start Geant4 in PreInit mode where the geometry is not loaded.
slic -n
Other commands may also be executed before the interactive mode starts.
slic -g myGeom.lcdd -n
What is a typical command to run SLIC in batch mode?
The following command illustrates some of the options that could be used in a typical batch run.
slic -g myGeom.lcdd \ # geometry file
-i events.stdhep \ # StdHep input file
-p lcio/ \ # path for LCIO output file
-o output.slcio \ # name of LCIO output file
-x \ # delete existing LCIO file
-r 1234 \ # seed the random engine
-s 100 \ # number of events to skip
-r 1000 # number of events to run
How can I check on the progress of my SLIC job(s)?
In bash, direct all output to a file, as follows.
slic &> job.log &
Now use the tail command to look at the output file as the job progresses.
tail -f job.log
The BeginEvent and EndEvent markers are best indicators of the job's progress.
How do I run SLIC on a batch system such as LSF?
How can I make SLIC look for the XML schemas in a local directory?
How can I automatically set the name of the LCIO file?
How can I automatically delete an existing LCIO file?
How do I skip events in a StdHep file?
How do I set the random seed?
How do I dump the state of the CLHEP random engine?
How can I see which physics lists are available?
How do I set the physics list?
How can I customize the handling of the magnetic field within Geant4?
How do I set the maximum number of events?
What types of event generator are available from SLIC?
How do I use a StdHep file for events?
How do I use an LCIO file for events?
How do I use the General Particle Source (GPS)?
How do I use the particle gun?
How can I print information about the current event generator?
LCIO
What is LCIO?
If I don't want to run SLIC, are there LCIO files available that I can use to get started with my analysis?
How do I request new LCIO files?
What tool can I use to look at LCIO output from the command line?
What tool can I use to look at LCIO output from within JAS3?
How can I create diagnostic histograms of LCIO output?
Where can I post my questions about LCIO?
Geometry using GDML and LCDD
What is GDML?
Where can I go for more information on GDML?
What is LCDD?
Where can I go for more information on LCDD?
Where can I find examples of LCDD?
What is the best way to create LCDD files?
How do I dump the current Geant4 geometry to GDML?
How do I check my geometry for overlaps?
How do I read a plain GDML file using SLIC?
The LCDD system supports reading both plain GDML and LCDD files from SLIC.
To read in a "plain" GDML file, simply use the "-g" option as you normally would ...
slic -g myGeom.gdml
The LCDD system will use the GDML schema instead of LCDD and the geometry should be loaded successfully.
Detector Visualization
How can I see a basic visualization of my events using Geant4?
How can I make a HepRep file using Geant4?
How do I use DAWN from within Geant4?
How can I make cuts using DAWN?
What other visualization options are available outside of using Geant4?
Compact Detector Description
What is the Compact Detector Description?
Where is the standard location for compact XML files and their matching LCDD description?
Compact detectors are kept at this base url in zip files.
http://www.lcsim.org/detectors
For instance, this is the location of the sid00 zip file.
http://www.lcsim.org/detectors/sid00.zip
The org.lcsim conditions system will use this URL automatically. Otherwise, a tool like wget can be used to download it manually.
Where is the list of available compact descriptions?
A list of available compact detectors is kept at this URL.
http://www.lcsim.org/detectors/taglist.txt
What is LCDetectors and how do I use it?
How do I convert compact detectors into LCDD using GeomConverter?
How do I create my own detector from the compact description?
How do I define detectors?
How do I define the magnetic field?
How do I define constants?
How do I define a new material?
How do I set physics limits?
How do I set the range cut?
How do I make org.lcsim use a custom detector?
How do I define detector conditions?
LCPhys
What is LCPhys?
Who is the maintainer of LCPhys?
What simulation packages use LCPhys?
LCPhys is used by all three of the main ILC simulation packages, SLIC, Mokka, and JUPITER.