improve doxygen documentation of PMsrHandler.*
This commit is contained in:
@@ -44,32 +44,73 @@
|
||||
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>MSR file parser and manager for musrfit framework.
|
||||
* \brief MSR file parser and manager for the musrfit framework.
|
||||
*
|
||||
* <p>This class handles all MSR (Muon Spin Rotation) file operations including:
|
||||
* - Reading and parsing MSR files
|
||||
* - Writing MSR files and log files
|
||||
* - Validating MSR file content (parameter ranges, theory consistency, etc.)
|
||||
* - Managing fit parameters, theory definitions, run configurations
|
||||
* - Evaluating user-defined functions
|
||||
* - Handling parameter mapping between runs
|
||||
* PMsrHandler is the central class for managing MSR (Muon Spin Rotation/Relaxation)
|
||||
* files used throughout the musrfit suite. It provides comprehensive functionality for:
|
||||
*
|
||||
* <p>The PMsrHandler performs comprehensive validation during parsing, checking for:
|
||||
* - Parameter name uniqueness
|
||||
* - Valid theory-to-parameter mappings
|
||||
* - Histogram grouping consistency
|
||||
* - RRF (Rotating Reference Frame) settings
|
||||
* - Function syntax and parameter usage
|
||||
* **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
|
||||
*
|
||||
* <p><b>Usage pattern:</b>
|
||||
* @code
|
||||
* PMsrHandler handler("myfile.msr");
|
||||
* **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();
|
||||
* // Process parameters, run fits, etc.
|
||||
* handler.WriteMsrFile("output.msr");
|
||||
*
|
||||
* // 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
|
||||
* \endcode
|
||||
*
|
||||
* \see PMusr.h for MSR data structure definitions
|
||||
* \see PFunctionHandler for user-defined function evaluation
|
||||
* \see PStartupOptions for configuration settings
|
||||
*/
|
||||
class PMsrHandler
|
||||
{
|
||||
@@ -333,67 +374,97 @@ class PMsrHandler
|
||||
virtual std::string GetLastErrorMsg() { return fLastErrorMsg.str(); }
|
||||
|
||||
private:
|
||||
Bool_t fFourierOnly; ///< flag indicating if Fourier transform only is wished. If yes, some part of the msr-file blocks are not needed.
|
||||
PStartupOptions *fStartupOptions; ///< contains information about startup options from the musrfit_startup.xml
|
||||
Bool_t fFourierOnly; ///< Flag indicating Fourier transform only mode (for musrFT)
|
||||
PStartupOptions *fStartupOptions; ///< Pointer to startup options from musrfit_startup.xml
|
||||
|
||||
TString fFileName; ///< file name of the msr-file
|
||||
TString fMsrFileDirectoryPath; ///< msr-file directory path
|
||||
TString fTitle; ///< holds the title string of the msr-file
|
||||
PMsrParamList fParam; ///< holds a list of the fit parameters
|
||||
PMsrLines fTheory; ///< holds the theory definition
|
||||
PMsrLines fFunctions; ///< holds the user defined functions
|
||||
PMsrGlobalBlock fGlobal; ///< holds the information of the global section
|
||||
PMsrRunList fRuns; ///< holds a list of run information
|
||||
PMsrLines fCommands; ///< holds a list of the minuit commands
|
||||
PMsrFourierStructure fFourier; ///< holds the parameters used for the Fourier transform
|
||||
PMsrPlotList fPlots; ///< holds a list of the plot input parameters
|
||||
PMsrStatisticStructure fStatistic; ///< holds the statistic info
|
||||
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; ///< used to select the proper msr-block
|
||||
Int_t fMsrBlockCounter; ///< Counter to track current MSR block during parsing
|
||||
|
||||
std::unique_ptr<PFunctionHandler> fFuncHandler; ///< needed to parse functions
|
||||
std::unique_ptr<PFunctionHandler> fFuncHandler; ///< Handler for parsing and evaluating user-defined functions
|
||||
|
||||
PIntVector fParamInUse; ///< array holding the information if a particular parameter is used at all, i.e. if the theory is using it (perhaps via maps or functions)
|
||||
PIntVector fParamInUse; ///< Flags indicating which parameters are actually used in theory/functions
|
||||
|
||||
Bool_t fCopyStatisticsBlock; ///< flag, if true: just copy to old statistics block (musrt0), otherwise write a new one (musrfit)
|
||||
Bool_t fCopyStatisticsBlock; ///< If true, copy old statistics block (musrt0); if false, write new one (musrfit)
|
||||
|
||||
std::stringstream fLastErrorMsg;
|
||||
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();
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user