Running SLIC Events in Pandora PFA New

Overview

The SLIC simulation package produces simulated physics events in the LCIO data format. This tutorial shows how to read these events into the Pandora PFA New project to create output Particle Flow Objects (PFOs).

Setup

Preliminaries

A Linux or Unix platform is assumed and the bash shell is used for all command-line instructions. These procedures should also work on an emulation platform like Cygwin. (untested!)

Two external packages must be installed onto your machine before setting up the SLIC to Pandora interface package. The LCIO package provides the data interchange format. The Pandora PFA New project is the C++ implementation of the Pandora Particle Flow Algorithm (PFA).

LCIO Installation

Checkout the LCIO project from cvs.

cd /workdir
cvs -d :pserver:anonymous@cvs.freehep.org:/cvs/lcd co lcio

Building this project requires the CMake tool, the installation of which is not covered here. It additionally requires command-line GNU Make.

cd lcio
cmake .
make

Pandora PFA New Installation

Now download the Pandora project from the internet and build it. This project also requires CMake to build it.

Follow this link to download the SVN trunk of the Pandora project. Save it to your local computer (in this case to a pandora subdirectory).

cd /workdir/pandora
tar -zxvf PandoraPFANew-trunk.tar.gz
cd trunk
cmake .
make

Now we're ready to setup the project that interfaces SLIC to Pandora.

slicPandora Installation

Checkout the slicPandora project from cvs.

cd /workdir
cvs -d :pserver:anonymous@cvs.freehep.org:/cvs/lcd co slicPandora
cd slicPandora

Copy the example setup script.

cp example_setup.sh my_setup.sh

Edit my_setup.sh so that the PANDORAPFA and LCIO variables point to the correct locations of these packages on your computer (from the installation above).

Source the new setup script.

. my_setup.sh

Build the slicPandora project.

make

The slicPandora project should now build successfully. If compilation or linking errors occur, then check that LCIO and Pandora were installed successfully and that the setup script is pointing to the correct locations of these packages.

Running Events

Overview

The essential steps to generating slicPandora events are as follows.

1) Use SLIC to generate LCIO simulation data.
2) Add tracks to the event by running a tracking package such as LCSim's SeedTracker.
3) Add the TrackState collections so slicPandora knows the Track momenta. (can be combined with #2 into one LCSim job)
4) Finally, run slicPandora with the LCSim output, a Pandora XML geometry generated by GeomConverter, and a Pandora settings XML file.

These steps are covered in more detail below.

LCSim

Before the simulated LCIO events can be run through Pandora, the LCSim tracking needs to run in order to add a collection of tracks. LCSim can be run using the steering file, sidloi3_tracking_steering.xml.

java -jar ./lcsim.jar sidloi3_tracking_steering.xml

The input files section needs to be changed to point to your local simulated SLIC events.

If you don't have a working LCSim setup, follow the LCSim XML instructions to set one up.

The LCSim job must accomplish three tasks before the events can be read into Pandora, in this order.

1. Generation of a Tracks collection using an appropriate Seed Tracker Driver.
2. Adding TrackState collections using the SeedTrackerTrackState Driver.
3. Writing out the necessary LCIO collections to a data file to be read into Pandora.

To generate the Tracks, a top-level Driver should be run that covers subdetector setup, digitization, and track finding and fitting. This top-level Driver will likely be specific to a certain detector design.

For instance, this simple Driver definition is sufficient to generate tracks in the sidloi3 detector.

 <driver name="MainTrackingDriver"
         type="org.lcsim.recon.tracking.seedtracker.trackingdrivers.sidloi3.MainTrackingDriver"/>

Three TrackState collections need to be added to the LCIO output to provide Pandora with track information at the track origins, the ECal, and the end point.

The following Driver in the Seed Tracker package will add these necessary TrackState collections. This Driver also requires that another Driver be run beforehand to cache Calorimeter subdetector data.

<driver name="CalInfoDriver"   
        type="org.lcsim.recon.util.CalInfoDriver"/>
<driver name="TrackStateDriver"
        type="org.lcsim.recon.tracking.seedtracker.SeedTrackerTrackStateDriver"/>

Finally, an LCIODriver should be added to the end of the event processing to output the appropriate collections.

<driver name="Writer"
        type="org.lcsim.util.loop.LCIODriver">
            <outputFilePath>OUTPUT_FILE</outputFilePath>
            <writeOnlyCollections>BeamCalHits EcalBarrelHits EcalEndcapHits HcalBarrelHits HcalEndcapHits MuonBarrelHits MuonEndcapHits Tracks StateAtECal StateAtEnd StateAtStart MCParticle MCParticleEndPointEnergy SiVertexBarrelHits SiVertexEndcapHits SiTrackerBarrelHits SiTrackerEndcapHits SiTrackerForwardHits LumiCalHits</writeOnlyCollections>
</driver>

The OUTPUT_FILE argument needs to be replaced with the actual name of the LCIO output file to be fed to Pandora.

Once these Drivers are defined in the <driver> section of your LCSim XML file, the execution order should look like the following.

<execute>
    <driver name="CalInfoDriver"/>
    <driver name="MainTrackingDriver"/>
    <driver name="TrackStateDriver"/>
    <driver name="Writer"/>
</execute>

Now that tracks and track states have been added to the events, we are ready to use Pandora itself.

The final LCSim XML file should look something like the example below.

<lcsim xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
        xs:noNamespaceSchemaLocation="http://www.lcsim.org/schemas/lcsim/1.0/lcsim.xsd">
    <inputFiles>
        <file>/u/ey/jeremym/work/jobs/2010-04-09_slicPandora_single_particles/lcio/slic/pi_Theta90_10GeV-0-1000_SLIC-v2r8p3_geant4-v9r3p1_QGSP_BERT_sidloi3.slcio</file>
    </inputFiles>
    <control>
        <numberOfEvents>1000</numberOfEvents>
        <verbose>true</verbose>
        <printSystemProperties>false</printSystemProperties>
    </control>
    <execute>
        <driver name="EventMarkerDriver"/>
        <driver name="CalInfoDriver"/>
        <driver name="MainTrackingDriver"/>
        <driver name="TrackStateDriver"/>
        <driver name="Writer"/>
    </execute>
    <drivers>
        <driver name="CalInfoDriver"   
                type="org.lcsim.recon.util.CalInfoDriver"/>
        <driver name="MainTrackingDriver"
                type="org.lcsim.recon.tracking.seedtracker.trackingdrivers.sidloi2.MainTrackingDriver"/>
        <driver name="EventMarkerDriver" 
                type="org.lcsim.job.EventMarkerDriver">
            <eventInterval>10</eventInterval>
        </driver>
        <driver name="TrackStateDriver"
                type="org.lcsim.recon.tracking.seedtracker.SeedTrackerTrackStateDriver"/>
        <driver name="Writer"
                type="org.lcsim.util.loop.LCIODriver">
            <outputFilePath>/u/ey/jeremym/work/jobs/2010-04-09_slicPandora_single_particles/lcio/lcsimTracking/pi_Theta90_10GeV-0-1000_SLIC-v2r8p3_geant4-v9r3p1_QGSP_BERT_sidloi3_lcsimTracking.slcio</outputFilePath>
            <writeOnlyCollections>BeamCalHits EcalBarrelHits EcalEndcapHits HcalBarrelHits HcalEndcapHits MuonBarrelHits MuonEndcapHits Tracks StateAtECal StateAtEnd StateAtStart MCParticle MCParticleEndPointEnergy SiVertexBarrelHits SiVertexEndcapHits SiTrackerBarrelHits SiTrackerEndcapHits SiTrackerForwardHits LumiCalHits</writeOnlyCollections>
        </driver>
    </drivers>
</lcsim>

The above example will likely not work in your environment. The data file names should be changed to match those that you have available.

PandoraFrontend

The PandoraFrontend binary provides a simple frontend to slicPandora.

The syntax of this command is the following.

./bin/PandoraFrontend geometry.xml pandoraSettings.xml inputEvents.slcio reconOutput.slcio [nevents]

The nevents command is optional, but all other arguments are required and must be supplied in order.

For example, to repeat the results of the JobManagerTest using PandoraFrontend, execute this command.

./bin/PandoraFrontend ./examples/sidloi3_pandora.xml ./examples/PandoraSettingsNew.xml ./input.slcio ./pandoraRecon.slcio 2

The above command requires that the input events were generated in the sidloi2 detector and that a symlink has been setup pointing from "input.slcio" to your input event file.

Using GeomConverter to Output the Pandora Format

The GeomConverter package can convert from compact detector descriptions to various output formats, including one for input to slicPandora. (Installation of GeomConverter is not covered here.)

Use this command from your GeomConverter root directory to generate a Pandora geometry file from a compact detector description.

java -jar ./target/GeomConverter-1.10-SNAPSHOT-bin.jar -o pandora ./myCompactDetector.xml ./myPandoraGeom.xml

This will write out a Pandora XML file to "myPandoraGeom.xml" from the compact description in "myCompactDetector.xml".