Energy Functions
Spectral component functions for energy-resolved spectroscopy.
Function Conventions
Use CamelCase naming (UpperCamelCase or lowerCamelCase) for function names.
Peak Functions: Signature: func(x, par1, par2, …) - x: Energy axis (numpy array) - par1, par2, …: Function-specific parameters - Returns: Spectrum as numpy array (same shape as x)
Background Functions: Signature: func(x, par, spectrum) - x: Energy axis (numpy array) - par: Background parameter(s) - spectrum: Current peak sum (numpy array, for backgrounds that depend on peaks) - Returns: Background spectrum as numpy array (same shape as x)
Parameter Naming: - Use descriptive names without underscores: A, x0, SD, W, F, m, alpha - A: Amplitude (maximum value of function) - x0: Peak center/position - SD: Standard deviation (Gaussian width) - W: FWHM (Full Width at Half Maximum) - F: Width parameter (pseudo-Voigt approximations) - m: Mixing parameter (Gaussian-Lorentzian balance) - alpha: Asymmetry parameter (Doniach-Sunjic)
Implementation Notes
Amplitude vs Area: All functions currently use amplitude normalization (peak height = A). Future versions may add area normalization options. SD2FWHM = 2*np.sqrt(2*np.log(2))
Adding New Functions
To add a new peak or background function:
Implement function following conventions above
Add to config/functions.py if it’s a background
Test with realistic spectroscopy parameters
- trspecfit.functions.energy.DS(x: ndarray, A: float, x0: float, F: float, alpha: float) ndarray[source]
Doniach-Sunjic lineshape for metallic systems.
- Parameters:
x (ndarray) – Energy axis
A (float) – Amplitude scaling factor (note: NOT the maximum value due to asymmetry)
x0 (float) – Peak position (approximately the maximum, depends on alpha)
F (float) – Width parameter (related to FWHM, but complex due to asymmetry)
alpha (float) – Asymmetry parameter (singularity index): - alpha = 0: Lorentzian (no asymmetry) - 0 < alpha < 0.3: Typical for metals (e.g., Al: 0.10-0.15) - Larger alpha: Stronger asymmetry, more pronounced tail - Range: typically 0-0.5 for physical systems
- Returns:
Doniach-Sunjic lineshape
- Return type:
ndarray
- trspecfit.functions.energy.GLP(x: ndarray, A: float, x0: float, F: float, m: float) ndarray[source]
Gaussian-Lorentzian Product (pseudo-Voigt) approximation.
- Parameters:
x (ndarray) – Energy axis
A (float) – Peak amplitude (maximum value)
x0 (float) – Peak center position
F (float) – Peak width parameter (related to FWHM)
m (float) – Mixing parameter controlling Gaussian/Lorentzian character: - m = 0: Pure Gaussian - m = 1: Pure Lorentzian - 0 < m < 1: Hybrid shape Typical value: m ≈ 0.3
- Returns:
Pseudo-Voigt profile (product form)
- Return type:
ndarray
- trspecfit.functions.energy.GLS(x: ndarray, A: float, x0: float, F: float, m: float) ndarray[source]
Gaussian-Lorentzian Sum (pseudo-Voigt) approximation.
- Parameters:
x (ndarray) – Energy axis
A (float) – Peak amplitude (maximum value)
x0 (float) – Peak center position
F (float) – Peak width parameter (related to FWHM)
m (float) – Mixing parameter controlling Gaussian/Lorentzian balance: - m = 0: Pure Gaussian - m = 1: Pure Lorentzian - 0 < m < 1: Weighted mixture Typical value: m ≈ 0.3
- Returns:
Pseudo-Voigt profile (sum form)
- Return type:
ndarray
- trspecfit.functions.energy.Gauss(x: ndarray, A: float, x0: float, SD: float) ndarray[source]
Gaussian (normal) distribution peak.
- Parameters:
- Returns:
Gaussian peak spectrum
- Return type:
ndarray
- trspecfit.functions.energy.GaussAsym(x: ndarray, A: float, x0: float, SD: float, ratio: float) ndarray[source]
Asymmetric Gaussian peak with different widths on each side.
- Parameters:
x (ndarray) – Energy axis
A (float) – Peak amplitude (maximum value at x0)
x0 (float) – Peak center position (energy at maximum)
SD (float) – Standard deviation for x < x0 (low energy side)
ratio (float) – Width ratio: SD2/SD1, where SD2 is width for x >= x0. - ratio = 1: Symmetric Gaussian - ratio < 1: Narrower on high energy side - ratio > 1: Broader on high energy side
- Returns:
Asymmetric Gaussian peak spectrum
- Return type:
ndarray
- trspecfit.functions.energy.LinBack(x: ndarray, m: float, b: float, xStart: float, xStop: float, spectrum: ndarray | None = None) ndarray[source]
Clamped linear background.
Linear between xStart and xStop, constant outside that range. Works for both inclining and declining energy axes — xStart and xStop refer to energy values (xStart < xStop required).
- Parameters:
x (ndarray) – Energy axis.
m (float) – Slope (intensity per energy unit).
b (float) – Y-value at xStart (intercept).
xStart (float) – Left boundary of linear region (energy units, must be < xStop).
xStop (float) – Right boundary of linear region (energy units, must be > xStart).
spectrum (ndarray or None, optional) – Current peak sum (unused; accepted for background calling convention).
- Returns:
Background: linear between xStart and xStop, clamped constant outside.
- Return type:
ndarray
- Raises:
ValueError – If any xStart >= xStop (scalar or array).
- trspecfit.functions.energy.Lorentz(x: ndarray, A: float, x0: float, W: float) ndarray[source]
Lorentzian (Cauchy) distribution peak.
- trspecfit.functions.energy.Offset(x: ndarray, y0: float, spectrum: ndarray | None = None) ndarray[source]
Constant offset background.
- Parameters:
x (ndarray) – Energy axis. Shape determines output shape via broadcasting.
y0 (float) – Offset value (constant intensity level).
spectrum (ndarray or None, optional) – Current peak sum (unused; accepted for background calling convention).
- Returns:
Constant array matching the shape of x with value y0.
- Return type:
ndarray
- trspecfit.functions.energy.Shirley(x: ndarray, pShirley: float, spectrum: ndarray) ndarray[source]
Shirley background for inelastic electron scattering.
- Parameters:
x (ndarray) – Energy axis (not used in calculation, but required for signature).
pShirley (float) – Shirley scaling factor. Controls the strength of the background relative to peak area. Typical values are on the order of 1E-4.
spectrum (ndarray) – Current peak sum. The Shirley background is computed as cumulative integral of this spectrum along the last (energy) axis. Must have increasing kinetic energy (or decreasing binding energy) direction.
- Returns:
Shirley background spectrum (same shape as spectrum). Works for both 1D
(n_energy,)and 2D(n_time, n_energy).- Return type:
ndarray