erlab.analysis.fit.functions

Various functions used in fitting.

Modules

dynamic	Class-based dynamic functions for fitting.
general	Some general functions and utilities used in fitting.

Functions

active_shirley(x, peaks, k_steps, *[, ...])	Evaluate a Shirley-like background from the intensity of the peaks.
bcs_gap(x[, a, b, tc])	Interpolation formula for temperature dependent BCS-like gap magnitude.
do_convolve(x, func, resolution[, pad, ...])	Convolves func with gaussian of FWHM resolution in x.
do_convolve_2d(x, y, func, resolution[, pad])	Convolve a two-dimensional model along its first coordinate.
dynes(x[, n0, gamma, delta])	Dynes formula for superconducting density of states.
fermi_dirac(x, center, temp)	Fermi-dirac distribution.
fermi_dirac_broad(x, center, temp, resolution)	Resolution-broadened Fermi edge.
fermi_dirac_linbkg(x, center, temp, back0, ...)	Fermi-dirac edge with linear backgrounds above and below the Fermi level.
fermi_dirac_linbkg_broad(x, center, temp, ...)	Resolution-broadened Fermi edge with linear backgrounds.
gaussian(x, center, sigma, amplitude)	Gaussian parametrized with standard deviation and amplitude.
gaussian_wh(x[, center, width, height])	Gaussian parametrized with FWHM and peak height.
lorentzian(x, center, gamma, amplitude)	Lorentzian parametrized with HWHM and amplitude.
lorentzian_wh(x[, center, width, height])	Lorentzian parametrized with FWHM and peak height.
sc_self_energy(x[, gamma1, gamma0, delta])	General phenomenological self-energy for superconductors.
sc_spectral_function(x[, amp, gamma1, ...])	Resolution-broadened superconducting spectral function.
step_broad(x[, center, sigma, amplitude])	Step function convolved with a Gaussian.
step_linbkg_broad(x, center, sigma, back0, ...)	Resolution broadened step function with linear backgrounds.
tll(x[, amp, center, alpha, temp, ...])	Resolution-broadened Tomonaga-Luttinger liquid (TLL) spectral function.
voigt(x[, center, sigma, gamma, amplitude])	Voigt profile.

Classes

FermiEdge2dFunction([degree])	Polynomial Fermi edge with a linear intensity background.
MultiPeakFunction(npeaks[, peak_shapes, fd, ...])	Multiple peaks with optional Fermi-Dirac distribution and background.
PolynomialFunction([degree])	A callable class for an arbitrary degree polynomial.

class erlab.analysis.fit.functions.FermiEdge2dFunction(degree=1)

Bases: DynamicFunction

Polynomial Fermi edge with a linear intensity background.

The edge position is

\[E_F(\alpha) = \sum_{i=0}^{n} c_i \alpha^i,\]

where degree is \(n\). A Gaussian convolution is applied along eV.

Parameters:

degree (int, default: 1) – Degree of the polynomial that describes the edge position as a function of alpha.

Notes

eV, \(E_F\), and resolution are in eV. alpha is in degrees, temp is in K, and resolution is the Gaussian FWHM. Coefficient c{i} has units of eV per degree raised to i. const_bkg and offset have the units of the returned intensity. lin_bkg has intensity per eV units.

Calling the function with separate NumPy coordinates returns a flattened array in (eV, alpha) order. If both coordinates are xarray.DataArray objects, the result has their broadcast dimensions and coordinates. If only one coordinate is a DataArray, the result is a NumPy array. The Gaussian convolution delegates to do_convolve_2d().

property argnames: list[str]

property kwargs: list[tuple[str, float]]

pre_call(eV, alpha, **params)

class erlab.analysis.fit.functions.MultiPeakFunction(npeaks, peak_shapes=None, *, fd=True, background='linear', degree=2, convolve=True, oversample=3, segmented=False)

Bases: DynamicFunction

Multiple peaks with optional Fermi-Dirac distribution and background.

Parameters:

• npeaks (int) – The number of peaks to fit.

• peak_shapes (list[str] | str | None, default: None) – The shape(s) of the peaks in the model. If a list of strings is provided, each string represents the shape of a peak. If a single string is provided, it will be split by spaces to create a list of peak shapes. Supported shapes are "lorentzian", "gaussian", and "voigt", together with their documented aliases. If omitted, all peaks are Lorentzian.

• fd (bool, default: True) – Whether to multiply the peaks and background by a Fermi-Dirac distribution. This adds efermi in the units of x, temp in K, and offset in the units of the dependent data. When this option is enabled, x and efermi must be in eV.

• background (Literal['constant', 'linear', 'polynomial', 'none', 'shirley'], default: 'linear') –

  The type of background to include in the model. Possible values are:

  Value	Additional parameters
  ’none’	None
  ’constant’	const_bkg
  ’linear’	lin_bkg, const_bkg
  ’polynomial’	c0, c1, … depending on degree
  ’shirley’	const_bkg, lin_bkg, k_slope, and k_step_i with i from 0 to npeaks - 1

  Note

  The ‘shirley’ background is calculated by erlab.analysis.fit.functions.general.active_shirley() See its documentation for details about the parameters.

• degree (int, default: 2) – The degree of the polynomial background. Only used if background is 'polynomial'. Default is 2.

• convolve (bool, default: True) – Whether to convolve the complete model with a Gaussian kernel. If True, the model includes resolution, the Gaussian FWHM in the units of x.

• oversample (int, default: 3) – Factor by which to oversample x during convolution to reduce numerical artifacts.

• segmented (bool, default: False) – Whether to convolve the model in contiguous uniformly spaced segments. Use True when x contains large gaps or discontinuities.

Notes

Peak parameters use the prefix p{i}_, where i starts at zero. All peak positions and widths use the units of x.

• Gaussian and Lorentzian peaks use center, width, and height. width is the FWHM and height is the intensity at center. The corresponding sigma or gamma and amplitude parameters are derived.

• Voigt peaks use center, sigma, gamma, and amplitude. sigma is the Gaussian standard deviation, gamma is the Lorentzian HWHM, and amplitude is the integrated peak area. width and height are derived.

Background parameter units follow from the dependent data and x. For example, const_bkg has intensity units and lin_bkg has intensity per unit of x.

DEFAULT_PEAK: str = 'lorentzian'

PEAK_SHAPES: ClassVar[dict[Callable, list[str]]] = {<function gaussian_wh>: ['gaussian', 'gauss', 'g'], <function lorentzian_wh>: ['lorentzian', 'lor', 'l'], <function voigt>: ['voigt', 'v']}

Mapping of peak functions to their string aliases.

property argnames: list[str]

eval_bkg(x, **params)

eval_bkg_components(x, **params)

eval_fd(x, **params)

eval_peak(index, x, **params)

eval_peaks(x, **params)

Get a list of peak contributions.

property kwargs: list[tuple[str, float]]

property peak_all_args: dict[Callable, PeakArgs]

property peak_argnames: dict[Callable, list[str]]

property peak_funcs: Sequence[Callable]

peak_param_hints(index, prefix)

pre_call(x, **params)

class erlab.analysis.fit.functions.PolynomialFunction(degree=1)

Bases: DynamicFunction

A callable class for an arbitrary degree polynomial.

Parameters:

degree (int, default: 1) – The degree of the polynomial.

property argnames: list[str]

property kwargs: list[tuple[str, float]]

erlab.analysis.fit.functions.active_shirley(x, peaks, k_steps, *, k_slope=0.0, lin_bkg=0.0, const_bkg=0.0)

Evaluate a Shirley-like background from the intensity of the peaks.

The model function is a Shirley-Végh-Salvi-Castle type background [Shirley, 1972, Végh, 1988, Salvi and Castle, 1998, Herrera-Gomez et al., 2014] together with a slope background [Herrera-Gomez et al., 2013] and a linear baseline. For more information about the model function, see Herrera-Gomez et al. [2014].

This function is intended for “active” fitting where the background is computed from individual peak components during the fitting process, so that the background updates as the peak parameters change.

The returned background is given by:

\[B(x) = \underbrace{c + m x}_{\text{baseline}} + \sum_i \underbrace{k_{\mathrm{step},\,i}\int_x^{x_{\mathrm{right}}} P_i(x')\,dx'}_{\text{step}} + \underbrace{k_{\mathrm{slope}}\int_x^{x_{\mathrm{right}}} \left(\int_{x'}^{x_{\mathrm{right}}} \sum_i P_i(t)\,dt\right)\,dx'}_{\text{slope}}\]

Parameters:

• x (array-like) – 1D coordinate array. Must be strictly monotonic (increasing or decreasing). Nonuniform spacing is allowed, but not tested extensively.

• peaks (list of array-like) – List of individual peak component arrays \(P_i(x)\), each 1D with the same shape as x.

• k_steps (Sequence[float]) – Per-peak scattering factors for each peak component. Must have the same length as peaks.

• k_slope (float, default: 0.0) – Scale factor for the slope-background.

• lin_bkg (float, default: 0.0) – Linear baseline slope \(m\).

• const_bkg (float, default: 0.0) – Constant baseline offset \(c\).

Returns:

background (dict) –

Dictionary with the following keys and values:

• "baseline": The linear baseline component.

• "shirley": The Shirley background component (if any k_steps are nonzero).

• "slope": The slope background component (if k_slope is nonzero).

Return type:

dict[str, ndarray[tuple[Any, …], dtype[_ScalarT]]]

Notes

• The integration endpoint, or right side, is always x[-1] (input order).

erlab.analysis.fit.functions.bcs_gap(x, a=1.76, b=1.74, tc=100.0)

Interpolation formula for temperature dependent BCS-like gap magnitude.

\[\Delta(T) \simeq a \cdot k_B T_c \cdot \tanh\left(b \sqrt{\frac{T_c}{T} - 1}\right)\]

Parameters:

• x (array-like) – The temperature values in kelvins at which to calculate the BCS gap.

• a (float, default: 1.76) – Proportionality constant. Default is 1.76.

• b (float, default: 1.74) – Proportionality constant. Default is 1.74.

• tc (float, default: 100.0) – The critical temperature in Kelvins. Default is 100.0.

erlab.analysis.fit.functions.do_convolve(x, func, resolution, pad=7, oversample=3, **kwargs)

Convolves func with gaussian of FWHM resolution in x.

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]]) – An evenly spaced 1D array specifying where to evaluate the convolution.

• func (Callable) – Function to convolve.

• resolution (float) – FWHM of the gaussian kernel.

• pad (int, default: 7) – Multiples of the standard deviation \(\sigma\) to pad with.

• oversample (int, default: 3) – Factor by which to oversample x for convolution to reduce numerical artifacts.

• **kwargs – Additional keyword arguments to func.

erlab.analysis.fit.functions.do_convolve_2d(x, y, func, resolution, pad=5, **kwargs)

Convolve a two-dimensional model along its first coordinate.

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]]) – Uniformly spaced values of the convolution coordinate. Supply either a one-dimensional coordinate or the flattened x output from a rectangular mesh grid. At least two values are required.

• y (ndarray[tuple[Any, ...], dtype[float64]] | float) – Values of the second independent variable. Supply a scalar, a one-dimensional coordinate, or the flattened y output that matches a flattened mesh grid in x.

• func (Callable) – Model callable with the signature func(x, y, **kwargs). It must return one value for each supplied x value.

• resolution (float) – FWHM of the Gaussian kernel in the units of x.

• pad (int, default: 5) – Number of Gaussian standard deviations added to each end of x before the model is evaluated.

• **kwargs – Additional keyword arguments passed to func.

Returns:

numpy.ndarray – Convolved model values. Separate one-dimensional coordinates produce an array with shape (x.size, y.size). Matching flattened mesh-grid coordinates produce a flattened array in the same traversal order as the mesh grid.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

Notes

The convolution is applied only along x. The function evaluates and convolves the model independently for each value of y.

erlab.analysis.fit.functions.dynes(x, n0=1.0, gamma=0.003, delta=0.01)

Dynes formula for superconducting density of states.

The formula is given by [Dynes et al., 1978]:

\[N_0 \text{Re}\left[\frac{|x| + i \Gamma}{\sqrt{(|x| + i \Gamma)^2 - \Delta^2}}\right]\]

where \(x\) is the binding energy, \(N_0\) is the normal-state density of states at the Fermi level, \(\Gamma\) is the broadening term, and \(\Delta\) is the superconducting energy gap.

Parameters:

• x (array-like) – The input array of energy in eV.

• n0 (default: 1.0) – \(N_0\), by default 1.0.

• gamma (default: 0.003) – \(\Gamma\), by default 0.003.

• delta (default: 0.01) – The superconducting energy gap \(\Delta\), by default 0.01.

erlab.analysis.fit.functions.fermi_dirac(x, center, temp)

Fermi-dirac distribution.

\[f(x) = \frac{1}{1 + e^{(x-x_0)/k_B T}}\]

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]]) – Energy values at which to calculate the Fermi edge.

• center (float) – The Fermi level.

• temp (float) – The temperature in K.

erlab.analysis.fit.functions.fermi_dirac_broad(x, center, temp, resolution)

Resolution-broadened Fermi edge.

The Fermi edge is calculated as:

\[\frac{1}{1 + e^{(x-x_0)/k_B T}} \otimes \text{g}(\sigma)\]

where \(\text{g}(\sigma)\) is a Gaussian kernel with standard deviation \(\sigma\). Note that the resolution is given in FWHM rather than the standard deviation.

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]] | DataArray) – The energy values at which to calculate the Fermi edge.

• center (float | DataArray) – The Fermi level.

• temp (float | DataArray) – The temperature in K.

• resolution (float | DataArray) – The resolution of the Gaussian kernel in eV. Note that this is the FWHM of the Gaussian kernel, not the standard deviation.

erlab.analysis.fit.functions.fermi_dirac_linbkg(x, center, temp, back0, back1, dos0, dos1)

Fermi-dirac edge with linear backgrounds above and below the Fermi level.

\[I(x) = b_0 + b_1 x + \frac{d_0 - b_0 + (d_1 - b_1) x} {1 + e^{(x-x_0)/k_B T}}\]

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]]) – The energy values at which to calculate the Fermi edge.

• center (float) – The Fermi level.

• temp (float) – The temperature in K.

• back0 (float) – The constant background above the Fermi level.

• back1 (float) – The slope of the background above the Fermi level.

• dos0 (float) – The constant background below the Fermi level.

• dos1 (float) – The slope of the background below the Fermi level.

Note

back0 and back1 corresponds to the linear background above and below EF (due to non-homogeneous detector efficiency or residual intensity on the phosphor screen during swept measurements), while dos0 and dos1 corresponds to the linear density of states below EF including the linear background.

erlab.analysis.fit.functions.fermi_dirac_linbkg_broad(x, center, temp, resolution, back0, back1, dos0, dos1)

Resolution-broadened Fermi edge with linear backgrounds.

\[I(x) = \left[ b_0 + b_1 x + \frac{d_0 - b_0 + (d_1 - b_1) x} {1 + e^{(x-x_0)/k_B T}} \right] \otimes \text{g}(\sigma)\]

erlab.analysis.fit.functions.gaussian(x, center, sigma, amplitude)

Gaussian parametrized with standard deviation and amplitude.

\[G(x) = \frac{A}{\sqrt{2\pi\sigma^2}} \exp\left[-\frac{(x-x_0)^2}{2\sigma^2}\right]\]

erlab.analysis.fit.functions.gaussian_wh(x, center=0.0, width=1.0, height=1.0)

Gaussian parametrized with FWHM and peak height.

\[G(x) = h \exp\left[-\frac{16 \log{2} (x-x_0)^2}{w^2}\right]\]

Note

\(\sigma=\frac{w}{2\sqrt{2\log{2}}}\)

erlab.analysis.fit.functions.lorentzian(x, center, gamma, amplitude)

Lorentzian parametrized with HWHM and amplitude.

\[L(x) = \frac{A}{\pi\gamma\left[1 + \left(\frac{x-x_0}{\gamma}\right)^2\right]}\]

erlab.analysis.fit.functions.lorentzian_wh(x, center=0.0, width=1.0, height=1.0)

Lorentzian parametrized with FWHM and peak height.

\[L(x) = \frac{h}{1 + 4\left(\frac{x-x_0}{w}\right)^2}\]

Note

\(\gamma=w/2\)

erlab.analysis.fit.functions.sc_self_energy(x, gamma1=1e-05, gamma0=0.0, delta=0.0)

General phenomenological self-energy for superconductors.

The function is given by [Norman et al., 1998]:

\[\Sigma(x) = -i \Gamma_1 + \frac{\Delta^2}{x + i \Gamma_0}\]

where \(\Gamma_1\) is the single-particle scattering rate, \(\Gamma_0\) is the pair-breaking rate, and \(\Delta\) is the energy gap.

Parameters:

• x (array-like) – The input array of energy in eV.

• gamma1 (default: 1e-05) – \(\Gamma_1\), the single-particle scattering rate.

• gamma0 (default: 0.0) – \(\Gamma_0\), the pair-breaking scattering rate.

• delta (default: 0.0) – The energy gap \(\Delta\).

erlab.analysis.fit.functions.sc_spectral_function(x, amp=1.0, gamma1=1e-05, gamma0=0.0, delta=0.0, lin_bkg=0.0, const_bkg=0.0, resolution=0.01)

Resolution-broadened superconducting spectral function.

The superconducting spectral function with a linear background is calculated as:

\[I(x) = \left[ A \cdot A_{sc}(x, \Sigma) + \left(m \cdot |x| + b \right) \right] \otimes \text{g}(\sigma)\]

where \(A_{sc}(x, \Sigma)\) is the superconducting spectral function calculated using the self-energy \(\Sigma(x)\) given by sc_self_energy(). \(\text{g}(\sigma)\) is a Gaussian kernel with standard deviation \(\sigma\). Note that the resolution parameter is the FWHM of the Gaussian kernel, not the standard deviation.

Parameters:

• x (array-like) – The input array of energy in eV.

• amp (float | DataArray, default: 1.0) – The overall scale factor \(A\).

• gamma1 (float | DataArray, default: 1e-05) – \(\Gamma_1\), the single-particle scattering rate.

• gamma0 (float | DataArray, default: 0.0) – \(\Gamma_0\), the pair-breaking scattering rate.

• delta (float | DataArray, default: 0.0) – The energy gap \(\Delta\).

• lin_bkg (float | DataArray, default: 0.0) – The slope of the linear background \(m\).

• const_bkg (float | DataArray, default: 0.0) – The constant background \(b\).

• resolution (float | DataArray, default: 0.01) – The broadening in eV. Note that this is the FWHM of the Gaussian kernel, not the standard deviation.

erlab.analysis.fit.functions.step_broad(x, center=0.0, sigma=1.0, amplitude=1.0)

Step function convolved with a Gaussian.

The broadened step function is calculated as:

\[\frac{A}{2}\cdot\text{erfc}\left(\frac{x - x_0}{\sqrt{2\sigma^2}}\right)\]

where \(\text{erfc}\) is the complementary error function.

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]]) – The input array of x values.

• center (float, default: 0.0) – The center of the step function.

• sigma (float, default: 1.0) – The standard deviation of the Gaussian.

• amplitude (float, default: 1.0) – The amplitude of the step.

erlab.analysis.fit.functions.step_linbkg_broad(x, center, sigma, back0, back1, dos0, dos1)

Resolution broadened step function with linear backgrounds.

erlab.analysis.fit.functions.tll(x, amp=1.0, center=0.0, alpha=0.1, temp=10.0, resolution=0.01, const_bkg=0.0)

Resolution-broadened Tomonaga-Luttinger liquid (TLL) spectral function.

The TLL spectral function is calculated as [Ohtsubo et al., 2015]:

\[I(x,T) = \left[A T^\alpha \cosh\left(\frac{\epsilon}{2}\right) \left|\Gamma\left(\frac{1 + \alpha}{2} + i \frac{\epsilon}{2\pi}\right)\right|^2 f(\epsilon,T)\right] \otimes \text{g}(\sigma) + B\]

where \(\epsilon=(x - x_0)/k_B T\) is the temperature-normalized energy, \(\Gamma\) is the gamma function, \(f(\epsilon,T) = 1/(e^{\epsilon}+1)\) is the Fermi-Dirac distribution, \(\text{g}(\sigma)\) is a Gaussian kernel with standard deviation \(\sigma\), and \(B\) is a constant background.

Note that the resolution parameter is the FWHM of the Gaussian kernel, not the standard deviation.

Parameters:

• x (ndarray[tuple[Any, ...], dtype[float64]] | DataArray) – The energy values at which to calculate the TLL spectral function.

• amp (float | DataArray, default: 1.0) – The amplitude.

• center (float | DataArray, default: 0.0) – The center.

• alpha (float | DataArray, default: 0.1) – The power law exponent.

• temp (float | DataArray, default: 10.0) – The temperature in K.

• resolution (float | DataArray, default: 0.01) – The resolution of the Gaussian kernel in eV. Note that this is the FWHM of the Gaussian kernel, not the standard deviation.

• const_bkg (float | DataArray, default: 0.0) – A constant background to add to the broadened TLL function.

erlab.analysis.fit.functions.voigt(x, center=0.0, sigma=0.0, gamma=0.5, amplitude=1.0)

Voigt profile.

The Voigt profile can be expressed as:

\[V(x) = A \frac{\text{Re}[w(z)]}{\sigma \sqrt{2\pi}}, \quad z = \frac{x - x_0 + i \gamma}{\sigma \sqrt{2}}\]

where \(w(z)\) is the Faddeeva function. This implementation uses scipy.special.voigt_profile to compute the Voigt profile.