feat: add optional GPU backend and CLI/API backend selector

Introduce experimental GPU backend using CuPy to accelerate singleton (k=1) support counting; non-singleton candidates fall back to Rust (if available) or Python
Expose backend selection across layers:
accelerate.support_counts now accepts backend: Optional[str] (overrides GSPPY_BACKEND env when provided)
GSP._support and GSP.search accept a backend parameter and forward it to the acceleration layer
Add --backend option to CLI (choices: auto, python, rust, gpu); when non-auto, it sets GSPPY_BACKEND for the run
Update README with a new GPU acceleration section, installation via optional extra, runtime selection instructions, and revised CLI examples including --backend
Add gpu extra in pyproject.toml (cupy>=11,<14) to keep GPU dependencies optional
Maintain default CPU behavior (auto: try Rust, then Python) for backward compatibility

Author: jacksonpradolima

README.md

@@ -138,7 +138,26 @@ GSPPY_BACKEND=auto uv run --python .venv/bin/python --no-project \
   python benchmarks/bench_support.py --n_tx 1000000 --tx_len 8 --vocab 50000 --min_support 0.2 --warmup
 ```
 
-#### 4. Common development tasks
+#### 4. Optional: Enable GPU (CuPy) acceleration
+
+GPU acceleration is experimental and currently optimizes singleton (k=1) support counting using CuPy.
+Non-singleton candidates fall back to the Rust/Python backend.
+
+Install the optional extra (choose a CuPy build that matches your CUDA/ROCm setup if needed):
+
+```bash
+uv run pip install -e .[gpu]
+```
+
+Select the GPU backend at runtime:
+
+```bash
+export GSPPY_BACKEND=gpu
+```
+
+If a GPU isn't available, an error will be raised when GSPPY_BACKEND=gpu is set. Otherwise, the default "auto" uses CPU.
+
+#### 5. Common development tasks
 After the environment is ready, activate it and run tasks with standard tools:
 
 ```bash
@@ -228,19 +247,20 @@ Your input file should be either:
 Use the following command to run GSPPy on your data:
 
 ```bash
-gsppy --file path/to/transactions.json --min_support 0.3
+gsppy --file path/to/transactions.json --min_support 0.3 --backend auto
 ```
 
 Or for CSV files:
 
 ```bash
-gsppy --file path/to/transactions.csv --min_support 0.3
+gsppy --file path/to/transactions.csv --min_support 0.3 --backend rust
 ```
 
 #### CLI Options
 
 - `--file`: Path to your input file (JSON or CSV). **Required**.
 - `--min_support`: Minimum support threshold as a fraction (e.g., `0.3` for 30%). Default is `0.2`.
+- `--backend`: Backend to use for support counting. One of `auto` (default), `python`, `rust`, or `gpu`.
 - `--verbose`: (Optional) Enable detailed output for debugging.
 
 #### Example

gsppy/accelerate.py

@@ -15,10 +15,25 @@
 from __future__ import annotations
 
 import os
-from typing import Any, Dict, List, Tuple, cast
+from typing import Any, Dict, List, Tuple, Optional, cast
 
 from .utils import split_into_batches, is_subsequence_in_list
 
+# Optional GPU (CuPy) support
+_gpu_available = False
+try:  # pragma: no cover - optional dependency path
+    import cupy as _cp_mod  # type: ignore[import-not-found]
+
+    cp = cast(Any, _cp_mod)
+
+    try:
+        _gpu_available = cp.cuda.runtime.getDeviceCount() > 0  # type: ignore[attr-defined]
+    except Exception:
+        _gpu_available = False
+except Exception:  # pragma: no cover - optional dependency path
+    cp = None  # type: ignore[assignment]
+    _gpu_available = False
+
 # Simple per-process cache for encoded transactions keyed by the list object's id
 _ENCODED_CACHE: Dict[int, Tuple[List[List[int]], Dict[int, str], Dict[str, int], int]] = {}
 
@@ -89,6 +104,40 @@ def _encode_candidates(candidates: List[Tuple[str, ...]], vocab: Dict[str, int])
     return [[vocab[s] for s in cand] for cand in candidates]
 
 
+def _support_counts_gpu_singletons(
+    enc_tx: List[List[int]],
+    cand_ids: List[int],
+    min_support_abs: int,
+    vocab_size: int,
+) -> List[Tuple[List[int], int]]:
+    """GPU-accelerated support counts for singleton candidates using CuPy.
+
+    This computes the number of transactions containing each candidate item ID.
+    It uniquifies items per transaction on CPU to preserve presence semantics,
+    then performs a single bincount on GPU.
+    """
+    # Ensure one contribution per transaction
+    unique_rows: List[List[int]] = [list(set(row)) for row in enc_tx]
+    if not unique_rows:
+        return []
+
+    # Flatten to a 1D list of item ids, then move to GPU
+    flat: List[int] = [item for row in unique_rows for item in row]
+    if not flat:
+        return []
+
+    cp_flat = cp.asarray(flat, dtype=cp.int32)  # type: ignore[name-defined]
+    counts = cp.bincount(cp_flat, minlength=vocab_size)  # type: ignore[attr-defined]
+    counts_host: Any = counts.get()  # back to host as a NumPy array
+
+    out: List[Tuple[List[int], int]] = []
+    for cid in cand_ids:
+        freq = int(counts_host[cid])
+        if freq >= min_support_abs:
+            out.append(([cid], freq))
+    return out
+
+
 def support_counts_python(
     transactions: List[Tuple[str, ...]],
     candidates: List[Tuple[str, ...]],
@@ -118,30 +167,91 @@ def support_counts(
     candidates: List[Tuple[str, ...]],
     min_support_abs: int,
     batch_size: int = 100,
+    backend: Optional[str] = None,
 ) -> Dict[Tuple[str, ...], int]:
     """Choose the best available backend for support counting.
 
-    Backend selection is controlled by the env var GSPPY_BACKEND:
+    Backend selection is controlled by the `backend` argument when provided,
+    otherwise by the env var GSPPY_BACKEND:
     - "rust": require Rust extension (raise if missing)
+    - "gpu": try GPU path when available (currently singletons optimized),
+              fall back to CPU for the rest
     - "python": force pure-Python fallback
     - otherwise: try Rust first and fall back to Python
     """
-    backend = _env_backend()
+    backend_sel = (backend or _env_backend()).lower()
 
-    if backend == "python":
+    if backend_sel == "gpu":
+        if not _gpu_available:
+            raise RuntimeError("GSPPY_BACKEND=gpu but CuPy GPU is not available")
+        # Encode once
+        enc_tx, inv_vocab, vocab = _get_encoded_transactions(transactions)
+        enc_cands = _encode_candidates(candidates, vocab)
+
+        # Partition candidates into singletons and non-singletons
+        singletons: List[Tuple[int, Tuple[str, ...]]] = []
+        others: List[Tuple[List[int], Tuple[str, ...]]] = []
+        # Pair original and encoded candidates; lengths should match
+        assert len(candidates) == len(enc_cands), "Encoded candidates length mismatch"
+        for orig, enc in zip(candidates, enc_cands):  # noqa: B905 - lengths checked above
+            if len(enc) == 1:
+                singletons.append((enc[0], orig))
+            else:
+                others.append((enc, orig))
+
+        out: Dict[Tuple[str, ...], int] = {}
+
+        # GPU path for singletons
+        if singletons:
+            vocab_size = max(vocab.values()) + 1 if vocab else 0
+            gpu_res = _support_counts_gpu_singletons(
+                enc_tx=enc_tx,
+                cand_ids=[cid for cid, _ in singletons],
+                min_support_abs=min_support_abs,
+                vocab_size=vocab_size,
+            )
+            # Map back to original strings
+            cand_by_id: Dict[int, Tuple[str, ...]] = {cid: orig for cid, orig in singletons}
+            for enc_cand, freq in gpu_res:
+                cid = enc_cand[0]
+                out[cand_by_id[cid]] = int(freq)
+
+        # Fallback for others (prefer rust when available)
+        if others:
+            if _rust_available:
+                try:
+                    other_enc = [enc for enc, _ in others]
+                    res = cast(
+                        List[Tuple[List[int], int]], _compute_supports_rust(enc_tx, other_enc, int(min_support_abs))
+                    )
+                    for enc_cand, freq in res:
+                        out[tuple(inv_vocab[i] for i in enc_cand)] = int(freq)
+                except Exception:
+                    # fallback to python
+                    out.update(
+                        support_counts_python(transactions, [orig for _, orig in others], min_support_abs, batch_size)
+                    )
+            else:
+                out.update(
+                    support_counts_python(transactions, [orig for _, orig in others], min_support_abs, batch_size)
+                )
+
+        return out
+
+    if backend_sel == "python":
         return support_counts_python(transactions, candidates, min_support_abs, batch_size)
 
-    if backend == "rust":
+    if backend_sel == "rust":
         if not _rust_available:
             raise RuntimeError("GSPPY_BACKEND=rust but Rust extension _gsppy_rust is not available")
         # use rust
         enc_tx, inv_vocab, vocab = _get_encoded_transactions(transactions)
         enc_cands = _encode_candidates(candidates, vocab)
         result = cast(List[Tuple[List[int], int]], _compute_supports_rust(enc_tx, enc_cands, int(min_support_abs)))
-        out: Dict[Tuple[str, ...], int] = {}
+        out_rust: Dict[Tuple[str, ...], int] = {}
         for enc_cand, freq in result:
-            out[tuple(inv_vocab[i] for i in enc_cand)] = int(freq)
-        return out
+            out_rust[tuple(inv_vocab[i] for i in enc_cand)] = int(freq)
+        return out_rust
 
     # auto: try rust then fallback
     if _rust_available:

gsppy/cli.py

@@ -156,8 +156,15 @@ def detect_and_read_file(file_path: str) -> List[List[str]]:
     type=float,
     help="Minimum support threshold as a fraction of total transactions.",
 )
+@click.option(
+    "--backend",
+    type=click.Choice(["auto", "python", "rust", "gpu"], case_sensitive=False),
+    default="auto",
+    show_default=True,
+    help="Backend to use for support counting.",
+)
 @click.option("--verbose", is_flag=True, help="Enable verbose output for debugging purposes.")
-def main(file_path: str, min_support: float, verbose: bool) -> None:
+def main(file_path: str, min_support: float, backend: str, verbose: bool) -> None:
     """
     Run the GSP algorithm on transactional data from a file.
     """
@@ -175,6 +182,10 @@ def main(file_path: str, min_support: float, verbose: bool) -> None:
         logger.error("Error: min_support must be in the range (0.0, 1.0].")
         sys.exit(1)
 
+    # Select backend for acceleration layer
+    if backend and backend.lower() != "auto":
+        os.environ["GSPPY_BACKEND"] = backend.lower()
+
     # Initialize and run GSP algorithm
     try:
         gsp = GSP(transactions)

gsppy/gsp.py

@@ -235,15 +235,19 @@ def _support_python(
         return {item: freq for batch in batch_results for item, freq in batch}
 
     def _support(
-        self, items: List[Tuple[str, ...]], min_support: int = 0, batch_size: int = 100
+        self,
+        items: List[Tuple[str, ...]],
+        min_support: int = 0,
+        batch_size: int = 100,
+        backend: Optional[str] = None,
     ) -> Dict[Tuple[str, ...], int]:
         """
         Calculate support counts for candidate sequences using the fastest available backend.
         This will try the Rust extension if available (and configured), otherwise fall back to
         the Python multiprocessing implementation.
         """
         try:
-            return support_counts_accel(self.transactions, items, min_support, batch_size)
+            return support_counts_accel(self.transactions, items, min_support, batch_size, backend=backend)
         except Exception:
             # Fallback to Python implementation on any acceleration failure
             return self._support_python(items, min_support, batch_size)
@@ -261,7 +265,12 @@ def _print_status(self, run: int, candidates: List[Tuple[str, ...]]) -> None:
         """
         logger.info("Run %d: %d candidates filtered to %d.", run, len(candidates), len(self.freq_patterns[run - 1]))
 
-    def search(self, min_support: float = 0.2, max_k: Optional[int] = None) -> List[Dict[Tuple[str, ...], int]]:
+    def search(
+        self,
+        min_support: float = 0.2,
+        max_k: Optional[int] = None,
+        backend: Optional[str] = None,
+    ) -> List[Dict[Tuple[str, ...], int]]:
         """
         Execute the Generalized Sequential Pattern (GSP) mining algorithm.
 
@@ -302,7 +311,7 @@ def search(self, min_support: float = 0.2, max_k: Optional[int] = None) -> List[
 
         # scan transactions to collect support count for each candidate
         # sequence & filter
-        self.freq_patterns.append(self._support(candidates, abs_min_support))
+        self.freq_patterns.append(self._support(candidates, abs_min_support, backend=backend))
 
         # (k-itemsets/k-sequence = 1)
         k_items = 1
@@ -323,7 +332,7 @@ def search(self, min_support: float = 0.2, max_k: Optional[int] = None) -> List[
 
             # candidate pruning - eliminates candidates who are not potentially
             # frequent (using support as threshold)
-            self.freq_patterns.append(self._support(candidates, abs_min_support))
+            self.freq_patterns.append(self._support(candidates, abs_min_support, backend=backend))
 
             self._print_status(k_items, candidates)
         logger.info("GSP algorithm completed.")

pyproject.toml

@@ -54,6 +54,9 @@ dev = [
 rust = [
     "maturin==1.6.0"
 ]
+gpu = [
+    "cupy>=11,<14"
+]
 
 [tool.hatch.build]
 include = ["gsppy/*"]