xarpes 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

xarpes/.ipynb_checkpoints/__init__-checkpoint.py

@@ -0,0 +1,13 @@
+__version__ = '0.1.0'
+
+from . import plotting
+
+from .band_map import *
+from .distributions import *
+from .functions import *
+from .plotting import *
+
+# from . import plotting
+# from xarpes.plotting import *
+# from xarpes.distributions import *
+# from xarpes.distributions import fermi_dirac

xarpes/.ipynb_checkpoints/band_map-checkpoint.py

@@ -0,0 +1,205 @@
+# Copyright (C) 2024 xARPES Developers
+# This program is free software under the terms of the GNU GPLv3 license.
+
+# get_ax_fig_plt and add_fig_kwargs originate from pymatgen/util/plotting.py.
+# Copyright (C) 2011-2024 Shyue Ping Ong and the pymatgen Development Team
+# Pymatgen is released under the MIT License.
+
+# See also abipy/tools/plotting.py.
+# Copyright (C) 2021 Matteo Giantomassi and the AbiPy Group
+# AbiPy is free software under the terms of the GNU GPLv2 license.
+
+"""The band map class and allowed operations on it."""
+
+import numpy as np
+from .plotting import get_ax_fig_plt, add_fig_kwargs
+from .distributions import fermi_dirac
+
+class band_map():
+    r"""Class for the band map from the ARPES experiment.
+
+    Parameters
+    ----------
+    intensities : ndarray
+        2D array of counts for given (E,k) or (E,angle) pairs [counts]
+    angles : ndarray
+        1D array of angular values for the abscissa [degrees]
+    ekin : ndarray
+        1D array of kinetic energy values for the ordinate [eV]
+    energy_resolution : float
+        Energy resolution of the detector [eV]
+    temperature : float, None
+        Temperature of the sample [K]
+    hnuminphi : float, None
+        Kinetic energy minus the work function [eV]
+    hnuminphi_std : float, None
+        Standard deviation of kinetic energy minus work function [eV]
+    """
+    def __init__(self, intensities, angles, ekin, energy_resolution=None,
+                 temperature=None, hnuminphi=None, hnuminphi_std=None):
+        self.intensities = intensities
+        self.angles = angles
+        self.ekin = ekin
+        self.energy_resolution = energy_resolution
+        self.temperature = temperature
+        self.hnuminphi = hnuminphi
+        self.hnuminphi_std = hnuminphi_std
+
+    @property
+    def hnuminphi(self):
+        r"""Returns the photon energy minus the work function in eV if it has
+        been set, either during instantiation, with the setter, or by fitting
+        the Fermi-Dirac distribution to the integrated weight.
+
+        Returns
+        -------
+        hnuminphi : float, None
+            Kinetic energy minus the work function [eV]
+        """
+        return self._hnuminphi
+
+    @hnuminphi.setter
+    def hnuminphi(self, hnuminphi):
+        r"""Manually sets the photon energy minus the work function in eV if it
+        has been set; otherwise returns None.
+
+        Parameters
+        ----------
+        hnuminphi : float, None
+            Kinetic energy minus the work function [eV]
+        """
+        self._hnuminphi = hnuminphi
+
+    @property
+    def hnuminphi_std(self):
+        r"""Returns standard deviation of the photon energy minus the work
+        function in eV.
+
+        Returns
+        -------
+        hnuminphi_std : float
+            Standard deviation of energy minus the work function [eV]
+        """
+        return self._hnuminphi_std
+
+    @hnuminphi_std.setter
+    def hnuminphi_std(self, hnuminphi_std):
+        r"""Manually sets the standard deviation of photon energy minus the
+        work function in eV.
+
+        Parameters
+        ----------
+        hnuminphi_std : float
+            Standard deviation of energy minus the work function [eV]
+        """
+        self._hnuminphi_std = hnuminphi_std
+
+    def shift_angles(self, shift):
+        r"""
+        Shifts the angles by the specified amount in degrees. Used to shift
+        from the detector angle to the material angle.
+
+        Parameters
+        ----------
+        shift : float
+            Angular shift [degrees]
+        """
+        self.angles = self.angles + shift
+
+    @add_fig_kwargs
+    def fit_fermi_edge(self, hnuminphi_guess, background_guess=0.0,
+                       integrated_weight_guess=1.0, angle_min=-np.infty,
+                       angle_max=np.infty, ekin_min=-np.infty,
+                       ekin_max=np.infty, ax=None, **kwargs):
+        r"""
+        Fits the Fermi edge of the band map and plots the result.
+        Also sets hnuminphi, the kinetic energy minus the work function in eV.
+        The fitting includes an energy convolution with an abscissa range
+        expanded by 5 times the energy resolution standard deviation.
+
+        Parameters
+        ----------
+        hnuminphi_guess : float
+            Initial guess for kinetic energy minus the work function [eV]
+        background_guess : float
+            Initial guess for background intensity [counts]
+        integrated_weight_guess : float
+            Initial guess for integrated spectral intensity [counts]
+        angle_min : float
+            Minimum angle of integration interval [degrees]
+        angle_max : float
+            Maximum angle of integration interval [degrees]
+        ekin_min : float
+            Minimum kinetic energy of integration interval [eV]
+        ekin_max : float
+            Maximum kinetic energy of integration interval [eV]
+        ax : Matplotlib-Axes / NoneType
+            Axis for plotting the Fermi edge on. Created if not provided by
+            the user.
+
+        Other parameters
+        ----------------
+        **kwargs : dict, optional
+            Additional arguments passed on to add_fig_kwargs. See the keyword
+            table below.
+
+        Returns
+        -------
+        fig : Matplotlib-Figure
+            Figure containing the Fermi edge fit
+        """
+        from xarpes.functions import fit_leastsq
+
+        ax, fig, plt = get_ax_fig_plt(ax=ax)
+
+        min_angle_index = np.argmin(np.abs(self.angles - angle_min))
+        max_angle_index = np.argmin(np.abs(self.angles - angle_max))
+
+        min_ekin_index = np.argmin(np.abs(self.ekin - ekin_min))
+        max_ekin_index = np.argmin(np.abs(self.ekin - ekin_max))
+
+        energy_range = self.ekin[min_ekin_index:max_ekin_index]
+
+        integrated_intensity = np.trapz(
+            self.intensities[min_ekin_index:max_ekin_index,
+                min_angle_index:max_angle_index], axis=1)
+
+        fdir_initial = fermi_dirac(temperature=self.temperature,
+                                   hnuminphi=hnuminphi_guess,
+                                   background=background_guess,
+                                   integrated_weight=integrated_weight_guess,
+                                   name='Initial guess')
+
+        parameters = np.array(
+            [hnuminphi_guess, background_guess, integrated_weight_guess])
+
+        extra_args = (self.energy_resolution)
+
+        popt, pcov = fit_leastsq(parameters, energy_range, integrated_intensity,
+                                 fdir_initial, extra_args)
+
+        fdir_final = fermi_dirac(temperature=self.temperature,
+                                 hnuminphi=popt[0], background=popt[1],
+                                 integrated_weight=popt[2],
+                                 name='Fitted result')
+
+        self.hnuminphi = popt[0]
+        self.hnuminphi_std = np.sqrt(np.diag(pcov))[0][0]
+
+        ax.set_xlabel(r'$E_{\mathrm{kin}}$ (-)')
+        ax.set_ylabel('Counts (-)')
+        ax.set_xlim([ekin_min, ekin_max])
+
+        ax.plot(energy_range, integrated_intensity, label='Data')
+
+        ax.plot(energy_range, fdir_initial.convolve(energy_range,
+                energy_resolution=self.energy_resolution),
+                label=fdir_initial.name)
+
+        ax.plot(energy_range, fdir_final.convolve(energy_range,
+                energy_resolution=self.energy_resolution),
+                label=fdir_final.name)
+
+        ax.legend()
+
+        return fig

xarpes/.ipynb_checkpoints/distributions-checkpoint.py

@@ -0,0 +1,430 @@
+# Copyright (C) 2024 xARPES Developers
+# This program is free software under the terms of the GNU GPLv3 license.
+
+"""The distributions used throughout the code."""
+
+class distribution:
+    r"""Parent class for distributions. The class cannot be used on its own,
+    but is used to instantiate unique and non-unique distributions.
+
+    Parameters
+    ----------
+    name : str
+        Non-unique name for instances, not to be modified after instantiation.
+    """
+    def __init__(self, name):
+        self._name = name
+
+    @property
+    def name(self):
+        r"""Returns the name of the class instance.
+
+        Returns
+        -------
+        name : str
+            Non-unique name for instances, not to be modified after
+            instantiation.
+        """
+        return self._name
+
+class unique_distribution(distribution):
+    r"""Parent class for unique distributions, to be used one at a time, e.g.,
+    during the background of an MDC fit or the Fermi-Dirac distribution.
+
+    Parameters
+    ----------
+    label : str
+        Unique label for instances, identical to the name for unique
+        distributions. Not to be modified after instantiation.
+    """
+    def __init__(self, name):
+        super().__init__(name)
+        self._label = name
+
+    @property
+    def label(self):
+        r"""Returns the unique class label.
+
+        Returns
+        -------
+        label : str
+            Unique label for instances, identical to the name for unique
+            distributions. Not to be modified after instantiation.
+        """
+        return self._label
+
+class constant(unique_distribution):
+    r"""Child class for constant distributions, used e.g., during MDC fitting.
+    The constant class is unique, only one instance should be used per task.
+
+    Parameters
+    ----------
+    offset : float
+        The value of the distribution for the abscissa equal to 0.
+    """
+    def __init__(self, offset):
+        super().__init__(name='constant')
+        self._offset = offset
+
+    @property
+    def offset(self):
+        r"""Returns the offset of the constant distribution.
+
+        Returns
+        -------
+        offset : float
+            The value of the distribution for the abscissa equal to 0.
+        """
+        return self._offset
+
+    @offset.setter
+    def set_offset(self, x):
+        r"""Sets the offset of the constant distribution.
+
+        Parameters
+        ----------
+        offset : float
+            The value of the distribution for the abscissa equal to 0.
+        """
+        self._offset = x
+
+class linear(unique_distribution):
+    r"""Child cass for for linear distributions, used e.g., during MDC fitting.
+    The constant class is unique, only one instance should be used per task.
+
+    Parameters
+    ----------
+    offset : float
+        The value of the distribution for the abscissa equal to 0.
+    slope : float
+        The linear slope of the distribution w.r.t. the abscissa.
+    """
+    def __init__(self, slope, offset):
+        super().__init__(name='linear')
+        self._offset = offset
+        self._slope = slope
+
+    @property
+    def offset(self):
+        r"""Returns the offset of the linear distribution.
+
+        Returns
+        -------
+        offset : float
+            The value of the distribution for the abscissa equal to 0.
+        """
+        return self._offset
+
+    @offset.setter
+    def set_offset(self, x):
+        r"""Sets the offset of the linear distribution.
+
+        Parameters
+        ----------
+        offset : float
+            The value of the distribution for the abscissa equal to 0.
+        """
+        self._offset = x
+
+    @property
+    def slope(self):
+        r"""Returns the slope of the linear distribution.
+
+        Returns
+        -------
+        slope : float
+            The linear slope of the distribution w.r.t. the abscissa.
+        """
+        return self._slope
+
+    @slope.setter
+    def set_slope(self, x):
+        r"""Sets the slope of the linear distribution.
+
+        Parameters
+        ----------
+        slope : float
+            The linear slope of the distribution w.r.t. the abscissa.
+        """
+        self._slope = x
+
+class linear(unique_distribution):
+    r"""Child cass for for linear distributions, used e.g., during MDC fitting.
+    The constant class is unique, only one instance should be used per task.
+
+    Parameters
+    ----------
+    offset : float
+        The value of the distribution for the abscissa equal to 0.
+    slope : float
+        The linear slope of the distribution w.r.t. the abscissa.
+    """
+    def __init__(self, slope, offset):
+
+        super().__init__(name='linear')
+        self._offset = offset
+        self._slope = slope
+
+    @property
+    def offset(self):
+        r"""Returns the offset of the linear distribution.
+
+        Returns
+        -------
+        offset : float
+            The value of the distribution for the abscissa equal to 0.
+        """
+        return self._offset
+
+    @offset.setter
+    def set_offset(self, x):
+        r"""Sets the offset of the linear distribution.
+
+        Parameters
+        ----------
+        offset : float
+            The value of the distribution for the abscissa equal to 0.
+        """
+        self._offset = x
+
+    @property
+    def slope(self):
+        r"""Returns the slope of the linear distribution.
+
+        Returns
+        -------
+        slope : float
+            The linear slope of the distribution w.r.t. the abscissa.
+        """
+        return self._slope
+
+    @slope.setter
+    def set_slope(self, x):
+        r"""Sets the slope of the linear distribution.
+
+        Parameters
+        ----------
+        slope : float
+            The linear slope of the distribution w.r.t. the abscissa.
+        """
+        self._slope = x
+
+class fermi_dirac(unique_distribution):
+    r"""Child class for Fermi-Dirac (FD) distributions, used e.g., during Fermi
+    edge fitting. The FD class is unique, only one instance should be used
+    per task.
+
+    The Fermi-Dirac distribution is described by the following formula:
+
+    .. math::
+
+            \frac{A}{\rm{e}^{\beta(E_{\rm{kin}}-(h\nu-\Phi))}+1} + B
+
+    with :math:`A` as :attr:`integrated_weight`, :math:`B` as
+    :attr:`background`, :math:`h\nu-\Phi` as :attr:`hnuminphi`, and
+    :math:`\beta=1/(k_{\rm{B}}T)` with :math:`T` as :attr:`temperature`.
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature of the sample [K]
+    hnuminphi : float
+        Kinetic energy minus the work function [eV]
+    background : float
+        Background spectral weight [counts]
+    integrated_weight : float
+        Integrated weight on top of the background [counts]
+    """
+    def __init__(self, temperature, hnuminphi, background=0,
+                 integrated_weight=1, name='fermi_dirac'):
+        super().__init__(name)
+        self.temperature = temperature
+        self.hnuminphi = hnuminphi
+        self.background = background
+        self.integrated_weight = integrated_weight
+
+        @property
+        def temperature(self):
+            r"""Returns the temperature of the sample.
+
+            Returns
+            -------
+            temperature : float
+                Temperature of the sample [K]
+            """
+            return self._temperature
+
+        @temperature.setter
+        def set_temperature(self, x):
+            r"""Sets the temperature of the FD distribution.
+
+            Parameters
+            ----------
+            temperature : float
+                Temperature of the sample [K]
+            """
+            self._temperature = x
+
+        @property
+        def hnuminphi(self):
+            r"""Returns the photon energy minus the work function of the FD
+            distribution.
+
+            Returns
+            -------
+            hnuminphi: float
+                Kinetic energy minus the work function [eV]
+            """
+            return self._hnuminphi
+
+        @hnuminphi.setter
+        def set_hnuminphi(self, x):
+            r"""Sets the photon energy minus the work function of the FD
+            distribution.
+
+            Parameters
+            ----------
+            hnuminphi : float
+                Kinetic energy minus the work function [eV]
+            """
+            self._hnuminphi = x
+
+        @property
+        def background(self):
+            r"""Returns the background intensity of the FD distribution.
+
+            Returns
+            -------
+            background : float
+                Background spectral weight [counts]
+            """
+            return self._background
+
+        @background.setter
+        def set_background(self, x):
+            r"""Sets the background intensity of the FD distribution.
+
+            Parameters
+            ----------
+            background : float
+                Background spectral weight [counts]
+            """
+            self._background = x
+
+        @property
+        def integrated_weight(self):
+            r"""Returns the integrated weight of the FD distribution.
+
+            Returns
+            -------
+            integrated_weight: float
+                Integrated weight on top of the background [counts]
+            """
+            return self._integrated_weight
+
+        @integrated_weight.setter
+        def set_integrated_weight(self, x):
+            r"""Sets the integrated weight of the FD distribution.
+
+            Parameters
+            ----------
+            integrated_weight : float
+                Integrated weight on top of the background [counts]
+            """
+            self._integrated_weight = x
+
+    def __call__(self, energy_range, hnuminphi, background, integrated_weight,
+                 energy_resolution):
+        """Call method to directly evaluate a FD distribution without having to
+        instantiate a class instance.
+
+        Parameters
+        ----------
+        energy_range : ndarray
+            1D array on which to evaluate the FD distribution [eV]
+        hnuminphi : float
+            Kinetic energy minus the work function [eV]
+        background : float
+            Background spectral weight [counts]
+        integrated_weight : float
+            Integrated weight on top of the background [counts]
+        energy_resolution : float
+            Energy resolution of the detector for the convolution [eV]
+
+        Returns
+        -------
+        evalf : ndarray
+            1D array of the energy-convolved FD distribution [counts]
+        """
+        from scipy.ndimage import gaussian_filter
+        import numpy as np
+        sigma_extend = 5 # Extend data range by "5 sigma"
+        # Conversion from FWHM to standard deviation [-]
+        fwhm_to_std = np.sqrt(8 * np.log(2))
+        k_B = 8.617e-5 # Boltzmann constant [eV/K]
+        k_BT = self.temperature * k_B
+        step_size = np.abs(energy_range[1] - energy_range[0])
+        estep = energy_resolution / (step_size * fwhm_to_std)
+        enumb = int(sigma_extend * estep)
+        extend = np.linspace(energy_range[0] - enumb * step_size,
+                             energy_range[-1] + enumb * step_size,
+                             len(energy_range) + 2 * enumb)
+        result = (integrated_weight / (1 + np.exp((extend - hnuminphi) / k_BT))
+            + background)
+        evalf = gaussian_filter(result, sigma=estep)[enumb:-enumb]
+        return evalf
+
+    def evaluate(self, energy_range):
+        r"""Evaluates the FD distribution for a given class instance.
+        No energy convolution is performed with evaluate.
+
+        Parameters
+        ----------
+        energy_range : ndarray
+            1D array on which to evaluate the FD distribution [eV]
+
+        Returns
+        -------
+        evalf : ndarray
+            1D array of the evaluated FD distribution [counts]
+        """
+        import numpy as np
+        k_B = 8.617e-5 # Boltzmann constant [eV/K]
+        k_BT = self.temperature * k_B
+        evalf = (self.integrated_weight
+            / (1 + np.exp((energy_range - self.hnuminphi) / k_BT))
+            + self.background)
+        return evalf
+
+    def convolve(self, energy_range, energy_resolution):
+        r"""Evaluates the FD distribution for a given class instance and
+        performs the energy convolution with the given resolution. The
+        convolution is performed with an expanded abscissa range of 5
+        times the standard deviation.
+
+        Parameters
+        ----------
+        energy_range : ndarray
+            1D array on which to evaluate and convolve FD distribution [eV]
+        energy_resolution : float
+            Energy resolution of the detector for the convolution [eV]
+
+        Returns
+        -------
+        evalf : ndarray
+            1D array of the energy-convolved FD distribution [counts]
+        """
+        import numpy as np
+        from scipy.ndimage import gaussian_filter
+        sigma_extend = 5 # Extend data range by "5 sigma"
+        # Conversion from FWHM to standard deviation [-]
+        fwhm_to_std = np.sqrt(8 * np.log(2))
+        step_size = np.abs(energy_range[1] - energy_range[0])
+        estep = energy_resolution / (step_size * fwhm_to_std)
+        enumb = int(sigma_extend * estep)
+        extend = np.linspace(energy_range[0] - enumb * step_size,
+                             energy_range[-1] + enumb * step_size,
+                             len(energy_range) + 2 * enumb)
+        evalf = gaussian_filter(self.evaluate(extend),
+                                sigma=estep)[enumb:-enumb]
+        return evalf