compute mu

news/mu.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* function to compute x-ray attenuation coefficient (mu) using XrayDB
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

requirements/conda.txt

@@ -1 +1,2 @@
 numpy
+xraydb

requirements/pip.txt

@@ -1 +1,2 @@
 numpy
+xraydb

src/diffpy/utils/tools.py

@@ -3,6 +3,8 @@
 from copy import copy
 from pathlib import Path
 
+from xraydb import material_mu
+
 
 def _stringify(obj):
     """
@@ -131,3 +133,32 @@ def get_package_info(package_names, metadata=None):
         pkg_info.update({package: importlib.metadata.version(package)})
     metadata["package_info"] = pkg_info
     return metadata
+
+
+def compute_mu_using_xraydb(sample_composition, energy, density=None, packing_fraction=1):
+    """Compute the attenuation coefficient (mu) using the XrayDB database.
+
+    Computes mu based on the sample composition and energy.
+    If density is not provided, a standard reference density (e.g., 0.987 g/cm^3 for H2O) is used.
+    User can provide either a measured density or an estimated packing fraction (with a standard density).
+    It is recommended to specify the density, especially for materials like ZrO2, where it can vary.
+    Reference: https://xraypy.github.io/XrayDB/python.html#xraydb.material_mu.
+
+    Parameters
+    ----------
+    sample_composition : str
+        The chemical formula or the name of the material.
+    energy : float
+        The energy in eV.
+    density : float, optional, Default is None
+        The mass density of the packed powder/sample in gr/cm^3. If None, a standard density from XrayDB is used.
+    packing_fraction : float, optional, Default is 1
+        The fraction of sample in the capillary (between 0 and 1).
+
+    Returns
+    -------
+    mu : float
+        The attenuation coefficient mu in mm^{-1}.
+    """
+    mu = material_mu(sample_composition, energy, density=density, kind="total") * packing_fraction / 10
+    return mu

tests/test_tools.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from diffpy.utils.tools import get_package_info, get_user_info
+from diffpy.utils.tools import compute_mu_using_xraydb, get_package_info, get_user_info
 
 # def _setup_dirs(monkeypatch, user_filesystem):
 #     home_dir, cwd_dir = user_filesystem.home_dir, user_filesystem.cwd_dir
@@ -189,3 +189,65 @@ def test_get_package_info(monkeypatch, inputs, expected):
     )
     actual_metadata = get_package_info(inputs[0], metadata=inputs[1])
     assert actual_metadata == expected
+
+
+@pytest.mark.parametrize(
+    "inputs, expected_mu",
+    [
+        # Test whether the function returns the correct mu
+        (  # C1: No density or packing fraction provided, expect to compute mu based on standard density
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": None,
+                "packing_fraction": 1,
+            },
+            0.5330,
+        ),
+        (  # C2: Packing fraction (=0.5) provided only, expect to return half of mu based on standard density
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": None,
+                "packing_fraction": 0.5,
+            },
+            0.2665,
+        ),
+        (  # C3: Density provided only, expect to compute mu based on density
+            # 1. Standard density provided, expect to return the same mu as C1
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": 0.997,
+                "packing_fraction": 1,
+            },
+            0.5330,
+        ),
+        (  # 2. Lower density for H2O (half of standard), expect to return half of mu based on standard density
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": 0.4985,
+                "packing_fraction": 1,
+            },
+            0.2665,
+        ),
+        (  # C4: Both standard density and packing fraction are provided, expect to compute the same mu as C2
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": 0.997,
+                "packing_fraction": 0.5,
+            },
+            0.2665,
+        ),
+    ],
+)
+def test_compute_mu_using_xraydb(inputs, expected_mu):
+    actual_mu = compute_mu_using_xraydb(
+        inputs["sample_composition"],
+        inputs["energy"],
+        density=inputs["density"],
+        packing_fraction=inputs["packing_fraction"],
+    )
+    assert actual_mu == pytest.approx(expected_mu, rel=0.01, abs=0.1)