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

@@ -1,8 +1,11 @@
 import importlib.metadata
 import json
+import warnings
 from copy import copy
 from pathlib import Path
 
+from xraydb import material_mu
+
 
 def clean_dict(obj):
     """Remove keys from the dictionary where the corresponding value is None.
@@ -206,3 +209,47 @@ 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, sample_mass_density=None, packing_fraction=None):
+    """Compute the attenuation coefficient (mu) using the XrayDB database.
+
+    Computes mu based on the sample composition and energy.
+    User should provide a sample mass density or a packing fraction.
+    If neither density nor packing fraction is specified, or if both are specified, a ValueError will be raised.
+    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 of the incident x-rays in keV.
+    sample_mass_density : float, optional, Default is None
+        The mass density of the packed powder/sample in gr/cm^3.
+    packing_fraction : float, optional, Default is None
+        The fraction of sample in the capillary (between 0 and 1).
+
+    Returns
+    -------
+    mu : float
+        The attenuation coefficient mu in mm^{-1}.
+    """
+    if (sample_mass_density is None and packing_fraction is None) or (
+        sample_mass_density is not None and packing_fraction is not None
+    ):
+        raise ValueError(
+            "You must specify either sample_mass_density or packing_fraction, but not both. "
+            "Please rerun specifying only one."
+        )
+    if sample_mass_density is not None:
+        mu = material_mu(sample_composition, energy * 1000, density=sample_mass_density, kind="total") / 10
+    else:
+        warnings.warn(
+            "Warning: Density is set to None if a packing fraction is specified, "
+            "which may cause errors for some materials. "
+            "We recommend specifying sample mass density for now. "
+            "Auto-density calculation is coming soon."
+        )
+        mu = material_mu(sample_composition, energy * 1000, density=None, kind="total") * packing_fraction / 10
+    return mu

tests/test_tools.py

@@ -5,7 +5,12 @@
 
 import pytest
 
-from diffpy.utils.tools import check_and_build_global_config, get_package_info, get_user_info
+from diffpy.utils.tools import (
+    check_and_build_global_config,
+    compute_mu_using_xraydb,
+    get_package_info,
+    get_user_info,
+)
 
 
 @pytest.mark.parametrize(
@@ -160,3 +165,67 @@ 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: Composition, energy, and mass density provided, expect to get mu based on mass density
+            # 1. Fully dense mass density
+            {"sample_composition": "quartz", "energy": 10, "sample_mass_density": 2.65},
+            5.0368,
+        ),
+        (  # 2. Measured mass density
+            {
+                "sample_composition": "ZrO2",
+                "energy": 17.445,
+                "sample_mass_density": 1.009,
+            },
+            1.2522,
+        ),
+        (  # C2: Composition, energy, and packing fraction provided, expect to get mu based on packing fraction
+            # Reuse pattern from C1.1 here
+            {
+                "sample_composition": "quartz",
+                "energy": 10,
+                "packing_fraction": 0.5,
+            },
+            2.5184,
+        ),
+    ],
+)
+def test_compute_mu_using_xraydb(inputs, expected_mu):
+    actual_mu = compute_mu_using_xraydb(**inputs)
+    assert actual_mu == pytest.approx(expected_mu, rel=1e-6, abs=1e-4)
+
+
+@pytest.mark.parametrize(
+    "inputs",
+    [
+        # Test when the function raises ValueError
+        # C1: Both mass density and packing fraction are provided
+        (
+            {
+                "sample_composition": "quartz",
+                "energy": 10,
+                "sample_mass_density": 2.65,
+                "packing_fraction": 1,
+            }
+        ),
+        # C2: None of mass density or packing fraction are provided
+        (
+            {
+                "sample_composition": "quartz",
+                "energy": 10,
+            }
+        ),
+    ],
+)
+def test_compute_mu_using_xraydb_bad(inputs):
+    with pytest.raises(
+        ValueError,
+        match="You must specify either sample_mass_density or packing_fraction, but not both. "
+        "Please rerun specifying only one.",
+    ):
+        compute_mu_using_xraydb(**inputs)