FASER Databases

This page is intended to describe the COOL database information used in the offline simulation, digitization, and reconstruction along with some other auxiliary information. Other databases, including the online DAQ configurations, tracker configuration, and DCS database, are not described here.

Database Conventions

FASER follows ATLAS in using the COOL database API infrastructure. COOL is a library that provides a common interface for databases stored in different technologies, such as Oracle, SQLite, or MySQL. COOL provides a lot of nice features (and ATLAS has written a lot of handy utilities) to make database interactions easier, but it needs to be stressed that COOL will not be supported by CERN past Run3 (at least that is the current claim). The tight integration of COOL into the ATLAS offline software makes it the obvious choice for FASER offline software.

Database Keys

Most offline conditions are fundamentally keyed by run number. FASER does not have 'Luminosity Blocks' like the ATLAS experiment, although there is a plan to fill the luminosity block information in the event header with the raw data file for a given run. As we use the ATLAS infrastructure for providing COOL conditions, filling the luminosity block number in this way would provide a correspondence with each raw file, but also allow conditions to be set on a per-file (approximately one file per minute) basis, rather than a per-run basis. More detail on the format of the keys are given below in the IOV section.

Database Schema

The FASER offline database mostly uses SQLite files as a schema. There is no support for an offline Oracle DB server. The production DB sqlite files are world-readable by cvmfs in the directory /cvmfs/faser.cern.ch/repo/sw/database/DBRelease. Different fixed database releases are stored in cvmfs in separate subdirectories, and a current directory contains the current best knowledge. Any production reconstruction tag other than a prompt reconstruction tag (starting with a p) should specify an explicit DB version in the dblookup.xml file. Prompt reco tags will point to the current directory, which in the future may even be stored and updated on eos.

Most of the offline conditions are stored in the sqlite file named ALLP200.db. There is also a geometry database stored in geomDB_sqlite that really contains pointers to information in external geometry files, also known as POOL files. Currently, the detector channel - detector element assignments (also known as a cable map) are stored in a separate sqlite file CABP200.db. The 200 in the file names relates to a COOL version number 2.0. In the early days of ATLAS is was important to distinguish COOL databases as different COOL formats were not backwards compatible. This is no longer a consideration, but the convention has stuck.

To allow testing of new database entries, the dblookup.xml file specifies multiple schema where conditions can be found for different types of information, in a prioritized list. In particular, the local directory data/sqlite200 will be searched first. So to test a new version of COOL conditions, the sqlite file can be copied to this subdirectory (from the execution directory) and conditions will be loaded from there first. You can also edit the dblookup.xml file in your own release area and point to any file you wish. Be careful, as you can not specify more than one file in the same directory location for a given data type.

Database Names

Inside a given schema (file) there can be multiple different databases stored, each with a different database name (also sometimes called a database instance). The two names used in FASER are CONDBR3 for real data conditions (Conditions DB R3) and OFLP200 for monte carlo conditions. These different databases can contain the same folder structure, or there can be additional folders contained in one DB (usually OFLP200 for MC-specific conditions) compared to the other. When a database file is accessed, the database name must also be specified. In the FASER reconstruction code, real data conditions are loaded from CONDBR3, while simulated data conditions are loaded from OFLP200.

Folders

Inside a database, there is a hierarchal folder structure which looks somewhat like a file system. Conditions related to a particular sub-detector usually share the same top-level folder. Because renaming these from the ATLAS conventions would involve importing a log of ATLAS code from Athena, we have recycled the ATLAS subdetector names. So the tracker conditions tend to be in the /SCT/... folders, while the waveform conditions are in the /WAVE/... folders.

IOVs, Payloads, and Channels

Each folder contains typed data keyed by an IOV (Interval of Validity). The interval of validity is a range in time defined by two unsigned 64-bit integers, but the convention for a Run-LumiBlock keyed folder is that this value is (run<<32 + lumi_block). For folders keyed by time, the value is the UNIX time since the epoch in nanoseconds. The two times in the IOV are the inclusive start time (since) and exclusive end time (until) over which a given set of conditions data are valid. For a given IOV there can be a variable number of channels, which are most often used to indicate conditions that might vary by channel number in a detector. Finally, the actual values are stored in what is known as the payload of the folder. The payload is essentially a key-value dictionary (similar in spirit to JSON) where the keys are always strings, and the value can be usual simple data types (integers, floats, etc). Structured data types (like lists or dictionaries) are not supported in COOL, although unstructured binary data (known as a BLOB) is possible.

Finally, some folders do not contain a payload of values, but rather pointers to external objects. COOL supports a number of possible objects, but by far the most common is an external file containing data, known as a POOL file. In FASER, this mechanism is used to point to the alignment files, which are external ROOT files.

Folder Tags

For a given database folder, COOL provides the ability to have different versions of the conditions available in the same database instance. This mechanism is known as a folder tag, where each tag specifies a version of the conditions in that folder. While this can be a convenient way to test out new conditions, specifying which tag to use for every folder in a job can be a major configuration challenge. With simpler conditions, FASER has mostly avoided tags (aside from the geometry and alignment folders) although this may change in the future.

Offline Reconstruction Conditions

The following describes the conditions used in offline reconstruction. These folders will be present in both the OFLP200 (simulation) and CONDB3 (real data) database instances.

Tracker Reconstruction Conditions

Folder /SCT/DAQ/NoisyStrips

Noisy strips data is produced by the NoisyStripFinder package. This is used in clustering to ignore noisy strips. The actual occupancy threshold for a strip to be considered noisy is set when the information is used, not what is written into the database. Currently, all strips with occupancy greater than 0.001 are written to the DB, so the noisy threshold applied can't be less than this value. The threshold is applied by the FaserSCT_ConfigurationCondAlg algorithm which copies the noisy strip data from the COOL folder into StoreGate. This algorithm is configured here.

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Sensor number (from 0 - 191), 2 sensors per module, 8 modules per layer
sensor	Int32	Should be the same as the channel number
nstrips	Int32	Number of noisy strips found for this sensor
noisyList	String64k	String containing strip:occupancy values

Folder /SCT/DAQ/CableMapping

This folder is found in the CABP200.db schema. This contains the correspondence between the TRB number and the physical tracker geometry. The entries in this database are created using the code here.

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Indicates the TRB number
station	Int32	Station number for this TRB
plane	Int32	Plane number for this TRB

Waveform Reconstruction Conditions

The waveform conditions are in two different subfolders for Calibration and DAQ. The Calibration folders contain conditions to apply the calibrated energy scale to the raw waveform reconstruction. The PMT HV from DCS is stored, along with the reference HV when the calibration was performed and the calibrated MIP signal.

The DAQ folders are used to set the range of the digitizer readout time that is fit by the Waveform reconstruction algorithm. The NominalTriggerTime added to the TriggerOffset should approximately be at the position of the waveform peak. The window (with respect to this time) is set in the WaveformReconstructionTool by the FitWindowStart and FitWindowWidth parameters. Note these are values are by number of waveform samples, not ns.

The waveform DAQ conditions are generated by the code in the WaveCondUtils package and provided by the tools in WaveformConditionsTools.

Folder /WAVE/Calibration/HV

The PMT HV is read in from the DCS and is saved for all digizer channels. The DB is only updated if the HV changed by more than 0.1V. The code that creates this DB folder is found here.

Data	Type	Comments
IOV	Time	Time, in ns since epoch (UTC time zone)
Channel	UInt32	Digitizer readout channel
HV	Float	PMT High Voltage (copied from DCS) with 0.1V deadband

Folder /WAVE/Calibration/MIP_ref

This is the measured reference MIP charge obtained from doing an analysis each time the calorimeter setup changed (i.e. filter installed). This also changes each time we changed from low to high gain with the filter not installed, that way we can avoid using the HV gain curves when we don't have to. The reference MIP charge is obtained by fitting a MIP charge distribution with a Landau+Gaussian convolution function, where the width of the gaussian is set to the measure PMT noise, and then extracting the MPV of the Landau. The code that creates this DB folder is found here.

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Digitizer readout channel
charge_ref	Float	Calibrated charge deposited by MIP
HV_ref	Float	High voltage setting at the time of the MIP calibration

Folder /WAVE/DAQ/Timing

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Always zero
NominalTriggerTime	Float	Nominal trigger time (in ns) of the waveform in the digitizer readout

Folder /WAVE/DAQ/TimingOffset

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	The digitizer readout channel
TriggerOffset	Float	Additional offset added to the Nominal trigger time (in ns) to set the reconstruction window for a specific channel

Folder /WAVE/DAQ/Range

This folder contains the configuration information about the full-scale range (in volts) of the waveform digitizer. The entries in this database are created using the code here.

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Indicates the waveform digitizer channel number
range	Float	Full scale digitizer range (in volts)

Folder /WAVE/DAQ/CableMapping

This folder is found in the CABP200.db schema. This contains the correspondence between the waveform digitizer channel and the physics detector. The entries in this database are created using the code here. The geometry of the different detector types contain different identifiers. To avoid confusion, these are stored in different payload values. So for instance, the calorimeter contains (row, module, pmt) information, while the veto detector contains (station, plate) information.

The meaning of the numbers are defined by the identifiers for the calorimeter and the scintillator detectors.

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Indicates the waveform digitizer channel number
type	String255	Signal type (e.g. veto, calo, trigger, clock)
station	Int32	Station number
plate	Int32	Plane number
row	Int32	Row number
module	Int32	Module number
pmt	Int32	PMT number

LHC Information

These folders store information about the LHC conditions. There are generally swiped from ATLAS and stored into the xAOD::FaserLHCData object per event. The code to update this information can be found in the cool-conditions package.

Folder /LHC/FillData

This time-based folder is filled with one entry per LHC fill. In the end, this is useful to correlate time to LHC fill number. All other quantities can change during the fill, and are included in BeamData below. There are no channels in this folder.

Data	Type	Comments
IOV	timestamp	One entry per LHC fill, update on change, open-ended IOVs
FillNumber	Int32	LHC Fill number uniquely identifies this LHC period

Notes:

• The NumBunchBeam values reflect the LHC fill pattern, but don't guarantee that the bunches are actually filled with non-zero current.

Folder /LHC/BeamData

This time-based folder is filled with entries that vary during a single LHC fill.

Data	Type	Comments
IOV	timestamp	UTC timestamp, update on change, open-ended IOVs
FillNumber	Int32	LHC Fill number uniquely identifies this LHC period
MachineMode	String4k	Status of the LHC machine mode (e.g.: "PROTON PHYSICS")
BeamType1	Int32	Beam1 beam type encoding defined by LHC operation - usually charge of particle (1-proton, 82-lead)
BeamType2	Int32	Beam2 beam type encoding defined by LHC operation - usually charge of particle (1-proton, 82-lead)
BeamMode	String4k	Summary status of the LHC beam state (e.g.: "STABLE BEAMS")
BeamEnergyGeV	Int32	LHC beam energy in GeV
BetaStar	Float	Converted from string, nominal beta-star at Point 1, should be in cm, to be confirmed
CrossingAngle	Float	Converted from string, nominal vertical crossing-angle at Point 1, -1 in case of 'no_value', should be in uRad, to be confirmed
StableBeams	Bool	LHC StableBeams flag (GMT/BIS/hardware version)
InjectionScheme	String4k	String from LHC describing injection pattern (e.g.: "25ns_1465b_1453_1243_1278_144bpi13inj")

Folder /LHC/BCIDData

This time-based folder contains information about which BCIDs contain beam. This data is decoded from the LPC webpage and represents the nominal filling scheme.

Data	Type	Comments
IOV	timestamp	UTC timestamp, update on change, open-ended IOVs
Beam1Bunches	UInt32	number of bunches in beam 1
Beam2Bunches	UInt32	number of bunches in beam 2
CollidingBunches	UInt32	number of colliding bunches
BCIDmasks	Blob64k	Lists of BCID positions of filled/colliding bunches

Following ATLAS, the format of BCIDmasks his is a fixed-length array of 3564 8-bit (char) values where the LSB (bit 0 ) indicates the presence of Beam1, and the nLSB (bit 1) indicates the presence of Beam 2. Colliding bunches are those with both bits set (char value = 0x03).

Other Reconstruction Conditions

The magnetic field and geometry information is used by ACTS in reconstruction, and this information comes from these folders.

Folder /Tracker/Align

For both data and simulation, this is currently read from the OFLP200 DB instance. This should be fixed for real data. This is a multi-versioned folder that contains links to POOL files with the alignment data. There is currently one POOL file per tag stored on cvmfs in the poolcond subdirectory.

Data	Type	Comments
IOV	Run-Lumi	Keyed by run number
Channel	UInt32	Specifies alignment for different detector elements
PoolRef	String4k	POOL file reference

Folder /GLOBAL/BField/Maps

This is a multi-versioned folder containing links to the external file that contains the actual field map. These technically aren't POOL files, as the folder payload is just a string with a file name. The tags specify different geometry epochs for FASER, such as testbeam data, or TI12 collision data. The files are in cvmfs under /cvmfs/faser.cern.ch/repo/sw/software/22.0/faser/offline/ReleaseData/v20/MagneticFieldMaps. To install a new map, see the instructions in FaserSCT_ConditionsData.

Data	Type	Comments
IOV	time	These are stored with time-based IOVs
FieldType	String4k	Type of map
MapFileName	String4k	File name of field map

Folder /GLOBAL/BField/Scales

This is a multi-versioned folder containing an overall scale factor that is multiplied by the values contained in the external field maps.

Data	Type	Comments
IOV	time	These are stored with time-based IOVs
value	Float	Scale factor applied to the external field maps

Offline Simulation/Digitization Conditions

Simulation and digitization conditions are only present in the OFLP200 database instance. These are all multiversioned folders.

Tracker Simulation Conditions

These are all multi-versioned folders.

Folder /SCT/DAQ/Calibration/ChipGain

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Sensor hash (I think)
serialNumber	UInt63
runNumber	UInt32
scanNumber	UInt32
gainRMSByChip	String4k	12 Decimal values stored in string
offsetByChip	String4k	12 Decimal values stored in string
noiseByChip	String4k	12 Decimal values stored in string
noiseRMSByChip	String4k	12 Decimal values stored in string

Folder /SCT/DAQ/Calibration/ChipNoise

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Sensor hash (I think)
serialNumber	UInt63
runNumber	UInt32
scanNumber	UInt32
occupancyByChip	String4k	12 Decimal values stored in string
occupancyRMSByChip	String4k	12 Decimal values stored in string
noiseByChip	String4k	I think this may be a mistake, as it is not filled

Folder /SCT/DCS/CHANSTAT

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Sensor hash (I think)
LVCHSTAT_RECV	Int32
STATE	UInt32

Folder /SCT/DCS/HV

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Sensor hash (I think)
HVCHVOLT_RECV	Int32
HVCHCURR_RECV	UInt32

Folder /SCT/DCS/MODTEMP

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Sensor hash (I think)
MOCH_TM0_RECV	Int32
MOCH_TM1_RECV	UInt32

Waveform Simulation Conditions

Folder /WAVE/Digitization

This folder contains the parameters used to digitize the raw energy deposited in a given scintillator detector. The raw energy is convoluted with a CrystalBall function with the parameters specified. A baseline is also applied. These quantities are in units of ADC counts and ns. The channels indicate the type of detector (0: Calo, 1: VetoNu, 2: Veto, 3: Timing, 4: Preshower). All detectors of a given type have the same digitization parameters.

This folder is created using the makeDigiDB.py script.

Data	Type	Comments
IOV	run-LB	Valid for entire run, from LB range 0-0xFFFFFFFF
Channel	UInt32	Detector channel, as defined above
base_mean	Float	Baseline mean
base_rms	Float	Baseline RMS
cb_norm	Float	CrystalBall normalization
cb_mean	Float	CrystalBall mean
cb_sigma	Float	CrystalBall sigma
cb_alpha	Float	CrystalBall alpha parameter
cb_n	Float	CrystalBall N parameter

Different calorimeter gain settings are applied using different folder tags. This can be passed to faser_digi.py with the --digiTag option.

Folder Tag	Comments
WAVE-Digitization-01-LG	Low gain with filters installed (default)
WAVE-Digitization-01-LG-nofilt	Low gain without filters installed (x10 over -LG)
WAVE-Digitization-01-HG	High gain with filters installed
WAVE-Digitization-01-HG-nofilt	High gain without filters installed (x10 over -HG)

COOL Tools

The following are some useful tools for reading and manipulating COOL databases. These come from ATLAS and will be available when you set up an Athena release.

AtlCoolConsole

This is the best way to see what is really in a COOL database. You can open a database as follows:

AtlCoolConsole.py "sqlite://;schema=ALLP200.db;dbname=CONDBR3"

The schema specifies the file to open, while the dbname specifies the instance. The format comes from ATLAS CoolConnections strings. We don't need to specify a server, as we will always be dealing with local files.

Once a database is open, AtlCoolConsole provides a shell-like interface. So you can use cd and ls to navigate around the folder structure, and in a given folder, the more . command will dump the current folder contents. Since this can be a lot of data, you can select a range of IOVs using userunlumi, and you can select a specific channel using usechan. For folders that have been versioned, you must select a tag with usetag before you will see any data. To see the tags available in the current folder, use the command showtags .. Don't forget the dot to specify the current folder, or else you won't see any tags specified.

More information on this utility can be found on the ATLAS Twiki page for AtlCoolConsole.

AtlCoolCopy

This is the only method for merging a new folder, or new entries in an existing folder, into an sqlite file. If you need to update ALLP200.db, for instance, you would first copy this from the production cvmfs area to a local directory with

cp /cvmfs/faser.cern.ch/repo/sw/database/DBRelease/current/sqlite200/ALLP200.db .

Then you can copy the folders in a local file mysqlite.db into ALLP200.db using AtlCoolCopy. The copy is done using CoolConnections strings just like AtlCoolConsole above.

AtlCoolCopy "sqlite://;schema=mysqlite.db;dbname=CONDBR3" "sqlite://;schema=ALLP200.db;dbname=CONDBR3"

There are a number of useful options for AtlCoolCopy, including the ability to only copy specific folders, time ranges, channels, and so on. If you need to completely replace a folder, you should first copy ALLP200.db to a temporary DB using the -exclude option. This will copy everything except the specified folder. Then you can copy that folder into the temporary file. If you try to overwrite a folder that already exists, and you are not just appending new values to the end of the folder, AtlCoolCopy may refuse to perform the operation, as it doesn't know how to merge the information.

More information on this utility can be found on the ATLAS Twiki page for AtlCoolCopy.

-- EricTorrence - 2022-09-17