Merge pull request #163 from yucongalicechen/functions-docs

docs: for functions module

Author: sbillinge

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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/examples/zro2_mo.xy doc/source/examples/example_data/zro2_mo.xy

@@ -0,0 +1,10 @@
+.. _Examples:
+
+:tocdepth: -1
+
+Examples
+########
+Landing page for diffpy.labpdfproc examples.
+
+.. toctree::
+    functions_example

doc/source/examples/examples.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.

doc/source/examples/functions_example.rst

@@ -34,6 +34,8 @@ Table of contents
 
    license
    release
+   Utilities <utilities/utilities>
+   Examples <examples/examples>
    Package API <api/diffpy.labpdfproc>
 
 =======

doc/source/index.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 <Functions Example>`.

doc/source/utilities/functions_utility.rst

@@ -0,0 +1,13 @@
+.. _Utilities:
+
+:tocdepth: -1
+
+Utilities
+#########
+Overview of utilities offered by ``diffpy.labpdfproc``.
+Check the :ref:`examples<Examples>` provided for how to use these.
+
+.. contents::
+   :depth: 2
+
+.. include:: functions_utility.rst

doc/source/utilities/utilities.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Documentation for functions module.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>