* Transitioned nappNorm, nappDetermineShift, and nappCopyShift to use modern MATLAB arguments blocks, removing their legacy functionSignatures.json entries.
* Refactored nappNorm to rely on prior peak fitting results (e.g., from nappFitGaussXps) for normalization rather than performing the fitting internally.
* Decoupled energy calibration: nappDetermineShift now solely calculates internal binding energy shifts, and nappCopyShift distributes them using a unified matching engine ('earlier', 'after', 'spectrumNumber').
* Implemented a Universal Logging Block to track data provenance, automatically appending execution timestamps and caller script names to processed rows.
* Updated nappCombineSpectra to output a logDataSource cell array and cleanly name combined spectra.
* Created nappSaveDataTable for automatic, script-named .mat file saving, complete with a Live Editor interceptor.
* Added a publish-mode silencer to nappFitGaussXps to prevent optimizer spam in generated PDFs.
* Updated readme.md to document the new arguments structure, the 3-step calibration workflow, the matching engine, and the new table variables.
This commit replaces the numerically unstable Shirley background calculation in the peak fitting routine with a continuous, analytical Pseudo-Voigt Cumulative Distribution Function (CDF).
Previously, the solver struggled to converge and pushed peak parameters (area, width) into their absolute bounds due to two critical mathematical bugs in the objective function:
1. The 'flip' and Energy Axis Mutation Bug:
To handle kinetic energy scales (where the background steps up as energy decreases), the code mutated the energy axis (E = max(E)+100-E) inside the peak loop and attempted to use array flipping. This approach fundamentally decoupled the background step from the physical peak position. Array flipping mirrors data based on the length of the plot window, physically moving the Shirley step away from the true peak center. Furthermore, mutating E inside the loop corrupted the X-axis for subsequent peaks in multi-peak fits.
2. The Integration Cutoff ('idxregion') Bug:
The prior implementation used a hard Boolean cutoff (idxregion = (E >= pos)) to restrict the background calculation to only one side of the peak. Because Pseudo-Voigt peaks have long tails, this created a severe mathematical discontinuity (a sharp cliff) exactly at the peak center. Non-linear optimization solvers require smooth, continuous gradients to step correctly. The sharp cutoff destroyed the gradient, causing the solver to panic and lock parameters against their constraints.
The Fix:
- Removed all 'flip()' calls and energy array mutations.
- Replaced the hard cutoff with a continuous analytical CDF evaluated over the entire energy range.
- Handled binding vs. kinetic energy directionality cleanly by toggling between 'integral_fraction' and '(1 - integral_fraction)'.
Result:
The non-linear solver now receives perfectly smooth, mathematically continuous gradients, leading to rapid convergence. Peak parameters no longer crash into their bounds, and the plotted red fit line now perfectly aligns with the internally calculated solver residuals.
BREAKING CHANGES:
- Single-spectrum fitting only (enforces exactly one row selected)
- Gauss fitting now uses FWHM parameter instead of Gaussian width sigma
- Removed multi-row batch processing capability
NEW FEATURES:
- Generic model architecture: arbitrary number of peaks (determined by length of FitParameter.peakArea)
- Full Shirley background support for both Gaussian and Pseudo-Voigt peak shapes
- Comprehensive parameter validation system with detailed error messages
- Support for shared vs per-peak Shirley K parameters
- New fitting modes: 'positionShirley', 'widthShirley', 'widthPositionShirley'
- New custom mode: 'TwoSpinOrbitDoubletPseudoVoigtShirley'
- Automatic field name typo correction ('Bond' → 'Bound')
- Enhanced results export: now includes peakEta and peakShirleyK columns
REFACTORING:
- Centralized peak and background equations in helper functions
- gaussPeak(), lorentzPeak(), pseudoVoigtPeak()
- linearBackground(), activeShirleyBackgroundFwhm()
- fwhm2w() conversion utility
- Extracted model generation to genericModelGenerator()
- Modular validation helpers: checkFieldDimension(), checkBoundsPair()
- Standardized parameter vector layouts documented for all mode/background/peak-type combinations
- Improved column resizing logic with resizeColumnHelper()
- Enhanced plotting integration with nappPlot.m and nappAddFitToPlot.m
ARCHITECTURE:
- Unified parameter extraction for all fitting modes in centralized switch-case structure
- Consistent FWHM-based width parameterization across all peak types
- Mode-specific Shirley K sizing (scalar for shared modes, array for per-peak modes)
- Comprehensive inline documentation of parameter vector layouts (50+ combinations)
IMPROVEMENTS:
- Backward compatibility for 'gauss' width mode (auto-converts to FWHM)
- Robust bounds checking with detailed diagnostic messages
- Enhanced figure generation: residuals plot + fit visualization in tiledlayout
- Better error handling for empty/malformed data structures
- NaN-padded result arrays for variable peak counts
FILE SIZE: ~73KB → ~152KB (107% increase due to comprehensive documentation and generic architecture)
bartels-rausch