L1Trigger/interface/VertexWord.h

0001 #ifndef DataFormats_L1TVertex_VertexWord_h
0002 #define DataFormats_L1TVertex_VertexWord_h
0003
0004 ////////
0005 //
0006 // class to store the 96-bit track word produced by the L1 Track Trigger.  Intended to be inherited by L1 TTTrack.
0007 // packing scheme given below.
0008 //
0009 // author:      Alexx Perloff
0010 // created:     March 17, 2021
0011 // modified by:    Nick Manganelli
0012 // modified:    November 18, 2022
0013 //
0014 ///////
0015
0016 #include "DataFormats/L1Trigger/interface/Vertex.h"
0017
0018 #include <ap_int.h>
0019 #include <ap_fixed.h>
0020
0021 #include <bitset>
0022 #include <vector>
0023
0024 namespace l1t {
0025
0026   class VertexWord {
0027   public:
0028     // ----------constants, enums and typedefs ---------
0029     enum VertexBitWidths {
0030       // The sizes of the vertex word components and total word size
0031       kValidSize = 1,         // Width of the valid bit
0032       kZ0Size = 15,           // Width of z-position
0033       kZ0MagSize = 6,         // Width of z-position magnitude (signed)
0034       kNTrackInPVSize = 8,    // Width of the multiplicity in the PV (unsigned)
0035       kSumPtSize = 12,        // Width of pT
0036       kSumPtMagSize = 10,     // Width of pT magnitude (unsigned)
0037       kQualitySize = 3,       // Width of the quality field
0038       kNTrackOutPVSize = 10,  // Width of the multiplicity outside the PV (unsigned)
0039       kUnassignedSize = 15,   // Width of the unassigned bits
0040
0041       kVertexWordSize = kValidSize + kZ0Size + kNTrackInPVSize + kSumPtSize + kQualitySize + kNTrackOutPVSize +
0042                         kUnassignedSize,  // Width of the vertex word in bits
0043     };
0044
0045     enum VertexBitLocations {
0046       // The location of the least significant bit (LSB) and most significant bit (MSB) in the vertex word for different fields
0047       kValidLSB = 0,
0048       kValidMSB = kValidLSB + VertexBitWidths::kValidSize - 1,
0049       kZ0LSB = kValidMSB + 1,
0050       kZ0MSB = kZ0LSB + VertexBitWidths::kZ0Size - 1,
0051       kNTrackInPVLSB = kZ0MSB + 1,
0052       kNTrackInPVMSB = kNTrackInPVLSB + VertexBitWidths::kNTrackInPVSize - 1,
0053       kSumPtLSB = kNTrackInPVMSB + 1,
0054       kSumPtMSB = kSumPtLSB + VertexBitWidths::kSumPtSize - 1,
0055       kQualityLSB = kSumPtMSB + 1,
0056       kQualityMSB = kQualityLSB + VertexBitWidths::kQualitySize - 1,
0057       kNTrackOutPVLSB = kQualityMSB + 1,
0058       kNTrackOutPVMSB = kNTrackOutPVLSB + VertexBitWidths::kNTrackOutPVSize - 1,
0059       kUnassignedLSB = kNTrackOutPVMSB + 1,
0060       kUnassignedMSB = kUnassignedLSB + VertexBitWidths::kUnassignedSize - 1
0061     };
0062
0063     // vertex parameters types
0064     typedef ap_uint<VertexBitWidths::kValidSize> vtxvalid_t;  // Vertex validity
0065     typedef ap_fixed<VertexBitWidths::kZ0Size, VertexBitWidths::kZ0MagSize, AP_RND_CONV, AP_SAT> vtxz0_t;  // Vertex z0
0066     typedef ap_ufixed<VertexBitWidths::kNTrackInPVSize, VertexBitWidths::kNTrackInPVSize, AP_RND_CONV, AP_SAT>
0067         vtxmultiplicity_t;  // NTracks in vertex
0068     typedef ap_ufixed<VertexBitWidths::kSumPtSize, VertexBitWidths::kSumPtMagSize, AP_RND_CONV, AP_SAT>
0069         vtxsumpt_t;                                               // Vertex Sum pT
0070     typedef ap_uint<VertexBitWidths::kQualitySize> vtxquality_t;  // Vertex quality
0071     typedef ap_ufixed<VertexBitWidths::kNTrackOutPVSize, VertexBitWidths::kNTrackOutPVSize, AP_RND_CONV, AP_SAT>
0072         vtxinversemult_t;                                               // NTracks outside vertex
0073     typedef ap_uint<VertexBitWidths::kUnassignedSize> vtxunassigned_t;  // Unassigned bits
0074
0075     // vertex word types
0076     typedef std::bitset<VertexBitWidths::kVertexWordSize> vtxword_bs_t;  // Entire track word;
0077     typedef ap_uint<VertexBitWidths::kVertexWordSize> vtxword_t;         // Entire vertex word;
0078
0079     // reference types
0080     typedef edm::Ref<l1t::VertexCollection> VertexRef;  // Reference to a persistent l1t::Vertex
0081
0082   public:
0083     // ----------Constructors --------------------------
0084     VertexWord() {}
0085     VertexWord(unsigned int valid,
0086                double z0,
0087                unsigned int multiplicity,
0088                double pt,
0089                unsigned int quality,
0090                unsigned int inverseMultiplicity,
0091                unsigned int unassigned);
0092     VertexWord(unsigned int valid,
0093                unsigned int z0,
0094                unsigned int multiplicity,
0095                unsigned int pt,
0096                unsigned int quality,
0097                unsigned int inverseMultiplicity,
0098                unsigned int unassigned);
0099     VertexWord(vtxvalid_t valid,
0100                vtxz0_t z0,
0101                vtxmultiplicity_t multiplicity,
0102                vtxsumpt_t pt,
0103                vtxquality_t quality,
0104                vtxinversemult_t inverseMultiplicity,
0105                vtxunassigned_t unassigned);
0106
0107     ~VertexWord() {}
0108
0109     // ----------copy constructor ----------------------
0110     VertexWord(const VertexWord& word) { vertexWord_ = word.vertexWord_; }
0111
0112     // ----------operators -----------------------------
0113     VertexWord& operator=(const VertexWord& word) {
0114       vertexWord_ = word.vertexWord_;
0115       return *this;
0116     }
0117
0118     // ----------member functions (getters) ------------
0119     // These functions return arbitarary precision words (lists of bits) for each quantity
0120     vtxvalid_t validWord() const { return vertexWord()(VertexBitLocations::kValidMSB, VertexBitLocations::kValidLSB); }
0121     vtxz0_t z0Word() const {
0122       vtxz0_t ret;
0123       ret.V = vertexWord()(VertexBitLocations::kZ0MSB, VertexBitLocations::kZ0LSB);
0124       return ret;
0125     }
0126     vtxmultiplicity_t multiplicityWord() const {
0127       return vertexWord()(VertexBitLocations::kNTrackInPVMSB, VertexBitLocations::kNTrackInPVLSB);
0128     }
0129     vtxsumpt_t ptWord() const {
0130       vtxsumpt_t ret;
0131       ret.V = vertexWord()(VertexBitLocations::kSumPtMSB, VertexBitLocations::kSumPtLSB);
0132       return ret;
0133     }
0134     vtxquality_t qualityWord() const {
0135       return vertexWord()(VertexBitLocations::kQualityMSB, VertexBitLocations::kQualityLSB);
0136     }
0137     vtxinversemult_t inverseMultiplicityWord() const {
0138       return vertexWord()(VertexBitLocations::kNTrackOutPVMSB, VertexBitLocations::kNTrackOutPVLSB);
0139     }
0140     vtxunassigned_t unassignedWord() const {
0141       return vertexWord()(VertexBitLocations::kUnassignedMSB, VertexBitLocations::kUnassignedLSB);
0142     }
0143     vtxword_t vertexWord() const { return vtxword_t(vertexWord_.to_string().c_str(), 2); }
0144
0145     // These functions return the packed bits in integer format for each quantity
0146     // Signed quantities have the sign enconded in the left-most bit.
0147     unsigned int validBits() const { return validWord().to_uint(); }
0148     unsigned int z0Bits() const { return z0Word().range().to_uint(); }
0149     unsigned int multiplicityBits() const { return multiplicityWord().to_uint(); }
0150     unsigned int ptBits() const { return ptWord().range().to_uint(); }
0151     unsigned int qualityBits() const { return qualityWord().to_uint(); }
0152     unsigned int inverseMultiplicityBits() const { return inverseMultiplicityWord().to_uint(); }
0153     unsigned int unassignedBits() const { return unassignedWord().to_uint(); }
0154
0155     // These functions return the unpacked and converted values
0156     // These functions return real numbers converted from the digitized quantities by unpacking the 64-bit vertex word
0157     bool valid() const { return validWord().to_bool(); }
0158     double z0() const { return z0Word().to_double(); }
0159     unsigned int multiplicity() const { return multiplicityWord().to_uint(); }
0160     double pt() const { return ptWord().to_double(); }
0161     unsigned int quality() const { return qualityWord().to_uint(); }
0162     unsigned int inverseMultiplicity() const { return inverseMultiplicityWord().to_uint(); }
0163     unsigned int unassigned() const { return unassignedWord().to_uint(); }
0164
0165     // return reference to floating point vertex
0166     VertexRef vertexRef() const { return vertexRef_; }
0167
0168     // ----------member functions (setters) ------------
0169     void setVertexWord(vtxvalid_t valid,
0170                        vtxz0_t z0,
0171                        vtxmultiplicity_t multiplicity,
0172                        vtxsumpt_t pt,
0173                        vtxquality_t quality,
0174                        vtxinversemult_t inverseMultiplicity,
0175                        vtxunassigned_t unassigned);
0176
0177     // set reference to floating point vertex
0178     void setVertexRef(const VertexRef& ref) { vertexRef_ = ref; }
0179
0180   private:
0181     // ----------private member functions --------------
0182     double unpackSignedValue(unsigned int bits, unsigned int nBits, double lsb) const {
0183       int isign = 1;
0184       unsigned int digitized_maximum = (1 << nBits) - 1;
0185       if (bits & (1 << (nBits - 1))) {  // check the sign
0186         isign = -1;
0187         bits = (1 << (nBits + 1)) - bits;  // if negative, flip everything for two's complement encoding
0188       }
0189       return (double(bits & digitized_maximum) + 0.5) * lsb * isign;
0190     }
0191
0192     // ----------member data ---------------------------
0193     vtxword_bs_t vertexWord_;
0194     VertexRef vertexRef_;
0195   };
0196
0197   typedef std::vector<VertexWord> VertexWordCollection;
0198   typedef edm::Ref<VertexWordCollection> VertexWordRef;
0199 }  // namespace l1t
0200
0201 #endif