use Claude ai to generate doxygen documentation.

src/include/PFitter.h

@@ -40,56 +40,170 @@
 #include "PRunListCollection.h"
 #include "PFitterFcn.h"
 
+//-------------------------------------------------------------
+/**
+ * <p>Minuit2 command identifiers for COMMANDS block.
+ *
+ * <p>These constants map MSR file COMMANDS block keywords to internal
+ * command identifiers. Commands control the fitting process, including
+ * minimization algorithms, parameter fixing/releasing, error analysis,
+ * and output options.
+ *
+ * <p><b>Categories:</b>
+ * - <b>Minimizers:</b> MIGRAD (gradient descent), SIMPLEX (non-gradient), MINIMIZE (automatic)
+ * - <b>Error analysis:</b> HESSE (covariance matrix), MINOS (asymmetric errors)
+ * - <b>Parameter control:</b> FIX, RELEASE, RESTORE, SAVE
+ * - <b>Exploration:</b> SCAN (1D/2D parameter space), CONTOURS (error ellipses)
+ * - <b>Settings:</b> STRATEGY, MACHINE_PRECISION, PRINT
+ * - <b>Analysis:</b> FIT_RANGE (time-window scan), SECTOR (chisq vs. time)
+ */
+
+/// Interactive mode (not implemented in musrfit)
 #define PMN_INTERACTIVE       0
+/// Contour plot command (2D error ellipses)
 #define PMN_CONTOURS          1
+/// Eigenvalue analysis (not implemented)
 #define PMN_EIGEN             2
+/// Fit range scan to find optimal fitting window
 #define PMN_FIT_RANGE         3
+/// Fix parameters at current values
 #define PMN_FIX               4
+/// Calculate Hessian matrix for error estimation
 #define PMN_HESSE             5
+/// Set machine precision for numerical derivatives
 #define PMN_MACHINE_PRECISION 6
+/// MIGRAD minimizer (gradient-based, recommended)
 #define PMN_MIGRAD            7
+/// MINIMIZE (automatic algorithm selection)
 #define PMN_MINIMIZE          8
+/// MINOS error analysis (asymmetric confidence intervals)
 #define PMN_MINOS             9
+/// Plot command (for scan/contour results)
 #define PMN_PLOT              10
+/// Release previously fixed parameters
 #define PMN_RELEASE           11
+/// Restore parameters from previous SAVE
 #define PMN_RESTORE           12
+/// Save current parameter state
 #define PMN_SAVE              13
+/// Parameter scan (1D or 2D)
 #define PMN_SCAN              14
+/// SIMPLEX minimizer (robust but slow)
 #define PMN_SIMPLEX           15
+/// Set minimization strategy (0=fast, 1=default, 2=careful)
 #define PMN_STRATEGY          16
+/// Set user covariance matrix (not implemented)
 #define PMN_USER_COVARIANCE   17
+/// Set user parameter state (not implemented)
 #define PMN_USER_PARAM_STATE  18
+/// Set print level for fit output (0=quiet, 1=normal, 2=verbose)
 #define PMN_PRINT             19
+/// Calculate χ² vs. time in sectors (time-window analysis)
 #define PMN_SECTOR            20
 
 //-----------------------------------------------------------------------------
 /**
- * <p>The PSectorChisq class is needed to store the chisq/maxLH of a sector.
- * A sector is a time window from fgb to fLast (fLast < lgb). It also stores
- * these information for each run of the msr-file.
+ * <p>Container for sector χ² (or max likelihood) analysis results.
+ *
+ * <p>The SECTOR command analyzes how χ² changes as the fit range is extended
+ * from the first good bin (fgb) to progressively later times. This helps
+ * identify:
+ * - Optimal fitting windows
+ * - Time regions with systematic deviations
+ * - Data quality issues
+ * - Relaxation component contributions
+ *
+ * <p>A "sector" is a time window [fgb, fLast] where fLast < lgb. The class
+ * stores χ²/maxLH and NDF for each sector, both for the total fit and for
+ * individual runs.
+ *
+ * <p><b>Use case:</b> If early-time data shows poor χ², the sector analysis
+ * reveals whether to adjust t0, fgb, or background estimation.
  */
 class PSectorChisq
 {
   public:
+    /**
+     * <p>Constructor.
+     *
+     * @param noOfRuns Number of runs in the fit (allocates storage for per-run statistics)
+     */
     PSectorChisq(UInt_t noOfRuns);
 
+    /// Sets the first good bin time for a specific run
+    /// @param first First good bin time in microseconds
+    /// @param idx Run index
     void SetRunFirstTime(Double_t first, UInt_t idx);
+
+    /// Sets the sector end time (last bin included in this sector)
+    /// @param last Sector end time in microseconds
     void SetSectorTime(Double_t last) { fLast = last; }
+
+    /// Sets the total χ² (or max likelihood) for this sector
+    /// @param chisq Chi-squared or maximum likelihood value
     void SetChisq(Double_t chisq) { fChisq = chisq; }
+
+    /// Sets the χ² for a specific run in this sector
+    /// @param chisq Chi-squared value for run
+    /// @param idx Run index
     void SetChisq(Double_t chisq, UInt_t idx);
+
+    /// Sets the expected total χ² for this sector
+    /// @param expChisq Expected chi-squared value
     void SetExpectedChisq(Double_t expChisq) { fExpectedChisq = expChisq; }
+
+    /// Sets the expected χ² for a specific run
+    /// @param chisq Expected chi-squared value
+    /// @param idx Run index
     void SetExpectedChisq(Double_t chisq, UInt_t idx);
+
+    /// Sets the total number of degrees of freedom for this sector
+    /// @param ndf Degrees of freedom
     void SetNDF(UInt_t ndf) { fNDF = ndf; }
+
+    /// Sets the NDF for a specific run
+    /// @param ndf Degrees of freedom for run
+    /// @param idx Run index
     void SetNDF(UInt_t ndf, UInt_t idx);
 
+    /// Gets the first good bin time for a specific run
+    /// @param idx Run index
+    /// @return First good bin time in microseconds
     Double_t GetTimeRangeFirst(UInt_t idx);
+
+    /// Returns the sector end time
+    /// @return Last bin time in microseconds
     Double_t GetTimeRangeLast() { return fLast; }
+
+    /// Returns the total χ² for this sector
+    /// @return Chi-squared or max likelihood value
     Double_t GetChisq() { return fChisq; }
+
+    /// Returns the χ² for a specific run
+    /// @param idx Run index
+    /// @return Chi-squared value
     Double_t GetChisq(UInt_t idx);
+
+    /// Returns the expected total χ²
+    /// @return Expected chi-squared value
     Double_t GetExpectedChisq() { return fExpectedChisq; }
+
+    /// Returns the expected χ² for a specific run
+    /// @param idx Run index
+    /// @return Expected chi-squared value
     Double_t GetExpectedChisq(UInt_t idx);
+
+    /// Returns the total NDF for this sector
+    /// @return Degrees of freedom
     UInt_t   GetNDF() { return fNDF; }
+
+    /// Returns the NDF for a specific run
+    /// @param idx Run index
+    /// @return Degrees of freedom
     UInt_t   GetNDF(UInt_t idx);
+
+    /// Returns the number of runs
+    /// @return Number of runs in the analysis
     UInt_t   GetNoRuns() { return fNoOfRuns; }
 
   private:
@@ -106,17 +220,74 @@ class PSectorChisq
 
 //-----------------------------------------------------------------------------
 /**
- * <p>Interface class to minuit2.
+ * <p>Main fitting engine interfacing with ROOT Minuit2.
+ *
+ * <p>PFitter orchestrates the entire fitting process for musrfit:
+ * - Initializes Minuit2 with parameters from MSR file
+ * - Executes COMMANDS block directives (MIGRAD, HESSE, MINOS, etc.)
+ * - Manages parameter fixing, releasing, and boundaries
+ * - Performs error analysis (Hessian, MINOS)
+ * - Conducts parameter scans and contour plots
+ * - Calculates sector χ² for time-window analysis
+ * - Generates fit output and statistics
+ *
+ * <p><b>Fitting workflow:</b>
+ * 1. Initialize parameters and set boundaries
+ * 2. Execute COMMANDS block sequentially:
+ *    - MIGRAD: Find minimum using gradient descent
+ *    - HESSE: Calculate symmetric errors from covariance matrix
+ *    - MINOS: Calculate asymmetric errors (optional, slower)
+ *    - SAVE: Save parameter state
+ * 3. Update MSR file with fitted parameters and statistics
+ *
+ * <p><b>Minimization modes:</b>
+ * - <b>χ² minimization:</b> Standard least-squares fitting
+ * - <b>Maximum likelihood:</b> Poisson statistics (better for low counts)
+ *
+ * <p><b>Example COMMANDS block:</b>
+ * @code
+ * COMMANDS
+ * SET PRINT 1
+ * MIGRAD
+ * MINOS
+ * SAVE
+ * @endcode
  */
 class PFitter
 {
   public:
+    /**
+     * <p>Constructor for fitting engine.
+     *
+     * @param runInfo Pointer to MSR handler containing fit configuration
+     * @param runListCollection Pointer to collection of data runs to fit
+     * @param chisq_only If true, only calculate χ² without fitting
+     * @param yaml_out If true, generate YAML output file with fit results
+     */
     PFitter(PMsrHandler *runInfo, PRunListCollection *runListCollection, Bool_t chisq_only = false, Bool_t yaml_out = false);
+
     virtual ~PFitter();
 
+    /// Returns true if fitter initialized successfully
+    /// @return Validity status
     Bool_t IsValid() { return fIsValid; }
+
+    /// Returns true if only parameter scan requested (no minimization)
+    /// @return Scan-only flag
     Bool_t IsScanOnly() { return fIsScanOnly; }
+
+    /// Returns true if fit converged successfully
+    /// @return Convergence status
     Bool_t HasConverged() { return fConverged; }
+
+    /**
+     * <p>Executes the complete fitting procedure.
+     *
+     * <p>Processes all commands from the COMMANDS block sequentially,
+     * performs the fit, calculates errors, and prepares output statistics.
+     *
+     * @return true if fit completed successfully, false on error
+     */
     Bool_t DoFit();
 
   private: