L1Trigger/interface/TkTripletWord.h

0001 #ifndef FIRMWARE_TkTripletWord_h
0002 #define FIRMWARE_TkTripletWord_h
0003
0004 // Class to store the 128-bit TkTriplet word for the L1TrackTriggerMatch.
0005 // Original author: George Karathanasis (Dec 2023)
0006
0007 #include <vector>
0008 #include <ap_int.h>
0009 #include <cassert>
0010 #include <cmath>
0011 #include <bitset>
0012 #include <string>
0013 #include "DataFormats/L1TrackTrigger/interface/TTTrack_TrackWord.h"
0014
0015 namespace l1t {
0016
0017   class TkTripletWord {
0018   public:
0019     // ----------constants, enums and typedefs ---------
0020     static constexpr double MAX_MASS = 1000.;
0021     static constexpr double MAX_ETA = 8.;
0022     static constexpr double MAX_CHARGE = 3.;
0023     static constexpr double MAX_Z0 = 25.;
0024
0025     enum TkTripletBitWidths {
0026       // The sizes of the triplet word components and total word size
0027       kValidSize = 1,  // Width of the valid bit
0028       kPtSize = 16,    // Width of the triplet pt
0029       kPtMagSize = 11,
0030       kGlbEtaSize = 14,          // Width of the triplet eta
0031       kGlbPhiSize = 13,          // Width of the triplet phi
0032       kMassSize = 16,            // Width of the triplet mass
0033       kChargeSize = 3,           // Width of the triplet charge
0034       kDiTrackMinMassSize = 16,  // Width of the mass of min mass pair
0035       kDiTrackMaxMassSize = 16,  // Width of the mass of max mass pair
0036       kDiTrackMinZ0Size = 8,     // Width of the Dz of min Dz pair
0037       kDiTrackMaxZ0Size = 8,     // Width of the Dz of max Dz pair
0038       kUnassignedSize = 17,
0039       kTkTripletWordSize = kValidSize + kPtSize + kGlbEtaSize + kGlbPhiSize + kMassSize + kChargeSize +
0040                            kDiTrackMinMassSize + kDiTrackMaxMassSize + kDiTrackMinZ0Size + kDiTrackMaxZ0Size +
0041                            kUnassignedSize,
0042     };
0043
0044     enum TkTripletBitLocations {
0045       // The location of the least significant bit (LSB) and most significant bit (MSB) in the triplet word for different fields
0046       kValidLSB = 0,
0047       kValidMSB = kValidLSB + TkTripletBitWidths::kValidSize - 1,
0048       kPtLSB = kValidMSB + 1,
0049       kPtMSB = kPtLSB + TkTripletBitWidths::kPtSize - 1,
0050       kGlbPhiLSB = kPtMSB + 1,
0051       kGlbPhiMSB = kGlbPhiLSB + TkTripletBitWidths::kGlbPhiSize - 1,
0052       kGlbEtaLSB = kGlbPhiMSB + 1,
0053       kGlbEtaMSB = kGlbEtaLSB + TkTripletBitWidths::kGlbEtaSize - 1,
0054       kMassLSB = kGlbEtaMSB + 1,
0055       kMassMSB = kMassLSB + TkTripletBitWidths::kMassSize - 1,
0056       kChargeLSB = kMassMSB + 1,
0057       kChargeMSB = kChargeLSB + TkTripletBitWidths::kChargeSize - 1,
0058       kDiTrackMinMassLSB = kChargeMSB + 1,
0059       kDiTrackMinMassMSB = kDiTrackMinMassLSB + TkTripletBitWidths::kDiTrackMinMassSize - 1,
0060       kDiTrackMaxMassLSB = kDiTrackMinMassMSB + 1,
0061       kDiTrackMaxMassMSB = kDiTrackMaxMassLSB + TkTripletBitWidths::kDiTrackMaxMassSize - 1,
0062       kDiTrackMinZ0LSB = kDiTrackMaxMassMSB + 1,
0063       kDiTrackMinZ0MSB = kDiTrackMinZ0LSB + TkTripletBitWidths::kDiTrackMinZ0Size - 1,
0064       kDiTrackMaxZ0LSB = kDiTrackMinZ0MSB + 1,
0065       kDiTrackMaxZ0MSB = kDiTrackMaxZ0LSB + TkTripletBitWidths::kDiTrackMaxZ0Size - 1,
0066       kUnassignedLSB = kDiTrackMaxZ0MSB + 1,
0067       kUnassignedMSB = kUnassignedLSB + TkTripletBitWidths::kUnassignedSize - 1,
0068     };
0069
0070     // vertex parameters types
0071     typedef ap_uint<kValidSize> valid_t;                          //valid
0072     typedef ap_ufixed<kPtSize, kPtMagSize, AP_TRN, AP_SAT> pt_t;  //triplet pt
0073     typedef ap_int<kGlbEtaSize> glbeta_t;                         //triplet eta
0074     typedef ap_int<kGlbPhiSize> glbphi_t;                         //triplet phi
0075     typedef ap_int<kMassSize> mass_t;                             //triplet mass
0076     typedef ap_int<kChargeSize> charge_t;                         //triplet Q
0077     typedef ap_int<kDiTrackMinMassSize> ditrack_minmass_t;        //pair min mass
0078     typedef ap_int<kDiTrackMaxMassSize> ditrack_maxmass_t;        //pair max mass
0079     typedef ap_int<kDiTrackMinZ0Size> ditrack_minz0_t;            //pair dz min
0080     typedef ap_int<kDiTrackMaxZ0Size> ditrack_maxz0_t;            //pair dz max
0081     typedef ap_uint<TkTripletBitWidths::kUnassignedSize> unassigned_t;
0082     typedef std::bitset<TkTripletBitWidths::kTkTripletWordSize> tktripletword_bs_t;
0083     typedef ap_uint<TkTripletBitWidths::kTkTripletWordSize> tktripletword_t;
0084
0085   public:
0086     // ----------Constructors --------------------------
0087     TkTripletWord() {}
0088     TkTripletWord(valid_t valid,
0089                   pt_t pt,
0090                   glbeta_t eta,
0091                   glbphi_t phi,
0092                   mass_t mass,
0093                   charge_t charge,
0094                   ditrack_minmass_t ditrack_minmass,
0095                   ditrack_maxmass_t ditrack_maxmass,
0096                   ditrack_minz0_t ditrack_minz0_t,
0097                   ditrack_maxz0_t ditrack_maxz0_t,
0098                   unassigned_t unassigned);
0099
0100     ~TkTripletWord() {}
0101
0102     // ----------copy constructor ----------------------
0103     TkTripletWord(const TkTripletWord& word) { tkTripletWord_ = word.tkTripletWord_; }
0104
0105     // ----------operators -----------------------------
0106     TkTripletWord& operator=(const TkTripletWord& word) {
0107       tkTripletWord_ = word.tkTripletWord_;
0108       return *this;
0109     }
0110
0111     // ----------member functions (getters) ------------
0112     // These functions return arbitarary precision words (lists of bits) for each quantity
0113     valid_t validWord() const {
0114       return tkTripletWord()(TkTripletBitLocations::kValidMSB, TkTripletBitLocations::kValidLSB);
0115     }
0116     pt_t ptWord() const {
0117       pt_t ret;
0118       ret.V = tkTripletWord()(TkTripletBitLocations::kPtMSB, TkTripletBitLocations::kPtLSB);
0119       return ret;
0120     }
0121     glbeta_t glbEtaWord() const {
0122       glbeta_t ret;
0123       ret.V = tkTripletWord()(TkTripletBitLocations::kGlbEtaMSB, TkTripletBitLocations::kGlbEtaLSB);
0124       return ret;
0125     }
0126     glbphi_t glbPhiWord() const {
0127       glbphi_t ret;
0128       ret.V = tkTripletWord()(TkTripletBitLocations::kGlbPhiMSB, TkTripletBitLocations::kGlbPhiLSB);
0129       return ret;
0130     }
0131     mass_t massWord() const {
0132       mass_t ret;
0133       ret.V = tkTripletWord()(TkTripletBitLocations::kMassMSB, TkTripletBitLocations::kMassLSB);
0134       return ret;
0135     }
0136     charge_t chargeWord() const {
0137       charge_t ret;
0138       ret.V = tkTripletWord()(TkTripletBitLocations::kChargeMSB, TkTripletBitLocations::kChargeLSB);
0139       return ret;
0140     }
0141
0142     ditrack_minmass_t ditrackMinMassWord() const {
0143       ditrack_minmass_t ret;
0144       ret.V = tkTripletWord()(TkTripletBitLocations::kDiTrackMinMassMSB, TkTripletBitLocations::kDiTrackMinMassLSB);
0145       return ret;
0146     }
0147     ditrack_maxmass_t ditrackMaxMassWord() const {
0148       ditrack_maxmass_t ret;
0149       ret.V = tkTripletWord()(TkTripletBitLocations::kDiTrackMaxMassMSB, TkTripletBitLocations::kDiTrackMaxMassLSB);
0150       return ret;
0151     }
0152     ditrack_minz0_t ditrackMinZ0Word() const {
0153       ditrack_minz0_t ret;
0154       ret.V = tkTripletWord()(TkTripletBitLocations::kDiTrackMinZ0MSB, TkTripletBitLocations::kDiTrackMinZ0LSB);
0155       return ret;
0156     }
0157     ditrack_maxz0_t ditrackMaxZ0Word() const {
0158       ditrack_maxz0_t ret;
0159       ret.V = tkTripletWord()(TkTripletBitLocations::kDiTrackMaxZ0MSB, TkTripletBitLocations::kDiTrackMaxZ0LSB);
0160       return ret;
0161     }
0162     unassigned_t unassignedWord() const {
0163       return tkTripletWord()(TkTripletBitLocations::kUnassignedMSB, TkTripletBitLocations::kUnassignedLSB);
0164     }
0165     tktripletword_t tkTripletWord() const { return tktripletword_t(tkTripletWord_.to_string().c_str(), 2); }
0166
0167     // These functions return the packed bits in integer format for each quantity
0168     // Signed quantities have the sign enconded in the left-most bit.
0169     unsigned int validBits() const { return validWord().to_uint(); }
0170     unsigned int ptBits() const { return ptWord().to_uint(); }
0171     unsigned int glbEtaBits() const { return glbEtaWord().to_uint(); }
0172     unsigned int glbPhiBits() const { return glbPhiWord().to_uint(); }
0173     unsigned int massBits() const { return massWord().to_uint(); }
0174     unsigned int chargeBits() const { return chargeWord().to_uint(); }
0175     unsigned int ditrackMinMassBits() const { return ditrackMinMassWord().to_uint(); }
0176     unsigned int ditrackMaxMassBits() const { return ditrackMaxMassWord().to_uint(); }
0177     unsigned int ditrackMinZ0Bits() const { return ditrackMinZ0Word().to_uint(); }
0178     unsigned int ditrackMaxZ0Bits() const { return ditrackMaxZ0Word().to_uint(); }
0179     unsigned int unassignedBits() const { return unassignedWord().to_uint(); }
0180
0181     // These functions return the unpacked and converted values
0182     // These functions return real numbers converted from the digitized quantities by unpacking the 64-bit vertex word
0183     bool valid() const { return validWord().to_bool(); }
0184     float pt() const { return ptWord().to_float(); }
0185     float glbeta() const {
0186       return unpackSignedValue(
0187           glbEtaWord(), TkTripletBitWidths::kGlbEtaSize, (MAX_ETA) / (1 << TkTripletBitWidths::kGlbEtaSize));
0188     }
0189     float glbphi() const {
0190       return unpackSignedValue(glbPhiWord(),
0191                                TkTripletBitWidths::kGlbPhiSize,
0192                                (2. * std::abs(M_PI)) / (1 << TkTripletBitWidths::kGlbPhiSize));
0193     }
0194     float mass() const {
0195       return unpackSignedValue(
0196           massWord(), TkTripletBitWidths::kMassSize, MAX_MASS / (1 << TkTripletBitWidths::kMassSize));
0197     }
0198     int charge() const {
0199       return unpackSignedValue(
0200           chargeWord(), TkTripletBitWidths::kChargeSize, MAX_CHARGE / (1 << TkTripletBitWidths::kChargeSize));
0201     }
0202     float ditrackMinMass() const {
0203       return unpackSignedValue(ditrackMinMassWord(),
0204                                TkTripletBitWidths::kDiTrackMinMassSize,
0205                                MAX_MASS / (1 << TkTripletBitWidths::kDiTrackMinMassSize));
0206     }
0207     float ditrackMaxMass() const {
0208       return unpackSignedValue(ditrackMaxMassWord(),
0209                                TkTripletBitWidths::kDiTrackMaxMassSize,
0210                                MAX_MASS / (1 << TkTripletBitWidths::kDiTrackMaxMassSize));
0211     }
0212     float ditrackMinZ0() const {
0213       return unpackSignedValue(ditrackMinZ0Word(),
0214                                TkTripletBitWidths::kDiTrackMinZ0Size,
0215                                MAX_Z0 / (1 << TkTripletBitWidths::kDiTrackMinZ0Size));
0216     }
0217     float ditrackMaxZ0() const {
0218       return unpackSignedValue(ditrackMaxZ0Word(),
0219                                TkTripletBitWidths::kDiTrackMaxZ0Size,
0220                                MAX_Z0 / (1 << TkTripletBitWidths::kDiTrackMaxZ0Size));
0221     }
0222     unsigned int unassigned() const { return unassignedWord().to_uint(); }
0223
0224     // ----------member functions (setters) ------------
0225     void setTkTripletWord(valid_t valid,
0226                           pt_t pt,
0227                           glbeta_t eta,
0228                           glbphi_t phi,
0229                           mass_t mass,
0230                           charge_t charge,
0231                           ditrack_minmass_t ditrack_minmass,
0232                           ditrack_maxmass_t ditrack_maxmass,
0233                           ditrack_minz0_t ditrack_minz0,
0234                           ditrack_maxz0_t ditrack_maxz0,
0235                           unassigned_t unassigned);
0236
0237     template <class packVarType>
0238     inline void packIntoWord(unsigned int& currentOffset, unsigned int wordChunkSize, packVarType& packVar);
0239
0240   private:
0241     // ----------private member functions --------------
0242     double unpackSignedValue(unsigned int bits, unsigned int nBits, double lsb) const {
0243       int isign = 1;
0244       unsigned int digitized_maximum = (1 << nBits) - 1;
0245       if (bits & (1 << (nBits - 1))) {  // check the sign
0246         isign = -1;
0247         bits = (1 << (nBits + 1)) - bits;  // if negative, flip everything for two's complement encoding
0248       }
0249       return (double(bits & digitized_maximum) + 0.5) * lsb * isign;
0250     }
0251
0252     // ----------member data ---------------------------
0253     tktripletword_bs_t tkTripletWord_;
0254   };
0255
0256   typedef std::vector<l1t::TkTripletWord> TkTripletWordCollection;
0257
0258 }  // namespace l1t
0259
0260 #endif