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

  PMsrHandler.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 _PMSRHANDLER_H_
#define _PMSRHANDLER_H_

#include <memory>
#include <sstream>
#include <string>

#include <TString.h>
#include <TComplex.h>

#include "PMusr.h"
#include "PFunctionHandler.h"
#include "PFunctionGrammar.h"
#include "PFunction.h"

//-------------------------------------------------------------
/**
 * \brief MSR file parser and manager for the musrfit framework.
 *
 * PMsrHandler is the central class for managing MSR (Muon Spin Rotation/Relaxation)
 * files used throughout the musrfit suite. It provides comprehensive functionality for:
 *
 * **File Operations:**
 * - Reading and parsing MSR files with full syntax validation
 * - Writing MSR files with fitted parameters and statistics
 * - Generating log files (.mlog) for debugging
 * - Preserving user comments during file I/O
 *
 * **Data Management:**
 * - Fit parameters (values, errors, constraints, names)
 * - Theory definitions (fit functions for asymmetry/relaxation)
 * - User-defined functions (mathematical expressions)
 * - Global settings (fit type, data format, etc.)
 * - Run configurations (data files, histograms, ranges)
 * - MINUIT commands (fit strategy, precision, etc.)
 * - Fourier transform parameters
 * - Plot settings
 * - Fit statistics (χ², degrees of freedom, convergence)
 *
 * **Validation and Integrity Checking:**
 * - Parameter name uniqueness verification
 * - Theory-to-parameter mapping validation
 * - Histogram grouping consistency checks
 * - RRF (Rotating Reference Frame) configuration validation
 * - Function syntax and parameter usage verification
 * - Map index range checking
 * - Legacy lifetimecorrection detection
 *
 * **MSR File Structure:**
 * An MSR file contains the following blocks (in order):
 * 1. TITLE - Brief description of the fit
 * 2. FITPARAMETER - Fit parameters with initial values and constraints
 * 3. THEORY - Asymmetry/relaxation function definitions
 * 4. FUNCTIONS (optional) - User-defined mathematical functions
 * 5. GLOBAL (optional) - Global fit settings
 * 6. RUN - Data file specifications and fit ranges
 * 7. COMMANDS - MINUIT fitting commands
 * 8. FOURIER (optional) - Fourier transform settings
 * 9. PLOT (optional) - Plotting parameters
 * 10. STATISTIC - Fit results (χ², NDF, convergence)
 *
 * **Usage Example:**
 * \code
 * // Reading an MSR file
 * PMsrHandler handler("run1234.msr");
 * if (handler.ReadMsrFile() == PMUSR_SUCCESS) {
 *   PMsrParamList *params = handler.GetMsrParamList();
 *
 *   // Access and modify parameters
 *   handler.SetMsrParamValue(0, 12.5);
 *
 *   // Perform fit (in calling code)
 *   // ...
 *
 *   // Update statistics and write results
 *   handler.SetMsrStatisticMin(chisq);
 *   handler.SetMsrStatisticNdf(ndf);
 *   handler.WriteMsrFile("run1234_fitted.msr");
 * }
 * \endcode
 *
 * \see PMusr.h for MSR data structure definitions
 * \see PFunctionHandler for user-defined function evaluation
 * \see PStartupOptions for configuration settings
 */
class PMsrHandler
{
  public:
    /**
     * <p>Constructor for PMsrHandler.
     *
     * @param fileName Path to MSR file to read/write
     * @param startupOptions Optional startup configuration (from musrfit_startup.xml)
     * @param fourierOnly If true, only parse Fourier-related blocks (for musrFT)
     */
    PMsrHandler(const Char_t *fileName, PStartupOptions *startupOptions=0, const Bool_t fourierOnly=false);

    virtual ~PMsrHandler();

    /**
     * <p>Reads and parses the MSR file.
     *
     * <p>Performs comprehensive parsing of all MSR file blocks including
     * TITLE, FITPARAMETER, THEORY, FUNCTIONS, GLOBAL, RUN, COMMANDS,
     * FOURIER, PLOT, and STATISTIC blocks. Validates consistency and
     * reports detailed error messages on failure.
     *
     * @return PMUSR_SUCCESS on success, negative error code on failure
     *
     * @see PMUSR_MSR_FILE_NOT_FOUND
     * @see PMUSR_MSR_SYNTAX_ERROR
     */
    virtual Int_t ReadMsrFile();

    /**
     * <p>Writes a log file with MSR file content and parsing information.
     *
     * <p>Creates a .mlog file containing the parsed MSR structure,
     * useful for debugging and verifying parameter interpretation.
     *
     * @param messages If true, includes informational messages in log
     * @return PMUSR_SUCCESS on success, negative error code on failure
     */
    virtual Int_t WriteMsrLogFile(const Bool_t messages = true);

    /**
     * <p>Writes MSR file with updated parameters and results.
     *
     * <p>Writes a complete MSR file, optionally preserving user comments
     * from specific blocks. Typically called after fitting to save
     * fitted parameters and statistics.
     *
     * @param filename Output MSR file path
     * @param commentsPAR Optional comments for FITPARAMETER block (line number → comment)
     * @param commentsTHE Optional comments for THEORY block
     * @param commentsFUN Optional comments for FUNCTIONS block
     * @param commentsRUN Optional comments for RUN block
     * @return PMUSR_SUCCESS on success, negative error code on failure
     */
    virtual Int_t WriteMsrFile(const Char_t *filename, std::map<UInt_t, TString> *commentsPAR = 0, std::map<UInt_t, TString> *commentsTHE = 0, \
                                                       std::map<UInt_t, TString> *commentsFUN = 0, std::map<UInt_t, TString> *commentsRUN = 0);

    /// Returns pointer to MSR file title string
    virtual TString*                GetMsrTitle() { return &fTitle; }
    /// Returns pointer to fit parameter list
    virtual PMsrParamList*          GetMsrParamList() { return &fParam; }
    /// Returns pointer to THEORY block lines
    virtual PMsrLines*              GetMsrTheory() { return &fTheory; }
    /// Returns pointer to FUNCTIONS block lines
    virtual PMsrLines*              GetMsrFunctions() { return &fFunctions; }
    /// Returns pointer to GLOBAL block settings
    virtual PMsrGlobalBlock*        GetMsrGlobal() { return &fGlobal; }
    /// Returns pointer to list of RUN blocks
    virtual PMsrRunList*            GetMsrRunList() { return &fRuns; }
    /// Returns pointer to COMMANDS block lines
    virtual PMsrLines*              GetMsrCommands() { return &fCommands; }
    /// Returns pointer to FOURIER block settings
    virtual PMsrFourierStructure*   GetMsrFourierList() { return &fFourier; }
    /// Returns pointer to list of PLOT blocks
    virtual PMsrPlotList*           GetMsrPlotList() { return &fPlots; }
    /// Returns pointer to STATISTIC block
    virtual PMsrStatisticStructure* GetMsrStatistic() { return &fStatistic; }

    /// Returns pointer to MSR file directory path
    virtual TString* GetMsrFileDirectoryPath() { return &fMsrFileDirectoryPath; }

    /// Returns the number of RUN blocks in MSR file
    virtual UInt_t GetNoOfRuns() { return fRuns.size(); }

    /// Returns the number of fit parameters in FITPARAMETER block
    virtual UInt_t GetNoOfParams() { return fParam.size(); }
    /// Returns the MSR file name
    virtual const TString& GetFileName() const { return fFileName; }

    /// Sets the MSR file title
    /// @param title New title string
    virtual void SetMsrTitle(const TString &title) { fTitle = title; }

    /**
     * <p>Sets the value of a fit parameter.
     *
     * @param i Parameter index (0-based)
     * @param value New parameter value
     * @return true on success, false if index out of range
     */
    virtual Bool_t SetMsrParamValue(UInt_t i, Double_t value);

    /**
     * <p>Sets the step size (or error) of a fit parameter.
     *
     * @param i Parameter index (0-based)
     * @param value New step/error value
     * @return true on success, false if index out of range
     */
    virtual Bool_t SetMsrParamStep(UInt_t i, Double_t value);

    /**
     * <p>Sets whether positive error is present for a parameter.
     *
     * @param i Parameter index (0-based)
     * @param value True if positive error is defined
     * @return true on success, false if index out of range
     */
    virtual Bool_t SetMsrParamPosErrorPresent(UInt_t i, Bool_t value);

    /**
     * <p>Sets the positive error value for a parameter (asymmetric errors).
     *
     * @param i Parameter index (0-based)
     * @param value Positive error value
     * @return true on success, false if index out of range
     */
    virtual Bool_t SetMsrParamPosError(UInt_t i, Double_t value);

    /**
     * <p>Sets a time-zero bin entry for a specific run.
     *
     * @param runNo Run block number (0-based)
     * @param idx Histogram index within t0 list
     * @param bin Time-zero bin value
     */
    virtual void SetMsrT0Entry(UInt_t runNo, UInt_t idx, Double_t bin);

    /**
     * <p>Sets a time-zero bin for an addrun histogram.
     *
     * @param runNo Run block number (0-based)
     * @param addRunIdx Index of addrun entry
     * @param histoIdx Histogram index within addrun
     * @param bin Time-zero bin value
     */
    virtual void SetMsrAddT0Entry(UInt_t runNo, UInt_t addRunIdx, UInt_t histoIdx, Double_t bin);

    /**
     * <p>Sets a data range bin entry for a specific run.
     *
     * @param runNo Run block number (0-based)
     * @param idx Data range index (0=start, 1=end, etc.)
     * @param bin Data range bin value
     */
    virtual void SetMsrDataRangeEntry(UInt_t runNo, UInt_t idx, Int_t bin);

    /**
     * <p>Sets a background range bin entry for a specific run.
     *
     * @param runNo Run block number (0-based)
     * @param idx Background range index (0=start, 1=end, etc.)
     * @param bin Background range bin value
     */
    virtual void SetMsrBkgRangeEntry(UInt_t runNo, UInt_t idx, Int_t bin);

    /// Flags that STATISTIC block should be copied as-is (for musrt0)
    virtual void CopyMsrStatisticBlock() { fCopyStatisticsBlock = true; }

    /// Sets whether fit converged in STATISTIC block
    /// @param converged True if fit converged successfully
    virtual void SetMsrStatisticConverged(Bool_t converged) { fStatistic.fValid = converged; }

    /// Sets the minimum χ² (or max likelihood) in STATISTIC block
    /// @param min Minimum value
    virtual void SetMsrStatisticMin(Double_t min) { fStatistic.fMin = min; }

    /// Sets the number of degrees of freedom in STATISTIC block
    /// @param ndf Degrees of freedom
    virtual void SetMsrStatisticNdf(UInt_t ndf) { fStatistic.fNdf = ndf; }

    /// Returns the number of user-defined functions in FUNCTIONS block
    virtual Int_t GetNoOfFuncs() { return fFuncHandler->GetNoOfFuncs(); }

    /**
     * <p>Gets function number by index.
     *
     * @param idx Function index (0-based)
     * @return Function number as defined in FUNCTIONS block
     */
    virtual UInt_t GetFuncNo(Int_t idx) { return fFuncHandler->GetFuncNo(idx); }

    /**
     * <p>Gets function index from function number.
     *
     * @param funNo Function number
     * @return Function index (0-based)
     */
    virtual UInt_t GetFuncIndex(Int_t funNo) { return fFuncHandler->GetFuncIndex(funNo); }

    /**
     * <p>Checks if map and parameter ranges are valid for functions.
     *
     * @param mapSize Size of map vector
     * @param paramSize Number of available parameters
     * @return true if ranges are valid
     */
    virtual Bool_t CheckMapAndParamRange(UInt_t mapSize, UInt_t paramSize)
                       { return fFuncHandler->CheckMapAndParamRange(mapSize, paramSize); }

    /**
     * <p>Evaluates a user-defined function.
     *
     * @param i Function index
     * @param map Parameter mapping vector
     * @param param Parameter value vector
     * @param metaData Experimental metadata (field, temperature, etc.)
     * @return Evaluated function value
     */
    virtual Double_t EvalFunc(UInt_t i, std::vector<Int_t> map, std::vector<Double_t> param, PMetaData metaData)
                       { return fFuncHandler->Eval(i, map, param, metaData); }

    /**
     * <p>Gets the number of fit parameters used in a specific theory line.
     *
     * @param idx Theory line index
     * @return Number of parameters used
     */
    virtual UInt_t GetNoOfFitParameters(UInt_t idx);

    /**
     * <p>Checks if a parameter is used in theory or functions.
     *
     * @param paramNo Parameter number (1-based as in MSR file)
     * @return 1 if used, 0 if unused, -1 on error
     */
    virtual Int_t ParameterInUse(UInt_t paramNo);

    /**
     * <p>Generates a grouping string for histogram display.
     *
     * @param runNo Run block number
     * @param detector Detector identifier ("forward" or "backward")
     * @param groupingStr Output grouping string
     */
    virtual void GetGroupingString(Int_t runNo, TString detector, TString &groupingStr);

    /**
     * <p>Estimates N0 parameter for single histogram fits.
     *
     * <p>Uses data amplitude at t=0 to provide initial N0 estimate,
     * improving fit convergence for single histogram fits.
     *
     * @return true on success
     */
    virtual Bool_t EstimateN0();

    /// Returns the last error message as a string
    /// @return Error message string
    virtual std::string GetLastErrorMsg() { return fLastErrorMsg.str(); }

  private:
    Bool_t                 fFourierOnly; ///< Flag indicating Fourier transform only mode (for musrFT)
    PStartupOptions       *fStartupOptions; ///< Pointer to startup options from musrfit_startup.xml

    TString                fFileName;  ///< MSR file name (with path)
    TString                fMsrFileDirectoryPath; ///< Directory path of the MSR file
    TString                fTitle;     ///< MSR file title string
    PMsrParamList          fParam;     ///< List of fit parameters with values, errors, constraints
    PMsrLines              fTheory;    ///< Theory block lines defining asymmetry/relaxation functions
    PMsrLines              fFunctions; ///< User-defined functions block lines
    PMsrGlobalBlock        fGlobal;    ///< Global block settings (fit type, data format, etc.)
    PMsrRunList            fRuns;      ///< List of RUN blocks with data file specifications
    PMsrLines              fCommands;  ///< MINUIT commands block lines
    PMsrFourierStructure   fFourier;   ///< Fourier transform parameters and settings
    PMsrPlotList           fPlots;     ///< List of PLOT blocks with plotting parameters
    PMsrStatisticStructure fStatistic; ///< Fit statistics (χ², NDF, convergence status)

    Int_t  fMsrBlockCounter; ///< Counter to track current MSR block during parsing

    std::unique_ptr<PFunctionHandler> fFuncHandler; ///< Handler for parsing and evaluating user-defined functions

    PIntVector fParamInUse; ///< Flags indicating which parameters are actually used in theory/functions

    Bool_t fCopyStatisticsBlock; ///< If true, copy old statistics block (musrt0); if false, write new one (musrfit)

    std::stringstream fLastErrorMsg; ///< Stream accumulating error messages during parsing

    /// Parses FITPARAMETER block entries
    virtual Bool_t HandleFitParameterEntry(PMsrLines &line);
    /// Parses THEORY block entries
    virtual Bool_t HandleTheoryEntry(PMsrLines &line);
    /// Parses FUNCTIONS block entries
    virtual Bool_t HandleFunctionsEntry(PMsrLines &line);
    /// Parses GLOBAL block entries
    virtual Bool_t HandleGlobalEntry(PMsrLines &line);
    /// Parses RUN block entries
    virtual Bool_t HandleRunEntry(PMsrLines &line);
    /// Parses COMMANDS block entries
    virtual Bool_t HandleCommandsEntry(PMsrLines &line);
    /// Parses FOURIER block entries
    virtual Bool_t HandleFourierEntry(PMsrLines &line);
    /// Parses PLOT block entries
    virtual Bool_t HandlePlotEntry(PMsrLines &line);
    /// Parses STATISTIC block entries
    virtual Bool_t HandleStatisticEntry(PMsrLines &line);

    /// Determines which parameters are used in theory and functions
    virtual void FillParameterInUse(PMsrLines &theory, PMsrLines &funcs, PMsrLines &run);

    /// Initializes Fourier parameter structure with default values
    virtual void InitFourierParameterStructure(PMsrFourierStructure &fourier);
    /// Removes comments from MSR file line
    virtual void RemoveComment(const TString &str, TString &truncStr);
    /// Parses Fourier phase value vector
    virtual Bool_t ParseFourierPhaseValueVector(PMsrFourierStructure &fourier, const TString &str, Bool_t &error);
    /// Parses Fourier phase parameter vector
    virtual Bool_t ParseFourierPhaseParVector(PMsrFourierStructure &fourier, const TString &str, Bool_t &error);
    /// Parses Fourier phase parameter iteration vector
    virtual Bool_t ParseFourierPhaseParIterVector(PMsrFourierStructure &fourier, const TString &str, Bool_t &error);

    /// Extracts number from string with specific filter pattern
    virtual Bool_t FilterNumber(TString str, const Char_t *filter, Int_t offset, Int_t &no);

    /// Calculates precision needed for formatting a double value
    virtual UInt_t NeededPrecision(Double_t dval, UInt_t precLimit=13);
    /// Finds position of last significant digit in a double value
    virtual UInt_t LastSignificant(Double_t dval, UInt_t precLimit=6);

    /// Creates detector grouping string from integer vector
    virtual void MakeDetectorGroupingString(TString str, PIntVector &group, TString &result, Bool_t includeDetector = true);
    /// Formats Fourier phase parameter string for display
    virtual TString BeautifyFourierPhaseParameterString();

    /// Checks for deprecated lifetimecorrection syntax and warns user
    virtual void CheckLegacyLifetimecorrection();
    /// Validates RUN block structure and consistency
    virtual Bool_t CheckRunBlockIntegrity();
    /// Checks that all parameter names are unique
    virtual Bool_t CheckUniquenessOfParamNames(UInt_t &parX, UInt_t &parY);
    /// Validates that all map indices are within parameter range
    virtual Bool_t CheckMaps();
    /// Validates user-defined functions syntax and parameter usage
    virtual Bool_t CheckFuncs();
    /// Checks histogram grouping consistency across runs
    virtual Bool_t CheckHistoGrouping();
    /// Validates addrun parameter references
    virtual Bool_t CheckAddRunParameters();
    /// Validates RRF (Rotating Reference Frame) settings
    virtual Bool_t CheckRRFSettings();
    /// Checks if real FFT requirements are met
    virtual Bool_t CheckRealFFT();
    /// Validates maximum likelihood fit settings
    virtual void CheckMaxLikelihood();
};

#endif // _PMSRHANDLER_H_