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

xarpes/distributions.py

@@ -1,38 +1,361 @@
 # Copyright (C) 2024 xARPES Developers
-# This program is free software under the terms of the GNU GPLv2 license.
+# 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
+        self._name = name
 
-    def dist(self):
-        return self._dist
+    @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
-        self.name = name
+
+        @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"
@@ -48,17 +371,49 @@ class fermi_dirac(unique_distribution):
                              len(energy_range) + 2 * enumb)
         result = (integrated_weight / (1 + np.exp((extend - hnuminphi) / k_BT))
             + background)
-        return gaussian_filter(result, sigma=estep)[enumb:-enumb]
+        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
-        return (self.integrated_weight
+        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"
@@ -70,35 +425,6 @@ class fermi_dirac(unique_distribution):
         extend = np.linspace(energy_range[0] - enumb * step_size,
                              energy_range[-1] + enumb * step_size,
                              len(energy_range) + 2 * enumb)
-        return gaussian_filter(self.evaluate(extend), sigma=estep)[enumb:-enumb]
-
-
-class constant(unique_distribution):
-    def __init__(self, offset):
-        super().__init__(name='constant')
-        self._offset = offset
-
-    def offset(self):
-        return self._offset
-
-    def set_offset(self, x):
-        self._offset = x
-
-
-class linear(unique_distribution):
-    def __init__(self, slope, offset):
-        super().__init__(name='linear')
-        self._offset = offset
-        self._slope = slope
-
-    def offset(self):
-        return self._offset
-
-    def set_offset(self, x):
-        self._offset = x
-
-    def slope(self):
-        return self._slope
-
-    def set_slope(self, x):
-        self._slope = x
+        evalf = gaussian_filter(self.evaluate(extend),
+                                sigma=estep)[enumb:-enumb]
+        return evalf

xarpes/functions.py

@@ -1,20 +1,115 @@
 # Copyright (C) 2024 xARPES Developers
-# This program is free software under the terms of the GNU GPLv2 license.
+# This program is free software under the terms of the GNU GPLv3 license.
 
-"""Separate functions used in conjunction with various classes."""
+"""Separate functions mostly used in conjunction with various classes."""
 
-import numpy as np
-from scipy.optimize import leastsq
+def download_examples():
+    """Downloads the examples folder from the xARPES code only if it does not
+    already exist. Prints executed steps and a final cleanup/failure message.
+    
+    Returns
+    -------
+    0, 1 : int
+        Returns 0 if the execution succeeds, 1 if it fails.
+    """
+    import requests
+    import zipfile
+    import os
+    import shutil
+    import io
+    
+    repo_url = 'https://github.com/xARPES/xARPES_examples'
+    output_dir = '.'  # Directory from which the function is called
+    
+    # Check if 'examples' directory already exists
+    final_examples_path = os.path.join(output_dir, 'examples')
+    if os.path.exists(final_examples_path):
+        print("Warning: 'examples' folder already exists. No download will be performed.")
+        return 1 # Exit the function if 'examples' directory exists
+
+    # Proceed with download if 'examples' directory does not exist
+    repo_parts = repo_url.replace("https://github.com/", "").rstrip('/')
+    zip_url = f"https://github.com/{repo_parts}/archive/refs/heads/main.zip"
+
+    # Make the HTTP request to download the zip file
+    print(f"Downloading {zip_url}")
+    response = requests.get(zip_url)
+    if response.status_code == 200:
+        zip_file_bytes = io.BytesIO(response.content)
+
+        with zipfile.ZipFile(zip_file_bytes, 'r') as zip_ref:
+            zip_ref.extractall(output_dir)
 
-def error_function(p, x, y, function, extra_args):
+        # Path to the extracted main folder
+        main_folder_path = os.path.join(output_dir, repo_parts.split('/')[-1] + '-main')
+        examples_path = os.path.join(main_folder_path, 'examples')
+
+        # Move the 'examples' directory to the target location if it was extracted
+        if os.path.exists(examples_path):
+            shutil.move(examples_path, final_examples_path)
+            print(f"'examples' subdirectory moved to {final_examples_path}")
+        else:
+            print("'examples' subdirectory not found in the repository.")
+
+        # Remove the rest of the extracted content
+        shutil.rmtree(main_folder_path)
+        print(f"Cleaned up temporary files in {main_folder_path}")
+        return 0
+    else:
+        print(f"Failed to download the repository. Status code: {response.status_code}")
+        return 1
+
+
+def error_function(p, xdata, ydata, function, extra_args):
     r"""The error function used inside the fit_leastsq function.
+
+    Parameters
+    ----------
+    p : ndarray
+        Array of parameters during the optimization
+    xdata : ndarray
+        Array of abscissa values the function is evaluated on
+    ydata : ndarray
+        Outcomes on ordinate the evaluated function is compared to
+    function : function
+        Function or class with call method to be evaluated
+    extra_args :
+        Arguments provided to function that should not be optimized
+
+    Returns
+    -------
+    residual :
+        Residual between evaluated function and ydata
     """
-    return function(x, *p, extra_args) - y
+    residual = function(xdata, *p, extra_args) - ydata
+    return residual
 
 
 def fit_leastsq(p0, xdata, ydata, function, extra_args):
     r"""Wrapper arround scipy.optimize.leastsq.
+
+    Parameters
+    ----------
+    p0 : ndarray
+        Initial guess for parameters to be optimized
+    xdata : ndarray
+        Array of abscissa values the function is evaluated on
+    ydata : ndarray
+        Outcomes on ordinate the evaluated function is compared to
+    function : function
+        Function or class with call method to be evaluated
+    extra_args :
+        Arguments provided to function that should not be optimized
+
+    Returns
+    -------
+    pfit_leastsq : ndarray
+        Array containing the optimized parameters
+    perr_leastsq : ndarray
+        Covariance matrix of the optimized parameters
     """
+    import numpy as np
+    from scipy.optimize import leastsq
     pfit, pcov, infodict, errmsg, success = leastsq(
         error_function, p0, args=(xdata, ydata, function, extra_args),
         full_output=1)
@@ -35,4 +130,4 @@ def fit_leastsq(p0, xdata, ydata, function, extra_args):
     pfit_leastsq = pfit
     perr_leastsq = np.array(error)
 
-    return pfit_leastsq, perr_leastsq
+    return pfit_leastsq, perr_leastsq

xarpes/plotting.py

@@ -1,5 +1,5 @@
 # Copyright (C) 2024 xARPES Developers
-# This program is free software under the terms of the GNU GPLv2 license.
+# 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
@@ -15,7 +15,7 @@ from functools import wraps
 import matplotlib.pyplot as plt
 import matplotlib as mpl
 
-def my_plot_settings(name='default'):
+def plot_settings(name='default'):
     mpl.rc('xtick', labelsize=10, direction='in')
     mpl.rc('ytick', labelsize=10, direction='in')
     lw = dict(default=2.0, large=4.0)[name]
@@ -26,20 +26,28 @@ def my_plot_settings(name='default'):
     mpl.rcParams['xtick.major.width'] = 0.8
     mpl.rcParams.update({'font.size': 16})
 
-
 def get_ax_fig_plt(ax=None, **kwargs):
-    r"""Helper function used in plot functions supporting an optional Axes
-    argument. If ax is None, we build the `matplotlib` figure and create the
-    Axes else. We return the current active figure.
-
-    Args:
-        ax (Axes, optional): Axes object. Defaults to None.
-        kwargs: keyword arguments are passed to plt.figure if ax is not None.
-
-      Returns:
-        ax: :class:`Axes` object
-        figure: matplotlib figure
-        plt: matplotlib pyplot module.
+    r"""Helper function used in plot functions supporting an optional `Axes`
+    argument.
+
+    If `ax` is `None`, we build the `matplotlib` figure and create the `Axes`.
+    Else we return the current active figure.
+
+    Parameters
+    ----------
+    ax : object
+        `Axes` object. Defaults to `None`.
+    **kwargs
+        Keyword arguments are passed to `plt.figure` if `ax` is not `None`.
+
+    Returns
+    -------
+    ax : object
+        `Axes` object.
+    figure : object
+        `matplotlib` figure.
+    plt : object
+        `matplotlib.pyplot` module.
     """
     if ax is None:
         fig = plt.figure(**kwargs)
@@ -49,7 +57,6 @@ def get_ax_fig_plt(ax=None, **kwargs):
 
     return ax, fig, plt
 
-
 def add_fig_kwargs(func):
     """Decorator that adds keyword arguments for functions returning matplotlib
     figures.
@@ -115,6 +122,10 @@ def add_fig_kwargs(func):
 
     # Add docstring to the decorated method.
     doc_str = """\n\n
+
+        notes
+        -----
+
         Keyword arguments controlling the display of the figure:
 
         ================  ====================================================
@@ -126,7 +137,8 @@ def add_fig_kwargs(func):
         size_kwargs       Dictionary with options passed to fig.set_size_inches
                           e.g. size_kwargs=dict(w=3, h=4)
         tight_layout      True to call fig.tight_layout (default: False)
-        ax_grid           True (False) to add (remove) grid from all axes in fig.
+        ax_grid           True (False) to add (remove) grid from all axes in
+                          fig.
                           Default: None i.e. fig is left unchanged.
         ax_annotate       Add labels to  subplots e.g. (a), (b).
                           Default: False
@@ -142,4 +154,4 @@ def add_fig_kwargs(func):
         # Use s
         wrapper.__doc__ = doc_str
 
-    return wrapper
+    return wrapper