Docs PDF and SGMA Examples #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

lukelowry merged 50 commits into main from dev

Jan 20, 2026

.gitignore

-Original file line number
+Diff line change
@@ Expand Up / @@ -4,3 +4,6 @@ build @@
     dist
     .vscode/settings.json
     .coverage
+    .benchmarks
+    benchmark_*.pdf
+    examples/.data_dir

.readthedocs.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,10 @@ @@
     # Required
     version: 2
+    # Build PDF
+    formats:
+      - pdf
     # Set the OS, Python version, and other tools you might need
     build:
       os: ubuntu-22.04
@@ Expand Down @@

CHANGELOG.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -6,64 +6,81 @@ All notable changes to this project will be documented in this file.
  
    The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,

    and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.

    [0.3.6] - 2026-01-18

    --------------------

    **Changed**

    - Improved library accessors for laplacians

    - Extended documentation

    - PDF available for documentation

    - More tests for validation

    **Added**

    - SGMA modal analysis tool and examples

    - Extensive examples of SGMA

    - Benchmark performance tests of analytical filters

    - Meshes for visualization (bunny, horse, brain)

    [0.3.5] - 2026-01-10

    --------------------

    Changed

    ~~~~~~~

    **Changed**

    - Expanded test suite to full code and branch coverage, including all edge cases and defensive branches.

    - Tests to do cover KLU wrapper, because it is not used in this version.

    [0.3.4] - 2026-01-06

    --------------------

    Changed

    ~~~~~~~

    - Migrated the entire test suite from `unittest` to `pytest` for a more modern, readable, and feature-rich testing framework. The tests are now included as an installable sub-package `sgwt.tests`.

    **Changed**

    - Migrated the entire test suite from ``unittest`` to ``pytest`` for a more modern, readable, and feature-rich testing framework. The tests are now included as an installable sub-package ``sgwt.tests``.

    Fixed

    ~~~~~

    - Resolved an issue where `DyConvolve.addbranch` would cause an unhandled error for negative branch weights. It now raises a descriptive `ValueError`.

    **Fixed**

    - Resolved an issue where ``DyConvolve.addbranch`` would cause an unhandled error for negative branch weights. It now raises a descriptive ``ValueError``.

    [0.3.3] - 2026-01-05

    ------------

    --------------------

    **Added**

    Added

    ~~~~~

    - New documentation section for Chebyshev approximation examples and benchmarks.

    - Lazy loading for built-in resources (Laplacians, Signals, Kernels) to improve import time and reduce memory usage.

    Fixed

    ~~~~~

    - Offset ``d_a`` of Kernel Fitted approximation correctly implemented

    **Fixed**

    - Offset ``d_a`` of Kernel Fitted approximation correctly implemented.

    - Documentation typos referring to ``VFKern`` instead of ``VFKernel``.

    [0.3.2] - 2026-01-03

    --------------------

    Added

    ~~~~~

    **Added**

    - ``CHANGELOG.rst`` to track project history.

    - ``CITATION.cff`` for easier citation.

    Changed

    ~~~~~~~

    **Changed**

    - Renamed internal ``io`` module to ``util`` for better semantic clarity.

    - Renamed ``VFKern`` to ``VFKernel`` for clarity and consistency.

    - Improved ``README.rst`` layout, usage example, and author links.

    - Enhanced documentation for the data library (``library_data.rst``) with code snippets.

    - Corrected and clarified kernel JSON format documentation (``library_json.rst``).

    - Standardized API and documentation for consistency (e.g., `n_vertices`, `np.ndarray` links, default parameter formatting).

    - Switched documentation parser from `numpydoc` to `sphinx.ext.napoleon` for improved styling and stability.

    - Standardized API and documentation for consistency (e.g., ``n_vertices``, ``np.ndarray`` links, default parameter formatting).

    - Switched documentation parser from ``numpydoc`` to ``sphinx.ext.napoleon`` for improved styling and stability.

    **Fixed**

    Fixed

    ~~~~~

    - Updated documentation and packaging to reflect Windows-only compatibility due to the pre-compiled CHOLMOD ``.dll``.

    [0.3.1] - 2026-01-01

    --------------------

    Added

    ~~~~~

    **Added**

    - First stable public release of the ``sgwt`` package.

    - Comprehensive documentation, usage examples, and testing suite.

README.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,103 +1,81 @@
  
    Sparse SGWT

    ====================================

    |pypi| |python| |license| |coverage|

    .. only:: not latex

    .. |pypi| image:: https://img.shields.io/pypi/v/sgwt.svg

        :target: https://pypi.org/project/sgwt/

        :alt: PyPI Version

        |pypi| |python| |license| |coverage|

    .. |python| image:: https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue.svg

        :target: https://pypi.org/project/sgwt/

        :alt: Python Version

        .. |pypi| image:: https://img.shields.io/pypi/v/sgwt.svg

            :target: https://pypi.org/project/sgwt/

            :alt: PyPI Version

    .. |license| image:: https://img.shields.io/badge/License-GPLv3-blue.svg

        :target: ./LICENSE.md

        :alt: License

        .. |python| image:: https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue.svg

            :target: https://pypi.org/project/sgwt/

            :alt: Python Version

    .. |coverage| image:: https://img.shields.io/badge/coverage-100%25-brightgreen.svg

        :alt: Coverage

        .. |license| image:: https://img.shields.io/badge/License-GPLv3-blue.svg

            :target: ./LICENSE.md

            :alt: License

        .. |coverage| image:: https://img.shields.io/badge/coverage-100%25-brightgreen.svg

            :alt: Coverage

    A high-performance Python library for sparse Graph Signal Processing (GSP) and Spectral Graph Wavelet Transforms (SGWT). This package leverages the ``CHOLMOD`` library for efficient sparse direct solvers, providing significant speedups over traditional dense or iterative methods for large-scale graph convolution.

    Key Features

    ------------

    Some of the key features include:

    - **High-Performance Sparse Solvers**: Direct integration with the ``CHOLMOD`` library for optimized sparse Cholesky factorizations and linear system solves.

    - **Generalized Graph Convolution**: Support for arbitrary spectral kernels via rational approximation (Kernel Fitting), polynomial approximation (Chebyshev), and standard analytical filters (low-pass, band-pass, high-pass).

    - **Dynamic Topology Support**: Specialized routines for graphs with evolving structures, utilizing efficient rank-1 updates for real-time topology changes.

    - **Resource-Aware Execution**: Context-managed memory allocation and workspace reuse to minimize overhead in high-throughput applications.

    - **Integrated Graph Repository**: Built-in access to standardized graph Laplacians and signals from power systems and infrastructure networks.

    For detailed usage, API reference, and theoretical background, please visit the `documentation website <https://sgwt.readthedocs.io/>`_.

    Installation

    ------------

    You can install ``sgwt`` from the `Python Package Index (PyPI) <https://pypi.org/project/sgwt/>`_:

    The ``sgwt`` package requires Python 3.7+ and is currently only compatible with **Windows** operating systems due to its reliance on a pre-compiled ``CHOLMOD`` library.

    Install the latest stable release from `PyPI <https://pypi.org/project/sgwt/>`_:

    .. code-block:: bash

        pip install sgwt

    This command will also install the necessary dependencies (e.g., NumPy, SciPy).

    Documentation

    Basic Example

    -------------

    For detailed usage, API reference, and theoretical background, please visit the `documentation website <https://sgwt.readthedocs.io/>`_.

    Here is a quick example using a band-pass filter to an impulse signal on the synthetic Texas grid to get the wavelet function at three different scales.

    Usage Example

    -------------

    Here is a quick example of applying a band-pass filter to an impulse signal on the built-in synthetic Texas grid Laplacian.

    .. code-block:: python

        import sgwt

        # 1. Load a built-in graph Laplacian, which defines the graph's topology.

        # Graph Laplacian

        L = sgwt.DELAY_TEXAS

        # 2. Create a vertex-domain signal. Here, a Dirac impulse on the 600th vertex.

        #    The `impulse` helper function ensures the required column-major memory order.

        signal = sgwt.impulse(L, n=600)

        # Impulse at 600th Vertex

        X = sgwt.impulse(L, n=600)

        # 3. Use the static convolution context manager. This performs a one-time

        #    symbolic factorization of the Laplacian for efficient repeated solves.

        with sgwt.Convolve(L) as conv:

            # 4. Apply an analytical band-pass filter. The scale parameter controls

            #    the filter's center frequency.

            filtered_signals = conv.bandpass(signal, scales=[10.0])

        # 5. The result is a list of filtered signals, one for each input scale.

        result = filtered_signals[0]

            # Wavelet at 3 scales

            Y = conv.bandpass(X, scales=[0.1, 1, 10])

        print(f"Graph has {L.shape[0]} vertices.")

        print(f"Signal on vertex 600, shape: {signal.shape}")

        print(f"Filtered signal shape: {result.shape}")

    More Examples

    -------------

    The `examples/ <https://github.com/lukelowry/sgwt/tree/main/examples>`_ directory contains a comprehensive suite of demonstrations, also rendered in the `Examples <https://sgwt.readthedocs.io/en/stable/examples/static.html>`_ section of the documentation. Key applications include:

    - **Static Filtering**: Basic low-pass, band-pass, and high-pass filtering on various graph sizes.

    - **Dynamic Graphs**: Real-time topology updates, performance comparisons, and online stream processing.

    Testing

    -------

    The package includes a comprehensive test suite to verify its correctness. To run the tests on an installed version of ``sgwt``, first install the test dependencies and then run pytest:

    .. code-block:: bash

        pip install sgwt[test]

        pytest --pyargs sgwt.tests

    For more detailed instructions, including how to run tests from a source checkout, see the `Validation Tests <https://sgwt.readthedocs.io/en/stable/dev/tests.html>`_ section in the documentation.

    Citation

    --------

    Citation & Acknowledgements

    ---------------------------

    If you use this library in your research, please cite it. The `GitHub repository <https://github.com/lukelowry/sgwt>`_ includes a ``CITATION.cff`` file that provides citation metadata. On GitHub, you can use the "Cite this repository" button on the sidebar to get the citation in your preferred format (including BibTeX).

    @@ -111,14 +89,9 @@ For convenience, the BibTeX entry for the associated paper is:
  
          year={2026}

        }

    Author

    Luke Lowery developed this module during his PhD studies at Texas A&M University. You can learn more on his `research page <https://lukelowry.github.io/>`_ or view his publications on `Google Scholar <https://scholar.google.com/citations?user=CTynuRMAAAAJ&hl=en>`_.

    An alternative implementation in `Julia <https://github.com/lukelowry/SpectralGraphWavelet.jl>`_ is also available and leverages native SuiteSparse support.

    Acknowledgements

    ----------------

    - The core performance of this library relies on the ``CHOLMOD`` library from `SuiteSparse <https://github.com/DrTimothyAldenDavis/SuiteSparse>`_, developed by Dr. Tim Davis at Texas A&M University.

    - The graph laplacians used in the examples are derived from the `synthetic grid repository <https://electricgrids.engr.tamu.edu/electric-grid-test-cases/>`_, made available by Dr. Adam Birchfield at Texas A&M University.

docs/_static/images/demo_benchmark.png

Sorry, something went wrong. Reload?