Andreas Suter
3d07894b2d
All checks were successful
Build and Deploy Documentation / build-and-deploy (push) Successful in 17s
209 lines
8.5 KiB
C++
209 lines
8.5 KiB
C++
/***************************************************************************
|
||
|
||
PRunBase.h
|
||
|
||
Author: Andreas Suter
|
||
e-mail: andreas.suter@psi.ch
|
||
|
||
***************************************************************************/
|
||
|
||
/***************************************************************************
|
||
* Copyright (C) 2007-2025 by Andreas Suter *
|
||
* andreas.suter@psi.ch *
|
||
* *
|
||
* This program is free software; you can redistribute it and/or modify *
|
||
* it under the terms of the GNU General Public License as published by *
|
||
* the Free Software Foundation; either version 2 of the License, or *
|
||
* (at your option) any later version. *
|
||
* *
|
||
* This program is distributed in the hope that it will be useful, *
|
||
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
|
||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
|
||
* GNU General Public License for more details. *
|
||
* *
|
||
* You should have received a copy of the GNU General Public License *
|
||
* along with this program; if not, write to the *
|
||
* Free Software Foundation, Inc., *
|
||
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
|
||
***************************************************************************/
|
||
|
||
#ifndef _PRUNBASE_H_
|
||
#define _PRUNBASE_H_
|
||
|
||
#include <vector>
|
||
#include <memory>
|
||
|
||
#include <TString.h>
|
||
|
||
#include "PMusr.h"
|
||
#include "PMsrHandler.h"
|
||
#include "PRunDataHandler.h"
|
||
#include "PTheory.h"
|
||
|
||
//------------------------------------------------------------------------------------------
|
||
/**
|
||
* <p>Abstract base class defining the interface for all μSR fit types.
|
||
*
|
||
* <p>PRunBase establishes a common API for processing and fitting different
|
||
* types of μSR data (single histogram, asymmetry, RRF, etc.). Derived classes
|
||
* implement specific data processing and χ² calculation for each fit type:
|
||
* - <b>PRunSingleHisto:</b> Single detector histogram fits
|
||
* - <b>PRunAsymmetry:</b> Asymmetry fits (forward - backward)
|
||
* - <b>PRunSingleHistoRRF:</b> Single histogram in rotating reference frame
|
||
* - <b>PRunAsymmetryRRF:</b> Asymmetry in rotating reference frame
|
||
* - <b>PRunMuMinus:</b> Negative muon fits
|
||
* - <b>PRunNonMusr:</b> General x-y data fits
|
||
*
|
||
* <p><b>Key responsibilities:</b>
|
||
* - Loading and preprocessing raw histogram data
|
||
* - Background subtraction and normalization
|
||
* - Time bin packing/rebinning
|
||
* - Theory evaluation at data points
|
||
* - χ² or maximum likelihood calculation
|
||
* - RRF transformations (if applicable)
|
||
*
|
||
* <p><b>Processing workflow:</b>
|
||
* 1. <tt>PrepareData()</tt> - Load and preprocess raw data
|
||
* 2. <tt>CalcTheory()</tt> - Evaluate theory function
|
||
* 3. <tt>CalcChiSquare()</tt> or <tt>CalcMaxLikelihood()</tt> - Compute fit metric
|
||
*
|
||
* <p><b>Design pattern:</b> Template Method - base class defines workflow,
|
||
* derived classes implement fit-type-specific algorithms.
|
||
*/
|
||
class PRunBase
|
||
{
|
||
public:
|
||
/// Default constructor
|
||
PRunBase();
|
||
|
||
/**
|
||
* <p>Constructor initializing run from MSR file and raw data.
|
||
*
|
||
* @param msrInfo Pointer to MSR file handler
|
||
* @param rawData Pointer to raw data handler
|
||
* @param runNo Run number (0-based index in MSR file)
|
||
* @param tag Operation mode (kFit, kView)
|
||
*/
|
||
PRunBase(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag);
|
||
|
||
virtual ~PRunBase();
|
||
|
||
/**
|
||
* <p>Calculates χ² between data and theory (pure virtual).
|
||
*
|
||
* <p>χ² = Σ[(data_i - theory_i)² / σ_i²] summed over all data points.
|
||
* This is the standard least-squares metric for fitting.
|
||
*
|
||
* @param par Vector of fit parameter values
|
||
* @return Chi-squared value
|
||
*/
|
||
virtual Double_t CalcChiSquare(const std::vector<Double_t>& par) = 0;
|
||
|
||
/**
|
||
* <p>Calculates maximum likelihood (pure virtual).
|
||
*
|
||
* <p>For Poisson statistics: -2ln(L) = 2Σ[theory_i - data_i·ln(theory_i)]
|
||
* Better than χ² for low-count data where Gaussian approximation fails.
|
||
*
|
||
* @param par Vector of fit parameter values
|
||
* @return Negative 2 times log-likelihood
|
||
*/
|
||
virtual Double_t CalcMaxLikelihood(const std::vector<Double_t>& par) = 0;
|
||
|
||
/**
|
||
* <p>Sets the fit time range for this run.
|
||
*
|
||
* <p>Updates the fitting window, useful for FIT_RANGE command which
|
||
* scans different time windows to find the optimal range.
|
||
*
|
||
* @param fitRange Vector of (start, end) time pairs in microseconds
|
||
*/
|
||
virtual void SetFitRange(PDoublePairVector fitRange);
|
||
|
||
/**
|
||
* <p>Evaluates theory function at all data points (pure virtual).
|
||
*
|
||
* <p>Uses current parameter values to calculate expected signal
|
||
* at each time point. Called during each fit iteration.
|
||
*/
|
||
virtual void CalcTheory() = 0;
|
||
|
||
/// Returns the run number (0-based index in MSR file)
|
||
/// @return Run number
|
||
virtual UInt_t GetRunNo() { return fRunNo; }
|
||
|
||
/// Returns pointer to processed data (background-corrected, binned)
|
||
/// @return Pointer to PRunData object
|
||
virtual PRunData* GetData() { return &fData; }
|
||
|
||
/// Cleans up internal data structures
|
||
virtual void CleanUp();
|
||
|
||
/// Returns validity status of this run object
|
||
/// @return true if run initialized successfully
|
||
virtual Bool_t IsValid() { return fValid; }
|
||
|
||
protected:
|
||
Bool_t fValid; ///< Flag showing if the run object initialized successfully
|
||
|
||
EPMusrHandleTag fHandleTag; ///< Operation mode: kFit (fitting), kView (display only)
|
||
|
||
Int_t fRunNo; ///< Run number (0-based index in MSR file RUN blocks)
|
||
PMsrHandler *fMsrInfo; ///< Pointer to MSR file handler
|
||
PMsrRunBlock *fRunInfo; ///< Pointer to this run's RUN block settings
|
||
PRunDataHandler *fRawData; ///< Pointer to raw data handler for this run
|
||
|
||
PRunData fData; ///< Processed data ready for fitting (background-corrected, packed, etc.)
|
||
Double_t fTimeResolution; ///< Time resolution of raw data in microseconds (μs)
|
||
PMetaData fMetaData; ///< Experimental metadata (field, temperature, energy) from data file
|
||
PDoubleVector fT0s; ///< Time-zero bins for all histograms in this run
|
||
std::vector<PDoubleVector> fAddT0s; ///< Time-zero bins for all addrun histograms
|
||
|
||
Double_t fFitStartTime; ///< Fit range start time in microseconds (μs)
|
||
Double_t fFitEndTime; ///< Fit range end time in microseconds (μs)
|
||
|
||
PDoubleVector fFuncValues; ///< Values of user-defined functions from FUNCTIONS block
|
||
std::unique_ptr<PTheory> fTheory; ///< Theory function evaluator for χ² calculation
|
||
|
||
PDoubleVector fKaiserFilter; ///< Kaiser window coefficients for RRF filtering
|
||
|
||
/**
|
||
* <p>Prepares raw data for fitting (pure virtual).
|
||
*
|
||
* <p>Performs fit-type-specific preprocessing:
|
||
* - Background subtraction
|
||
* - Asymmetry calculation (if applicable)
|
||
* - Time bin packing/rebinning
|
||
* - RRF transformation (if applicable)
|
||
* - Error propagation
|
||
*
|
||
* <p>Called during initialization before fitting begins.
|
||
*
|
||
* @return true on success, false on error
|
||
*/
|
||
virtual Bool_t PrepareData() = 0;
|
||
|
||
/**
|
||
* <p>Calculates Kaiser window filter coefficients for RRF.
|
||
*
|
||
* <p>The Kaiser window reduces spectral leakage when transforming
|
||
* to the rotating reference frame. Parameters control the trade-off
|
||
* between main lobe width and side lobe suppression.
|
||
*
|
||
* @param wc Cutoff frequency (normalized, 0 to π)
|
||
* @param A Attenuation in dB (controls side lobe level)
|
||
* @param dw Transition width (normalized)
|
||
*/
|
||
virtual void CalculateKaiserFilterCoeff(Double_t wc, Double_t A, Double_t dw);
|
||
|
||
/**
|
||
* <p>Applies Kaiser filter to theory values for RRF.
|
||
*
|
||
* <p>Filters the theory function in the same way data is filtered,
|
||
* ensuring consistent comparison between data and theory in RRF fits.
|
||
*/
|
||
virtual void FilterTheo();
|
||
};
|
||
|
||
#endif // _PRUNBASE_H_
|