gsvd4py 0.0.1__tar.gz

gsvd4py-0.0.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: gsvd4py
+Version: 0.0.1
+Summary: Generalized SVD (GSVD) via LAPACK ?ggsvd3, using the same LAPACK library as SciPy
+Author-email: Hayden Ringer <hjrrockies@gmail.com>
+Requires-Python: >=3.9
+Requires-Dist: scipy>=1.13
+Requires-Dist: numpy>=2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"

gsvd4py-0.0.1/README.md

@@ -0,0 +1,104 @@
+# gsvd4py
+
+A lightweight Python wrapper for the LAPACK `?ggsvd3` routines, providing the Generalized Singular Value Decomposition (GSVD) in a style similar to `scipy.linalg`. It links to the same LAPACK library that SciPy uses on your machine — no separate LAPACK installation required.
+
+## Installation
+
+```bash
+pip install gsvd4py
+```
+
+Requires SciPy >= 1.13 and NumPy >= 2.0.
+
+## Background
+
+The GSVD decomposes a pair of matrices `A` (m×p) and `B` (n×p) as:
+
+```
+A = U @ C @ X.conj().T
+B = V @ S @ X.conj().T
+```
+
+where:
+- `U` (m×m) and `V` (n×n) are unitary
+- `C` (m×q) and `S` (n×q) are real diagonal with `C.T @ C + S.T @ S = I`
+- `X` (p×q) is nonsingular
+- `q = k + l` is the numerical rank of the stacked matrix `[A; B]`
+
+The generalized singular values are the ratios `C[i,i] / S[i,i]`.
+
+## Usage
+
+```python
+import numpy as np
+from gsvd4py import gsvd
+
+A = np.random.randn(5, 6)
+B = np.random.randn(4, 6)
+```
+
+### Full GSVD (default)
+
+```python
+U, V, X, C, S = gsvd(A, B)
+# U: (5,5), V: (4,4), X: (6,q), C: (5,q), S: (4,q)
+```
+
+### Economy GSVD
+
+Truncates `U` and `V` to at most `q` columns:
+
+```python
+U, V, X, C, S = gsvd(A, B, mode='econ')
+```
+
+### Raw LAPACK output
+
+Returns the LAPACK decomposition `A = U @ D1 @ [0, R] @ Q.T` directly:
+
+```python
+U, V, D1, D2, R, Q, k, l = gsvd(A, B, mode='separate')
+```
+
+### Skipping U and/or V
+
+```python
+X, C, S = gsvd(A, B, compute_u=False, compute_v=False)
+U, X, C, S = gsvd(A, B, compute_v=False)
+V, X, C, S = gsvd(A, B, compute_u=False)
+```
+
+## API Reference
+
+```python
+gsvd(a, b, mode='full', compute_u=True, compute_v=True,
+     overwrite_a=False, overwrite_b=False, lwork=None, check_finite=True)
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | (m, p) array |
+| `b` | (n, p) array |
+| `mode` | `'full'` (default), `'econ'`, or `'separate'` |
+| `compute_u` | Compute left singular vectors of `a` (default `True`) |
+| `compute_v` | Compute left singular vectors of `b` (default `True`) |
+| `overwrite_a` | Allow overwriting `a` to avoid a copy (default `False`) |
+| `overwrite_b` | Allow overwriting `b` to avoid a copy (default `False`) |
+| `lwork` | Work array size; `None` triggers an optimal workspace query |
+| `check_finite` | Check inputs for non-finite values (default `True`) |
+
+Supported dtypes: `float32`, `float64`, `complex64`, `complex128`. Integer inputs are upcast to `float64`.
+
+## LAPACK backend
+
+`gsvd4py` discovers the LAPACK library at runtime in the following order:
+
+1. **Apple Accelerate** (macOS) — via `$NEWLAPACK` symbols
+2. **scipy-openblas** — the OpenBLAS bundle shipped with SciPy
+3. **System LAPACK** — `liblapack` found via `ctypes.util.find_library`
+
+No compilation is required.
+
+## License
+
+MIT

gsvd4py-0.0.1/gsvd4py/__init__.py

@@ -0,0 +1,5 @@
+"""gsvd4py — Generalized SVD via LAPACK ?ggsvd3."""
+
+from ._gsvd import gsvd
+
+__all__ = ['gsvd']

gsvd4py-0.0.1/gsvd4py/_gsvd.py

@@ -0,0 +1,453 @@
+"""
+Core implementation of gsvd() using ctypes LAPACK calls.
+
+LAPACK vs spec notation mapping
+--------------------------------
+The spec uses Matlab-style dimensions: A is m×p, B is n×p.
+LAPACK dggsvd3 uses: A is M×N, B is P×N.
+
+  spec m  →  LAPACK M   (rows of A)
+  spec n  →  LAPACK P   (rows of B)
+  spec p  →  LAPACK N   (columns, shared)
+
+LAPACK decomposition (real case)
+----------------------------------
+  A = U * D1 * [0, R] * Q^T
+  B = V * D2 * [0, R] * Q^T
+
+where:
+  U   M×M orthogonal   (spec: m×m)
+  V   P×P orthogonal   (spec: n×n)
+  Q   N×N orthogonal   (spec: p×p)
+  D1  M×q "diagonal"   (spec: m×q)   q = K+L
+  D2  P×q "diagonal"   (spec: n×q)
+  R   q×q upper-triangular, stored inside A (and B if M < q)
+  [0, R]  q×N block matrix
+
+Matlab-style X (full / econ modes)
+------------------------------------
+  Q2     = Q[:, p-q:]        last q columns of Q,  shape p×q
+  X      = Q2 @ conj(R).T    shape p×q
+  then A = U * C * X^H,  B = V * S * X^H
+
+D1 / D2 structure (ALPHA, BETA from LAPACK)
+--------------------------------------------
+Case m >= q  (M >= K+L):
+  ALPHA[0:k]   = 1,  BETA[0:k]   = 0      (infinite GSVs)
+  ALPHA[k:k+l] = C,  BETA[k:k+l] = S      (finite GSVs, C²+S²=I)
+  ALPHA[k+l:p] = 0,  BETA[k+l:p] = 0
+
+Case m < q  (M < K+L, still K <= M):
+  ALPHA[0:k]   = 1,  BETA[0:k]   = 0
+  ALPHA[k:m]   = C,  BETA[k:m]   = S      (first M-K pairs)
+  ALPHA[m:q]   = 0,  BETA[m:q]   = 1      (identity block in D2)
+  ALPHA[q:p]   = 0,  BETA[q:p]   = 0
+"""
+
+import ctypes
+
+import numpy as np
+
+from ._lapack import get_ggsvd3
+
+# ---------------------------------------------------------------------------
+# dtype helpers
+# ---------------------------------------------------------------------------
+
+_DTYPE_MAP = {
+    np.dtype('float32'):    ('s', np.dtype('float32'),   False),
+    np.dtype('float64'):    ('d', np.dtype('float64'),   False),
+    np.dtype('complex64'):  ('c', np.dtype('float32'),   True),
+    np.dtype('complex128'): ('z', np.dtype('float64'),   True),
+}
+
+
+def _resolve_dtype(a, b):
+    """Return (lapack_dtype, real_dtype, is_complex) for inputs a and b."""
+    dtype = np.result_type(a, b)
+    # Upcast integers / booleans to float64
+    if not (np.issubdtype(dtype, np.floating) or
+            np.issubdtype(dtype, np.complexfloating)):
+        dtype = np.float64
+    # Upcast float16 → float32, etc.
+    if dtype == np.float16:
+        dtype = np.float32
+    return _DTYPE_MAP[np.dtype(dtype)]
+
+
+# ---------------------------------------------------------------------------
+# ctypes helpers
+# ---------------------------------------------------------------------------
+
+_c_int_p  = ctypes.POINTER(ctypes.c_int)
+_c_void_p = ctypes.c_void_p
+
+
+def _ptr(arr):
+    """Return a c_void_p pointing to arr's data buffer."""
+    return arr.ctypes.data_as(_c_void_p)
+
+
+def _iptr(val):
+    """Return a ctypes pointer to a c_int value."""
+    return ctypes.byref(ctypes.c_int(val))
+
+
+# ---------------------------------------------------------------------------
+# LAPACK call wrapper
+# ---------------------------------------------------------------------------
+
+def _call_ggsvd3(a_f, b_f, alpha, beta, u_f, v_f, q_f, iwork,
+                 jobu, jobv, lwork, fn, is_complex, real_dtype,
+                 uses_hidden_lengths):
+    """Call ?ggsvd3 once (workspace query or actual computation).
+
+    All array arguments must already be Fortran-contiguous and correctly typed.
+    Returns (k, l, info).
+    """
+    m_lap, p_lap = a_f.shape   # LAPACK M, N
+    n_lap        = b_f.shape[0]  # LAPACK P
+    q_lap        = p_lap         # = LAPACK N, used for LDQ
+
+    lwork_val = lwork if lwork is not None else 1
+    work = np.zeros(max(1, lwork_val), dtype=a_f.dtype)
+    lwork_c = ctypes.c_int(-1 if lwork is None else lwork_val)
+
+    k_c    = ctypes.c_int(0)
+    l_c    = ctypes.c_int(0)
+    info_c = ctypes.c_int(0)
+
+    # Dummy 1×1 arrays for when U or V is not computed
+    dummy = np.zeros((1, 1), dtype=a_f.dtype, order='F')
+
+    u_ptr   = _ptr(u_f)   if u_f is not None else _ptr(dummy)
+    v_ptr   = _ptr(v_f)   if v_f is not None else _ptr(dummy)
+    ldu_val = m_lap        if u_f is not None else 1
+    ldv_val = n_lap        if v_f is not None else 1
+
+    # jobu / jobv chars (single byte)
+    jobu_b = jobu.encode()
+    jobv_b = jobv.encode()
+    jobq_b = b'Q'
+
+    args = [
+        jobu_b, jobv_b, jobq_b,
+        _iptr(m_lap), _iptr(p_lap), _iptr(n_lap),
+        ctypes.byref(k_c), ctypes.byref(l_c),
+        _ptr(a_f),   _iptr(m_lap),
+        _ptr(b_f),   _iptr(n_lap),
+        _ptr(alpha), _ptr(beta),
+        u_ptr,       _iptr(ldu_val),
+        v_ptr,       _iptr(ldv_val),
+        _ptr(q_f),   _iptr(q_lap),
+        _ptr(work),  ctypes.byref(lwork_c),
+    ]
+
+    if is_complex:
+        rwork = np.zeros(2 * p_lap, dtype=real_dtype)
+        args += [_ptr(rwork)]
+
+    args += [_ptr(iwork), ctypes.byref(info_c)]
+
+    if uses_hidden_lengths:
+        one = ctypes.c_size_t(1)
+        args += [one, one, one]
+
+    fn(*args)
+
+    if lwork is None:
+        # workspace query: return optimal lwork from work[0]
+        return int(work[0].real)
+
+    return k_c.value, l_c.value, info_c.value
+
+
+# ---------------------------------------------------------------------------
+# Output construction helpers
+# ---------------------------------------------------------------------------
+
+def _build_C_S(alpha, beta, m, n, k, l):
+    """Build dense C (m×q) and S (n×q) from LAPACK ALPHA / BETA vectors.
+
+    Returns (C, S) as float64 arrays regardless of dtype (GSVs are real).
+    """
+    q = k + l
+    C = np.zeros((m, q))
+    S = np.zeros((n, q))
+
+    if k > 0:
+        C[:k, :k] = np.eye(k)   # identity block
+
+    if m >= q:                   # Case 1: M >= K+L
+        idx = np.arange(l)
+        C[k + idx, k + idx] = alpha[k:k+l]
+        S[idx,     k + idx] = beta[k:k+l]
+    else:                        # Case 2: M < K+L  (still K <= M)
+        mk = m - k               # number of (cos, sin) pairs that fit in D1
+        if mk > 0:
+            idx = np.arange(mk)
+            C[k + idx, k + idx] = alpha[k:m]
+            S[idx,     k + idx] = beta[k:m]
+        kl_m = q - m             # K+L-M  = size of identity block in D2
+        if kl_m > 0:
+            idx2 = np.arange(kl_m)
+            S[mk + idx2, m + idx2] = 1.0
+
+    return C, S
+
+
+def _extract_R(a_f, b_f, m, n, p, k, l):
+    """Extract the (k+l)×(k+l) upper-triangular R from the modified A (and B).
+
+    LAPACK stores R in A[0:k+l, p-k-l:p] (0-indexed, Fortran-order array).
+    If m < k+l, the bottom k+l-m rows come from B[0:k+l-m, p-k-l:p].
+    """
+    q = k + l
+    R = np.zeros((q, q), dtype=a_f.dtype)
+    col_start = p - q
+
+    if m >= q:
+        R[:] = a_f[:q, col_start:]
+    else:
+        kl_m = q - m                    # K+L-M rows of R that overflow into B
+        R[:m, :] = a_f[:m, col_start:]
+        # LAPACK stores R[m:q, m:q] (upper-triangular block) in
+        # B(M-K+1 : L,  N+M-K-L+1 : N)  [Fortran 1-indexed]
+        # = b_f[m-k : l,  col_start+m : p]  [Python 0-indexed]
+        b_row = m - k
+        b_col = col_start + m           # = p - kl_m
+        R[m:, m:] = b_f[b_row:b_row + kl_m, b_col:]
+
+    return R
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def gsvd(a, b, mode='full', compute_u=True, compute_v=True,
+         overwrite_a=False, overwrite_b=False, lwork=None, check_finite=True):
+    """Generalized Singular Value Decomposition.
+
+    Computes the GSVD of the matrix pair (a, b) using the LAPACK routine
+    ?ggsvd3 linked via the same LAPACK library as SciPy.
+
+    Parameters
+    ----------
+    a : (m, p) array_like
+    b : (n, p) array_like
+    mode : {'full', 'econ', 'separate'}, default 'full'
+        'full'     — Full Matlab-style: U (m×m), V (n×n), X (p×q), C (m×q),
+                     S (n×q), where q = k+l is the numerical rank of [a; b].
+        'econ'     — Economy Matlab-style: U (m×min(m,q)), V (n×min(n,q)),
+                     X (p×q), C (min(m,q)×q), S (min(n,q)×q).
+        'separate' — Raw LAPACK output (no rank truncation): U, V, D1, D2,
+                     R, Q, k, l.
+    compute_u : bool, default True
+        Compute left singular vectors of a.
+    compute_v : bool, default True
+        Compute left singular vectors of b.
+    overwrite_a : bool, default False
+        Allow overwriting a (avoids a copy if True and a is already
+        Fortran-contiguous with the correct dtype).
+    overwrite_b : bool, default False
+        Allow overwriting b (same as overwrite_a).
+    lwork : int or None, default None
+        LAPACK work array size.  None (or -1) triggers an optimal query.
+    check_finite : bool, default True
+        Check that a and b contain only finite values.
+
+    Returns
+    -------
+    mode='full' or 'econ':
+        If compute_u and compute_v:     U, V, X, C, S
+        If compute_u and not compute_v: U, X, C, S
+        If not compute_u and compute_v: V, X, C, S
+        If not compute_u and compute_v: X, C, S
+
+    mode='separate':
+        If compute_u and compute_v:     U, V, D1, D2, R, Q, k, l
+        If compute_u and not compute_v: U, D1, D2, R, Q, k, l
+        If not compute_u and compute_v: V, D1, D2, R, Q, k, l
+        If not compute_u and compute_v: D1, D2, R, Q, k, l
+    """
+    # ------------------------------------------------------------------
+    # Input validation
+    # ------------------------------------------------------------------
+    if mode not in ('full', 'econ', 'separate'):
+        raise ValueError(f"mode must be 'full', 'econ', or 'separate', got {mode!r}")
+
+    a = np.asarray(a)
+    b = np.asarray(b)
+
+    if a.ndim != 2:
+        raise ValueError(f"a must be 2-D, got shape {a.shape}")
+    if b.ndim != 2:
+        raise ValueError(f"b must be 2-D, got shape {b.shape}")
+
+    m, p = a.shape
+    n    = b.shape[0]
+    if b.shape[1] != p:
+        raise ValueError(
+            f"a and b must have the same number of columns: "
+            f"{p} != {b.shape[1]}"
+        )
+
+    if check_finite:
+        if not np.all(np.isfinite(a)):
+            raise ValueError("Array a contains non-finite values.")
+        if not np.all(np.isfinite(b)):
+            raise ValueError("Array b contains non-finite values.")
+
+    # ------------------------------------------------------------------
+    # Dtype resolution + array preparation
+    # ------------------------------------------------------------------
+    dtype_char, real_dtype, is_complex = _resolve_dtype(a, b)
+    dtype = np.dtype('complex64' if dtype_char == 'c'
+                     else 'complex128' if dtype_char == 'z'
+                     else 'float32' if dtype_char == 's'
+                     else 'float64')
+
+    def _prep(arr, overwrite):
+        if overwrite and arr.dtype == dtype and np.isfortran(arr):
+            return arr
+        return np.array(arr, dtype=dtype, order='F', copy=True)
+
+    a_f = _prep(a, overwrite_a)
+    b_f = _prep(b, overwrite_b)
+
+    # ------------------------------------------------------------------
+    # Load LAPACK function
+    # ------------------------------------------------------------------
+    fn, uses_hidden_lengths = get_ggsvd3(dtype_char)
+
+    # ------------------------------------------------------------------
+    # Allocate output arrays
+    # ------------------------------------------------------------------
+    jobu_char = 'U' if compute_u else 'N'
+    jobv_char = 'V' if compute_v else 'N'
+
+    alpha  = np.zeros(p, dtype=real_dtype)
+    beta   = np.zeros(p, dtype=real_dtype)
+    iwork  = np.zeros(p, dtype=np.int32)
+    q_f    = np.zeros((p, p), dtype=dtype, order='F')
+    u_f    = np.zeros((m, m), dtype=dtype, order='F') if compute_u else None
+    v_f    = np.zeros((n, n), dtype=dtype, order='F') if compute_v else None
+
+    # ------------------------------------------------------------------
+    # Workspace query
+    # ------------------------------------------------------------------
+    if lwork is None or lwork == -1:
+        opt = _call_ggsvd3(
+            a_f, b_f, alpha, beta, u_f, v_f, q_f, iwork,
+            jobu_char, jobv_char,
+            lwork=None, fn=fn, is_complex=is_complex,
+            real_dtype=real_dtype, uses_hidden_lengths=uses_hidden_lengths,
+        )
+        lwork_use = max(opt, 1)
+    else:
+        lwork_use = lwork
+
+    # ------------------------------------------------------------------
+    # Actual LAPACK call
+    # ------------------------------------------------------------------
+    k, l, info = _call_ggsvd3(
+        a_f, b_f, alpha, beta, u_f, v_f, q_f, iwork,
+        jobu_char, jobv_char,
+        lwork=lwork_use, fn=fn, is_complex=is_complex,
+        real_dtype=real_dtype, uses_hidden_lengths=uses_hidden_lengths,
+    )
+
+    if info < 0:
+        raise ValueError(f"Illegal argument #{-info} passed to dggsvd3.")
+    if info > 0:
+        raise np.linalg.LinAlgError(
+            f"LAPACK ?ggsvd3 failed to converge (info={info})."
+        )
+
+    q_rank = k + l   # effective numerical rank
+
+    # ------------------------------------------------------------------
+    # Post-processing
+    # ------------------------------------------------------------------
+    if mode == 'separate':
+        return _build_separate(
+            a_f, b_f, alpha, beta, u_f, v_f, q_f, iwork,
+            m, n, p, k, l, q_rank,
+            compute_u, compute_v, real_dtype,
+        )
+    else:
+        return _build_matlab_style(
+            a_f, b_f, alpha, beta, u_f, v_f, q_f,
+            m, n, p, k, l, q_rank,
+            mode, compute_u, compute_v,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Post-processing: separate mode
+# ---------------------------------------------------------------------------
+
+def _build_separate(a_f, b_f, alpha, beta, u_f, v_f, q_f, iwork,
+                    m, n, p, k, l, q_rank,
+                    compute_u, compute_v, real_dtype):
+    R = _extract_R(a_f, b_f, m, n, p, k, l)
+    D1, D2 = _build_C_S(alpha, beta, m, n, k, l)
+
+    # Convert to C-order for return
+    R  = np.ascontiguousarray(R)
+    D1 = np.ascontiguousarray(D1)
+    D2 = np.ascontiguousarray(D2)
+    Q  = np.ascontiguousarray(q_f)
+
+    result = []
+    if compute_u:
+        result.append(np.ascontiguousarray(u_f))
+    if compute_v:
+        result.append(np.ascontiguousarray(v_f))
+    result += [D1, D2, R, Q, k, l]
+    return tuple(result)
+
+
+# ---------------------------------------------------------------------------
+# Post-processing: full / econ modes
+# ---------------------------------------------------------------------------
+
+def _build_matlab_style(a_f, b_f, alpha, beta, u_f, v_f, q_f,
+                        m, n, p, k, l, q_rank,
+                        mode, compute_u, compute_v):
+    # Build C and S (real-valued diagonal matrices)
+    C_full, S_full = _build_C_S(alpha, beta, m, n, k, l)
+
+    # Extract R then build X = Q2 @ conj(R).T
+    R   = _extract_R(a_f, b_f, m, n, p, k, l)
+    Q2  = np.asarray(q_f)[:, p - q_rank:]    # p×q_rank
+    X   = Q2 @ np.conj(R).T                  # p×q_rank
+
+    # Full mode: U is m×m, V is n×n, C is m×q, S is n×q
+    # Econ mode: truncate U to m×r, V to n×r, C to r×q, S to r×q
+    #   where r = min(m, q_rank) for U/C  and  min(n, q_rank) for V/S
+    if mode == 'full':
+        C = C_full
+        S = S_full
+        U_out = np.ascontiguousarray(u_f) if compute_u else None
+        V_out = np.ascontiguousarray(v_f) if compute_v else None
+    else:  # 'econ'
+        ru = min(m, q_rank)
+        rv = min(n, q_rank)
+        C  = np.ascontiguousarray(C_full[:ru, :])
+        S  = np.ascontiguousarray(S_full[:rv, :])
+        U_out = np.ascontiguousarray(u_f[:, :ru]) if compute_u else None
+        V_out = np.ascontiguousarray(v_f[:, :rv]) if compute_v else None
+
+    X = np.ascontiguousarray(X)
+    C = np.ascontiguousarray(C)
+    S = np.ascontiguousarray(S)
+
+    result = []
+    if compute_u:
+        result.append(U_out)
+    if compute_v:
+        result.append(V_out)
+    result += [X, C, S]
+    return tuple(result)

gsvd4py-0.0.1/gsvd4py/_lapack.py

@@ -0,0 +1,126 @@
+"""
+LAPACK library discovery for gsvd4py.
+
+Tries, in order:
+  1. Apple Accelerate (macOS) — symbols named ?ggsvd3$NEWLAPACK
+  2. scipy_openblas32           — symbols named scipy_?ggsvd3_
+  3. scipy_openblas64           — symbols named scipy_?ggsvd3_
+  4. CDLL(None)                 — all loaded symbols (works on Linux)
+  5. ctypes.util.find_library   — system LAPACK / OpenBLAS
+
+Calling conventions differ:
+  - Accelerate:        pure C interface, no hidden Fortran char-length args
+  - gfortran LAPACK:   three hidden size_t args (len_jobu, len_jobv, len_jobq)
+                       appended after `info`
+"""
+
+import ctypes
+import ctypes.util
+import glob
+import os
+import sys
+
+# Module-level cache
+_lib = None
+_lib_type = None   # 'accelerate' | 'scipy_openblas' | 'system'
+
+
+def _load_lib():
+    global _lib, _lib_type
+
+    if _lib is not None:
+        return
+
+    # --- Strategy 1: Apple Accelerate (macOS) ---
+    if sys.platform == 'darwin':
+        try:
+            lib = ctypes.CDLL(
+                '/System/Library/Frameworks/Accelerate.framework/Accelerate'
+            )
+            lib['dggsvd3$NEWLAPACK']   # raises KeyError if absent
+            _lib = lib
+            _lib_type = 'accelerate'
+            return
+        except (OSError, KeyError):
+            pass
+
+    # --- Strategy 2 & 3: scipy_openblas32 / scipy_openblas64 ---
+    for _pkg in ('scipy_openblas32', 'scipy_openblas64'):
+        try:
+            pkg = __import__(_pkg)
+            lib_dir = pkg.get_lib_dir()
+            pattern = '*.dylib' if sys.platform == 'darwin' else '*.so*'
+            for dylib in glob.glob(os.path.join(lib_dir, pattern)):
+                try:
+                    lib = ctypes.CDLL(dylib)
+                    getattr(lib, f'scipy_dggsvd3_')
+                    _lib = lib
+                    _lib_type = 'scipy_openblas'
+                    return
+                except (OSError, AttributeError):
+                    pass
+        except ImportError:
+            pass
+
+    # --- Strategy 4: CDLL(None) — all loaded symbols (Linux) ---
+    lib = ctypes.CDLL(None)
+    try:
+        getattr(lib, 'dggsvd3_')
+        _lib = lib
+        _lib_type = 'system'
+        return
+    except AttributeError:
+        pass
+
+    # --- Strategy 5: find_library ---
+    for name in ('lapack', 'openblas', 'flexiblas'):
+        path = ctypes.util.find_library(name)
+        if not path:
+            continue
+        try:
+            lib = ctypes.CDLL(path)
+            getattr(lib, 'dggsvd3_')
+            _lib = lib
+            _lib_type = 'system'
+            return
+        except (OSError, AttributeError):
+            pass
+
+    raise ImportError(
+        "gsvd4py: Could not find a LAPACK library providing dggsvd3. "
+        "Ensure scipy is installed (pip install scipy), or install "
+        "scipy-openblas32 (pip install scipy-openblas32)."
+    )
+
+
+def get_ggsvd3(dtype_char):
+    """Return the ctypes function handle for ?ggsvd3.
+
+    Parameters
+    ----------
+    dtype_char : str
+        One of 'd', 's', 'z', 'c'.
+
+    Returns
+    -------
+    fn : ctypes function object (restype already set to None)
+    uses_hidden_lengths : bool
+        True when the function uses the gfortran hidden char-length ABI.
+    """
+    _load_lib()
+
+    if _lib_type == 'accelerate':
+        sym = f'{dtype_char}ggsvd3$NEWLAPACK'
+        fn = _lib[sym]
+        uses_hidden_lengths = False
+    elif _lib_type == 'scipy_openblas':
+        sym = f'scipy_{dtype_char}ggsvd3_'
+        fn = getattr(_lib, sym)
+        uses_hidden_lengths = True
+    else:   # 'system'
+        sym = f'{dtype_char}ggsvd3_'
+        fn = getattr(_lib, sym)
+        uses_hidden_lengths = True
+
+    fn.restype = None
+    return fn, uses_hidden_lengths

gsvd4py-0.0.1/gsvd4py.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: gsvd4py
+Version: 0.0.1
+Summary: Generalized SVD (GSVD) via LAPACK ?ggsvd3, using the same LAPACK library as SciPy
+Author-email: Hayden Ringer <hjrrockies@gmail.com>
+Requires-Python: >=3.9
+Requires-Dist: scipy>=1.13
+Requires-Dist: numpy>=2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"

gsvd4py-0.0.1/gsvd4py.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+gsvd4py/__init__.py
+gsvd4py/_gsvd.py
+gsvd4py/_lapack.py
+gsvd4py.egg-info/PKG-INFO
+gsvd4py.egg-info/SOURCES.txt
+gsvd4py.egg-info/dependency_links.txt
+gsvd4py.egg-info/requires.txt
+gsvd4py.egg-info/top_level.txt
+tests/test_gsvd.py

gsvd4py-0.0.1/gsvd4py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gsvd4py-0.0.1/gsvd4py.egg-info/requires.txt

@@ -0,0 +1,5 @@
+scipy>=1.13
+numpy>=2.0
+
+[test]
+pytest

gsvd4py-0.0.1/gsvd4py.egg-info/top_level.txt

@@ -0,0 +1 @@
+gsvd4py

gsvd4py-0.0.1/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gsvd4py"
+version = "0.0.1"
+description = "Generalized SVD (GSVD) via LAPACK ?ggsvd3, using the same LAPACK library as SciPy"
+requires-python = ">=3.9"
+authors = [{name = "Hayden Ringer", email = "hjrrockies@gmail.com"}]
+dependencies = [
+    "scipy >= 1.13",
+    "numpy >= 2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]

gsvd4py-0.0.1/setup.cfg

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

gsvd4py-0.0.1/tests/test_gsvd.py

@@ -0,0 +1,308 @@
+"""
+Tests for gsvd4py.
+
+Validates:
+  - LAPACK library is found and loaded
+  - Reconstruction accuracy: A ≈ U @ C @ X.conj().T,  B ≈ V @ S @ X.conj().T
+  - Unitarity of U and V
+  - All modes (full, econ, separate)
+  - All four dtypes (float32, float64, complex64, complex128)
+  - compute_u=False / compute_v=False short-tuple returns
+  - Various shapes (square, tall, wide, rank-deficient)
+"""
+
+import numpy as np
+import pytest
+from numpy.testing import assert_allclose
+
+from gsvd4py import gsvd
+import gsvd4py._lapack as _lapack_mod
+
+
+# ---------------------------------------------------------------------------
+# Tolerances
+# ---------------------------------------------------------------------------
+_RTOL = {
+    np.float32:    1e-5,
+    np.float64:    1e-12,
+    np.complex64:  1e-5,
+    np.complex128: 1e-12,
+}
+
+
+# ---------------------------------------------------------------------------
+# Test: library loading
+# ---------------------------------------------------------------------------
+
+class TestLibraryLoading:
+    def test_loads_without_error(self):
+        _lapack_mod._load_lib()
+        assert _lapack_mod._lib_type in ('accelerate', 'scipy_openblas', 'system')
+
+    def test_lib_type_is_string(self):
+        _lapack_mod._load_lib()
+        assert isinstance(_lapack_mod._lib_type, str)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _random_matrix(rng, m, n, dtype):
+    """Generate a random matrix of the given real or complex dtype."""
+    if np.issubdtype(dtype, np.complexfloating):
+        rdtype = np.float32 if dtype == np.complex64 else np.float64
+        return (rng.standard_normal((m, n)).astype(rdtype) +
+                1j * rng.standard_normal((m, n)).astype(rdtype)).astype(dtype)
+    return rng.standard_normal((m, n)).astype(dtype)
+
+
+def _check_reconstruction(U, V, X, C, S, A, B, rtol):
+    """Check A ≈ U @ C @ X.conj().T and B ≈ V @ S @ X.conj().T."""
+    XH = X.conj().T
+    assert_allclose(U @ C @ XH, A, rtol=rtol, atol=rtol * np.linalg.norm(A))
+    assert_allclose(V @ S @ XH, B, rtol=rtol, atol=rtol * np.linalg.norm(B))
+
+
+def _check_unitary(M, rtol):
+    """Check M @ M.conj().T ≈ I."""
+    n = M.shape[1]
+    assert_allclose(M.conj().T @ M, np.eye(n), atol=rtol * 10)
+
+
+# ---------------------------------------------------------------------------
+# Test: mode='full'
+# ---------------------------------------------------------------------------
+
+class TestFullMode:
+    @pytest.mark.parametrize("dtype", [np.float32, np.float64,
+                                        np.complex64, np.complex128])
+    @pytest.mark.parametrize("shape", [
+        (5, 4, 6),   # m=5, n=4, p=6  (tall A, tall B)
+        (4, 4, 4),   # square
+        (3, 5, 6),   # m < p, n < p  (wide)
+        (6, 3, 4),   # m > p, n < p
+    ])
+    def test_reconstruction(self, dtype, shape):
+        m, n, p = shape
+        rng = np.random.default_rng(42)
+        A = _random_matrix(rng, m, p, dtype)
+        B = _random_matrix(rng, n, p, dtype)
+        rtol = _RTOL[dtype]
+
+        U, V, X, C, S = gsvd(A, B, mode='full')
+
+        assert U.shape == (m, m)
+        assert V.shape == (n, n)
+        assert X.shape[0] == p
+        assert C.shape[0] == m
+        assert S.shape[0] == n
+        assert C.shape[1] == X.shape[1] == S.shape[1]  # same q
+
+        _check_reconstruction(U, V, X, C, S, A, B, rtol)
+        _check_unitary(U, rtol)
+        _check_unitary(V, rtol)
+
+    def test_no_u_no_v(self):
+        rng = np.random.default_rng(0)
+        A = rng.standard_normal((4, 5))
+        B = rng.standard_normal((3, 5))
+        result = gsvd(A, B, compute_u=False, compute_v=False)
+        assert len(result) == 3
+        X, C, S = result
+        assert X.shape[0] == 5
+
+    def test_no_u_with_v(self):
+        rng = np.random.default_rng(0)
+        A = rng.standard_normal((4, 5))
+        B = rng.standard_normal((3, 5))
+        result = gsvd(A, B, compute_u=False, compute_v=True)
+        assert len(result) == 4
+        V, X, C, S = result
+        assert V.shape == (3, 3)
+
+    def test_with_u_no_v(self):
+        rng = np.random.default_rng(0)
+        A = rng.standard_normal((4, 5))
+        B = rng.standard_normal((3, 5))
+        result = gsvd(A, B, compute_u=True, compute_v=False)
+        assert len(result) == 4
+        U, X, C, S = result
+        assert U.shape == (4, 4)
+
+
+# ---------------------------------------------------------------------------
+# Test: mode='econ'
+# ---------------------------------------------------------------------------
+
+class TestEconMode:
+    @pytest.mark.parametrize("dtype", [np.float64, np.complex128])
+    def test_reconstruction(self, dtype):
+        rng = np.random.default_rng(7)
+        m, n, p = 6, 4, 5
+        A = _random_matrix(rng, m, p, dtype)
+        B = _random_matrix(rng, n, p, dtype)
+        rtol = _RTOL[dtype]
+
+        U, V, X, C, S = gsvd(A, B, mode='econ')
+        q = X.shape[1]
+
+        assert U.shape == (m, min(m, q))
+        assert V.shape == (n, min(n, q))
+        assert C.shape == (min(m, q), q)
+        assert S.shape == (min(n, q), q)
+
+        _check_reconstruction(U, V, X, C, S, A, B, rtol)
+
+    def test_econ_smaller_than_full(self):
+        rng = np.random.default_rng(3)
+        A = rng.standard_normal((8, 5))
+        B = rng.standard_normal((6, 5))
+        U_f, V_f, X_f, C_f, S_f = gsvd(A, B, mode='full')
+        U_e, V_e, X_e, C_e, S_e = gsvd(A, B, mode='econ')
+        q = X_e.shape[1]
+        # Economy U/V should be the first q columns of the full U/V
+        assert U_e.shape[1] <= U_f.shape[1]
+        assert V_e.shape[1] <= V_f.shape[1]
+
+
+# ---------------------------------------------------------------------------
+# Test: mode='separate'
+# ---------------------------------------------------------------------------
+
+class TestSeparateMode:
+    def test_full_return(self):
+        rng = np.random.default_rng(11)
+        A = rng.standard_normal((5, 6))
+        B = rng.standard_normal((4, 6))
+        result = gsvd(A, B, mode='separate')
+        assert len(result) == 8
+        U, V, D1, D2, R, Q, k, l = result
+        assert U.shape == (5, 5)
+        assert V.shape == (4, 4)
+        assert Q.shape == (6, 6)
+        assert R.shape == (k + l, k + l)
+        assert D1.shape == (5, k + l)
+        assert D2.shape == (4, k + l)
+
+    def test_no_u(self):
+        rng = np.random.default_rng(12)
+        A = rng.standard_normal((4, 5))
+        B = rng.standard_normal((3, 5))
+        result = gsvd(A, B, mode='separate', compute_u=False)
+        assert len(result) == 7
+        V = result[0]
+        assert V.shape == (3, 3)
+
+    def test_no_u_no_v(self):
+        rng = np.random.default_rng(13)
+        A = rng.standard_normal((4, 5))
+        B = rng.standard_normal((3, 5))
+        result = gsvd(A, B, mode='separate', compute_u=False, compute_v=False)
+        assert len(result) == 6
+        D1, D2, R, Q, k, l = result
+
+    def test_reconstruction_via_lapack_form(self):
+        """Verify A ≈ U @ D1 @ np.hstack([zeros, R]) @ Q.T."""
+        rng = np.random.default_rng(20)
+        A = rng.standard_normal((5, 6))
+        B = rng.standard_normal((4, 6))
+        U, V, D1, D2, R, Q, k, l = gsvd(A, B, mode='separate')
+
+        q = k + l
+        p = A.shape[1]
+        zero_block = np.zeros((q, p - q))
+        RQ_block = np.hstack([zero_block, R]) @ Q.T    # q×p
+
+        A_rec = U @ D1 @ RQ_block
+        B_rec = V @ D2 @ RQ_block
+        assert_allclose(A_rec, A, rtol=1e-10, atol=1e-10 * np.linalg.norm(A))
+        assert_allclose(B_rec, B, rtol=1e-10, atol=1e-10 * np.linalg.norm(B))
+
+
+# ---------------------------------------------------------------------------
+# Test: overwrite and lwork options
+# ---------------------------------------------------------------------------
+
+class TestOptions:
+    def test_overwrite_a_b(self):
+        rng = np.random.default_rng(99)
+        A = np.asfortranarray(rng.standard_normal((4, 5)))
+        B = np.asfortranarray(rng.standard_normal((3, 5)))
+        # Should not raise
+        gsvd(A, B, overwrite_a=True, overwrite_b=True)
+
+    def test_explicit_lwork(self):
+        rng = np.random.default_rng(100)
+        A = rng.standard_normal((4, 5))
+        B = rng.standard_normal((3, 5))
+        U1, V1, X1, C1, S1 = gsvd(A, B)
+        U2, V2, X2, C2, S2 = gsvd(A, B, lwork=500)
+        assert_allclose(C1, C2, rtol=1e-12)
+
+    def test_check_finite_raises(self):
+        A = np.array([[1.0, np.nan], [2.0, 3.0]])
+        B = np.array([[1.0, 2.0]])
+        with pytest.raises(ValueError, match="non-finite"):
+            gsvd(A, B)
+
+    def test_check_finite_skip(self):
+        # With check_finite=False, no error even with nan (behaviour is
+        # undefined, but the call should not raise a Python-level error
+        # for this test — we just check the flag is respected)
+        A = np.array([[1.0, 2.0], [3.0, 4.0]])
+        B = np.array([[1.0, 2.0]])
+        gsvd(A, B, check_finite=False)   # should not raise
+
+
+# ---------------------------------------------------------------------------
+# Test: input validation
+# ---------------------------------------------------------------------------
+
+class TestValidation:
+    def test_bad_mode(self):
+        A = np.eye(3)
+        B = np.eye(3)
+        with pytest.raises(ValueError, match="mode"):
+            gsvd(A, B, mode='bad')
+
+    def test_mismatched_columns(self):
+        A = np.ones((3, 4))
+        B = np.ones((2, 5))
+        with pytest.raises(ValueError, match="columns"):
+            gsvd(A, B)
+
+    def test_1d_input(self):
+        with pytest.raises(ValueError, match="2-D"):
+            gsvd(np.ones(3), np.ones((2, 3)))
+
+    def test_integer_input_upcasted(self):
+        A = np.array([[1, 2, 3], [4, 5, 6]])
+        B = np.array([[1, 2, 3]])
+        # Should not raise; integers are upcast to float64
+        U, V, X, C, S = gsvd(A, B)
+        assert U.dtype in (np.float64, np.complex128)
+
+
+# ---------------------------------------------------------------------------
+# Test: dtype handling
+# ---------------------------------------------------------------------------
+
+class TestDtypes:
+    @pytest.mark.parametrize("dtype", [np.float32, np.float64,
+                                        np.complex64, np.complex128])
+    def test_dtype_preserved(self, dtype):
+        rng = np.random.default_rng(55)
+        A = _random_matrix(rng, 4, 5, dtype)
+        B = _random_matrix(rng, 3, 5, dtype)
+        U, V, X, C, S = gsvd(A, B)
+        assert U.dtype == dtype
+        assert V.dtype == dtype
+        assert X.dtype == dtype
+
+    def test_mixed_real_float32_float64(self):
+        rng = np.random.default_rng(56)
+        A = rng.standard_normal((4, 5)).astype(np.float32)
+        B = rng.standard_normal((3, 5)).astype(np.float64)
+        U, V, X, C, S = gsvd(A, B)
+        assert U.dtype == np.float64   # result_type promotes to float64