Access to calibration data in OEP

[Incomplete and still under construction, 99.04.18]

Calibration data produced in a read-out module (ROM) in the Dataflow system using the standard (DNB) calibration framework classes is always wrapped inside a "CalDataTC" object. Discussion of their content is beyond the scope of this note; see DNB's documentation for details. Here we discuss only how to access the objects.

Data from ROMs is, in general, available in OEP in a type-safe way through the "odfModuleScan<YTC>" interface. In ordinary data-taking, the "YTC" template argument class is the detector-subsystem-specific type of the subsystem's feature extraction "output container" (which must inherit from odfXTC). The interface provides a simple forward iterator over all ROM-level objects of type YTC in the event, supplying their associated odfdAdr and odfpAdr addresses and DataFlow damage values in the process. The interface originally inherited from odfTCIterator and so follows the same post-increment semantics used in that class. The inheritance has since been removed, but the behavior is still the same. Since this is an infamous source of confusion, a suggestion on how to work with this is appended at the bottom of this note.

Objects of the abstract odfModuleScan<YTC> type are requested from the AbsEvent in OEP Framework modules using ProxyDict:

   odfModuleScan<YTC>* ytcp =
     Ifd< odfModuleScan<YTC> >::get( AbsEvent*, const IfdKey& );

(NB: as usual, this does not return ownership of the scanner to the caller, and thus the caller must not delete it.)

The IfdKey "secondary key" is usually obtained through an AbsParmIfdStrKey TCL parameter in the Framework module, and is set to match the one used by the creator of the odfModuleScan<YTC>.

For data transported by DataFlow, the current method for constructing an odfModuleScan<YTC> in an OEP application is for the user to include an OepFSimpleModScanMaker<YTC> module in the AppUserBuild for the application. This module can be configured with the desired secondary key for the odfModuleScan<YTC> to be produced. IfdStrKey("Default") is the default for this, which should in general note be modified.

The same interface applies to calibration data, but there are two complications. First, it's not possible in calibration to distinguish subsystems from each other using the template argument of the odfModuleScan. The interface will always be "odfModuleScan<CalDataTC>". For multi-subsystem calibrations, users will have to test the odfdAdr values returned in the iteration over CalDataTC objects in order to distinguish different subsystems' data. (A "restricted odfModuleScan" design that would simplify this exists but has not been implemented, due to lack of resources.)

The second complication is large-datagram support. The basic OepFSimpleModScanMaker<YTC> produces a scanner which knows only about the primary event from DataFlow. In large-datagram mode, however, the actual CalDataTC objects are not transported in the DataFlow event. Instead, for each ROM, the event contains a small odfFileXTC object which carries an encoded file name, relative to a presumed root directory (which normally will be on the IR-2 server); the actual CalDataTCs are stored in these files, ROM by ROM, in ".xtc" format.

In order to accommodate this, we have provided a new type of module-scanner-maker which understands this system and can retrieve files from disk. The abstractness of the odfModuleScan<YTC> interface allows this to be done nearly transparently to user code.

The new module-scanner-maker module is OepFFileXTCModScanMaker<YTC>. It presumes that it can find in the AbsEvent "ordinary" module scanners for both YTCs and odfFileXTCs. (The secondary keys it uses for these are settable via TCL parameters, which default to "Default".) It then creates in AbsEvent a new odfModuleScan<YTC> which can iterate over both "primary event" YTCs and "file-based" YTCs. To avoid key collisions, since it has the same ProxyDict type as the "primary event" odfModuleScan<YTC>, the module creates the new scanner with a different secondary key, also controllable via TCL, with a default of "FileXTCs".

Currently, due to a limitation in the odfModuleScan interface which is only lifted in post-8.0.1 releases, the "combined scanner" has an either-or behavior: if it finds any YTCs in the primary DataFlow event, it will return only those, and not proceed to look for file-based ones. If it finds no YTCs in the primary event, it will then return any file-based YTCs it can find in the event.

Files are read in "lazily" - only when the scanner must actually return a pointer to the corresponding YTC. The YTCs are retained in memory until the scanner is deleted (normally with the AbsEvent).

In order to make this all more convenient for calibration users, the creation of the three module scanners: primary-event-CalDataTC, primary-event-FileXTC, and primary-and-file-based-CalDataTC, has been combined into a single Framework sequence: CalOffline/CalOepModScanSequence.{hh,cc,tcl}.