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

xarpes/.ipynb_checkpoints/functions-checkpoint.py

@@ -0,0 +1,133 @@
+# Copyright (C) 2024 xARPES Developers
+# This program is free software under the terms of the GNU GPLv3 license.
+
+"""Separate functions mostly used in conjunction with various classes."""
+
+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)
+
+        # 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
+    """
+    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)
+
+    if (len(ydata) > len(p0)) and pcov is not None:
+        s_sq = (error_function(pfit, xdata, ydata, function,
+                               extra_args) ** 2).sum() / (len(ydata) - len(p0))
+        pcov = pcov * s_sq
+    else:
+        pcov = np.inf
+
+    error = []
+    for i in range(len(pfit)):
+        try:
+          error.append(np.absolute(pcov[i][i]) ** 0.5)
+        except:
+          error.append(0.00)
+    pfit_leastsq = pfit
+    perr_leastsq = np.array(error)
+
+    return pfit_leastsq, perr_leastsq

xarpes/.ipynb_checkpoints/plotting-checkpoint.py

@@ -0,0 +1,157 @@
+# 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.
+
+"""Functions related to plotting."""
+
+from functools import wraps
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+
+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]
+    mpl.rcParams['lines.linewidth'] = lw
+    mpl.rcParams['lines.markersize'] = 3
+    mpl.rcParams['xtick.major.size'] = 4
+    mpl.rcParams['xtick.minor.size'] = 2
+    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.
+
+    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)
+        ax = fig.gca()
+    else:
+        fig = plt.gcf()
+
+    return ax, fig, plt
+
+def add_fig_kwargs(func):
+    """Decorator that adds keyword arguments for functions returning matplotlib
+    figures.
+
+    The function should return either a matplotlib figure or None to signal
+    some sort of error/unexpected event.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        # pop the kwds used by the decorator.
+        title = kwargs.pop('title', None)
+        size_kwargs = kwargs.pop('size_kwargs', None)
+        show = kwargs.pop('show', True)
+        savefig = kwargs.pop('savefig', None)
+        tight_layout = kwargs.pop('tight_layout', False)
+        ax_grid = kwargs.pop('ax_grid', None)
+        ax_annotate = kwargs.pop('ax_annotate', None)
+        fig_close = kwargs.pop('fig_close', False)
+
+        # Call func and return immediately if None is returned.
+        fig = func(*args, **kwargs)
+        if fig is None:
+            return fig
+
+        # Operate on matplotlib figure.
+        if title is not None:
+            fig.suptitle(title)
+
+        if size_kwargs is not None:
+            fig.set_size_inches(size_kwargs.pop('w'), size_kwargs.pop('h'),
+                                **size_kwargs)
+
+        if ax_grid is not None:
+            for ax in fig.axes:
+                ax.grid(bool(ax_grid))
+
+        if ax_annotate:
+            tags = ascii_letters
+            if len(fig.axes) > len(tags):
+                tags = (1 + len(ascii_letters) // len(fig.axes)) * ascii_letters
+            for ax, tag in zip(fig.axes, tags):
+                ax.annotate(f'({tag})', xy=(0.05, 0.95),
+                            xycoords='axes fraction')
+
+        if tight_layout:
+            try:
+                fig.tight_layout()
+            except Exception as exc:
+                # For some unknown reason, this problem shows up only on travis.
+                # https://stackoverflow.com/questions/22708888/valueerror-when-using-matplotlib-tight-layout
+                print('Ignoring Exception raised by fig.tight_layout\n',
+                      str(exc))
+
+        if savefig:
+            fig.savefig(savefig)
+
+        if show:
+            plt.show()
+        if fig_close:
+            plt.close(fig=fig)
+
+        return fig
+
+    # Add docstring to the decorated method.
+    doc_str = """\n\n
+
+        notes
+        -----
+
+        Keyword arguments controlling the display of the figure:
+
+        ================  ====================================================
+        kwargs            Meaning
+        ================  ====================================================
+        title             Title of the plot (Default: None).
+        show              True to show the figure (default: True).
+        savefig           "abc.png" or "abc.eps" to save the figure to a file.
+        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.
+                          Default: None i.e. fig is left unchanged.
+        ax_annotate       Add labels to  subplots e.g. (a), (b).
+                          Default: False
+        fig_close         Close figure. Default: False.
+        ================  ====================================================
+
+"""
+
+    if wrapper.__doc__ is not None:
+        # Add s at the end of the docstring.
+        wrapper.__doc__ += f'\n{doc_str}'
+    else:
+        # Use s
+        wrapper.__doc__ = doc_str
+
+    return wrapper

xarpes/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.1.0'
+__version__ = '0.2.0'
 
 from . import plotting
 

xarpes/band_map.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
@@ -28,43 +28,72 @@ class band_map():
         1D array of kinetic energy values for the ordinate [eV]
     energy_resolution : float
         Energy resolution of the detector [eV]
-    temperature : float
+    temperature : float, None
         Temperature of the sample [K]
-    hnuminphi : float
+    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):
-
+                 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.
+        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
+        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.
+        r"""Manually sets the photon energy minus the work function in eV if it
+        has been set; otherwise returns None.
 
         Parameters
         ----------
-        hnuminphi : float
+        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
@@ -84,6 +113,9 @@ class band_map():
                        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
         ----------
@@ -104,13 +136,17 @@ class band_map():
         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
         -------
-        Matplotlib-Figure
+        fig : Matplotlib-Figure
+            Figure containing the Fermi edge fit
         """
         from xarpes.functions import fit_leastsq
 
@@ -148,6 +184,7 @@ class band_map():
                                  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 (-)')
@@ -165,4 +202,4 @@ class band_map():
 
         ax.legend()
 
-        return fig
+        return fig