pystatistics 2.0.0__tar.gz → 2.0.1__tar.gz

{pystatistics-2.0.0 → pystatistics-2.0.1}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 2.0.1
+
+- **GPU Backend Convention: codified when NOT to add a GPU backend**
+  (`pystatistics/GPU_BACKEND_CONVENTION.md`, new Section 0). Formalises
+  the Oprah-test rule: don't give every module a GPU backend — only
+  those where the algorithm is actually a good fit for GPU hardware
+  (large dense linear algebra, big-N likelihoods, batched independent
+  fits). Explicitly calls out the non-targets (many-small-fits,
+  sequential algorithms, transfer-bound cheap compute) and the ~100 ms
+  CPU-time threshold below which launch + PCIe overhead eats any
+  speedup. Names the deliberate CPU-only modules (`anova`,
+  `timeseries.ets`, `survival.coxph`, `multivariate.factor_analysis`,
+  acf / stationarity) so future contributors know these omissions are
+  intentional, not oversights.
+- **`auto_arima` now accepts `backend=` and `method=`**
+  (`pystatistics/timeseries/_arima_order.py`). Parameters are threaded
+  through `_stepwise_search` / `_grid_search` / `_try_fit` to every
+  candidate `arima()` call. Previously there was no way to route the
+  per-candidate fits through the GPU Whittle path, so on a
+  GPU-equipped box the search was stuck on CPU even if the user
+  wanted frequency-domain speedups. Default `backend=None` → CPU
+  (R-reference); pass `method='Whittle', backend='gpu'` to run each
+  candidate on GPU.
+- **`little_mcar_test` now accepts `backend=` and `algorithm=`**
+  (`pystatistics/mvnmle/mcar_test.py`). Previously the function had no
+  backend knob and always ran `mlest()` with the default — which after
+  2.0.0's CPU-default sweep meant there was no way to route Little's
+  MCAR test through the GPU path, defeating the purpose of having a
+  GPU MLE backend at all. The new `backend` parameter is forwarded
+  straight to `mlest`; default None → CPU (consistent with the 2.0.0
+  convention), `'gpu'` / `'auto'` opt in to GPU. The per-pattern
+  test-statistic accumulation still runs on CPU — it's O(P × v³) for
+  v = observed vars per pattern (typically < 50) and was never the
+  bottleneck; the ML estimation step is where GPU matters. Verified
+  GPU/CPU results agree within FP32 tolerance (Δ stat ≈ 1.4e-4 on
+  the apple dataset).
+
+
 ## 2.0.0
 
 - **BREAKING: Default backend is now CPU across all public solvers**

{pystatistics-2.0.0 → pystatistics-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pystatistics
-Version: 2.0.0
+Version: 2.0.1
 Summary: GPU-accelerated statistical computing for Python
 Project-URL: Homepage, https://sgcx.org/technology/pystatistics/
 Project-URL: Documentation, https://sgcx.org/docs/pystatistics/
@@ -51,6 +51,31 @@ GPU-accelerated statistical computing for Python.
 
 ## What's New
 
+### 2.0.1 — GPU-backend exposure gaps and a convention rule
+
+Two public functions had GPU-capable inner calls but no `backend=`
+parameter, so there was no way to route them through the GPU path —
+exactly the regression the 2.0.0 CPU-default sweep was trying *not*
+to create. Both fixed:
+
+- **`little_mcar_test`** now accepts `backend=` and `algorithm=`,
+  forwarded to `mlest`. The per-pattern test-statistic accumulation
+  still runs on CPU (O(P × v³) for tiny v — never the bottleneck).
+  GPU results match CPU within FP32 tolerance (Δ stat ≈ 1.4e-4 on
+  the apple dataset).
+- **`auto_arima`** now accepts `backend=` and `method=`, threaded
+  through `_stepwise_search` / `_grid_search` / `_try_fit` so every
+  candidate fit honours the same backend. Pass
+  `method='Whittle', backend='gpu'` to run each candidate on GPU.
+
+Also codified the "when to add a GPU backend, and when not to" rule
+as Section 0 of `pystatistics/GPU_BACKEND_CONVENTION.md` — the
+absence of `backends/gpu*.py` in a module (`anova`, `ets`, `coxph`,
+`factor_analysis`, acf / stationarity) is a deliberate statement,
+not an oversight. GPU backends belong on workloads that actually
+map to GPU hardware (large dense linear algebra, big-N likelihoods,
+batched fits, frequency-domain transforms), not on everything.
+
 ### 2.0.0 — CPU is now the default backend everywhere (breaking)
 
 Every public solver that previously defaulted to `backend='auto'` now

{pystatistics-2.0.0 → pystatistics-2.0.1}/README.md

@@ -4,6 +4,31 @@ GPU-accelerated statistical computing for Python.
 
 ## What's New
 
+### 2.0.1 — GPU-backend exposure gaps and a convention rule
+
+Two public functions had GPU-capable inner calls but no `backend=`
+parameter, so there was no way to route them through the GPU path —
+exactly the regression the 2.0.0 CPU-default sweep was trying *not*
+to create. Both fixed:
+
+- **`little_mcar_test`** now accepts `backend=` and `algorithm=`,
+  forwarded to `mlest`. The per-pattern test-statistic accumulation
+  still runs on CPU (O(P × v³) for tiny v — never the bottleneck).
+  GPU results match CPU within FP32 tolerance (Δ stat ≈ 1.4e-4 on
+  the apple dataset).
+- **`auto_arima`** now accepts `backend=` and `method=`, threaded
+  through `_stepwise_search` / `_grid_search` / `_try_fit` so every
+  candidate fit honours the same backend. Pass
+  `method='Whittle', backend='gpu'` to run each candidate on GPU.
+
+Also codified the "when to add a GPU backend, and when not to" rule
+as Section 0 of `pystatistics/GPU_BACKEND_CONVENTION.md` — the
+absence of `backends/gpu*.py` in a module (`anova`, `ets`, `coxph`,
+`factor_analysis`, acf / stationarity) is a deliberate statement,
+not an oversight. GPU backends belong on workloads that actually
+map to GPU hardware (large dense linear algebra, big-N likelihoods,
+batched fits, frequency-domain transforms), not on everything.
+
 ### 2.0.0 — CPU is now the default backend everywhere (breaking)
 
 Every public solver that previously defaulted to `backend='auto'` now

{pystatistics-2.0.0 → pystatistics-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pystatistics"
-version = "2.0.0"
+version = "2.0.1"
 description = "GPU-accelerated statistical computing for Python"
 readme = "README.md"
 license = "MIT"

{pystatistics-2.0.0 → pystatistics-2.0.1}/pystatistics/GPU_BACKEND_CONVENTION.md

@@ -10,6 +10,49 @@ Two exemplars to read alongside this doc:
 - `pystatistics/multivariate/_pca.py` + `backends/gpu_pca.py`
 - `pystatistics/multinomial/_solver.py` + `backends/gpu_likelihood.py`
 
+## 0. When to add a GPU backend — and when not to
+
+A GPU backend exists because the underlying computation is a good fit
+for GPU hardware, not because the module is public and therefore
+"deserves" one. Adding a GPU backend that doesn't make algorithmic
+sense is worse than having none at all: it invites users to pick a
+slower path, adds a maintenance surface, and forces convention
+compliance (Rules 1–9 below) for no benefit.
+
+**Reasonable targets:** large dense linear algebra (QR / SVD /
+Cholesky), per-iteration gradient evaluations on large design
+matrices, big-N likelihood evaluations, batched independent fits,
+frequency-domain transforms.
+
+**Not reasonable targets — do not add a GPU backend for these:**
+
+- Many-small-fits workflows where per-call launch overhead dominates
+  compute (e.g. ANOVA SS computation, which fits a chain of tiny
+  regressions — the CPU LAPACK call is microseconds, the GPU kernel
+  launch is milliseconds).
+- Inherently sequential algorithms without exploitable parallelism
+  (most EM variants below a certain dataset size, Cox PH partial
+  likelihood).
+- Algorithms already bounded by PCIe / D2H transfer, where the
+  compute is cheap enough that you spend more time copying data than
+  running the kernel.
+- Algorithms where the existing scipy / LAPACK implementation is
+  already within an order of magnitude of hardware peak — a 2× speedup
+  is not worth the convention-compliance + test + review cost.
+
+**Signal that GPU makes sense:** measured CPU time > 100 ms on a
+representative input, with > 80 % of that time in a compute kernel
+that maps to cuBLAS / cuSOLVER / cuFFT. Below that threshold, the
+launch + transfer overhead eats the win.
+
+If a public module has no `backends/gpu*.py`, that is a deliberate
+statement — like `anova`, `timeseries.ets`, `survival.coxph`,
+`multivariate.factor_analysis`, and the acf / stationarity families.
+The public API correspondingly does *not* expose a `backend=`
+parameter, which is the correct state (Rule 1: don't offer choices
+you can't honor; exposing `backend='gpu'` on a CPU-only module would
+violate fail-fast).
+
 ## 1. Input type determines default backend
 
 The top-level fit function accepts either a numpy array *or* a

{pystatistics-2.0.0 → pystatistics-2.0.1}/pystatistics/__init__.py

@@ -16,7 +16,7 @@ Usage:
     result = fit(design)
 """
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"
 __author__ = "Hai-Shuo"
 __email__ = "contact@sgcx.org"
 

{pystatistics-2.0.0 → pystatistics-2.0.1}/pystatistics/mvnmle/mcar_test.py

@@ -102,6 +102,8 @@ def regularized_inverse(matrix: np.ndarray,
 
 def little_mcar_test(data,
                      alpha: float = 0.05,
+                     backend: str | None = None,
+                     algorithm: str = 'direct',
                      verbose: bool = False) -> MCARTestResult:
     """
     Little's test for Missing Completely at Random (MCAR).
@@ -112,6 +114,14 @@ def little_mcar_test(data,
         Data matrix with missing values as np.nan.
     alpha : float, default=0.05
         Significance level
+    backend : str or None, default None
+        Backend for the ML estimation step (the dominant cost).
+        Default None → 'cpu' (R-reference path). Explicit: 'cpu',
+        'gpu', or 'auto' to prefer GPU when available. The per-pattern
+        test-statistic accumulation runs on CPU regardless — it's
+        O(P × v³) for tiny v and is not the bottleneck.
+    algorithm : str, default 'direct'
+        ML algorithm: 'direct' (BFGS) or 'em'. Forwarded to mlest.
     verbose : bool, default=False
         Print detailed progress
 
@@ -138,7 +148,9 @@ def little_mcar_test(data,
         print("Step 1: Computing ML estimates...")
 
     try:
-        ml_result = mlest(data_array, verbose=False)
+        ml_result = mlest(
+            data_array, backend=backend, algorithm=algorithm, verbose=False,
+        )
         mu_ml = ml_result.muhat
         sigma_ml = ml_result.sigmahat
     except Exception as e:

{pystatistics-2.0.0 → pystatistics-2.0.1}/pystatistics/timeseries/_arima_order.py

@@ -117,6 +117,8 @@ def _try_fit(
     ic: str,
     tol: float,
     max_iter: int,
+    method: str = "CSS-ML",
+    backend: str | None = None,
 ) -> tuple[object | None, float]:
     """Attempt to fit an ARIMA model; return (result, ic_value).
 
@@ -149,8 +151,10 @@ def _try_fit(
             y,
             order=order,
             seasonal=seasonal_order,
+            method=method,
             tol=tol,
             max_iter=max_iter,
+            backend=backend,
         )
         if not result.converged:
             return None, math.inf
@@ -229,6 +233,8 @@ def _stepwise_search(
     ic: str,
     tol: float,
     max_iter: int,
+    method: str = "CSS-ML",
+    backend: str | None = None,
 ) -> tuple[object, tuple[int, int, int], float, list[tuple[tuple, float]]]:
     """Stepwise ARIMA order selection.
 
@@ -274,7 +280,9 @@ def _stepwise_search(
     best_ic = math.inf
 
     for order in initial_orders:
-        result, ic_val = _try_fit(y, order, seasonal_order, ic, tol, max_iter)
+        result, ic_val = _try_fit(
+            y, order, seasonal_order, ic, tol, max_iter, method, backend,
+        )
         search_results.append((order, ic_val))
         if ic_val < best_ic:
             best_ic = ic_val
@@ -311,7 +319,7 @@ def _stepwise_search(
         for order in neighbours:
             visited.add(order)
             result, ic_val = _try_fit(
-                y, order, seasonal_order, ic, tol, max_iter
+                y, order, seasonal_order, ic, tol, max_iter, method, backend,
             )
             search_results.append((order, ic_val))
             if ic_val < best_ic:
@@ -336,6 +344,8 @@ def _grid_search(
     ic: str,
     tol: float,
     max_iter: int,
+    method: str = "CSS-ML",
+    backend: str | None = None,
 ) -> tuple[object, tuple[int, int, int], float, list[tuple[tuple, float]]]:
     """Exhaustive grid search over all (p, d, q) combinations.
 
@@ -368,7 +378,9 @@ def _grid_search(
 
     for p, q in itertools.product(range(max_p + 1), range(max_q + 1)):
         order = (p, d, q)
-        result, ic_val = _try_fit(y, order, seasonal_order, ic, tol, max_iter)
+        result, ic_val = _try_fit(
+            y, order, seasonal_order, ic, tol, max_iter, method, backend,
+        )
         search_results.append((order, ic_val))
         if ic_val < best_ic:
             best_ic = ic_val
@@ -403,6 +415,8 @@ def auto_arima(
     stepwise: bool = True,
     tol: float = 1e-8,
     max_iter: int = 1000,
+    method: str = "CSS-ML",
+    backend: str | None = None,
 ) -> AutoARIMAResult:
     """Automatic ARIMA model selection.
 
@@ -436,6 +450,15 @@ def auto_arima(
         Convergence tolerance passed to :func:`arima`.
     max_iter : int
         Maximum iterations passed to :func:`arima`.
+    method : str
+        Estimation method forwarded to every candidate fit. Default
+        ``'CSS-ML'`` matches R. Use ``'Whittle'`` with ``backend='gpu'``
+        to route each candidate through the frequency-domain GPU path.
+    backend : str or None
+        Backend forwarded to every candidate fit. Default ``None`` →
+        CPU (R-reference path). Pass ``'gpu'`` or ``'auto'`` to
+        opt into the GPU path; only meaningful when the candidate
+        fits actually support it (e.g. ``method='Whittle'``).
 
     Returns
     -------
@@ -486,11 +509,13 @@ def auto_arima(
     # --- Search ---
     if stepwise:
         best_result, best_order, best_ic_val, search_results = _stepwise_search(
-            arr, d, max_p, max_q, seasonal_order, ic, tol, max_iter
+            arr, d, max_p, max_q, seasonal_order, ic, tol, max_iter,
+            method, backend,
         )
     else:
         best_result, best_order, best_ic_val, search_results = _grid_search(
-            arr, d, max_p, max_q, seasonal_order, ic, tol, max_iter
+            arr, d, max_p, max_q, seasonal_order, ic, tol, max_iter,
+            method, backend,
         )
 
     models_fitted = sum(1 for _, v in search_results if v < math.inf)

{pystatistics-2.0.0 → pystatistics-2.0.1}/tests/mvnmle/test_gpu.py

@@ -331,3 +331,32 @@ class TestGPUEdgeCases:
         assert result_em.converged
         assert np.all(np.isfinite(result_direct.muhat))
         assert np.all(np.isfinite(result_direct.sigmahat))
+
+
+# =====================================================================
+# Little's MCAR test — backend forwarding
+# =====================================================================
+
+class TestLittleMCARGPU:
+    """Little's MCAR test must accept and honor backend=.
+
+    Regression coverage for the gap exposed during Project Lacuna:
+    pre-fix, little_mcar_test had no backend knob, so there was no
+    way to route the (dominant) ML estimation step through the GPU
+    path even though a GPU MLE backend existed.
+    """
+
+    def test_gpu_backend_runs(self):
+        from pystatistics.mvnmle import little_mcar_test
+        result = little_mcar_test(datasets.apple, backend='gpu')
+        assert np.isfinite(result.statistic)
+        assert 0.0 <= result.p_value <= 1.0
+        assert result.df > 0
+
+    def test_gpu_matches_cpu_within_fp32_tolerance(self):
+        from pystatistics.mvnmle import little_mcar_test
+        cpu = little_mcar_test(datasets.apple, backend='cpu')
+        gpu = little_mcar_test(datasets.apple, backend='gpu')
+        assert gpu.df == cpu.df
+        # FP32 mlest → ~1e-3 level agreement on the chi-sq statistic
+        assert abs(gpu.statistic - cpu.statistic) < 1e-2