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:

$ \sigma = \sqrt{\frac{\sum (x - \bar{x})^{2}}{n}} $

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:

$ \sigma_{tot} = \sqrt{\frac{\sum_{i} \sum(x - \bar{x}_{i})^{2}}{\sum_{i} n_{i}}} $

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

Topic attachments
I Attachment History Action Size Date Who Comment
Texttxt ExampleVariables.txt r1 manage 0.6 K 2023-03-13 - 18:48 MatthewKevinKingston Example file specifying variables to read
Edit | Attach | Watch | Print version | History: r10 < r9 < r8 < r7 < r6 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r10 - 2023-03-22 - MatthewKevinKingston
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Sandbox All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback