diff --git a/src/musredit_qt6/musrWiz/PAdmin.cpp b/src/musredit_qt6/musrWiz/PAdmin.cpp index 55c630a46..e218b960b 100644 --- a/src/musredit_qt6/musrWiz/PAdmin.cpp +++ b/src/musredit_qt6/musrWiz/PAdmin.cpp @@ -925,8 +925,11 @@ PAdmin::PAdmin() : QObject() //-------------------------------------------------------------------------- /** - * @brief PAdmin::getInstituteList - * @return + * @brief PAdmin::getInstituteList returns a list of all available institute names. + * + * Iterates through all loaded institutes and collects their names into a QStringList. + * + * @return QStringList containing all institute names (e.g., "PSI", "TRIUMF", "ISIS", "J-PARC"). */ QStringList PAdmin::getInstituteList() { @@ -940,6 +943,15 @@ QStringList PAdmin::getInstituteList() } //-------------------------------------------------------------------------- +/** + * @brief PAdmin::getInstrumentList returns a list of instruments for a given institute. + * + * Searches for the specified institute and returns the names of all instruments + * associated with it. + * + * @param institute Institute name to query (e.g., "PSI"). + * @return QStringList containing instrument names, or empty list if institute not found. + */ QStringList PAdmin::getInstrumentList(QString institute) { QStringList list; @@ -968,10 +980,15 @@ QStringList PAdmin::getInstrumentList(QString institute) //-------------------------------------------------------------------------- /** - * @brief PAdmin::addInstrument - * @param institute - * @param instrument - * @return + * @brief PAdmin::addInstrument adds an instrument to an institute. + * + * Searches for the specified institute. If found, adds the instrument to it. + * If the institute doesn't exist, creates a new institute entry and adds + * the instrument to it. + * + * @param institute Institute name (e.g., "PSI"). + * @param instrument Instrument object to add. + * @return 0 on success. */ int PAdmin::addInstrument(QString institute, PInstrument instrument) { @@ -998,7 +1015,10 @@ int PAdmin::addInstrument(QString institute, PInstrument instrument) //-------------------------------------------------------------------------- /** + * @brief PAdmin::getTheoTemplate returns a theory template by index. * + * @param idx Index of the requested theory template. + * @return PTheoTemplate at the given index, or an empty/default template if index is out of range. */ PTheoTemplate PAdmin::getTheoTemplate(int idx) { @@ -1012,7 +1032,13 @@ PTheoTemplate PAdmin::getTheoTemplate(int idx) //-------------------------------------------------------------------------- /** + * @brief PAdmin::getMusrfitFunc returns a musrfit function by name or abbreviation. * + * Searches the list of loaded musrfit functions for one matching the given name + * (either full name or abbreviation). + * + * @param name Function name (e.g., "simpleGss") or abbreviation (e.g., "sg"). + * @return PMusrfitFunc matching the name, or a default/empty function if not found. */ PMusrfitFunc PAdmin::getMusrfitFunc(QString name) { @@ -1178,7 +1204,13 @@ void PAdmin::dump(int tag) //-------------------------------------------------------------------------- /** + * @brief PAdmin::getInstrument returns a pointer to an instrument object. * + * Searches for the specified institute and instrument combination. + * + * @param institute Institute name (e.g., "PSI"). + * @param instrument Instrument name (e.g., "HAL9500"). + * @return Pointer to the PInstrument object, or nullptr if not found. */ PInstrument *PAdmin::getInstrument(QString institute, QString instrument) { @@ -1192,7 +1224,13 @@ PInstrument *PAdmin::getInstrument(QString institute, QString instrument) //-------------------------------------------------------------------------- /** + * @brief PAdmin::loadMusrWizDefault loads the musrWiz.xml default settings file. * + * If the file doesn't exist at the specified path, copies the default from + * the built-in Qt resource system to $HOME/.musrfit/musrWiz/. + * + * @param fln Path to the musrWiz.xml file. + * @return 0 on success, 1 on failure. */ int PAdmin::loadMusrWizDefault(QString fln) { @@ -1232,7 +1270,13 @@ int PAdmin::loadMusrWizDefault(QString fln) //-------------------------------------------------------------------------- /** + * @brief PAdmin::loadMusrfitFunc loads the musrfit_funcs.xml file. * + * If the file doesn't exist at the specified path, copies the default from + * the built-in Qt resource system to $HOME/.musrfit/musrWiz/. + * + * @param fln Path to the musrfit_funcs.xml file. + * @return 0 on success, 1 on failure. */ int PAdmin::loadMusrfitFunc(QString fln) { @@ -1265,10 +1309,14 @@ int PAdmin::loadMusrfitFunc(QString fln) //-------------------------------------------------------------------------- /** - * @brief PAdmin::loadInstrumentDef - * @param path - * @param fln - * @return + * @brief PAdmin::loadInstrumentDef loads an instrument definition XML file. + * + * If the file doesn't exist at the specified path, copies the default from + * the built-in Qt resource system to $HOME/.musrfit/musrWiz/. + * + * @param path Directory path containing the file. + * @param fln Filename of the instrument definition file (e.g., "instrument_def_psi.xml"). + * @return 0 on success, 1 on failure. */ int PAdmin::loadInstrumentDef(QString path, QString fln) { diff --git a/src/musredit_qt6/musrWiz/PAdmin.h b/src/musredit_qt6/musrWiz/PAdmin.h index 6d7175a66..c14f0f02a 100644 --- a/src/musredit_qt6/musrWiz/PAdmin.h +++ b/src/musredit_qt6/musrWiz/PAdmin.h @@ -43,16 +43,36 @@ class PAdmin; -//--------------------------------------------------------------------------- +/** + * @brief The PFuncXMLParser class parses the musrfit_funcs.xml file. + * + * This class reads and parses the XML file containing musrfit function definitions + * and theory templates. The parsed data is stored in the PAdmin object which is + * passed to the constructor. + */ class PFuncXMLParser { public: + /** + * @brief Constructor. Parses the given XML file. + * @param fln Path to the musrfit_funcs.xml file. + * @param admin Pointer to the PAdmin object where parsed data will be stored. + */ PFuncXMLParser(const QString &fln, PAdmin*); + + /** + * @brief Destructor. + */ virtual ~PFuncXMLParser() {} + /** + * @brief Checks if the XML parsing was successful. + * @return true if parsing succeeded, false otherwise. + */ virtual bool isValid() { return fValid; } private: + /// @brief Enumeration of XML tag keywords for parsing state machine. enum EFuncKeyWords {eEmpty, eTemplateName, eTemplateTheo, eTemplateFunc, eName, eAbbrv, eNoOfParam, eParam, @@ -71,21 +91,41 @@ class PFuncXMLParser EFuncKeyWords fKeyWord; ///< key word tag to know how to handle the content PAdmin *fAdmin; ///< a pointer to the main administration class object - PTheoTemplate fTheoTemplate; - PMusrfitFunc fFunc; - PFuncParam fParam; + PTheoTemplate fTheoTemplate; ///< current theory template being parsed + PMusrfitFunc fFunc; ///< current function being parsed + PFuncParam fParam; ///< current function parameter being parsed }; -//--------------------------------------------------------------------------- +/** + * @brief The PInstrumentDefXMLParser class parses instrument definition XML files. + * + * This class reads and parses XML files containing instrument definitions for + * various muon facilities (PSI, TRIUMF, ISIS, J-PARC). Each instrument includes + * setup configurations for different measurement types (ZF, TF, LF). + */ class PInstrumentDefXMLParser { public: + /** + * @brief Constructor. Parses the given instrument definition XML file. + * @param fln Path to the instrument definition XML file. + * @param admin Pointer to the PAdmin object where parsed data will be stored. + */ PInstrumentDefXMLParser(const QString &fln, PAdmin*); + + /** + * @brief Destructor. + */ virtual ~PInstrumentDefXMLParser() {} + /** + * @brief Checks if the XML parsing was successful. + * @return true if parsing succeeded, false otherwise. + */ virtual bool isValid() { return fValid; } private: + /// @brief Enumeration of XML tag keywords for parsing state machine. enum EKeyWords {eEmpty, eInstitute, eInstrument, eRunNameTemplate, eBeamline, eDataFileFormat, eTf, eZf, eLf, eNoOfDetectors, eFgbOffset, eLgb, eBkgRange, @@ -100,45 +140,105 @@ class PInstrumentDefXMLParser QXmlStreamReader fXml; ///< xml stream reader object bool fValid; ///< flag showing if XML read has been successful - EKeyWords fKeyWord; ///< key word tag to know how to handle the content - PAdmin *fAdmin; ///< a pointer to the main administration class object + EKeyWords fKeyWord; ///< key word tag to know how to handle the content + PAdmin *fAdmin; ///< a pointer to the main administration class object - QString fInstituteName; - PInstrument *fInstrument; - PSetup *fSetup; + QString fInstituteName; ///< current institute name being parsed + PInstrument *fInstrument; ///< current instrument object being built + PSetup *fSetup; ///< current setup object being built }; -//--------------------------------------------------------------------------- +/** + * @brief The PMusrWizDefault class stores default settings for the musrWiz wizard. + * + * This class holds the default institute, instrument, and fit type that should + * be pre-selected when the wizard starts. These defaults are loaded from the + * musrWiz.xml configuration file. + */ class PMusrWizDefault { public: + /** + * @brief Constructor. Initializes defaults to "UnDef". + */ PMusrWizDefault(); + + /** + * @brief Destructor. + */ ~PMusrWizDefault() {} + /** + * @brief Returns the default institute name. + * @return Default institute name. + */ QString getInstitute() { return fInstitute; } + + /** + * @brief Returns the default instrument name. + * @return Default instrument name. + */ QString getInstrument() { return fInstrument; } + + /** + * @brief Returns the default fit type. + * @return Default fit type string. + */ QString getFitType() { return fFitType; } + /** + * @brief Sets the default institute name. + * @param str Institute name to set. + */ void setInstitute(QString str) { fInstitute = str; } + + /** + * @brief Sets the default instrument name. + * @param str Instrument name to set. + */ void setInstrument(QString str) { fInstrument = str; } + + /** + * @brief Sets the default fit type. + * @param str Fit type to set. + */ void setFitType(QString str) { fFitType = str; } private: - QString fInstitute; - QString fInstrument; - QString fFitType; + QString fInstitute; ///< default institute name + QString fInstrument; ///< default instrument name + QString fFitType; ///< default fit type }; -//--------------------------------------------------------------------------- +/** + * @brief The PMusrWizDefaultXMLParser class parses the musrWiz.xml default settings file. + * + * This class reads the musrWiz.xml file which contains the default settings for + * the wizard, including the default institute, instrument, and fit type. + */ class PMusrWizDefaultXMLParser { public: + /** + * @brief Constructor. Parses the given musrWiz.xml file. + * @param fln Path to the musrWiz.xml file. + * @param admin Pointer to the PAdmin object where parsed defaults will be stored. + */ PMusrWizDefaultXMLParser(const QString &fln, PAdmin*); + + /** + * @brief Destructor. + */ virtual ~PMusrWizDefaultXMLParser() {} + /** + * @brief Checks if the XML parsing was successful. + * @return true if parsing succeeded, false otherwise. + */ virtual bool isValid() { return fValid; } private: + /// @brief Enumeration of XML tag keywords for parsing state machine. enum EKeyWords {eEmpty, eInstitute, eInstrument, eFitType}; bool parse(QIODevice *device); @@ -150,37 +250,136 @@ class PMusrWizDefaultXMLParser QXmlStreamReader fXml; ///< xml stream reader object bool fValid; ///< flag showing if XML read has been successful - EKeyWords fKeyWord; ///< key word tag to know how to handle the content - PAdmin *fAdmin; ///< a pointer to the main administration class object + EKeyWords fKeyWord; ///< key word tag to know how to handle the content + PAdmin *fAdmin; ///< a pointer to the main administration class object - PMusrWizDefault fDefault; + PMusrWizDefault fDefault; ///< default settings being parsed }; -//--------------------------------------------------------------------------- +/** + * @brief The PAdmin class is the main administration class for musrWiz. + * + * This class serves as the central repository for all configuration data needed + * by the musrWiz application. It loads and manages: + * - Default wizard settings from musrWiz.xml + * - Musrfit function definitions and theory templates from musrfit_funcs.xml + * - Instrument definitions from instrument_def_*.xml files + * + * The XML parser friend classes populate this class with data from the configuration files. + */ class PAdmin : public QObject { public: + /** + * @brief Constructor. Loads all configuration files. + * + * Attempts to load configuration files first from the local directory, + * then from $HOME/.musrfit/musrWiz/. If files don't exist, creates them + * from built-in resources. + */ PAdmin(); + + /** + * @brief Destructor. + */ ~PAdmin() {} + /** + * @brief Checks if the admin object was initialized successfully. + * @return true if all required configuration files were loaded, false otherwise. + */ bool IsValid() { return fValid; } + + /** + * @brief Dumps debug information to stdout. + * @param tag Debug tag: 0=instrument defs, 1=musrfit funcs, 2=both, -1=none. + */ void dump(int tag); + /** + * @brief Returns the default institute name. + * @return Default institute name from musrWiz.xml. + */ QString getDefaultInstitute() { return fDefault.getInstitute(); } + + /** + * @brief Returns the default instrument name. + * @return Default instrument name from musrWiz.xml. + */ QString getDefaultInstrument() { return fDefault.getInstrument(); } + + /** + * @brief Returns the default fit type. + * @return Default fit type string from musrWiz.xml. + */ QString getDefaultFitType() { return fDefault.getFitType(); } + /** + * @brief Returns a list of all available institute names. + * @return QStringList containing all institute names. + */ QStringList getInstituteList(); + + /** + * @brief Returns a list of instruments for a given institute. + * @param institute Institute name to query. + * @return QStringList containing all instrument names for the institute. + */ QStringList getInstrumentList(QString institute); + + /** + * @brief Returns a pointer to an instrument object. + * @param institute Institute name. + * @param instrument Instrument name. + * @return Pointer to PInstrument, or nullptr if not found. + */ PInstrument *getInstrument(QString institute, QString instrument); + + /** + * @brief Returns the number of theory templates. + * @return Number of theory templates. + */ int getTheoTemplateSize() { return fTheoTemplate.size(); } + + /** + * @brief Returns all theory templates. + * @return QVector containing all PTheoTemplate objects. + */ QVector getTheoTemplates() { return fTheoTemplate; } + + /** + * @brief Returns a theory template by index. + * @param idx Index of the template. + * @return PTheoTemplate at the given index, or empty template if out of range. + */ PTheoTemplate getTheoTemplate(int idx); + + /** + * @brief Returns the number of musrfit functions. + * @return Number of musrfit functions. + */ int getMusrfitFuncSize() { return fMusrfitFunc.size(); } + + /** + * @brief Returns all musrfit functions. + * @return QVector containing all PMusrfitFunc objects. + */ QVector getMusrfitFunc() { return fMusrfitFunc; } + + /** + * @brief Returns a musrfit function by name or abbreviation. + * @param name Function name or abbreviation. + * @return PMusrfitFunc matching the name, or default func if not found. + */ PMusrfitFunc getMusrfitFunc(QString name); protected: + /** + * @brief Adds an instrument to an institute. + * @param institute Institute name. Creates the institute if it doesn't exist. + * @param instrument Instrument object to add. + * @return 0 on success. + */ int addInstrument(QString institute, PInstrument instrument); private: @@ -188,15 +387,33 @@ class PAdmin : public QObject friend class PInstrumentDefXMLParser; friend class PMusrWizDefaultXMLParser; - bool fValid; + bool fValid; ///< flag indicating successful initialization - PMusrWizDefault fDefault; - QVector fInstitute; - QVector fTheoTemplate; - QVector fMusrfitFunc; + PMusrWizDefault fDefault; ///< default wizard settings + QVector fInstitute; ///< list of institutes with their instruments + QVector fTheoTemplate; ///< list of theory templates + QVector fMusrfitFunc; ///< list of musrfit functions + /** + * @brief Loads the musrWiz.xml default settings file. + * @param fln Path to the file. + * @return 0 on success, 1 on failure. + */ int loadMusrWizDefault(QString fln); + + /** + * @brief Loads the musrfit_funcs.xml file. + * @param fln Path to the file. + * @return 0 on success, 1 on failure. + */ int loadMusrfitFunc(QString fln); + + /** + * @brief Loads an instrument definition XML file. + * @param path Directory path containing the file. + * @param fln Filename of the instrument definition file. + * @return 0 on success, 1 on failure. + */ int loadInstrumentDef(QString path, QString fln); }; diff --git a/src/musredit_qt6/musrWiz/PInstrumentDef.cpp b/src/musredit_qt6/musrWiz/PInstrumentDef.cpp index c4df1b9ad..ddab025b4 100644 --- a/src/musredit_qt6/musrWiz/PInstrumentDef.cpp +++ b/src/musredit_qt6/musrWiz/PInstrumentDef.cpp @@ -31,7 +31,7 @@ //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * + * @brief PSetup::PSetup constructor initializes all values to -1/empty. */ PSetup::PSetup() { @@ -45,9 +45,10 @@ PSetup::PSetup() //-------------------------------------------------------------------------- /** - * @brief PSetup::getDetector - * @param idx - * @return + * @brief PSetup::getDetector returns a pointer to a single-histogram logical detector. + * + * @param idx Index of the detector in the logical detector list. + * @return Pointer to PDetector, or nullptr if index is out of range. */ PDetector* PSetup::getDetector(int idx) { @@ -59,9 +60,10 @@ PDetector* PSetup::getDetector(int idx) //-------------------------------------------------------------------------- /** - * @brief PSetup::getAsymDetector - * @param idx - * @return + * @brief PSetup::getAsymDetector returns a pointer to an asymmetry logical detector. + * + * @param idx Index of the detector in the asymmetry detector list. + * @return Pointer to PDetector, or nullptr if index is out of range. */ PDetector* PSetup::getAsymDetector(int idx) { @@ -73,7 +75,7 @@ PDetector* PSetup::getAsymDetector(int idx) //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * + * @brief PInstrument::PInstrument constructor initializes all strings to empty. */ PInstrument::PInstrument() { @@ -86,9 +88,10 @@ PInstrument::PInstrument() //-------------------------------------------------------------------------- /** - * @brief PInstrument::getZFSetup - * @param name - * @return + * @brief PInstrument::getZFSetup returns a zero-field setup by name. + * + * @param name Setup name to search for. If empty, returns the first available setup. + * @return Pointer to PSetup, or nullptr if not found. */ PSetup* PInstrument::getZFSetup(QString name) { @@ -101,9 +104,10 @@ PSetup* PInstrument::getZFSetup(QString name) //-------------------------------------------------------------------------- /** - * @brief PInstrument::getTFSetup - * @param name - * @return + * @brief PInstrument::getTFSetup returns a transverse-field setup by name. + * + * @param name Setup name to search for. If empty, returns the first available setup. + * @return Pointer to PSetup, or nullptr if not found. */ PSetup* PInstrument::getTFSetup(QString name) { @@ -116,9 +120,10 @@ PSetup* PInstrument::getTFSetup(QString name) //-------------------------------------------------------------------------- /** - * @brief PInstrument::getLFSetup - * @param name - * @return + * @brief PInstrument::getLFSetup returns a longitudinal-field setup by name. + * + * @param name Setup name to search for. If empty, returns the first available setup. + * @return Pointer to PSetup, or nullptr if not found. */ PSetup* PInstrument::getLFSetup(QString name) { @@ -131,7 +136,7 @@ PSetup* PInstrument::getLFSetup(QString name) //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * + * @brief PInstitute::PInstitute constructor initializes the name to empty. */ PInstitute::PInstitute() { @@ -140,7 +145,10 @@ PInstitute::PInstitute() //-------------------------------------------------------------------------- /** + * @brief PInstitute::getInstrument returns an instrument by name. * + * @param name Instrument name to search for. + * @return Pointer to PInstrument, or nullptr if not found. */ PInstrument *PInstitute::getInstrument(QString name) { diff --git a/src/musredit_qt6/musrWiz/PInstrumentDef.h b/src/musredit_qt6/musrWiz/PInstrumentDef.h index d919e0290..0e27b8e96 100644 --- a/src/musredit_qt6/musrWiz/PInstrumentDef.h +++ b/src/musredit_qt6/musrWiz/PInstrumentDef.h @@ -33,131 +33,434 @@ #include #include -//--------------------------------------------------------------------------- +/** + * @brief The PDetector class represents a logical muon detector. + * + * This class encapsulates the properties of a detector configuration including + * its name, relative geometric phase, forward/backward detector indices, and + * alpha parameter (for asymmetry fits). It is used in the instrument definition + * to specify detector groupings for different measurement setups. + */ class PDetector { public: + /** + * @brief Constructor. + */ PDetector() {} + + /** + * @brief Destructor. + */ ~PDetector() {} + /** + * @brief Sets the detector name. + * @param str Detector name (e.g., "Forward", "Backward", "Left"). + */ void setName(QString str) { fName = str; } + + /** + * @brief Sets the relative geometric phase. + * @param phase Phase angle in degrees relative to a reference detector. + */ void setRelGeomPhase(double phase) { fRelGeomPhase = phase; } + + /** + * @brief Sets the forward detector indices. + * @param num Vector of physical detector numbers forming the forward group. + */ void setForwards(QVector num) { fForward = num; } + + /** + * @brief Sets the backward detector indices. + * @param num Vector of physical detector numbers forming the backward group. + */ void setBackwards(QVector num) { fBackward = num; } + + /** + * @brief Sets the alpha correction factor. + * @param alpha Alpha value for asymmetry correction. + */ void setAlpha(double alpha) { fAlpha = alpha; } + /** + * @brief Returns the detector name. + * @return Detector name. + */ QString getName() { return fName; } + + /** + * @brief Returns the relative geometric phase. + * @return Phase angle in degrees. + */ double getRelGeomPhase() { return fRelGeomPhase; } + + /** + * @brief Returns the forward detector indices. + * @return Vector of forward detector numbers. + */ QVector getForwards() { return fForward; } + + /** + * @brief Returns the backward detector indices. + * @return Vector of backward detector numbers. + */ QVector getBackwards() { return fBackward; } + + /** + * @brief Returns the alpha correction factor. + * @return Alpha value. + */ double getAlpha() { return fAlpha; } private: - QString fName; - QVector fForward; - QVector fBackward; - double fAlpha; - double fRelGeomPhase; + QString fName; ///< detector name + QVector fForward; ///< forward detector indices + QVector fBackward; ///< backward detector indices + double fAlpha; ///< alpha correction factor + double fRelGeomPhase; ///< relative geometric phase in degrees }; -//--------------------------------------------------------------------------- +/** + * @brief The PSetup class represents a measurement setup configuration. + * + * This class defines a specific detector setup for a measurement type (ZF, TF, or LF). + * It includes information about the number of detectors, good bin ranges, background + * ranges, and logical detector groupings for both single-histogram and asymmetry fits. + */ class PSetup { public: + /** + * @brief Constructor. Initializes all values to -1/empty. + */ PSetup(); + + /** + * @brief Destructor. + */ ~PSetup() {} + /** + * @brief Sets the setup name. + * @param str Setup name (e.g., "Default", "Veto"). + */ void setName(QString str) { fName = str; } + + /** + * @brief Sets the total number of physical detectors. + * @param no Number of detectors. + */ void setNoOfDetectors(int no) { fNoOfDetectors = no; } + + /** + * @brief Sets the first good bin offset from t0. + * @param fgbOffset Offset in bins from t0 to first good bin. + */ void setFgbOffset(int fgbOffset) { fFgbOffset = fgbOffset; } + + /** + * @brief Sets the last good bin. + * @param lgb Last good bin number. + */ void setLgb(int lgb) { fLgb = lgb; } + + /** + * @brief Sets the background range for asymmetry fits. + * @param start Start bin for background estimation. + * @param end End bin for background estimation. + */ void setBkgRange(int start, int end) { fBkgStartBin = start; fBkgEndBin = end; } + + /** + * @brief Adds a logical detector for single-histogram fits. + * @param detector Detector configuration to add. + */ void addDetector(PDetector detector) { fLogicDetectors.push_back(detector); } + + /** + * @brief Adds a logical detector for asymmetry fits. + * @param detector Detector configuration to add (with forward/backward groups). + */ void addAsymDetector(PDetector detector) { fLogicAsymDetectors.push_back(detector); } + /** + * @brief Returns the setup name. + * @return Setup name. + */ QString getName() { return fName; } + + /** + * @brief Returns the total number of physical detectors. + * @return Number of detectors. + */ int getNoOfDetectors() { return fNoOfDetectors; } + + /** + * @brief Returns the number of logical detectors for single-histogram fits. + * @return Number of logical detectors. + */ int getNoOfLogicalDetectors() { return fLogicDetectors.size(); } + + /** + * @brief Returns the number of logical detectors for asymmetry fits. + * @return Number of asymmetry detectors. + */ int getNoOfLogicalAsymDetectors() { return fLogicAsymDetectors.size(); } + + /** + * @brief Returns the first good bin offset. + * @return Offset in bins from t0. + */ int getFgbOffset() { return fFgbOffset; } + + /** + * @brief Returns the last good bin. + * @return Last good bin number. + */ int getLgb() { return fLgb; } + + /** + * @brief Returns the background range start bin. + * @return Background start bin. + */ int getBkgStartBin() { return fBkgStartBin; } + + /** + * @brief Returns the background range end bin. + * @return Background end bin. + */ int getBkgEndBin() { return fBkgEndBin; } + + /** + * @brief Returns a pointer to a single-histogram logical detector. + * @param idx Index of the detector. + * @return Pointer to PDetector, or nullptr if index out of range. + */ PDetector* getDetector(int idx); + + /** + * @brief Returns a pointer to an asymmetry logical detector. + * @param idx Index of the detector. + * @return Pointer to PDetector, or nullptr if index out of range. + */ PDetector* getAsymDetector(int idx); private: - QString fName; - int fNoOfDetectors; - int fFgbOffset; - int fLgb; - int fBkgStartBin; - int fBkgEndBin; + QString fName; ///< setup name + int fNoOfDetectors; ///< total number of physical detectors + int fFgbOffset; ///< first good bin offset from t0 + int fLgb; ///< last good bin + int fBkgStartBin; ///< background range start bin + int fBkgEndBin; ///< background range end bin - QVector fLogicDetectors; - QVector fLogicAsymDetectors; + QVector fLogicDetectors; ///< logical detectors for single-histogram fits + QVector fLogicAsymDetectors; ///< logical detectors for asymmetry fits }; -//--------------------------------------------------------------------------- +/** + * @brief The PInstrument class represents a muon spectrometer instrument. + * + * This class contains all information about a specific muon instrument including + * its name, beamline, run name template, data file format, and measurement setups + * for ZF (zero field), TF (transverse field), and LF (longitudinal field) configurations. + */ class PInstrument { public: + /** + * @brief Constructor. Initializes all strings to empty. + */ PInstrument(); + + /** + * @brief Destructor. + */ ~PInstrument() {} + /** + * @brief Sets the run name template for data file naming. + * @param str Template string (e.g., "deltat_tdc_gps_[yyyy]_[nnnn].bin"). + */ void setRunNameTemplate(QString str) { fRunNameTemplate = str; } + + /** + * @brief Sets the beamline name. + * @param str Beamline identifier (e.g., "piM3.2"). + */ void setBeamline(QString str) { fBeamline = str; } + + /** + * @brief Sets the data file format. + * @param str File format (e.g., "PsiMdu", "NeXus", "WKM"). + */ void setDataFileFormat(QString str) { fDataFileFormat = str; } + + /** + * @brief Sets the institute name. + * @param str Institute name (e.g., "PSI"). + */ void setInstitue(QString str) { fInstitue = str; } + + /** + * @brief Sets the instrument name. + * @param str Instrument name (e.g., "GPS", "HAL9500"). + */ void setName(QString str) { fName = str; } + /** + * @brief Adds a zero-field (ZF) setup configuration. + * @param zf Setup object to add. + */ void addSetupZF(PSetup zf) { fZF.push_back(zf); } + + /** + * @brief Adds a transverse-field (TF) setup configuration. + * @param tf Setup object to add. + */ void addSetupTF(PSetup tf) { fTF.push_back(tf); } + + /** + * @brief Adds a longitudinal-field (LF) setup configuration. + * @param lf Setup object to add. + */ void addSetupLF(PSetup lf) { fLF.push_back(lf); } + /** + * @brief Returns the run name template. + * @return Run name template string. + */ QString getRunNameTemplate() { return fRunNameTemplate; } + + /** + * @brief Returns the beamline name. + * @return Beamline name. + */ QString getBeamline() { return fBeamline; } + + /** + * @brief Returns the data file format. + * @return Data file format string. + */ QString getDataFileFormat() { return fDataFileFormat; } + + /** + * @brief Returns the institute name. + * @return Institute name. + */ QString getInstitute() { return fInstitue; } + + /** + * @brief Returns the instrument name. + * @return Instrument name. + */ QString getName() { return fName; } - QVector getZFSetups() { return fZF; } - QVector getTFSetups() { return fTF; } - QVector getLFSetups() { return fLF; } + /** + * @brief Returns all ZF setups. + * @return Vector of ZF setup configurations. + */ + QVector getZFSetups() { return fZF; } + /** + * @brief Returns all TF setups. + * @return Vector of TF setup configurations. + */ + QVector getTFSetups() { return fTF; } + + /** + * @brief Returns all LF setups. + * @return Vector of LF setup configurations. + */ + QVector getLFSetups() { return fLF; } + + /** + * @brief Returns a ZF setup by name. + * @param name Setup name (default: first available). + * @return Pointer to PSetup, or nullptr if not found. + */ PSetup* getZFSetup(QString name=""); + + /** + * @brief Returns a TF setup by name. + * @param name Setup name (default: first available). + * @return Pointer to PSetup, or nullptr if not found. + */ PSetup* getTFSetup(QString name=""); + + /** + * @brief Returns a LF setup by name. + * @param name Setup name (default: first available). + * @return Pointer to PSetup, or nullptr if not found. + */ PSetup* getLFSetup(QString name=""); private: - QString fRunNameTemplate; - QString fBeamline; - QString fDataFileFormat; - QString fInstitue; - QString fName; + QString fRunNameTemplate; ///< template for run file names + QString fBeamline; ///< beamline identifier + QString fDataFileFormat; ///< data file format + QString fInstitue; ///< institute name + QString fName; ///< instrument name - QVector fZF; - QVector fTF; - QVector fLF; + QVector fZF; ///< zero-field setups + QVector fTF; ///< transverse-field setups + QVector fLF; ///< longitudinal-field setups }; -//--------------------------------------------------------------------------- +/** + * @brief The PInstitute class represents a muon research facility/institute. + * + * This class groups multiple muon instruments belonging to the same research + * facility (e.g., PSI, TRIUMF, ISIS, J-PARC). + */ class PInstitute { public: + /** + * @brief Constructor. Initializes the name to empty. + */ PInstitute(); + + /** + * @brief Destructor. + */ ~PInstitute() {} + /** + * @brief Sets the institute name. + * @param str Institute name (e.g., "PSI", "TRIUMF"). + */ void setName(QString str) { fName = str; } + + /** + * @brief Adds an instrument to this institute. + * @param instrument Instrument object to add. + */ void addInstrument(PInstrument instrument) { fInstrument.push_back(instrument); } + /** + * @brief Returns the institute name. + * @return Institute name. + */ QString getName() { return fName; } + + /** + * @brief Returns all instruments belonging to this institute. + * @return Vector of PInstrument objects. + */ QVector getInstruments() { return fInstrument; } + + /** + * @brief Returns an instrument by name. + * @param name Instrument name. + * @return Pointer to PInstrument, or nullptr if not found. + */ PInstrument *getInstrument(QString name); private: - QString fName; - QVector fInstrument; + QString fName; ///< institute name + QVector fInstrument; ///< list of instruments at this institute }; #endif // _PINSTRUMENTDEF_H_ diff --git a/src/musredit_qt6/musrWiz/PMusrfitFunc.cpp b/src/musredit_qt6/musrWiz/PMusrfitFunc.cpp index 45c7198b6..b2bc956d9 100644 --- a/src/musredit_qt6/musrWiz/PMusrfitFunc.cpp +++ b/src/musredit_qt6/musrWiz/PMusrfitFunc.cpp @@ -31,7 +31,10 @@ //--------------------------------------------------------------------------- /** + * @brief PMusrfitFunc::initFunc initializes all member variables to default values. * + * Sets name and abbreviation to "UnDef", number of parameters to -1, + * and clears the parameter list. */ void PMusrfitFunc::initFunc() { @@ -43,7 +46,10 @@ void PMusrfitFunc::initFunc() //--------------------------------------------------------------------------- /** + * @brief PMusrfitFunc::getFuncParam returns a function parameter by index. * + * @param idx Index of the parameter (0-based). + * @return PFuncParam at the given index, or an empty/default parameter if index is out of range. */ PFuncParam PMusrfitFunc::getFuncParam(int idx) { diff --git a/src/musredit_qt6/musrWiz/PMusrfitFunc.h b/src/musredit_qt6/musrWiz/PMusrfitFunc.h index 80ba45bd8..e5e763f50 100644 --- a/src/musredit_qt6/musrWiz/PMusrfitFunc.h +++ b/src/musredit_qt6/musrWiz/PMusrfitFunc.h @@ -33,52 +33,159 @@ #include #include -//--------------------------------------------------------------------------- +/** + * @brief The PFuncParam class represents a parameter of a musrfit function. + * + * This class holds information about a single parameter of a musrfit theory function, + * including its name, default value, and whether it should be treated as a map + * (run-specific parameter) rather than a global parameter. + */ class PFuncParam { public: + /** + * @brief Constructor. Initializes to default values. + */ PFuncParam() { initParam(); } + + /** + * @brief Destructor. + */ ~PFuncParam() {} + /** + * @brief Initializes all member variables to default values. + * + * Sets name to "UnDef", value to 0.0, and map flag to false. + */ void initParam() { fName = "UnDef"; fValue = 0.0; fMap = false; } + /** + * @brief Sets the parameter name. + * @param name Parameter name (e.g., "rate", "phase", "sigma"). + */ void setParamName(QString name) { fName = name; } + + /** + * @brief Sets the default parameter value. + * @param dval Default value. + */ void setParamValue(double dval) { fValue = dval; } + + /** + * @brief Sets whether this parameter should be a map. + * @param isMap true if this is a run-specific (map) parameter. + */ void setParamMap(bool isMap) { fMap = isMap; } + /** + * @brief Returns the parameter name. + * @return Parameter name. + */ QString getParamName() { return fName; } + + /** + * @brief Returns the default parameter value. + * @return Default value. + */ double getParamValue() { return fValue; } + + /** + * @brief Checks if this is a map parameter. + * @return true if this is a run-specific (map) parameter. + */ bool isMap() { return fMap; } private: - QString fName; - double fValue; - bool fMap; + QString fName; ///< parameter name + double fValue; ///< default parameter value + bool fMap; ///< flag indicating if this is a map (run-specific) parameter }; -//--------------------------------------------------------------------------- +/** + * @brief The PMusrfitFunc class represents a musrfit theory function. + * + * This class holds the definition of a musrfit theory function including its + * full name, abbreviation (used in msr-files), number of parameters, and + * the parameter definitions. Examples include simpleGss (sg), simpleLor (sl), + * TFieldCos (tf), etc. + */ class PMusrfitFunc { public: + /** + * @brief Constructor. Initializes to default values. + */ PMusrfitFunc() { initFunc(); } + + /** + * @brief Destructor. + */ ~PMusrfitFunc() {} + /** + * @brief Initializes all member variables to default values. + */ void initFunc(); + /** + * @brief Sets the function name. + * @param name Full function name (e.g., "simpleGss"). + */ void setName(QString name) { fName = name; } + + /** + * @brief Sets the function abbreviation. + * @param abbrv Abbreviation used in msr-files (e.g., "sg"). + */ void setAbbrv(QString abbrv) { fAbbrv = abbrv; } + + /** + * @brief Sets the number of parameters this function takes. + * @param ival Number of parameters. + */ void setNoOfParam(int ival) { fNoOfParam = ival; } + + /** + * @brief Adds a parameter definition to this function. + * @param param Parameter object to add. + */ void addFuncParam(PFuncParam param) { fParam.push_back(param); } + /** + * @brief Returns the function name. + * @return Full function name. + */ QString getName() { return fName; } + + /** + * @brief Returns the function abbreviation. + * @return Abbreviation string. + */ QString getAbbrv() { return fAbbrv; } + + /** + * @brief Returns the number of parameters. + * @return Number of parameters. + */ int getNoOfParam() { return fNoOfParam; } + + /** + * @brief Returns a function parameter by index. + * @param idx Index of the parameter. + * @return PFuncParam at the given index, or default param if out of range. + */ PFuncParam getFuncParam(int idx); + + /** + * @brief Returns a pointer to the parameter vector. + * @return Pointer to the QVector of PFuncParam. + */ QVector *getFuncParams() { return &fParam; } private: - QString fName; - QString fAbbrv; - int fNoOfParam; - QVector fParam; + QString fName; ///< full function name + QString fAbbrv; ///< abbreviation for msr-files + int fNoOfParam; ///< number of parameters + QVector fParam; ///< parameter definitions }; #endif // _PMUSRFITFUNC_H_ diff --git a/src/musredit_qt6/musrWiz/musrWiz.cpp b/src/musredit_qt6/musrWiz/musrWiz.cpp index 0ac3e400c..8466eac11 100644 --- a/src/musredit_qt6/musrWiz/musrWiz.cpp +++ b/src/musredit_qt6/musrWiz/musrWiz.cpp @@ -17,7 +17,10 @@ //------------------------------------------------------------------- /** + * @brief PParam::init initializes all member variables to default/undefined values. * + * Sets name, posErr, boundLow, and boundHigh to "UnDef", number to -1, + * and value/step to 0.0. */ void PParam::init() { @@ -32,7 +35,13 @@ void PParam::init() //------------------------------------------------------------------- /** + * @brief Prints the command-line syntax help for musrWiz. * + * Displays usage information including available command-line options: + * - --version/-v: prints git version information + * - --debug [0|1|2]: enables debug output for instrument definitions and/or functions + * - --log: writes a log file with the generated msr-file path + * - --help: shows this help */ void musrWiz_syntax() { @@ -48,7 +57,20 @@ void musrWiz_syntax() //------------------------------------------------------------------- /** + * @brief Main entry point for the musrWiz application. * + * Parses command-line arguments and launches the musrWiz wizard GUI. + * Creates the PAdmin object to load configuration files (instrument definitions, + * musrfit functions, etc.) and then starts the wizard workflow. + * + * After the wizard completes, if requested via --log option, writes a log file + * containing the path to the generated msr-file. If musrt0 should be called + * (T0_FROM_MUSR_T0), either logs this flag or starts musrt0 directly. + * + * @param argc Number of command-line arguments. + * @param argv Array of command-line argument strings. + * @return 0 on success (or --help/--version), 1 on initialization failure, + * or the wizard result code. */ int main(int argc, char *argv[]) { diff --git a/src/musredit_qt6/musrWiz/musrWiz.h b/src/musredit_qt6/musrWiz/musrWiz.h index 67e6677d8..3650243cb 100644 --- a/src/musredit_qt6/musrWiz/musrWiz.h +++ b/src/musredit_qt6/musrWiz/musrWiz.h @@ -32,44 +32,133 @@ #include -//------------------------------------------------------------------- +/** + * @brief The PParam class handles a single fit parameter for the musrWiz application. + * + * This class encapsulates all properties of a musrfit fit parameter including its + * name, number, value, step size, positive error, and optional lower/upper bounds. + * It is used throughout the musrWiz wizard to manage parameter definitions. + */ class PParam { public: + /** + * @brief Constructor. Initializes the parameter to default values. + */ PParam() { init(); } + + /** + * @brief Destructor. + */ ~PParam() {} + /** + * @brief Initializes all member variables to default/undefined values. + */ void init(); + /** + * @brief Returns the parameter name. + * @return Parameter name as QString. + */ QString getName() { return fName; } + + /** + * @brief Returns the parameter number. + * @return Parameter number. + */ int getNumber() { return fNumber; } + + /** + * @brief Returns the parameter value. + * @return Parameter value. + */ double getValue() { return fValue; } + + /** + * @brief Returns the step size for the fit. + * @return Step size. + */ double getStep() { return fStep; } + + /** + * @brief Returns the positive error string. + * @return Positive error as QString. + */ QString getPosErr() { return fPosErr; } + + /** + * @brief Returns the lower bound for the parameter. + * @return Lower bound as QString. + */ QString getBoundLow() { return fBoundLow; } + + /** + * @brief Returns the upper bound for the parameter. + * @return Upper bound as QString. + */ QString getBoundHigh() { return fBoundHigh; } + /** + * @brief Sets the parameter name. + * @param str Name to set. + */ void setName(QString str) { fName = str; } + + /** + * @brief Sets the parameter number. + * @param ival Number to set. + */ void setNumber(int ival) { fNumber = ival; } + + /** + * @brief Sets the parameter value. + * @param dval Value to set. + */ void setValue(double dval) { fValue = dval; } + + /** + * @brief Sets the step size. + * @param dval Step size to set. + */ void setStep(double dval) { fStep = dval; } + + /** + * @brief Sets the positive error string. + * @param str Positive error to set. + */ void setPosErr(QString str) { fPosErr = str; } + + /** + * @brief Sets the lower bound. + * @param str Lower bound to set. + */ void setBoundLow(QString str) { fBoundLow = str; } + + /** + * @brief Sets the upper bound. + * @param str Upper bound to set. + */ void setBoundHigh(QString str) { fBoundHigh = str; } private: - QString fName; - int fNumber; - double fValue; - double fStep; - QString fPosErr; - QString fBoundLow; - QString fBoundHigh; + QString fName; ///< parameter name + int fNumber; ///< parameter number + double fValue; ///< parameter value + double fStep; ///< step size for fitting + QString fPosErr; ///< positive error (or "none") + QString fBoundLow; ///< lower bound (optional) + QString fBoundHigh; ///< upper bound (optional) }; -//------------------------------------------------------------------- +/** + * @brief The PFunc struct holds a function definition for musrfit. + * + * This structure stores a function number and its corresponding function + * expression string used in musrfit msr-files. + */ struct PFunc { - int number; - QString fun; + int number; ///< function number (e.g., 1 for fun1) + QString fun; ///< function expression string (e.g., "fun1 = par1 * par2") }; #endif // _MUSRWIZ_H_