freealg 0.7.6__py3-none-any.whl → 0.7.8__py3-none-any.whl

freealg/__version__.py

@@ -1 +1 @@
-__version__ = "0.7.6"
+__version__ = "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/_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/_algebraic_form/_homotopy.py

@@ -3,17 +3,19 @@
 # =======
 
 import numpy
+from ._moments import AlgebraicStieltjesMoments
 
 __all__ = ['stieltjes_poly']
 
 
 # =====================
-# stieltjes select root
+# select root
 # =====================
 
-def stieltjes_select_root(roots, z, w_prev=None):
+def select_root(roots, z, target):
     """
-    Select the Stieltjes-branch root among candidates at a given z.
+    Select the root among Herglotz candidates at a given z closest to a
+    given target
 
     Parameters
     ----------
@@ -22,9 +24,9 @@ def stieltjes_select_root(roots, z, w_prev=None):
     z : complex
         Evaluation point. The Stieltjes/Herglotz branch satisfies
         sign(Im(m)) = sign(Im(z)) away from the real axis.
-    w_prev : complex or None, optional
-        Previous continuation value used to enforce continuity. If None,
-        the asymptotic target -1/z is used.
+    target : complex
+        Previous continuation value used to enforce continuity, or
+        target value.
 
     Returns
     -------
@@ -40,11 +42,6 @@ def stieltjes_select_root(roots, z, w_prev=None):
 
     desired_sign = numpy.sign(z.imag)
 
-    if w_prev is None:
-        target = -1.0 / z
-    else:
-        target = complex(w_prev)
-
     # 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)
@@ -62,77 +59,222 @@ def stieltjes_select_root(roots, z, w_prev=None):
 # stieltjes poly
 # ==============
 
-def stieltjes_poly(z, a, eps=None, height=1e+4, steps=100):
+class StieltjesPoly(object):
     """
-    Evaluate the Stieltjes-branch solution m(z) of an algebraic equation.
+    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
 
-    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.
+
+    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
     ----------
-    z : complex
-        Evaluation point. Must be a single value.
     a : ndarray, shape (L, K)
-        Coefficient matrix defining P(z, m) in the monomial basis.
+        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, optional
+    height : float, default = 2.0
         Imaginary height used for the starting point z0 in the same
         half-plane as the evaluation point.
-    steps : int, optional
+    steps : int, default = 100
         Number of continuation steps along the homotopy path.
+    order : int, default = 15
+        Number of moments in Stieltjes estimate
 
-    Returns
+    Methods
     -------
-    w : complex
-        Value of the Stieltjes-branch solution m(z) (or m(z+i*eps) if z is
-        real).
+    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|).
     """
 
-    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
-
-    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)
+    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)
 
-    # 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) * float(height)
-
-    # Initialize at z0 via asymptotic / Im-sign selection.
-    w_prev = stieltjes_select_root(poly_roots(z0), z0, w_prev=None)
-
-    # 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 = stieltjes_select_root(poly_roots(z_tau), z_tau, w_prev=w_prev)
-
-    return w_prev
+    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

freealg/_algebraic_form/_moments.py

@@ -0,0 +1,450 @@
+import numpy
+
+
+# =========
+# Moments
+# =========
+
+class MomentsESD(object):
+    """
+    Moments :math:`\\mu_n(t)` generated from eigenvalues, under
+    free decompression, where
+
+    .. math::
+
+        m_n = \\mu_n(0) = \\mathbb{E}[\\lambda^n],
+
+    and :math:`\\lambda` denotes an eigenvalue sample.
+
+    Parameters
+    ----------
+
+    eig : array_like
+        1D array of eigenvalues (or samples). Internally it is converted to a
+        floating-point :class:`numpy.ndarray`.
+
+    Attributes
+    ----------
+
+    eig : numpy.ndarray
+        Eigenvalue samples.
+
+    Methods
+    -------
+
+    m
+        Compute the raw moment :math:`m_n = \\mathbb{E}[\\lambda^n]`.
+
+    coeffs
+        Compute the coefficient vector :math:`a_n`.
+
+    __call__
+        Evaluate :math:`\\mu_n(t)` for a given :math:`n` and :math:`t`.
+
+    Notes
+    -----
+
+    The recursion memoizes:
+
+    * Moments ``_m[n] = m_n``.
+    * Coefficients ``_a[n] = a_n`` where ``a_n`` has length ``n`` and contains
+      :math:`(a_{n,0}, \\dots, a_{n,n-1})`.
+
+    The coefficient row :math:`a_n` is computed using an intermediate quantity
+    :math:`R_{n,k}` formed via discrete convolutions of previous rows.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        >>> import numpy as np
+        >>> eig = np.array([1.0, 2.0, 3.0])
+        >>> mu = Moments(eig)
+        >>> mu(3, t=0.0)   # equals m_3
+        12.0
+        >>> mu(3, t=0.1)
+        14.203...
+    """
+
+    # ====
+    # init
+    # ====
+
+    def __init__(self, eig):
+        """
+        Initialization.
+        """
+
+        self.eig = numpy.asarray(eig, dtype=float)
+
+        # Memoized moments m_n
+        self._m = {0: 1.0}
+
+        # Memoized coefficients a[n] = array of length n
+        # (a_{n,0},...,a_{n,n-1})
+        self._a = {0: numpy.array([1.0])}
+
+    # ----------
+    # moments
+    # ----------
+
+    def m(self, n):
+        """
+        Compute raw moment :math:`m_n`.
+
+        Parameters
+        ----------
+
+        n : int
+            Order of the moment.
+
+        Returns
+        -------
+
+        m_n : float
+            The raw moment :math:`m_n = \\mathbb{E}[\\lambda^n]`, estimated by
+            the sample mean of ``eig**n``.
+        """
+
+        if n not in self._m:
+            self._m[n] = numpy.mean(self.eig ** n)
+        return self._m[n]
+
+    # -------------
+    # coefficients
+    # -------------
+
+    def coeffs(self, n):
+        """
+        Get coefficients :math:`a_n` for :math:`\\mu_n(t)`.
+
+        Parameters
+        ----------
+
+        n : int
+            Order of :math:`\\mu_n(t)`.
+
+        Returns
+        -------
+
+        a_n : numpy.ndarray
+            Array of shape ``(n,)`` containing :math:`(a_{n,0}, \\dots, a_{n,n-1})`.
+        """
+
+        if n in self._a:
+            return self._a[n]
+
+        # Ensure previous rows exist
+        for r in range(1, n):
+            if r not in self._a:
+                self._compute_row(r)
+
+        self._compute_row(n)
+        return self._a[n]
+
+    def _compute_row(self, n):
+        """
+        Compute and memoize the coefficient row :math:`a_n`.
+
+        Parameters
+        ----------
+
+        n : int
+            Row index to compute.
+
+        Notes
+        -----
+
+        For :math:`n=1`, the row is
+
+        .. math::
+
+            a_{1,0} = m_1.
+
+        For :math:`n \\ge 2`, let :math:`R_n` be a length ``n-1`` array defined
+        by convolution of previous rows:
+
+        .. math::
+
+            R_n = \\sum_{i=1}^{n-1} (a_i * a_{n-i})\\big|_{0:(n-2)}.
+
+        Then for :math:`k = 0, \\dots, n-2`,
+
+        .. math::
+
+            a_{n,k} = \\frac{1 + k/2}{(n-1-k)} R_{n,k},
+
+        and the last coefficient is chosen so that :math:`\\mu_n(0)=m_n`:
+
+        .. math::
+
+            a_{n,n-1} = m_n - \\sum_{k=0}^{n-2} a_{n,k}.
+        """
+
+        if n in self._a:
+            return
+
+        if n == 1:
+            self._a[1] = numpy.array([self.m(1)])
+            return
+
+        # Ensure all smaller rows exist
+        for r in range(1, n):
+            if r not in self._a:
+                self._compute_row(r)
+
+        a_n = numpy.zeros(n, dtype=float)
+
+        # Compute R_{n,k} via convolutions:
+        # R_n = sum_{i=1}^{n-1} convolve(a[i], a[n-i]) truncated to length n-1
+        R = numpy.zeros(n - 1, dtype=float)
+        for i in range(1, n):
+            conv = numpy.convolve(self._a[i], self._a[n - i])
+            R += conv[: n - 1]
+
+        k = numpy.arange(n - 1, dtype=float)
+        factors = (1.0 + 0.5 * k) / (n - 1 - k)
+        a_n[: n - 1] = factors * R
+
+        # k = n-1 from the initial condition mu_n(0) = m_n
+        a_n[n - 1] = self.m(n) - a_n[: n - 1].sum()
+
+        self._a[n] = a_n
+
+    # ----------
+    # evaluate
+    # ----------
+
+    def __call__(self, n, t=0.0):
+        """
+        Evaluate :math:`\\mu_n(t)`.
+
+        Parameters
+        ----------
+
+        n : int
+            Order of :math:`\\mu_n(t)`.
+
+        t : float, default=0.0
+            Deformation parameter.
+
+        Returns
+        -------
+
+        mu_n : float
+            The value of :math:`\\mu_n(t)`.
+
+        Notes
+        -----
+
+        This function evaluates
+
+        .. math::
+
+            \\mu_n(t) = \\sum_{k=0}^{n-1} a_{n,k} \\, e^{k t}.
+
+        For ``n == 0``, it returns ``1.0``.
+        """
+
+        if n == 0:
+            return 1.0
+
+        a_n = self.coeffs(n)
+        k = numpy.arange(n, dtype=float)
+        return numpy.dot(a_n, numpy.exp(k * t))
+
+# ===========================
+# Algebraic Stieltjes Moments
+# ===========================
+
+
+class AlgebraicStieltjesMoments(object):
+    """
+    Given coefficients a[i,j] for P(z,m)=sum_{i,j} a[i,j] z^i m^j,
+    compute the large-|z| branch
+        m(z) = sum_{k>=0} mu_series[k] / z^{k+1}.
+
+    Convention here: choose mu0 (the leading coefficient) by solving the 
+    leading-diagonal equation and (by default) picking the root closest
+    to -1, i.e. m(z) ~ -1/z.
+
+    The returned 'moments(N)' are normalized density moments:
+        mu_density[k] = mu_series[k] / mu_series[0]
+    so mu_density[0] = 1.
+    """
+
+    def __init__(self, a, mu0=None):
+        self.a = numpy.asarray(a)
+        # Ensure valid
+        self.a[-1, 0] = 0.0
+        if self.a.ndim != 2:
+            raise ValueError("a must be a 2D NumPy array with a[i,j]=a_{ij}.")
+
+        self.I = self.a.shape[0] - 1
+        self.J = self.a.shape[1] - 1
+
+        nz = numpy.argwhere(self.a != 0)
+        if nz.size == 0:
+            raise ValueError("All coefficients are zero.")
+
+        # r = max(i-j) over nonzero terms
+        self.r = int(numpy.max(nz[:, 0] - nz[:, 1]))
+
+        # Group coefficients by diagonal offset s = r - (i-j) >= 0
+        # diag[s] is list of (j, a_ij) for which i-j = r-s
+        self.diag = {}
+        for i, j in nz:
+            i = int(i)
+            j = int(j)
+            coeff = self.a[i, j]
+            s = self.r - (i - j)
+            if s >= 0:
+                self.diag.setdefault(int(s), []).append((j, coeff))
+
+        # Choose mu0 (series leading coefficient). This should be
+        # -1 for m(z) ~ -1/z, but it may only hold approximately.
+        if mu0 is None:
+            self.mu0 = self._solve_mu0()
+        else:
+            self.mu0 = mu0
+
+        # Precompute mu0^p up to p=J
+        self.mu0pow = [1]
+        for _ in range(self.J):
+            self.mu0pow.append(self.mu0pow[-1] * self.mu0)
+
+        # Linear coefficient A0 = sum_{i-j=r} j a_ij mu0^{j-1}
+        self.A0 = 0
+        for j, coeff in self.diag.get(0, []):
+            if j > 0:
+                self.A0 += j * coeff * self.mu0pow[j - 1]
+        if self.A0 == 0:
+            raise ValueError("A0 is zero for this mu0; the sequential recursion is degenerate.")
+
+        # Stored series moments mu_series[0..]
+        self._mu = [self.mu0]
+
+        # Convolution table c[j][n] = coefficient of w^n in (S(w))^j,
+        # where S(w) = sum_{t>=0} mu_series[t] w^t and m(z)=w S(w), w=1/z.
+        #
+        # We store c as lists growing in n: c[j][n] for j=0..J.
+        self._c = [[0] for _ in range(self.J + 1)]
+        self._c[0][0] = 1
+        for j in range(1, self.J + 1):
+            self._c[j][0] = self.mu0pow[j]
+
+    def _solve_mu0(self):
+        # Leading diagonal polynomial L(m) = sum_{i-j=r} a_ij m^j.
+        # That means i = j + r, so coefficient is a[j+r, j] if in bounds.
+        coeffs = numpy.zeros(self.J + 1, dtype=numpy.complex128)
+        for j in range(self.J + 1):
+            i = j + self.r
+            if 0 <= i <= self.I:
+                coeffs[j] = self.a[i, j]
+
+        if not numpy.any(coeffs != 0):
+            raise ValueError("Leading diagonal polynomial is identically zero; cannot determine mu0.")
+
+        deg = int(numpy.max(numpy.nonzero(coeffs)[0]))
+        roots = numpy.roots(coeffs[:deg + 1][::-1])  # descending powers for numpy.roots
+
+        # Targetting mu0 = -1 for ~ -1/z asymptotics
+        mu0 = roots[numpy.argmin(numpy.abs(roots + 1))]
+        
+        if abs(mu0.imag) < 1e-12:
+            mu0 = mu0.real
+        return mu0
+
+    def _ensure(self, N):
+        # Compute mu_series up to index N (inclusive)
+        while len(self._mu) <= N:
+            k = len(self._mu)  # compute mu_k
+
+            # Compute f[j] = coefficient of w^k in (S_trunc(w))^j,
+            # where S_trunc uses mu_0..mu_{k-1} only (i.e. mu_k treated as 0).
+            # Key fact: in the true c[j,k], mu_k can only appear linearly as j*mu_k*mu0^{j-1}.
+            f = [0] * (self.J + 1)
+            f[0] = 0
+            for j in range(1, self.J + 1):
+                ssum = 0
+                # sum_{t=1..k-1} mu_t * c[j-1, k-t]
+                for t in range(1, k):
+                    ssum += self._mu[t] * self._c[j - 1][k - t]
+                # recurrence: c[j,k] = mu0*c[j-1,k] + sum_{t=1..k-1} mu_t*c[j-1,k-t] + mu_k*c[j-1,0]
+                # with mu_k=0 for f, and c[j-1,k]=f[j-1]
+                f[j] = self.mu0 * f[j - 1] + ssum
+
+            # Build the linear equation for mu_k:
+            # A0*mu_k + rest = 0
+            rest = 0
+
+            # s=0 diagonal contributes coeff*(f[j]) (the mu_k-free part)
+            for j, coeff in self.diag.get(0, []):
+                if j == 0:
+                    # only affects k=0, but we never come here with k=0
+                    continue
+                rest += coeff * f[j]
+
+            # lower diagonals s=1..k contribute coeff*c[j,k-s] (already known since k-s < k)
+            for s in range(1, k + 1):
+                entries = self.diag.get(s)
+                if not entries:
+                    continue
+                n = k - s
+                for j, coeff in entries:
+                    if j == 0:
+                        if n == 0:
+                            rest += coeff
+                    else:
+                        rest += coeff * self._c[j][n]
+
+            mu_k = -rest / self.A0
+            self._mu.append(mu_k)
+
+            # Now append the new column k to c using the full convolution recurrence:
+            # c[j,k] = sum_{t=0..k} mu_t * c[j-1,k-t]
+            for j in range(self.J + 1):
+                self._c[j].append(0)
+
+            self._c[0][k] = 0
+            for j in range(1, self.J + 1):
+                val = 0
+                for t in range(0, k + 1):
+                    val += self._mu[t] * self._c[j - 1][k - t]
+                self._c[j][k] = val
+
+    # --- API ---
+
+    def __call__(self, k):
+        self._ensure(k)
+        return self._mu[k] / self._mu[0]
+
+    def moments(self, N):
+        # normalized density moments so moment 0 is 1
+        self._ensure(N)
+        mu0 = self._mu[0]
+        return numpy.array([self._mu[k] / mu0 for k in range(N + 1)])
+
+    def radius(self, N):
+        # Estimate the radius of convergence of the Stieltjes
+        # series
+        if N < 3:
+            raise RuntimeError("Order is too small, choose a larger value of N")
+        self._ensure(N)
+        return max([numpy.abs(self._mu[j] / self._mu[j-1]) for j in range(2,N+1)])
+
+    def stieltjes(self, z, N):
+        # Estimate Stieltjes transform (root) using moment
+        # expansion
+        z = numpy.asarray(z)
+        mu = self.moments(N)
+        return -numpy.sum(z[..., numpy.newaxis]**(-numpy.arange(N+1)-1) * mu,
+                          axis=-1)
+
+    def target_pt(self, N=15):
+        # Obtain an estimate of the Stieltjes transform at a
+        # single point z where the estimate is likely reliable
+        z = 1j + 2j * self.radius(N)
+        return z, self.stieltjes(z, N)
+

freealg/_algebraic_form/algebraic_form.py

@@ -20,7 +20,9 @@ from ._continuation_algebraic import sample_z_joukowski, \
 from ._edge import evolve_edges, merge_edges
 from ._decompress import decompress_newton
 from ._decompress2 import decompress_coeffs
-from ._homotopy import stieltjes_poly
+from ._homotopy import StieltjesPoly
+from ._discriminant import compute_singular_points
+from ._moments import MomentsESD
 from .._free_form._support import supp
 from .._free_form._plot_util import plot_density
 
@@ -143,6 +145,7 @@ class AlgebraicForm(object):
         self.A = None
         self.eig = None
         self.stieltjes = None
+        self.moments = None
         self.support = support
         self.delta = delta    # Offset above real axis to apply Plemelj formula
 
@@ -177,6 +180,7 @@ class AlgebraicForm(object):
             # Use empirical Stieltjes function
             self.stieltjes = lambda z: \
                 numpy.mean(1.0/(self.eig-z[:, numpy.newaxis]), axis=-1)
+            self.moments = MomentsESD(self.eig)
 
         # Support
         if support is None:
@@ -262,11 +266,13 @@ class AlgebraicForm(object):
 
         # Fitting (w_inf = None means adaptive weight selection)
         m1_fit = self.stieltjes(z_fit)
-        a_coeffs = fit_polynomial_relation(z_fit, m1_fit, s=deg_m, deg_z=deg_z,
-                                           ridge_lambda=reg,
-                                           triangular=triangular,
-                                           normalize=normalize, mu=mu,
-                                           mu_reg=mu_reg)
+        a_coeffs, fit_metrics = fit_polynomial_relation(
+                z_fit, m1_fit, s=deg_m, deg_z=deg_z, ridge_lambda=reg,
+                triangular=triangular, normalize=normalize, mu=mu,
+                mu_reg=mu_reg)
+
+        # Compute global branhc points, zeros of leading a_j, and support
+        branch_points, a_s_zero, support = compute_singular_points(a_coeffs)
 
         self.a_coeffs = a_coeffs
 
@@ -282,9 +288,13 @@ class AlgebraicForm(object):
                                                eta=max(y_eps, 1e-2), n_x=128,
                                                max_bad_frac=0.05)
 
+        status['branch_points'] = branch_points
+        status['a_s_zero'] = a_s_zero
         status['res_max'] = float(res_max)
         status['res_99_9'] = float(res_99_9)
+        status['fit_metrics'] = fit_metrics
         self.status = status
+        self.stieltjes = StieltjesPoly(self.a_coeffs)
 
         if verbose:
             print(f'fit residual max  : {res_max:>0.4e}')
@@ -309,7 +319,7 @@ class AlgebraicForm(object):
             else:
                 print('\nStieltjes sanity check: OK')
 
-        return a_coeffs, status
+        return a_coeffs, support, status
 
     # =============
     # generate grid
@@ -389,13 +399,7 @@ class AlgebraicForm(object):
             x = self._generate_grid(1.25)
 
         # Preallocate density to zero
-        rho = numpy.zeros_like(x)
-
-        for idx, x_i in enumerate(x):
-            m_i = stieltjes_poly(x_i, self.a_coeffs)
-            rho[idx] = m_i.imag
-
-        rho = rho / numpy.pi
+        rho = self.stieltjes(x).imag / numpy.pi
 
         # if self.method == 'jacobi':
         #     rho[mask] = jacobi_density(x[mask], self.psi, self.support,
@@ -663,12 +667,9 @@ class AlgebraicForm(object):
         # Decompression ratio equal to e^{t}.
         alpha = numpy.atleast_1d(size) / self.n
 
-        def m_fn(z):
-            return stieltjes_poly(z, self.a_coeffs)
-
         # Lower and upper bound on new support
-        hilb_lb = (1.0 / m_fn(self.lam_m + self.delta * 1j).item()).real
-        hilb_ub = (1.0 / m_fn(self.lam_p + self.delta * 1j).item()).real
+        hilb_lb = (1.0 / self.stieltjes(self.lam_m + self.delta * 1j).item()).real
+        hilb_ub = (1.0 / self.stieltjes(self.lam_p + self.delta * 1j).item()).real
         lb = self.lam_m - (numpy.max(alpha) - 1) * hilb_lb
         ub = self.lam_p - (numpy.max(alpha) - 1) * hilb_ub
 
@@ -689,9 +690,7 @@ class AlgebraicForm(object):
             z_query = x + 1j * self.delta
 
             # Initial condition at t=0 (physical branch)
-            # w0_list = self.stieltjes(z_query)
-            stieltjes = numpy.vectorize(m_fn)
-            w0_list = stieltjes(z_query)
+            w0_list = self.stieltjes(z_query)
 
             # Times
             t = numpy.log(alpha)
@@ -721,9 +720,8 @@ class AlgebraicForm(object):
             for i in range(alpha.size):
                 coeffs_i = decompress_coeffs(self.a_coeffs,
                                              numpy.log(alpha[i]))
-                for j, x_j in enumerate(x):
-                    m_j = stieltjes_poly(x_j, coeffs_i)
-                    rho[i, j] = m_j.imag
+                stieltjes_i = StieltjesPoly(coeffs_i)
+                rho[i, :] = stieltjes_i.imag
 
             rho = rho / numpy.pi
 

{freealg-0.7.6.dist-info → freealg-0.7.8.dist-info}/METADATA

@@ -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.6.dist-info → freealg-0.7.8.dist-info}/RECORD

@@ -1,15 +1,17 @@
 freealg/__init__.py,sha256=SjcYb6HWmaclnnM-m1eC1honZRyfNBWYDYBx23kSdjo,833
-freealg/__version__.py,sha256=wu65dmVM9fKR1rBHH263ls8Ca2FZzb0ejYcrP_Ld0iY,22
+freealg/__version__.py,sha256=uC8wB9mRblQ0jUBAOUyCQLUQJ39MC2xybVLB_8ZsevU,22
 freealg/_util.py,sha256=RzccUCORgzrI9NdNqwMVugiHU0uDKkJFcIyjFMUOnv8,2518
 freealg/_algebraic_form/__init__.py,sha256=MIB_jVgw2qI-JW_ypqaFSeNAB6c4GvpjNySnap_a6hg,398
 freealg/_algebraic_form/_constraints.py,sha256=37U7nvtCTocuS7l_nfUznkPi195PY7eXFzeiikrv3B0,2448
-freealg/_algebraic_form/_continuation_algebraic.py,sha256=SyuWjw0jABlIst9RjHS13gG2M94KZwwrTa3eeJNfmRI,19098
+freealg/_algebraic_form/_continuation_algebraic.py,sha256=KundB9VfX61a35VRxLFyuvB5A51QdT4PD2ffAMjrKR0,19383
 freealg/_algebraic_form/_decompress.py,sha256=gGtixLOVxlMy5S-NsXgoA7lIrB7u7nUZImQk1mIDo3s,21101
 freealg/_algebraic_form/_decompress2.py,sha256=Ng9w9xmGe9M-DApp35IeNeQlvszfzT4NZx5BQn0lQ3I,2459
+freealg/_algebraic_form/_discriminant.py,sha256=755pproom6-xThFARaH20m4GuBwwZS2rc0Y80Yg6NzY,5331
 freealg/_algebraic_form/_edge.py,sha256=7l9QyLJDxaEY4WB6MCUFtfEZSf04wyHwH7YPHFJXSbM,10690
-freealg/_algebraic_form/_homotopy.py,sha256=2oMcqJ2VJGzG7WKGM6FUS3923GT8Adtq_hLPEGgzqoU,3990
+freealg/_algebraic_form/_homotopy.py,sha256=YmNpRbKYKHQIYQpRsyFqUIQhaCr4bvxSQLyPwg61iO8,9174
+freealg/_algebraic_form/_moments.py,sha256=xSQdJhPUtSnXOLrd2JDmz4O_soDCtmcDt5_iSeiNOZg,12404
 freealg/_algebraic_form/_sheets_util.py,sha256=6OLzWQKu-gN8rxM2rbpbN8TjNZFmD8UJ-8t9kcZdkCo,4174
-freealg/_algebraic_form/algebraic_form.py,sha256=N-R8cv7580p-iPW7oPlDZ9py7BVjEmPcCjs25UVtNV4,32706
+freealg/_algebraic_form/algebraic_form.py,sha256=fmcyunM4fkRjuVjQpDtgwBBs5wTbShPyNGGSpqAynIM,32775
 freealg/_free_form/__init__.py,sha256=5cnSX7kHci3wKx6-BEFhmVY_NjjmQAq1JjWPTEqETTg,611
 freealg/_free_form/_chebyshev.py,sha256=zkyVA8NLf7uUKlJdLz4ijd_SurdsqUgkA5nHGWSybaE,6916
 freealg/_free_form/_damp.py,sha256=k2vtBtWOxQBf4qXaWu_En81lQBXbEO4QbxxWpvuVhdE,1802
@@ -42,9 +44,9 @@ freealg/distributions/_wigner.py,sha256=epgx6ne6R_7to5j6-QsWIAVFJQFquWMmYgnZYMN4
 freealg/visualization/__init__.py,sha256=NLq_zwueF7ytZ8sl8zLPqm-AODxxXNvfMozHGmmklcE,435
 freealg/visualization/_glue_util.py,sha256=2oKnEYjUOS4OZfivmciVLauVr53kyHMwi6c2zRKilTQ,693
 freealg/visualization/_rgb_hsv.py,sha256=rEskxXxSlKKxIrHRslVkgxHtD010L3ge9YtcVsOPl8E,3650
-freealg-0.7.6.dist-info/licenses/AUTHORS.txt,sha256=0b67Nz4_JgIzUupHJTAZxu5QdSUM_HRM_X_w4xCb17o,30
-freealg-0.7.6.dist-info/licenses/LICENSE.txt,sha256=J-EEYEtxb3VVf_Bn1TYfWnpY5lMFIM15iLDDcnaDTPA,1443
-freealg-0.7.6.dist-info/METADATA,sha256=cifScuAeI6gPbjzzCzBMMLqTYtxbqIIJhuICSIi-BkE,5516
-freealg-0.7.6.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-freealg-0.7.6.dist-info/top_level.txt,sha256=eR2wrgYwDdnnJ9Zf5PruPqe4kQav0GMvRsqct6y00Q8,8
-freealg-0.7.6.dist-info/RECORD,,
+freealg-0.7.8.dist-info/licenses/AUTHORS.txt,sha256=0b67Nz4_JgIzUupHJTAZxu5QdSUM_HRM_X_w4xCb17o,30
+freealg-0.7.8.dist-info/licenses/LICENSE.txt,sha256=J-EEYEtxb3VVf_Bn1TYfWnpY5lMFIM15iLDDcnaDTPA,1443
+freealg-0.7.8.dist-info/METADATA,sha256=b5v5ekXtGJh4o-fcwxpF58bMWc8oZs4qrgfVMDO79h0,5516
+freealg-0.7.8.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+freealg-0.7.8.dist-info/top_level.txt,sha256=eR2wrgYwDdnnJ9Zf5PruPqe4kQav0GMvRsqct6y00Q8,8
+freealg-0.7.8.dist-info/RECORD,,