stmmlib 0.2.0__tar.gz

stmmlib-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ghardapaty Ghiffary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stmmlib-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: stmmlib
+Version: 0.2.0
+Summary: Family-aware spatio-temporal mixed models (Gaussian + Beta) with optional GPU acceleration
+Author: Ghardapaty Ghiffary
+License: MIT
+Project-URL: Homepage, https://github.com/ghiffahry/STMMLib
+Project-URL: Repository, https://github.com/ghiffahry/STMMLib
+Project-URL: Issues, https://github.com/ghiffahry/STMMLib/issues
+Keywords: spatio-temporal,mixed models,small area estimation,Beta regression,generalized linear mixed models,areal data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.0
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=13.0; extra == "gpu"
+Requires-Dist: torch>=2.0; extra == "gpu"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# stmmlib
+
+Spatio-temporal mixed models for areal panel data, with Gaussian and Beta
+families behind one API.
+
+## Overview
+
+`stmmlib` fits area-level panel models that combine spatial random effects
+(IID, SAR, nested, SEBLUP Rao-Yu), temporal random effects (IID, AR(1)), and
+optional area-time interactions. Two likelihood families are available, so the
+same model structure can be fitted to continuous responses or to proportions.
+
+Developed as a reference implementation for a study of Indonesian district
+poverty data. It is a general tool for area-level panel data, does not
+depend on that dataset, and is published as a software reference.
+
+## Features
+
+- 14 model structures (M1 to M14) plus a Beta regression baseline
+- Gaussian family: ML and REML by marginal likelihood
+- Beta family: Laplace-approximated ML with convergence certificates (gradient
+  norm, Hessian positive definiteness, iteration count)
+- Prediction: EBLUP for Gaussian, EBP from posterior draws for Beta, both
+  in-sample and for same-area holdout
+- Configurable column names, so data does not need renaming
+- Fixed-effect inference in both families: Wald tests and restricted-refit
+  likelihood-ratio tests (`inference="lrt"`, `lrt_terms=[...]`)
+- Optional GPU backend through CuPy or PyTorch
+
+## Installation
+
+```bash
+pip install stmmlib
+```
+
+For the optional GPU backend:
+
+```bash
+pip install "stmmlib[gpu]"
+```
+
+Install from source instead:
+
+```bash
+git clone https://github.com/ghiffahry/STMMLib.git
+cd STMMLib
+pip install -e .
+```
+
+Run the test suite:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick start
+
+Runs end to end on synthetic data, nothing external needed:
+
+```python
+import numpy as np
+import pandas as pd
+from stmmlib.stmm import stmm
+
+m, T = 12, 6
+rng = np.random.default_rng(7)
+area = np.repeat(np.arange(m), T)
+time = np.tile(np.arange(T), m)
+
+df = pd.DataFrame({
+    "y": np.clip(rng.beta(6, 4, m * T), 1e-4, 1 - 1e-4),   # in (0, 1), as required
+    "area": area,
+    "time": time,
+    "x1": rng.normal(size=m * T),
+    "x2": rng.normal(size=m * T),
+})
+
+fit = stmm(data=df, model="m1_iid_iid", family="beta",
+           method="Laplace", gpu="no", n_starts=1)
+print(fit.summary())             # reads the certificate, refuses to call an invalid fit inference-grade
+print(fit.certificate["valid"])  # True/False: may the SEs be quoted?
+```
+
+Gaussian family, same call surface:
+
+```python
+df_gauss = df.assign(y=df["x1"] + rng.normal(0, 1, len(df)))
+W = np.ones((m, m)); np.fill_diagonal(W, 0); W /= W.sum(1, keepdims=True)
+
+fit = stmm(data=df_gauss, model="m3_sar_iid", family="gaussian",
+           W=W, method="REML", area_col="area", time_col="time", gpu="no")
+fit["beta_hat"]; fit["se_beta"]; fit["blup"]["v_hat"]
+```
+
+Fixed-effect inference in both families, Wald or likelihood-ratio test,
+and the requirement that the LRT compares ML likelihoods, are documented
+in `docs/API.md`.
+
+## Models
+
+| ID | Area effect | Time effect | Interaction |
+|---|---|---|---|
+| `m1_iid_iid` | IID | IID | none |
+| `m2_iid_ar1` | IID | AR(1) | none |
+| `m3_sar_iid` | SAR | IID | none |
+| `m4_sar_ar1` | SAR | AR(1) | none |
+| `m5_seblup_rao_yu_it` | SEBLUP Rao-Yu | AR(1) | none |
+| `m6_nested_iid_iid` | nested IID | IID | none |
+| `m7_nested_ar1` | nested SAR | AR(1) | none |
+| `m8_iid_iid_int` | IID | IID | IID |
+| `m9_sar_iid_int` | SAR | IID | spatial |
+| `m10_iid_ar1_int` | IID | AR(1) | temporal |
+| `m11_sar_ar1_int` | SAR | AR(1) | spatio-temporal |
+| `m12_seblup_rao_yu_it_int` | SEBLUP Rao-Yu | AR(1) | spatio-temporal |
+| `m13_nested_iid_iid_int` | nested IID | IID | temporal |
+| `m14_nested_ar1_int` | nested SAR | AR(1) | IID |
+| `beta_regression` | none | none | none |
+
+Models ending in `_int` add an interaction term between area and time effects.
+Models with SAR or SEBLUP area effects require `W`.
+
+## Estimation and prediction
+
+- Gaussian: `method="ML"` or `method="REML"`. The fit is returned as a dict
+  with `beta_hat`, `se_beta`, `log_lik`, `AIC`, `BIC`, and `blup`
+  (`v_hat`, `u_hat`, `se_v`).
+- Beta: `method="Laplace"`. The fit is an object with `summary()`,
+  `certificate`, `beta_original`, `se_original`, `ebp()`, and `ebp_newdata()`.
+- Fixed effects in the Beta family are standardised internally. Use
+  `beta_original` and `se_original` for reporting, not the standardised values.
+- `ebp_newdata()` predicts for held-out periods of areas seen during fitting.
+  Areas never seen during fitting are rejected.
+- Accuracy presets: `fast`, `balanced`, `medium`, `full`.
+
+## Requirements
+
+- Python 3.10 or newer
+- NumPy 1.24+, SciPy 1.11+, pandas 2.0+
+- CuPy and PyTorch only for the `gpu` extra
+
+## Documentation
+
+`docs/API.md` holds a compact API reference covering fitting, diagnostics, LRT,
+and prediction intervals.
+
+## Limitations
+
+- EBP here means `E[mu | y]`, computed from posterior draws. It is not the
+  Molina-Rao EBP, and its mean squared error is not implemented.
+- Spatial block cross-validation supports fixed effects only.
+- The Gaussian path is CPU only. Run it with `gpu="no"`.
+- Gaussian fits return a dict, Beta fits return an object. The two return types
+  are not unified yet.
+- Nested models with interactions are dense and slow. Raise `max_iter` for them.
+- `simulate_beta` supports the flat models M1-M5 and the interaction models
+  M8-M12. Nested models M6/M7/M13/M14 raise `ValueError`.
+- `beta_criteria` (cAIC, conditional R2) returns NaN for nested models; their
+  province/district/cell precision builder is not implemented.
+- When the automatic prior refit is used, the reported `logLik`, `AIC`, and
+  `BIC` are the penalized objective. The fit's `optim` record
+  (`fit._opt["optim"]`) flags this with `penalty_auto` and reports the
+  unpenalized value at the same estimate in `penalty_refit_msg`.
+
+## Citation
+
+```bibtex
+@software{ghiffahry_stmmlib,
+  author  = {Ghiffary, Ghardapaty},
+  title   = {STMMLib: spatio-temporal mixed models for areal panel data},
+  year    = {2026},
+  version = {0.2.0},
+  url     = {https://github.com/ghiffahry/STMMLib},
+  license = {MIT}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

stmmlib-0.2.0/README.md

@@ -0,0 +1,180 @@
+# stmmlib
+
+Spatio-temporal mixed models for areal panel data, with Gaussian and Beta
+families behind one API.
+
+## Overview
+
+`stmmlib` fits area-level panel models that combine spatial random effects
+(IID, SAR, nested, SEBLUP Rao-Yu), temporal random effects (IID, AR(1)), and
+optional area-time interactions. Two likelihood families are available, so the
+same model structure can be fitted to continuous responses or to proportions.
+
+Developed as a reference implementation for a study of Indonesian district
+poverty data. It is a general tool for area-level panel data, does not
+depend on that dataset, and is published as a software reference.
+
+## Features
+
+- 14 model structures (M1 to M14) plus a Beta regression baseline
+- Gaussian family: ML and REML by marginal likelihood
+- Beta family: Laplace-approximated ML with convergence certificates (gradient
+  norm, Hessian positive definiteness, iteration count)
+- Prediction: EBLUP for Gaussian, EBP from posterior draws for Beta, both
+  in-sample and for same-area holdout
+- Configurable column names, so data does not need renaming
+- Fixed-effect inference in both families: Wald tests and restricted-refit
+  likelihood-ratio tests (`inference="lrt"`, `lrt_terms=[...]`)
+- Optional GPU backend through CuPy or PyTorch
+
+## Installation
+
+```bash
+pip install stmmlib
+```
+
+For the optional GPU backend:
+
+```bash
+pip install "stmmlib[gpu]"
+```
+
+Install from source instead:
+
+```bash
+git clone https://github.com/ghiffahry/STMMLib.git
+cd STMMLib
+pip install -e .
+```
+
+Run the test suite:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick start
+
+Runs end to end on synthetic data, nothing external needed:
+
+```python
+import numpy as np
+import pandas as pd
+from stmmlib.stmm import stmm
+
+m, T = 12, 6
+rng = np.random.default_rng(7)
+area = np.repeat(np.arange(m), T)
+time = np.tile(np.arange(T), m)
+
+df = pd.DataFrame({
+    "y": np.clip(rng.beta(6, 4, m * T), 1e-4, 1 - 1e-4),   # in (0, 1), as required
+    "area": area,
+    "time": time,
+    "x1": rng.normal(size=m * T),
+    "x2": rng.normal(size=m * T),
+})
+
+fit = stmm(data=df, model="m1_iid_iid", family="beta",
+           method="Laplace", gpu="no", n_starts=1)
+print(fit.summary())             # reads the certificate, refuses to call an invalid fit inference-grade
+print(fit.certificate["valid"])  # True/False: may the SEs be quoted?
+```
+
+Gaussian family, same call surface:
+
+```python
+df_gauss = df.assign(y=df["x1"] + rng.normal(0, 1, len(df)))
+W = np.ones((m, m)); np.fill_diagonal(W, 0); W /= W.sum(1, keepdims=True)
+
+fit = stmm(data=df_gauss, model="m3_sar_iid", family="gaussian",
+           W=W, method="REML", area_col="area", time_col="time", gpu="no")
+fit["beta_hat"]; fit["se_beta"]; fit["blup"]["v_hat"]
+```
+
+Fixed-effect inference in both families, Wald or likelihood-ratio test,
+and the requirement that the LRT compares ML likelihoods, are documented
+in `docs/API.md`.
+
+## Models
+
+| ID | Area effect | Time effect | Interaction |
+|---|---|---|---|
+| `m1_iid_iid` | IID | IID | none |
+| `m2_iid_ar1` | IID | AR(1) | none |
+| `m3_sar_iid` | SAR | IID | none |
+| `m4_sar_ar1` | SAR | AR(1) | none |
+| `m5_seblup_rao_yu_it` | SEBLUP Rao-Yu | AR(1) | none |
+| `m6_nested_iid_iid` | nested IID | IID | none |
+| `m7_nested_ar1` | nested SAR | AR(1) | none |
+| `m8_iid_iid_int` | IID | IID | IID |
+| `m9_sar_iid_int` | SAR | IID | spatial |
+| `m10_iid_ar1_int` | IID | AR(1) | temporal |
+| `m11_sar_ar1_int` | SAR | AR(1) | spatio-temporal |
+| `m12_seblup_rao_yu_it_int` | SEBLUP Rao-Yu | AR(1) | spatio-temporal |
+| `m13_nested_iid_iid_int` | nested IID | IID | temporal |
+| `m14_nested_ar1_int` | nested SAR | AR(1) | IID |
+| `beta_regression` | none | none | none |
+
+Models ending in `_int` add an interaction term between area and time effects.
+Models with SAR or SEBLUP area effects require `W`.
+
+## Estimation and prediction
+
+- Gaussian: `method="ML"` or `method="REML"`. The fit is returned as a dict
+  with `beta_hat`, `se_beta`, `log_lik`, `AIC`, `BIC`, and `blup`
+  (`v_hat`, `u_hat`, `se_v`).
+- Beta: `method="Laplace"`. The fit is an object with `summary()`,
+  `certificate`, `beta_original`, `se_original`, `ebp()`, and `ebp_newdata()`.
+- Fixed effects in the Beta family are standardised internally. Use
+  `beta_original` and `se_original` for reporting, not the standardised values.
+- `ebp_newdata()` predicts for held-out periods of areas seen during fitting.
+  Areas never seen during fitting are rejected.
+- Accuracy presets: `fast`, `balanced`, `medium`, `full`.
+
+## Requirements
+
+- Python 3.10 or newer
+- NumPy 1.24+, SciPy 1.11+, pandas 2.0+
+- CuPy and PyTorch only for the `gpu` extra
+
+## Documentation
+
+`docs/API.md` holds a compact API reference covering fitting, diagnostics, LRT,
+and prediction intervals.
+
+## Limitations
+
+- EBP here means `E[mu | y]`, computed from posterior draws. It is not the
+  Molina-Rao EBP, and its mean squared error is not implemented.
+- Spatial block cross-validation supports fixed effects only.
+- The Gaussian path is CPU only. Run it with `gpu="no"`.
+- Gaussian fits return a dict, Beta fits return an object. The two return types
+  are not unified yet.
+- Nested models with interactions are dense and slow. Raise `max_iter` for them.
+- `simulate_beta` supports the flat models M1-M5 and the interaction models
+  M8-M12. Nested models M6/M7/M13/M14 raise `ValueError`.
+- `beta_criteria` (cAIC, conditional R2) returns NaN for nested models; their
+  province/district/cell precision builder is not implemented.
+- When the automatic prior refit is used, the reported `logLik`, `AIC`, and
+  `BIC` are the penalized objective. The fit's `optim` record
+  (`fit._opt["optim"]`) flags this with `penalty_auto` and reports the
+  unpenalized value at the same estimate in `penalty_refit_msg`.
+
+## Citation
+
+```bibtex
+@software{ghiffahry_stmmlib,
+  author  = {Ghiffary, Ghardapaty},
+  title   = {STMMLib: spatio-temporal mixed models for areal panel data},
+  year    = {2026},
+  version = {0.2.0},
+  url     = {https://github.com/ghiffahry/STMMLib},
+  license = {MIT}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

stmmlib-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stmmlib"
+version = "0.2.0"
+description = "Family-aware spatio-temporal mixed models (Gaussian + Beta) with optional GPU acceleration"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Ghardapaty Ghiffary"},
+]
+keywords = [
+    "spatio-temporal",
+    "mixed models",
+    "small area estimation",
+    "Beta regression",
+    "generalized linear mixed models",
+    "areal data",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.11",
+    "pandas>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ghiffahry/STMMLib"
+Repository = "https://github.com/ghiffahry/STMMLib"
+Issues = "https://github.com/ghiffahry/STMMLib/issues"
+
+[project.optional-dependencies]
+gpu = ["cupy-cuda12x>=13.0", "torch>=2.0"]
+dev = ["pytest>=7.0", "pytest-cov"]
+
+[tool.setuptools.packages.find]
+include = ["stmmlib*"]

stmmlib-0.2.0/setup.cfg

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

stmmlib-0.2.0/stmmlib/__init__.py

@@ -0,0 +1,30 @@
+"""stmmlib — Family-aware spatio-temporal mixed models.
+
+Supports 14 model structures (M1-M14) for Gaussian and Beta families,
+with optional CUDA/GPU acceleration via CuPy.
+"""
+
+from stmmlib.registry import (
+    stmm_available_models,
+    stmm_model_label,
+    stmm_parse_model,
+)
+from stmmlib.stmm import stmm, stmm_normal, stmm_beta
+from stmmlib.output_format import format_output
+from stmmlib._backend import Backend
+
+try:  # single source of truth for the version: the installed package metadata
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("stmmlib")
+except Exception:  # source checkout without an install
+    __version__ = "0.2.0"
+__all__ = [
+    "stmm",
+    "stmm_normal",
+    "stmm_beta",
+    "format_output",
+    "stmm_available_models",
+    "stmm_model_label",
+    "stmm_parse_model",
+    "Backend",
+]

stmmlib-0.2.0/stmmlib/_backend.py

@@ -0,0 +1,153 @@
+"""GPU/CPU backend abstraction with auto-detection.
+
+Usage:
+    backend = Backend(gpu="auto")  # auto-detect GPU
+    backend = Backend(gpu=True)    # force GPU (error if unavailable)
+    backend = Backend(gpu=False)   # force CPU
+
+All array operations go through backend.xp (numpy or cupy).
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Literal
+
+
+class Backend:
+    """Array backend that routes computation to CPU or GPU.
+
+    Attributes:
+        xp: Array namespace (numpy or cupy).
+        sparse: Sparse matrix namespace (scipy.sparse or cupyx.scipy.sparse).
+        device: "cpu" or "gpu".
+    """
+
+    def __init__(self, gpu: bool | Literal["auto"] = "auto") -> None:
+        self.xp = None
+        self.sparse = None
+        self.device: Literal["cpu", "gpu"] = "cpu"
+
+        use_gpu = self._resolve_gpu(gpu)
+
+        if use_gpu:
+            try:
+                import cupy as cp  # type: ignore[import-untyped]
+                import cupyx.scipy.sparse as csp  # type: ignore[import-untyped]
+
+                cp.zeros(1, dtype=cp.float64)  # test allocation
+                self.xp = cp  # type: ignore[assignment]
+                self.sparse = csp  # type: ignore[assignment]
+                self.device = "gpu"
+                return
+            except Exception as e:
+                if gpu is True:
+                    raise RuntimeError(f"GPU requested but unavailable: {e}") from e
+                warnings.warn(
+                    f"GPU unavailable ({e}), falling back to CPU.",
+                    stacklevel=2,
+                )
+
+        import numpy as np
+        import scipy.sparse as sp
+
+        self.xp = np  # type: ignore[assignment]
+        self.sparse = sp  # type: ignore[assignment]
+        self.device = "cpu"
+
+    @staticmethod
+    def _resolve_gpu(gpu: bool | Literal["auto"]) -> bool:
+        if isinstance(gpu, str):
+            g = gpu.strip().lower()
+            if g == "auto":
+                try:
+                    import cupy as cp  # type: ignore[import-untyped]
+
+                    cp.zeros(1, dtype=cp.float64)
+                    return True
+                except Exception:
+                    return False
+            if g in ("no", "false", "0", "off", "cpu"):
+                return False
+            if g in ("yes", "true", "1", "on", "gpu"):
+                return True
+        if gpu == "auto":
+            try:
+                import cupy as cp  # type: ignore[import-untyped]
+
+                cp.zeros(1, dtype=cp.float64)
+                return True
+            except Exception:
+                return False
+        return bool(gpu)
+
+    def to_cpu(self, arr):
+        """Move array to CPU. No-op if already on CPU."""
+        if self.device == "gpu":
+            return self.xp.asnumpy(arr)
+        return arr
+
+    def to_gpu(self, arr):
+        """Move array to GPU. No-op if already on CPU."""
+        if self.device == "gpu":
+            return self.xp.asarray(arr)
+        return arr
+
+    def is_sparse(self, m) -> bool:
+        """Check if matrix is a sparse matrix."""
+        if self.device == "gpu":
+            return self.sparse.issparse(m)
+        import scipy.sparse as sp
+
+        return sp.issparse(m)
+
+    def to_sparse(self, m):
+        """Convert dense array to sparse CSR."""
+        if self.is_sparse(m):
+            return m
+        if self.device == "gpu":
+            return self.sparse.csr_matrix(m)
+        import scipy.sparse as sp
+
+        return sp.csr_matrix(m)
+
+    def sparse_kron(self, A, B, format="csr"):
+        """Kronecker product of two (sparse) matrices."""
+        return self.sparse.kron(A, B, format=format)
+
+    def sparse_block_diag(self, mats):
+        """Block-diagonal from list of matrices."""
+        if self.device == "gpu":
+            return self.sparse.block_diag(mats, format="csr")
+        import scipy.sparse as sp
+
+        return sp.block_diag(mats, format="csr")
+
+    def sparse_eye(self, n, dtype=None):
+        """Identity matrix (sparse)."""
+        if dtype is None:
+            dtype = self.xp.float64
+        return self.sparse.eye(n, dtype=dtype, format="csr")
+
+    def solve(self, A, b):
+        """Solve linear system A @ x = b."""
+        return self.xp.linalg.solve(A, b)
+
+    def cholesky(self, A):
+        """Cholesky decomposition. Returns lower-triangular L where A = L @ L.T."""
+        return self.xp.linalg.cholesky(A)
+
+    def slogdet(self, A):
+        """Log-determinant via sign and log-abs-determinant."""
+        return self.xp.linalg.slogdet(A)
+
+    def eigh(self, A):
+        """Eigenvalues and eigenvectors of symmetric matrix."""
+        return self.xp.linalg.eigh(A)
+
+    def pinv(self, A):
+        """Moore-Penrose pseudo-inverse."""
+        return self.xp.linalg.pinv(A)
+
+    def __repr__(self) -> str:
+        return f"Backend(device={self.device!r})"