reppi 0.1.0__tar.gz

reppi-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: reppi
+Version: 0.1.0
+Summary: A Python toolkit for representation-based learning/classification algorithms
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: scipy>=1.17.1

reppi-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "reppi"
+version = "0.1.0"
+description = "A Python toolkit for representation-based learning/classification algorithms"
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.4.4",
+    "scipy>=1.17.1",
+]
+
+[build-system]
+requires = [
+    "setuptools>=61.0",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

reppi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

reppi-0.1.0/src/reppi/__init__.py

@@ -0,0 +1,20 @@
+"""
+reppi — Representation Learning Algorithms
+==========================================
+
+A Python library implementing classical sparse representation and
+dictionary learning algorithms.
+
+Modules
+-------
+sparse
+    Sparse coding (OMP, Batch-OMP).
+dictionary
+    Dictionary learning (K-SVD, LC-KSVD1, LC-KSVD2).
+"""
+
+from reppi.sparse import OMP
+from reppi.dictionary import KSVD, LCKSVD
+
+__all__ = ["OMP", "KSVD", "LCKSVD"]
+__version__ = "0.1.0"

reppi-0.1.0/src/reppi/base.py

@@ -0,0 +1,70 @@
+"""
+Base classes for representation learning algorithms.
+"""
+
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class BaseSparseCoder(ABC):
+    """Abstract base class for sparse coding algorithms."""
+
+    @abstractmethod
+    def encode(self, X: np.ndarray, D: np.ndarray) -> np.ndarray:
+        """
+        Compute sparse codes for signals X given dictionary D.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+            Input signals as columns.
+        D : np.ndarray, shape (n_features, n_atoms)
+            Dictionary with (approximately) unit-norm columns.
+
+        Returns
+        -------
+        Gamma : np.ndarray, shape (n_atoms, n_samples)
+            Sparse representation matrix.
+        """
+        raise NotImplementedError
+
+
+class BaseDictionaryLearner(ABC):
+    """Abstract base class for dictionary learning algorithms."""
+
+    @abstractmethod
+    def fit(self, X: np.ndarray) -> "BaseDictionaryLearner":
+        """
+        Learn a dictionary from training data.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+            Training signals as columns.
+
+        Returns
+        -------
+        self
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def transform(self, X: np.ndarray) -> np.ndarray:
+        """
+        Encode signals using the learned dictionary.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+            Signals to encode.
+
+        Returns
+        -------
+        Gamma : np.ndarray, shape (n_atoms, n_samples)
+            Sparse representations.
+        """
+        raise NotImplementedError
+
+    def fit_transform(self, X: np.ndarray) -> np.ndarray:
+        """Fit and return sparse codes on the training data."""
+        return self.fit(X).transform(X)

reppi-0.1.0/src/reppi/dictionary/__init__.py

@@ -0,0 +1,6 @@
+"""Dictionary learning algorithms."""
+
+from reppi.dictionary.ksvd import KSVD
+from reppi.dictionary.lc_ksvd import LCKSVD, initialization4lcksvd
+
+__all__ = ["KSVD", "LCKSVD", "initialization4lcksvd"]

reppi-0.1.0/src/reppi/dictionary/ksvd.py

@@ -0,0 +1,292 @@
+"""
+K-SVD dictionary learning.
+
+Implements the K-SVD algorithm described in:
+    Aharon, Elad, Bruckstein. "The K-SVD: An Algorithm for Designing
+    Overcomplete Dictionaries for Sparse Representation".
+    IEEE Trans. Signal Processing, 54(11), 2006.
+
+Batch-OMP integration follows:
+    Elad, Rubinstein, Zibulevsky. "Efficient Implementation of the K-SVD
+    Algorithm using Batch Orthogonal Matching Pursuit". Technion TR, 2008.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import linalg
+
+from reppi.base import BaseDictionaryLearner
+from reppi.exceptions import DictionaryLearningError
+from reppi.sparse.omp import OMP, batch_omp
+from reppi.sparse.src import col_norms_squared, normalize_columns, rep_error_squared
+
+
+class KSVD(BaseDictionaryLearner):
+    """
+    K-SVD dictionary learner.
+
+    Alternates between:
+      1. Sparse coding — encode each training signal over the current D.
+      2. Dictionary update — update each atom (and its coefficients) via a
+         rank-1 approximation of the residual matrix.
+
+    Parameters
+    ----------
+    n_components : int
+        Number of dictionary atoms to learn.
+    n_nonzero_coefs : int
+        Sparsity target T: each signal is represented with at most T atoms.
+    n_iter : int
+        Number of K-SVD iterations (default 10).
+    exact_svd : bool
+        If True, use full SVD for the atom update (exact K-SVD).
+        If False (default), use the faster approximate update.
+    mu_thresh : float
+        Mutual-incoherence threshold in (0, 1].  Atoms whose pairwise
+        correlation exceeds this value are replaced.  Set to 1.0 to
+        disable (default 0.99).
+    mem_usage : str
+        One of 'high', 'normal' (default), 'low'.
+        Controls whether G = D'D (and DtX = D'X) are precomputed.
+    random_state : int or None
+        Seed for reproducible atom initialisation.
+    verbose : bool
+        Print iteration progress (default False).
+    """
+
+    def __init__(
+        self,
+        n_components: int,
+        n_nonzero_coefs: int,
+        n_iter: int = 10,
+        exact_svd: bool = False,
+        mu_thresh: float = 0.99,
+        mem_usage: str = "normal",
+        random_state: int | None = None,
+        verbose: bool = False,
+    ) -> None:
+        if mem_usage not in ("high", "normal", "low"):
+            raise ValueError("mem_usage must be 'high', 'normal', or 'low'.")
+        self.n_components = n_components
+        self.n_nonzero_coefs = n_nonzero_coefs
+        self.n_iter = n_iter
+        self.exact_svd = exact_svd
+        self.mu_thresh = mu_thresh
+        self.mem_usage = mem_usage
+        self.random_state = random_state
+        self.verbose = verbose
+
+        # Set after fit
+        self.D_: np.ndarray | None = None
+        self.errors_: list[float] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def fit(self, X: np.ndarray, D_init: np.ndarray | None = None) -> "KSVD":
+        """
+        Learn a dictionary from training signals.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+        D_init : np.ndarray or None, shape (n_features, n_components)
+            Optional initial dictionary.  If None, random training signals
+            are chosen as initial atoms.
+
+        Returns
+        -------
+        self
+        """
+        X = np.asarray(X, dtype=float)
+        rng = np.random.default_rng(self.random_state)
+
+        D = self._init_dict(X, D_init, rng)
+        self.errors_ = []
+
+        for it in range(self.n_iter):
+            G = D.T @ D if self.mem_usage in ("high", "normal") else None
+            Gamma = self._sparse_code(X, D, G)
+
+            unused = np.arange(X.shape[1])
+            replaced = np.zeros(self.n_components, dtype=bool)
+
+            for j in range(self.n_components):
+                D[:, j], gamma_j, idx, unused, replaced = _optimize_atom(
+                    X, D, j, Gamma, unused, replaced, self.exact_svd
+                )
+                Gamma[j, idx] = gamma_j
+
+            err = float(np.sqrt(rep_error_squared(X, D, Gamma).sum() / X.size))
+            self.errors_.append(err)
+
+            D, _ = _clear_dict(D, Gamma, X, self.mu_thresh, unused, replaced)
+
+            if self.verbose:
+                print(f"Iter {it + 1}/{self.n_iter}  RMSE={err:.6f}")
+
+        self.D_ = D
+        return self
+
+    def transform(self, X: np.ndarray) -> np.ndarray:
+        """Encode X using the learned dictionary."""
+        if self.D_ is None:
+            raise DictionaryLearningError("Call fit() before transform().")
+        coder = OMP(self.n_nonzero_coefs, mode="batch", check_dict=False)
+        return coder.encode(X, self.D_)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _init_dict(
+        self,
+        X: np.ndarray,
+        D_init: np.ndarray | None,
+        rng: np.random.Generator,
+    ) -> np.ndarray:
+        n_features, n_samples = X.shape
+        k = self.n_components
+
+        if D_init is not None:
+            D = np.asarray(D_init, dtype=float)
+            if D.shape != (n_features, k):
+                raise DictionaryLearningError(
+                    f"D_init shape {D.shape} does not match "
+                    f"(n_features={n_features}, n_components={k})."
+                )
+        else:
+            valid = np.where(col_norms_squared(X) > 1e-6)[0]
+            if len(valid) < k:
+                raise DictionaryLearningError(
+                    "Not enough non-zero training signals to initialise the dictionary."
+                )
+            chosen = rng.choice(valid, size=k, replace=False)
+            D = X[:, chosen].copy()
+
+        return normalize_columns(D)
+
+    def _sparse_code(
+        self,
+        X: np.ndarray,
+        D: np.ndarray,
+        G: np.ndarray | None,
+    ) -> np.ndarray:
+        if self.mem_usage == "high" and G is not None:
+            return batch_omp(D.T @ X, G, self.n_nonzero_coefs)
+        coder = OMP(self.n_nonzero_coefs, mode="batch", check_dict=False)
+        return coder.encode(X, D, G=G)
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers (shared with LC-KSVD)
+# ---------------------------------------------------------------------------
+
+
+def _optimize_atom(
+    X: np.ndarray,
+    D: np.ndarray,
+    j: int,
+    Gamma: np.ndarray,
+    unused_sigs: np.ndarray,
+    replaced: np.ndarray,
+    exact_svd: bool,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Update the j-th dictionary atom and the corresponding sparse codes.
+
+    Mirrors the MATLAB ``optimize_atom`` function.
+
+    Returns
+    -------
+    atom : np.ndarray, shape (n_features,)
+    gamma_j : np.ndarray, non-zero coefficients for atom j
+    data_indices : np.ndarray, signal indices that use atom j
+    unused_sigs : np.ndarray (updated)
+    replaced : np.ndarray (updated)
+    """
+    # Signals that actively use atom j
+    data_indices = np.where(np.abs(Gamma[j, :]) > 1e-10)[0]
+
+    # --- Dead atom: replace with the worst-reconstructed unused signal ---
+    if len(data_indices) == 0:
+        max_signals = 5000
+        perm = np.random.permutation(len(unused_sigs))[:min(max_signals, len(unused_sigs))]
+        candidates = unused_sigs[perm]
+        E = rep_error_squared(X, D, Gamma, block_size=len(candidates) + 1)
+        best = int(np.argmax(E[candidates]))
+        atom = X[:, candidates[best]]
+        atom = atom / max(np.linalg.norm(atom), 1e-14)
+        gamma_j = np.zeros(len(data_indices))
+        # Remove used signal from the pool
+        mask = np.ones(len(unused_sigs), dtype=bool)
+        mask[perm[best]] = False
+        unused_sigs = unused_sigs[mask]
+        replaced[j] = True
+        return atom, gamma_j, data_indices, unused_sigs, replaced
+
+    # --- Normal update ---
+    small_gamma = Gamma[:, data_indices]       # (n_atoms, |support|)
+    g_j = Gamma[j, data_indices]              # (|support|,)
+
+    # Residual matrix: remove atom j's contribution then add it back
+    # E = X[:,support] - D*small_gamma + d_j * g_j
+    E = X[:, data_indices] - D @ small_gamma + np.outer(D[:, j], g_j)
+
+    if exact_svd:
+        # Exact update via rank-1 SVD
+        U, s, Vt = np.linalg.svd(E, full_matrices=False)
+        atom = U[:, 0]
+        gamma_j = s[0] * Vt[0, :]
+    else:
+        # Approximate update (alternating optimisation)
+        atom = E @ g_j
+        atom_norm = np.linalg.norm(atom)
+        atom = atom / max(atom_norm, 1e-14)
+        gamma_j = atom @ E  # (|support|,)
+
+    return atom, gamma_j, data_indices, unused_sigs, replaced
+
+
+def _clear_dict(
+    D: np.ndarray,
+    Gamma: np.ndarray,
+    X: np.ndarray,
+    mu_thresh: float,
+    unused_sigs: np.ndarray,
+    replaced: np.ndarray,
+    use_thresh: int = 4,
+) -> tuple[np.ndarray, int]:
+    """
+    Replace rarely-used or highly-correlated atoms with high-error signals.
+
+    Mirrors the MATLAB ``cleardict`` function.
+
+    Returns
+    -------
+    D : np.ndarray (possibly modified)
+    cleared : int  number of atoms replaced
+    """
+    n_atoms = D.shape[1]
+    err = rep_error_squared(X, D, Gamma)
+    use_count = (np.abs(Gamma) > 1e-7).sum(axis=1)  # (n_atoms,)
+    cleared = 0
+
+    for j in range(n_atoms):
+        if len(unused_sigs) == 0:
+            break
+        Gj = D.T @ D[:, j]
+        Gj[j] = 0.0
+        bad_coherence = np.max(Gj ** 2) > mu_thresh ** 2
+        bad_usage = use_count[j] < use_thresh
+
+        if (bad_coherence or bad_usage) and not replaced[j]:
+            best = int(np.argmax(err[unused_sigs]))
+            atom = X[:, unused_sigs[best]]
+            D[:, j] = atom / max(np.linalg.norm(atom), 1e-14)
+            unused_sigs = np.delete(unused_sigs, best)
+            cleared += 1
+
+    return D, cleared

reppi-0.1.0/src/reppi/dictionary/lc_ksvd.py

@@ -0,0 +1,542 @@
+"""
+Label Consistent K-SVD (LC-KSVD) dictionary learning.
+
+Implements LC-KSVD1 and LC-KSVD2 as described in:
+    Zhuolin Jiang, Zhe Lin, Larry S. Davis.
+    "Learning A Discriminative Dictionary for Sparse Coding via Label
+     Consistent K-SVD", CVPR 2011.
+
+LC-KSVD augments the standard K-SVD objective with:
+  - A label-consistency term (LC-KSVD1) that encourages atoms associated
+    with the same class to produce similar sparse codes.
+  - An additional linear classifier term (LC-KSVD2) that jointly trains a
+    classifier W alongside the dictionary.
+
+Optimization problems
+---------------------
+LC-KSVD1:
+    min_{D, A, X}  ||Y - DX||_F^2 + alpha * ||Q - AX||_F^2
+    s.t.  ||x_i||_0 <= T
+
+LC-KSVD2:
+    min_{D, A, W, X}  ||Y - DX||_F^2 + alpha * ||Q - AX||_F^2
+                      + beta * ||H - WX||_F^2
+    s.t.  ||x_i||_0 <= T
+
+where:
+  Y = training signals
+  D = dictionary
+  X = sparse codes
+  Q = label-consistent sparse code targets (binary atom-class assignments)
+  A = linear mapping for Q-consistency
+  W = linear classifier
+  H = class label matrix (one-hot per column)
+  alpha, beta = trade-off weights
+
+Usage
+-----
+For LC-KSVD1::
+
+    model = LCKSVD(
+        n_components=570,
+        n_nonzero_coefs=30,
+        alpha=4.0,
+        variant="lcksvd1",
+    )
+    model.fit(X_train, H_train)
+    predictions = model.predict(X_test)
+
+For LC-KSVD2::
+
+    model = LCKSVD(
+        n_components=570,
+        n_nonzero_coefs=30,
+        alpha=4.0,
+        beta=2.0,
+        variant="lcksvd2",
+    )
+    model.fit(X_train, H_train)
+    predictions = model.predict(X_test)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from reppi.base import BaseDictionaryLearner
+from reppi.exceptions import DictionaryLearningError
+from reppi.sparse.omp import OMP, batch_omp
+from reppi.sparse.src import col_norms_squared, normalize_columns, rep_error_squared
+from reppi.dictionary.ksvd import KSVD, _optimize_atom, _clear_dict
+
+
+# ---------------------------------------------------------------------------
+# Initialisation helper
+# ---------------------------------------------------------------------------
+
+
+def _build_label_consistent_target(
+    H: np.ndarray,
+    n_components: int,
+    n_nonzero_coefs: int,
+    sparse_codes: np.ndarray,
+) -> np.ndarray:
+    """
+    Build the label-consistent target matrix Q.
+
+    Each dictionary atom is associated with exactly one class.  Q[:,i] is a
+    binary vector that is 1 in the positions of atoms belonging to the same
+    class as training sample i, and 0 elsewhere.
+
+    Parameters
+    ----------
+    H : np.ndarray, shape (n_classes, n_samples)
+        One-hot class label matrix.
+    n_components : int
+        Total number of dictionary atoms.
+    n_nonzero_coefs : int
+        Sparsity level T.
+    sparse_codes : np.ndarray, shape (n_components, n_samples)
+        Current sparse codes (used to determine per-class atom assignment).
+
+    Returns
+    -------
+    Q : np.ndarray, shape (n_components, n_samples)
+    """
+    n_classes, n_samples = H.shape
+
+    # Distribute atoms evenly across classes
+    atoms_per_class = n_components // n_classes
+
+    # Assign atoms to classes in order
+    atom_class = np.zeros(n_components, dtype=int)
+    for c in range(n_classes):
+        start = c * atoms_per_class
+        end = start + atoms_per_class if c < n_classes - 1 else n_components
+        atom_class[start:end] = c
+
+    Q = np.zeros((n_components, n_samples))
+    for i in range(n_samples):
+        cls = int(np.argmax(H[:, i]))
+        Q[atom_class == cls, i] = 1.0
+
+    return Q
+
+
+def initialization4lcksvd(
+    X: np.ndarray,
+    H: np.ndarray,
+    n_components: int,
+    n_iter_init: int,
+    n_nonzero_coefs: int,
+    random_state: int | None = None,
+    verbose: bool = False,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Initialise D, A (label-consistency transform), W (classifier), and Q.
+
+    This mirrors the MATLAB ``initialization4LCKSVD`` step. A plain K-SVD is
+    run first, then a linear classifier W and label-consistent target Q are
+    estimated from the resulting sparse codes.
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (n_features, n_samples)
+        Training signals.
+    H : np.ndarray, shape (n_classes, n_samples)
+        One-hot label matrix.
+    n_components : int
+        Dictionary size.
+    n_iter_init : int
+        K-SVD iterations for the initialisation run.
+    n_nonzero_coefs : int
+        Sparsity level T.
+    random_state : int or None
+    verbose : bool
+
+    Returns
+    -------
+    D_init : np.ndarray, shape (n_features, n_components)
+    A_init : np.ndarray, shape (n_components, n_components)
+        Initial label-consistency transform.
+    W_init : np.ndarray, shape (n_classes, n_components)
+        Initial linear classifier weights.
+    Q : np.ndarray, shape (n_components, n_samples)
+        Label-consistent sparse code targets.
+    """
+    # Step 1: standard K-SVD initialisation
+    ksvd = KSVD(
+        n_components=n_components,
+        n_nonzero_coefs=n_nonzero_coefs,
+        n_iter=n_iter_init,
+        random_state=random_state,
+        verbose=verbose,
+    )
+    ksvd.fit(X)
+    D_init = ksvd.D_
+
+    # Step 2: sparse-code the training data with the initial dictionary
+    coder = OMP(n_nonzero_coefs, mode="batch", check_dict=False)
+    Gamma = coder.encode(X, D_init)
+
+    # Step 3: build Q
+    Q = _build_label_consistent_target(H, n_components, n_nonzero_coefs, Gamma)
+
+    # Step 4: fit W (classifier) via least squares: W * Gamma ≈ H
+    # W = H @ Gamma.T @ pinv(Gamma @ Gamma.T)
+    W_init = H @ np.linalg.pinv(Gamma)
+
+    # Step 5: fit A (label-consistency map) via least squares: A * Gamma ≈ Q
+    A_init = Q @ np.linalg.pinv(Gamma)
+
+    return D_init, A_init, W_init, Q
+
+
+# ---------------------------------------------------------------------------
+# LC-KSVD training
+# ---------------------------------------------------------------------------
+
+
+def _augment_data(
+    X: np.ndarray,
+    Q: np.ndarray,
+    H: np.ndarray | None,
+    sqrt_alpha: float,
+    sqrt_beta: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Build the augmented signal/dictionary system for LC-KSVD.
+
+    The combined objective is minimised by stacking the data matrices:
+
+        Y_aug = [ X        ]       D_aug = [ D  ]
+                [ α * Q    ]               [ α A]
+                [ β * H    ]               [ β W]   (LC-KSVD2 only)
+
+    This augmentation lets the standard K-SVD atom-update step
+    simultaneously minimise reconstruction, label-consistency, and
+    (optionally) classification error.
+
+    Returns
+    -------
+    X_aug : np.ndarray
+    alpha_scale : float  (for constructing D_aug at each iteration)
+    beta_scale : float
+    """
+    alpha_scale = sqrt_alpha
+    beta_scale = sqrt_beta
+
+    parts = [X, sqrt_alpha * Q]
+    if H is not None:
+        parts.append(sqrt_beta * H)
+
+    X_aug = np.vstack(parts)
+    return X_aug, alpha_scale, beta_scale
+
+
+class LCKSVD(BaseDictionaryLearner):
+    """
+    Label Consistent K-SVD dictionary learner (LC-KSVD1 and LC-KSVD2).
+
+    Parameters
+    ----------
+    n_components : int
+        Number of dictionary atoms.
+    n_nonzero_coefs : int
+        Sparsity level T.
+    alpha : float
+        Weight for the label-consistency term (sqrt_alpha in the paper).
+    beta : float
+        Weight for the classifier term (sqrt_beta; LC-KSVD2 only).
+    variant : {'lcksvd1', 'lcksvd2'}
+        Which variant to train.
+    n_iter : int
+        Number of LC-KSVD iterations (default 50).
+    n_iter_init : int
+        K-SVD iterations for the initialisation phase (default 20).
+    exact_svd : bool
+        Use exact SVD in the atom-update step (slower but slightly better).
+    mu_thresh : float
+        Mutual-incoherence threshold (default 0.99).
+    random_state : int or None
+    verbose : bool
+
+    Attributes
+    ----------
+    D_ : np.ndarray, shape (n_features, n_components)
+        Learned dictionary.
+    W_ : np.ndarray, shape (n_classes, n_components)
+        Learned linear classifier weights.
+    A_ : np.ndarray, shape (n_components, n_components)
+        Learned label-consistency transform.
+    errors_ : list of float
+        Per-iteration RMSE on training data.
+    """
+
+    def __init__(
+        self,
+        n_components: int,
+        n_nonzero_coefs: int,
+        alpha: float = 4.0,
+        beta: float = 2.0,
+        variant: str = "lcksvd2",
+        n_iter: int = 50,
+        n_iter_init: int = 20,
+        exact_svd: bool = False,
+        mu_thresh: float = 0.99,
+        random_state: int | None = None,
+        verbose: bool = False,
+    ) -> None:
+        if variant not in ("lcksvd1", "lcksvd2"):
+            raise ValueError("variant must be 'lcksvd1' or 'lcksvd2'.")
+        self.n_components = n_components
+        self.n_nonzero_coefs = n_nonzero_coefs
+        self.alpha = alpha
+        self.beta = beta
+        self.variant = variant
+        self.n_iter = n_iter
+        self.n_iter_init = n_iter_init
+        self.exact_svd = exact_svd
+        self.mu_thresh = mu_thresh
+        self.random_state = random_state
+        self.verbose = verbose
+
+        self.D_: np.ndarray | None = None
+        self.W_: np.ndarray | None = None
+        self.A_: np.ndarray | None = None
+        self.errors_: list[float] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def fit(
+        self,
+        X: np.ndarray,
+        H: np.ndarray,
+        D_init: np.ndarray | None = None,
+        A_init: np.ndarray | None = None,
+        W_init: np.ndarray | None = None,
+        Q: np.ndarray | None = None,
+    ) -> "LCKSVD":
+        """
+        Learn a discriminative dictionary from labelled training data.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+            Training signals.
+        H : np.ndarray, shape (n_classes, n_samples)
+            One-hot label matrix.
+        D_init : np.ndarray or None
+            Initial dictionary. If None, a K-SVD initialisation is run.
+        A_init : np.ndarray or None
+            Initial label-consistency transform.
+        W_init : np.ndarray or None
+            Initial classifier weights (required / used for LC-KSVD2).
+        Q : np.ndarray or None
+            Label-consistent target matrix. Computed from H if None.
+
+        Returns
+        -------
+        self
+        """
+        X = np.asarray(X, dtype=float)
+        H = np.asarray(H, dtype=float)
+        n_features, n_samples = X.shape
+        n_classes = H.shape[0]
+
+        # ---- Initialisation ----
+        if D_init is None or A_init is None or W_init is None or Q is None:
+            if self.verbose:
+                print("Running initialisation K-SVD...")
+            D_init, A_init, W_init, Q = initialization4lcksvd(
+                X, H,
+                self.n_components,
+                self.n_iter_init,
+                self.n_nonzero_coefs,
+                random_state=self.random_state,
+                verbose=self.verbose,
+            )
+
+        D = normalize_columns(D_init.copy())
+        A = A_init.copy()
+        W = W_init.copy()
+
+        sqrt_alpha = self.alpha
+        sqrt_beta = self.beta
+
+        use_classifier_term = (self.variant == "lcksvd2")
+
+        # ---- Build augmented training data ----
+        # Y_aug = [X ; sqrt_alpha*Q ; sqrt_beta*H]  (LC-KSVD2)
+        # Y_aug = [X ; sqrt_alpha*Q]                 (LC-KSVD1)
+        H_aug = H if use_classifier_term else None
+        X_aug, _, _ = _augment_data(X, Q, H_aug, sqrt_alpha, sqrt_beta)
+
+        self.errors_ = []
+
+        for it in range(self.n_iter):
+
+            # ---- Build augmented dictionary ----
+            # D_aug = [D ; sqrt_alpha*A ; sqrt_beta*W]
+            D_aug = self._build_aug_dict(D, A, W, sqrt_alpha, sqrt_beta, use_classifier_term)
+            D_aug_norm = normalize_columns(D_aug)
+
+            # ---- Sparse coding on augmented system ----
+            G_aug = D_aug_norm.T @ D_aug_norm
+            Gamma = batch_omp(D_aug_norm.T @ X_aug, G_aug, self.n_nonzero_coefs)
+
+            # ---- Dictionary update (on original data only) ----
+            # We update D, A (and W for LC-KSVD2) jointly via the
+            # augmented residual, but evaluate coherence/usage on original X.
+            unused = np.arange(n_samples)
+            replaced = np.zeros(self.n_components, dtype=bool)
+
+            for j in range(self.n_components):
+                D_aug_norm[:, j], gamma_j, idx, unused, replaced = _optimize_atom(
+                    X_aug, D_aug_norm, j, Gamma, unused, replaced, self.exact_svd
+                )
+                Gamma[j, idx] = gamma_j
+
+            # De-augment: extract D, A, W from D_aug_norm
+            D, A, W = self._split_aug_dict(
+                D_aug_norm, n_features, n_classes, sqrt_alpha, sqrt_beta, use_classifier_term
+            )
+            D = normalize_columns(D)
+
+            # ---- Update classifier W (LC-KSVD2) via least squares ----
+            if use_classifier_term:
+                W = H @ np.linalg.pinv(Gamma)
+
+            # ---- Update A via least squares ----
+            A = Q @ np.linalg.pinv(Gamma)
+
+            # ---- Clear incoherent / rarely-used atoms ----
+            # Rebuild normalised augmented dict for coherence checking
+            D_aug_rebuilt = self._build_aug_dict(D, A, W, sqrt_alpha, sqrt_beta, use_classifier_term)
+            D_aug_rebuilt = normalize_columns(D_aug_rebuilt)
+            D_aug_rebuilt, _ = _clear_dict(
+                D_aug_rebuilt, Gamma, X_aug, self.mu_thresh,
+                unused, replaced
+            )
+            D, A, W = self._split_aug_dict(
+                D_aug_rebuilt, n_features, n_classes, sqrt_alpha, sqrt_beta, use_classifier_term
+            )
+            D = normalize_columns(D)
+
+            # ---- Track RMSE on original X ----
+            err = float(np.sqrt(rep_error_squared(X, D, Gamma).sum() / X.size))
+            self.errors_.append(err)
+
+            if self.verbose:
+                print(f"[{self.variant.upper()}] Iter {it + 1}/{self.n_iter}  RMSE={err:.6f}")
+
+        self.D_ = D
+        self.A_ = A
+        self.W_ = W
+        return self
+
+    def transform(self, X: np.ndarray) -> np.ndarray:
+        """
+        Encode X using the learned dictionary D.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+
+        Returns
+        -------
+        Gamma : np.ndarray, shape (n_components, n_samples)
+        """
+        self._check_fitted()
+        coder = OMP(self.n_nonzero_coefs, mode="batch", check_dict=False)
+        return coder.encode(X, self.D_)
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Classify test signals using the learned classifier W.
+
+        The predicted class for each signal is the argmax of W @ gamma.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+
+        Returns
+        -------
+        labels : np.ndarray, shape (n_samples,)  integer class indices
+        """
+        self._check_fitted()
+        if self.W_ is None:
+            raise DictionaryLearningError(
+                "Classifier W is not available. "
+                "Use variant='lcksvd2' or access sparse codes via transform()."
+            )
+        Gamma = self.transform(X)
+        scores = self.W_ @ Gamma          # (n_classes, n_samples)
+        return np.argmax(scores, axis=0)
+
+    def score(self, X: np.ndarray, H: np.ndarray) -> float:
+        """
+        Classification accuracy on (X, H).
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+        H : np.ndarray, shape (n_classes, n_samples) — one-hot labels
+
+        Returns
+        -------
+        accuracy : float in [0, 1]
+        """
+        true_labels = np.argmax(H, axis=0)
+        pred_labels = self.predict(X)
+        return float(np.mean(pred_labels == true_labels))
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _check_fitted(self) -> None:
+        if self.D_ is None:
+            raise DictionaryLearningError("Call fit() before transform() / predict().")
+
+    @staticmethod
+    def _build_aug_dict(
+        D: np.ndarray,
+        A: np.ndarray,
+        W: np.ndarray,
+        sqrt_alpha: float,
+        sqrt_beta: float,
+        use_classifier: bool,
+    ) -> np.ndarray:
+        """Stack [D ; sqrt_alpha*A ; (sqrt_beta*W)]."""
+        parts = [D, sqrt_alpha * A]
+        if use_classifier:
+            parts.append(sqrt_beta * W)
+        return np.vstack(parts)
+
+    @staticmethod
+    def _split_aug_dict(
+        D_aug: np.ndarray,
+        n_features: int,
+        n_classes: int,
+        sqrt_alpha: float,
+        sqrt_beta: float,
+        use_classifier: bool,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Recover (D, A, W) from the augmented dictionary D_aug.
+
+        D_aug rows are: n_features | n_components | (n_classes if lcksvd2).
+        """
+        n_components = D_aug.shape[1]
+        D = D_aug[:n_features, :]
+        A_rows = n_components
+        A = D_aug[n_features: n_features + A_rows, :] / max(sqrt_alpha, 1e-14)
+        if use_classifier:
+            W = D_aug[n_features + A_rows:, :] / max(sqrt_beta, 1e-14)
+        else:
+            W = np.zeros((n_classes, n_components))
+        return D, A, W

reppi-0.1.0/src/reppi/exceptions.py

@@ -0,0 +1,23 @@
+"""
+Custom exceptions for the reppi library.
+"""
+
+
+class ReppiError(Exception):
+    """Base exception for all reppi errors."""
+
+
+class DictionaryNormalizationError(ReppiError):
+    """Raised when dictionary atoms are not unit-norm."""
+
+
+class SparseCodingError(ReppiError):
+    """Raised when sparse coding fails or receives invalid inputs."""
+
+
+class DictionaryLearningError(ReppiError):
+    """Raised when dictionary learning encounters an unrecoverable error."""
+
+
+class InvalidParameterError(ReppiError):
+    """Raised when an invalid parameter value is supplied."""

reppi-0.1.0/src/reppi/sparse/__init__.py

@@ -0,0 +1,5 @@
+"""Sparse coding algorithms."""
+
+from reppi.sparse.omp import OMP, batch_omp, omp_cholesky
+
+__all__ = ["OMP", "batch_omp", "omp_cholesky"]

reppi-0.1.0/src/reppi/sparse/omp.py

@@ -0,0 +1,218 @@
+"""
+Orthogonal Matching Pursuit (OMP) sparse coding.
+
+Implements Batch-OMP as described in:
+    Elad, Rubinstein, Zibulevsky. "Efficient Implementation of the K-SVD
+    Algorithm using Batch Orthogonal Matching Pursuit". Technion TR, 2008.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import linalg
+
+from reppi.base import BaseSparseCoder
+from reppi.exceptions import DictionaryNormalizationError, SparseCodingError
+
+
+def _check_dict_normalized(D: np.ndarray, tol: float = 1e-2) -> None:
+    """Raise if any atom of D deviates from unit L2-norm by more than tol."""
+    norms = np.sqrt((D * D).sum(axis=0))
+    if np.any(np.abs(norms - 1.0) > tol):
+        raise DictionaryNormalizationError(
+            "Dictionary columns must be normalized to unit L2-norm. "
+            f"Got norms in range [{norms.min():.4f}, {norms.max():.4f}]."
+        )
+
+
+def omp_cholesky(
+    D: np.ndarray,
+    x: np.ndarray,
+    n_nonzero: int,
+) -> np.ndarray:
+    """
+    Single-signal OMP via Cholesky updates (OMP-Cholesky).
+
+    Parameters
+    ----------
+    D : np.ndarray, shape (n_features, n_atoms)
+        Normalized dictionary.
+    x : np.ndarray, shape (n_features,)
+        Single input signal.
+    n_nonzero : int
+        Maximum number of non-zero coefficients (sparsity).
+
+    Returns
+    -------
+    gamma : np.ndarray, shape (n_atoms,)
+        Sparse representation of x.
+    """
+    n_atoms = D.shape[1]
+    residual = x.copy().astype(float)
+    support: list[int] = []
+    gamma = np.zeros(n_atoms)
+
+    # Cholesky factor of D[:,support].T @ D[:,support]
+    L = np.zeros((n_nonzero, n_nonzero))
+
+    for k in range(n_nonzero):
+        correlations = D.T @ residual
+        j = int(np.argmax(np.abs(correlations)))
+        support.append(j)
+
+        # --- Cholesky update ---
+        Ds = D[:, support]
+        if k == 0:
+            L[0, 0] = 1.0
+        else:
+            w = Ds[:, :-1].T @ D[:, j]  # (k,)
+            # Solve L[:k,:k] * v = w
+            v = linalg.solve_triangular(L[:k, :k], w, lower=True)
+            l_new = np.sqrt(max(1.0 - float(v @ v), 1e-14))
+            L[k, :k] = v
+            L[k, k] = l_new
+
+        # Solve (L L.T) c = Ds.T x
+        rhs = Ds.T @ x
+        c = linalg.cho_solve(
+            (L[: k + 1, : k + 1], True), rhs
+        )
+        residual = x - Ds @ c
+
+    gamma[support] = c
+    return gamma
+
+
+def batch_omp(
+    DtX: np.ndarray,
+    G: np.ndarray,
+    n_nonzero: int,
+) -> np.ndarray:
+    """
+    Batch OMP — fastest variant; requires precomputed G = D'D and DtX = D'X.
+
+    Parameters
+    ----------
+    DtX : np.ndarray, shape (n_atoms, n_samples)
+        Precomputed projections D.T @ X.
+    G : np.ndarray, shape (n_atoms, n_atoms)
+        Precomputed Gram matrix D.T @ D.
+    n_nonzero : int
+        Sparsity level.
+
+    Returns
+    -------
+    Gamma : np.ndarray, shape (n_atoms, n_samples)
+        Sparse representations (dense).
+    """
+    n_atoms, n_samples = DtX.shape
+    Gamma = np.zeros((n_atoms, n_samples))
+
+    for i in range(n_samples):
+        dtx = DtX[:, i]
+        residual_proj = dtx.copy()
+        support: list[int] = []
+        L = np.zeros((n_nonzero, n_nonzero))
+
+        for k in range(n_nonzero):
+            j = int(np.argmax(np.abs(residual_proj)))
+            support.append(j)
+
+            # Cholesky update using Gram matrix
+            if k == 0:
+                L[0, 0] = 1.0
+            else:
+                w = G[support[:-1], j]  # (k,)
+                v = linalg.solve_triangular(L[:k, :k], w, lower=True)
+                l_new = np.sqrt(max(1.0 - float(v @ v), 1e-14))
+                L[k, :k] = v
+                L[k, k] = l_new
+
+            # Solve (L L.T) c = DtX[support, i]
+            rhs = dtx[support]
+            c = linalg.cho_solve((L[: k + 1, : k + 1], True), rhs)
+
+            # Update residual in projection space
+            residual_proj = dtx - G[:, support] @ c
+
+        Gamma[support, i] = c
+
+    return Gamma
+
+
+class OMP(BaseSparseCoder):
+    """
+    Orthogonal Matching Pursuit sparse coder.
+
+    Parameters
+    ----------
+    n_nonzero_coefs : int
+        Target sparsity — maximum number of non-zero coefficients per signal.
+    mode : {'batch', 'cholesky'}
+        Implementation variant.
+        'batch'     — Batch-OMP; requires the full Gram matrix G = D'D.
+                      Fastest when encoding many signals at once.
+        'cholesky'  — Single-signal OMP-Cholesky; lower memory footprint.
+    check_dict : bool
+        Whether to verify that dictionary atoms are unit-norm (default True).
+    """
+
+    def __init__(
+        self,
+        n_nonzero_coefs: int,
+        mode: str = "batch",
+        check_dict: bool = True,
+    ) -> None:
+        if n_nonzero_coefs < 1:
+            raise ValueError("n_nonzero_coefs must be >= 1.")
+        if mode not in ("batch", "cholesky"):
+            raise ValueError("mode must be 'batch' or 'cholesky'.")
+        self.n_nonzero_coefs = n_nonzero_coefs
+        self.mode = mode
+        self.check_dict = check_dict
+
+    def encode(
+        self,
+        X: np.ndarray,
+        D: np.ndarray,
+        G: np.ndarray | None = None,
+    ) -> np.ndarray:
+        """
+        Compute sparse codes for each column of X.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_features, n_samples)
+        D : np.ndarray, shape (n_features, n_atoms)
+        G : np.ndarray or None, shape (n_atoms, n_atoms)
+            Precomputed Gram matrix D.T @ D.  Required for 'batch' mode;
+            computed internally if not supplied.
+
+        Returns
+        -------
+        Gamma : np.ndarray, shape (n_atoms, n_samples)
+        """
+        X = np.asarray(X, dtype=float)
+        D = np.asarray(D, dtype=float)
+
+        if X.ndim == 1:
+            X = X[:, np.newaxis]
+
+        if self.check_dict:
+            _check_dict_normalized(D)
+
+        T = self.n_nonzero_coefs
+
+        if self.mode == "batch":
+            if G is None:
+                G = D.T @ D
+            DtX = D.T @ X
+            return batch_omp(DtX, G, T)
+
+        # cholesky mode — signal by signal
+        n_atoms = D.shape[1]
+        n_samples = X.shape[1]
+        Gamma = np.zeros((n_atoms, n_samples))
+        for i in range(n_samples):
+            Gamma[:, i] = omp_cholesky(D, X[:, i], T)
+        return Gamma

reppi-0.1.0/src/reppi/sparse/src.py

@@ -0,0 +1,67 @@
+"""
+Utility functions shared across sparse coding algorithms.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def normalize_columns(D: np.ndarray) -> np.ndarray:
+    """Return D with each column scaled to unit L2-norm.
+
+    Columns whose norm is below 1e-10 are left unchanged to avoid division
+    by zero.
+    """
+    norms = np.sqrt((D * D).sum(axis=0))
+    norms = np.where(norms < 1e-10, 1.0, norms)
+    return D / norms
+
+
+def col_norms_squared(X: np.ndarray, block_size: int = 2000) -> np.ndarray:
+    """Compute squared L2-norm of each column of X in blocks (memory-safe).
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (n_features, n_samples)
+    block_size : int
+        Number of columns to process at a time.
+
+    Returns
+    -------
+    norms2 : np.ndarray, shape (n_samples,)
+    """
+    n_samples = X.shape[1]
+    norms2 = np.zeros(n_samples)
+    for start in range(0, n_samples, block_size):
+        end = min(start + block_size, n_samples)
+        norms2[start:end] = (X[:, start:end] ** 2).sum(axis=0)
+    return norms2
+
+
+def rep_error_squared(
+    X: np.ndarray,
+    D: np.ndarray,
+    Gamma: np.ndarray,
+    block_size: int = 2000,
+) -> np.ndarray:
+    """Per-signal squared reconstruction error |x_i - D gamma_i|^2.
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (n_features, n_samples)
+    D : np.ndarray, shape (n_features, n_atoms)
+    Gamma : np.ndarray, shape (n_atoms, n_samples)
+    block_size : int
+
+    Returns
+    -------
+    err2 : np.ndarray, shape (n_samples,)
+    """
+    n_samples = X.shape[1]
+    err2 = np.zeros(n_samples)
+    for start in range(0, n_samples, block_size):
+        end = min(start + block_size, n_samples)
+        diff = X[:, start:end] - D @ Gamma[:, start:end]
+        err2[start:end] = (diff ** 2).sum(axis=0)
+    return err2

reppi-0.1.0/src/reppi.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: reppi
+Version: 0.1.0
+Summary: A Python toolkit for representation-based learning/classification algorithms
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: scipy>=1.17.1

reppi-0.1.0/src/reppi.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+src/reppi/__init__.py
+src/reppi/base.py
+src/reppi/exceptions.py
+src/reppi.egg-info/PKG-INFO
+src/reppi.egg-info/SOURCES.txt
+src/reppi.egg-info/dependency_links.txt
+src/reppi.egg-info/requires.txt
+src/reppi.egg-info/top_level.txt
+src/reppi/dictionary/__init__.py
+src/reppi/dictionary/ksvd.py
+src/reppi/dictionary/lc-ksvd.py
+src/reppi/dictionary/lc_ksvd.py
+src/reppi/linear/__init__.py
+src/reppi/linear/crc.py
+src/reppi/linear/lrc.py
+src/reppi/linear/lsr.py
+src/reppi/sparse/__init__.py
+src/reppi/sparse/omp.py
+src/reppi/sparse/src.py

reppi-0.1.0/src/reppi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

reppi-0.1.0/src/reppi.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy>=2.4.4
+scipy>=1.17.1

reppi-0.1.0/src/reppi.egg-info/top_level.txt

@@ -0,0 +1 @@
+reppi