Adding documentation for power method

Author: lorenzotomada

.github/workflows/docs.yml

@@ -44,12 +44,12 @@ jobs:
       uses: actions/upload-artifact@v4
       with:
         name: documentation
-        path: docs/html/
+        path: docs/_build/html/
 
     - name: Deploy
-      if: success() && github.ref == 'refs/heads/main'
+      if: success()
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/html
+        publish_dir: docs/_build/html
         allow_empty_commit: true

docs/conf.py

@@ -6,6 +6,11 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
 project = "final_project"
 copyright = "2025, Gaspare Li Causi, Lorenzo Tomada"
 author = "Gaspare Li Causi, Lorenzo Tomada"
@@ -14,7 +19,12 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+# here are a few extensions that are not strictly necessary, but might help:
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/index.rst

@@ -10,11 +10,24 @@ Welcome to the documentation for the final project of the course in Development
 We are currently working on the project and on the documentation.
 Stay tuned!
 
-Add your content using ``reStructuredText`` syntax. See the
+Recall that the documentation is written following
 `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
 
 
+Table of Contents
+=================
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents:
+
+   pyclassify
+
+Module Documentation
+====================
+
+.. automodule:: pyclassify
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:

docs/pyclassify.rst

@@ -0,0 +1,20 @@
+PyClassify Module Documentation
+===============================
+
+This module contains all the functions for the PyClassify package.
+
+Functions:
+==========
+
+.. automodule:: pyclassify
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodule: utils
+================
+
+.. automodule:: pyclassify.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/pyclassify/eigenvalues.py

@@ -7,13 +7,52 @@
 
 @profile
 def eigenvalues_np(A, symmetric=True):
+    """
+    Compute the eigenvalues of a square matrix using NumPy's `eig` or `eigh` function.
+
+    This function checks if the input matrix is square (and is actually a matrix) using 'check_A_square_matrix', and then computes its eigenvalues.
+    If the matrix is symmetric, it uses `eigh` (which is more efficient for symmetric matrices).
+    Otherwise, it uses `eig`.
+
+    Args:
+        A (np.ndarray): A square matrix whose eigenvalues are to be computed.
+        symmetric (bool, optional): If True, assumes the matrix is symmetric and uses `eigh` for
+                                     faster computation. If False, uses `eig` for general matrices
+                                     (default is True).
+
+    Returns:
+        np.ndarray: An array containing the eigenvalues of the matrix `A`.
+
+    Raises:
+        TypeError: If the input is not a NumPy array or a SciPy sparse matrix.
+        ValueError: If number of rows != number of columns.
+    """
     check_A_square_matrix(A)
     eigenvalues, _ = eigh(A) if symmetric else eig(A)
     return eigenvalues
 
 
 @profile
 def eigenvalues_sp(A, symmetric=True):
+    """
+    Compute the eigenvalues of a sparse matrix using SciPy's `eigsh` or `eigs` function.
+
+    This function checks if the input matrix is square, then computes its eigenvalues using
+    SciPy's sparse linear algebra solvers. For symmetric matrices, it uses `eigsh` for
+    more efficient computation. For non-symmetric matrices, it uses `eigs`.
+
+    Args:
+        A (sp.spmatrix): A square sparse matrix whose eigenvalues are to be computed.
+        symmetric (bool, optional): If True, assumes the matrix is symmetric and uses `eigsh`.
+                                     If False, uses `eigs` for general matrices (default is True).
+
+    Returns:
+        np.ndarray: An array containing the eigenvalues of the sparse matrix `A`.
+
+    Raises:
+        TypeError: If the input is not a NumPy array or a SciPy sparse matrix.
+        ValueError: If number of rows != number of columns.
+    """
     check_A_square_matrix(A)
     eigenvalues, _ = (
         sp.linalg.eigsh(A, k=A.shape[0] - 1)
@@ -25,6 +64,23 @@ def eigenvalues_sp(A, symmetric=True):
 
 @profile
 def power_method(A, max_iter=500, tol=1e-4, x=None):
+    """
+    Compute the dominant eigenvalue of a square matrix using the power method.
+
+    Args:
+        A (np.ndarray or sp.spmatrix): A square matrix whose dominant eigenvalue is to be computed.
+        max_iter (int, optional): Maximum number of iterations to perform (default is 500).
+        tol (float, optional): Tolerance for convergence based on the relative change between iterations
+                               (default is 1e-4).
+        x (np.ndarray, optional): Initial guess for the eigenvector. If None, a random vector is generated.
+
+    Returns:
+        float: The approximated dominant eigenvalue of the matrix `A`, computed as the Rayleigh quotient x @ A @ x.
+
+    Raises:
+        TypeError: If the input is not a NumPy array or a SciPy sparse matrix.
+        ValueError: If number of rows != number of columns.
+    """
     check_A_square_matrix(A)
     if x is None:
         x = np.random.rand(A.shape[0])
@@ -46,4 +102,20 @@ def power_method(A, max_iter=500, tol=1e-4, x=None):
 
 @profile
 def power_method_numba(A):
+    """
+    Compute the dominant eigenvalue of a matrix using the power method, with Numba optimization.
+
+    This function wraps the `power_method` function and applies Numba's Just-In-Time (JIT) compilation
+    to optimize the performance of the power method for large matrices. The function leverages the
+    `power_method_numba_helper` function for the actual computation. The reason for that is the following: profiling
+    directly a function decorated with @numba.jit does not actually keep track of the calls and execution time due to
+    numba technicalities. Therefore, the helper function is profiled instead.
+    Remark that numba does not support scipy sparse matrices, so the input matrix must be a NumPy array.
+
+    Args:
+        A (np.ndarray): A square matrix whose dominant eigenvalue is to be computed.
+
+    Returns:
+        float: The approximated dominant eigenvalue of the matrix `A`.
+    """
     return power_method_numba_helper(A)

src/pyclassify/utils.py

@@ -9,6 +9,19 @@
 
 
 def check_A_square_matrix(A):
+    """
+    Checks if the input matrix is a square matrix of type NumPy ndarray or SciPy sparse matrix.
+    This is done to ensure that the input matrix `A` is both:
+    1. Of type `np.ndarray` (NumPy array) or `scipy.sparse` (SciPy sparse matrix).
+    2. A square matrix.
+
+    Args:
+        A (np.ndarray or sp.spmatrix): The matrix to be checked.
+
+    Raises:
+        TypeError: If the input is not a NumPy array or a SciPy sparse matrix.
+        ValueError: If number of rows != number of columns.
+    """
     if not isinstance(A, (np.ndarray, sp.spmatrix)):
         raise TypeError("Input matrix must be a NumPy array or a SciPy sparse matrix!")
     if A.shape[0] != A.shape[1]:
@@ -17,13 +30,49 @@ def check_A_square_matrix(A):
 
 @profile
 def make_symmetric(A):
+    """
+    Ensures the input matrix is symmetric by averaging it with its transpose.
+
+    This function first checks if the matrix is square using the `check_A_square_matrix` function.
+    Then, it makes the matrix symmetric by averaging it with its transpose.
+
+    Args:
+        A (np.ndarray or sp.spmatrix): The input square matrix to be made symmetric.
+
+    Returns:
+        np.ndarray or sp.spmatrix: The symmetric version of the input matrix.
+
+    Raises:
+        TypeError: If the input matrix is not a NumPy array or SciPy sparse matrix.
+        ValueError: If the input matrix is not square.
+    """
     check_A_square_matrix(A)
     A_sym = (A + A.T) / 2
     return A_sym
 
 
 @numba.njit(nogil=True, parallel=True)
 def power_method_numba_helper(A, max_iter=500, tol=1e-4, x=None):
+    """
+    Approximate the dominant eigenvalue of a square matrix using the power method.
+
+    This helper function applies the power method to a matrix A to estimate its dominant eigenvalue.
+    It returns the Rayleigh quotient, x @ A @ x, which serves as an approximation of the dominant eigenvalue.
+
+    The function is optimized with Numba using the 'njit' decorator with nogil and parallel options.
+
+    Args:
+        A (np.ndarray): A square matrix.
+        max_iter (int, optional): Maximum number of iterations to perform (default is 500).
+        tol (float, optional): Tolerance for convergence based on the relative change between iterations (default is 1e-4).
+        x (np.ndarray, optional): Initial guess for the eigenvector. If None, a random vector is generated.
+
+    Returns:
+        float: The approximated dominant eigenvalue of the matrix A.
+
+    Raises:
+        ValueError: If the input matrix A is not square. The check is not done using 'check_A_square_matrix' because of numba technicalities.
+    """
     if A.shape[0] != A.shape[1]:
         raise ValueError("Matrix must be square!")  # explain why re-written
     if x is None:
@@ -46,11 +95,16 @@ def power_method_numba_helper(A, max_iter=500, tol=1e-4, x=None):
 
 def read_config(file: str) -> dict:
     """
-    To read the desired configuration file, passed in input as a string
-    Input:
-        file: str (representing the location of file)
+    Reads a YAML configuration file and returns its contents as a dictionary.
+
+    This function constructs the absolute path to a YAML file (by appending the '.yaml' extension
+    to the provided base file name), opens the file, and parses its content using yaml.safe_load.
+
+    Args:
+        file (str): The base name of the YAML file (without the '.yaml' extension).
+
     Returns:
-        dict (containing the configuration parameters needed)
+        dict: A dictionary containing the configuration parameters loaded from the YAML file.
     """
     filepath = os.path.abspath(f"{file}.yaml")
     with open(filepath, "r") as stream: