docs: add functions examples, move files around to make docs appear correctly

Author: yucongalicechen

Diff for: doc/examples/functions_example.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 for: doc/source/api/diffpy.labpdfproc.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 for: doc/examples/example_data/zro2_mo.xy renamed to doc/source/examples/example_data/zro2_mo.xy

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

Diff for: doc/examples/examples.rst renamed to doc/source/examples/examples.rst

@@ -3,21 +3,21 @@
 Functions Utility
 =================
 
-The `diffpy.labpdfproc.functions` module provides tools
+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
+- ``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
+- ``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
+- ``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>`.