sTiles 2026.7.19__tar.gz

stiles-2026.7.19/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: sTiles
+Version: 2026.7.19
+Summary: Python bindings for the sTiles sparse Cholesky / selected-inverse framework
+Author-email: Esmail Abdul Fattah <esmail.abdulfattah@kaust.edu.sa>
+Project-URL: Homepage, https://esmail-abdulfattah.github.io/sTiles/
+Project-URL: Repository, https://github.com/esmail-abdulfattah/sTiles
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.5

stiles-2026.7.19/README.md

@@ -0,0 +1,39 @@
+# pysTiles
+
+Python bindings for the **sTiles** sparse Cholesky / selected-inverse
+framework. Pure `ctypes` over the prebuilt `libstiles` shared object — no
+compiler or build step on the user's machine.
+
+```python
+import scipy.sparse as sp
+from pysTiles import sTiles
+
+with sTiles(Q, cores=4, mode="auto", inverse=True) as s:
+    s.logdet             # log|Q|
+    s.selinv_diag()      # diag(Q^-1) -> marginal variances
+    s.solve(b)           # Q x = b
+```
+
+Reuse the preprocessing (one symbolic analysis, many numeric factorizations):
+
+```python
+s = sTiles(Q0, cores=4, inverse=True)
+for theta in grid:
+    s.update_values(build_Q(theta))   # reuses ordering + layout
+    ll = ... s.logdet ...
+s.close()
+```
+
+## Install
+
+```bash
+pip install .
+# if the library isn't bundled or in a dev checkout:
+export STILES_LIB=/path/to/libstiles.so
+```
+
+The library is located via `$STILES_LIB`, `$STILES_LIB_DIR`, a bundled
+`pysTiles/_libs/<os>-<arch>/` binary, or a repo `lib/libstiles.so` fallback.
+
+See [`../README.md`](../README.md) for the full API table, the R binding, and
+CI/packaging notes. Run the self-check with `python examples/quickstart.py`.

stiles-2026.7.19/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sTiles"
+dynamic = ["version"]
+description = "Python bindings for the sTiles sparse Cholesky / selected-inverse framework"
+requires-python = ">=3.8"
+authors = [{ name = "Esmail Abdul Fattah", email = "esmail.abdulfattah@kaust.edu.sa" }]
+dependencies = ["numpy>=1.20", "scipy>=1.5"]
+classifiers = [
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+]
+
+[project.urls]
+Homepage = "https://esmail-abdulfattah.github.io/sTiles/"
+Repository = "https://github.com/esmail-abdulfattah/sTiles"
+
+[tool.setuptools]
+packages = ["sTiles"]
+
+[tool.setuptools.dynamic]
+version = { attr = "sTiles._version.__version__" }
+
+[tool.setuptools.package-data]
+# Prebuilt libstiles binaries dropped in by CI (per platform sub-directory).
+# These are large and are NOT committed to git; a release wheel bundles the
+# matching one. Layout: _libs/<os>-<arch>/libstiles.{so,dylib} (see sync_binaries.sh).
+sTiles = ["_libs/**/*.so", "_libs/**/*.dylib", "_libs/*.so", "_libs/*.dylib"]

stiles-2026.7.19/sTiles/__init__.py

@@ -0,0 +1,40 @@
+"""
+sTiles -- Python bindings for the sTiles sparse Cholesky / selected-inverse
+framework (KAUST).
+
+Loads the prebuilt ``libstiles`` shared object via ctypes; no build step and no
+compiler required on the user's machine.
+
+Quick start
+-----------
+    import scipy.sparse as sp
+    from sTiles import sTiles
+
+    with sTiles(Q, cores=4, inverse=True) as s:
+        s.logdet
+        s.selinv_diag()      # diag(Q^-1)
+        s.solve(b)           # Q x = b
+"""
+
+from .core import sTiles, factorize, version, library_path
+from .core import (
+    MODE_AUTO,
+    MODE_DENSE,
+    MODE_SEMISPARSE,
+    MODE_SPARSE,
+    sTilesError,
+)
+
+__all__ = [
+    "sTiles",
+    "factorize",
+    "version",
+    "library_path",
+    "sTilesError",
+    "MODE_AUTO",
+    "MODE_DENSE",
+    "MODE_SEMISPARSE",
+    "MODE_SPARSE",
+]
+
+from ._version import __version__  # date-based CalVer, YYYY.M.D

stiles-2026.7.19/sTiles/_ffi.py

@@ -0,0 +1,331 @@
+"""
+Low-level ctypes binding to libstiles.
+
+This module does exactly three things:
+
+  1. Locate the shared library (``libstiles.so`` on Linux, ``libstiles.dylib``
+     on macOS) for the current platform.
+  2. ``ctypes.CDLL`` it.
+  3. Declare the ``argtypes`` / ``restype`` for every ``sTiles_*`` entry point
+     the high-level wrapper uses.
+
+Everything user-facing lives in :mod:`sTiles.core`; this file is the raw
+FFI surface and has no NumPy/SciPy dependency.
+
+Library search order (first hit wins)
+-------------------------------------
+  1. ``$STILES_LIB``            -- full path to the shared object.
+  2. ``$STILES_LIB_DIR``        -- directory containing it.
+  3. ``$STILES_BINARIES_DIR``   -- a CI-artifact tree with
+                                   ``libstiles-<plat>/lib/libstiles.{so,dylib}``.
+  4. a ``binaries/`` (or ``bindings/binaries/``) directory in any ancestor,
+     using the same CI-artifact layout -- so unzipped GitHub Actions artifacts
+     dropped in ``bindings/binaries/`` are found with zero configuration.
+  5. bundled ``_libs/<plat>/``  -- shipped inside the wheel / R package by CI.
+  6. repo dev fallback          -- ``lib/libstiles.{so,dylib}`` in an ancestor.
+  7. GitHub Release download     -- the matching platform library is fetched from
+                                   the project's Release assets and cached (this
+                                   is what makes ``pip install`` work). Disable
+                                   with ``$STILES_NO_DOWNLOAD=1``.
+
+The library built for Linux embeds MKL/SCOTCH/METIS statically and localizes
+their symbols, so a plain ``CDLL`` is safe even inside a process that already
+loaded its own MKL (e.g. R, or MKL-backed NumPy/SciPy).  The macOS build links Homebrew OpenBLAS +
+LAPACK, so those must be discoverable at load time on a Mac.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+import shutil
+import sys
+import tempfile
+import urllib.request
+import zipfile
+from ctypes import (
+    POINTER,
+    c_bool,
+    c_char_p,
+    c_double,
+    c_int,
+    c_longlong,
+    c_void_p,
+)
+from pathlib import Path
+
+__all__ = ["lib", "library_path", "c_int_p", "c_double_p", "c_bool_p"]
+
+c_int_p = POINTER(c_int)
+c_double_p = POINTER(c_double)
+c_bool_p = POINTER(c_bool)
+
+# Suppress the one-time ASCII banner libstiles prints on first use.  Set before
+# the library is loaded so its getenv() sees it; overridable by exporting
+# STILES_NO_BANNER=0 for users who want the banner.
+os.environ.setdefault("STILES_NO_BANNER", "1")
+
+
+def _platform_tag() -> str:
+    """Return the ``<os>-<arch>`` sub-directory name used for bundled libs."""
+    machine = platform.machine().lower()
+    arch = {
+        "x86_64": "x86_64",
+        "amd64": "x86_64",
+        "arm64": "arm64",
+        "aarch64": "arm64",
+    }.get(machine, machine)
+    if sys.platform == "darwin":
+        return f"macos-{arch}"
+    if sys.platform.startswith("linux"):
+        return f"linux-{arch}"
+    return f"{sys.platform}-{arch}"
+
+
+def _ci_folder() -> str:
+    """Name of the CI build-artifact directory for this platform.
+
+    The GitHub Actions ``build`` workflow uploads one directory per target as
+    ``libstiles-<name>/lib/libstiles.{so,dylib}`` -- these names differ from the
+    bundle ``<os>-<arch>`` tag (e.g. ``libstiles-macos-apple-arm64``).
+    """
+    machine = platform.machine().lower()
+    arch = {"x86_64": "x86_64", "amd64": "x86_64",
+            "arm64": "arm64", "aarch64": "arm64"}.get(machine, machine)
+    if sys.platform == "darwin":
+        return "libstiles-macos-apple-arm64" if arch == "arm64" \
+            else "libstiles-macos-intel-x86_64"
+    if sys.platform.startswith("linux"):
+        return f"libstiles-linux-{arch}"
+    if sys.platform.startswith("win"):
+        return f"libstiles-windows-{arch}"
+    return f"libstiles-{sys.platform}-{arch}"
+
+
+def _lib_filename() -> str:
+    if sys.platform == "darwin":
+        return "libstiles.dylib"
+    if sys.platform.startswith("win"):
+        return "libstiles.dll"
+    return "libstiles.so"
+
+
+def _candidate_paths() -> list[Path]:
+    fname = _lib_filename()
+    ci = _ci_folder()
+    cands: list[Path] = []
+
+    env_lib = os.environ.get("STILES_LIB")
+    if env_lib:
+        cands.append(Path(env_lib))
+
+    env_dir = os.environ.get("STILES_LIB_DIR")
+    if env_dir:
+        cands.append(Path(env_dir) / fname)
+
+    here = Path(__file__).resolve().parent
+
+    # CI binaries tree: <root>/libstiles-<ci>/lib/libstiles.{so,dylib}.
+    # Explicit root, then any `binaries/` or `bindings/binaries/` above us.
+    env_bin = os.environ.get("STILES_BINARIES_DIR")
+    if env_bin:
+        cands.append(Path(env_bin) / ci / "lib" / fname)
+    for parent in [here, *here.parents]:
+        cands.append(parent / "binaries" / ci / "lib" / fname)
+        cands.append(parent / "bindings" / "binaries" / ci / "lib" / fname)
+
+    # Bundled: sTiles/_libs/<plat>/libstiles.{so,dylib} and a flat fallback.
+    cands.append(here / "_libs" / _platform_tag() / fname)
+    cands.append(here / "_libs" / fname)
+
+    # Cache dir from a previous release download (see _download_from_release).
+    cands.append(_cache_dir() / ci / fname)
+
+    # Repo dev fallback: search ancestors for lib/libstiles.{so,dylib}.
+    for parent in [here, *here.parents]:
+        cands.append(parent / "lib" / fname)
+
+    return cands
+
+
+# ---------------------------------------------------------------------------
+# Fetch the matching prebuilt libstiles from the GitHub Release.
+#
+# When pip-installed there is no binary in the tree, so on first use we download
+# the platform library from the project's Release assets and cache it under the
+# user cache dir.  The Linux/macOS builds are self-contained (BLAS embedded), so
+# the cached file loads with no extra system packages.
+#
+# Overrides:
+#   $STILES_NO_DOWNLOAD=1      -- never hit the network (raise instead).
+#   $STILES_RELEASE_REPO       -- "owner/repo" hosting the Release (default below).
+#   $STILES_RELEASE_BASE_URL   -- full base URL for the assets (bypasses the repo).
+#   $STILES_CACHE_DIR          -- where to cache the downloaded library.
+# ---------------------------------------------------------------------------
+_RELEASE_REPO = os.environ.get("STILES_RELEASE_REPO", "esmail-abdulfattah/sTiles")
+
+
+def _cache_dir() -> Path:
+    env = os.environ.get("STILES_CACHE_DIR")
+    if env:
+        return Path(env)
+    if sys.platform.startswith("win"):
+        base = os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local"))
+        return Path(base) / "sTiles"
+    base = os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))
+    return Path(base) / "sTiles"
+
+
+def _download_from_release() -> Path | None:
+    """Download the matching libstiles into the cache; return its path or None."""
+    if os.environ.get("STILES_NO_DOWNLOAD"):
+        return None
+    ci = _ci_folder()
+    fname = _lib_filename()
+    dest = _cache_dir() / ci
+    lib_path = dest / fname
+    if lib_path.is_file():
+        return lib_path  # already downloaded on a previous run
+
+    base = os.environ.get(
+        "STILES_RELEASE_BASE_URL",
+        f"https://github.com/{_RELEASE_REPO}/releases/latest/download",
+    )
+    url = f"{base}/{ci}.zip"
+    try:
+        dest.mkdir(parents=True, exist_ok=True)
+        sys.stderr.write(f"sTiles: fetching libstiles for {ci} from {url}\n")
+        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+            with urllib.request.urlopen(url) as resp:  # noqa: S310
+                shutil.copyfileobj(resp, tmp)
+            tmp_zip = tmp.name
+        try:
+            with zipfile.ZipFile(tmp_zip) as zf:
+                for member in zf.namelist():
+                    bn = os.path.basename(member)
+                    # The library, plus (Windows) the sibling runtime DLLs.
+                    want = bn == fname or (
+                        sys.platform.startswith("win") and bn.lower().endswith(".dll")
+                    )
+                    if want:
+                        with zf.open(member) as src, open(dest / bn, "wb") as out:
+                            shutil.copyfileobj(src, out)
+        finally:
+            os.unlink(tmp_zip)
+    except Exception as exc:  # noqa: BLE001 - any failure -> fall through to error
+        sys.stderr.write(f"sTiles: release download failed ({exc})\n")
+        return None
+    return lib_path if lib_path.is_file() else None
+
+
+def _load() -> tuple[ctypes.CDLL, str]:
+    tried: list[str] = []
+    for path in _candidate_paths():
+        tried.append(str(path))
+        if path.is_file():
+            try:
+                return ctypes.CDLL(str(path)), str(path)
+            except OSError as exc:  # pragma: no cover - surfaced below
+                tried[-1] += f"  (load failed: {exc})"
+
+    # Nothing local: fetch the prebuilt library from the GitHub Release.
+    downloaded = _download_from_release()
+    if downloaded is not None:
+        tried.append(str(downloaded))
+        try:
+            return ctypes.CDLL(str(downloaded)), str(downloaded)
+        except OSError as exc:
+            tried[-1] += f"  (load failed: {exc})"
+
+    # Last resort: let the loader resolve a bare SONAME via LD_LIBRARY_PATH.
+    try:
+        return ctypes.CDLL(_lib_filename()), _lib_filename()
+    except OSError:
+        pass
+
+    raise OSError(
+        "Could not locate libstiles for this platform.\n"
+        "The automatic download from the GitHub Release failed or was disabled.\n"
+        "Set $STILES_LIB to the shared object, point $STILES_BINARIES_DIR at a\n"
+        f"CI-artifact tree ({_ci_folder()}/lib/{_lib_filename()}), or drop it in\n"
+        f"sTiles/_libs/{_platform_tag()}/{_lib_filename()}.\nSearched:\n  "
+        + "\n  ".join(tried)
+    )
+
+
+lib, library_path = _load()
+
+
+# ---------------------------------------------------------------------------
+# Prototype declarations.
+#
+# The handle is an opaque ``void*``; every lifecycle call takes ``void**`` which
+# on the Python side is ``byref(c_void_p)``.  We declare those params as
+# ``c_void_p`` (a pointer-to-pointer is still just an address) and always pass
+# ``ctypes.byref(handle)`` at the call site.
+# ---------------------------------------------------------------------------
+def _decl(name, restype, argtypes):
+    fn = getattr(lib, name)
+    fn.restype = restype
+    fn.argtypes = argtypes
+    return fn
+
+
+# Version / logging ---------------------------------------------------------
+_decl("sTiles_get_version", c_char_p, [])
+_decl("sTiles_set_log_level", None, [c_int])
+_decl("sTiles_expert_user", None, [])
+
+# Global configuration ------------------------------------------------------
+_decl("sTiles_set_tile_size", None, [c_int])
+_decl("sTiles_return_tile_size", c_int, [])
+_decl("sTiles_get_auto_tile_size", c_int, [])
+_decl("sTiles_set_tile_type_mode", None, [c_int])
+_decl("sTiles_set_ordering_mode", None, [c_int])
+_decl("sTiles_force_ND", None, [c_int])
+
+# Lifecycle -----------------------------------------------------------------
+# int sTiles_create(void**, int num_groups, const int* calls_per_group,
+#                   const int* cores_per_group, const int* chol_type,
+#                   const bool* get_inverse)
+_decl("sTiles_create", c_int,
+      [c_void_p, c_int, c_int_p, c_int_p, c_int_p, c_bool_p])
+# int sTiles_assign_graph_one_call(int g, int c, void**, int n, int nnz,
+#                                  int* row, int* col)
+_decl("sTiles_assign_graph_one_call", c_int,
+      [c_int, c_int, c_void_p, c_int, c_int, c_int_p, c_int_p])
+_decl("sTiles_init_group", c_int, [c_int, c_void_p])
+_decl("sTiles_assign_values", c_int, [c_int, c_int, c_void_p, c_double_p])
+_decl("sTiles_bind", c_int, [c_int, c_int, c_void_p])
+_decl("sTiles_unbind", c_int, [c_int, c_int, c_void_p])
+_decl("sTiles_chol", c_int, [c_int, c_int, c_void_p])
+_decl("sTiles_selinv", c_int, [c_int, c_int, c_void_p])
+_decl("sTiles_freeGroup", None, [c_int])
+_decl("sTiles_quit", None, [])
+
+# Result accessors ----------------------------------------------------------
+_decl("sTiles_get_logdet", c_double, [c_int, c_int, c_void_p])
+_decl("sTiles_get_nnz_factor", c_longlong, [c_int, c_int, c_void_p])
+_decl("sTiles_get_selinv_elm", c_double, [c_int, c_int, c_int, c_int, c_void_p])
+_decl("sTiles_get_chol_elm", c_double, [c_int, c_int, c_int, c_int, c_void_p])
+# double* sTiles_get_selinv_row(int g, int c, int node, int* neighbors,
+#                               int size, void**)
+_decl("sTiles_get_selinv_row", c_double_p,
+      [c_int, c_int, c_int, c_int_p, c_int, c_void_p])
+_decl("sTiles_clear_selinv", c_int, [c_int, c_int, c_void_p])
+_decl("sTiles_get_chol_timing", c_double, [c_int, c_int, c_void_p])
+_decl("sTiles_get_selinv_timing", c_double, [c_int, c_int, c_void_p])
+
+# Permutation ---------------------------------------------------------------
+# int sTiles_get_logical_element_perm(int g, int c, void**, int* out_perm)
+_decl("sTiles_get_logical_element_perm", c_int, [c_int, c_int, c_void_p, c_int_p])
+
+# Solvers (B is column-major, original order, overwritten in place) ----------
+_decl("sTiles_solve_LLT", c_int, [c_int, c_int, c_void_p, c_double_p, c_int])
+_decl("sTiles_solve_L", c_int, [c_int, c_int, c_void_p, c_double_p, c_int])
+_decl("sTiles_solve_LT", c_int, [c_int, c_int, c_void_p, c_double_p, c_int])
+
+# Memory estimate (static, no handle) --------------------------------------
+_decl("sTiles_estimate_memory", c_double,
+      [c_int, c_int, c_int, c_int, c_int, c_int])

stiles-2026.7.19/sTiles/_version.py

@@ -0,0 +1,3 @@
+# Single source of truth for the sTiles Python package version.
+# Date-based (CalVer): YYYY.M.D. Bump with ../release.sh (stamps today's date).
+__version__ = "2026.7.19"

stiles-2026.7.19/sTiles/core.py

@@ -0,0 +1,473 @@
+"""
+High-level Python interface to sTiles.
+
+Typical use (compute a Cholesky, log-determinant, marginal variances, solve)::
+
+    import numpy as np, scipy.sparse as sp
+    from sTiles import sTiles
+
+    Q = ...                       # symmetric positive-definite sparse matrix
+    with sTiles(Q, cores=4, inverse=True) as s:
+        print(s.logdet)           # log|Q|
+        var = s.selinv_diag()     # diag(Q^-1)  -> marginal variances
+        x   = s.solve(b)          # Q x = b
+
+Reuse the preprocessing -- factor many matrices that share one sparsity pattern
+without repeating the (expensive) symbolic analysis::
+
+    s = sTiles(Q0, cores=4, inverse=True)
+    for theta in grid:
+        s.factorize(build_Q(theta))        # reuses ordering + layout
+        loglik = ... s.logdet ...
+    s.close()
+
+Notes
+-----
+* The matrix must be symmetric positive-definite.  Only the lower triangle is
+  read; the upper triangle (if present) is ignored.
+* All indices exposed by this API are 0-based in the *original* ordering of the
+  input matrix -- sTiles undoes its internal fill-reducing permutation for you.
+* State inside libstiles is keyed by an integer ``group`` index.  Distinct live
+  :class:`sTiles` objects must use distinct ``group`` values (default 0).
+"""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import byref, c_bool, c_int, c_void_p
+
+import numpy as np
+
+from . import _ffi
+from ._ffi import lib
+
+__all__ = ["sTiles", "factorize", "version", "library_path"]
+
+# tile_type_mode values (mirror stiles.h)
+MODE_DENSE = 0
+MODE_SEMISPARSE = 1
+MODE_SPARSE = 2
+MODE_AUTO = 3
+_MODE_ALIASES = {
+    "dense": MODE_DENSE,
+    "semisparse": MODE_SEMISPARSE,
+    "semi": MODE_SEMISPARSE,
+    "sparse": MODE_SPARSE,
+    "auto": MODE_AUTO,
+}
+
+
+def version() -> str:
+    raw = lib.sTiles_get_version()
+    return raw.decode() if raw else "unknown"
+
+
+def library_path() -> str:
+    """Absolute path of the loaded libstiles shared object."""
+    return _ffi.library_path
+
+
+def _resolve_mode(mode) -> int:
+    if isinstance(mode, str):
+        try:
+            return _MODE_ALIASES[mode.lower()]
+        except KeyError:
+            raise ValueError(
+                f"unknown mode {mode!r}; use one of {sorted(_MODE_ALIASES)}"
+            ) from None
+    return int(mode)
+
+
+def _lower_coo(Q):
+    """
+    Reduce a square symmetric matrix to its lower triangle in a canonical COO
+    order (sorted by (row, col)), returned as int32 row/col and float64 values.
+
+    Accepts anything SciPy can turn into a COO matrix, or a dense ndarray.
+    """
+    import scipy.sparse as sp
+
+    if sp.issparse(Q):
+        coo = sp.tril(Q).tocoo()
+        row = np.ascontiguousarray(coo.row, dtype=np.int32)
+        col = np.ascontiguousarray(coo.col, dtype=np.int32)
+        val = np.ascontiguousarray(coo.data, dtype=np.float64)
+        n = Q.shape[0]
+    else:
+        A = np.asarray(Q, dtype=np.float64)
+        if A.ndim != 2 or A.shape[0] != A.shape[1]:
+            raise ValueError("matrix must be square 2-D")
+        n = A.shape[0]
+        ii, jj = np.nonzero(np.tril(A))
+        row = np.ascontiguousarray(ii, dtype=np.int32)
+        col = np.ascontiguousarray(jj, dtype=np.int32)
+        val = np.ascontiguousarray(A[ii, jj], dtype=np.float64)
+
+    if Q.shape[0] != Q.shape[1]:
+        raise ValueError("matrix must be square")
+
+    # Canonical (row, col) order so repeated factorizations of the same pattern
+    # line up value-for-value.
+    order = np.lexsort((col, row))
+    return int(n), row[order].copy(), col[order].copy(), val[order].copy()
+
+
+class sTilesError(RuntimeError):
+    pass
+
+
+class sTiles:
+    """
+    A live sTiles factorization of one symmetric positive-definite matrix.
+
+    Parameters
+    ----------
+    Q : scipy.sparse matrix or 2-D ndarray
+        Symmetric positive-definite matrix.  Only the lower triangle is used.
+    cores : int
+        Worker threads for the factorization (default 1).
+    mode : {'auto','dense','semisparse','sparse'} or int
+        Tile factorization regime (default 'auto').
+    tile_size : int
+        Tile size; use -1 for sTiles auto-detection (default 40).
+    inverse : bool
+        Reserve storage for the selected inverse.  Must be True to call
+        :meth:`selinv_diag`, :meth:`selinv_elm`, or :meth:`selinv_row`
+        (default False).
+    group : int
+        libstiles group index; use distinct values for concurrent instances.
+    log_level : int
+        Verbosity of libstiles' own logging (default -1 = silent).  Errors are
+        always shown.  Use 0 for [TIME] markers, 1 = info, 2 = debug, 3 = trace.
+    factorize : bool
+        If True (default) run the numeric Cholesky as part of construction.  If
+        False, only the preprocessing (symbolic analysis) runs, and you call
+        :meth:`factorize` yourself -- letting you time the two phases apart.
+
+    Notes
+    -----
+    Construction has two phases: **preprocessing** (ordering bake-off + tile
+    layout, depends only on the sparsity pattern) and the **numeric** Cholesky.
+    With ``factorize=False`` the constructor stops after preprocessing::
+
+        s = sTiles(Q, inverse=True, factorize=False)   # time preprocessing
+        s.factorize()                                   # time the numeric part
+        s.chol_time                                     # library-measured numeric time
+    """
+
+    def __init__(self, Q, cores=1, mode="auto", tile_size=40, inverse=False,
+                 group=0, log_level=-1, factorize=True):
+        self._closed = False
+        self._handle = c_void_p(None)
+        self.group = int(group)
+        self.want_inverse = bool(inverse)
+        self._factored = False
+        self._selinv_done = False
+        self.cores = int(cores)
+        self.mode = _resolve_mode(mode)
+
+        n, row, col, val = _lower_coo(Q)
+        self.n = n
+        self.nnz = row.size
+        self._row = row          # keep refs alive for the lib's lifetime
+        self._col = col
+        self._values = val
+
+        lib.sTiles_set_log_level(int(log_level))
+
+        # --- global configuration (expert mode gates the setters) ----------
+        lib.sTiles_expert_user()
+        lib.sTiles_set_tile_size(int(tile_size))
+        lib.sTiles_set_tile_type_mode(self.mode)
+
+        # --- create handle -------------------------------------------------
+        # State inside libstiles is indexed by group; a handle must be created
+        # with at least (group+1) groups for `group` to be a valid slot.  Only
+        # our group gets a graph; the rest stay empty.
+        ng = self.group + 1
+        calls = (c_int * ng)(*([1] * ng))
+        cores_arr = (c_int * ng)(*([self.cores] * ng))
+        chol_type = (c_int * ng)(*([0] * ng))   # 0 = sparse factorization variant
+        get_inv = (c_bool * ng)(*([self.want_inverse] * ng))
+        rc = lib.sTiles_create(byref(self._handle), ng, calls, cores_arr,
+                               chol_type, get_inv)
+        self._check(rc, "sTiles_create")
+
+        # --- PHASE 1: preprocessing (graph + ordering + tile layout) -------
+        # Symbolic only -- no numeric values, no Cholesky.
+        rc = lib.sTiles_assign_graph_one_call(
+            self.group, 0, byref(self._handle), self.n, self.nnz,
+            row.ctypes.data_as(_ffi.c_int_p), col.ctypes.data_as(_ffi.c_int_p))
+        self._check(rc, "sTiles_assign_graph_one_call")
+
+        rc = lib.sTiles_init_group(self.group, byref(self._handle))
+        self._check(rc, "sTiles_init_group")
+
+        # --- PHASE 2: numeric factorization (optional) ---------------------
+        if factorize:
+            self.factorize()
+
+    # -- internals ----------------------------------------------------------
+    def _check(self, rc, what):
+        if rc is not None and rc != 0:
+            raise sTilesError(f"{what} failed (status {rc})")
+
+    def _require_open(self):
+        if self._closed:
+            raise sTilesError("this sTiles handle has been closed")
+
+    def _require_factored(self):
+        self._require_open()
+        if not self._factored:
+            raise sTilesError(
+                "not factorized yet; call .factorize() (preprocessing is done, "
+                "the numeric Cholesky is not)")
+
+    def factorize(self, Q=None):
+        """
+        Run the numeric Cholesky (assign_values + chol), reusing the
+        preprocessing.  This is PHASE 2 and is what you time separately from
+        construction.  Pass ``Q`` to factor a matrix with the SAME sparsity
+        pattern (reusing the preprocessing); otherwise the values captured at
+        construction are used.  Returns ``self``.
+        """
+        self._require_open()
+        if Q is not None:
+            _, row, col, val = _lower_coo(Q)
+            if row.size != self.nnz or not (
+                np.array_equal(row, self._row) and np.array_equal(col, self._col)
+            ):
+                raise sTilesError(
+                    "factorize(Q=) requires an identical sparsity pattern; "
+                    "build a new sTiles for a different pattern")
+            self._values = val
+        val = self._values
+        rc = lib.sTiles_assign_values(
+            self.group, 0, byref(self._handle),
+            val.ctypes.data_as(_ffi.c_double_p))
+        self._check(rc, "sTiles_assign_values")
+        lib.sTiles_bind(self.group, 0, byref(self._handle))
+        rc = lib.sTiles_chol(self.group, 0, byref(self._handle))
+        lib.sTiles_unbind(self.group, 0, byref(self._handle))
+        self._check(rc, "sTiles_chol")
+        self._factored = True
+        self._selinv_done = False
+        return self
+
+    def _ensure_selinv(self):
+        if not self.want_inverse:
+            raise sTilesError(
+                "construct sTiles(..., inverse=True) to use the selected inverse")
+        self._require_factored()
+        if not self._selinv_done:
+            lib.sTiles_bind(self.group, 0, byref(self._handle))
+            rc = lib.sTiles_selinv(self.group, 0, byref(self._handle))
+            lib.sTiles_unbind(self.group, 0, byref(self._handle))
+            self._check(rc, "sTiles_selinv")
+            self._selinv_done = True
+
+    # -- results ------------------------------------------------------------
+    @property
+    def is_factored(self) -> bool:
+        """Whether the numeric Cholesky has run (PHASE 2)."""
+        return self._factored
+
+    @property
+    def logdet(self) -> float:
+        """log-determinant of Q (== 2 * sum(log diag(L)))."""
+        self._require_factored()
+        return float(lib.sTiles_get_logdet(self.group, 0, byref(self._handle)))
+
+    @property
+    def nnz_factor(self) -> int:
+        """Number of stored non-zeros in the Cholesky factor L."""
+        self._require_open()
+        return int(lib.sTiles_get_nnz_factor(self.group, 0, byref(self._handle)))
+
+    @property
+    def chol_time(self) -> float:
+        """Library-measured numeric Cholesky time in seconds (no Python overhead)."""
+        self._require_factored()
+        return float(lib.sTiles_get_chol_timing(self.group, 0, byref(self._handle)))
+
+    @property
+    def selinv_time(self) -> float:
+        """Library-measured selected-inverse time in seconds (no Python overhead)."""
+        self._require_factored()
+        return float(lib.sTiles_get_selinv_timing(self.group, 0, byref(self._handle)))
+
+    def summary(self) -> dict:
+        """
+        Structured snapshot: dimensions, fill, mode, phase state and
+        library-measured timings.  Mirrors R's ``sTiles_summary(s)`` (returns a
+        dict, e.g. ``s.summary()["chol_time"]``).  Timings are ``None`` until the
+        corresponding phase has run.
+        """
+        self._require_open()
+        modes = {0: "dense", 1: "semisparse", 2: "sparse", 3: "auto"}
+        return {
+            "n": self.n,
+            "nnz": self.nnz,
+            "nnz_factor": self.nnz_factor,
+            "mode": modes.get(self.mode, self.mode),
+            "cores": self.cores,
+            "inverse": self.want_inverse,
+            "factored": self._factored,
+            "chol_time": self.chol_time if self._factored else None,
+            "selinv_time": self.selinv_time if self._selinv_done else None,
+            "version": version(),
+            "library": library_path(),
+        }
+
+    def selinv(self):
+        """
+        Compute the selected inverse explicitly, as its own (timeable) phase --
+        ``Z = Q^-1`` restricted to the pattern of the Cholesky factor.  Requires
+        ``inverse=True``.  Idempotent; otherwise it is computed lazily on the
+        first ``selinv_*`` query.  Returns ``self``.
+        """
+        self._ensure_selinv()
+        return self
+
+    def chol_elm(self, i: int, j: int) -> float:
+        """Entry L[i, j] of the Cholesky factor (0-based, original order)."""
+        self._require_factored()
+        return float(lib.sTiles_get_chol_elm(
+            self.group, 0, int(i), int(j), byref(self._handle)))
+
+    def selinv_elm(self, i: int, j: int) -> float:
+        """
+        Selected-inverse entry ``(Q^-1)[i, j]`` at ANY position (0-based,
+        original order).  Returns the value when ``(i, j)`` lies in the factor
+        pattern (pattern of ``L+L^T``) and exactly ``0.0`` outside it.  Both
+        triangles work (Z is symmetric).  Triggers the selected-inverse
+        computation on first use.
+        """
+        self._ensure_selinv()
+        return float(lib.sTiles_get_selinv_elm(
+            self.group, 0, int(i), int(j), byref(self._handle)))
+
+    def selinv_diag(self) -> np.ndarray:
+        """
+        Diagonal of the selected inverse, ``diag(Q^-1)`` -- the marginal
+        variances.  Length-``n`` float64 array in original order.
+        """
+        self._ensure_selinv()
+        out = np.empty(self.n, dtype=np.float64)
+        get = lib.sTiles_get_selinv_elm
+        h = byref(self._handle)
+        g = self.group
+        for i in range(self.n):
+            out[i] = get(g, 0, i, i, h)
+        return out
+
+    def selinv_row(self, node: int, neighbors) -> np.ndarray:
+        """
+        Values ``(Q^-1)[node, k]`` for each ``k`` in ``neighbors`` (entries that
+        fall outside the factor pattern come back as 0).
+        """
+        self._ensure_selinv()
+        nb = np.ascontiguousarray(neighbors, dtype=np.int32)
+        ptr = lib.sTiles_get_selinv_row(
+            self.group, 0, int(node), nb.ctypes.data_as(_ffi.c_int_p),
+            nb.size, byref(self._handle))
+        if not ptr:
+            raise sTilesError("sTiles_get_selinv_row returned null")
+        vals = np.ctypeslib.as_array(ptr, shape=(nb.size,)).copy()
+        return vals
+
+    def permutation(self) -> np.ndarray:
+        """
+        Fill-reducing permutation over the original nodes, as a length-``n``
+        int32 array (logical, ND-padding removed).
+        """
+        self._require_open()
+        out = np.empty(self.n, dtype=np.int32)
+        m = lib.sTiles_get_logical_element_perm(
+            self.group, 0, byref(self._handle), out.ctypes.data_as(_ffi.c_int_p))
+        if m < 0:
+            raise sTilesError("sTiles_get_logical_element_perm failed")
+        return out[:m]
+
+    # -- solves -------------------------------------------------------------
+    def _solve(self, fn, b):
+        self._require_factored()
+        B = np.asarray(b, dtype=np.float64)
+        one_d = B.ndim == 1
+        if one_d:
+            B = B.reshape(self.n, 1)
+        if B.shape[0] != self.n:
+            raise ValueError(f"rhs has {B.shape[0]} rows, expected {self.n}")
+        nrhs = B.shape[1]
+        # libstiles wants column-major (each rhs contiguous); overwrite in place.
+        work = np.asfortranarray(B, dtype=np.float64).copy(order="F")
+        lib.sTiles_bind(self.group, 0, byref(self._handle))
+        rc = fn(self.group, 0, byref(self._handle),
+                work.ctypes.data_as(_ffi.c_double_p), nrhs)
+        lib.sTiles_unbind(self.group, 0, byref(self._handle))
+        self._check(rc, fn.__name__)
+        return work[:, 0].copy() if one_d else np.ascontiguousarray(work)
+
+    def solve(self, b, system="A") -> np.ndarray:
+        """
+        Solve with the factorization.  ``b`` is a length-n vector or n x nrhs
+        matrix.  ``system``: ``"A"`` solves ``Q x = b`` (default), ``"L"`` solves
+        ``L y = b`` (forward), ``"Lt"`` solves ``L^T x = b`` (backward).
+        """
+        fn = {"A": lib.sTiles_solve_LLT, "L": lib.sTiles_solve_L,
+              "Lt": lib.sTiles_solve_LT}.get(system)
+        if fn is None:
+            raise ValueError(f"system must be 'A', 'L' or 'Lt', got {system!r}")
+        return self._solve(fn, b)
+
+    def solve_L(self, b) -> np.ndarray:
+        """Forward solve ``L y = b`` (alias for ``solve(b, 'L')``)."""
+        return self.solve(b, "L")
+
+    def solve_LT(self, b) -> np.ndarray:
+        """Backward solve ``L^T x = b`` (alias for ``solve(b, 'Lt')``)."""
+        return self.solve(b, "Lt")
+
+    # -- value reuse (same pattern, new values) ----------------------------
+    def update_values(self, Q):
+        """
+        Re-factor a matrix that shares this object's sparsity pattern, reusing
+        the symbolic analysis (ordering + layout).  Much cheaper than building
+        a fresh :class:`sTiles`.  Alias for ``factorize(Q)``; raises if the
+        pattern differs.
+        """
+        return self.factorize(Q)
+
+    # -- lifecycle ----------------------------------------------------------
+    def close(self):
+        if not self._closed:
+            try:
+                lib.sTiles_freeGroup(self.group)
+            finally:
+                self._closed = True
+                self._handle = c_void_p(None)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+        return False
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __repr__(self):
+        if self._closed:
+            return "<sTiles closed>"
+        phase = "factorized" if self._factored else "analyzed (not factorized)"
+        return (f"<sTiles n={self.n}, nnz={self.nnz}, mode={self.mode}, "
+                f"cores={self.cores}, {phase}>")
+
+
+def factorize(Q, **kw) -> sTiles:
+    """Convenience constructor -- identical to :class:`sTiles`."""
+    return sTiles(Q, **kw)

stiles-2026.7.19/sTiles.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: sTiles
+Version: 2026.7.19
+Summary: Python bindings for the sTiles sparse Cholesky / selected-inverse framework
+Author-email: Esmail Abdul Fattah <esmail.abdulfattah@kaust.edu.sa>
+Project-URL: Homepage, https://esmail-abdulfattah.github.io/sTiles/
+Project-URL: Repository, https://github.com/esmail-abdulfattah/sTiles
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.5

stiles-2026.7.19/sTiles.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+sTiles/__init__.py
+sTiles/_ffi.py
+sTiles/_version.py
+sTiles/core.py
+sTiles.egg-info/PKG-INFO
+sTiles.egg-info/SOURCES.txt
+sTiles.egg-info/dependency_links.txt
+sTiles.egg-info/requires.txt
+sTiles.egg-info/top_level.txt

stiles-2026.7.19/sTiles.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stiles-2026.7.19/sTiles.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy>=1.20
+scipy>=1.5

stiles-2026.7.19/sTiles.egg-info/top_level.txt

@@ -0,0 +1 @@
+sTiles

stiles-2026.7.19/setup.cfg

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