Identifier Dictionary Documentation

$Date: 2003-05-16 10:18:24 $
$Revision: 1.1.1.1 $
Editors: C. Arnault, RD Schaffer


1. - Overview

The software notes: ATL-SOFT-2001-004 and ATL-MUON-2001-014 describe the offline identifier scheme for the various detectors, where the latter note is just for the muons. The identifiers are hierarchically structured following a logical decomposition of the ATLAS detector. For example, the top level specifies the detector system (InnerDetector, LArCalorimeter, TileCalorimeter, MuonSpectrometer) and the next level down typically specifies the detector subsystem (pixel, sct, etc.). Subsequently there may be a level which distinguishes between barrel or endcap, or a level which specifies which layer or defines the eta/phi numbering within a layer. The muon system scheme is somewhat different in that they first identify the stations of the muon system and then the different detector technology within each station.

This scheme is currently being used to identify individual readout channels and as well corresponding "detector elements", where a detector element is a higher level grouping of a number of readout channels. For example, the silicon wafers server as "detector elements" for the pixels and SCT.

The readout and detector element identifiers are being used in a variety of ways. For example, the High Level Trigger is accessing data limited to regions of interest by geometrical eta/phi regions into lists of detector element identifiers which specify which bytestream data to decode and make available. Another important use is to connect the readout data its their corresponding detector description information, for example, to calculate positions or energies.

The software infrastructure to support this work can be split into three parts:

Identifier structure

The identifier specification is captured by an "identifier dictionary" which is in the IdDict package. The values allowed for the identifiers of each subsystem can be expressed in terms of a set of "regions" where for each region one provides the allowed values for each of the levels. For example, for the pixel detector, the channel numbering on each wafer is the same. The number of wafers varies in each layer in the barrel, but the endcap disks are all similar. Thus, one is able to describe the pixel identifier numbering with only four regions: one for each of the three layers in the barrel and one for the endcaps.

Today, the region description is specified in XML (eXtended Markup Language) in an ASCII file. The dictionary reads the XML descriptions and maintains them in memory. There is a dictionary manager (IdDictMgr) which holds a dictionary for each detector system (InnerDetector, LArCalorimeter, TileCalorimeter, MuonSpectrometer). Each dictionary provides three primary functions:

  • Access to its "fields", where each level in the identifier hierarchy corresponds to a single field. Thus, a client who "knows" the names of the different levels in of identifier may get their index or level number.
  • Access to the allowed values for the identifiers of a particular subsystem (or region). The allowed values are captured by a MultiRange object, discussed in more detail in section (2. Range and MultiRange classes). The allowed values may correspond to the full identifiers down to the readout channel level, or one may request the allowed values for a limited number of levels, for example just for the detector elements.
  • Packing and unpacking of compact identifiers. The MultiRange objects provide identifiers in an expanded form. It is the dictionary that "knows" how to compactify them.

Identifier creation and interpretation

There are helper classes for each detector subsystem which interact with the identifier dictionary to allow creation of the required identifiers as well as their corresponding interpretation (see IdHelper classes and tests). For the InnerDetector, these classes are PixelID, SCT_ID and TRT_ID which reside in the InDetIdentifier package. These classes are used to create Identifier objects, for example, when constructing a digit or a readout object by providing the helper class with the set of indices for the various levels of the identifier. One also uses the helper classes to extract from an Identifier object the information as to whether it belongs to the barrel or endcap, its layer number, etc.

The helpers are intialized from the information in the dictionary. They are stored in the Athena Detector Store and are accessed via the detector description managers for each system. They provide the interface to manipulate identifiers for the rest of the software, e.g. Athena algorithms.

Identifier classes

There are three different identifier classes used in the software (which can be found in the Identifier package below DetectorDescription):
  • Identifier - compact 32-bit identifier
  • IdentifierHash - compact 32-bit identifier which can be used a a compact hash code for direct access
  • ExpandedIdentifier - an identifier whose fields are "expanded", for example, into an internal vector, providing fast access to the value of any field.

The first two forms, Identifier and IdentifierHash, are the objects which are widely used in the software to provide the identification of readout channels and detector elements. The expanded form is primarily used by the helper classes and the dictionary.

The Identifier class contains the id values of the different levels packed into a 32-bit word. For a given subsystem, one may obtain different Identifier objects depending upon the number of levels included. For example for the pixels, an Identifier which identifies "detector elements" includes levels from "InnerDetector" down to "eta module" which corresponds to the individual wafers. Similarly for the muons, one can identify stations, MDT multilayers or layers or tubes all with different sets of Identifier objects. For any set of objects, e.g. a set up rpc readout strips, the identifiers can be used as a search key with corresponding log(N) lookup time. The interface of the Identifier class is quite simple. Its primary method is just the comparison operator (operator <) so that it behaves as a "type-safe unsigned int".

The IdentifierHash class is similar the Identifier class - it basically is a "type-safe unsigned int". However, it is used to distinguish the special where the total number N of a set of objects is known. In this case, one is able to transform a packed Identifier into a "hash" code with a value from 0 to N-1, and thus perform constant-time lookup, for example in a simple vector. In general, hash tables provide constant-time lookup, however, one must trade-off the cost of converting a key into a hash code and allow for clashes (where two different keys may convert into the same hash code and must be treated specially). For our situation, it is the "detector elements" which in general will be identified with IdentifierHash. This allows a fast lookup, for example, when using IdentifiableContainer to collect raw data objects within regons of interest, or when fetching the transformation matrices for the detector elements from the detector store.


2 - IdDict dictionary specification

The identifier dictionary describes the possible identifier ranges. One may describe several identifier dictionaries. Currently there is one dictionary for the top identifier level and one for each detector system.

A dictionary is identified by its name and may contain the follow three elements:


3 - Range and MultiRange classes

A Range class corresponds to the region specification of the dictionary (see idDict region). This effectively captures the a range of values for each of the identifier levels for a region or subset of identifiers. The Range class interacts with the ExpandedIdentifier class. This class can be found in the Identifier package under DetectorDescription. The Range interface provides: The MultiRange class is simply a "container" class for more than one Range. It is a MultiRange that can represent a full Identifier specification for the identifiers of a subsystem.


4 - IdHelper classes and tests

For each detector system there are separate helper classes for each subsystem which allow creation and interpretation of the various kinds of identifiers. These classes are the "servers" for any client who needs to know more about an identifier than simply using it as a lookup key. These classes "pre-digest" the information in the identifier dictionary. We provide here some of the details of the helper classes developed for the InnerDetector to allow other helper classes to be developed.

4.1 - IdDictTest algorithm

There is a test algorithm IdDictTest under AtlasTest/DetDescrTest which serves as an overall test of the idhelpers. For the inner detector, tests are performed by comparing detector element identifiers which are obtained from the detector description manager (derived from the geant 3 information) with the detector elements identifiers provided by the helpers. This check assures that the sets of identifiers are identical and has been used to correct the XML specification which is the source for the idhelpers.

4.2 - PixelID example

We take as an example the PixelID class which is the helper class for the Pixel ids (in package InDetIdentifier under InnerDetector/InDetDetDescr).



Warning : this document is under construction