Enhanced text editor for msr file editing with block insertion support. More...

#include <PSubTextEdit.h>

Inheritance diagram for PSubTextEdit:

Collaboration diagram for PSubTextEdit:

[legend]

Public Slots
void	insertTitle ()
	Slot: Inserts a title block via dialog.

void	insertParameterBlock ()
	Slot: Inserts a FITPARAMETER block via dialog.

void	insertTheoryFunction (QString name)
	Slot: Inserts a specific theory function.

void	insertTheoryBlock ()
	Slot: Inserts a THEORY block via dialog.

void	insertFunctionBlock ()
	Slot: Inserts a FUNCTIONS block via dialog.

void	insertAsymRunBlock ()
	Slot: Inserts an asymmetry RUN block via dialog.

void	insertSingleHistRunBlock ()
	Slot: Inserts a single histogram RUN block via dialog.

void	insertNonMusrRunBlock ()
	Slot: Inserts a non-µSR RUN block via dialog.

void	insertCommandBlock ()
	Slot: Inserts a default COMMANDS block.

void	insertFourierBlock ()
	Slot: Inserts a FOURIER block via dialog.

void	insertPlotBlock ()
	Slot: Inserts a PLOT block via dialog.

void	insertStatisticBlock ()
	Slot: Inserts a default STATISTIC block.

Public Member Functions
	PSubTextEdit (PAdmin admin=0, QWidget parent=0)
	Constructs the enhanced text editor.

virtual	~PSubTextEdit ()
	Virtual destructor.

int	getFitType ()
	Retrieves the fit type from the current msr file content.

Private Attributes
PAdmin *	fAdmin
	Pointer to administration object with theory functions, help URLs, and configuration.

Detailed Description

Enhanced text editor for msr file editing with block insertion support.

This class extends QPlainTextEdit to provide specialized editing capabilities for musrfit msr files. It offers dialog-based assistants for inserting the various structured blocks that comprise an msr file, reducing errors and improving workflow efficiency.

MSR File Structure:

An msr file contains several required and optional blocks:

Title: Optional descriptive title
FITPARAMETER: Fit parameters with initial values and constraints
THEORY: Mathematical theory functions describing the expected signal
FUNCTIONS: User-defined mathematical functions
RUN: One or more run blocks specifying data files and fit configuration
COMMANDS: MINUIT minimization commands
FOURIER: Optional Fourier transform specifications
PLOT: Plot configuration for data visualization
STATISTIC: Fit results (chi-square, NDF, etc.)

Block Insertion Features:

Each insertion method launches a specialized dialog that:

Guides users through required and optional parameters
Validates input to prevent syntax errors
Provides context-sensitive help
Inserts properly formatted text at cursor position

Run Block Types:

Different fit types require different run block formats:

Asymmetry (fittype 2): Standard µSR asymmetry analysis
Single Histogram (fittype 0): Direct histogram fitting
Non-µSR (fittype 8): General x-y data fitting

Theory Function Support:

The class provides access to all available theory functions from the PAdmin configuration, allowing quick insertion of common functions like:

Exponential relaxation (simpleExp, simpleGss)
Oscillations (cosPol, polyKT)
Static Kubo-Toyabe (statKT, dynKT)
User-defined functions (userFcn)

Validation and Error Handling:

Input validation occurs during block creation
Invalid or incomplete data triggers warning dialogs
Default values are inserted for missing critical parameters
Users are informed about required corrections

Workflow Integration:

Tab-based interface allows multiple files open simultaneously
Each tab contains a PSubTextEdit instance
Cursor position determines insertion point
Undo/redo support through QPlainTextEdit base class

Note: This class is used as the editor widget within each tab of musredit.; All block insertion operations are undoable via standard edit commands.; The class relies on PAdmin for theory function definitions and help URLs.

See also: PAdmin For theory function definitions and configuration; PGetTitleBlockDialog For title input; PGetParameterBlockDialog For parameter block creation; PGetTheoryBlockDialog For theory block creation; PGetFunctionsBlockDialog For functions block creation; PGetAsymmetryRunBlockDialog For asymmetry run blocks; PGetSingleHistoRunBlockDialog For single histogram run blocks; PGetNonMusrRunBlockDialog For non-µSR run blocks; PGetFourierBlockDialog For Fourier block creation; PGetPlotBlockDialog For plot block creation

Definition at line 128 of file PSubTextEdit.h.

Constructor & Destructor Documentation

◆ PSubTextEdit()

PSubTextEdit::PSubTextEdit	(	PAdmin *	admin = 0,
		QWidget *	parent = 0 )

Constructs the enhanced text editor.

Constructor - Initializes the enhanced text editor.

Initializes the text editor with access to the global administration object for theory functions and configuration.

Parameters

admin	Pointer to PAdmin object containing theory function definitions, help URLs, and application configuration. If nullptr, block insertion features may not work properly.
parent	Pointer to parent widget. Typically nullptr as this widget is embedded in a tab widget.

See also: PAdmin For the global administration object

Constructs a PSubTextEdit instance with access to the global administration object. The constructor is minimal, delegating most initialization to the QPlainTextEdit base class.

The administration object provides:

Theory function definitions for block insertion
Help URLs for context-sensitive documentation
Application configuration and preferences

Parameters

admin	Pointer to the PAdmin global administration object. This pointer is stored for later use by block insertion methods. If nullptr, block insertion features will not work properly as they depend on theory function definitions and help URLs.
parent	Pointer to the parent widget. Typically nullptr as this editor is embedded in a QTabWidget where the tab widget manages widget ownership and lifetime.

Note: The constructor performs no special initialization beyond storing the admin pointer. All QPlainTextEdit functionality is available immediately.; Block insertion methods should check fAdmin for nullptr before use, though in normal operation it should never be null.

See also: PAdmin For the global administration object; QPlainTextEdit For base class functionality

Definition at line 101 of file PSubTextEdit.cpp.

◆ ~PSubTextEdit()

virtual PSubTextEdit::~PSubTextEdit ( )

inlinevirtual

Virtual destructor.

Default destructor. Qt's parent-child ownership handles cleanup.

Note: Declared virtual for proper cleanup in inheritance hierarchies.

Definition at line 156 of file PSubTextEdit.h.

Member Function Documentation

◆ getFitType()

int PSubTextEdit::getFitType ( )

Retrieves the fit type from the current msr file content.

Parses the text editor content to find and extract the fittype value. The fittype determines the analysis mode and run block format:

0: Single histogram fit
2: Asymmetry fit
4: µSR-MnF fit
8: Non-µSR fit

Returns: int The fittype value if found and valid, -1 otherwise.

Note: Returns -1 if "fittype" keyword not found or value is invalid.; Only finds the first occurrence of "fittype" in the document.

Parses the entire text editor content to locate the "fittype" keyword and extract its associated integer value. The fittype determines the analysis mode and affects which parameters are required in RUN blocks.

Parsing Algorithm:

Convert all editor text to QString
Search for first occurrence of "fittype" keyword
Skip whitespace after "fittype"
Extract first non-whitespace character after "fittype"
Convert character to integer
Return value if conversion succeeds

Fittype Values:

0: Single histogram fit - fits a single detector histogram directly
2: Asymmetry fit - calculates asymmetry from forward/backward histograms
4: µSR-MnF fit - special mode for muon spin rotation in magnetic fields
8: Non-µSR fit - general x-y data fitting for arbitrary data

Return Value Interpretation:

Valid fittype (0, 2, 4, 8): Normal operation, fittype found and parsed
-1: Error condition - keyword not found or invalid value

Usage Context: This method is useful for:

Validating msr file completeness before saving
Determining appropriate RUN block format for insertion
Conditional behavior based on analysis mode
Error checking during file editing

Limitations:

Only finds the first occurrence of "fittype"
Does not validate that fittype is in a RUN block context
Single-digit parsing only (assumes fittype value is 0-9)
Case-sensitive search for "fittype" keyword

Returns: int The fittype value (0, 2, 4, or 8) if found and valid, -1 if "fittype" keyword not found, value is not numeric, or parsing fails for any reason.

Note: This method searches the entire document on each call; it is not optimized for frequent queries.; Only the first occurrence of "fittype" is processed; multiple RUN blocks with different fittypes will only report the first.; The method assumes fittype appears as "fittype<whitespace><digit>".

See also: insertAsymRunBlock() Uses fittype 2; insertSingleHistRunBlock() Uses fittype 0; insertNonMusrRunBlock() Uses fittype 8

Definition at line 164 of file PSubTextEdit.cpp.

◆ insertAsymRunBlock

void PSubTextEdit::insertAsymRunBlock ( )

slot

Slot: Inserts an asymmetry RUN block via dialog.

Launches PGetAsymmetryRunBlockDialog for creating a RUN block configured for asymmetry fitting (fittype 2). This is the most common µSR analysis mode with forward/backward detector histograms and asymmetry calculation.

Validates all required fields and provides default values for missing critical parameters with appropriate warnings.

See also: PGetAsymmetryRunBlockDialog For the asymmetry run block dialog

Starts the msr-asymmetry-run input dialog window.

Definition at line 384 of file PSubTextEdit.cpp.

◆ insertCommandBlock

void PSubTextEdit::insertCommandBlock ( )

slot

Slot: Inserts a default COMMANDS block.

Inserts a standard COMMANDS block with common MINUIT commands for batch processing:

SET BATCH (suppress interactive prompts)
STRATEGY 1 (balance speed and accuracy)
MINIMIZE (perform minimization)
MINOS (commented out - for asymmetric errors)
SAVE (save parameters)
END RETURN (exit MINUIT)

Users can edit the block after insertion to customize the fit strategy.

Inserts a standard COMMANDS block with commonly used MINUIT commands for batch fitting. This block controls the MINUIT minimizer behavior during the fit process.

Inserted Commands:

SET BATCH: Suppresses interactive prompts, allowing unattended execution
STRATEGY 1: Balance between speed and accuracy (0=fast, 2=thorough)
MINIMIZE: Executes the minimization algorithm to find best parameters
**#MINOS**: (Commented out) Computes asymmetric parameter errors
SAVE: Saves fitted parameter values back to msr file
END RETURN: Exits MINUIT and returns to musrfit

MINUIT Strategy Levels:

Strategy 0: Fast, less accurate gradient/Hessian calculations
Strategy 1: Default, good balance (recommended for most fits)
Strategy 2: Thorough, most accurate but slowest

MINOS Command: MINOS is commented out (#MINOS) by default because:

It significantly increases fit time
It's only needed when asymmetric errors are important
Users can uncomment it when needed for publication-quality results

Customization: Users can edit the inserted block to:

Change STRATEGY level based on fit complexity
Uncomment MINOS for asymmetric error calculation
Add additional MINUIT commands (SIMPLEX, SEEK, IMPROVE, etc.)
Modify convergence criteria with SET commands

Block Structure: The block is delimited by:

Header: "###..." separator line
Body: "COMMANDS" keyword followed by command lines
Footer: "END RETURN" to exit command mode
Double newline for separation from next block

Note: This is the only insertion method that doesn't use a dialog, as COMMANDS blocks have a standard structure.; The block is inserted at current cursor position with proper formatting and delimiters.; All insertions are undoable via Edit → Undo.

See also: MINUIT documentation for complete command reference

Definition at line 701 of file PSubTextEdit.cpp.

◆ insertFourierBlock

void PSubTextEdit::insertFourierBlock ( )

slot

Slot: Inserts a FOURIER block via dialog.

Launches PGetFourierBlockDialog for creating the optional FOURIER block that configures Fourier transform parameters for frequency-domain analysis of µSR data.

See also: PGetFourierBlockDialog For the Fourier block dialog

Starts the msr-Fourier input dialog window.

Definition at line 717 of file PSubTextEdit.cpp.

◆ insertFunctionBlock

void PSubTextEdit::insertFunctionBlock ( )

slot

Slot: Inserts a FUNCTIONS block via dialog.

Launches PGetFunctionsBlockDialog for creating user-defined mathematical functions that can be used in theory expressions. Functions allow complex mathematical expressions to be reused.

See also: PGetFunctionsBlockDialog For the functions block dialog

Starts the msr-functions input dialog window.

Definition at line 366 of file PSubTextEdit.cpp.

◆ insertNonMusrRunBlock

void PSubTextEdit::insertNonMusrRunBlock ( )

slot

Slot: Inserts a non-µSR RUN block via dialog.

Launches PGetNonMusrRunBlockDialog for creating a RUN block configured for general x-y data fitting (fittype 8). This mode is used for fitting arbitrary tabulated data, not specifically µSR histograms.

Validates all required fields and provides default values for missing critical parameters with appropriate warnings.

See also: PGetNonMusrRunBlockDialog For the non-µSR run block dialog

Starts the msr-nonMusr-run input dialog window.

Definition at line 594 of file PSubTextEdit.cpp.

◆ insertParameterBlock

void PSubTextEdit::insertParameterBlock ( )

slot

Slot: Inserts a FITPARAMETER block via dialog.

Launches PGetParameterBlockDialog for creating the FITPARAMETER block with initial values, constraints, and parameter naming. This block defines all parameters used in the theory functions.

See also: PGetParameterBlockDialog For the parameter block dialog

Starts the msr-fit-parameter input dialog window.

Definition at line 237 of file PSubTextEdit.cpp.

◆ insertPlotBlock

void PSubTextEdit::insertPlotBlock ( )

slot

Slot: Inserts a PLOT block via dialog.

Launches PGetPlotBlockDialog for creating the PLOT block that configures data visualization options including plot ranges, what to plot (data, theory, difference), and display options.

See also: PGetPlotBlockDialog For the plot block dialog

Starts the msr-plot input dialog window.

Definition at line 734 of file PSubTextEdit.cpp.

◆ insertSingleHistRunBlock

void PSubTextEdit::insertSingleHistRunBlock ( )

slot

Slot: Inserts a single histogram RUN block via dialog.

Launches PGetSingleHistoRunBlockDialog for creating a RUN block configured for single histogram fitting (fittype 0). This mode fits a single histogram directly without asymmetry calculation.

Validates all required fields and provides default values for missing critical parameters with appropriate warnings.

See also: PGetSingleHistoRunBlockDialog For the single histogram run block dialog

Starts the msr-single-historgram-run input dialog window.

Definition at line 489 of file PSubTextEdit.cpp.

◆ insertStatisticBlock

void PSubTextEdit::insertStatisticBlock ( )

slot

Slot: Inserts a default STATISTIC block.

Inserts a STATISTIC block template with placeholder values for fit results. The block includes:

Current timestamp
Placeholder for chi-square value
Placeholder for NDF (number of degrees of freedom)
Placeholder for chi-square/NDF ratio

After fitting, musrfit will update these placeholders with actual values.

Inserts a STATISTIC block template with the current timestamp and placeholder values for fit results. After fitting, musrfit updates these placeholders with actual fit statistics.

Inserted Content:

###############################################################
STATISTIC --- 2025-01-15 14:23:45
chisq = ????, NDF = ????, chisq/NDF = ????

Block Components:

Separator line: Visual delimiter (63 # characters)
STATISTIC keyword: Identifies the block type
Timestamp: Current date and time in "yyyy-MM-dd hh:mm:ss" format
Placeholder line: Template for fit quality metrics

Placeholder Values:

chisq: Chi-square value measuring fit quality (lower is better)
NDF: Number of degrees of freedom (data points - parameters)
chisq/NDF: Normalized chi-square (should be ~1 for good fit)

Fit Quality Interpretation:

chisq/NDF ≈ 1: Good fit, data matches theory within errors
chisq/NDF << 1: Overestimated errors or over-fitting
chisq/NDF >> 1: Underestimated errors or poor model

Usage Workflow:

User inserts STATISTIC block template (this method)
User completes msr file with other required blocks
User runs musrfit on the msr file
musrfit replaces "????" with actual values
User reviews fit statistics to assess quality

Timestamp Purpose: The timestamp records when the fit was performed, useful for:

Tracking fit history and iterations
Documenting analysis workflow
Identifying most recent results
Version control and reproducibility

Multiple STATISTIC Blocks: Users can have multiple STATISTIC blocks to record fit history:

Initial fit with default parameters
After parameter adjustments
After fixing certain parameters
Final publication-quality fit

Note: The timestamp reflects insertion time, not fit time. musrfit updates the timestamp when it updates fit statistics.; Placeholder "????" clearly indicates values not yet computed.; Double newline provides separation from subsequent content.; Insertion is undoable via Edit → Undo.

See also: QDateTime::currentDateTime() For timestamp generation; musrfit For the fitting application that updates placeholders

Definition at line 809 of file PSubTextEdit.cpp.

◆ insertTheoryBlock

void PSubTextEdit::insertTheoryBlock ( )

slot

Slot: Inserts a THEORY block via dialog.

Launches PGetTheoryBlockDialog which provides an interactive interface for building complex theory blocks by combining multiple theory functions with addition and multiplication operators.

See also: PGetTheoryBlockDialog For the theory block dialog

Starts the msr-theory input dialog window.

Definition at line 348 of file PSubTextEdit.cpp.

◆ insertTheoryFunction

void PSubTextEdit::insertTheoryFunction ( QString name )

slot

Slot: Inserts a specific theory function.

Inserts a single theory function line based on the given function name. The function is looked up in the PAdmin theory function registry and formatted with placeholder parameter numbers.

Parameters

name	Label of the theory function to insert (e.g., "simpleGss", "asymmetry", "userFcn").

Note: This is typically called from a menu action triggered by the user selecting a specific theory function.

See also: PAdmin::getTheoryItem() For theory function definitions

Looks up the specified theory function by name in the PAdmin theory registry, formats it with placeholder parameters, and inserts it at the current cursor position.

Function Lookup Process:

Search PAdmin theory registry for function matching given label
If not found, silently return (no insertion)
If found, retrieve PTheory definition
Format function line with name, parameters, and comment

Formatted Output: Standard functions:

functionName 1 2 3 (comment describing parameters)

User-defined functions (userFcn):

userFcn libMyLibrary.so TMyFunction 1 2 (parameters)

Parameter Placeholders: Numbers (1, 2, 3, ...) are placeholder parameter indices that users must replace with actual FITPARAMETER references or map variables before the msr file can be used for fitting.

User Function Special Handling: The "userFcn" theory function requires library and function names, so placeholder values "libMyLibrary.so" and "TMyFunction" are inserted for the user to replace with actual names.

Insertion Behavior:

Text inserted at current cursor position
Trailing newline for proper block separation
Existing text unaffected
Operation is undoable

Parameters

name	Label of the theory function to insert. Must match a label in the PAdmin theory registry (e.g., "simpleGss", "asymmetry", "cosPol", "userFcn").

Note: If name not found in registry, method returns silently without error message or user feedback.; Parameter numbers start at 1 (not 0) to match musrfit conventions.; The comment from PTheory provides parameter descriptions to guide users in understanding what each parameter represents.

See also: PAdmin::getTheoryItem() For retrieving theory function definitions; PTheory For theory function structure definition; insertTheoryBlock() For interactive theory block building

Definition at line 305 of file PSubTextEdit.cpp.

◆ insertTitle

void PSubTextEdit::insertTitle ( )

slot

Slot: Inserts a title block via dialog.

Launches PGetTitleBlockDialog for entering or editing the optional msr file title. If accepted, inserts the title text at the current cursor position.

See also: PGetTitleBlockDialog For the title input dialog

Launches PGetTitleBlockDialog to gather title input from the user. If the dialog is accepted, inserts the entered title at the current cursor position with a trailing newline.

Dialog Workflow:

Create PGetTitleBlockDialog with help URL from PAdmin
Display dialog modally (blocks until user responds)
If user accepts: retrieve title and insert into text editor
If user cancels: perform no action

Insertion Behavior:

Text is inserted at current cursor position
Trailing newline separates title from subsequent blocks
Existing text is not affected
Insertion is undoable via Edit → Undo

Help Integration: The dialog receives a help URL retrieved from PAdmin using the "title" key. This provides context-sensitive documentation about title block format and best practices.

Note: Uses std::unique_ptr for automatic dialog cleanup.; Null check on dialog pointer is defensive programming; in normal operation, make_unique should not return nullptr.; The comment about hard-coded URLs is outdated; URLs are retrieved from PAdmin configuration.

See also: PGetTitleBlockDialog For the title input dialog implementation; PAdmin::getHelpUrl() For help URL retrieval; insertPlainText() Qt method for text insertion

Definition at line 219 of file PSubTextEdit.cpp.

Member Data Documentation

◆ fAdmin

PAdmin* PSubTextEdit::fAdmin

private

Pointer to administration object with theory functions, help URLs, and configuration.

Definition at line 333 of file PSubTextEdit.h.

The documentation for this class was generated from the following files:

/workspace/LMU/musrfit/src/musredit_qt6/musredit/PSubTextEdit.h
/workspace/LMU/musrfit/src/musredit_qt6/musredit/PSubTextEdit.cpp

Public Slots

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PSubTextEdit()

◆ ~PSubTextEdit()

Member Function Documentation

◆ getFitType()

◆ insertAsymRunBlock

◆ insertCommandBlock

◆ insertFourierBlock

◆ insertFunctionBlock

◆ insertNonMusrRunBlock

◆ insertParameterBlock

◆ insertPlotBlock

◆ insertSingleHistRunBlock

◆ insertStatisticBlock

◆ insertTheoryBlock

◆ insertTheoryFunction

◆ insertTitle

Member Data Documentation

◆ fAdmin