improve doxygen documentation of PMsrHandler.*
This commit is contained in:
@@ -45,13 +45,28 @@
|
||||
// Constructor
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Constructor
|
||||
* \brief Constructor that initializes the MSR handler.
|
||||
*
|
||||
* \param fileName name of a msr-file.
|
||||
* Initializes all internal data structures and extracts the directory path
|
||||
* from the MSR file name. The directory path is used for resolving relative
|
||||
* paths in the MSR file (e.g., for data files).
|
||||
*
|
||||
* Initialization includes:
|
||||
* - Setting default values for all MSR blocks
|
||||
* - Initializing statistics structure (invalid, χ² mode, min=-1, ndf=0)
|
||||
* - Extracting file directory path from file name
|
||||
* - Setting block counter to 0
|
||||
*
|
||||
* \param fileName Path to MSR file (absolute or relative)
|
||||
* \param startupOptions Optional pointer to startup configuration from musrfit_startup.xml
|
||||
* \param fourierOnly If true, only parse Fourier-related blocks (used by musrFT tool)
|
||||
*
|
||||
* \note If fileName contains "/" characters, the directory path is extracted
|
||||
* and stored in fMsrFileDirectoryPath; otherwise defaults to "./"
|
||||
*/
|
||||
PMsrHandler::PMsrHandler(const Char_t *fileName, PStartupOptions *startupOptions, const Bool_t fourierOnly) :
|
||||
fFourierOnly(fourierOnly), fStartupOptions(startupOptions), fFileName(fileName)
|
||||
{
|
||||
{
|
||||
// init variables
|
||||
fMsrBlockCounter = 0;
|
||||
|
||||
@@ -83,7 +98,19 @@ PMsrHandler::PMsrHandler(const Char_t *fileName, PStartupOptions *startupOptions
|
||||
// Destructor
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Destructor
|
||||
* \brief Destructor that cleans up all data structures.
|
||||
*
|
||||
* Clears all vectors and releases memory:
|
||||
* - Parameter list
|
||||
* - Theory lines
|
||||
* - Functions lines
|
||||
* - Run configurations
|
||||
* - MINUIT commands
|
||||
* - Plot settings
|
||||
* - Statistics data
|
||||
* - Parameter usage flags
|
||||
*
|
||||
* The unique_ptr member (fFuncHandler) is automatically cleaned up.
|
||||
*/
|
||||
PMsrHandler::~PMsrHandler()
|
||||
{
|
||||
@@ -103,11 +130,46 @@ PMsrHandler::~PMsrHandler()
|
||||
// ReadMsrFile (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Reads and parses a msr-file.
|
||||
* \brief Reads and parses the MSR file.
|
||||
*
|
||||
* <p><b>return:</b>
|
||||
* - PMUSR_SUCCESS if everything is OK
|
||||
* - line number if an error in the MSR file was encountered which cannot be handled.
|
||||
* Performs comprehensive parsing of all MSR file blocks in the following order:
|
||||
* 1. TITLE - File description
|
||||
* 2. FITPARAMETER - Fit parameters with values, errors, 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 parameters
|
||||
* 9. PLOT (optional) - Plotting parameters
|
||||
* 10. STATISTIC - Fit results (χ², NDF, convergence)
|
||||
*
|
||||
* After parsing, performs extensive validation:
|
||||
* - Checks for legacy lifetimecorrection syntax
|
||||
* - Validates RUN block integrity (required fields, grouping consistency)
|
||||
* - Verifies parameter name uniqueness
|
||||
* - Checks map index validity
|
||||
* - Validates user-defined functions
|
||||
* - Verifies histogram grouping consistency
|
||||
* - Checks addrun parameter references
|
||||
* - Validates RRF (Rotating Reference Frame) settings
|
||||
* - Checks real FFT requirements
|
||||
* - Validates maximum likelihood settings
|
||||
*
|
||||
* Error Handling:
|
||||
* - Detailed error messages are written to stderr
|
||||
* - Error messages are accumulated in fLastErrorMsg for programmatic access
|
||||
* - Returns line number where error occurred for syntax errors
|
||||
*
|
||||
* \return
|
||||
* - PMUSR_SUCCESS (0) if parsing succeeded
|
||||
* - PMUSR_MSR_FILE_NOT_FOUND if file cannot be opened
|
||||
* - PMUSR_MSR_SYNTAX_ERROR if syntax error encountered
|
||||
* - Positive line number if parsing error occurred at specific line
|
||||
*
|
||||
* \note In Fourier-only mode (fFourierOnly=true), only relevant blocks are parsed
|
||||
*
|
||||
* \see HandleFitParameterEntry, HandleTheoryEntry, HandleRunEntry for block parsing
|
||||
*/
|
||||
Int_t PMsrHandler::ReadMsrFile()
|
||||
{
|
||||
@@ -341,15 +403,42 @@ Int_t PMsrHandler::ReadMsrFile()
|
||||
// WriteMsrLogFile (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Writes a mlog-file.
|
||||
* \brief Writes an MSR log file (.mlog) with parsed MSR content.
|
||||
*
|
||||
* <p><b>return:</b>
|
||||
* - PMUSR_SUCCESS everything is OK
|
||||
* - PMUSR_MSR_LOG_FILE_WRITE_ERROR msr-/mlog-file couldn't be opened
|
||||
* - PMUSR_MSR_SYNTAX_ERROR a syntax error has been encountered
|
||||
* Creates a log file with the same base name as the MSR file but with .mlog
|
||||
* extension. The log file contains the parsed and formatted MSR structure,
|
||||
* which is useful for:
|
||||
* - Debugging MSR file parsing
|
||||
* - Verifying parameter interpretation
|
||||
* - Checking fit range calculations
|
||||
* - Reviewing theory and function definitions
|
||||
*
|
||||
* \param messages if true some additional messages concerning the statistic block are written.
|
||||
* When using musrt0, messages will be set to false.
|
||||
* The log file format mirrors the MSR file structure but with:
|
||||
* - Standardized formatting and precision
|
||||
* - Expanded parameter values
|
||||
* - Calculated fit ranges (in bins and microseconds)
|
||||
* - Resolved function definitions
|
||||
* - Complete statistics (if available)
|
||||
*
|
||||
* Processing includes:
|
||||
* - Re-reading original MSR file to preserve comments and structure
|
||||
* - Identifying missing tags (t0, background, data) in RUN blocks
|
||||
* - Formatting numeric values with appropriate precision
|
||||
* - Writing all MSR blocks in canonical format
|
||||
*
|
||||
* \param messages If true, includes additional informational messages about
|
||||
* the statistics block. Set to false when called from musrt0
|
||||
* to suppress messages.
|
||||
*
|
||||
* \return
|
||||
* - PMUSR_SUCCESS if log file written successfully
|
||||
* - PMUSR_MSR_LOG_FILE_WRITE_ERROR if MSR or log file cannot be opened
|
||||
* - PMUSR_MSR_SYNTAX_ERROR if syntax error encountered during processing
|
||||
*
|
||||
* \note The log file name is constructed by replacing the MSR file extension
|
||||
* with ".mlog" (e.g., "run1234.msr" → "run1234.mlog")
|
||||
*
|
||||
* \see WriteMsrFile for writing updated MSR files
|
||||
*/
|
||||
Int_t PMsrHandler::WriteMsrLogFile(const Bool_t messages)
|
||||
{
|
||||
@@ -1549,13 +1638,51 @@ Int_t PMsrHandler::WriteMsrLogFile(const Bool_t messages)
|
||||
// WriteMsrFile (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Writes a msr-file from the internal data structures
|
||||
* \brief Writes an MSR file from internal data structures.
|
||||
*
|
||||
* <p><b>return:</b>
|
||||
* - PMUSR_SUCCESS everything is OK
|
||||
* - PMUSR_MSR_FILE_WRITE_ERROR msr output file couldn't be opened
|
||||
* Creates a complete MSR file with all blocks, typically called after fitting
|
||||
* to save updated parameter values, errors, and fit statistics. The file
|
||||
* includes properly formatted blocks in the standard MSR file order.
|
||||
*
|
||||
* \param filename The name of the output file.
|
||||
* **MSR File Structure Written:**
|
||||
* 1. TITLE block
|
||||
* 2. FITPARAMETER block (with fitted values and errors)
|
||||
* 3. THEORY block
|
||||
* 4. FUNCTIONS block (if functions are defined)
|
||||
* 5. GLOBAL block (if global settings exist)
|
||||
* 6. RUN blocks (one per run)
|
||||
* 7. COMMANDS block
|
||||
* 8. FOURIER block (if Fourier parameters are defined)
|
||||
* 9. PLOT blocks (if plot settings exist)
|
||||
* 10. STATISTIC block (with fit results)
|
||||
*
|
||||
* **Comment Preservation:**
|
||||
* The comment maps allow preserving user comments from specific MSR blocks.
|
||||
* Comments are inserted before the corresponding line based on the map key
|
||||
* (line number). This is useful when updating MSR files while maintaining
|
||||
* documentation.
|
||||
*
|
||||
* **Formatting:**
|
||||
* - Parameters: Right-aligned numbers, left-aligned names and values
|
||||
* - Precision: 6 significant digits for floating-point values
|
||||
* - Boundaries: Properly formatted lower/upper limits
|
||||
* - Separators: Dashed lines between major sections
|
||||
*
|
||||
* \param filename Output MSR file path
|
||||
* \param commentsPAR Optional map of line number → comment for FITPARAMETER block
|
||||
* \param commentsTHE Optional map of line number → comment for THEORY block
|
||||
* \param commentsFUN Optional map of line number → comment for FUNCTIONS block
|
||||
* \param commentsRUN Optional map of line number → comment for RUN blocks
|
||||
*
|
||||
* \return
|
||||
* - PMUSR_SUCCESS if file written successfully
|
||||
* - PMUSR_MSR_FILE_WRITE_ERROR if output file cannot be opened
|
||||
*
|
||||
* \note Comments are removed from the maps after being written
|
||||
* \note The STATISTIC block content depends on fCopyStatisticsBlock flag
|
||||
*
|
||||
* \see WriteMsrLogFile for writing debug/verification log files
|
||||
* \see SetMsrStatisticMin, SetMsrStatisticNdf for updating statistics
|
||||
*/
|
||||
Int_t PMsrHandler::WriteMsrFile(const Char_t *filename, std::map<UInt_t, TString> *commentsPAR, \
|
||||
std::map<UInt_t, TString> *commentsTHE, \
|
||||
|
||||
Reference in New Issue
Block a user