packages/TpcConditions/README.md

0001 # TPC Conditions
0002
0003 The `TpcConditions` package provides event-by-event access to TPC operating
0004 conditions stored in the sPHENIX Conditions Database (CDB).
0005
0006 `TpcConditionsReco` retrieves the `TPC_CONDITIONS` payload for the current
0007 run and uses the event BCO to select the most recent conditions record at or
0008 before the event.  The resulting conditions are made available to other
0009 Fun4All modules through a transient `TpcConditions` object on the node tree.
0010
0011 The `TpcConditions` object is a `PHDataNode` and is intended only for
0012 communication between reconstruction modules.  It is not intended to be
0013 written to an output DST.
0014
0015 ## Event Selection
0016
0017 Two flags describe whether the TPC had recovered from an HV trip:
0018
0019 - `FieldOK` indicates that the complete GEM/transfer-gap voltage stack has
0020   recovered the proper total voltage required for the TPC drift field.
0021 - `GainOK` indicates that the GEMs have recovered their appropriate operating
0022   voltages.
0023
0024 `TpcConditionsReco` returns `Fun4AllReturnCodes::ABORTEVENT` if either
0025 `FieldOK` or `GainOK` is false.
0026
0027 ## Available Conditions
0028
0029 The following quantities are available for the current event:
0030
0031 - Gas temperature
0032 - Gas pressure
0033 - `FieldOK`
0034 - `GainOK`
0035 - Median G4 load current for all undamaged GEMs
0036 - Median G4 load current for the North side
0037 - Median G4 load current for the South side
0038 - Median G4 load current separately for R1, R2, and R3 on each side
0039
0040 The corresponding load-current accessors are:
0041
0042 ```cpp
0043 get_LoadCurrent()   // all undamaged GEMs
0044 get_LoadNorth()     // North
0045 get_LoadSouth()     // South
0046
0047 get_LoadNR1()       // North R1
0048 get_LoadNR2()       // North R2
0049 get_LoadNR3()       // North R3
0050
0051 get_LoadSR1()       // South R1
0052 get_LoadSR2()       // South R2
0053 get_LoadSR3()       // South R3
0054 ```
0055
0056 The load-current quantities are provided separately so that downstream
0057 calibrations may select the grouping appropriate to their application.
0058 No current-to-calibration conversion is performed by `TpcConditionsReco`.
0059
0060 ## Using TpcConditions in a Fun4All Module
0061
0062 A consumer can obtain the current-event conditions using the standard PHOOL
0063 node-tree lookup:
0064
0065 ```cpp
0066 #include <tpcconditions/TpcConditions.h>
0067
0068 #include <phool/getClass.h>
0069
0070 TpcConditions *conditions =
0071     findNode::getClass<TpcConditions>(topNode, "TpcConditions");
0072 ```
0073
0074 The conditions can then be accessed directly:
0075
0076 ```cpp
0077 float temperature = conditions->get_Temperature();
0078 float pressure    = conditions->get_Pressure();
0079
0080 bool fieldOK = conditions->get_FieldOK();
0081 bool gainOK  = conditions->get_GainOK();
0082
0083 float load      = conditions->get_LoadCurrent();
0084 float loadNorth = conditions->get_LoadNorth();
0085 float loadSouth = conditions->get_LoadSouth();
0086
0087 float loadNR1 = conditions->get_LoadNR1();
0088 float loadNR2 = conditions->get_LoadNR2();
0089 float loadNR3 = conditions->get_LoadNR3();
0090
0091 float loadSR1 = conditions->get_LoadSR1();
0092 float loadSR2 = conditions->get_LoadSR2();
0093 float loadSR3 = conditions->get_LoadSR3();
0094 ```
0095
0096 `TpcConditionsReco` must be registered before modules that consume the
0097 `TpcConditions` node so that the conditions have been updated for the
0098 current event before they are used.
0099
0100 ## CDB Payload
0101
0102 The conditions are stored in CDB under
0103
0104 ```text
0105 TPC_CONDITIONS
0106 ```
0107
0108 Each payload contains a time history for one run.  The individual records
0109 are indexed internally by BCO.  For each event, `TpcConditionsReco` selects
0110 the latest conditions sample whose BCO is less than or equal to the event
0111 BCO.
0112
0113 The payload contains the gas temperature, gas pressure, TPC HV status flags,
0114 and individual GEM G4 currents used to calculate the load-current quantities.