What is a Driver

In HPS Java terminology, a driver processes events and can read or add collection data.  A driver may create histograms from physics data or implement a physics reconstruction algorithm.  Drivers are executed in order, and a driver may have child drivers in order to implement complex, hierarchical behavior.

The following is a toy example of a driver which prints information to the console at certain points in the job processing.

Driver Example

package org.hps.users.jeremym;

import org.lcsim.event.EventHeader;
import org.lcsim.geometry.Detector;
import org.lcsim.util.Driver;

public class ExampleDriver extends Driver {

    private int value;
  
    public void process(EventHeader event) {
        System.out.println("Processing event " + event.getEventNumber());   
    }

    protected void detectorChanged(Detector detector) {
        System.out.println("Detector name is " + detector.getDetectorName());
    }
    
    protected void endOfData() {
        System.out.println("Read all the data.");
    }

    protected void startOfData() {        
        System.out.println("Starting the job.");
    }
 
    public void setValue(int value) {
        this.value = value;
    }
}

 

Event Processing Hooks

Each driver may implement one or more job processing hooks which are activated by the framework in the following order.

Execution Order

OrderMethodExplanation
1Driver constructorThe driver's constructor is activated at the very beginning of the job. it should not take any arguments.
2Driver setters calledA driver's setter methods are called based on parameters defined in the steering file.
3startOfDataThis is activated at the beginning of the job after drivers are created and configured but before a specific detector configuration is activated.
4detectorChangedThis hook activates when detector conditions are initialized so that a driver may can perform detector-specific setup and configuration.
5process

This is the main processing hook which is called once for every event in the job.

The default implementation of this method will execute a driver's child drivers, if it has any.

6endOfData

This is the end of data processing hook.

Histograms may be normalized/scaled in this method based on the number of events that were processed, for instance.

Steering Files

The lcsim xml format describes a chain of drivers and their parameters using an XML data description.  The Guidelines for Creating Compatible Drivers documentation describes how to write a driver so that it can be using within an XML steering files.

Here is sample XML file which calls the ExampleDriver defined above and sets a parameter value.

<lcsim xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="http://www.lcsim.org/schemas/lcsim/1.0/lcsim.xsd">       
    <execute>
        <driver name="ExampleDriver"/>
    </execute>    
    <drivers>
        <driver name="ExampleDriver" type="org.hps.users.jeremym.ExampleDriver">
            <value>1234</value>
        </driver>
    </drivers>
</lcsim>

Processing Data

Reading Event Data

Data collections can be read from the event using the get method of the EventHeader class which will return a list of physics objects.


Here is an example of accessing the ECal hits collection and printing out the hit energies:

public void process(EventHeader event) {        
    List<CalorimeterHit> hits = event.get(CalorimeterHit.class, "EcalHits");
    for (CalorimeterHit hit : hits) {
        System.out.println("calorimeter hit has energy " + hit.getCorrectedEnergy() + " GeV.");
    }
}

You may also get all the collections with a given object type:

public void process(EventHeader event) {        
    List<List<CalorimeterHit>> collections = event.get(CalorimeterHit.class);
    for (List<CalorimeterHit> hits : collections) {    
        for (CalorimeterHit hit : hits) {
            System.out.println("calorimeter hit has energy " + hit.getCorrectedEnergy() + " GeV.");
        }
    }
}

Collection Metadata

Each collection in the event has an associated metadata object with information about it.

public void process(EventHeader event) {        
    List<List<CalorimeterHit>> collections = event.get(CalorimeterHit.class);
    for (List<CalorimeterHit> hits : collections) {    
        System.out.println("found Calorimeter collection: " + event.getMetaData(hits).getName());
    }
}

 

You must provide the list object as a key in order to retrieve this metadata.

Writing Event Data

New collections can be added to the event using the put method of EventHeader.

public void process(EventHeader event) {        
    // Create new collection somehow!
    List<Track> myFancyTracks = createFancyTracks(event);
 
    // Put new collection into the event.
    int flag = 1 << LCIOConstants.TRBIT_HITS;
    event.put("MyFancyTracks", fancyTrackCollection, Track.class, flag);
}

The flags are an integer bit mask with values defined in the LCIOConstants class.  This controls some of the IO behavior of the LCIO format.

AIDA Histogramming

Histogramming of event data can be done using the AIDA utility class which provides a simplified wrapper to the AIDA plotting interface.

private AIDA aida = AIDA.getInstance();
 
public void process(EventHeader event) {        
    List<CalorimeterHit> hits = event.get(CalorimeterHit.class, "EcalHits");
    for (CalorimeterHit hit : hits) {
        aida.cloud1D("Cal Hit Energy").fill(hit.getCorrectedEnergy();
    }
}

AIDA provides facilities for creating many different types of analysis objects such as histogrmas.  Refer to the AIDA API for full details.


  • No labels