/***************************************************************************

  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_