diff --git a/doc/source/api/diffpy.labpdfproc.rst b/doc/source/api/diffpy.labpdfproc.rst index 941776e..a3f53e1 100644 --- a/doc/source/api/diffpy.labpdfproc.rst +++ b/doc/source/api/diffpy.labpdfproc.rst @@ -35,14 +35,6 @@ diffpy.labpdfproc.tools module :undoc-members: :show-inheritance: -diffpy.labpdfproc.mud_calculator module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: diffpy.labpdfproc.mud_calculator - :members: - :undoc-members: - :show-inheritance: - diffpy.labpdfproc.labpdfprocapp module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/examples/zro2_mo.xy b/doc/source/examples/example_data/zro2_mo.xy similarity index 100% rename from doc/examples/zro2_mo.xy rename to doc/source/examples/example_data/zro2_mo.xy diff --git a/doc/source/examples/examples.rst b/doc/source/examples/examples.rst new file mode 100644 index 0000000..6e7d024 --- /dev/null +++ b/doc/source/examples/examples.rst @@ -0,0 +1,10 @@ +.. _Examples: + +:tocdepth: -1 + +Examples +######## +Landing page for diffpy.labpdfproc examples. + +.. toctree:: + functions_example diff --git a/doc/source/examples/functions_example.rst b/doc/source/examples/functions_example.rst new file mode 100644 index 0000000..cc833ea --- /dev/null +++ b/doc/source/examples/functions_example.rst @@ -0,0 +1,74 @@ +.. _Functions Example: + +:tocdepth: -1 + +Functions Example +################# + +This example will demonstrate how to use ``diffpy.labpdfproc.functions`` module independently +to apply absorption correction to your 1D diffraction data. + +1. First, you will need to prepare and load your input diffraction data. +For example, if you want to load data from ``zro2_mo.xy`` in the ``example_data`` directory, you can write: + +.. code-block:: python + + from diffpy.utils.parsers.loaddata import loadData + from diffpy.utils.diffraction_objects import DiffractionObject + + filepath = "../example_data/zro2_mo.xy" + xarray, yarray = loadData(filepath, unpack=True) + input_pattern = DiffractionObject( + xarray=xarray, + yarray=yarray, + xtype="tth", + wavelength=0.7, + scat_quantity="x-ray", + name="input diffraction data", + metadata={"beamline": "28ID-2"}, + ) + +For the full tutorial, please refer to https://www.diffpy.org/diffpy.utils/examples/diffraction_objects_example.html. + +2. Assume you have created your ``input_pattern`` and specified mu*D value as ``muD`` (e.g., ``muD=2``). +You can now compute the absorption correction (cve) for the given mu*D using the ``compute_cve`` function, +apply it to your input pattern, and save the corrected file. + +.. code-block:: python + + from diffpy.labpdfproc.functions import apply_corr, compute_cve + absorption_correction = compute_cve(input_pattern, muD) # compute cve, default method is "polynomial_interpolation" + corrected_pattern = apply_corr(input_pattern, absorption_correction) # apply cve correction + corrected_data.dump("corrected pattern.chi", xtype="tth") # save the corrected pattern + +If you want to use brute-force computation instead, you can replace the first line with: + +.. code-block:: python + + absorption_correction = compute_cve(input_pattern, muD, method="brute_force") + +3. Now, you can visualize the effect of the absorption correction +by plotting the original and corrected diffraction patterns. + +.. code-block:: python + + import matplotlib.pyplot as plt + plt.plot(input_pattern.xarray, input_pattern.yarray, label="Original Intensity") + plt.plot(corrected_pattern.xarray, corrected_pattern.yarray, label="Corrected Intensity") + plt.xlabel("tth (degrees)") + plt.ylabel("Intensity") + plt.legend() + plt.title("Original vs. Corrected Intensity") + plt.show() + +4. You can modify the global parameters +``N_POINTS_ON_DIAMETER`` (the number of points on each diameter to sample the circle) +and ``TTH_GRID`` (the range of angles) when using the brute-force method. + +To speed up computation, you can reduce the range of ``TTH_GRID``. You can also increase ``N_POINTS_ON_DIAMETER`` +for better accuracy, but keep in mind that this will increase computation time. +For optimal results, we recommend setting it to an even number. + +Currently, the interpolation coefficients were computed using ``N_POINTS_ON_DIAMETER=2000``, +which ensures good accuracy within the mu*D range of 0.5 to 6. +This value also provides flexibility if we decide to extend the interpolation range in the future. diff --git a/doc/source/index.rst b/doc/source/index.rst index 7fc14b4..1de5c3f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -34,6 +34,8 @@ Table of contents license release + Utilities + Examples Package API ======= diff --git a/doc/source/utilities/functions_utility.rst b/doc/source/utilities/functions_utility.rst new file mode 100644 index 0000000..6b15422 --- /dev/null +++ b/doc/source/utilities/functions_utility.rst @@ -0,0 +1,23 @@ +.. _Functions Utility: + +Functions Utility +================= + +The ``diffpy.labpdfproc.functions`` module provides tools +for computing and applying absorption correction (cve) to 1D diffraction patterns. + +- ``Gridded_circle``: This class supports absorption correction by + creating a uniform grid of points within a circle for a given radius and mu (linear absorption coefficient), + and computing the path length and effective volume for each grid point at a given angle. + +- ``compute_cve``: This function computes the absorption correction curve for a given mu*D + (absorption coefficient mu and capillary diameter D). + For brute force computation, it averages the effective volume across all grid points, + then computes the cve values as the reciprocal of this average. + For polynomial interpolation, it uses pre-computed coefficients to quickly interpolate cve values for a given mu*D. + Polynomial interpolation is available for mu*D values between 0.5-6. + +- ``apply_corr``: This function applies the computed absorption correction to the input diffraction pattern + by multiplying it with the computed cve, resulting in a corrected diffraction pattern. + +For a more in-depth tutorial for how to use these tools, click :ref:`here `. diff --git a/doc/source/utilities/utilities.rst b/doc/source/utilities/utilities.rst new file mode 100644 index 0000000..715063b --- /dev/null +++ b/doc/source/utilities/utilities.rst @@ -0,0 +1,13 @@ +.. _Utilities: + +:tocdepth: -1 + +Utilities +######### +Overview of utilities offered by ``diffpy.labpdfproc``. +Check the :ref:`examples` provided for how to use these. + +.. contents:: + :depth: 2 + +.. include:: functions_utility.rst diff --git a/news/functions-docs.rst b/news/functions-docs.rst new file mode 100644 index 0000000..8142dc4 --- /dev/null +++ b/news/functions-docs.rst @@ -0,0 +1,23 @@ +**Added:** + +* Documentation for functions module. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +*