improve the doxygen docu with the help of Claude AI.

src/classes/PFitter.cpp

@@ -264,11 +264,32 @@ UInt_t PSectorChisq::GetNDF(UInt_t idx)
 // Constructor
 //--------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructor for the fitting engine.
  *
- * \param runInfo pointer of the msr-file handler
- * \param runListCollection pointer of the run list collection (pre-processed historgrams)
- * \param chisq_only flag: true=calculate chisq only (no fitting)
+ * Initializes the fitter with MSR configuration and preprocessed data.
+ * Sets up the fitting environment including:
+ * - Parameter lists and command queues
+ * - Fit mode (χ² vs. likelihood)
+ * - Strategy and print level defaults
+ * - Original fit ranges for RANGE commands
+ * - Phase parameter identification
+ *
+ * The constructor validates the COMMANDS block and creates the objective
+ * function (PFitterFcn) but does not start the fit. Call DoFit() to execute.
+ *
+ * @param runInfo Pointer to MSR file handler containing fit configuration
+ * @param runListCollection Pointer to preprocessed data collection
+ * @param chisq_only If true, only evaluate χ² without fitting (useful for validation)
+ * @param yaml_out If true, generate YAML output file with fit results
+ *
+ * @note Sets fIsValid = false if command validation fails. Check IsValid() before DoFit().
+ *
+ * @par Initialization sequence:
+ * 1. Copy parameters and commands from MSR handler
+ * 2. Store original fit ranges (for FIT_RANGE command)
+ * 3. Parse and validate COMMANDS block
+ * 4. Identify phase parameters (for angle wrapping)
+ * 5. Create objective function interface
  */
 PFitter::PFitter(PMsrHandler *runInfo, PRunListCollection *runListCollection, Bool_t chisq_only, Bool_t yaml_out) :
   fChisqOnly(chisq_only), fYamlOut(yaml_out), fRunInfo(runInfo), fRunListCollection(runListCollection)
@@ -356,7 +377,10 @@ PFitter::PFitter(PMsrHandler *runInfo, PRunListCollection *runListCollection, Bo
 // Destructor
 //--------------------------------------------------------------------------
 /**
- * <p>Destructor.
+ * @brief Destructor - Cleans up dynamically allocated resources.
+ *
+ * Frees memory used by command lists, scan data, and timing information.
+ * Smart pointers (fFitterFcn, fFcnMin) are automatically cleaned up.
  */
 PFitter::~PFitter()
 {
@@ -371,8 +395,30 @@ PFitter::~PFitter()
 // GetPhaseParams (private)
 //--------------------------------------------------------------------------
 /**
- * <p>Checks which parameters are phases. This information is needed to
- * restrict the phases to the intervall -360 to +360 degrees.
+ * @brief Identifies which parameters represent phase angles.
+ *
+ * Scans the THEORY block to detect parameters used as phases in standard
+ * muSR functions. Phase parameters are flagged to enable automatic wrapping
+ * to the interval [-360°, +360°] during fitting, preventing meaningless
+ * phase values outside this range.
+ *
+ * Recognized phase-containing functions:
+ * - TFieldCos/tf: phase is 1st parameter
+ * - bessel/b: phase is 1st parameter
+ * - skewedGss/skg: phase is 1st parameter
+ * - staticNKTF/snktf: phase is 1st parameter
+ * - dynamicNKTF/dnktf: phase is 1st parameter
+ * - internFld/if: phase is 2nd parameter
+ * - internBsl/ib: phase is 2nd parameter
+ * - muMinusExpTF/mmsetf: phase is 5th parameter
+ *
+ * Phase references can be:
+ * - Direct parameter numbers (e.g., "7" → par7)
+ * - Function references (e.g., "fun3" → all params in function 3)
+ * - Map references (e.g., "map2" → parameters mapped across runs)
+ *
+ * @note Populates fPhase vector where fPhase[i] = true means parameter i+1 is a phase.
+ * @note User-defined functions cannot be automatically analyzed for phases.
  */
 void PFitter::GetPhaseParams()
 {
@@ -456,11 +502,22 @@ void PFitter::GetPhaseParams()
 // GetParFromFun (private)
 //--------------------------------------------------------------------------
 /**
- * <p>Extract from string funX the function number. Base on the function number
- * the paramter numbers will be collected.
+ * @brief Extracts parameter numbers from a FUNCTIONS block entry.
  *
- * @param funStr string of the form funX, where X is the function number
- * @return a vector of all the parameter numbers related to funX
+ * Parses a function definition to find all parameters it references.
+ * Recursively handles nested map references within the function.
+ *
+ * @param funStr Function identifier (e.g., "fun1", "fun23")
+ * @return Vector of parameter numbers (1-indexed) used in the function
+ *
+ * @par Example:
+ * If FUNCTIONS block contains:
+ * @code
+ * fun1 = par3 * par7 + map2
+ * @endcode
+ * Then GetParFromFun("fun1") returns [3, 7, ...params from map2...]
+ *
+ * @note Returns empty vector if function not found or parsing fails.
  */
 PIntVector PFitter::GetParFromFun(const TString funStr)
 {
@@ -523,11 +580,25 @@ PIntVector PFitter::GetParFromFun(const TString funStr)
 // GetParFromMap (private)
 //--------------------------------------------------------------------------
 /**
- * <p>Extract from string mapX the map number. Based on the map number the
- * parameter numbers will be collected.
+ * @brief Extracts parameter numbers from a map reference.
  *
- * @param mapStr string of the form mapX, where X is the map number
- * @return a vector of all the parameter numbers related to mapX
+ * Parses "mapX" to find which parameters are mapped to the X-th position
+ * across all RUN blocks. Maps allow different runs to use different parameters
+ * for the same theoretical component, enabling multi-run fits with run-dependent
+ * parameters.
+ *
+ * @param mapStr Map identifier (e.g., "map1", "map5")
+ * @return Vector of parameter numbers (1-indexed) mapped at this position
+ *
+ * @par Example:
+ * If RUN blocks have:
+ * @code
+ * RUN 1: map 7 8 9
+ * RUN 2: map 10 11 12
+ * @endcode
+ * Then GetParFromMap("map1") returns [7, 10] (first map entry per run)
+ *
+ * @note Returns empty vector if map index is out of range or invalid.
  */
 PIntVector PFitter::GetParFromMap(const TString mapStr)
 {
@@ -574,9 +645,37 @@ PIntVector PFitter::GetParFromMap(const TString mapStr)
 // DoFit
 //--------------------------------------------------------------------------
 /**
- * <p>Main calling routine to invoke minuit2, i.e. fitting etc.
+ * @brief Main entry point for executing the fit.
  *
- * <b>return:</b> true if all commands could be executed successfully, otherwise returns false.
+ * This is the primary method that orchestrates the entire fitting process:
+ * 1. Transfers parameters from MSR to Minuit2
+ * 2. If chisq_only mode: calculates χ²/maxLH and returns
+ * 3. Otherwise: executes COMMANDS block sequentially
+ * 4. Updates MSR file with fit results and statistics
+ *
+ * @return true if fit completed successfully (or chisq calculated), false on errors
+ *
+ * @par Execution modes:
+ * - **chisq_only = true:** Evaluates objective function once with current parameters,
+ *   reports χ²/maxLH and NDF, useful for validating parameter sets
+ * - **chisq_only = false:** Runs full fit according to COMMANDS block, which typically
+ *   includes MIGRAD (minimization), HESSE (error matrix), optionally MINOS (asymmetric errors)
+ *
+ * @par COMMANDS execution:
+ * Commands are executed in the order they appear in the MSR file. Common sequence:
+ * @code
+ * SET PRINT 1          # Set verbosity
+ * MIGRAD               # Find minimum
+ * HESSE                # Calculate symmetric errors
+ * MINOS                # Calculate asymmetric errors (optional)
+ * SAVE                 # Save results to MSR file
+ * @endcode
+ *
+ * @note Check IsValid() before calling. Check HasConverged() after completion.
+ * @note Updates fRunInfo with final parameters, errors, and fit statistics.
+ * @note Prints detailed χ² breakdown per run if multiple runs are fitted.
+ *
+ * @see ExecuteMigrad(), ExecuteHesse(), ExecuteMinos(), ExecuteSave()
  */
 Bool_t PFitter::DoFit()
 {
@@ -905,10 +1004,31 @@ Bool_t PFitter::DoFit()
 // CheckCommands
 //--------------------------------------------------------------------------
 /**
- * <p>Check the msr-file COMMAND's, fill the command queue and make sure that given parameters (if present)
- * do make any sense.
+ * @brief Validates COMMANDS block and builds execution queue.
  *
- * <b>return:</b> true if the commands are valid, otherwise returns false.
+ * Parses all command lines from the MSR file's COMMANDS block, validates
+ * syntax and parameters, and constructs an ordered execution list. This
+ * ensures commands are executable before starting the fit.
+ *
+ * @return true if all commands are valid and parseable, false on any error
+ *
+ * @par Validation checks:
+ * - Command keywords are recognized (MIGRAD, HESSE, MINOS, etc.)
+ * - Numeric arguments are valid (parameter indices, ranges, point counts)
+ * - Parameter references are within bounds
+ * - SCAN/CONTOURS have required arguments
+ * - FIX/RELEASE specify valid parameter lists
+ *
+ * @par Side effects:
+ * - Populates fCmdList with (command_ID, line_number) pairs
+ * - Sets fIsValid = false if any command is invalid
+ * - Configures scan parameters (fScanParameter, fScanNoPoints, etc.)
+ * - Detects SECTOR command presence (sets fSectorFlag)
+ *
+ * @note Called automatically by constructor. Errors are reported to stderr.
+ * @note Some legacy commands (SET BATCH, END RETURN) are silently ignored.
+ *
+ * @see PMN_* command constants in PFitter.h
  */
 Bool_t PFitter::CheckCommands()
 {