Detector Conditions

HPS uses a database conditions backend which is accessible through the DatabaseConditionsManager.

Basic Usage

Initialization

The conditions system is initialized using the ConditionsManager's setDetector method which takes the name of a detector and a run number.

DatabaseConditionsManager.getInstance().setDetector("RealDetectorNameHere", 1234);

HPS adds several features to the lcsim conditions system.

You can add one or more tags for filtering the conditions records.  Only those records belonging to the tag will be accessible.

DatabaseConditionsManager.getInstance().addTag("pass0");

The conditions system can be "frozen" after it is initialized, meaning that subsequent calls to set a new detector and run number will be completely ignored.

DatabaseConditionsManager.getInstance().freeze();

This is useful to force the system to load a specific configuration by run number if the actual event data does not have the same run number (or for run 0 events from simulation).

Typically, the conditions system will be initialized for you automatically or configured using switches to the various HPS Java command line tools (exact syntax depends on the tool).

Accessing Conditions from a Driver

Typically, conditions information is accessed in the beginning of the job through the Driver class's detectorChanged method.

public void detectorChanged(Detector detector) {
    DatabaseConditionsManager conditionsManager = DatabaseConditionsManager.getInstance();
    EcalChannelCollection channels = 
            conditionsManager.getCachedConditions(EcalChannelCollection.class, "ecal_channels").getCachedData();
    System.out.println("got " + channels.size() + " ECal channels");
}

Typically, all conditions collections required by a Driver should be loaded in this method to avoid incurring a performance overhead by reading the conditions on every event.

You can also access collections not associated to the current run by providing the collection ID.

DatabaseConditionsManager conditionsManager = DatabaseConditionsManager.getInstance();
EcalGainCollection gains = new EcalGainCollection();
gains.setConnection(conditionsManager.getConnection());
gains.setTableMetaData(conditionsManager.findTableMetaData("ecal_gains");
gains.select(1234); /* where number is a valid collection ID in the database */

This can be used to retrieve reference data that is not accessible in the conditions for the run.

Conditions Types

Conditions Type Table

Database Schema

Data Tables

Each type of condition has an associated database table which contains records with conditions information plus a few additional pieces of information.  These tables are modeled by the ConditionsObjectCollection class.

mysql> describe beam_energies;
+---------------+---------+------+-----+---------+----------------+
| Field         | Type    | Null | Key | Default | Extra          |
+---------------+---------+------+-----+---------+----------------+
| id            | int(11) | NO   | PRI | NULL    | auto_increment |
| collection_id | int(11) | NO   |     | NULL    |                |
| beam_energy   | double  | NO   |     | NULL    |                |
+---------------+---------+------+-----+---------+----------------+
3 rows in set (0.00 sec)

The id is the row ID used to uniquely identify the record.  The collection_id associates a set of records together into a collection.  Every data table has these two fields plus additional columns with the conditions data.

Conditions Table

The conditions table associates collections with a run number range.

mysql> describe conditions;
+---------------+--------------+------+-----+-------------------+-----------------------------+
| Field         | Type         | Null | Key | Default           | Extra                       |
+---------------+--------------+------+-----+-------------------+-----------------------------+
| id            | int(11)      | NO   | PRI | NULL              | auto_increment              |
| run_start     | int(11)      | NO   |     | NULL              |                             |
| run_end       | int(11)      | NO   |     | NULL              |                             |
| updated       | timestamp    | NO   |     | CURRENT_TIMESTAMP | on update CURRENT_TIMESTAMP |
| created       | datetime     | NO   |     | NULL              |                             |
| tag           | varchar(256) | YES  |     | NULL              |                             |
| created_by    | varchar(255) | YES  |     | NULL              |                             |
| notes         | longtext     | YES  |     | NULL              |                             |
| name          | varchar(40)  | NO   |     | NULL              |                             |
| table_name    | varchar(50)  | NO   |     | NULL              |                             |
| collection_id | int(11)      | NO   |     | NULL              |                             |
+---------------+--------------+------+-----+-------------------+-----------------------------+
11 rows in set (0.01 sec)

The run_start and run_end give a range of run numbers for which the conditions are valid.  These can be the same number to specify a single run.

The table_name gives the name of the table containing the conditions data.

The collection_id gives the collection ID to load from the table.

This table is modeled by the ConditionsRecord class which is accessible via the DatabaseConditionsManager.

When multiple collections of the same type are valid for the current run, the most recently added one will be used by default.

Defining Conditions Classes

New conditions classes should follow a basic template which provides information about its associated database tables and columns.

For example, here is the definition for the BeamEnergy condition.

@Table(names = {"beam_energies"})
public final class BeamEnergy extends BaseConditionsObject {

    public static final class BeamEnergyCollection extends BaseConditionsObjectCollection<BeamEnergy> {
    }

    @Field(names = {"beam_energy"})
    public Double getBeamEnergy() {
        return this.getFieldValue("beam_energy");
    }
}

The @Table annotation on the class maps the class to its possible database tables.  Typically, this is a single value.

The @Field annotation is applied to a method which should be mapped to a column in the database.  The method must be public.