BmnAlignPriors.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
 
    BmnAlignPriors class declaration
    Prior knowledge about the alignment: constraints and presigmas
*/
 
#ifndef BMNALIGNPRIORS_H
#define BMNALIGNPRIORS_H
 
#include "BmnAlignHierarchy.h"
 
#include <TMatrixD.h>
#include <TVectorD.h>
 
/*
 *  Everything the fit is told before it sees a single hit, in the form the
 *  solver consumes it:
 *
 *    - constraints : exact linear relations the solution must satisfy, entering
 *      the system as Lagrange multiplier rows.
 *    - presigmas   : per-parameter prior uncertainties, entering as
 *      pseudo-measurements "parameter == reference +/- sigma" (see Apply).
 *
 *  Both are addressed in the full layout of BmnAlignHierarchy. BmnAlignConfig
 *  fills this from JSON; BmnAligner and BmnAlignReport only read it.
 *
 *  They are also the way to hold an element in place. A constraint on a leaf
 *  pins its effective correction, so the element does not move at all. A
 *  tight presigma pins its own share only, so it still moves with its
 *  ancestors.
 *
 *  Data is public on purpose: this is the parsed content of two config files,
 *  and the loaders write it field by field. The two members below carry the
 *  behaviour that belongs with the data rather than with either consumer.
 */
 
class BmnAlignPriors
{
  public:
    // --- constraints -----------------------------------------------------
    // constraints * A = rhs, one row per constraint, columns in the full layout
    TMatrixD constraints;
    TVectorD rhs;
    Bool_t inhomogeneous{kFALSE};   // any non-zero right-hand side
 
    // --- presigmas -------------------------------------------------------
    VecDouble_t sigma;        // prior sigma per full-layout parameter; <= 0 means "no prior"
    VecDouble_t ref;          // value the prior pulls towards
    Int_t presigmaCount{0};   // parameters that actually carry one
 
    // sizes the presigma arrays and records the layout the addressing is in.
    // Call once the hierarchy is built and before either loader runs.
    void Init(const BmnAlignHierarchy& hierarchy)
    {
        fAllParams = hierarchy.AllParams();
        sigma.assign(fAllParams, 0.0);
        ref.assign(fAllParams, 0.0);
        presigmaCount = 0;
        constraints.ResizeTo(0, fAllParams);
        rhs.ResizeTo(0);
        inhomogeneous = kFALSE;
        fKept.clear();
        fKeptRows.ResizeTo(0, 0);
    }
 
    Int_t ConstCount() const noexcept { return constraints.GetNrows(); }
    Bool_t UsePresigmas() const noexcept { return presigmaCount > 0; }
    // the independent constraints, found by Check(): their indices into
    // constraints / rhs, and their rows promoted to the solved basis
    const VecInt_t& Kept() const noexcept { return fKept; }
    const TMatrixD& KeptRows() const noexcept { return fKeptRows; }
    Int_t KeptCount() const noexcept { return static_cast<Int_t>(fKept.size()); }
    // presigmas are absent altogether when no file was given, hence the guard
    Double_t SigmaAt(Int_t full) const noexcept { return full < static_cast<Int_t>(sigma.size()) ? sigma[full] : 0.0; }
 
    // Folds the presigmas into an already reduced system, as pseudo-measurements
    // of the parameters they refer to. accA is the accumulated solution in the
    // full layout (effective leaf corrections), null on the first iteration;
    // leaf priors are measured against its own-share part.
    void Apply(TVectorD& vB, TMatrixD& mC, const BmnAlignHierarchy& hierarchy, const TVectorD* accA) const;
 
    // Finds the independent constraints (see Kept()). kFALSE if the constraints
    // contradict each other, or if the composite parameters of the hierarchy are
    // not all determined by what is configured here, i.e. if the fit would be
    // singular along some direction of the level split. Logs the reason.
    Bool_t Check(const BmnAlignHierarchy& hierarchy);
 
  protected:
    Int_t fAllParams{0};   // the layout everything above is addressed in
    VecInt_t fKept;        // see Kept()
    TMatrixD fKeptRows;    // see KeptRows()
};
 
#endif   // BMNALIGNPRIORS_H