add packing fraction, add more tests

Author: yucongalicechen

src/diffpy/utils/tools.py

@@ -135,24 +135,30 @@ def get_package_info(package_names, metadata=None):
     return metadata
 
 
-def compute_mu_using_xraydb(sample, energy, density=None):
+def compute_mu_using_xraydb(sample_composition, energy, density=None, packing_fraction=1):
     """
-    compute mu using the XrayDB database
+    Compute the attenuation coefficient (mu) using the XrayDB database
 
+    This function calculates 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 str
-        the chemical formula or the name of the material
-    energy float
-        the energy in eV
-    density float or None
-        material density in gr/cm^3
+    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
     -------
     the attenuation coefficient mu in mm^{-1}
     """
-    mu = material_mu(sample, energy, density=density, kind="total") / 10
+    mu = material_mu(sample_composition, energy, density=density, kind="total") * packing_fraction / 10
     return mu

tests/test_tools.py

@@ -191,7 +191,25 @@ def test_get_package_info(monkeypatch, inputs, expected):
     assert actual_metadata == expected
 
 
-def test_compute_mu_using_xraydb():
-    sample, energy, density = "ZrO2", 17445.362740959618, 1.009
-    actual_mu = compute_mu_using_xraydb(sample, energy, density=density)
-    assert actual_mu == pytest.approx(1.252, rel=1e-4, abs=0.1)
+params_mu = [
+    # C1: user didn't specify density or packing fraction
+    ({"sample_composition": "H2O", "energy": 10000, "density": None, "packing_fraction": 1}, 0.5330),
+    # C2: user specified packing fraction only
+    ({"sample_composition": "H2O", "energy": 10000, "density": None, "packing_fraction": 0.5}, 0.2665),
+    # C3: user specified density only
+    ({"sample_composition": "H2O", "energy": 10000, "density": 0.997, "packing_fraction": 1}, 0.5330),
+    ({"sample_composition": "H2O", "energy": 10000, "density": 0.4985, "packing_fraction": 1}, 0.2665),
+    # C4: user specified a standard density and a packing fraction
+    ({"sample_composition": "H2O", "energy": 10000, "density": 0.997, "packing_fraction": 0.5}, 0.2665),
+]
+
+
+@pytest.mark.parametrize("inputs, expected", params_mu)
+def test_compute_mu_using_xraydb(inputs, expected):
+    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, rel=0.01, abs=0.1)