Metadata-Version: 2.3
Name: kccagpu
Version: 0.1.3
Summary: Fast implementation of Kernel Canonical Corellation Analysis using GPU
Author: Ivan
Author-email: Ivan <sonicivan321@gmail.com>
Requires-Dist: cupy-cuda12x>=14.2.0
Requires-Dist: numpy<=2.2
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# GPU-Accelerated Kernel Canonical Correlation Analysis (KCCA)

A high-performance GPU-accelerated Python implementation of Kernel Canonical Correlation Analysis (KCCA) using Numba and CuPy.

This module is designed to process high-dimensional datasets by optimizing RBF kernel matrix computation, feature space centering, covariance regularization, and canonical component decomposition via SVD and Cholesky factorization.

## Features

* Custom CUDA Kernels (Numba):
  * Fast RBF kernel computation directly from the Gram matrix.
  * Shared memory parallel reductions for row squared norms and row/column sums.
  * Kernel matrix centering and symmetrization in $O(N^2)$ time without allocating dense auxiliary matrices ($O(N^3)$ memory overhead).
  * Column scaling and dot product operations tuned for coalesced GPU memory access.

* Robust Decomposition with Adaptive Jitter:
  * Leverages CuPy Cholesky decomposition (`cp.linalg.cholesky`) with cuSOLVER exception handling.
  * Automatically injects adaptive diagonal jitter when handling ill-conditioned or non-positive-definite matrices.

* Native CuPy & cuBLAS Integration:
  * Blends high-level CuPy matrix operations (cuBLAS/cuSOLVER) with low-level custom CUDA kernels.

## Requirements & Prerequisites

An GPU with CUDA support is required alongside the following Python packages:

* **Python**: `>= 3.8`
* **NVIDIA CUDA Toolkit**: Version matching your GPU drivers.
* **CuPy**: Installed for your specific CUDA version (`cupy-cuda11x`, `cupy-cuda12x`, etc.).
* **Numba**: `>= 0.53`
* **NumPy**: `>= 1.20`

### Dependency Installation

```bash
pip install kccagpu
```


## 📖 Usage Example

Here is a basic example demonstrating how to run KCCA using `kcca_gpu.py`:

```python
import numpy as np
from kcca_gpu import KCCAGPU

#Generate synthetic data (D features x N samples)
n_samples = 1000
n_features = 50

X_a = np.random.randn(n_features, n_samples).astype(np.float32)
X_b = np.random.randn(n_features, n_samples).astype(np.float32)

#Initialize KCCA engine
kcca = KCCAGPU()

#Hyperparameters
gamma = 0.05  # RBF kernel bandwidth
reg = 1e-2    # Regularization parameter

#Prepare the reference view (X_b)
ref_b = kcca._prepare_reference(X_b, reg=reg, gamma=gamma)

#Compute projections and correlations
proj_a, proj_b, alpha, beta, corrs = kcca.kcca_projections(
    X_a=X_a,
    ref=ref_b,
    reg=reg,
    gamma=gamma
)

#Inspect results
print("Canonical correlations:", corrs)
print("Projection A shape:", proj_a.shape)
print("Projection B shape:", proj_b.shape)
```

## Code Structure & Key Methods

### `KCCAGPU` Class

| Method | Description |
| --- | --- |
| `compute_kernel(X, Y, gamma)` | Computes the RBF kernel matrix between two GPU arrays using row norms and cuBLAS Gram matrix multiplication. |
| `center_kernel(K)` | Centers and symmetrizes the kernel matrix in feature space without constructing full dense centering matrices. |
| `_reg_matrix(K, reg)` | Builds the regularized covariance matrix $R = K^2 + \text{reg} \cdot K + 10^{-6} I$. |
| `_safe_cholesky(R, max_tries)` | Performs Cholesky decomposition with adaptive diagonal jitter injection on failure. |
| `_prepare_reference(X_b, reg, gamma)` | Pre-computes the kernel matrix, regularized covariance, and Cholesky factor for reference view $X_b$. |
| `kcca_projections(X_a, ref, reg, gamma)` | Computes SVD of the cross-modal operator and returns projections ($K_x \alpha, K_y \beta$), weight vectors ($\alpha, \beta$), and canonical correlation values. |



## 📄 License

This module is distributed under the [MIT License](LICENSE).
