Writing Event Drivers

What is a Driver

In HPS Java terminology, a Driver processes events and can read or add collection data. A Driver can create histograms from physics data or implement a step of physics reconstruction. Drivers are executed in order, and a Driver can have child Drivers to implement complex behavior. A chain of Drivers is activated by the "mother of all drivers" which contains a list of the top level Drivers as children.

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

    protected void detectorChanged(Detector detector) {
    }
    
    protected void endOfData() {
    }

    protected void startOfData() {        
    }
 
    public void setValue(int value) {
        this.value = value;
    }
}

Event Processing Hooks

Execution Order

Order	Method	Explanation
1	Driver constructor	no argument constructor activated when Driver created
2	Driver setters called	set methods called individually for different parameters (by JobManager)
3	startOfData	data processing has started but detector conditions not initialized yet
4	detectorChanged	activates after detector conditions are initialized so Driver can perform any necessary setup
5	process	called once for every event in the job default behavior of parent class executes child drivers
6	endOfData	end of data processing hook histograms can be normalized/scaled in this method

process method

The process method is called once for every event. This method typically implements the main event processing algorithm of the Driver. Collections can be read from the event and their data plotted, or new data collections can be added to the event using this method. The default implementation of this method in the Driver class calls the process method of all the child Drivers.

startOfData method

The startOfData method is activated at the beginning of data processing but before detector conditions are initialized. Any setup that needs to be performed which is independent of the detector information can be implemented here.

detectorChanged method

The detectorChanged method is called after the conditions system is initialized.

Steering Files

The lcsim xml format can describe drivers and their parameters at runtime using an XML data description. The Guidelines for Creating Compatible Drivers describes how to write a Driver so that it can be using in the XML steering files.

Here is sample XML which calls the ExampleDriver and sets a parameter value on it.

<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 are read from the event using the get method of the EventHeader class which will return a list of objects.

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

You may also get all collections of a given type by not providing a collection name which will return a "list of lists."

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.");
        }
    }
}

Search/Navigation:

Related: