diff --git a/src/musredit_qt6/mupp/Pmupp.cpp b/src/musredit_qt6/mupp/Pmupp.cpp index d889e2c9f..a619b5c60 100644 --- a/src/musredit_qt6/mupp/Pmupp.cpp +++ b/src/musredit_qt6/mupp/Pmupp.cpp @@ -27,6 +27,27 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file Pmupp.cpp + * + * @brief Implementation of core data classes for mupp parameter management. + * + * This file implements the data structures and handler classes for managing + * muSR fit parameters in mupp. It provides the functionality to read, parse, + * and access parameter data from various file formats (db, dat, msr). + * + * Key implementations: + * - PmuppParam: Storage and access for individual parameters + * - PmuppRun: Container for all parameters from a single run + * - PmuppCollection: Container for multiple related runs + * - PParamDataHandler: File I/O and data management operations + * + * The file parsers handle three main formats: + * - DB format: Structured database format with metadata and parameters + * - DAT/TXT format: Column-based format with flexible error handling + * - MSR format: Indirect support via msr2data external tool + */ + #include #include @@ -55,7 +76,9 @@ //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * @brief PmuppParam::PmuppParam. Ctor + * @brief Default constructor for PmuppParam. + * + * Initializes a parameter with undefined values (MUPP_UNDEF) and an empty name. */ PmuppParam::PmuppParam() { ResetParam(); @@ -63,10 +86,14 @@ PmuppParam::PmuppParam() { //-------------------------------------------------------------------------- /** - * @brief PmuppParam::PmuppParam. Ctor - * @param name parameter name - * @param param parameter value - * @param posErr parameter error + * @brief Constructor for PmuppParam with symmetric errors. + * + * Initializes a parameter with a name, value, and symmetric error + * (positive error = negative error). + * + * @param name parameter name (e.g., "alpha", "lambda") + * @param param parameter central value + * @param posErr parameter error (used for both positive and negative) */ PmuppParam::PmuppParam(QString name, double param, double posErr) { @@ -75,11 +102,16 @@ PmuppParam::PmuppParam(QString name, double param, double posErr) //-------------------------------------------------------------------------- /** - * @brief PmuppParam::PmuppParam. Ctor - * @param name parameter name - * @param param parameter value - * @param posErr positive parameter error - * @param negErr negative parameter error + * @brief Constructor for PmuppParam with asymmetric errors. + * + * Initializes a parameter with a name, value, and asymmetric errors. + * This is useful when the uncertainty is not symmetric around the + * central value, which can occur with non-Gaussian likelihoods. + * + * @param name parameter name (e.g., "alpha", "lambda") + * @param param parameter central value + * @param posErr positive (upper) parameter error + * @param negErr negative (lower) parameter error */ PmuppParam::PmuppParam(QString name, double param, double posErr, double negErr) { @@ -88,7 +120,10 @@ PmuppParam::PmuppParam(QString name, double param, double posErr, double negErr) //-------------------------------------------------------------------------- /** - * @brief PmuppParam::ResetParam. Reset the parameter values + * @brief Resets the parameter to undefined state. + * + * Clears the parameter name and sets all numeric values to MUPP_UNDEF, + * effectively marking the parameter as uninitialized. */ void PmuppParam::ResetParam() { @@ -100,9 +135,13 @@ void PmuppParam::ResetParam() //-------------------------------------------------------------------------- /** - * @brief PmuppParam::SetParam. Set a parameter + * @brief Sets parameter with symmetric errors. + * + * Sets the parameter name, value, and error. The negative error is not + * explicitly set and should be set separately if asymmetric errors are needed. + * * @param name parameter name - * @param param parameter value + * @param param parameter central value * @param posErr parameter error */ void PmuppParam::SetParam(QString name, double param, double posErr) @@ -114,11 +153,15 @@ void PmuppParam::SetParam(QString name, double param, double posErr) //-------------------------------------------------------------------------- /** - * @brief PmuppParam::SetParam. Set a parameter + * @brief Sets parameter with asymmetric errors. + * + * Sets the parameter name, value, positive error, and negative error. + * Use this when the uncertainty is asymmetric around the central value. + * * @param name parameter name - * @param param parameter value - * @param posErr positive parameter value - * @param negErr negative parameter value + * @param param parameter central value + * @param posErr positive (upper) error value + * @param negErr negative (lower) error value */ void PmuppParam::SetParam(QString name, double param, double posErr, double negErr) { @@ -130,9 +173,13 @@ void PmuppParam::SetParam(QString name, double param, double posErr, double negE //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * @brief PmuppRun::GetParam. Get a parameter from a run - * @param idx index of the parameter - * @return the parameter value + * @brief Retrieves a parameter from a run by index. + * + * Returns a copy of the parameter at the specified index. If the index + * is out of range, returns an empty (default-constructed) parameter. + * + * @param idx zero-based index of the parameter to retrieve + * @return the parameter at the specified index, or an empty parameter if out of range */ PmuppParam PmuppRun::GetParam(unsigned int idx) { @@ -146,9 +193,13 @@ PmuppParam PmuppRun::GetParam(unsigned int idx) //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * @brief PmuppCollection::GetRun. Returns a run from a collection. - * @param idx of the run in a collection - * @return a run from a collection + * @brief Retrieves a run from a collection by index. + * + * Returns a copy of the run at the specified index. If the index + * is out of range, returns an empty (default-constructed) run. + * + * @param idx zero-based index of the run to retrieve + * @return the run at the specified index, or an empty run if out of range */ PmuppRun PmuppCollection::GetRun(unsigned int idx) { @@ -162,9 +213,12 @@ PmuppRun PmuppCollection::GetRun(unsigned int idx) //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * @brief PParamDataHandler::NewCollection. Adds an empty new collection with - * name 'name'. - * @param name of the new collection + * @brief Creates and adds an empty collection with the specified name. + * + * This method creates a new empty collection and adds it to the handler's + * collection vector. The collection can then be populated with runs later. + * + * @param name the name to assign to the new collection */ void PParamDataHandler::NewCollection(const QString name) { @@ -176,17 +230,24 @@ void PParamDataHandler::NewCollection(const QString name) //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::analyzeFileList. In case the input is given by - * msr-files, the structure of the file names needs to be analyzed that - * msr2data can be called. + * @brief Analyzes a list of msr-files to prepare arguments for msr2data. * - * @param fln list of msr-files to be analyzed. - * @param collectionName output collection name (db-/dat-file). - * @param arg argument list which is needed to feed msr2data - * @param workDir working directory - * @param errorMsg error message in case something went wrong. + * When parameter data is provided as msr-files (muSR fit input files), + * this function analyzes their structure to extract run numbers and + * extensions, preparing the argument list needed to invoke the msr2data + * external tool for conversion to db format. * - * @return true if successful, false otherwise + * The function expects msr-files with names following the pattern: + * .msr where starts with '_'. + * All msr-files in the list must have the same extension. + * + * @param fln list of msr-file paths to be analyzed + * @param collectionName output parameter: name for the resulting db/dat collection file + * @param arg output parameter: argument list to be passed to msr2data + * @param workDir output parameter: working directory where files are located + * @param errorMsg output parameter: error message if analysis fails + * + * @return true if analysis is successful, false otherwise */ bool PParamDataHandler::analyzeFileList(const QStringList &fln, QString &collectionName, QStringList &arg, QString &workDir, QString &errorMsg) @@ -260,11 +321,27 @@ bool PParamDataHandler::analyzeFileList(const QStringList &fln, QString &collect //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::ReadParamFile. Reads a msr-file. - * @param fln file name of the msr-file to be read - * @param errorMsg error message in case reading fails. + * @brief Reads parameter file(s) and loads them into collections. * - * @return true on success, otherwise false. + * This is the main entry point for loading parameter data. It handles + * multiple file formats (msr, db, dat) and dispatches to the appropriate + * reader function. For msr-files, it invokes msr2data to convert them to + * db format first. + * + * File format handling: + * - .msr files: Converted via msr2data, then loaded as db + * - .db files: Loaded directly via ReadDbFile() + * - .dat/.txt files: Loaded directly via ReadColumnParamFile() + * + * Multiple files can be loaded in a single call. Each file becomes a + * separate collection in the handler. + * + * @param fln list of file names (with paths) to be loaded + * @param errorMsg output parameter: error message if reading fails + * + * @return true on success, false on any error + * + * @see ReadDbFile(), ReadColumnParamFile(), analyzeFileList() */ bool PParamDataHandler::ReadParamFile(const QStringList fln, QString &errorMsg) { @@ -397,12 +474,27 @@ bool PParamDataHandler::ReadParamFile(const QStringList fln, QString &errorMsg) //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::ReadDbFile. Reads a db-file. - * @param fln file name of the db-file - * @param valid true on success, otherwise false - * @param errorMsg error messages in case read fails + * @brief Reads and parses a db-format parameter file. * - * @return the collection object containing the db-file on success. + * The db format is a structured text format containing parameter data with + * metadata sections. The file structure includes: + * - Title and abstract sections (ignored by this parser) + * - Data-tags section (ignored) + * - Parameter entries section (following "\\-e" marker) + * - Each parameter: name=value, posError, negError, unused + * - Run entries: runNumber, title + * + * The function validates that all runs have the same number of parameters + * to ensure data consistency. + * + * @param fln path to the db-file to be read + * @param valid output parameter: set to true on success, false on failure + * @param errorMsg output parameter: error message describing any failures + * + * @return a PmuppCollection object containing all runs and parameters from the file. + * Returns an empty collection if reading fails (valid will be false). + * + * @see ReadParamFile(), ReadColumnParamFile() */ PmuppCollection PParamDataHandler::ReadDbFile(const QString fln, bool &valid, QString &errorMsg) { @@ -554,12 +646,31 @@ PmuppCollection PParamDataHandler::ReadDbFile(const QString fln, bool &valid, QS //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::ReadColumnParamFile. Reads a dat-file - * @param fln file name of the dat-file to be read - * @param valid true on success, false otherwise. - * @param errorMsg error message in case read fails. + * @brief Reads and parses a column-based parameter file (dat/txt format). * - * @return the collection object containing the dat-file on success. + * The column format is a simple text format where: + * - First line: Header with column names + * - Following lines: Data values (one row per run) + * - Columns are whitespace-separated + * + * Column naming conventions: + * - Parameter names without suffix: parameter values + * - Names ending with "Err": symmetric errors + * - Names ending with "PosErr": positive (upper) errors + * - Names ending with "NegErr": negative (lower) errors + * - Column named "RUN": run number identifier + * + * Error handling supports both symmetric (single error column) and + * asymmetric (separate PosErr/NegErr columns) error specifications. + * + * @param fln path to the dat/txt-file to be read + * @param valid output parameter: set to true on success, false on failure + * @param errorMsg output parameter: error message describing any failures + * + * @return a PmuppCollection object containing all runs and parameters from the file. + * Returns an empty collection if reading fails (valid will be false). + * + * @see ReadParamFile(), ReadDbFile() */ PmuppCollection PParamDataHandler::ReadColumnParamFile(const QString fln, bool &valid, QString &errorMsg) { @@ -691,12 +802,18 @@ PmuppCollection PParamDataHandler::ReadColumnParamFile(const QString fln, bool & //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::GetCollection. Get a single collection from all - * the loaded collections - * @param idx of the collection - * @param valid true if collection is found + * @brief Retrieves a collection by index (by value). * - * @return requested collection on success. + * Returns a copy of the collection at the specified index position. + * If the index is out of range, returns an empty collection and sets + * valid to false. + * + * @param idx zero-based index of the collection to retrieve + * @param valid output parameter: set to true if collection found, false otherwise + * + * @return copy of the requested collection, or an empty collection if not found + * + * @see GetCollection(const QString, bool&), GetCollection(const int) */ PmuppCollection PParamDataHandler::GetCollection(const int idx, bool &valid) { @@ -821,13 +938,23 @@ QString PParamDataHandler::GetCollectionName(const int idx) //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::GetValues. Get the data values of a parameter of - * a requested collection. - * @param collName name of the collection - * @param paramName parameter name + * @brief Retrieves all values for a specific parameter across all runs. * - * @return data values of the requested parameter name of the collection collName. - * Empty data vector otherwise. + * This method extracts the central values of a named parameter from all + * runs in the specified collection. The returned vector has one entry per + * run, in the order they appear in the collection. + * + * This is useful for plotting parameter evolution (e.g., relaxation rate + * vs. temperature) where each run represents a different experimental + * condition. + * + * @param collName name of the collection to query + * @param paramName name of the parameter to extract (e.g., "alpha", "lambda") + * + * @return vector of parameter values, one per run in the collection. + * Returns an empty vector if the collection or parameter is not found. + * + * @see GetPosErr(), GetNegErr() */ QVector PParamDataHandler::GetValues(QString collName, QString paramName) { @@ -867,13 +994,21 @@ QVector PParamDataHandler::GetValues(QString collName, QString paramName //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::GetPosErr. Get the positive data error values of - * a parameter of a requested collection. - * @param collName name of the requested collection - * @param paramName parameter name + * @brief Retrieves all positive errors for a specific parameter across all runs. * - * @return positive error values of the requested parameter name of the - * collection collName. Empty positive error vector otherwise. + * This method extracts the positive (upper) error values of a named parameter + * from all runs in the specified collection. The returned vector has one entry + * per run, in the order they appear in the collection. + * + * Used in conjunction with GetValues() for plotting parameters with error bars. + * + * @param collName name of the collection to query + * @param paramName name of the parameter whose positive errors to extract + * + * @return vector of positive error values, one per run in the collection. + * Returns an empty vector if the collection or parameter is not found. + * + * @see GetValues(), GetNegErr() */ QVector PParamDataHandler::GetPosErr(QString collName, QString paramName) { @@ -913,13 +1048,22 @@ QVector PParamDataHandler::GetPosErr(QString collName, QString paramName //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::GetNegErr. Get the negative data error values of - * a parameter of a requested collection. - * @param collName name of the requested collection - * @param paramName parameter name + * @brief Retrieves all negative errors for a specific parameter across all runs. * - * @return negative error values of the requested parameter name of the - * collection collName. Empty negative error vector otherwise. + * This method extracts the negative (lower) error values of a named parameter + * from all runs in the specified collection. The returned vector has one entry + * per run, in the order they appear in the collection. + * + * Used in conjunction with GetValues() and GetPosErr() for plotting parameters + * with asymmetric error bars. + * + * @param collName name of the collection to query + * @param paramName name of the parameter whose negative errors to extract + * + * @return vector of negative error values, one per run in the collection. + * Returns an empty vector if the collection or parameter is not found. + * + * @see GetValues(), GetPosErr() */ QVector PParamDataHandler::GetNegErr(QString collName, QString paramName) { @@ -959,9 +1103,13 @@ QVector PParamDataHandler::GetNegErr(QString collName, QString paramName //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::RemoveCollection. Remove a collection from the - * data handler. - * @param name of the collection to be removed. + * @brief Removes a collection from the handler by name. + * + * Searches for a collection with the specified name and removes it from + * the internal collection vector. If multiple collections have the same + * name, only the first match is removed. + * + * @param name the name of the collection to be removed */ void PParamDataHandler::RemoveCollection(QString name) { @@ -975,10 +1123,13 @@ void PParamDataHandler::RemoveCollection(QString name) //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::ReplaceCollection. Replaces a collection at index - * position idx. - * @param coll collection - * @param idx index of the collection to be replaced + * @brief Replaces a collection at the specified index. + * + * Replaces an existing collection with a new one at the given index position. + * If the index is out of range, no action is taken. + * + * @param coll the new collection to insert + * @param idx the index position where the collection should be replaced */ void PParamDataHandler::ReplaceCollection(PmuppCollection coll, int idx) { @@ -990,7 +1141,17 @@ void PParamDataHandler::ReplaceCollection(PmuppCollection coll, int idx) //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::Dump. Dumps the collection onto stdout + * @brief Dumps all collection data to stdout for debugging. + * + * Prints a formatted representation of all loaded collections, including + * collection names, run numbers, run names, and all parameters with their + * values and errors. This is primarily used for debugging and verification + * purposes. + * + * Output format shows: + * - Collection separator and name + * - For each run: run number, run name + * - For each parameter: name, value, negative error, positive error */ void PParamDataHandler::Dump() { @@ -1017,7 +1178,11 @@ void PParamDataHandler::Dump() //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::readFromStdOut + * @brief Slot to handle standard output from msr2data process. + * + * This slot is connected to the readyReadStandardOutput signal of the + * QProcess used to run msr2data. It reads and logs all output from the + * process's stdout. */ void PParamDataHandler::readFromStdOut() { @@ -1026,7 +1191,11 @@ void PParamDataHandler::readFromStdOut() //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::readFromStdErr + * @brief Slot to handle standard error from msr2data process. + * + * This slot is connected to the readyReadStandardError signal of the + * QProcess used to run msr2data. It reads and logs all output from the + * process's stderr. */ void PParamDataHandler::readFromStdErr() { @@ -1035,9 +1204,14 @@ void PParamDataHandler::readFromStdErr() //-------------------------------------------------------------------------- /** - * @brief PParamDataHandler::processDone - * @param exitCode - * @param exitStatus + * @brief Slot to handle completion of msr2data process. + * + * This slot is connected to the finished signal of the QProcess used to + * run msr2data. It checks the exit status and logs errors if the process + * crashed or exited with a non-zero exit code. + * + * @param exitCode the exit code returned by the process + * @param exitStatus indicates whether the process exited normally or crashed */ void PParamDataHandler::processDone(int exitCode, QProcess::ExitStatus exitStatus) { diff --git a/src/musredit_qt6/mupp/Pmupp.h b/src/musredit_qt6/mupp/Pmupp.h index ff26f1af0..8f997ec4b 100644 --- a/src/musredit_qt6/mupp/Pmupp.h +++ b/src/musredit_qt6/mupp/Pmupp.h @@ -27,6 +27,23 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file Pmupp.h + * + * @brief Core data structures and handler classes for mupp parameter management. + * + * This header file defines the fundamental data structures used in mupp for + * managing muSR fit parameters. It implements a hierarchical data model: + * - PmuppParam: Individual parameter with value and errors + * - PmuppRun: Collection of parameters from a single run + * - PmuppCollection: Set of runs forming a complete dataset + * - PParamDataHandler: Manager class for loading and accessing collections + * + * The classes support reading parameter data from multiple file formats + * (db, dat, msr) and provide interfaces for accessing parameter values, + * errors, and metadata. + */ + #ifndef _PMUPP_H_ #define _PMUPP_H_ @@ -38,12 +55,27 @@ #include #include +/** + * @brief Undefined value constant used to indicate missing or invalid data. + * + * This constant is used throughout mupp to mark parameters or values that + * have not been set or are invalid. It is set to a very large number that + * is unlikely to occur in real experimental data. + */ #define MUPP_UNDEF 1.0e99 //---------------------------------------------------------------------------- /** - *

The PmuppParam class. It handles a single parameter: name, value, - * positive- and negative error. + * @brief Represents a single fit parameter with its value and uncertainties. + * + * The PmuppParam class encapsulates a single parameter from a muSR fit, + * including its name, central value, and asymmetric error bars (positive + * and negative errors). This class is the fundamental building block for + * storing parameter information in mupp. + * + * The class supports both symmetric errors (where positive and negative + * errors are equal) and asymmetric errors (where they differ), which is + * common in fits with non-Gaussian likelihood profiles. */ class PmuppParam { public: @@ -54,84 +86,238 @@ class PmuppParam { void ResetParam(); void SetParam(QString name, double param, double posErr); void SetParam(QString name, double param, double posErr, double negErr); + + /** + * @brief Sets the parameter name. + * @param name the parameter name to be set + */ void SetName(QString name) { fName = name; } + + /** + * @brief Sets the parameter value. + * @param dval the parameter value to be set + */ void SetValue(double dval) { fValue = dval; } + + /** + * @brief Sets the positive error of the parameter. + * @param dval the positive error value to be set + */ void SetPosErr(double dval) { fPosErr = dval; } + + /** + * @brief Sets the negative error of the parameter. + * @param dval the negative error value to be set + */ void SetNegErr(double dval) { fNegErr = dval; } + /** + * @brief Gets the parameter name. + * @return the parameter name + */ QString GetName() { return fName; } + + /** + * @brief Gets the parameter value. + * @return the parameter value + */ double GetValue() { return fValue; } + + /** + * @brief Gets the positive error of the parameter. + * @return the positive error value + */ double GetPosErr() { return fPosErr; } + + /** + * @brief Gets the negative error of the parameter. + * @return the negative error value + */ double GetNegErr() { return fNegErr; } private: - QString fName; ///< parameter name - double fValue; ///< parameter value - double fPosErr; ///< positive error of the parameter - double fNegErr; ///< negative error of the parameter + QString fName; ///< parameter name (e.g., "alpha", "lambda", "phase") + double fValue; ///< central value of the parameter + double fPosErr; ///< positive (upper) error of the parameter + double fNegErr; ///< negative (lower) error of the parameter }; //---------------------------------------------------------------------------- /** - *

The PmuppRun class. Contains all the parameters of a single run. + * @brief Represents all fit parameters from a single experimental run. + * + * The PmuppRun class contains a complete set of parameters from one muSR + * run, including the run number, run name/title, and a vector of all fit + * parameters (PmuppParam objects) associated with that run. + * + * This class forms the intermediate level in the data hierarchy: + * Parameter -> Run -> Collection */ class PmuppRun { public: + /** + * @brief Default constructor. Initializes an empty run with invalid number. + */ PmuppRun() { fNumber = -1; fName=""; fParam.clear(); } + + /** + * @brief Destructor. Cleans up the run data. + */ ~PmuppRun() { fNumber = -1; fName=""; fParam.clear(); } + /** + * @brief Clears all run data and resets to initial state. + */ void Clear() { fNumber = -1; fName=""; fParam.clear(); } + + /** + * @brief Sets the run name/title. + * @param name the run name or title string to be set + */ void SetName(QString name) { fName = name; } + + /** + * @brief Sets the run number. + * @param ival the run number to be set + */ void SetNumber(int ival) { fNumber = ival; } + + /** + * @brief Adds a parameter to this run. + * @param param the PmuppParam object to be added to the parameter list + */ void AddParam(PmuppParam param) { fParam.push_back(param); } + /** + * @brief Gets the run number. + * @return the run number (may be -1 if not set) + */ int GetNumber() { return fNumber; } + + /** + * @brief Gets the run name/title. + * @return the run name or title string + */ QString GetName() { return fName; } + + /** + * @brief Gets the number of parameters in this run. + * @return the count of parameters stored in this run + */ int GetNoOfParam() { return fParam.size(); } + PmuppParam GetParam(unsigned int idx); private: - int fNumber; ///< run number - QString fName; ///< name of the run - QVector fParam; ///< parameters of the run + int fNumber; ///< run number identifier + QString fName; ///< descriptive name or title of the run + QVector fParam; ///< vector of all fit parameters for this run }; //---------------------------------------------------------------------------- /** - *

The PmuppCollection class. Is collecting a number of runs. Typically - * something like a full temperature scan, an energy scan, etc. + * @brief Represents a collection of related experimental runs. + * + * The PmuppCollection class groups together multiple runs that form a + * coherent dataset, typically representing a scan over some experimental + * parameter such as temperature, magnetic field, energy, pressure, etc. + * + * A collection corresponds to a single data file (db, dat, or msr format) + * and contains all runs from that file. This is the top level in the + * data hierarchy: Parameter -> Run -> Collection + * + * Example use cases: + * - Temperature scan: multiple runs at different temperatures + * - Field scan: runs at various magnetic field values + * - Energy scan: runs at different implantation energies */ class PmuppCollection { public: + /** + * @brief Default constructor. Initializes an empty collection. + */ PmuppCollection() { fPathName=""; fName = ""; fRun.clear(); } + /** + * @brief Sets the full path name of the collection file. + * @param pathName the absolute or relative path to the collection file + */ void SetPathName(QString pathName) { fPathName = pathName; } + + /** + * @brief Sets the collection name. + * @param name the display name for this collection + */ void SetName (QString name) { fName = name; } + + /** + * @brief Adds a run to this collection. + * @param run the PmuppRun object to be added to the run list + */ void AddRun(PmuppRun run) { fRun.push_back(run); } + /** + * @brief Gets the full path name of the collection file. + * @return the path name string + */ QString GetPathName() { return fPathName; } + + /** + * @brief Gets the collection name. + * @return the collection name string + */ QString GetName() { return fName; } + + /** + * @brief Gets the number of runs in this collection. + * @return the count of runs stored in this collection + */ int GetNoOfRuns() { return fRun.size(); } + PmuppRun GetRun(unsigned int idx); private: - QString fPathName; ///< path-name of the collection - QString fName; ///< name of the collection - QVector fRun; ///< all the runs in the collection + QString fPathName; ///< full path and filename of the collection data file + QString fName; ///< display name of the collection (usually just the filename) + QVector fRun; ///< vector of all runs in this collection }; //---------------------------------------------------------------------------- /** - *

The PParamDataHandler class. This class handles all the collections - * loaded. + * @brief Central manager class for loading and accessing parameter collections. + * + * The PParamDataHandler class is responsible for managing all loaded parameter + * collections in mupp. It provides functionality for: + * - Reading and parsing parameter files (db, dat, msr formats) + * - Managing multiple collections simultaneously + * - Providing access to parameter data by collection and parameter name + * - Handling conversion of msr files via msr2data external process + * + * This class acts as the primary interface between the data storage and the + * GUI or scripting components of mupp. It maintains a vector of all loaded + * collections and provides various query methods to extract parameter values + * and errors. + * + * File format support: + * - .db files: muSR database format with structured parameter entries + * - .dat/.txt files: Column-based parameter files + * - .msr files: muSR fit input files (converted via msr2data) */ class PParamDataHandler : public QObject { Q_OBJECT public: + /** + * @brief Default constructor. + */ PParamDataHandler() {} + /** + * @brief Gets the total number of loaded collections. + * @return the count of collections currently managed + */ int GetNoOfCollections() { return fCollection.size(); } + void NewCollection(const QString name); bool ReadParamFile(const QStringList fln, QString &errorMsg); @@ -155,11 +341,18 @@ class PParamDataHandler : public QObject { void Dump(); signals: + /** + * @brief Signal emitted when new data has been successfully loaded. + * + * This signal is emitted after parameter files have been read and + * collections have been added to the handler. Connected slots can + * update their displays or perform other actions in response. + */ void newData(); private: - std::unique_ptr fProc; ///< this will be needed if msr2data needs to be called - QVector fCollection; ///< all the collections handeled + std::unique_ptr fProc; ///< process handle for invoking msr2data when msr files need conversion + QVector fCollection; ///< vector containing all loaded collections bool analyzeFileList(const QStringList &fln, QString &collectionName, QStringList &arg, QString &workDir, QString &errorMsg); diff --git a/src/musredit_qt6/mupp/mupp.cpp b/src/musredit_qt6/mupp/mupp.cpp index af5e7dff4..0ef84068c 100644 --- a/src/musredit_qt6/mupp/mupp.cpp +++ b/src/musredit_qt6/mupp/mupp.cpp @@ -27,6 +27,25 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file mupp.cpp + * + * @brief Implementation of mupp (muon parameter plotter) main application. + * + * mupp is a tool for plotting muon spin spectroscopy (muSR) fit parameters + * as a function of various experimental conditions (temperature, field, etc.). + * The application supports both GUI and script-based modes. It can handle + * parameter files in db, dat, and msr formats, allowing users to visualize + * trends in fit parameters across multiple runs. + * + * The main functionality includes: + * - Loading and parsing parameter files (db, dat, msr) + * - Interactive GUI for data selection and visualization + * - Script-based batch processing for automated plotting + * - Export of plots in various formats (pdf, png, svg, etc.) + * - Generation of ROOT macros for further analysis + */ + #include #include @@ -49,7 +68,14 @@ //------------------------------------------------------------------------ /** - *

mupp script help. + * @brief Displays the mupp script syntax help to stdout. + * + * This function prints detailed information about the mupp script commands, + * including available commands, their syntax, and descriptions. The script + * commands allow for batch processing and automated plotting of parameter + * data without user interaction. + * + * @see mupp_syntax(), mupp_script_read(), mupp_script_syntax_check() */ void mupp_script_syntax() { @@ -89,7 +115,18 @@ void mupp_script_syntax() //------------------------------------------------------------------------ /** - *

mupp syntax help. + * @brief Displays the mupp application syntax and usage help to stdout. + * + * This function prints the complete usage information for the mupp application, + * including command-line options, file path specifications, and supported file + * formats. It also calls mupp_script_syntax() to display script-specific help. + * + * Command-line options include: + * - Help and version information + * - Script mode execution + * - File path and file name specifications + * + * @see mupp_script_syntax() */ void mupp_syntax() { @@ -108,12 +145,21 @@ void mupp_syntax() //------------------------------------------------------------------------ /** - *

Reads a mupp script and feeds its content to list. + * @brief Reads a mupp script file and parses its content into a string list. * - * @param fln mupp script file name - * @param list content of the mupp script + * This function reads a mupp script file line by line, processes each line by: + * - Removing leading and trailing whitespace + * - Skipping empty lines + * - Skipping comment lines (starting with '#', '%', or '//') + * - Removing trailing comments from command lines + * - Adding valid command lines to the output list * - * @return 0 if success, otherwise -1 + * @param fln the mupp script file name (path) to be read + * @param list reference to QStringList that will contain the parsed script commands + * + * @return 0 on success, -1 if the file cannot be opened + * + * @see mupp_script_syntax_check(), mupp_script_syntax() */ int mupp_script_read(const char *fln, QStringList &list) { @@ -156,11 +202,17 @@ int mupp_script_read(const char *fln, QStringList &list) //------------------------------------------------------------------------ /** - *

check if a bash environment variable exists. + * @brief Checks if a bash environment variable exists and is non-empty. * - * @param str name of bash variable to be checked. + * This function verifies the existence of a bash environment variable by + * querying the system environment. The variable name can be specified with + * or without the leading '$' symbol, as it will be removed internally. * - * @return true if the bash variable exists, false otherwise. + * @param str name of the bash variable to be checked (with or without '$' prefix) + * + * @return true if the bash variable exists and has a non-empty value, false otherwise + * + * @see mupp_script_syntax_check() */ bool mupp_bash_variable_exists(const QString str) { @@ -177,11 +229,30 @@ bool mupp_bash_variable_exists(const QString str) //------------------------------------------------------------------------ /** - *

checks the mupp script syntax. + * @brief Validates the syntax of mupp script commands. * - * @param list mupp script content. + * This function performs comprehensive validation of mupp script commands, + * including: + * - Verification of command syntax and required parameters + * - Validation of file paths and bash environment variables + * - Checking file extensions for plot and macro outputs + * - Ensuring variable definitions are properly linked to collections + * - Verifying collection indices are within valid ranges * - * @return 0 on success, negative numbers otherwise. + * The function tracks defined variables and ensures they are properly linked + * to collections before use. It also validates that all collections referenced + * in the script have been loaded. + * + * @param list reference to QStringList containing the parsed mupp script commands + * + * @return 0 on success, negative values indicating different types of errors: + * -1: general syntax error + * -2: invalid file extension or empty bash variable + * -3: unrecognized command or collection out of range + * -4: no data loaded or internal consistency error + * -5: variable not defined before linking + * + * @see mupp_script_read(), mupp_bash_variable_exists() */ int mupp_script_syntax_check(QStringList &list) { @@ -439,14 +510,22 @@ int mupp_script_syntax_check(QStringList &list) //------------------------------------------------------------------------ /** - *

Depending on whether a script or gui application is wished, select - * the proper Qt application class. + * @brief Factory function to create the appropriate Qt application object. * - * @param argc - * @param argv - * @param gui if true, the gui is wanted, otherwise the script is called. + * This function selects and creates the proper Qt application class based on + * whether GUI or console mode is required. It creates a QApplication instance + * for GUI mode (which supports widgets and graphics) or a QCoreApplication + * instance for script/console mode (which is lighter and has no GUI support). * - * @return the request qt application + * @param argc reference to the argument count from main() + * @param argv argument vector from main() containing command-line arguments + * @param gui if true, a GUI application (QApplication) is created; + * if false, a console application (QCoreApplication) is created + * + * @return pointer to the created Qt application object (either QApplication + * or QCoreApplication depending on the gui parameter) + * + * @see main() */ QCoreApplication* createApplication(int &argc, char *argv[], bool gui) { @@ -458,15 +537,39 @@ QCoreApplication* createApplication(int &argc, char *argv[], bool gui) //------------------------------------------------------------------------ /** - *

Main mupp application. mupp stands for muon parameter plotter. It allows - * to plot the parameters of db- or dat-files. The typical use case is e.g. - * plotting parameters of muSR fits as function of temperature, pressure, - * energy, etc. + * @brief Main entry point of the mupp application. * - * @param argc - * @param argv + * mupp (muon parameter plotter) is an application designed to visualize + * muSR fit parameters from db-files, dat-files, or msr-files. The typical + * use case is plotting fit parameters as a function of experimental conditions + * such as temperature, pressure, magnetic field, energy, etc. * - * @return return value of the Qt application + * The application supports two operational modes: + * - **GUI mode**: Interactive graphical interface for data exploration, + * parameter selection, and plot generation + * - **Script mode**: Batch processing using script files for automated + * plotting and analysis + * + * Command-line usage: + * @code + * mupp [OPTIONS] [[--path ] ] + * @endcode + * + * Processing flow: + * 1. Parse command-line arguments + * 2. Handle help (-h, --help) and version (-v, --version) requests + * 3. Process script mode (-s, --script) or file list mode + * 4. Create appropriate Qt application (GUI or console) + * 5. Initialize either PmuppGui or PmuppScript + * 6. Enter Qt event loop + * + * @param argc argument count from the command line + * @param argv argument vector containing command-line arguments + * + * @return 0 on successful execution, negative values on error: + * -1: file or script errors, invalid arguments + * + * @see PmuppGui, PmuppScript, createApplication() */ int main(int argc, char *argv[]) { diff --git a/src/musredit_qt6/mupp/mupp.h b/src/musredit_qt6/mupp/mupp.h index c8a7d6fba..32bc1609e 100644 --- a/src/musredit_qt6/mupp/mupp.h +++ b/src/musredit_qt6/mupp/mupp.h @@ -27,6 +27,15 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file mupp.h + * + * @brief Header file for mupp (muon parameter plotter) main application. + * + * This header defines constants and data structures used throughout the mupp + * application for inter-process communication and application configuration. + */ + #ifndef _MUPP_H_ #define _MUPP_H_ @@ -35,13 +44,32 @@ #include #include +/** + * @brief Maximum number of recent files to be tracked. + * + * This constant defines the number of recently opened files that should be + * stored and displayed in the application's file menu. + */ #define MAX_RECENT_FILES 5 +/** + * @brief Maximum size of the message text buffer. + * + * This constant defines the maximum number of characters that can be stored + * in the message buffer for inter-process communication. + */ #define PMUPP_MAX_MTEXT 512 +/** + * @brief Message buffer structure for inter-process communication. + * + * This structure is used for sending messages between processes using the + * System V message queue API. It follows the standard System V message + * buffer format with a type field and a character array for the message body. + */ struct mbuf { - long mtype; // message type - char mtext[PMUPP_MAX_MTEXT]; // message body + long mtype; ///< message type identifier for message routing + char mtext[PMUPP_MAX_MTEXT]; ///< message body containing the actual message data }; #endif // _MUPP_H_