From b5624cf43251f4129ab21504eeed60fc68c56c88 Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Sun, 21 Dec 2025 13:23:25 -0600 Subject: [PATCH 1/4] absportion doc checkpoint --- docs/source/examples/examples.rst | 1 + docs/source/examples/mu_calc_examples.rst | 68 +++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 docs/source/examples/mu_calc_examples.rst diff --git a/docs/source/examples/examples.rst b/docs/source/examples/examples.rst index 5a30d3b..f0cd8ca 100644 --- a/docs/source/examples/examples.rst +++ b/docs/source/examples/examples.rst @@ -12,3 +12,4 @@ Landing page for diffpy.utils examples. resample_example parsers_example tools_example + mu_calc_examples diff --git a/docs/source/examples/mu_calc_examples.rst b/docs/source/examples/mu_calc_examples.rst new file mode 100644 index 0000000..5f81156 --- /dev/null +++ b/docs/source/examples/mu_calc_examples.rst @@ -0,0 +1,68 @@ +.. _mu calc Example: + +:tocdepth: -1 + +Lab-collected PDF Correction Examples +###################################### + +These examples will demonstrate how to correct X-ray diffraction data +to compute pair distribution functions (PDFs) from lab-collected X-ray +diffraction experiments. + +When calculating PDFs using ``diffpy.pdfgetx``, +a key assumption is that the X-ray absorption is negligible. +This is frequently the case for high-energy X-rays. +However, this must be corrected for when using low energy +X-rays, such as those from a laboratory source. +To correct for X-ray absorption, the X-ray absorption coefficient, μ, +must be known. + +.. admonition:: Correction methods for X-ray absorption + + Correcting your diffraction data can be done in **three + different ways** using ``diffpy.utils``. + + 1. **Using a known μ value**: If the X-ray absorption coefficient μ + is already known for your sample, supply this value along with the capillary diameter + to directly correct the diffraction data. + 2. **Using a "z-scan" measurement**: Perform a z-scan measurement + on the sample to measure X-ray absorption and extract + the corresponding μ value, which is then used to correct the data. + 3. **Using tabulated values**: Find μ using tabulated absorption coefficients based on the sample + composition, density, and X-ray energy, and use this value to apply the + absorption correction. + +Using a known μ value +--------------------- + +example here + +Using a "z-scan" measurement +---------------------------- + +Example here + +Using tabulated values +---------------------------- + +The function to calculate μ from tabulated values is located +in the ``diffpy.utils.tools`` module. So first, import the function, + +.. code-block:: python + + from diffpy.utils.tools import compute_mu_using_xraydb + +To calculate μ, you need to know the sample composition, and X-ray energy, and sample mass density (g/cm\ :sup:`3`). + +.. code-block:: python + + composition = "Fe2O3" + energy_keV = 17.45 # Mo K-alpha energy + sample_mass_density = 5.24 # g/cm^3 + +Now calculate μ using the ``compute_mu_using_xraydb`` function. + +.. code-block:: python + + mu_density = compute_mu_using_xraydb(composition, energy_keV, sample_mass_density=sample_mass_density) + print(f"Calculated mu from sample_mass_density: {mu_density} cm^-1") From ff5a6aa40468cedf64ebf31e5b0005f3076c071f Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Sun, 21 Dec 2025 13:33:14 -0600 Subject: [PATCH 2/4] news --- news/mu-ex.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 news/mu-ex.rst diff --git a/news/mu-ex.rst b/news/mu-ex.rst new file mode 100644 index 0000000..698a993 --- /dev/null +++ b/news/mu-ex.rst @@ -0,0 +1,23 @@ +**Added:** + +* Add examples for calculating absorption coefficient. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* From 40f7a73db72e34ba2e9bfc4e1eb035108a1f06fd Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Mon, 22 Dec 2025 11:18:24 -0600 Subject: [PATCH 3/4] add z-scan example placeholder --- docs/source/examples/mu_calc_examples.rst | 119 ++++++++++++++++------ 1 file changed, 87 insertions(+), 32 deletions(-) diff --git a/docs/source/examples/mu_calc_examples.rst b/docs/source/examples/mu_calc_examples.rst index 5f81156..87ed127 100644 --- a/docs/source/examples/mu_calc_examples.rst +++ b/docs/source/examples/mu_calc_examples.rst @@ -2,48 +2,97 @@ :tocdepth: -1 -Lab-collected PDF Correction Examples -###################################### +X-ray Absorption Coefficient (μ) Examples +######################################### -These examples will demonstrate how to correct X-ray diffraction data -to compute pair distribution functions (PDFs) from lab-collected X-ray -diffraction experiments. +These examples will demonstrate how to calculate the X-ray absorption +coefficient, μ, using different methods provided in ``diffpy.utils``. -When calculating PDFs using ``diffpy.pdfgetx``, -a key assumption is that the X-ray absorption is negligible. -This is frequently the case for high-energy X-rays. -However, this must be corrected for when using low energy -X-rays, such as those from a laboratory source. -To correct for X-ray absorption, the X-ray absorption coefficient, μ, -must be known. -.. admonition:: Correction methods for X-ray absorption +.. admonition:: Methods for obtaining X-ray absorption coefficient - Correcting your diffraction data can be done in **three + Obtaining μ can be done in **two different ways** using ``diffpy.utils``. - 1. **Using a known μ value**: If the X-ray absorption coefficient μ - is already known for your sample, supply this value along with the capillary diameter - to directly correct the diffraction data. - 2. **Using a "z-scan" measurement**: Perform a z-scan measurement - on the sample to measure X-ray absorption and extract - the corresponding μ value, which is then used to correct the data. - 3. **Using tabulated values**: Find μ using tabulated absorption coefficients based on the sample - composition, density, and X-ray energy, and use this value to apply the - absorption correction. + 1. **Using a "z-scan" measurement**: Perform a z-scan measurement + on the sample and use ``diffpy.utils.tools.compute_mud`` to calculate + μ. + 2. **Using tabulated values**: Given composition, density, and X-ray energy, + use ``diffpy.utils.tools.compute_mu_using_xraydb`` to calculate μ from + tabulated values. + +Why is μ Important? +----------------------- + +The X-ray absorption coefficient, μ, quantifies how much X-ray +radiation is absorbed by a material per unit length. It is a critical +parameter in many scientific techniques. + +For example, when calculating pair distribution functions (PDFs) +using ``diffpy.pdfgetx``, +a key assumption is that the X-ray absorption is negligible. +This is frequently the case for high-energy X-rays. However, +this must be corrected for when using low energy X-rays, such +as those from a laboratory source. To correct for X-ray absorption, +the X-ray absorption coefficient, μ, must be known. + +.. admonition:: Correcting for X-ray Absorption with ``diffpy.labpdfproc`` + + If your objective is to correct for X-ray absorption in PDF calculations, + please refer to our package ``diffpy.labpdfproc``. This package is specifically + designed to correct your laboratory X-ray PDF data for absorption effects. + More information can be found in the + `diffpy.labpdfproc documentation `_. -Using a known μ value ---------------------- -example here +Calculating μ from a "z-scan" Measurement +----------------------------------------- -Using a "z-scan" measurement ----------------------------- +.. note:: -Example here + The data we will be using for this example can be found here, + `FIXME `_. -Using tabulated values ----------------------------- +A "z-scan" measurement is the measured transmission of your X-ray incident beam +as a function of sample position. This is obtained by moving the sample +along the X-ray beam (z-direction) and recording the transmitted +intensity at each position. This measured data looks something like this, + +.. image:: ../images/FIXME + :alt: Example of a z-scan measurement. + :align: center + :width: 200px + +Using this z-scan data, you can calculate **μ·d**, where d is the inner diameter of +your sample capillary. To do this, simply pass your z-scan measurement to the ``compute_mud`` +function from the ``diffpy.utils.tools`` module. + + +First, import the ``compute_mud`` function, + +.. code-block:: python + + from diffpy.utils.tools import compute_mud + +Next, pass the filepath to the function, + +.. code-block:: python + + filepath = "zscan_example_data.txt" + capillary_diameter = 0.5 # mm + mud = compute_mud(filepath) + print(f"Calculated mu*d: {round(mud, 3)}") + print(f"Calculated mu: {round(mud / capillary_diameter, 3)} mm^-1") + +This will output the calculated value of μ·d, which is unitless, and μ in mm\ :sup:`-1`. + +.. code-block:: console + + Calculated mu*d: FIXME + Calculated mu: FIXME mm^-1 + +Calculating μ from Tabulated Values +----------------------------------- The function to calculate μ from tabulated values is located in the ``diffpy.utils.tools`` module. So first, import the function, @@ -65,4 +114,10 @@ Now calculate μ using the ``compute_mu_using_xraydb`` function. .. code-block:: python mu_density = compute_mu_using_xraydb(composition, energy_keV, sample_mass_density=sample_mass_density) - print(f"Calculated mu from sample_mass_density: {mu_density} cm^-1") + print(f"Calculated mu from sample_mass_density: {round(mu_density, 3)} mm^-1") + +This will output the calculated X-ray absorption coefficient, μ, in mm\ :sup:`-1`. + +.. code-block:: console + + Calculated mu from sample_mass_density: 13.967 mm^-1 From 89a55edcbda66e1e676cc7a303775b5dd805253d Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Mon, 22 Dec 2025 11:46:56 -0600 Subject: [PATCH 4/4] typo --- docs/source/examples/mu_calc_examples.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/examples/mu_calc_examples.rst b/docs/source/examples/mu_calc_examples.rst index 87ed127..88b8d8c 100644 --- a/docs/source/examples/mu_calc_examples.rst +++ b/docs/source/examples/mu_calc_examples.rst @@ -113,11 +113,11 @@ Now calculate μ using the ``compute_mu_using_xraydb`` function. .. code-block:: python - mu_density = compute_mu_using_xraydb(composition, energy_keV, sample_mass_density=sample_mass_density) - print(f"Calculated mu from sample_mass_density: {round(mu_density, 3)} mm^-1") + mu = compute_mu_using_xraydb(composition, energy_keV, sample_mass_density) + print(f"Calculated mu: {round(mu, 3)} mm^-1") This will output the calculated X-ray absorption coefficient, μ, in mm\ :sup:`-1`. .. code-block:: console - Calculated mu from sample_mass_density: 13.967 mm^-1 + Calculated mu: 13.967 mm^-1