diffpy.labpdfproc 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

diffpy/__init__.py

@@ -1,10 +1,14 @@
 #!/usr/bin/env python
 ##############################################################################
 #
-# (c) 2024 The Trustees of Columbia University in the City of New York.
+# (c) 2024-2025, The Trustees of Columbia University in the City of New York.
 # All rights reserved.
 #
-# File coded by: Billinge Group members and community contributors.
+# (c) 2026-present, diffpy.labpdfproc developers and contributors.
+# All rights reserved.
+#
+# File coded by: Yucong Chen, Till Schertenleib, Caden Myers,
+# Billinge Group members.
 #
 # See GitHub contributions for a more detailed list of contributors.
 # https://github.com/diffpy/diffpy.labpdfproc/graphs/contributors
@@ -12,12 +16,3 @@
 # See LICENSE.rst for license information.
 #
 ##############################################################################
-
-"""Blank namespace package for module diffpy."""
-
-
-from pkgutil import extend_path
-
-__path__ = extend_path(__path__, __name__)
-
-# End of file

diffpy/labpdfproc/__init__.py

@@ -1,10 +1,14 @@
 #!/usr/bin/env python
 ##############################################################################
 #
-# (c) 2024 The Trustees of Columbia University in the City of New York.
+# (c) 2024-2025, The Trustees of Columbia University in the City of New York.
 # All rights reserved.
 #
-# File coded by: Billinge Group members and community contributors.
+# (c) 2026-present, diffpy.labpdfproc developers and contributors.
+# All rights reserved.
+#
+# File coded by: Yucong Chen, Till Schertenleib, Caden Myers,
+# Billinge Group members.
 #
 # See GitHub contributions for a more detailed list of contributors.
 # https://github.com/diffpy/diffpy.labpdfproc/graphs/contributors
@@ -12,8 +16,8 @@
 # See LICENSE.rst for license information.
 #
 ##############################################################################
-
-"""Tools for processing x-ray powder diffraction data from laboratory sources."""
+"""Tools for processing x-ray powder diffraction data from laboratory
+sources."""
 
 # package version
 from diffpy.labpdfproc.version import __version__

diffpy/labpdfproc/data/coefficient_list.csv

@@ -1,5 +1,7 @@
--6.543824057313183,2.517676049711881e-10,-430.98705781061807,-1390.1242894055792,-2233.6043531698424,-2624.226082870084,-2590.22123249732
-5.020666247920394,-4.676545705328227e-10,875.3743680589598,2744.521375373735,4366.230491983095,5113.620084734874,5051.51673764446
-1.8615172482459748,3.25649449911046e-10,-663.8228448830648,-2027.2101338882571,-3194.0427904869357,-3728.3876362721985,-3684.6430045258744
--1.9688714316525813,0.9999999998992586,224.64320300800793,666.0546805817288,1038.3830530062712,1207.4338980088214,1193.1790131535502
-0.9819818977427489,1.1680695590205036e-11,-28.533774174029173,-82.17596308875525,-126.6770208129477,-146.65755463691826,-144.8506009433783
+-20619.128648244743,2.4364997877410417e-06,26505.585137008606,-337279.3213902739,-1056051.2792994028,-1815539.1160187968,-2372171.980894541,-2642993.4538858426
+56203.20048346139,-6.774323967911372e-06,-51225.01460831775,1005023.6254387972,3051609.2101441943,5201294.212075991,6773264.754466731,7538833.212217793
+-63802.106117440504,7.845612740225726e-06,33089.880661840034,-1242527.9972772636,-3668761.3028854067,-6202335.40819644,-8050708.344579743,-8951452.327576341
+38603.18842240787,-4.844608638276231e-06,-4028.752491140328,816333.2796219026,2349291.871863084,3940828.5623758254,5099123.959731602,5663734.051678175
+-13126.533425725584,1.6822282153058894e-06,-4395.4012467221355,-300757.7094990732,-845218.597424347,-1407243.8630987857,-1815244.4369415767,-2014105.8565458413
+2378.155272695758,0.9999996885549859,1912.0755691304305,58944.34388638723,162014.93660541167,267802.2088119374,344395.5526651557,381710.2334140182
+-178.70587585316136,2.4018054840276848e-08,-234.76082555771987,-4803.1698085743365,-12928.521798999534,-21220.235622246797,-27207.092578054173,-30121.285267280207

diffpy/labpdfproc/functions.py

@@ -1,27 +1,37 @@
 import math
-from pathlib import Path
+import warnings
+from importlib.resources import files
 
 import numpy as np
 import pandas as pd
 from scipy.interpolate import interp1d
 
-from diffpy.utils.scattering_objects.diffraction_objects import Diffraction_object
+from diffpy.utils.diffraction_objects import XQUANTITIES, DiffractionObject
 
 RADIUS_MM = 1
 N_POINTS_ON_DIAMETER = 300
 TTH_GRID = np.arange(1, 180.1, 0.1)
+# Round down the last element if it's slightly above 180.00
+# due to floating point precision
+TTH_GRID[-1] = 180.00
 CVE_METHODS = ["brute_force", "polynomial_interpolation"]
 
-# pre-computed datasets for polynomial interpolation (fast calculation)
-MUD_LIST = [0.5, 1, 2, 3, 4, 5, 6]
-CWD = Path(__file__).parent.resolve()
-MULS = np.loadtxt(CWD / "data" / "inverse_cve.xy")
-COEFFICIENT_LIST = np.array(pd.read_csv(CWD / "data" / "coefficient_list.csv", header=None))
-INTERPOLATION_FUNCTIONS = [interp1d(MUD_LIST, coefficients, kind="quadratic") for coefficients in COEFFICIENT_LIST]
+# Pre-computed datasets for polynomial interpolation (fast calculation)
+data_dir = files("diffpy.labpdfproc") / "data"
+MUD_LIST = np.array([0.5, 1, 2, 3, 4, 5, 6, 7])
+MULS = np.loadtxt(data_dir / "inverse_cve.xy")
+COEFFICIENT_LIST = np.array(
+    pd.read_csv(data_dir / "coefficient_list.csv", header=None)
+)
+INTERPOLATION_FUNCTIONS = [
+    interp1d(MUD_LIST, coeffs, kind="quadratic") for coeffs in COEFFICIENT_LIST
+]
 
 
 class Gridded_circle:
-    def __init__(self, radius=1, n_points_on_diameter=N_POINTS_ON_DIAMETER, mu=None):
+    def __init__(
+        self, radius=1, n_points_on_diameter=N_POINTS_ON_DIAMETER, mu=None
+    ):
         self.radius = radius
         self.npoints = n_points_on_diameter
         self.mu = mu
@@ -30,103 +40,63 @@ class Gridded_circle:
         self._get_grid_points()
 
     def _get_grid_points(self):
-        """
-        given a radius and a grid size, return a grid of points to uniformly sample that circle
-        """
+        """Given a radius and a grid size, return a grid of points to
+        uniformly sample that circle."""
         xs = np.linspace(-self.radius, self.radius, self.npoints)
         ys = np.linspace(-self.radius, self.radius, self.npoints)
-        self.grid = {(x, y) for x in xs for y in ys if x**2 + y**2 <= self.radius**2}
+        self.grid = {
+            (x, y) for x in xs for y in ys if x**2 + y**2 <= self.radius**2
+        }
         self.total_points_in_grid = len(self.grid)
 
-    def set_distances_at_angle(self, angle):
-        """
-        given an angle, set the distances from the grid points to the entry and exit coordinates
-
-        Parameters
-        ----------
-        angle float
-          the angle in degrees
-
-        Returns
-        -------
-        the list of distances containing total distance, primary distance and secondary distance
-
-        """
-        self.primary_distances, self.secondary_distances, self.distances = [], [], []
-        for coord in self.grid:
-            distance, primary, secondary = self.get_path_length(coord, angle)
-            self.distances.append(distance)
-            self.primary_distances.append(primary)
-            self.secondary_distances.append(secondary)
-
-    def set_muls_at_angle(self, angle):
-        """
-        compute muls = exp(-mu*distance) for a given angle
-
-        Parameters
-        ----------
-        angle float
-          the angle in degrees
-
-        Returns
-        -------
-        an array of floats containing the muls corresponding to each angle
-
-        """
-        mu = self.mu
-        self.muls = []
-        if len(self.distances) == 0:
-            self.set_distances_at_angle(angle)
-        for distance in self.distances:
-            self.muls.append(np.exp(-mu * distance))
-
     def _get_entry_exit_coordinates(self, coordinate, angle):
-        """
-        get the coordinates where the beam enters and leaves the circle for a given angle and grid point
-
-        Parameters
-        ----------
-        grid_point tuple of floats
-          the coordinates of the grid point
-
-        angle float
-          the angle in degrees
-
-        radius float
-          the radius of the circle in units of inverse mu
+        """Get the coordinates where the beam enters and leaves the
+        circle for a given angle and grid point.
 
-        it is calculated in the following way:
-        For the entry coordinate, the y-component will be the y of the grid point and the x-component will be minus
+        It is calculated in the following way:
+        For the entry coordinate,
+        the y-component will be the y of the grid point
+        and the x-component will be minus
         the value of x on the circle at the height of this y.
 
         For the exit coordinate:
-        Find the line y = ax + b that passes through grid_point at angle angle
-        The circle is x^2 + y^2 = r^2
+        Find the line y = ax + b that passes through grid_point at angle.
+        The circle is x^2 + y^2 = r^2.
         The exit point is where these are simultaneous equations
         x^2 + y^2 = r^2 & y = ax + b
         x^2 + (ax+b)^2 = r^2
         => x^2 + a^2x^2 + 2abx + b^2 - r^2 = 0
         => (1+a^2) x^2 + 2abx + (b^2 - r^2) = 0
-        to find x_exit we find the roots of these equations and pick the root that is above y-grid
-        then we get y_exit from y_exit = a*x_exit + b
+        to find x_exit we find the roots of these equations
+        and pick the root that is above y-grid
+        then we get y_exit from y_exit = a*x_exit + b.
+
+        Parameters
+        ----------
+        coordinate : tuple of floats
+            The coordinates of the grid point.
+        angle : float
+            The angle in degrees.
 
         Returns
         -------
-        (1) the coordinate of the entry point and (2) of the exit point of a beam entering horizontally
-        impinging on a coordinate point that lies in the circle and then exiting at some angle, angle.
-
+        (entry_point, exit_point): tuple of floats
+            (1) The coordinate of the entry point and
+            (2) of the exit point of a beam entering horizontally
+            impinging on a coordinate point that lies in the circle
+            and then exiting at some angle, angle.
         """
         epsilon = 1e-7  # precision close to 90
         angle = math.radians(angle)
         xgrid = coordinate[0]
         ygrid = coordinate[1]
-
         entry_point = (-math.sqrt(self.radius**2 - ygrid**2), ygrid)
-
         if not math.isclose(angle, math.pi / 2, abs_tol=epsilon):
             b = ygrid - xgrid * math.tan(angle)
             a = math.tan(angle)
-            xexit_root1, xexit_root2 = np.roots((1 + a**2, 2 * a * b, b**2 - self.radius**2))
+            xexit_root1, xexit_root2 = np.roots(
+                (1 + a**2, 2 * a * b, b**2 - self.radius**2)
+            )
             yexit_root1 = a * xexit_root1 + b
             yexit_root2 = a * xexit_root2 + b
             if yexit_root2 >= yexit_root1:  # We pick the point above
@@ -135,34 +105,28 @@ class Gridded_circle:
                 exit_point = (xexit_root1, yexit_root1)
         else:
             exit_point = (xgrid, math.sqrt(self.radius**2 - xgrid**2))
-
         return entry_point, exit_point
 
-    def get_path_length(self, grid_point, angle):
-        """
-        return the path length
-
-        This is the pathlength of a horizontal line entering the circle at the
-        same height to the grid point then exiting at angle angle
+    def _get_path_length(self, grid_point, angle):
+        """Return the path length of a horizontal line entering the
+        circle at the same height to the grid point then exiting at
+        angle.
 
         Parameters
         ----------
-        grid_point double of floats
-          the coordinate inside the circle
-
-        angle float
-          the angle of the output beam
-
-        radius
-          the radius of the circle
+        grid_point : double of floats
+            The coordinate inside the circle.
+        angle : float
+            The angle of the output beam in degrees.
 
         Returns
         -------
-        floats total distance, primary distance and secondary distance
-
+        (total distance, primary distance, secondary distance): tuple of floats
+            The tuple containing three floats,
+            which are the total distance, entry distance and exit distance.
         """
-
-        # move angle a tad above zero if it is zero to avoid it having the wrong sign due to some rounding error
+        # move angle a tad above zero if it is zero
+        # to avoid it having the wrong sign due to some rounding error
         angle_delta = 0.000001
         if angle == float(0):
             angle = angle + angle_delta
@@ -172,15 +136,51 @@ class Gridded_circle:
         total_distance = primary_distance + secondary_distance
         return total_distance, primary_distance, secondary_distance
 
+    def set_distances_at_angle(self, angle):
+        """Given an angle, set the distances from the grid points to the
+        entry and exit coordinates.
 
-def _cve_brute_force(diffraction_data, mud):
-    """
-    compute cve for the given mud on a global grid using the brute-force method
-    assume mu=mud/2, given that the same mu*D yields the same cve and D/2=1
-    """
+        Parameters
+        ----------
+        angle : float
+            The angle of the output beam in degrees.
+        """
+        self.primary_distances = []
+        self.secondary_distances = []
+        self.distances = []
+        for coord in self.grid:
+            distance, primary, secondary = self._get_path_length(coord, angle)
+            self.distances.append(distance)
+            self.primary_distances.append(primary)
+            self.secondary_distances.append(secondary)
+
+    def set_muls_at_angle(self, angle):
+        """Compute muls = exp(-mu*distance) for a given angle.
+
+        Parameters
+        ----------
+        angle : float
+            The angle of the output beam in degrees.
+        """
+        mu = self.mu
+        self.muls = []
+        if len(self.distances) == 0:
+            self.set_distances_at_angle(angle)
+        for distance in self.distances:
+            self.muls.append(np.exp(-mu * distance))
 
+
+def _cve_brute_force(input_pattern, mud):
+    """Compute cve for the given mud on a global grid using the brute-
+    force method.
+
+    Assume mu=mud/2, given that the same mu*D yields the same cve and
+    D/2=1.
+    """
     mu_sample_invmm = mud / 2
-    abs_correction = Gridded_circle(mu=mu_sample_invmm)
+    abs_correction = Gridded_circle(
+        n_points_on_diameter=N_POINTS_ON_DIAMETER, mu=mu_sample_invmm
+    )
     distances, muls = [], []
     for angle in TTH_GRID:
         abs_correction.set_distances_at_angle(angle)
@@ -190,115 +190,118 @@ def _cve_brute_force(diffraction_data, mud):
     distances = np.array(distances) / abs_correction.total_points_in_grid
     muls = np.array(muls) / abs_correction.total_points_in_grid
     cve = 1 / muls
-
-    cve_do = Diffraction_object(wavelength=diffraction_data.wavelength)
-    cve_do.insert_scattering_quantity(
-        TTH_GRID,
-        cve,
-        "tth",
-        metadata=diffraction_data.metadata,
-        name=f"absorption correction, cve, for {diffraction_data.name}",
-        wavelength=diffraction_data.wavelength,
+    cve_do = DiffractionObject(
+        xarray=TTH_GRID,
+        yarray=cve,
+        xtype="tth",
+        wavelength=input_pattern.wavelength,
         scat_quantity="cve",
+        name=f"absorption correction, cve, for {input_pattern.name}",
+        metadata=input_pattern.metadata,
     )
     return cve_do
 
 
-def _cve_polynomial_interpolation(diffraction_data, mud):
-    """
-    compute cve using polynomial interpolation method, raise an error if mu*D is out of the range (0.5 to 6)
-    """
-
-    if mud > 6 or mud < 0.5:
-        raise ValueError(
-            f"mu*D is out of the acceptable range (0.5 to 6) for polynomial interpolation. "
-            f"Please rerun with a value within this range or specifying another method from {* CVE_METHODS, }."
+def _cve_polynomial_interpolation(input_pattern, mud):
+    """Compute cve using polynomial interpolation method, default to
+    brute- force computation if mu*D is out of the range (0.5 to 7)."""
+    if mud > 7 or mud < 0.5:
+        warnings.warn(
+            f"Input mu*D = {mud} is out of the acceptable range "
+            f"({np.min(MUD_LIST)} to {np.max(MUD_LIST)}) "
+            f"for polynomial interpolation. "
+            f"Proceeding with brute-force computation. "
         )
-    coeff_a, coeff_b, coeff_c, coeff_d, coeff_e = [
-        interpolation_function(mud) for interpolation_function in INTERPOLATION_FUNCTIONS
-    ]
-    muls = np.array(coeff_a * MULS**4 + coeff_b * MULS**3 + coeff_c * MULS**2 + coeff_d * MULS + coeff_e)
-    cve = 1 / muls
+        return _cve_brute_force(input_pattern, mud)
 
-    cve_do = Diffraction_object(wavelength=diffraction_data.wavelength)
-    cve_do.insert_scattering_quantity(
-        TTH_GRID,
-        cve,
-        "tth",
-        metadata=diffraction_data.metadata,
-        name=f"absorption correction, cve, for {diffraction_data.name}",
-        wavelength=diffraction_data.wavelength,
+    coeffs = np.array([f(mud) for f in INTERPOLATION_FUNCTIONS])
+    muls = np.polyval(coeffs, MULS)
+    cve = 1 / muls
+    cve_do = DiffractionObject(
+        xarray=TTH_GRID,
+        yarray=cve,
+        xtype="tth",
+        wavelength=input_pattern.wavelength,
         scat_quantity="cve",
+        name=f"absorption correction, cve, for {input_pattern.name}",
+        metadata=input_pattern.metadata,
     )
     return cve_do
 
 
 def _cve_method(method):
-    """
-    retrieve the cve computation function for the given method
-    """
+    """Retrieve the cve computation function for the given method."""
     methods = {
         "brute_force": _cve_brute_force,
         "polynomial_interpolation": _cve_polynomial_interpolation,
     }
     if method not in CVE_METHODS:
-        raise ValueError(f"Unknown method: {method}. Allowed methods are {*CVE_METHODS, }.")
+        raise ValueError(
+            f"Unknown method: {method}. "
+            f"Allowed methods are {*CVE_METHODS, }."
+        )
     return methods[method]
 
 
-def compute_cve(diffraction_data, mud, method="polynomial_interpolation"):
-    f"""
-    compute and interpolate the cve for the given diffraction data and mud using the selected method
+def compute_cve(
+    input_pattern, mud, method="polynomial_interpolation", xtype="tth"
+):
+    f"""Compute and interpolate the cylindrical volume effect (cve)
+    for the given input diffraction data and mu*D
+    using the selected method.
+
     Parameters
     ----------
-    diffraction_data Diffraction_object
-      the diffraction pattern
-    mud float
-      the mu*D of the diffraction object, where D is the diameter of the circle
-    method str
-      the method used to calculate cve, must be one of {* CVE_METHODS, }
+    input_pattern : DiffractionObject
+        The input diffraction object to which the cve will be applied.
+    mud : float
+        The mu*D value of the diffraction object,
+        where D is the diameter of the circle.
+    xtype : str
+        The quantity on the independent variable axis,
+        allowed values are {*XQUANTITIES, }.
+    method : str
+        The method used to calculate cve, must be one of {*CVE_METHODS, }.
 
     Returns
     -------
-    the diffraction object with cve curves
+    cve_do: DiffractionObject
+        The diffraction object that contains the cve to be applied.
     """
-
     cve_function = _cve_method(method)
-    abdo_on_global_tth = cve_function(diffraction_data, mud)
-    global_tth = abdo_on_global_tth.on_tth[0]
-    cve_on_global_tth = abdo_on_global_tth.on_tth[1]
-    orig_grid = diffraction_data.on_tth[0]
-    newcve = np.interp(orig_grid, global_tth, cve_on_global_tth)
-    cve_do = Diffraction_object(wavelength=diffraction_data.wavelength)
-    cve_do.insert_scattering_quantity(
-        orig_grid,
-        newcve,
-        "tth",
-        metadata=diffraction_data.metadata,
-        name=f"absorption correction, cve, for {diffraction_data.name}",
-        wavelength=diffraction_data.wavelength,
+    cve_do_on_global_grid = cve_function(input_pattern, mud)
+    orig_grid = input_pattern.on_xtype(xtype)[0]
+    global_xtype = cve_do_on_global_grid.on_xtype(xtype)[0]
+    cve_on_global_xtype = cve_do_on_global_grid.on_xtype(xtype)[1]
+    newcve = np.interp(orig_grid, global_xtype, cve_on_global_xtype)
+    cve_do = DiffractionObject(
+        xarray=orig_grid,
+        yarray=newcve,
+        xtype=xtype,
+        wavelength=input_pattern.wavelength,
         scat_quantity="cve",
+        name=f"absorption correction, cve, for {input_pattern.name}",
+        metadata=input_pattern.metadata,
     )
-
     return cve_do
 
 
-def apply_corr(diffraction_pattern, absorption_correction):
-    """
-    Apply absorption correction to the given diffraction object modo with the correction diffraction object abdo
+def apply_corr(input_pattern, absorption_correction):
+    """Apply absorption correction to the given diffraction object with
+    the correction diffraction object.
 
     Parameters
     ----------
-    diffraction_pattern Diffraction_object
-      the input diffraction object to which the cve will be applied
-    absorption_correction Diffraction_object
-      the diffraction object that contains the cve to be applied
+    input_pattern : DiffractionObject
+        The input diffraction object to which the cve will be applied.
+    absorption_correction : DiffractionObject
+        The diffraction object that contains the cve to be applied.
 
     Returns
     -------
-    a corrected diffraction object with the correction applied through multiplication
-
+    corrected_pattern: DiffractionObject
+        The corrected diffraction object
+        with the correction applied through multiplication.
     """
-
-    corrected_pattern = diffraction_pattern * absorption_correction
+    corrected_pattern = input_pattern * absorption_correction
     return corrected_pattern