BmnRun9DM.h

Go to the documentation of this file.

/*
    BM@N alignment routine
    BM@N experiment at NICA complex, JINR, 2025
 
    Department: Math & Soft Group of HEP lab
    Author:     Igor Polev, polev@jinr.int
 
    BmnRun9DM class declaration
    Run9 representation of detector elements via encoding
*/
 
#ifndef BMNRUN9DM_H
#define BMNRUN9DM_H
 
#include "BmnDetectorList.h"
#include "BmnDetectorModel.h"
 
#include <TString.h>
#include <numeric>
 
/*
 *  Detector elements enumeration scheme
 *
 *  SystemID  - fixed constatns defined in BmnDetectorList.h
 *  StationID - sequence across all systems starting from 0 or 1 (currently 1)
 *  ModuleID  - separate sequence for each station starting from 0 or 1 (currently 1)
 *
 *  CbmStsHit DetectorID layout:
 *
 *  27:24 ( 4 bit) System ID
 *  23:16 ( 8 bit) Station number
 *  15:4  (12 bit) Sector (module) number
 *   3:1  ( 3 bit) Sensor number (not used, allways 0b001)
 *   0:0  ( 1 bit) Unknown (not used, allways 0b0)
 *  --------------
 *  28 bit in total
 *
 *  See CbmStsHit.h and BmnToCbmHitConverter::Exec()
 *
 *  A zero module count in VSP_MODULES / SIL_MODULES / GEM_MODULES marks a
 *  station left out of the model: it gets no elements, and its hits are
 *  ignored, see IgnoreHit(). Its station number stays unused, so the element
 *  IDs are still the CbmStsHit DetectorIDs. The marker works on whole stations
 *  only: the elements of a station must have contiguous module numbers.
 *
 *  The target (TRG) closes the sequence as one more element, see TargetID(),
 *  unless the model is built without it. It is last so that the element
 *  indices of the stations, which config files address, are the same with and
 *  without it.
 */
 
class BmnRun9DM : public BmnDetectorModel
{
  protected:
    Int_t fSystem{-1}, fStation{-1}, fModule{-1};
    const Bool_t fWithTarget{kTRUE};   // the target element closes the sequence
 
    enum
    {
        kFirst,
        kLast
    };
    // Run9 configuration definition
    constexpr static const Int_t VSP_SYSTEM_ID{DetectorId::kVSP}, SIL_SYSTEM_ID{DetectorId::kSILICON},
        GEM_SYSTEM_ID{DetectorId::kGEM},
        TRG_SYSTEM_ID{DetectorId::kREF},   // no STS hit carries it, and it fits the 4-bit field
        VSP_STATION_CNT{1}, SIL_STATION_CNT{4}, GEM_STATION_CNT{8},
        ALL_STATION_CNT{VSP_STATION_CNT + SIL_STATION_CNT + GEM_STATION_CNT},
        STA_NUM_START{1},   // first station number (0 or 1)
        MOD_NUM_START{1},   // first module number for each station  (0 or 1)
        // stations have one common index range, VSP first, then silicons, then GEMs
        VSP_STATION_IDX[2]{STA_NUM_START, STA_NUM_START + VSP_STATION_CNT - 1},
        SIL_STATION_IDX[2]{VSP_STATION_IDX[kLast] + 1, VSP_STATION_IDX[kLast] + SIL_STATION_CNT},
        GEM_STATION_IDX[2]{SIL_STATION_IDX[kLast] + 1, SIL_STATION_IDX[kLast] + GEM_STATION_CNT},
        VSP_MODULES[VSP_STATION_CNT]{6}, SIL_MODULES[SIL_STATION_CNT]{6, 10, 14, 18},
        GEM_MODULES[GEM_STATION_CNT]{8, 8, 8, 8, 8, 8, 8, 0};
    // A GEM "module" here is one zone (sector) of a configuration module,
    // cold and hot zones alternate, see LoadGeometry(). The last station
    // has a single zone, but registers no hits in Run9 data: left out.
 
    // module count of the station at the given 0-based station index, zero for a station left out.
    // CAUTION: the index is not checked.
    inline Int_t StationModules(Int_t station) const noexcept
    {
        if (station < VSP_STATION_CNT)
            return VSP_MODULES[station];
        if (station < VSP_STATION_CNT + SIL_STATION_CNT)
            return SIL_MODULES[station - VSP_STATION_CNT];
        return GEM_MODULES[station - VSP_STATION_CNT - SIL_STATION_CNT];
    }
    // of those, the ones aligned independently. This is the single per-station
    // primitive Alignables() and MaxModulesInStation() are built from, so a
    // model keeping fewer elements per station restates it here alone.
    virtual Int_t StationAlignables(Int_t station) const noexcept { return StationModules(station); }
    // module number the station's alignable sequence starts at
    virtual Int_t FirstModule(Int_t /*station*/) const noexcept { return MOD_NUM_START; }
    // 0-based, inclusive index range of stations this model enumerates. A
    // subsystem-restricted model narrows it (e.g. GEM-only starts past silicon),
    // and Reset()/NextID()/Alignables()/Composites() all honour it.
    virtual Int_t FirstStation() const noexcept { return 0; }
    virtual Int_t LastStation() const noexcept { return ALL_STATION_CNT - 1; }
 
    // sensitive rectangles read from the Run9 XML configurations and the target
    // read from its ASCII geometry file, see the .cxx
    virtual Bool_t LoadGeometry(const char* targetGeoFile) override;
 
    // detector modules enumeration: see base class
    virtual void Reset() noexcept override
    {
        // must set iterator BEFORE the first module according to base class definition
        const Int_t station{FirstStation()};
        fSystem = station < VSP_STATION_CNT                     ? VSP_SYSTEM_ID
                  : station < VSP_STATION_CNT + SIL_STATION_CNT ? SIL_SYSTEM_ID
                                                                : GEM_SYSTEM_ID;
        fStation = station + STA_NUM_START;
        fModule = FirstModule(station) - 1;
    }
 
    virtual Int_t NextID() noexcept override
    {
        // out of range check
        if (-1 == fSystem)
            return -1;   // EOF marker must be negative
        // the target element was the last one
        if (TRG_SYSTEM_ID == fSystem)
            return fSystem = -1;
 
        fModule++;
 
        // Next station check. It is counted off the first module of the
        // station's own sequence, so the test holds for a model keeping only a
        // part of the station just as well as for the full one. A station with
        // no elements meets the condition at once, so the loop passes it.
        Int_t stationIdx{fStation - STA_NUM_START};
        while (fModule - FirstModule(stationIdx) >= StationAlignables(stationIdx)) {
            fStation++, stationIdx++;
            // remember: stations has common enumeration across all systems
 
            // past the last station the target, if any, closes the sequence
            if (stationIdx > LastStation()) {
                if (!fWithTarget)
                    return fSystem = -1;
                fSystem = TRG_SYSTEM_ID;
                return TargetID();
            }
 
            // next system check
            if (fStation > SIL_STATION_IDX[kLast])
                fSystem = GEM_SYSTEM_ID;
            else if (fStation > VSP_STATION_IDX[kLast])
                fSystem = SIL_SYSTEM_ID;
 
            fModule = FirstModule(stationIdx);
        }
 
        return (fSystem << 24) | (fStation << 16) | (fModule << 4) | 0b0010;
        // constant term 0b0010 is used to match CbmStsHit DetectorID encoding
    }
 
  public:
    virtual Int_t MaxModulesInStation() const noexcept override
    {
        Int_t cnt{0};
        for (Int_t i = FirstStation(); i <= LastStation(); i++)
            if (StationAlignables(i) > cnt)
                cnt = StationAlignables(i);
        return cnt;
    }
 
    virtual Int_t Alignables() const noexcept override
    {
        Int_t al{fWithTarget ? 1 : 0};
        for (Int_t i = FirstStation(); i <= LastStation(); i++)
            al += StationAlignables(i);
        return al;
    }
 
    virtual Int_t TargetID() const noexcept override
    {
        return fWithTarget ? (TRG_SYSTEM_ID << 24) | (STA_NUM_START << 16) | (MOD_NUM_START << 4) | 0b0010 : -1;
    }
 
    // the element IDs are the CbmStsHit DetectorIDs themselves, see the layout above
    virtual Int_t IDfromHit(Int_t CbmDetectorID) const noexcept override { return CbmDetectorID; }
 
    // ATTENTION: A station number out of range is not checked.
    //            The hit is unknown to the model, but not ignored.
    virtual Bool_t IgnoreHit(Int_t CbmDetectorID) const noexcept override
    {
        const Int_t station{((CbmDetectorID >> 16) & 0xFF) - STA_NUM_START};
        return TRG_SYSTEM_ID != (CbmDetectorID >> 24) && station >= 0 && station < ALL_STATION_CNT
               && StationModules(station) == 0;
    }
    virtual Bool_t IgnoresSome() const noexcept override
    {
        for (Int_t station = 0; station < ALL_STATION_CNT; station++)
            if (0 == StationModules(station))
                return kTRUE;
        return kFALSE;
    }
 
    // the target is shown with its system name, REF
    virtual std::string DecodeID(Int_t id) const override
    {
        TString system;
        BmnDetectorList::GetSystemNameCaps(id >> 24, system);
        return Form("%-7s st %2d mod %2d", system.Data(), (id >> 16) & 0xFF, (id >> 4) & 0xFFF);
    }
 
    virtual std::vector<Composite> Composites() const override
    {
        std::vector<Composite> nodes;
        nodes.reserve(2 * (LastStation() - FirstStation() + 1));
        for (Int_t station = FirstStation(), leaf = 0; station <= LastStation(); station++) {
            const Int_t nodeSize{StationAlignables(station) / 2};
            if (0 == nodeSize) {   // left out, or a single module: no halves
                leaf += StationAlignables(station);
                continue;
            }
            Composite node;
            node.leaves.resize(nodeSize);
 
            // upper half of the station
            node.name = Form("STA%02dU", station + STA_NUM_START);
            std::iota(node.leaves.begin(), node.leaves.end(), leaf);
            leaf += nodeSize;
            nodes.push_back(node);
 
            // lower half of the station
            node.name = Form("STA%02dL", station + STA_NUM_START);
            std::iota(node.leaves.begin(), node.leaves.end(), leaf);
            leaf += nodeSize;
            nodes.push_back(std::move(node));
        }
        return nodes;
    }
 
    // Without the target the data needs no SiBT beam branch, and a target
    // geometry file given to Init() is read but describes no element.
    explicit BmnRun9DM(Bool_t withTarget = kTRUE)
        : fWithTarget{withTarget}
    {
        fDescription = withTarget ? "Run9 VSP, FSD, GEM zones all independent plus the target: 111 elements"
                                  : "Run9 VSP, FSD, GEM zones all independent, no target: 110 elements";
    }
    virtual ~BmnRun9DM() override = default;
};
 
#endif   // BMNRUN9DM_H