Feature/mnist (#47)

* Refactor UDCT and related components for improved clarity and functionality

- Updated the UDCT class to support both angular_wedges_config and num_scales/wedges_per_direction parameters for enhanced flexibility in configuration.
- Introduced MUDCTCoefficients type for monogenic transforms, improving type safety and clarity in the codebase.
- Enhanced error messages for invalid angular wedge configurations, providing clearer guidance for users.
- Updated documentation to reflect changes in parameter handling and added examples for better usability.
- Improved test coverage for UDCT and MUDCT functionalities, ensuring robustness and correctness across various configurations.

* Enhance consistency and clarity in NumPy and PyTorch module exports

- Added pylint comments to suppress duplicate code warnings in both NumPy and PyTorch __init__.py files, indicating intentional duplication for shared API.
- Updated the __all__ list in both modules to ensure consistent API exposure, aligning with the shared functionality between NumPy and PyTorch implementations.
- Improved documentation comments to clarify the rationale behind the similar exports, enhancing maintainability and understanding of the code structure.

* Update project configuration and add new example for UDCT

- Added 'data/' directory to .gitignore to exclude data files from version control.
- Updated pyproject.toml to include 'scikit-learn' as a dependency for enhanced functionality.
- Enhanced documentation requirements by adding 'torchvision' to docs/requirements.txt for improved image processing capabilities.
- Introduced a new example script 'plot_10_udct_mnist.py' demonstrating the use of UDCT for image classification on the MNIST dataset, showcasing the model architecture and training process.

* Enhance type checking and update example for UDCT

- Updated `pyproject.toml` to include `torchvision` in mypy overrides for improved type checking.
- Modified `docs/requirements.txt` to ensure `torchvision` is included for documentation builds.
- Refactored `plot_10_udct_mnist.py` to implement a two-layer MLP for classification, improving model architecture clarity and performance.
- Updated comments and documentation within the example script for better understanding and maintainability.

* Enhance UDCT example and documentation

- Updated the `plot_10_udct_mnist.py` script to return both average loss and accuracy during training and testing, improving performance metrics tracking.
- Enhanced the visualization section to include separate subplots for training/testing loss and accuracy, providing clearer insights into model performance.
- Added `:no-index:` directive in `curvelets.torch` documentation to prevent indexing, streamlining documentation navigation.

* Enhance UDCT documentation and refactor code

- Added documentation for the `UDCTModule` class in `curvelets.torch`, improving clarity on its usage and functionality.
- Refactored the `_UDCTFunction` class to remove the unused `transform_type` parameter, streamlining the API and enhancing code clarity.
- Updated the plotting script `plot_10_udct_mnist.py` for better readability by formatting plot commands across multiple lines.

* Update training configuration in UDCT MNIST example

- Increased the number of training epochs from 2 to 10 in `plot_10_udct_mnist.py` to enhance model performance.
- Updated comments and section headers for improved clarity and organization throughout the script.

* Remove outdated comments from UDCT MNIST example script

- Deleted unnecessary comments and results section in `plot_10_udct_mnist.py` to streamline the code and improve readability.
- Focused on enhancing the clarity of the plotting functionality without extraneous information.

* Add sphinx_gallery_thumbnail_number comments to example scripts

- Introduced `sphinx_gallery_thumbnail_number` comments in multiple example scripts to enhance documentation and improve visual representation in the gallery.
- Updated `plot_01_zone_plate.py`, `plot_02_direction_resolution.py`, `plot_03_direction_disk.py`, `plot_04_meyer_wavelet.py`, `plot_05_curvelet_vs_wavelet.py`, and `plot_10_udct_mnist.py` to include these comments for better organization and clarity in the generated documentation.

* Implement tensor transfer functionality in UDCTModule and UDCT

- Added the `_apply` method in `UDCTModule` to facilitate the application of functions to internal tensors during device transfers.
- Introduced `apply_to_tensors` method in `UDCT` for applying functions to all internal tensors, ensuring proper handling during device and dtype changes.
- Created unit tests for the `_apply` method in `test_udct_module_apply.py` to verify correct tensor dtype transfers and functionality after conversions.

* Update window_threshold default value in UDCTModule from 1e-6 to 1e-5

- Modified the default value of the `window_threshold` parameter in the `UDCTModule` class to improve performance and storage efficiency.
- Ensured consistency in parameter documentation to reflect the updated default value.

Author: cako

.gitignore

@@ -4,6 +4,7 @@ sg_execution_times.rst
 playground/
 .cursor/
 references
+data/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/curvelet_faqs.rst

@@ -33,7 +33,7 @@ There are three flavors of the discrete curvelet transform with publicly availab
 As of 2026, any non-academic use of the CurveLab Toolbox requires a commercial license. Any library which ports or converts Curvelab code to another language is also subject to Curvelab's license.
 While this does not include libraries which wrap the CurveLab toolbox and therefore do not contain any source code of Curvelab, their usage still requires Curvelab and therefore its license. Such wrappers include `curvelops <https://github.com/PyLops/curvelops>`_, `PyCurvelab <https://github.com/slimgroup/PyCurvelab>`_, both MIT licensed.
 
-A third flavor is the **Uniform Discrete Curvelet Transform (UDCT)** which does not have the same restrictive license as the FDCT. The UDCT was first implemented in MATLAB (`ucurvmd <https://github.com/nttruong7/ucurvmd>`_ [dead link]) by one of its authors, Truong Nguyen. 
+A third flavor is the **Uniform Discrete Curvelet Transform (UDCT)** which does not have the same restrictive license as the FDCT. The UDCT was first implemented in MATLAB (`ucurvmd <https://github.com/nttruong7/ucurvmd>`_ [dead link]) by one of its authors, Truong Nguyen.
 
 **This library provides the first open-source, pure-Python implementation of the UDCT**, borrowing heavily from Nguyen's original implementation. The goal of this library is to allow industry professionals to use curvelets more easily. It also goes beyond the original implementation by providing a the support for complex signals, monogenic extension for real signals :cite:`Storath2010`, and a wavelet transform at the highest scale.
 

docs/requirements.txt

@@ -2,3 +2,4 @@
 # This ensures we use the smaller CPU-only build instead of the CUDA build
 --index-url https://download.pytorch.org/whl/cpu
 torch
+torchvision

docs/source/curvelets.torch.rst

@@ -5,3 +5,8 @@ curvelets.torch package
    :members:
    :show-inheritance:
    :undoc-members:
+   :no-index:
+
+.. autoclass:: curvelets.torch.UDCTModule
+   :members:
+   :show-inheritance:

examples/plot_01_zone_plate.py

@@ -3,6 +3,8 @@
 ==========
 """
 
+# sphinx_gallery_thumbnail_number = 2
+
 from __future__ import annotations
 
 # %%
@@ -43,7 +45,6 @@
 ax.set(title="Input")
 
 # %%
-# sphinx_gallery_thumbnail_number = 2
 fig, ax = plt.subplots(figsize=(4, 3))
 im = ax.imshow(zone_plate_inv.T, **opts)
 _, cb = create_colorbar(im=im, ax=ax)

examples/plot_02_direction_resolution.py

@@ -7,6 +7,8 @@
 fewer.
 """
 
+# sphinx_gallery_thumbnail_number = 2
+
 from __future__ import annotations
 
 import matplotlib.pyplot as plt
@@ -211,7 +213,6 @@ def plot_colorbars(
 C = C_sym
 colored_wins = color_windows(C, cmaps_dir=cmaps, color_low=color_low, color_bg=color_bg)
 
-# sphinx_gallery_thumbnail_number = 2
 fig = plt.figure(layout="constrained")
 fig.suptitle(title)
 gs = GridSpec(3, 2, figure=fig, height_ratios=[8, 1, 1])

examples/plot_03_direction_disk.py

@@ -6,6 +6,8 @@
 `Kymatio's Scattering disks <https://www.kymat.io/gallery_2d/plot_scattering_disk.html>`__.
 """
 
+# sphinx_gallery_thumbnail_number = 2
+
 from __future__ import annotations
 
 import matplotlib.pyplot as plt
@@ -62,7 +64,6 @@
 energy_c = apply_along_wedges(d_c, lambda w, *_: np.sqrt((np.abs(w) ** 2).mean()))
 
 # %%
-# sphinx_gallery_thumbnail_number = 2
 fig, ax = plt.subplots(figsize=(12, figsize_aspect * 8))
 ax.imshow(data.T, vmin=-vmax, vmax=vmax, **opts_space)
 overlay_arrows(kvecs, ax, arrowprops={"edgecolor": "w", "facecolor": "k"})

examples/plot_04_meyer_wavelet.py

@@ -8,6 +8,8 @@
 reconstruction of the original signal.
 """
 
+# sphinx_gallery_thumbnail_number = 4
+
 from __future__ import annotations
 
 # %%
@@ -135,7 +137,6 @@
 ky = fftshift(fftfreq(ny))
 
 # Create figure with 4 subplots
-# sphinx_gallery_thumbnail_number = 4
 fig, axs = plt.subplots(2, 2, figsize=(10, 10))
 axs = axs.flatten()
 

examples/plot_05_curvelet_vs_wavelet.py

@@ -7,6 +7,8 @@
 showing both frequency-domain windows and spatial coefficients.
 """
 
+# sphinx_gallery_thumbnail_number = 2
+
 from __future__ import annotations
 
 # %%
@@ -112,7 +114,6 @@
 }
 
 # Plot curvelet and wavelet windows
-# sphinx_gallery_thumbnail_number = 2
 n_curvelet_windows = len(curvelet_windows_scale1)
 n_wavelet_windows = len(wavelet_windows_scale1)
 n_cols = max(n_curvelet_windows, n_wavelet_windows)

examples/plot_07_monogenic_verification.py

@@ -67,7 +67,7 @@
 # Reproducing Formula
 # ###################
 #
-# According to :cite:`Storath2010`, the monogenic curvelet transform should satisfy
+# According to :cite:t:`Storath2010`, the monogenic curvelet transform should satisfy
 # the reproducing formula:
 #
 # .. math::