xarpes 0.5.0__py3-none-any.whl → 0.6.1__py3-none-any.whl

xarpes/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.5.0"
+__version__ = "0.6.1"
 
 from importlib import import_module
 

xarpes/bandmap.py

@@ -14,28 +14,49 @@
 import numpy as np
 from igor2 import binarywave
 from .plotting import get_ax_fig_plt, add_fig_kwargs
-from .functions import fit_leastsq, extend_function
+from .functions import fit_least_squares, extend_function
 from .distributions import FermiDirac, Linear
 from .constants import PREF
 
 class BandMap:
     r"""
-    Class for the band map from the ARPES experiment.
+    Band map container for ARPES intensity data.
 
-    Construction
-    ------------
-    Prefer the alternate constructors:
+    Notes
+    -----
+    Prefer :meth:`from_ibw_file` or :meth:`from_np_arrays`. The ``__init__``
+    expects canonical arrays (no file I/O).
 
-    - BandMap._from_ibw_file(path, ...)
-    - BandMap._from_np_arrays(intensities=..., angles=..., ekin=... or enel=...)
-
-    The __init__ takes *canonical* arrays (no file I/O).
+    See Also
+    --------
+    BandMap.from_ibw_file
+    BandMap.from_np_arrays
     """
 
     @classmethod
     def from_ibw_file(cls, datafile, transpose=False, flip_ekin=False,
                        flip_angles=False, **kwargs):
-        r"""Construct BandMap from an IGOR binary wave (.ibw)."""
+        r"""
+        Construct a `BandMap` from an IGOR binary wave (.ibw).
+
+        Parameters
+        ----------
+        datafile : path-like
+            Path to the .ibw file.
+        transpose : bool, optional
+            If True, transpose the loaded intensity array and swap axes metadata.
+        flip_ekin : bool, optional
+            If True, reverse the kinetic-energy axis.
+        flip_angles : bool, optional
+            If True, reverse the angle axis.
+        **kwargs
+            Passed to `BandMap.__init__`.
+
+        Returns
+        -------
+        BandMap
+            New instance constructed from the file contents.
+        """
         data = binarywave.load(datafile)
         intensities = data['wave']['wData']
 
@@ -66,7 +87,27 @@ class BandMap:
     @classmethod
     def from_np_arrays(cls, intensities=None, angles=None, ekin=None, enel=None,
                         **kwargs):
-        r"""Construct BandMap from NumPy arrays."""
+        r"""
+        Construct a `BandMap` from NumPy arrays.
+
+        Exactly one of `ekin` or `enel` must be provided.
+
+        Parameters
+        ----------
+        intensities : array-like
+            Intensity map with shape (n_energy, n_angle).
+        angles : array-like
+            Angle axis values.
+        ekin, enel : array-like
+            Provide exactly one: kinetic energy (`ekin`) or binding energy (`enel`).
+        **kwargs
+            Passed to `BandMap.__init__`.
+
+        Returns
+        -------
+        BandMap
+            New instance constructed from the provided arrays.
+        """
         if intensities is None or angles is None:
             raise ValueError('Please provide intensities and angles.')
         if (ekin is None) == (enel is None):
@@ -273,23 +314,51 @@ class BandMap:
         
     def mdc_set(self, angle_min, angle_max, energy_value=None,
                 energy_range=None):
-        r"""Returns a set of MDCs. Documentation is to be further completed.
-        
+        r"""Return a set of momentum distribution curves (MDCs).
+
+        This method extracts MDCs from the stored ARPES intensity map from a
+        specified angular interval and either selecting a single energy slice
+        or an energy window.
+
         Parameters
         ----------
         angle_min : float
-            Minimum angle of integration interval [degrees]
+            Minimum angle of the integration interval [degrees].
         angle_max : float
-            Maximum angle of integration interval [degrees]
+            Maximum angle of the integration interval [degrees].
+        energy_value : float, optional
+            Energy value [same units as ``self.enel``] at which a single MDC
+            is extracted. Exactly one of ``energy_value`` or ``energy_range``
+            must be provided.
+        energy_range : array-like, optional
+            Energy interval [same units as ``self.enel``] over which MDCs are
+            extracted. Exactly one of ``energy_value`` or ``energy_range``
+            must be provided.
 
         Returns
         -------
-        angle_range : ndarray
-            Array of size n containing the angular values
-        energy_range : ndarray
-            Array of size m containing the energy values
         mdcs : ndarray
-            Array of size n x m containing the MDC intensities
+            Extracted MDC intensities. Shape is ``(n_angles,)`` when a single
+            ``energy_value`` is provided, or ``(n_energies, n_angles)`` when
+            an ``energy_range`` is provided.
+        angle_range : ndarray
+            Angular values corresponding to the MDCs [degrees].
+        angle_resolution : float
+            Angular resolution associated with the MDCs.
+        energy_resolution : float
+            Energy resolution associated with the MDCs.
+        temperature: float
+            Temperature associated with the band map [K].
+        energy_range : ndarray or float
+            Energy value (scalar) or energy array corresponding to the MDCs.
+        hnuminPhi : float
+            Photon-energy-related offset propagated from the BandMap.
+
+        Raises
+        ------
+        ValueError
+            If neither or both of ``energy_value`` and ``energy_range`` are
+            provided.
 
         """
 
@@ -316,8 +385,8 @@ class BandMap:
             mdcs = self.intensities[energy_indices,
                                     angle_min_index:angle_max_index + 1]
 
-        return mdcs, angle_range_out, self.angle_resolution, \
-        enel_range_out, self.hnuminPhi
+        return (mdcs, angle_range_out, self.angle_resolution, 
+                self.energy_resolution, self.temperature, enel_range_out, self.hnuminPhi)
 
     @add_fig_kwargs
     def plot(self, abscissa='momentum', ordinate='electron_energy',
@@ -677,9 +746,10 @@ class BandMap:
 
         extra_args = (self.temperature,)
 
-        popt, pcov = fit_leastsq(
-        parameters, energy_range, integrated_intensity, fdir_initial,
-        self.energy_resolution, None, *extra_args)
+        popt, pcov, success = fit_least_squares(
+            p0=parameters, xdata=energy_range, ydata=integrated_intensity,
+            function=fdir_initial, resolution=self.energy_resolution,
+            yerr=None, bounds=None, extra_args=extra_args)
 
         # Update hnuminPhi; automatically sets self.enel
         self.hnuminPhi = popt[0]
@@ -757,9 +827,8 @@ class BandMap:
         angle_range = self.angles[angle_min_index:angle_max_index + 1]
         energy_range = self.ekin[ekin_min_index:ekin_max_index + 1]
         
-        angle_shape = angle_range.shape
-        nmps = np.zeros(angle_shape)
-        stds = np.zeros(angle_shape)
+        nmps = np.zeros_like(angle_range, dtype=float)
+        stds = np.zeros_like(angle_range, dtype=float)
         
         hnuminPhi_left = hnuminPhi_guess - (true_angle - angle_min) \
         * slope_guess
@@ -778,9 +847,10 @@ class BandMap:
         for indx in range(angle_max_index - angle_min_index + 1):
             edge = Intensities[:, indx]
             
-            parameters, pcov = fit_leastsq(
-            parameters, energy_range, edge, fdir_initial,
-            self.energy_resolution, None, *extra_args)
+            parameters, pcov, success = fit_least_squares(
+                p0=parameters, xdata=energy_range, ydata=edge,
+                function=fdir_initial, resolution=self.energy_resolution,
+                yerr=None, bounds=None, extra_args=extra_args)
 
             nmps[indx] = parameters[0]
             stds[indx] = np.sqrt(np.diag(pcov)[0])
@@ -793,11 +863,12 @@ class BandMap:
         
         lin_fun = Linear(offset_guess, slope_guess, 'Linear')
                     
-        popt, pcov = fit_leastsq(parameters, angle_range, nmps, lin_fun, None,
-                                 stds)
+        popt, pcov, success = fit_least_squares(p0=parameters, xdata=angle_range, 
+                        ydata=nmps, function=lin_fun, resolution=None,
+                                 yerr=stds, bounds=None)
 
         linsp = lin_fun(angle_range, popt[0], popt[1])
-            
+
         # Update hnuminPhi; automatically sets self.enel
         self.hnuminPhi = lin_fun(true_angle, popt[0], popt[1])
         self.hnuminPhi_std = np.sqrt(true_angle**2 * pcov[1, 1] + pcov[0, 0] 

xarpes/functions.py

@@ -148,8 +148,8 @@ def extend_function(abscissa_range, abscissa_resolution):
     return extend, step, numb
 
 
-def error_function(p, xdata, ydata, function, resolution, yerr, extra_args):
-    r"""The error function used inside the fit_leastsq function.
+def error_function(p, xdata, ydata, function, resolution, yerr, *extra_args):
+    r"""The error function used inside the fit_least_squares function.
 
     Parameters
     ----------
@@ -187,66 +187,53 @@ def error_function(p, xdata, ydata, function, resolution, yerr, extra_args):
     return residual
 
 
-def fit_leastsq(p0, xdata, ydata, function, resolution=None,
-                yerr=None, *extra_args):
-    r"""Wrapper around scipy.optimize.leastsq.
+def fit_least_squares(p0, xdata, ydata, function, resolution=None, yerr=None,
+                      bounds=None, extra_args=None):
+    r"""Least-squares fit using `scipy.optimize.least_squares`.
 
-    Parameters
-    ----------
-    p0 : ndarray
-        Initial guess for parameters to be optimized.
-    xdata : ndarray
-        Abscissa values the function is evaluated on.
-    ydata : ndarray
-        Measured values to compare to.
-    function : callable
-        Function or class with __call__ method to evaluate.
-    resolution : float or None, optional
-        Convolution resolution (sigma), if applicable.
-    yerr : ndarray or None, optional
-        Standard deviations of ydata. Defaults to ones if None.
-    extra_args : tuple
-        Additional arguments passed to the function.
+    Default behavior is Levenberg–Marquardt (`method="lm"`) when unbounded.
+    If `bounds` is provided, switches to trust-region reflective (`"trf"`).
 
-    Returns
-    -------
-    pfit_leastsq : ndarray
-        Optimized parameters.
-    pcov : ndarray or float
-        Scaled covariance matrix of the optimized parameters.
-        If the covariance could not be estimated, returns np.inf.
+    Returns (pfit, pcov, success) in the same style as the old `leastsq`
+    wrapper, with an additional boolean `success` from SciPy.
     """
-    from scipy.optimize import leastsq
+    from scipy.optimize import least_squares
 
     if yerr is None:
         yerr = np.ones_like(ydata)
 
-    pfit, pcov, infodict, errmsg, success = leastsq(
-        error_function,
-        p0,
-        args=(xdata, ydata, function, resolution, yerr, extra_args),
-        full_output=1
-    )
+    if extra_args is None:
+        extra_args = ()
+
+    def _residuals(p):
+        return error_function(
+            p, xdata, ydata, function, resolution, yerr, *extra_args
+        )
 
-    if (len(ydata) > len(p0)) and pcov is not None:
-        s_sq = (
-            error_function(pfit, xdata, ydata, function, resolution,
-                           yerr, extra_args) ** 2
-        ).sum() / (len(ydata) - len(p0))
-        pcov *= s_sq
+    if bounds is None:
+        res = least_squares(_residuals, p0, method="lm")
     else:
-        pcov = np.inf
+        res = least_squares(_residuals, p0, method="trf", bounds=bounds)
 
-    return pfit, pcov
+    pfit = res.x
+    success = bool(getattr(res, "success", False))
 
+    m = len(ydata)
+    n = pfit.size
 
-def MEM_core():
-    r"""
-    Extracts the unscaled Eliashberg function for a given value of the Lagrange 
-    multiplier alpha. It also returns the reconstruction F.
-    In essence, this function applies the Newton method to solve 
-    """
-    return 0
+    if (m > n) and (res.jac is not None) and res.jac.size:
+        resid = res.fun
+        s_sq = (resid ** 2).sum() / (m - n)
+
+        try:
+            jtj = res.jac.T @ res.jac
+            pcov = np.linalg.inv(jtj) * s_sq
+        except np.linalg.LinAlgError:
+            pcov = np.inf
+    else:
+        pcov = np.inf
+
+    return pfit, pcov, success
 
 
 
@@ -400,4 +387,242 @@ def set_script_dir():
         # If __file__ isn't defined, fall back to current working directory
         script_dir = os.getcwd()
 
-    return script_dir
+    return script_dir
+
+
+def MEM_core(dvec, model_in, uvec, mu, alpha, wvec, V_Sigma, U,
+             t_criterion, iter_max):
+    r"""
+    Implementation of Bryan's algorithm (not to be confused with Bryan's
+    'method' for determining the Lagrange multiplier alpha. For details, see
+    Eur. Biophys. J. 18, 165 (1990).
+    """
+    import numpy as np
+    import warnings
+
+    spectrum_in = model_in * np.exp(U @ uvec)  # Eq. 9
+    alphamu = alpha + mu
+
+    converged = False
+    iter_count = 0
+    while not converged and iter_count < iter_max:
+
+        T = V_Sigma @ (U.T @ spectrum_in)  # Below Eq. 7
+        gvec = V_Sigma.T @ (wvec * (T - dvec))  # Eq. 10
+        M = V_Sigma.T @ (wvec[:, None] * V_Sigma)  # Above Eq. 11
+        K = U.T @ (spectrum_in[:, None] * U)  # Above Eq. 11
+
+        xi, P = np.linalg.eigh(K)  # Eq. 13
+        sqrt_xi = np.sqrt(xi)
+        P_sqrt_xi = P * sqrt_xi[None, :]
+        A = P_sqrt_xi.T @ (M @ P_sqrt_xi)  # Between Eqs. 13 and 14
+        Lambda, R = np.linalg.eigh(A)  # Eq. 14
+        Y_inv = R.T @ (sqrt_xi[:, None] * P.T)  # Below Eq. 15
+
+        # From Eq. 16:
+        Y_inv_du = -(Y_inv @ (alpha * uvec + gvec)) / (alphamu + Lambda)
+        d_uvec = (
+            -alpha * uvec - gvec - M @ (Y_inv.T @ Y_inv_du)
+        ) / alphamu  # Eq. 20
+
+        uvec += d_uvec
+        spectrum_in = model_in * np.exp(U @ uvec)  # Eq. 9
+
+        # Convergence block: Section 2.3
+        alpha_K_u = alpha * (K @ uvec)  # Skipping the minus sign twice
+        K_g = K @ gvec
+        tcon = (
+            2 * np.linalg.norm(alpha_K_u + K_g)**2
+            / (np.linalg.norm(alpha_K_u) + np.linalg.norm(K_g))**2
+        )
+        converged = (tcon < t_criterion)
+
+        iter_count += 1
+
+    if not converged:
+        with warnings.catch_warnings():
+            warnings.simplefilter("always", RuntimeWarning)
+            warnings.warn(
+                f"MEM_core did not converge within iter_max={iter_max} "
+                f"(performed {iter_count} iterations).",
+                category=RuntimeWarning,
+                stacklevel=2,
+            )
+
+    return spectrum_in, uvec
+
+
+def bose_einstein(omega, k_BT):
+    """Bose-Einstein distribution n_B(omega) for k_BT > 0 and omega >= 0."""
+    x_over = np.log(np.finfo(float).max)  # ~709.78 for float64
+
+    x = omega / k_BT
+
+    out = np.empty_like(omega, dtype=float)
+
+    momega0 = (omega == 0)
+    if np.any(momega0):
+        out[momega0] = np.inf
+
+    mpos_big = (x > x_over) & (omega != 0)
+    if np.any(mpos_big):
+        out[mpos_big] = 0.0
+
+    mnorm = (omega != 0) & ~mpos_big
+    if np.any(mnorm):
+        out[mnorm] = 1.0 / np.expm1(x[mnorm])
+
+    return out
+
+
+def fermi(omega, k_BT):
+    """Fermi-Dirac distribution f(omega) for k_BT > 0 and omega >= 0.
+    Could potentially be made a core block of the FermiDirac distribution."""
+    x_over = np.log(np.finfo(float).max)  # ~709.78 for float64
+
+    x = omega / k_BT
+    out = np.empty_like(omega, dtype=float)
+
+    mover = x > x_over
+    out[mover] = 0.0
+
+    mnorm = ~mover
+    y = np.exp(-x[mnorm])
+    out[mnorm] = y / (1.0 + y)
+
+    return out
+
+
+def create_kernel_function(enel, omega, k_BT):
+    r"""Kernel function. Eq. 17 from https://arxiv.org/abs/2508.13845.
+
+    Returns
+    -------
+    K : ndarray, complex
+        Shape (enel.size, omega.size) if enel and omega are 1D.
+    """
+    from scipy.special import digamma
+
+    enel = enel[:, None]     # (Ne, 1)
+    omega = omega[None, :]   # (1, Nw)
+
+    denom = 2.0 * np.pi * k_BT
+
+    K = (digamma(0.5 - 1j * (enel - omega) / denom)
+         - digamma(0.5 - 1j * (enel + omega) / denom)
+         - 2j * np.pi * (bose_einstein(omega, k_BT) + 0.5))
+
+    return K
+
+
+def singular_value_decomposition(kernel, sigma_svd):
+    r"""
+    Some papers use kernel = U Sigma V^T; we follow Bryan's algorithm.
+    """
+    V, Sigma, U_transpose = np.linalg.svd(kernel)
+    U = U_transpose.T
+    Sigma = Sigma[Sigma > sigma_svd]
+    s_reduced = Sigma.size
+    V = V[:, :s_reduced]
+    U = U[:, :s_reduced]
+    V_Sigma = V * Sigma[None, :]
+    
+    uvec = np.zeros(s_reduced)
+    
+    print('Dimensionality has been reduced from a matrix of rank ' + str(min(kernel.shape)) +
+          ' to ' + str(int(s_reduced)) + ' in the singular space.')
+          
+    return V_Sigma, U, uvec
+
+
+def create_model_function(omega, omega_I, omega_M, omega_S, h_n):
+    r"""Piecewise model m_n(omega) defined on the omega grid.
+
+    Implements the piecewise definition in the figure, interpreting
+    omega_min/max as omega.min()/omega.max().
+
+    Parameters
+    ----------
+    omega : ndarray
+        Frequency grid (assumed sorted, but only min/max are used).
+    omega_I : float
+        ω_n^I
+    omega_M : float
+        ω_n^M
+    omega_S : float
+        ω_n^S
+    h_n : float
+        h_n in the prefactor m_n(omega) = 2 h_n * ( ... ).
+
+    Returns
+    -------
+    model : ndarray
+        m_n(omega) evaluated on the omega grid.
+    """
+    w_min = omega.min()
+    w_max = omega.max()
+
+    if omega_I <= 0:
+        raise ValueError("omega_I must be > 0.")
+    denom = w_max + omega_S - omega_M
+    if denom == 0:
+        raise ValueError("omega_max + omega_S - omega_M must be nonzero.")
+
+    w_I_half = 0.5 * omega_I
+    w_mid = 0.5 * (w_max + omega_S + omega_M)
+
+    domains = np.empty_like(omega)
+
+    m1 = (omega >= w_min) & (omega < w_I_half)
+    domains[m1] = (omega[m1] / omega_I) ** 2
+
+    m2 = (omega >= w_I_half) & (omega < omega_I)
+    domains[m2] = 0.5 - (omega[m2] / omega_I - 1.0) ** 2
+
+    m3 = (omega >= omega_I) & (omega < omega_M)
+    domains[m3] = 0.5
+
+    m4 = (omega >= omega_M) & (omega < w_mid)
+    domains[m4] = 0.5 - ((omega[m4] - omega_M) / denom) ** 2
+
+    m5 = (omega >= w_mid) & (omega <= w_max)
+    domains[m5] = ((omega[m5] - omega_M) / denom - 1.0) ** 2
+
+    return 2.0 * h_n * domains
+
+
+def chi2kink_logistic(x, a, b, c, d):
+    """Four-parameter logistic (scaled sigmoid), evaluated stably.
+
+    Parameters
+    ----------
+    x : array_like
+        Input values.
+    a : float
+        Lower asymptote.
+    b : float
+        Amplitude (upper - lower).
+    c : float
+        Midpoint (inflection point).
+    d : float
+        Slope parameter (steepness).
+
+    Returns
+    -------
+    phi : ndarray
+        Logistic curve evaluated at x.
+    """
+    z = d * (x - c)
+
+    phi = np.empty_like(z, dtype=float)
+
+    mpos = z >= 0
+    if np.any(mpos):
+        phi[mpos] = a + b / (1.0 + np.exp(-z[mpos]))
+
+    mneg = ~mpos
+    if np.any(mneg):
+        expz = np.exp(z[mneg])
+        phi[mneg] = a + b * expz / (1.0 + expz)
+
+    return phi

xarpes/mdcs.py

@@ -32,6 +32,10 @@ class MDCs:
         Angular grid corresponding to the MDCs [degrees].
     angle_resolution : float
         Angular step size or effective angular resolution [degrees].
+    energy_resolution : float
+        Energy resolution associated with the MDCs [eV].
+    temperature: float
+            Temperature associated with the band map [K].
     enel : ndarray or float
         Electron binding energies of the MDC slices [eV].
         Can be a scalar for a single MDC.
@@ -83,11 +87,13 @@ class MDCs:
     
     """
 
-    def __init__(self, intensities, angles, angle_resolution, enel, hnuminPhi):
-        # Core input data (read-only)
+    def __init__(self, intensities, angles, angle_resolution,
+                energy_resolution, temperature, enel, hnuminPhi):
         self._intensities = intensities
         self._angles = angles
         self._angle_resolution = angle_resolution
+        self._energy_resolution = energy_resolution
+        self._temperature = temperature
         self._enel = enel
         self._hnuminPhi = hnuminPhi
 
@@ -104,8 +110,39 @@ class MDCs:
 
     @property
     def angle_resolution(self):
-        """Angular step size (float)."""
+        """Angular resolution (float)."""
         return self._angle_resolution
+    
+    @angle_resolution.setter
+    def angle_resolution(self, _):
+        """Setter for the angle resolution. This raises an attribute error
+        as the angle resolution needs to be derived from the band map."""
+        raise AttributeError("`angle_resolution` is read-only; set it via the "
+        "constructor.")
+    
+    @property
+    def energy_resolution(self):
+        """Energy resolution (float)."""
+        return self._energy_resolution
+    
+    @energy_resolution.setter
+    def energy_resolution(self, _):
+        """Setter for the energy resolution. This raises an attribute error
+        as the energy resolution needs to be derived from the band map."""
+        raise AttributeError("`energy_resolution` is read-only; set it via the "
+        "constructor.")
+    
+    @property
+    def temperature(self):
+        """Temperature (float)."""
+        return self._temperature
+
+    @temperature.setter
+    def temperature(self, _):
+        """Setter for the temperature. This raises an attribute error as the
+        temperature needs to be derived from the band map."""
+        raise AttributeError("`temperature` is read-only; set it via the "
+        "constructor.")
 
     @property
     def enel(self):
@@ -114,7 +151,8 @@ class MDCs:
 
     @enel.setter
     def enel(self, _):
-        raise AttributeError("`enel` is read-only; set it via the constructor.")
+        raise AttributeError("`enel` is read-only; set it via the " \
+        "constructor.")
 
     @property
     def hnuminPhi(self):
@@ -962,6 +1000,10 @@ class MDCs:
             Kinetic-energy grid corresponding to the selected label.
         hnuminPhi : float
             Photoelectron work-function offset.
+        energy_resolution : float
+            Energy resolution associated with the extracted self-energy data.
+        temperature : float
+            Temperature [K] associated with the extracted self-energy data.
         label : str
             Label of the selected distribution.
         selected_properties : dict or list of dict
@@ -1031,5 +1073,6 @@ class MDCs:
                     if key not in ("label", "_class"):
                         exported_parameters[key] = val
 
-        return (self._ekin_range, self.hnuminPhi, select_label,
-                selected_properties, exported_parameters)
+        return (self._ekin_range, self.hnuminPhi, self.energy_resolution,
+                self.temperature, select_label, selected_properties, 
+                exported_parameters)