BmnAlignReport.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
 
    BmnAlignReport class declaration
    Textual analysis of alignment results
*/
 
#ifndef BMNALIGNREPORT_H
#define BMNALIGNREPORT_H
 
#include "BmnAligner.h"
 
#include <TPad.h>
 
class TH1;   // only pointers and references to it are named below
 
/*
 *  Reads what an alignment run produced and logs it: the summary of a finished
 *  run, the weak modes of the solved system, and the parameter correlations.
 *
 *  A consumer of BmnAligner, not a part of it - everything here is read-only
 *  over the aligner's public interface, so there is no state to hold and the
 *  methods are static. Weak mode analysis may write a constraints snippet file,
 *  and Draw() creates a canvas; those are the only side effects.
 */
 
class BmnAlignReport
{
  public:
    BmnAlignReport() = delete;
 
    // summary of a finished run: MSE and residual changes, constraint
    // satisfaction, composite corrections, timings
    static void Results(const BmnAligner& aligner);
 
    // eigenvectors of the solved system below an eigenvalue threshold, with
    // their overlap against the constraints already in force. With dumpNew the
    // unconstrained ones are written out as a ready-to-paste constraints file.
    static void ModesBelow(const BmnAligner& aligner, Double_t absThreshold, Bool_t dumpNew = kTRUE);
 
    // parameter pairs whose correlation exceeds a threshold, plus the
    // per-parameter global correlation
    static void Correlations(const BmnAligner& aligner,
                             Double_t absThreshold = 0.9,
                             Int_t topK = 20,
                             Bool_t skipIntraDet = kFALSE);
 
    // Canvas view of a result: residuals before and after, the SVD spectrum
    // tail, and a sample of tracks in 3D. Everything drawn is copied, so the
    // canvas keeps working after the aligner it was built from is gone.
    // number is the ordered number of the result starting from 1, negative
    // values mean counting from the end.
    static void Draw(const BmnAligner& aligner, Int_t number = -1);
 
  protected:
    // relative change of a value, as a percentage or in orders of magnitude
    static char* Change(Double_t before, Double_t after);
 
    // the eight pads Draw() lays out, passed between its helpers instead of
    // being held as state - there is nothing to remember between calls
    struct Pads
    {
        TPad *resSXbefore{nullptr},   // synthetic X residuals before alignment
            *resSXafter{nullptr},     // synthetic X residuals after  alignment
            *resSYbefore{nullptr},    // synthetic Y residuals before alignment
            *resSYafter{nullptr},     // synthetic Y residuals after  alignment
            *resX{nullptr},           // 1D total residuals by X
            *resY{nullptr},           // 1D total residuals by Y
            *svd{nullptr},            // SVD singular values
            *tracks{nullptr};         // 3D tracks visualization
    };
    static Pads PrepareCanvas();
    static void DrawResiduals(const BmnAligner& aligner, const Pads& pads, std::size_t idx);
 
  private:
    // A pad must not point into the aligner's own histograms: the canvas
    // outlives the run in macro mode, and redrawing a deleted histogram would
    // crash. Every plot is therefore drawn from a detached copy.
    static TH1* ClonePlot(const TH1& source);
};
 
#endif   // BMNALIGNREPORT_H