The STAR Simulation Framework

Outline

1. Introduction
2. Quick Start
3. Primary Event Generation
4. Geometry Description
5. Particle Transport and Detector Simulation
6. Digitization / Slow Simulation
7. The Truth about Event Records
8. Reconstruction

Introduction

STAR's simulation infrastructure is built around the GEANT 3 simulation package.  It is implemented in FORtran, augmented by the MORtran-based AgSTAR preprocessor language, with a ROOT and C++ interface which allows it to be integrated with our standard "big full chain" software.  The legacy documentation pages describe how to run starsim as a standalone application.  The purpose of this document is to describe how to run simulations using the modern C++ interface, and to serve as a starting point for extending the simulation infrastructure with additional geometry modules, event generators, and slow simulators.

This document assumes familiarity with:

1. C++
2. ROOT
3. The STAR Framework

Quick Start

1. Your First Simulation Job
2. Reconstructing the Events
3. idTruth and qaTruth
4. Taking it Further

Running your analysis code over Monte Carlo data samples is generally a three step process.  First you'll need to generate your Monte Carlo events by running the simulation package.  Then you'll pass these events through the reconstruction software to convert MC hits to "real" ones, then perform track reconstruction, matching to TOF/MTD/etc... and creating calorimeter hits.  Finally you will want to run your analysis code on the output, possibly even looking at the Monte Carlo Truth tables in order to better understand the efficiency, purity and resolution of your reconstruction codes.

A. Your First Simulation Job

We're going to start with a simple example:  starsim.kinematics.C.  This is an example macro which runs under root4star, and generates a sample of muons and neutral pions.  Start by checking the code out from CVS. 

$ cvs co StRoot/StarGenerator/macros/starsim.kinematics.C                 # check out the macro
$ ln -s StRoot/StarGenerator/macros/starsim.kinematics.C starsim.C        # create a link named starsim.C
$ root4star starsim.C                                                     # run the code using STAR's version of ROOT

You're going to see alot of output here, but in the end you'll have two output files:  starsim.kinematics.root and starsim.kinematics.fzd

$ ls
starsim.kinematics.fzd
starsim.kinematics.root
starsim.C
StRoot/

These two files are the so called "zebra" file (.fzd), containing the Monte Carlo hits, geometry and other associated event information, and the event generator record (.root), containing a ROOT TTree which saves all of the particles generated by the primary event generator. 

B. Reconstructing the Events

Once we have the output files, it's time to run them through the reconstruction chain.  STAR's reconstruction code is steered using the "big full chain" macro bfc.C.  For most jobs you'll want to provide BFC three arguements:  the number of events to produce, the set of chain options to run, and an input file.  For more complicated tasks you're encouraged to ask questions on the STAR software list.

Line 6 specifies the geometry model to use.  Generally you need to specify both "agml" and "UseXGeom" here.  (More on this later).  BTW, did you notice that capitalization is ignored? 
Line 7 tells the big full chain that the input will be a zebra file.  This is our standard for now.
Line 8 sets up the TPC simulator.  We perform our digitization of the geant hits in the reconstruction chain.  This is where the TPC hits are converted to ADC values used as input to the reconstruction codes.
Line 9 sets up the track finding and reconstruction codes.  We're using "sti" and "ittf" here.
Line 10 most STAR analyses use the micro DST.  This flag creates it.
Line 11 the "fzd" file contains an event record, which associates MC hits with generated tracks.  This will allow us to (much later) associate the reconstructed tracks with the true Monte Carlo particles from which they came.

$ emacs runBfc.C                    # Feel free to use your favorite editor instead of emacs
0001 | void runBfc() {
0002 |   gROOT->LoadMacro("bfc.C");                  // Load in BFC macro
0003 |   TString _file = "kinematics.starsim.fzd";   // This is our input file
0004 |   TString _chain;                             // We'll build this up
0005 |   _chain += "ry2012a ";                       // Start by specifying the geometry tag (note the trailing space...)
0006 |   _chain += "AgML USExgeom ";                 // Tells BFC which geometry package to use.  When in doubt, use agml.
0007 |   _chain += "fzin ";                          // Tells BFC that we'll be reading in a zebra file.
0008 |   _chain += "TpcFastSim ";                    // Runs TPC fast simulation
0009 |   _chain += "sti ittf ";                      // Runs track finding and reconstruction using the "sti" tracker
0010 |   _chain += "cmudst ";                        // Creates the MuDst file for output
0011 |   _chain += "geantout ";                      // Saves the "geant.root" file
0012 |   bfc(10, _chain, _file );                    // Runs the simulation chain
0013 | }
ctrl-x ctrl-s ctrl-x ctrl-q          # i.e. save and quit
$ root4star runBfc.C                 # run the reconstruction job
$ ls -l
...

If all has gone well, you now have several files in your directory including the MuDst which you'll use in your analysis.

$ ls -1 *.root
kinematics.geant.root
kinematics.hist.root
kinematics.MuDst.root
kinematics.runco.root
kinematics.starsim.root

C. idTruth and qaTruth

During the first phase of the simulation job we had full access to the state of the simulated particles at every step as they propagated through the STAR detector.  As particles propagate through active layers, the simulation package can register "hits" in those sensitive layers.  These hits tell us how much energy was deposited, in which layer and at what location.  They also save the association between the particle which deposited the energy and the resulting hit.  This association is saved as the "idTruth" of the hit.  It corresponds to the unique id (primary key) assigned to the particle by the simulation package.  This idTruth value is exceedingly useful, as it allows us to compare important information between reconstructed objects and the particles which are responsible for them.

Global and Primary tracks contain two truth variables:  idTruth and qaTruth.  idTruth tells us which Monte Carlo track was the dominant contributor (i.e. provided the most TPC hits) on the track, while qaTruth tells us the percentage of hits which thath particle provided.  With idTruth you can lookup the corresponding Monte Carlo track in the StMuMcTrack branch of the MuDst.  In the event that idTruth is zero, no MC particle was responsible for hits on the track. 
With the MC track, you can compare the thrown and reconstructed kinematics of the track (pT, eta, phi, etc...).

Primary vertex also contains an idTruth, which can be used to access the Monte Carlo vertex which it corresponds to in the StMuMcVertex branch of the MuDst.

D. Taking it further

In starsim.kinematics.C we use the StarKinematics event generator, which allows you to push particles onto the simulation stack on an event-by-event basis.  You can throw them flat in phase space, or sample them from a pT and eta distribution.  These methods are illustrated in the macro, which throws muons and pions in the simulation.  You can modify this to suit your needs, throwing whatever particles you want according to your own distribtions.  The list of available particles can be obtained from StarParticleData.
 

$ root4star starsim.C\(0\)
root [0] StarParticleData &data = StarParticleData::instance();
root [1] data.GetParticles().Print()

Additionally, you can define your own particles.  See starsim.addparticle.C.


Primary Event Generation

Geometry Definition

Running the Simulation

Event Reconstruction

The Truth about Event Records