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

improve the doxygen docu of musrWiz.

Browse Source
This commit is contained in:
suter_a
2025-11-23 18:41:03 +01:00
parent 594d080490
commit 8d41f47540
8 changed files with 902 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
src/musredit_qt6/musrWiz/PAdmin.h
View File

@@ -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<PTheoTemplate> 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<PMusrfitFunc> 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<PInstitute> fInstitute;
QVector<PTheoTemplate> fTheoTemplate;
QVector<PMusrfitFunc> fMusrfitFunc;
PMusrWizDefault fDefault; ///< default wizard settings
QVector<PInstitute> fInstitute; ///< list of institutes with their instruments
QVector<PTheoTemplate> fTheoTemplate; ///< list of theory templates
QVector<PMusrfitFunc> 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);
};