Overview

This application is integrated into atlaspixeldaq, and provides functionality to understand the status of detector tuning and configuration, as well as its evolution over time. This is achieved by reading config files, intefacing with the Coral database. Below the basic principles are described:

File Selection

The application connects to Coral, and for each module retrieves a list of config files corresponding to the requested module config tag, labelled by production ID and timestamp eg. M512512_001649244089000.root. Out of these files, the one is selected which is most 'recent', compared to the time requested. The application then looks for this file in the specified location, and if it cannot be found an error is thrown.

Disable Tags

In addition to the enable/disable masks in the config files (see 'Hard-Coded Enable Variables' below), entire modules and rods can be disabled. This information is stored in a separate file, eg. PIT_DIS_001646065678000.root. Similar to the config files, the file closest (but before) the requested time is used.

Position Information

In order to get information on the position of each module, the production ID (labelling config files) cannot be used. Coral is used to retrieve the module ID for each eg. LI_S06_A_M4_A7. This ID contains information on the detector region it is in, as well as its position within that region, used to create plots. For more information on the conventions governing this, see PixelCOOLoffline.

Usage

EvolutionMonMultiple

Generate information on the state of the detector at multiple times, as well as the way its state has evolved over time.

Example call on the command line:

EvolutionMonMultiple -d "path/to/config/files" -t "2021-06-08T00:00:00,2022-04-27T00:00:00,2022-10-27T00:00:00" -c "PIT_MOD,PIT_MOD_TUNED_RUN3_NM,PIT_MOD" -v "/path/to/vars.txt" -x "PIT_DIS,PIT_DIS,PIT_DIS"   

Flags for use (for explanation of how these are used see relevant sections below):

Flag	Status	Description
-d	Mandatory	Path to directory containing config files (in directories by ProdId)
-t	Mandatory	Comma separated list of UTC times in format YYYY-MM-DDThh:mm:ss.
-c	Mandatory	List of module config tags to be used at the corresponding times eg 'PIT_MOD'
-v	Mandatory	Path to file specifying variables (see 'Defining Variables' below)
-x	Mandatory	List of disable tags to use at corresponding times eg. 'PIT_DIS'
-n	Optional (for testing purposes)	Max number of modules to read

Output: single 'snapshot' at each time/config set specified, as well as evolution plots (see 'Plot Types' below for details)

EvolutionMonSingle

Generate plots showing the state of the detector at a given time, for a given set of tags.

Example call on the command line:

EvolutionMonSingle -d "/path/to/config/files" -t "2021-06-08T00:00:00" -c "PIT_MOD_B5600_LD4300" -v "path/yo/vars.txt" -x "PIT_DIS_EFR"

Flags for use (for explanation of how these are used see relevant sections below):

Flag	Status	Description
-d	Mandatory	Path to directory containing config files (in directories by ProdId)
-t	Optional	UTC time in format YYYY-MM-DDThh:mm:ss. If not set, the current time will be used.
-c	Mandatory	Module config tag to be used eg. 'PIT_MOD'
-v	Mandatory	Path to file specifying variables (see 'Defining Variables' below)
-x	Mandatory	Disable tags to be used eg. 'PIT_DIS'
-n	Optional (for testing purposes)	Max number of modules to read

Output: Single 'snaphot' set of plots at the given time

Defining Variables

Other than the Hard-coded Enable Variables (see section), the user has latitude to specify whichever values they want to read, and these will automatically be read and plotted in a user-friendly way.

The method for specifying variables is via a csv text file (example file attached, shown as table below):

Histogram Name	Branch Name	Title	isFei3	isFei4	isPixel	isInt	isBool	Register Max
Tdac	Trim_0.Trim.TDAC	TDAC	true	false	true	false	true	127
Tdac	Trim_0.Trim.TDAC	TDAC	false	true	true	false	true	31
GdacPixel	GlobalRegister_0.GlobalRegister.GLOBAL_DAC	GDAC	true	false	false	true	false	31
VFine	GlobalRegister_0.GlobalRegister.Vthin_AltFine	VThin_Fine (GDAC)	false	true	false	true	false	255
VCoarse	GlobalRegister_0.GlobalRegister.Vthin_AltCoarse	Thin_Coarse (GDAC)	false	true	false	true	false	255
Fdac	Trim_0.Trim.FDAC	FDAC	true	false	true	true	false	7
Fdac	Trim_0.Trim.FDAC	FDAC	false	true	true	true	false	15
Ifdac	GlobalRegister_0.GlobalRegister.PrmpVbpf	IFDAC	false	true	false	true	false	255
Ifdac	GlobalRegister_0.GlobalRegister.DAC_ITRIMIF	IFDAC	true	false	false	true	false	255

Below is a brief description of the fields (techincal details and limitations described in detail below):

Histogram Name	Used to name histograms within code, and used to name output files (so no spaces)
Branch Name	The branch name to get from the config file: NB without "PixFe_{N}." prefix, see examples
Title	Used to generate titles on output plots, should be human-readable and descirptive
isFei3	Whether the variable is present for FE-I3 modules
isFei4	Whether the variable is present for FE-I4 modules
isPixel	Whether the variable is defined per-pixel, is not it is assumed to be defined on a per-FE basis (see 'Pixel-level Variables below)
isInt	Whether the variable has an integer value (as opposed to boolean)
isBool	Whether the variable has a boolean value
registerMax	Sets the max value possible for the variable, used for plotting. Can be left blank, in which case plots will only be scaled to the data (zoomed).

Technical Details/Limitations for adding variables

The current state of the software is sufficient for reading all currently proposed variables of interest. However if new ones are added, the following assumptions are made about the underlying data types in the config file:

• if isPixel and isInt: assumed to be MaskWrapperObject <unsigned short>
• if isPixel and isBool: assumed to be MaskWrapperObject <bool>
• isInt/isBool: hopefully self-explanatory

Additionally, the reading of variables defined only per-module (i.e. 1 value per Root file) is currently not supported

Hard-coded Enable Variables

Information on the enable status of detector elements is hard-coded into this analysis, since it is necessary to properly analyse the other variables. Below is a brief explanation of these variables:

Variable	Description
FeTotal	Total number of FEs read (just 0 or 1 per FE). Only potentially useful to verify that all parts of the detector were read.
FeEnable	Stores the value of the FE Enable mask (doesn't account for disabled modules). Specifically, the ConfigEnable parameter is used. Initially it was planned to use 3 (DacsEnable, ScanEnable and ConfigEnable), which were believed to always be equal. However it was found that for certain modules, only the ConfigEnable mask is correct. A mismatch between these 3 still produces a warning message on runtime.
ModulePitDis	Shows which detector regions are disabled by the module-level disable file.
OverallFeEnable	Stores whether an FE is enabled by the combination of the 2 variables above
PixelTotal	Total number of pixels read in a given FE. Similar to FeTotal, useful for checking that all pixels were read.
PixelEnable	(Not present in 2D plots). Describes the fraction of pixels on enabled FE's which are themselves enabled. This gives an idea of the contribution made by the pixel-level enable mask, showing how noisy many pixels are on the relevant FE group.
OverallPixelEnable	This is the most useful variable for seeing how much of the detector is enabled/disabled. It show what fraction of each FE is enabled, taking into account all enable masks (i.e. also those on the FE/module level).
ColumnPixelEnable	Since one option when setting tunings is the disabling of entire columns (equal eta value), this keeps track of how many columns in a given FE are not entirely disabled. It takes all columns into account
LongColumnPixelEnable	Same as ColumnPixelEnable, expect only for the 2 columns at the edge of each detector (the ones consisting entirely of long pixels).

Pixel-level variables

For pixel-level variables, for all variables (other than those concerning the enbale/disable state), only those pixels which are enabled are considered in calculations. Specifically, a pixel is considered enabled if:
1) It is not part of a module which is disabled by the PIT_DIS list
2) Its FE is not disabled
3) It is not disabled on a per-pixel level

For pixel-level variables, what appears in plots and charts is the mean value across a given FE or set of FEs

Additionally, the standard deviation is automatically calculated across each FE, defined in the standard way:

When combining standard deviations across different FE's (eg in Pixel Comparison Plots and FE Number Plots), it is calculated in a non-standard way. Since pixel level-tunings are also influenced by FE-level tunings, if a normal overall standard deviation were calculated, it could produce a misleading result. This is because different FEs could have widely separated means (if the FE-level tuning were different), but be each well tuned. In order to account for this, the deviation for each FE is calculated with respect to its own mean, resulting in a calculation like:

Where the sums over i indicate the sum over each individual FE.

Plot Types

For all plots, plots are produced which scale the plotting (either heat-map range or y-axis) to the range of data read. If a 'Register Max' is set, this will be labelled 'Zoomed', and another plot will be made scaled to the full range of the variable.

2D

These are relatively simple plots, showing a value for each variable, on a per-FE basis, in a heat map format. For all plots, the y axis denotes phi position, and the x axis is eta (expect for endcap sections). In all cases, the axis labelling and offsets were chosen to mirror those used in existing detector monitoring applications. The axes are labelled with module labels, such that one should be able, with knowledge, to read out the ID of a given module from these plots.

Pixel Type Comparison

These plots allow comparison between pixel types, and across layers. There are 2 plots per (pixel-level) variable. The B-Layer (L0) is split into 2 regions: M0/M1 (the 3 modules nearest the interaction point, with smallest eta), and the rest, called 'L0 Outer'. Additonally, separate plots exist for IBL, and the rest of the Pixel Detector (explained below). The plots are further split by pixel type. We define 6 types of pixel:

1) Normal
2) Normal Ganged
3) Normal Inter-ganged
4) Long
5) Long Ganged
6) Long Inter-ganged

However these are all present only in FE-I3 chips. For FE-I4 (only in IBL), only normal and long pixels are present. This is one reason why they were separated. The other is that for several variables (eg. TDAC), the scale of values for IBL is very different than for the other detector regions, so comparison wouldn't be useful.

FE Number

These plots are designed to look for systematic effects, such that FE's with particular numbers (corresponding to the same relative postition within the module), have different behaviours. One possible cause of this could be differences in powering.

Evolution

Plots the change in variables over time. For pixel-level variables, an additional plots is made showing the evolution split by pixel type.

-- MatthewKevinKingston - 2023-03-13

• ExampleVariables.txt: Example file specifying variables to read</verbatim>