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

improve the doxygen docu of mupp.* Pmupp.* (musredit_qt6).

Browse Source
This commit is contained in:
suter_a
2025-11-25 09:27:59 +01:00
parent c06aa17a07
commit af14905fc2
4 changed files with 629 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
src/musredit_qt6/mupp/Pmupp.cpp
View File

@@ -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 <iostream>
#include <cmath>
@@ -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:
* <runNumber><extension>.msr where <extension> 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<double> PParamDataHandler::GetValues(QString collName, QString paramName)
{
@@ -867,13 +994,21 @@ QVector<double> 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<double> PParamDataHandler::GetPosErr(QString collName, QString paramName)
{
@@ -913,13 +1048,22 @@ QVector<double> 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<double> PParamDataHandler::GetNegErr(QString collName, QString paramName)
{
@@ -959,9 +1103,13 @@ QVector<double> 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)
{

231
src/musredit_qt6/mupp/Pmupp.h
View File

@@ -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 <QStringList>
#include <QProcess>
/**
* @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
//----------------------------------------------------------------------------
/**
* <p>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
};
//----------------------------------------------------------------------------
/**
* <p>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<PmuppParam> fParam; ///< parameters of the run
int fNumber; ///< run number identifier
QString fName; ///< descriptive name or title of the run
QVector<PmuppParam> fParam; ///< vector of all fit parameters for this run
};
//----------------------------------------------------------------------------
/**
* <p>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<PmuppRun> 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<PmuppRun> fRun; ///< vector of all runs in this collection
};
//----------------------------------------------------------------------------
/**
* <p>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<QProcess> fProc; ///< this will be needed if msr2data needs to be called
QVector<PmuppCollection> fCollection; ///< all the collections handeled
std::unique_ptr<QProcess> fProc; ///< process handle for invoking msr2data when msr files need conversion
QVector<PmuppCollection> fCollection; ///< vector containing all loaded collections
bool analyzeFileList(const QStringList &fln, QString &collectionName,
QStringList &arg, QString &workDir, QString &errorMsg);

153
src/musredit_qt6/mupp/mupp.cpp
View File

@@ -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 <iostream>
#include <QObject>
@@ -49,7 +68,14 @@
//------------------------------------------------------------------------
/**
* <p>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()
//------------------------------------------------------------------------
/**
* <p>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()
//------------------------------------------------------------------------
/**
* <p>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)
//------------------------------------------------------------------------
/**
* <p>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)
//------------------------------------------------------------------------
/**
* <p>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)
//------------------------------------------------------------------------
/**
* <p>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)
//------------------------------------------------------------------------
/**
* <p>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 <fit-param-path>] <fit-param-file-names>]
* @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[])
{

32
src/musredit_qt6/mupp/mupp.h
View File

@@ -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 <sys/msg.h>
#include <sys/stat.h>
/**
* @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_