LMU/musrfit
5
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 4 Activity

use Claude ai to generate doxygen documentation.

Browse Source
This commit is contained in:
suter_a
2025-11-10 15:14:08 +01:00
parent aa348c2393
commit 4d70c7baa9
8 changed files with 1751 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
src/include/PMsrHandler.h
View File

@@ -45,67 +45,292 @@
//-------------------------------------------------------------
/**
* <p>This class provides the routines needed to handle msr-files, i.e. reading, writing, parsing, etc.
* <p>MSR file parser and manager for 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
*
* <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
*
* <p><b>Usage pattern:</b>
* @code
* PMsrHandler handler("myfile.msr");
* if (handler.ReadMsrFile() == PMUSR_SUCCESS) {
* PMsrParamList *params = handler.GetMsrParamList();
* // Process parameters, run fits, etc.
* handler.WriteMsrFile("output.msr");
* }
* @endcode
*/
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(); }
virtual std::string GetDKSTheoryString();