diff --git a/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.cpp b/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.cpp index 31df2db5b..b061a2d1d 100644 --- a/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetSingleHistoRunBlockDialog.cpp + * @brief Implementation of the PGetSingleHistoRunBlockDialog class. + * @details This file implements the dialog for creating single histogram type + * RUN blocks in msr files. It handles user input validation and generates + * properly formatted msr-file text for all single histogram 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,10 +52,21 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructs the single histogram RUN block dialog. * - * \param helpUrl help url for the asymmetry run block - * \param lifetimeCorrection flag indicating if lifetime correction shall be enabled. + * @details Initializes the dialog UI and sets up input validators for all + * numeric fields. The dialog is created as modal. The lifetime correction + * checkbox is initialized based on the provided parameter. + * + * @par Input Validators: + * - Integer validators: histogram number, norm, data range, background range, + * background fit parameter, packing, t0, lifetime parameter + * - Double validators: fixed background value, fit range + * + * @param helpUrl URL to the online documentation for single histogram RUN blocks. + * Defaults to empty string if not provided. + * @param lifetimeCorrection Initial state of the lifetime correction checkbox. + * Defaults to true (enabled). */ PGetSingleHistoRunBlockDialog::PGetSingleHistoRunBlockDialog(const QString helpUrl, const bool lifetimeCorrection) : fHelpUrl(helpUrl) @@ -69,7 +93,14 @@ PGetSingleHistoRunBlockDialog::PGetSingleHistoRunBlockDialog(const QString helpU //---------------------------------------------------------------------------------------------------- /** - *

returns the run information line of the single histogram run block. + * @brief Generates the RUN header line for the single histogram 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 PGetSingleHistoRunBlockDialog::getRunHeaderInfo() { @@ -85,9 +116,16 @@ QString PGetSingleHistoRunBlockDialog::getRunHeaderInfo() //---------------------------------------------------------------------------------------------------- /** - *

returns the map for the single histogram run block. + * @brief Generates the parameter map line for the single histogram 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 PGetSingleHistoRunBlockDialog::getMap(bool &valid) { @@ -108,9 +146,16 @@ QString PGetSingleHistoRunBlockDialog::getMap(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns a data range (in bins) entry for the single histogram run block. + * @brief Generates the data range specification for the single histogram block. * - * \param valid flag indicating if the data entries are valid. + * @details Creates the "data" line specifying the histogram bin range to be + * used for fitting. Both start and end bins are required. + * + * @param[out] valid Set to true if both data range values are provided, + * false if either is missing. + * + * @return Formatted data range string, e.g.: "data 100 8000\\n" + * Returns empty string if values are missing. */ QString PGetSingleHistoRunBlockDialog::getData(bool &valid) { @@ -130,10 +175,23 @@ QString PGetSingleHistoRunBlockDialog::getData(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns the background information for the single histogram run block. + * @brief Generates the background specification for the single histogram block. * - * \param valid flag indicating if a valid background (either backgr.fix, background, or backgr.fit is given, but only one) - * is present. + * @details Creates either a "background" line (bin ranges for background estimation), + * "backgr.fix" line (fixed background value), or "backgr.fit" line (fit parameter + * for background). Only one type should be specified; if multiple are provided, + * the last one takes precedence. + * + * @par Background Types: + * - **background**: Two integers specifying bin range [start, end] for background estimation + * - **backgr.fix**: One double specifying fixed background counts per bin + * - **backgr.fit**: One integer specifying the fit parameter number for background + * + * @param[out] valid Set to true if valid background info is provided, false if + * no background info given (a default "background 0 10" is returned). + * + * @return Formatted background string, e.g.: "background 50 100\\n" + * or "backgr.fix 15.3\\n" or "backgr.fit 5\\n" */ QString PGetSingleHistoRunBlockDialog::getBackground(bool &valid) { @@ -168,10 +226,16 @@ QString PGetSingleHistoRunBlockDialog::getBackground(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns a fit range entry for the single histogram 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 single histogram 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. If no fit range is provided by the user, + * a default range of [0.0, 10.0] is returned. + * + * @param[out] valid Set to true if both fit range values are provided by the user, + * false if using the default range. + * + * @return Formatted fit range string, e.g.: "fit 0.5 9.5\\n" */ QString PGetSingleHistoRunBlockDialog::getFitRange(bool &valid) { @@ -192,10 +256,16 @@ QString PGetSingleHistoRunBlockDialog::getFitRange(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

returns the packing/binning of the single histogram 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 single histogram 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. If no packing is provided, a default value of 1 is used. + * + * @param[out] present Set to true if a packing value was provided by the user, + * false if using the default value. + * + * @return Formatted packing string, e.g.: "packing 10\\n" */ QString PGetSingleHistoRunBlockDialog::getPacking(bool &present) { @@ -214,9 +284,15 @@ QString PGetSingleHistoRunBlockDialog::getPacking(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

returns a t0 parameter for the single histogram run block. + * @brief Generates the T0 (time zero) specification for the single histogram block. * - * \param present flag indicating if a t0 parameter is set. + * @details Creates the "t0" line specifying the time zero bin for the histogram. + * T0 is the bin corresponding to muon implantation time. This parameter is optional. + * + * @param[out] present Set to true if a t0 value was provided, false if not specified. + * + * @return Formatted t0 string, e.g.: "t0 250\\n" + * Returns empty string if t0 is not specified. */ QString PGetSingleHistoRunBlockDialog::getT0(bool &present) { @@ -235,9 +311,16 @@ QString PGetSingleHistoRunBlockDialog::getT0(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

returns the muon lifetime parameter if present. + * @brief Generates the muon lifetime parameter line for the single histogram block. * - * \param present flag indicating if a muon life time parameter has been present. + * @details Creates the "lifetime" line specifying which fit parameter contains + * the muon lifetime value. This is used when the muon lifetime should be fitted + * rather than using the fixed standard value. This parameter is optional. + * + * @param[out] present Set to true if a lifetime parameter was provided, false otherwise. + * + * @return Formatted lifetime string, e.g.: "lifetime 3\\n" + * Returns empty string if lifetime parameter is not specified. */ QString PGetSingleHistoRunBlockDialog::getMuonLifetimeParam(bool &present) { @@ -256,9 +339,15 @@ QString PGetSingleHistoRunBlockDialog::getMuonLifetimeParam(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

returns the lifetime correction flag. + * @brief Generates the lifetime correction flag for the single histogram block. * - * \param present flag showing if the lifetime correction flag should be set. + * @details Creates the "lifetimecorrection" line if the checkbox is enabled. + * When present, musrfit will apply muon lifetime correction to the data, + * effectively removing the exponential decay component from the signal. + * + * @param[out] present Set to true if lifetime correction is enabled, false otherwise. + * + * @return "lifetimecorrection\\n" if enabled, empty string if disabled. */ QString PGetSingleHistoRunBlockDialog::getLifetimeCorrection(bool &present) { @@ -276,7 +365,11 @@ QString PGetSingleHistoRunBlockDialog::getLifetimeCorrection(bool &present) //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of the single histogram run block. + * @brief Opens the online help documentation for single histogram 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 PGetSingleHistoRunBlockDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.h b/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.h index de60b3bc8..ea0e12566 100644 --- a/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.h @@ -27,6 +27,23 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetSingleHistoRunBlockDialog.h + * @brief Dialog for creating single histogram RUN blocks in msr files. + * @details This header defines the PGetSingleHistoRunBlockDialog class which provides + * a dialog for entering parameters needed to create a single histogram type RUN block + * in a musrfit msr file. Single histogram fitting analyzes individual detector histograms + * rather than asymmetry between 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 PGetAsymmetryRunBlockDialog For asymmetry RUN blocks + * @see PGetNonMusrRunBlockDialog For non-muSR RUN blocks + */ + #ifndef _PGETSINGLEHISTORUNBLOCKDIALOG_H_ #define _PGETSINGLEHISTORUNBLOCKDIALOG_H_ @@ -35,9 +52,51 @@ #include "ui_PGetSingleHistoRunBlockDialog.h" -//-------------------------------------------------------------------------- +//--------------------------------------------------------------------------- /** - *

Class handling the content of the menu: Edit/Add Block/Single Histo Run Block. + * @class PGetSingleHistoRunBlockDialog + * @brief Dialog for creating single histogram type RUN blocks in msr files. + * + * @details This dialog collects all parameters needed to generate a single + * histogram RUN block for muon spin rotation data analysis. Single histogram + * fitting is used when analyzing individual detector counts rather than + * computing asymmetry from forward/backward detector pairs. + * + * @par RUN Block Parameters: + * - Run file name, beamline, institute, and file format + * - Forward histogram number + * - Normalization parameter + * - Parameter map + * - Data range (in bins) + * - Background specification (fixed, fitted, or estimated from bins) + * - T0 (time zero) value + * - Fit range (in microseconds) + * - Packing/binning factor + * - Muon lifetime parameter + * - Lifetime correction flag + * + * @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) + * map 1 2 3 + * forward 1 + * norm 1 + * data 100 8000 + * background 50 100 + * t0 250 + * fit 0.0 10.0 + * packing 1 + * @endcode + * + * @par Background Options: + * Three mutually exclusive background specification methods: + * - **background**: Bin range for background estimation [start, end] + * - **backgr.fix**: Fixed background value (counts per bin) + * - **backgr.fit**: Fit parameter number for background + * + * @see PGetAsymmetryRunBlockDialog For asymmetry fitting with detector pairs + * @see PGetNonMusrRunBlockDialog For non-muSR generic data */ class PGetSingleHistoRunBlockDialog : public QDialog, private Ui::PGetSingleHistoRunBlockDialog { @@ -46,10 +105,25 @@ class PGetSingleHistoRunBlockDialog : public QDialog, private Ui::PGetSingleHist public: PGetSingleHistoRunBlockDialog(const QString helpUrl = "", const bool lifetimeCorrection = true); + /** @name RUN Block Generators + * @brief Methods to generate formatted msr-file text for each parameter. + * @{ + */ QString getRunHeaderInfo(); QString getMap(bool &valid); + + /** + * @brief Gets the forward histogram specification line. + * @return Formatted "forward" line for the msr file. + */ QString getForward() { return QString("forward " + fForwardHistoNo_lineEdit->text() + "\n"); } + + /** + * @brief Gets the normalization parameter line. + * @return Formatted "norm" line for the msr file. + */ QString getNorm() { return QString("norm " + fNorm_lineEdit->text() + "\n"); } + QString getData(bool &valid); QString getBackground(bool &valid); QString getFitRange(bool &valid); @@ -57,12 +131,16 @@ class PGetSingleHistoRunBlockDialog : public QDialog, private Ui::PGetSingleHist QString getT0(bool &present); QString getMuonLifetimeParam(bool &present); QString getLifetimeCorrection(bool &present); + /** @} */ private slots: + /** + * @brief Opens the online help for single histogram RUN blocks. + */ void helpContent(); private: - QString fHelpUrl; ///< help url for the asymmetry run block + QString fHelpUrl; ///< URL to the online documentation for single histogram RUN blocks. }; #endif // _PGETSINGLEHISTORUNBLOCKDIALOG_H_