diff --git a/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.cpp b/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.cpp index 99b3dc649..67af0c8cf 100644 --- a/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetAsymmetryRunBlockDialog.cpp + * @brief Implementation of the PGetAsymmetryRunBlockDialog class. + * @details This file implements the dialog for creating asymmetry-type RUN blocks + * in msr files. It handles user input validation and generates properly formatted + * msr-file text for all asymmetry RUN block parameters. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include #include @@ -39,9 +52,16 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructs the asymmetry RUN block dialog. * - * \param helpUrl help url for the asymmetry run block + * @details Initializes the dialog UI and sets up input validators for all + * numeric fields. The dialog is created as modal. + * + * @par Input Validators: + * - Integer validators: histogram numbers, data ranges, background ranges, t0 values, packing, alpha, beta + * - Double validators: fixed background values, fit range + * + * @param helpUrl URL to the online documentation for asymmetry RUN blocks. */ PGetAsymmetryRunBlockDialog::PGetAsymmetryRunBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl) { @@ -72,7 +92,14 @@ PGetAsymmetryRunBlockDialog::PGetAsymmetryRunBlockDialog(const QString helpUrl) //---------------------------------------------------------------------------------------------------- /** - *

returns the run information line of the asymmetry run block. + * @brief Generates the RUN header line for the asymmetry block. + * + * @details Creates the first line of the RUN block containing the run file name, + * beamline identifier, institute name, and data file format. The beamline is + * converted to uppercase. + * + * @return Formatted RUN header string, e.g.: + * "RUN data001 GPS PSI ROOT (name beamline institute data-file-format)\n" */ QString PGetAsymmetryRunBlockDialog::getRunHeaderInfo() { @@ -88,9 +115,16 @@ QString PGetAsymmetryRunBlockDialog::getRunHeaderInfo() //---------------------------------------------------------------------------------------------------- /** - *

returns the alpha parameter for the asymmetry run block. + * @brief Generates the alpha parameter line for the asymmetry block. * - * \param present flag indicating if the alpha parameter is used, or a default alpha==1 is going to be used. + * @details Alpha is the detector efficiency ratio correction parameter used in + * asymmetry calculations: A = (N_F - alpha * N_B) / (N_F + alpha * N_B). + * The parameter typically references a fit parameter number. + * + * @param[out] present Set to true if an alpha value was entered, false if empty + * (default alpha=1 will be used). + * + * @return Formatted alpha parameter string, e.g.: "alpha 1\n" */ QString PGetAsymmetryRunBlockDialog::getAlphaParameter(bool &present) { @@ -106,9 +140,16 @@ QString PGetAsymmetryRunBlockDialog::getAlphaParameter(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

returns the beta parameter for the asymmetry run block + * @brief Generates the beta parameter line for the asymmetry block. * - * \param present flag indicating if the beta parameter is used, or a default beta==1 is going to be used. + * @details Beta is the detector phase correction parameter, typically used for + * correcting phase differences between forward and backward detectors. + * The parameter typically references a fit parameter number. + * + * @param[out] present Set to true if a beta value was entered, false if empty + * (default beta=1 will be used). + * + * @return Formatted beta parameter string, e.g.: "beta 1\n" */ QString PGetAsymmetryRunBlockDialog::getBetaParameter(bool &present) { @@ -124,9 +165,16 @@ QString PGetAsymmetryRunBlockDialog::getBetaParameter(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

returns the map for the asymmetry run block. + * @brief Generates the parameter map line for the asymmetry block. * - * \param valid flag indicating if the map is potentially valid. + * @details The map line defines the mapping between theory function parameters + * and the fit parameters defined in the FITPARAMETER block. It should contain + * only space-separated integers. + * + * @param[out] valid Set to true if the map contains only digits and spaces, + * false if invalid characters are found. + * + * @return Formatted map string, e.g.: "map 1 2 3 4\n" */ QString PGetAsymmetryRunBlockDialog::getMap(bool &valid) { @@ -147,10 +195,20 @@ QString PGetAsymmetryRunBlockDialog::getMap(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns the background information for the asymmetry run block. + * @brief Generates the background specification for the asymmetry block. * - * \param valid flag indicating if a valid background (either backgr.fix or background is given, but not both) - * is present. + * @details Creates either a "background" line (bin ranges for background estimation) + * or a "backgr.fix" line (fixed background values). Only one type should be specified. + * + * @par Background Types: + * - background: Four integers specifying bin ranges [forward_start, forward_end, backward_start, backward_end] + * - backgr.fix: Two doubles specifying fixed background counts for forward and backward detectors + * + * @param[out] valid Set to true if valid background info is provided, false if + * no background info given (a default "background 0 10 0 10" is returned). + * + * @return Formatted background string, e.g.: "background 50 150 50 150\n" + * or "backgr.fix 15.3 14.8\n" */ QString PGetAsymmetryRunBlockDialog::getBackground(bool &valid) { @@ -184,9 +242,17 @@ QString PGetAsymmetryRunBlockDialog::getBackground(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns a data range (in bins) entry for the asymmetry run block. + * @brief Generates the data range specification for the asymmetry block. * - * \param valid flag indicating if the data entries are valid. + * @details Creates the "data" line specifying the histogram bin ranges to be + * used for fitting. Four values are required: start and end bins for both + * forward and backward histograms. + * + * @param[out] valid Set to true if all four data range values are provided, + * false if any are missing. + * + * @return Formatted data range string, e.g.: "data 100 8000 100 8000\n" + * Returns empty string if values are missing. */ QString PGetAsymmetryRunBlockDialog::getData(bool &valid) { @@ -209,9 +275,15 @@ QString PGetAsymmetryRunBlockDialog::getData(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns a t0 parameter for the asymmetry run block. + * @brief Generates the T0 (time zero) specification for the asymmetry block. * - * \param present flag indicating if a t0 parameter is set. + * @details Creates the "t0" line specifying the time zero bin for both forward + * and backward histograms. T0 is the bin corresponding to muon implantation time. + * + * @param[out] present Set to true if both t0 values are provided, false otherwise. + * + * @return Formatted t0 string, e.g.: "t0 250 250\n" + * Returns empty string if values are missing. */ QString PGetAsymmetryRunBlockDialog::getT0(bool &present) { @@ -231,10 +303,15 @@ QString PGetAsymmetryRunBlockDialog::getT0(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

returns a fit range entry for the asymmetry run block. If no fit range has been provided, - * a fit range [0,10] will be set and the valid flag will be set to false. + * @brief Generates the fit range specification for the asymmetry block. * - * \param valid flag indicating if a fit range was provided. + * @details Creates the "fit" line specifying the time range (in microseconds) + * over which the fit will be performed. + * + * @param[out] valid Set to true if both fit range values are provided, false if + * missing (a default range [0.0, 10.0] is returned). + * + * @return Formatted fit range string, e.g.: "fit 0.5 9.5\n" */ QString PGetAsymmetryRunBlockDialog::getFitRange(bool &valid) { @@ -255,10 +332,16 @@ QString PGetAsymmetryRunBlockDialog::getFitRange(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns the packing/binning of the asymmetry run block. If no packing has been provided, - * a packing of '1' will be set and the present flag will be set to false. + * @brief Generates the packing (rebinning) specification for the asymmetry block. * - * \param present flag indicating if a packing parameter was provided. + * @details Creates the "packing" line specifying how many histogram bins should + * be combined into one. A packing of 1 means no rebinning, 2 means combine + * pairs of bins, etc. + * + * @param[out] present Set to true if a packing value was provided, false if + * missing (a default packing of 1 is returned). + * + * @return Formatted packing string, e.g.: "packing 10\n" */ QString PGetAsymmetryRunBlockDialog::getPacking(bool &present) { @@ -277,7 +360,11 @@ QString PGetAsymmetryRunBlockDialog::getPacking(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of the asymmetry run block. + * @brief Opens the online help documentation for asymmetry RUN blocks. + * + * @details Attempts to open the help URL in the system's default web browser + * using QDesktopServices. If the URL is empty, displays an informational message. + * If the browser fails to open, displays an error message with a clickable link. */ void PGetAsymmetryRunBlockDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.h b/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.h index 08201e5fa..851f17a7e 100644 --- a/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.h @@ -27,6 +27,23 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetAsymmetryRunBlockDialog.h + * @brief Dialog for creating asymmetry RUN blocks in msr files. + * @details This header defines the PGetAsymmetryRunBlockDialog class which provides + * a dialog for entering parameters needed to create an asymmetry-type RUN block + * in a musrfit msr file. Asymmetry fitting is used for analyzing muon spin + * rotation data using forward and backward detector pairs. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetSingleHistoRunBlockDialog For single histogram RUN blocks + * @see PGetNonMusrRunBlockDialog For non-muSR RUN blocks + */ + #ifndef _PGETASYMMETRYRUNBLOCKDIALOG_H_ #define _PGETASYMMETRYRUNBLOCKDIALOG_H_ @@ -34,7 +51,42 @@ //--------------------------------------------------------------------------- /** - *

Class handling the content of the menu: Edit/Add Block/Asymmetry Run Block. + * @class PGetAsymmetryRunBlockDialog + * @brief Dialog for creating asymmetry-type RUN blocks in msr files. + * + * @details This dialog collects all parameters needed to generate an asymmetry + * RUN block for muon spin rotation data analysis. Asymmetry fitting uses the + * ratio of forward and backward detector counts to extract the muon spin + * polarization signal. + * + * @par RUN Block Parameters: + * - Run file name, beamline, institute, and file format + * - Forward and backward histogram numbers + * - Alpha parameter (detector efficiency ratio) + * - Beta parameter (detector phase correction) + * - Parameter map + * - Background specification (fixed or fitted) + * - Data range (in bins) + * - T0 (time zero) values + * - Fit range (in microseconds) + * - Packing/binning factor + * + * @par Generated Output Format: + * The dialog generates msr-file formatted text blocks such as: + * @code + * RUN data001 GPS PSI ROOT (name beamline institute data-file-format) + * alpha 1 + * beta 1 + * map 1 2 3 + * forward 1 + * backward 2 + * background 50 150 50 150 + * fit 0.0 10.0 + * packing 1 + * @endcode + * + * @see PGetSingleHistoRunBlockDialog For single histogram fitting + * @see PGetNonMusrRunBlockDialog For non-muSR data */ class PGetAsymmetryRunBlockDialog : public QDialog, private Ui::PGetAsymmetryRunBlockDialog { @@ -43,23 +95,42 @@ class PGetAsymmetryRunBlockDialog : public QDialog, private Ui::PGetAsymmetryRun public: PGetAsymmetryRunBlockDialog(const QString helpUrl); + /** @name RUN Block Generators + * @brief Methods to generate formatted msr-file text for each parameter. + * @{ + */ QString getRunHeaderInfo(); QString getAlphaParameter(bool &present); QString getBetaParameter(bool &present); QString getMap(bool &valid); + + /** + * @brief Get the forward histogram specification line. + * @return Formatted "forward" line for the msr file. + */ QString getForward() { return QString("forward " + fForwardHistoNo_lineEdit->text() + "\n"); } + + /** + * @brief Get the backward histogram specification line. + * @return Formatted "backward" line for the msr file. + */ QString getBackward() { return QString("backward " + fBackwardHistoNo_lineEdit->text() + "\n"); } + QString getBackground(bool &valid); QString getData(bool &valid); QString getT0(bool &present); QString getFitRange(bool &valid); QString getPacking(bool &present); + /** @} */ private slots: + /** + * @brief Opens the online help for asymmetry RUN blocks. + */ void helpContent(); private: - QString fHelpUrl; ///< help url for the asymmetry run block + QString fHelpUrl; ///< URL to the online documentation for asymmetry RUN blocks. }; #endif // _PGETASYMMETRYRUNBLOCKDIALOG_H_