freealg 0.7.6__tar.gz → 0.7.8__tar.gz

{freealg-0.7.6 → freealg-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.7.6
+Version: 0.7.8
 Summary: Free probability for large matrices
 Home-page: https://github.com/ameli/freealg
 Download-URL: https://github.com/ameli/freealg/archive/main.zip

freealg-0.7.8/freealg/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.7.8"

{freealg-0.7.6 → freealg-0.7.8}/freealg/_algebraic_form/_continuation_algebraic.py

@@ -227,7 +227,7 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
                                                              dtype=float)
                     AN = numpy.vstack([AN, L])
 
-                _, _, vhN = numpy.linalg.svd(AN, full_matrices=False)
+                _, svals, vhN = numpy.linalg.svd(AN, full_matrices=False)
                 y = vhN[-1, :]
                 coef_scaled = N @ y
 
@@ -245,7 +245,8 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
                                                                  dtype=float)
                         As_aug = numpy.vstack([As_aug, L])
 
-                    _, _, vh = numpy.linalg.svd(As_aug, full_matrices=False)
+                    _, svals, vh = numpy.linalg.svd(As_aug,
+                                                    full_matrices=False)
                     coef_scaled = vh[-1, :]
                     coef = coef_scaled / s_col
                 else:
@@ -255,7 +256,7 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
                                                                  dtype=float)
                         As = numpy.vstack([As, L])
 
-                    _, _, vh = numpy.linalg.svd(As, full_matrices=False)
+                    _, svals, vh = numpy.linalg.svd(As, full_matrices=False)
                     coef_scaled = vh[-1, :]
                     coef = coef_scaled / s_col
 
@@ -265,7 +266,7 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
                 L = numpy.sqrt(ridge_lambda) * numpy.eye(n_coef, dtype=float)
                 As = numpy.vstack([As, L])
 
-            _, _, vh = numpy.linalg.svd(As, full_matrices=False)
+            _, svals, vh = numpy.linalg.svd(As, full_matrices=False)
             coef_scaled = vh[-1, :]
             coef = coef_scaled / s_col
 
@@ -275,7 +276,7 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
             L = numpy.sqrt(ridge_lambda) * numpy.eye(n_coef, dtype=float)
             As = numpy.vstack([As, L])
 
-        _, _, vh = numpy.linalg.svd(As, full_matrices=False)
+        _, svals, vh = numpy.linalg.svd(As, full_matrices=False)
         coef_scaled = vh[-1, :]
         coef = coef_scaled / s_col
 
@@ -286,7 +287,14 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
     if normalize:
         full = _normalize_coefficients(full)
 
-    return full
+    # Diagnostic metrics
+    fit_metrics = {
+        's_min': svals[-1],
+        'gap_ratio': float(svals[-2] / svals[-1]),
+        'n_small': float(int(numpy.sum(svals <= svals[0] * 1e-12))),
+    }
+
+    return full, fit_metrics
 
 
 # =============================

freealg-0.7.8/freealg/_algebraic_form/_discriminant.py

@@ -0,0 +1,226 @@
+# SPDX-FileCopyrightText: Copyright 2026, Siavash Ameli <sameli@berkeley.edu>
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileType: SOURCE
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the license found in the LICENSE.txt file in the root directory
+# of this source tree.
+
+
+# =======
+# Imports
+# =======
+
+import numpy as np
+import numpy.polynomial.polynomial as poly
+
+__all__ = ['compute_singular_points']
+
+
+# =========
+# ploy trim
+# =========
+
+def _poly_trim(p, tol):
+
+    p = np.asarray(p, dtype=complex).ravel()
+    if p.size == 0:
+        return np.zeros(1, dtype=complex)
+    k = p.size - 1
+    while k > 0 and abs(p[k]) <= tol:
+        k -= 1
+    return p[:k + 1].copy()
+
+
+# ============
+# poly is zero
+# ============
+
+def _poly_is_zero(p, tol):
+
+    p = _poly_trim(p, tol)
+    return (p.size == 1) and (abs(p[0]) <= tol)
+
+
+# ========
+# poly add
+# ========
+
+def _poly_add(a, b, tol):
+
+    return _poly_trim(poly.polyadd(a, b), tol)
+
+
+# ========
+# poly sub
+# ========
+
+def _poly_sub(a, b, tol):
+
+    return _poly_trim(poly.polysub(a, b), tol)
+
+
+# =======
+# ply mul
+# =======
+
+def _poly_mul(a, b, tol):
+
+    return _poly_trim(poly.polymul(a, b), tol)
+
+
+# ==============
+# poly div exact
+# ==============
+
+def _poly_div_exact(a, b, tol):
+
+    a = _poly_trim(a, tol)
+    b = _poly_trim(b, tol)
+    if _poly_is_zero(b, tol):
+        raise ZeroDivisionError("poly division by zero")
+
+    q, r = poly.polydiv(a, b)
+    r = _poly_trim(r, tol)
+
+    # Bareiss expects exact division; with floats it's only approximate.
+    # If the remainder is small, drop it.
+    scale = max(1.0, np.linalg.norm(a))
+    if np.linalg.norm(r) > 1e3 * tol * scale:
+        # Fallback: still drop remainder (keeps algorithm running).
+        # This is acceptable because we only need the resultant roots
+        # robustly, not exact symbolic coefficients.
+        pass
+
+    return _poly_trim(q, tol)
+
+
+# ================
+# det bareiss poly
+# ================
+
+def _det_bareiss_poly(M, tol):
+
+    n = len(M)
+    A = [[_poly_trim(M[i][j], tol) for j in range(n)] for i in range(n)]
+
+    denom = np.array([1.0], dtype=complex)
+    sign = 1.0
+
+    for k in range(n - 1):
+        if _poly_is_zero(A[k][k], tol):
+            piv = -1
+            for i in range(k + 1, n):
+                if not _poly_is_zero(A[i][k], tol):
+                    piv = i
+                    break
+            if piv == -1:
+                return np.array([0.0], dtype=complex)
+            A[k], A[piv] = A[piv], A[k]
+            sign *= -1.0
+
+        pivot = A[k][k]
+        for i in range(k + 1, n):
+            for j in range(k + 1, n):
+                num = _poly_sub(_poly_mul(A[i][j], pivot, tol),
+                                _poly_mul(A[i][k], A[k][j], tol),
+                                tol)
+                if k > 0:
+                    A[i][j] = _poly_div_exact(num, denom, tol)
+                else:
+                    A[i][j] = _poly_trim(num, tol)
+
+        denom = pivot
+
+    return _poly_trim(sign * A[n - 1][n - 1], tol)
+
+
+# ===================
+# cluster real points
+# ===================
+
+def _cluster_real_points(x, eps):
+
+    x = np.asarray(x, dtype=float).ravel()
+    if x.size == 0:
+        return x
+    x = np.sort(x)
+    uniq = []
+    for v in x:
+        if (len(uniq) == 0) or (abs(v - uniq[-1]) > eps):
+            uniq.append(float(v))
+        else:
+            uniq[-1] = 0.5 * (uniq[-1] + float(v))
+    return np.asarray(uniq, dtype=float)
+
+
+# =======================
+# compute singular points
+# =======================
+
+def compute_singular_points(a_coeffs, tol=1e-12, real_tol=None):
+    """
+    a_coeffs[i,j] is coefficient of z^i m^j, shape (deg_z+1, s+1).
+
+    Returns
+    -------
+
+    z_bp     : complex array, roots of Disc_m(P)(z)
+    a_s_zero : complex array, roots of leading coefficient a_s(z)
+    support  : list of (a,b) from real-ish branch points paired consecutively
+    """
+
+    a_coeffs = np.asarray(a_coeffs)
+    s = a_coeffs.shape[1] - 1
+    if s < 1:
+        return (np.array([], dtype=complex),
+                np.array([], dtype=complex),
+                [])
+
+    if real_tol is None:
+        real_tol = 1e3 * tol
+
+    a = [_poly_trim(a_coeffs[:, j], tol) for j in range(s + 1)]
+
+    a_s = a[s]
+    a_s_zero = np.roots(a_s[::-1]) if a_s.size > 1 else \
+        np.array([], dtype=complex)
+
+    b = []
+    for j in range(s):
+        b.append(_poly_trim((j + 1) * a[j + 1], tol))
+
+    mdeg = s
+    ndeg = s - 1
+    N = mdeg + ndeg  # 2s-1
+
+    z0 = np.array([0.0], dtype=complex)
+    M = [[z0 for _ in range(N)] for __ in range(N)]
+
+    for r in range(ndeg):
+        for j in range(mdeg + 1):
+            M[r][r + j] = a[j]
+
+    for r in range(mdeg):
+        rr = ndeg + r
+        for j in range(ndeg + 1):
+            M[rr][r + j] = b[j]
+
+    res = _det_bareiss_poly(M, tol)
+    if res.size <= 1:
+        z_bp = np.array([], dtype=complex)
+    else:
+        z_bp = np.roots(res[::-1])
+
+    support = []
+    if z_bp.size > 0:
+        zr = z_bp[np.abs(z_bp.imag) <= real_tol].real
+        zr = _cluster_real_points(zr, eps=1e2 * real_tol)
+        m2 = (zr.size // 2) * 2
+        for k in range(0, m2, 2):
+            a0 = float(zr[k])
+            b0 = float(zr[k + 1])
+            if b0 > a0:
+                support.append((a0, b0))
+
+    return z_bp, a_s_zero, support

freealg-0.7.8/freealg/_algebraic_form/_homotopy.py

@@ -0,0 +1,280 @@
+# =======
+# Imports
+# =======
+
+import numpy
+from ._moments import AlgebraicStieltjesMoments
+
+__all__ = ['stieltjes_poly']
+
+
+# =====================
+# select root
+# =====================
+
+def select_root(roots, z, target):
+    """
+    Select the root among Herglotz candidates at a given z closest to a
+    given target
+
+    Parameters
+    ----------
+    roots : array_like of complex
+        Candidate roots for m at the given z.
+    z : complex
+        Evaluation point. The Stieltjes/Herglotz branch satisfies
+        sign(Im(m)) = sign(Im(z)) away from the real axis.
+    target : complex
+        Previous continuation value used to enforce continuity, or
+        target value.
+
+    Returns
+    -------
+    w : complex
+        Selected root corresponding to the Stieltjes branch.
+    """
+
+    z = complex(z)
+    roots = numpy.asarray(roots, dtype=numpy.complex128).ravel()
+
+    if roots.size == 0:
+        raise ValueError("roots must contain at least one candidate root.")
+
+    desired_sign = numpy.sign(z.imag)
+
+    # Apply a soft Herglotz sign filter: prefer roots with Im(w) having the
+    # same sign as Im(z), allowing tiny numerical violations near the axis.
+    imag_roots = numpy.imag(roots)
+
+    good = roots[numpy.sign(imag_roots) == desired_sign]
+    if good.size == 0:
+        good = roots[(imag_roots * desired_sign) > -1e-12]
+
+    candidates = good if good.size > 0 else roots
+    idx = int(numpy.argmin(numpy.abs(candidates - target)))
+    return candidates[idx]
+
+
+# ==============
+# stieltjes poly
+# ==============
+
+class StieltjesPoly(object):
+    """
+    Stieltjes-branch evaluator for an algebraic equation P(z, m) = 0.
+
+    This class represents the Stieltjes-branch solution m(z) of an algebraic
+    equation defined by a polynomial relation
+
+        P(z, m) = 0,
+
+    where P is a polynomial in z and m with monomial-basis coefficients.
+    The coefficient matrix ``a`` is fixed at construction time, and all
+    quantities depending only on ``a`` are precomputed. Evaluation at a
+    complex point ``z`` is performed via :meth:`evaluate`. The instance is
+    also callable; :meth:`__call__` supports scalar or vector inputs and
+    applies :meth:`evaluate` elementwise.
+
+    The Stieltjes branch is selected by initializing in the appropriate
+    half-plane using an asymptotic Stieltjes estimate and then performing
+    homotopy continuation along a straight-line path in the complex plane.
+
+    Parameters
+    ----------
+    a : ndarray, shape (L, K)
+        Coefficient matrix defining P(z, m) in the monomial basis. For fixed
+        z, the coefficients of the polynomial in m are assembled from powers
+        of z.
+    eps : float or None, optional
+        If Im(z) == 0, use z + i*eps as the boundary evaluation point.
+        If None and Im(z) == 0, eps is set to 1e-8 * max(1, |z|).
+    height : float, default = 2.0
+        Imaginary height used for the starting point z0 in the same
+        half-plane as the evaluation point.
+    steps : int, default = 100
+        Number of continuation steps along the homotopy path.
+    order : int, default = 15
+        Number of moments in Stieltjes estimate
+
+    Methods
+    -------
+    evaluate(z)
+        Evaluate the Stieltjes-branch solution m(z) at a single complex point.
+
+    __call__(z)
+        If ``z`` is scalar, returns ``evaluate(z, ...)``.
+        If ``z`` is array-like, returns an array of the same shape, where each
+        entry is computed by calling ``evaluate`` on the corresponding element.
+
+    Notes
+    -----
+    If an input ``z`` value is real (Im(z) == 0), the evaluation is interpreted
+    as a boundary value by replacing that element with z + i*eps. If ``eps`` is
+    None, eps is chosen per element as 1e-8 * max(1, |z|).
+    """
+
+    def __init__(self, a, eps=None, height=2.0, steps=100, order=15):
+        a = numpy.asarray(a)
+        if a.ndim != 2:
+            raise ValueError("a must be a 2D array.")
+
+        self.a = a
+        self.a_l, _ = a.shape
+        self.eps = eps
+        self.height = height
+        self.steps = steps
+        self.order = order
+
+        # Objects depending only on a
+        self.mom = AlgebraicStieltjesMoments(a)
+        self._zpows_exp = numpy.arange(self.a_l)
+        self.rad = 1.0 + self.height * self.mom.radius(self.order)
+
+    def _poly_coeffs_m(self, z_val):
+        z_powers = z_val ** self._zpows_exp
+        return (z_powers @ self.a)[::-1]
+
+    def _poly_roots(self, z_val):
+        coeffs = numpy.asarray(self._poly_coeffs_m(z_val),
+                               dtype=numpy.complex128)
+        return numpy.roots(coeffs)
+
+    def evaluate(self, z, eps=None, height=2.0, steps=100, order=15):
+        """
+        Evaluate the Stieltjes-branch solution m(z) at a single point.
+
+        Parameters are as in the original function, except ``a`` is fixed at
+        construction time.
+        """
+        z = complex(z)
+
+        if steps < 1:
+            raise ValueError("steps must be a positive integer.")
+
+        # Boundary-value interpretation on the real axis
+        if z.imag == 0.0:
+            if self.eps is None:
+                eps_loc = 1e-8 * max(1.0, abs(z))
+            else:
+                eps_loc = float(self.eps)
+            z_eval = z + 1j * eps_loc
+        else:
+            z_eval = z
+
+        half_sign = numpy.sign(z_eval.imag)
+        if half_sign == 0.0:
+            half_sign = 1.0
+
+        # If z is outside radius of convergence, no homotopy
+        # necessary
+        if numpy.abs(z) > self.rad:
+            target = self.mom.stieltjes(z, self.order)
+            return select_root(self._poly_roots(z), z, target)
+
+        z0 = 1j * float(half_sign) * self.rad
+        target = self.mom.stieltjes(z0, self.order)
+
+        # Initialize at z0
+        w_prev = select_root(self._poly_roots(z0), z0, target)
+
+        # Straight-line homotopy continuation
+        for tau in numpy.linspace(0.0, 1.0, int(self.steps) + 1)[1:]:
+            z_tau = z0 + tau * (z_eval - z0)
+            w_prev = select_root(self._poly_roots(z_tau), z_tau, w_prev)
+
+        return w_prev
+
+    def __call__(self, z):
+        # Scalar fast-path
+        if numpy.isscalar(z):
+            return self.evaluate(z)
+
+        # Array-like: evaluate elementwise, preserving shape
+        z_arr = numpy.asarray(z)
+        out = numpy.empty(z_arr.shape, dtype=numpy.complex128)
+
+        # Iterate over indices so we can pass Python scalars into evaluate()
+        for idx in numpy.ndindex(z_arr.shape):
+            out[idx] = self.evaluate(z_arr[idx])
+
+        return out
+
+
+# def stieltjes_poly(z, a, eps=None, height=2., steps=100, order=15):
+#     """
+#     Evaluate the Stieltjes-branch solution m(z) of an algebraic equation.
+
+#     The coefficients `a` define a polynomial relation
+#         P(z, m) = 0,
+#     where P is a polynomial in z and m with monomial-basis coefficients
+#     arranged so that for fixed z, the coefficients of the polynomial in m
+#     can be assembled from powers of z.
+
+#     Parameters
+#     ----------
+#     z : complex
+#         Evaluation point. Must be a single value.
+#     a : ndarray, shape (L, K)
+#         Coefficient matrix defining P(z, m) in the monomial basis.
+#     eps : float or None, optional
+#         If Im(z) == 0, use z + i*eps as the boundary evaluation point.
+#         If None and Im(z) == 0, eps is set to 1e-8 * max(1, |z|).
+#     height : float, default = 2.0
+#         Imaginary height used for the starting point z0 in the same
+#         half-plane as the evaluation point.
+#     steps : int, default = 100
+#         Number of continuation steps along the homotopy path.
+#     order : int, default = 15
+#         Number of moments in Stieltjes estimate
+
+#     Returns
+#     -------
+#     w : complex
+#         Value of the Stieltjes-branch solution m(z) (or m(z+i*eps) if z is
+#         real).
+#     """
+
+#     z = complex(z)
+#     a = numpy.asarray(a)
+
+#     if a.ndim != 2:
+#         raise ValueError('a must be a 2D array.')
+
+#     if steps < 1:
+#         raise ValueError("steps must be a positive integer.")
+
+#     a_l, _ = a.shape
+#     mom = AlgebraicStieltjesMoments(a)
+
+#     def poly_coeffs_m(z_val):
+#         z_powers = z_val ** numpy.arange(a_l)
+#         return (z_powers @ a)[::-1]
+
+#     def poly_roots(z_val):
+#         coeffs = numpy.asarray(poly_coeffs_m(z_val), dtype=numpy.complex128)
+#         return numpy.roots(coeffs)
+
+#     # If user asked for a real-axis value, interpret as boundary value from C+.
+#     if z.imag == 0.0:
+#         if eps is None:
+#             eps = 1e-8 * max(1.0, abs(z))
+#         z_eval = z + 1j * float(eps)
+#     else:
+#         z_eval = z
+
+#     half_sign = numpy.sign(z_eval.imag)
+#     if half_sign == 0.0:
+#         half_sign = 1.0
+
+#     z0 = 1j * float(half_sign) * (1. + height * mom.radius(order))
+#     target = mom.stieltjes(z0, order)
+
+#     # Initialize at z0 via asymptotic / Im-sign selection.
+#     w_prev = select_root(poly_roots(z0), z0, target)
+
+#     # Straight-line homotopy from z0 to z_eval.
+#     for tau in numpy.linspace(0.0, 1.0, int(steps) + 1)[1:]:
+#         z_tau = z0 + tau * (z_eval - z0)
+#         w_prev = select_root(poly_roots(z_tau), z_tau, w_prev)
+
+#     return w_prev