BmnParamLayout.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:     Claude (Opus 5)
    Supervisor: Igor Polev, polev@jinr.int
 
    BmnParamLayout class header-only implementation
    Traversable description of the alignment parameter set
*/
 
#ifndef BMNPARAMLAYOUT_H
#define BMNPARAMLAYOUT_H
 
#include <TString.h>
#include <string>
#include <vector>
 
// Rebuild() reads it, but the hierarchy owns a layout in turn - so only the
// declaration is visible here, and the definition lives in BmnParamLayout.cxx
class BmnAlignHierarchy;
 
/*
 *  Parameter layout
 *  ================
 *
 *  BmnAlignHierarchy defines *what* the parameters are - which element or
 *  composite node each belongs to, and how the levels propagate into one
 *  another. This class describes *where* each of them lives, so that the code
 *  working with parameters never computes an index itself.
 *
 *  One ParamRef per parameter of the full layout is precomputed on Rebuild()
 *  and handed out by the traversal ranges below. Everything a loop over
 *  parameters used to derive by hand - the owning element, which of the six
 *  corrections it is, what to print it as - is a field of the reference.
 *
 *  BmnAlignHierarchy::EndBuild() calls Rebuild(). The name pointers refer to
 *  the node names owned by the hierarchy, so it has to outlive the layout
 *  built from it.
 */
 
struct ParamRef
{
    Int_t full{-1};             // index in the full layout; for a leaf parameter also its row of J
    Int_t leaf{-1};             // detector element index, -1 for a composite parameter
    Int_t comp{-1};             // index in the composite block (its column of J), -1 for a leaf parameter
    Int_t node{-1};             // index of the owning object in ByNode()
    Int_t prm{0};               // which correction, 0..BMN_GLOBAL_PARAMS_PD-1
    Int_t level{0};             // hierarchy depth of the owning node
    const char* nodeName{""};   // owned by the hierarchy, see the note above
    const char* prmName{""};    // one of BmnParamLayout::ParamNames()
 
    Bool_t IsComposite() const noexcept { return comp >= 0; }
    // how the parameter is named in reports, e.g. "STA07 dZ"
    TString Label() const { return TString::Format("%s %s", nodeName, prmName); }
};
 
// One alignable object - a detector element or a composite node - with the
// BMN_GLOBAL_PARAMS_PD corrections it carries. Reporting and serialization are
// written per object rather than per parameter, and this is what they walk.
struct NodeRef
{
    const char* name{""};
    Int_t level{0};
    Int_t leaf{-1};   // detector element index, -1 for a composite
    std::vector<ParamRef> params;
 
    Bool_t IsComposite() const noexcept { return leaf < 0; }
};
 
class BmnParamLayout
{
  public:
    typedef std::vector<ParamRef> Range_t;
    typedef std::vector<NodeRef> Nodes_t;
 
    BmnParamLayout() = default;
    virtual ~BmnParamLayout() = default;
 
    /*
     *  Names of the six rigid-body corrections, in parameter order. They are the
     *  vocabulary of the layout: reports label parameters with them, and the
     *  config files address parameters and declare the alignment type by them -
     *  which makes this list part of the file format, not a display detail.
     *  One definition, in the .cxx, so a header cannot hand out copies of it.
     */
    static const std::vector<std::string>& ParamNames();
    static const char* ParamName(Int_t p);              // "" if out of range
    static Int_t ParamIndex(const std::string& name);   // -1 if unknown
 
    void Rebuild(const BmnAlignHierarchy& hierarchy);
 
    Int_t Size() const noexcept { return static_cast<Int_t>(fAll.size()); }
 
    // traversal ranges, all in full-layout order
    const Range_t& All() const noexcept { return fAll; }
    const Range_t& Leaves() const noexcept { return fLeaves; }
    const Range_t& Composites() const noexcept { return fComposites; }
    // the same parameters grouped by the object owning them, elements first
    const Nodes_t& ByNode() const noexcept { return fByNode; }
 
    // direct access by full-layout index, for config loaders addressing a
    // parameter the user named rather than walking the set
    const ParamRef& operator[](Int_t full) const { return fAll[full]; }
 
    // the object a config file addressed by name, null if there is no such one
    inline const NodeRef* Find(const std::string& name) const;
 
  protected:
    Range_t fAll, fLeaves, fComposites;
    Nodes_t fByNode;
};
 
// === inline implementation ====================================================
 
inline const NodeRef* BmnParamLayout::Find(const std::string& name) const
{
    for (const NodeRef& node : fByNode)
        if (name == node.name)
            return &node;
    return nullptr;
}
 
#endif   // BMNPARAMLAYOUT_H