View Source

h1. The ILC Detector Simulations FAQ

h2. General

h4. 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|http://www.slac.stanford.edu] and [ALCPG|http://physics.uoregon.edu/~lc/alcpg/] has the [SLIC Simulations Package|http://www.lcsim.org/software/slic] (C++) with the [org.lcsim|http://www.lcsim.org/] for reconstruction and analysis using Java.  This system also uses the [JAS3|http://jas3.freehep.org] graphical analysis environment.  Much of the functionality within org.lcsim comes from the [FreeHep Java Library|http://www.freehep.org].

There is a C++ framework developed under [ECFA|http://www-zeuthen.desy.de/linear_collider/] that uses [Mokka|http://polype.in2p3.fr/geant4/tesla/www/mokka/mokka.html] for the simulator with the [MARLIN|http://ilcsoft.desy.de/marlin/] tool for analysis and reconstruction.

Finally, the [ACFA|http://ccwww.kek.jp/acfa/] group has a [suite of softare|http://acfahep.kek.jp/subg/sim/softs.html] based on the [ROOT|http://root.cern.ch] framework.

h4. Where can I get additional information about software packages?

The [LCSim Software Index|http://www.lcsim.org/software/] has links to all the primary tools for ILC Detector Simulations.  The [Portals Section|http://www.lcsim.org/software/#port] lists sites that cover full suites of software.

h4. 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|http://jas3.freehep.org/] provides a number of integrated tools such as the [WIRED event display|http://wired.freehep.org] and an [AIDA|http://aida.freehep.org]-compliant plotter.

{info}
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".
{info}

h2. Feedback

h4. Is there an forum for ILC detector simulation issues?

The [linearcollider.org forum|http://forum.linearcollider.org/] is an appropriate place to post your questions on detector simulations and reconstruction and analysis.

h4. How do I file a bug report or make a feature request related to ILC software?

The [SLAC Jira Bugtracker|https://jira.slac.stanford.edu/secure/Dashboard.jspa] allows users to submit bug reports or make feature requests.

The projects relavent to ILC are ...

* [SLIC|https://jira.slac.stanford.edu/browse/SLIC]
* [LCDD|https://jira.slac.stanford.edu/browse/LCDD]
* [GeomConverter|https://jira.slac.stanford.edu/browse/GC]
* [LCDetectors|https://jira.slac.stanford.edu/browse/LCD]
* [LCIO|https://jira.slac.stanford.edu/browse/LCIO]
* [LCSIM|https://jira.slac.stanford.edu/browse/LCSIM]
* [www-lcsim|https://jira.slac.stanford.edu/browse/WWWLCSIM]

Each package will be covered in more detail within this FAQ.

h4. 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|http://bugs.freehep.org] for these projects.  These Jira projects include ...

* [JAS3|http://bugs.freehep.org/browse/JAS]
* [AIDA|http://bugs.freehep.org/browse/AIDA]
* [WIRED|http://bugs.freehep.org/browse/WIRED]

h4. How do I get an account on the ILC or FreeHep Jira?

Contact Tony Johnson <[mailto:tony_johnson@slac.stanford.edu]> to obtain an account on either of these systems.

h2. SLIC

h4. What is SLIC?

SLIC stands for "Simulator for the Linear Collider".  It is a full simulation package that uses the [Geant4|http://geant4.cern.ch] Monte Carlo toolkit to simulate the passage of particles through the detector.  SLIC outputs [LCIO|http://lcio.desy.de] 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|http://www.lcsim.org/software/lcdd]), which itself is based on the [GDML|http://gdml.web.cern.ch/GDML/] project from CERN.

h4. Where is SLIC's homepage?

The [SLIC Confluence page|https://confluence.slac.stanford.edu/display/ilc/SLIC] is the best source for up-to-date information on this software package.

h4. Who is the primary maintainer of SLIC?

Jeremy McCormick <[mailto: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 <[mailto: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.  

h4. At which HEP sites and labs is SLIC installed?

*Fermilab*: Here are [instructions for Fermilab users|http://cd-amr.fnal.gov/ilc/slic.shtml] on getting started with SLIC.  

*SLAC*: Here are [instructions for SLAC users|https://confluence.slac.stanford.edu/display/ilc/Running+SLIC+at+SLAC] on running slic from the  [public Unix machines|http://www.slac.stanford.edu/comp/unix/public-machines.html] 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|http://nicadd.niu.edu] Linux clusters at _/k2data/APPS/SimDist_.

h2. Installing SLIC

h4. 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.

h4. How do I get simulation binaries for my platform?

SimDist downloads contain binaries for Linux, OSX, and Windows.

These are located at ...

{noformat}
http://www.lcsim.org/dist/slic/
{noformat}

To download a Linux release, use these commands.

{noformat}
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
{noformat}

h4. What is SimDist?

The _SimDist_ package bundles together all the dependencies of SLIC into one project.  This greatly simplifies the build process.

h4. How do I run slic from SimDist?

SimDist has a run script at _scripts/slic.sh_ which will setup the LD_LIBRARY_PATH to contain the Xerces lib directory and execute the current slic binary from the _packages/slic/${slic_version}_ directory.

It is useable from anywhere on the host where it was installed.

{noformat}
/path/to/my/SimDist/scripts/slic.sh [options]
{noformat}

This script passes all arguments to _slic_, so use it as you would the normal binary.

h4. How can I compile simulation binaries for my platform?

Follow the [build instructions for the SimDist project|Simulation Software Distribution] to make binaries for your platform.

h4. 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|SLIC From Scratch on Linux] and [building on Windws|SLIC From Scratch on Windows] if you must do this.

h2. Running SLIC

h4. Does SLIC have any runtime dependencies?

If you installed SLIC in the recommended way, the only runtime dependency would be the [Xerces C++|http://xml.apache.org/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.

{noformat}
export LD_LIBRARY_PATH=/path/to/my/xerces/install/lib:$LD_LIBRARY_PATH
{noformat}

If you see this error, it means that the LD_LIBRARY_PATH has not been set correctly.

{noformat}
./slic/bin/Linux-g++/slic: error while loading shared libraries: libxerces-c.so.27: cannot open shared object file: No such file or directory
{noformat}

The SimDist run script will set this variable automatically.

h4. How do I run the simulator binary?

Assuming you are within the slic package's top directory you would run it with this command.

{noformat}
./bin/$G4SYSTEM/slic [options]
{noformat}

The G4SYSTEM variable depends on your platform.  For instance, on Linux, it is set to _Linux-g++_, so the command would be ...

{noformat}
./bin/Linux-g++/slic [options]
{noformat}

h4. How do I get help on the command-line syntax?

To see explanations of slic's command-line options, use the "-h" option.

{noformat}
slic -h
{noformat}

This will print slic usage and exit.

h4. How do I find out about the SLIC version I am running?

h4. 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.

{noformat}
help [command]
{noformat}

Those directories containing only SLIC or LCDD commands are marked with _SLIC_ or _LCDD_.

{noformat}
/lcio/   LCIO output commands. [SLIC]
{noformat}

h4. 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_.

{noformat}
slic -m init.mac -m run.mac
{noformat}

The macros are executed in the order given at the command-line.

h4. 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.

{noformat}
slic -n
{noformat}

Other commands may also be executed before the interactive mode starts.

{noformat}
slic -g myGeom.lcdd -n
{noformat}

h4. 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.

{noformat}
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
{noformat}

h4. How can I check on the progress of my SLIC job(s)?

In bash, direct all output to a file, as follows.

{noformat}
slic &> job.log &
{noformat}

Now use the tail command to look at the output file as the job progresses.

{noformat}
tail -f job.log
{noformat}

The _BeginEvent_ and _EndEvent_ markers are best indicators of the job's progress.  

h4. How do I run SLIC on the LSF batch system?

h4. How do I run SLIC on the Condor batch system?

h4. Can I run SLIC on the Grid?

No.

h4. Why not?

Because getting things to run on the Grid is hard.

h4. How can I make SLIC look for the XML schemas in a local directory?

h4. How can I automatically set the name of the LCIO file?

h4. How can I automatically delete an existing LCIO file?

h4. How do I skip events in a StdHep file?

h4. How do I set the random seed?

h4. How do I dump the state of the CLHEP random engine?

h4. How can I see which physics lists are available?

h4. How do I set the physics list?

h4. How can I customize the handling of the magnetic field within Geant4?

h4. How do I set the maximum number of events?

h4. What types of event generator are available from SLIC?

h4. How do I use a StdHep file for events?

h4. How do I use an LCIO file for events?

h4. How do I use the General Particle Source (GPS)?

h4. How do I use the particle gun?

h4. How can I print information about the current event generator?

h4. What GUI are available for SLIC?

h2. LCIO

h4. What is LCIO?

h4. If I don't want to run SLIC, are there LCIO files available that I can use to get started with my analysis?

h4. How do I request new LCIO files?

h4. What tool can I use to look at LCIO output from the command line?

h4. What tool can I use to look at LCIO output from within JAS3?

h4. How can I create diagnostic histograms of LCIO output?

h4. Where can I post my questions about LCIO?

h2. Geometry using GDML and LCDD

h4. What is GDML?

h4. Where can I go for more information on GDML?

h4. What is LCDD?

h4. Where can I go for more information on LCDD?

h4. Where can I find examples of LCDD?

h4. What is the best way to create LCDD files?

h4. How do I dump the current Geant4 geometry to GDML?

h4. How do I check my geometry for overlaps?

h4. 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 ...

{noformat}
slic -g myGeom.gdml
{noformat}

The LCDD system will use the GDML schema instead of LCDD and the geometry should be loaded successfully.

h2. Detector Visualization

h4. How can I see a basic visualization of my events using Geant4?

h4. How can I make a HepRep file using Geant4?

h4. How do I use DAWN from within Geant4?

h4. How can I make cuts using DAWN?

h4. What other visualization options are available outside of using Geant4?

h2. Compact Detector Description

h4. What is the Compact Detector Description?

h4. 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.

{noformat}
http://www.lcsim.org/detectors
{noformat}

For instance, this is the location of the _sid00_ zip file.

{noformat}
http://www.lcsim.org/detectors/sid00.zip
{noformat}

The org.lcsim conditions system will use this URL automatically.  Otherwise, a tool like _wget_ can be used to download it manually.

h4. Where is the list of available compact descriptions?

A list of available compact detectors is kept at this URL.

{noformat}
http://www.lcsim.org/detectors/taglist.txt 
{noformat}

h4. What is LCDetectors and how do I use it?

h4. How do I convert compact detectors into LCDD using GeomConverter?

h4. How do I create my own detector from the compact description?

h4. How do I define detectors?

h4. How do I define the magnetic field?

h4. How do I define constants?

h4. How do I define a new material?

h4. How do I set physics limits?

h4. How do I set the range cut?

h4. How do I make org.lcsim use a custom detector?

h4. How do I define detector conditions?

h2. LCPhys

h4. What is LCPhys?

h4. Who is the maintainer of LCPhys?

h4. What simulation packages use LCPhys?

LCPhys is used by all three of the main ILC simulation packages, SLIC, Mokka, and JUPITER.

h4. Are there plots available of LCPhys physics results?

h2. org.lcsim

h4. What is org.lcsim?

h4. How do I install org.lcsim?

h4. What tools and algorithms are available in org.lcsim?

h4. Where can I go for more information on org.lcsim?