472 lines
20 KiB
C++
472 lines
20 KiB
C++
/***************************************************************************
|
|
|
|
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_
|