freealg 0.7.11__py3-none-any.whl → 0.7.14__py3-none-any.whl

freealg/_algebraic_form/_homotopy4.py

@@ -0,0 +1,320 @@
+# SPDX-FileCopyrightText: Copyright 2026, Siavash Ameli
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileType: SOURCE
+#
+# Robust Stieltjes branch evaluation for algebraic P(z,m)=0.
+#
+# This version is tailored for empirical polynomial fits where spurious
+# small-Im roots can appear outside the true support and create fake bulks
+# when using rho = Im m(x+i*eta)/pi.
+#
+# Core idea: pick the physical branch by combining
+#   (i) Herglotz half-plane constraint,
+#   (ii) asymptotic constraint z*m ~ -1,
+#   (iii) 1D continuity along x (Viterbi),
+# and DO NOT globally reward large |Im(m)| (which can fabricate density).
+
+import numpy
+
+__all__ = ["StieltjesPoly"]
+
+
+# =========================
+# Poly -> roots in m for z
+# =========================
+
+def _poly_m_coeffs(a_coeffs, z):
+    """Return coefficients b_j for \sum_j b_j m^j = 0 at fixed z.
+
+    a_coeffs[i,j] is coeff of z^i m^j.
+    Returns b of length (deg_m+1) with b[j] = \sum_i a[i,j] z^i.
+    """
+    a = numpy.asarray(a_coeffs, dtype=numpy.complex128)
+    deg_z = a.shape[0] - 1
+    deg_m = a.shape[1] - 1
+
+    # Horner in z for each m-power j
+    z = complex(z)
+    b = numpy.zeros((deg_m + 1,), dtype=numpy.complex128)
+    # b[j] = a[0,j] + a[1,j] z + ... + a[deg_z,j] z^{deg_z}
+    # do Horner: (((a[deg_z,j] z + a[deg_z-1,j]) z + ...) z + a[0,j])
+    for j in range(deg_m + 1):
+        acc = 0.0 + 0.0j
+        for i in range(deg_z, -1, -1):
+            acc = acc * z + a[i, j]
+        b[j] = acc
+
+    return b
+
+
+def _roots_m(a_coeffs, z):
+    """All algebraic roots in m at fixed z."""
+    b = _poly_m_coeffs(a_coeffs, z)
+
+    # Drop leading zeros in highest power to keep numpy.roots stable
+    # numpy.roots expects highest degree first.
+    coeffs = b.copy()
+    # find highest nonzero index
+    nz = numpy.flatnonzero(numpy.abs(coeffs) > 0.0)
+    if nz.size == 0:
+        return numpy.array([], dtype=numpy.complex128)
+    j_max = int(nz.max())
+    coeffs = coeffs[: j_max + 1]
+
+    # reverse to highest-first
+    return numpy.roots(coeffs[::-1])
+
+
+# ==============================
+# Physical root selection scalar
+# ==============================
+
+def _pick_physical_root_scalar(z, roots, target=None, tol_im=1e-12):
+    """Pick the physical root among candidates for a single z.
+
+    Rules:
+      1) Prefer roots with sign(Im m) = sign(Im z) (Herglotz).
+      2) Break ties by asymptotic closeness to -1/z.
+      3) If target provided, also enforce continuity by closeness to target.
+
+    Returns complex root.
+    """
+    z = complex(z)
+    roots = numpy.asarray(roots, dtype=numpy.complex128).ravel()
+    if roots.size == 0:
+        return numpy.nan + 1j * numpy.nan
+
+    s = numpy.sign(z.imag)
+    if s == 0.0:
+        s = 1.0
+
+    im_s = numpy.imag(roots) * s
+    cand = roots[im_s > -tol_im]
+    if cand.size == 0:
+        cand = roots
+
+    # asymptotic target
+    m_asym = -1.0 / z
+
+    if target is None:
+        score = numpy.abs(cand - m_asym)
+    else:
+        t = complex(target)
+        # continuity dominates, asymptotic helps in ambiguous regions
+        score = numpy.abs(cand - t) + 0.15 * numpy.abs(cand - m_asym)
+
+    return cand[int(numpy.argmin(score))]
+
+
+# =====================
+# Viterbi along a line
+# =====================
+
+def _viterbi_track(z_list, roots_list, mL, mR, *,
+                  lam_space=1.0,
+                  lam_edge=20.0,
+                  lam_asym=0.25,
+                  lam_time=0.0,
+                  # Hinge penalty against "tiny-im" traps ONLY
+                  lam_tiny_im=0.0,
+                  tiny_im=1e-7,
+                  tol_im=1e-12,
+                  m_prev=None):
+    """Choose one root per z via dynamic programming.
+
+    z_list: (nz,)
+    roots_list: list of arrays of candidate roots, each (k_i,)
+    mL,mR: boundary anchors (complex)
+    m_prev: optional previous-time chosen path, shape (nz,)
+
+    Returns m_path (nz,) and ok (nz,) boolean indicating finite.
+    """
+    z_list = numpy.asarray(z_list, dtype=numpy.complex128).ravel()
+    nz = z_list.size
+
+    # Determine a fixed K by padding with NaNs (max roots)
+    K = max((r.size for r in roots_list), default=0)
+    if K == 0:
+        return (numpy.full((nz,), numpy.nan + 1j * numpy.nan, dtype=numpy.complex128),
+                numpy.zeros((nz,), dtype=bool))
+
+    R = numpy.full((nz, K), numpy.nan + 1j * numpy.nan, dtype=numpy.complex128)
+    for i, r in enumerate(roots_list):
+        if r.size:
+            R[i, : r.size] = r
+
+    # feasible mask: finite and Herglotz half-plane (soft)
+    s = numpy.sign(z_list.imag)
+    s[s == 0.0] = 1.0
+    IM = (numpy.imag(R) * s[:, None])
+    feasible = numpy.isfinite(R) & (IM > -tol_im)
+
+    # unary cost
+    unary = numpy.full((nz, K), numpy.inf, dtype=numpy.float64)
+    # continuity to asymptotic (-1/z) discourages fake branches outside support
+    m_asym = -1.0 / z_list
+
+    for i in range(nz):
+        zi = z_list[i]
+        mi = m_asym[i]
+        for k in range(K):
+            if not feasible[i, k]:
+                continue
+            w = R[i, k]
+            c = 0.0
+
+            # asymptotic penalty (small weight)
+            if lam_asym != 0.0:
+                c += float(lam_asym) * float(numpy.abs(zi * w + 1.0))
+
+            # optional hinge against tiny imag (ONLY below threshold)
+            if lam_tiny_im != 0.0:
+                im = abs(w.imag)
+                floor = max(float(tiny_im), 0.25 * abs(zi.imag))
+                if im < floor:
+                    c += float(lam_tiny_im) * float(((floor / max(im, 1e-16)) - 1.0) ** 2)
+
+            # optional time consistency
+            if (lam_time != 0.0) and (m_prev is not None) and numpy.isfinite(m_prev[i]):
+                c += float(lam_time) * float(numpy.abs(w - m_prev[i]))
+
+            unary[i, k] = c
+
+    # boundary anchors
+    if numpy.isfinite(mL):
+        unary[0, :] += float(lam_edge) * numpy.abs(R[0, :] - mL)
+    if numpy.isfinite(mR):
+        unary[-1, :] += float(lam_edge) * numpy.abs(R[-1, :] - mR)
+
+    # pairwise cost
+    dp = numpy.full((nz, K), numpy.inf, dtype=numpy.float64)
+    prev = numpy.full((nz, K), -1, dtype=numpy.int64)
+
+    dp[0, :] = unary[0, :]
+
+    for i in range(1, nz):
+        for k in range(K):
+            if not numpy.isfinite(unary[i, k]):
+                continue
+            # transition from any j
+            best_val = numpy.inf
+            best_j = -1
+            wk = R[i, k]
+            for j in range(K):
+                if not numpy.isfinite(dp[i - 1, j]):
+                    continue
+                wj = R[i - 1, j]
+                if not numpy.isfinite(wj):
+                    continue
+                val = dp[i - 1, j] + float(lam_space) * float(numpy.abs(wk - wj))
+                if val < best_val:
+                    best_val = val
+                    best_j = j
+            if best_j >= 0:
+                dp[i, k] = best_val + unary[i, k]
+                prev[i, k] = best_j
+
+    # backtrack
+    k_end = int(numpy.argmin(dp[-1, :]))
+    m_path = numpy.full((nz,), numpy.nan + 1j * numpy.nan, dtype=numpy.complex128)
+    if not numpy.isfinite(dp[-1, k_end]):
+        return m_path, numpy.zeros((nz,), dtype=bool)
+
+    k = k_end
+    for i in range(nz - 1, -1, -1):
+        m_path[i] = R[i, k]
+        k = prev[i, k]
+        if (i > 0) and (k < 0):
+            # cannot continue
+            break
+
+    ok = numpy.isfinite(m_path)
+    return m_path, ok
+
+
+# ============
+# StieltjesPoly
+# ============
+
+class StieltjesPoly(object):
+    """Callable m(z) for P(z,m)=0 using robust branch selection."""
+
+    def __init__(self, a_coeffs, *,
+                 viterbi_opt=None):
+        self.a_coeffs = numpy.asarray(a_coeffs, dtype=numpy.complex128)
+        self.viterbi_opt = dict(viterbi_opt or {})
+
+    # ----------
+    # scalar eval
+    # ----------
+
+    def evaluate_scalar(self, z, target=None):
+        r = _roots_m(self.a_coeffs, z)
+        return _pick_physical_root_scalar(z, r, target=target)
+
+    # ---------------
+    # vectorized eval
+    # ---------------
+
+    def __call__(self, z):
+        z = numpy.asarray(z, dtype=numpy.complex128)
+        scalar = (z.ndim == 0)
+        if scalar:
+            z = z.reshape((1,))
+
+        # If 1D, do Viterbi tracking in the given order
+        if z.ndim == 1:
+            z_list = z.ravel()
+
+            # roots for each point
+            roots_list = [_roots_m(self.a_coeffs, zi) for zi in z_list]
+
+            # boundary anchors via scalar selection
+            mL = self.evaluate_scalar(z_list[0])
+            mR = self.evaluate_scalar(z_list[-1])
+
+            opt = {
+                "lam_space": 1.0,
+                "lam_edge": 20.0,
+                "lam_asym": 0.25,
+                "lam_time": 0.0,
+                "lam_tiny_im": 0.0,
+                "tiny_im": 1e-7,
+                "tol_im": 1e-12,
+            }
+            opt.update(self.viterbi_opt)
+
+            m_path, ok = _viterbi_track(
+                z_list,
+                roots_list,
+                mL,
+                mR,
+                lam_space=opt["lam_space"],
+                lam_edge=opt["lam_edge"],
+                lam_asym=opt["lam_asym"],
+                lam_time=opt["lam_time"],
+                lam_tiny_im=opt["lam_tiny_im"],
+                tiny_im=opt["tiny_im"],
+                tol_im=opt["tol_im"],
+                m_prev=None,
+            )
+
+            # fallback pointwise for any failures
+            if not numpy.all(ok):
+                out = m_path.copy()
+                for i in numpy.flatnonzero(~ok):
+                    out[i] = self.evaluate_scalar(z_list[i], target=None)
+                m_path = out
+
+            out = m_path.reshape(z.shape)
+            return out.reshape(()) if scalar else out
+
+        # For nd>1: evaluate pointwise with asymptotic tie-break
+        out = numpy.empty(z.size, dtype=numpy.complex128)
+        zf = z.ravel()
+        prev = None
+        for i in range(zf.size):
+            out[i] = self.evaluate_scalar(zf[i], target=prev)
+            prev = out[i]
+        out = out.reshape(z.shape)
+        return out.reshape(()) if scalar else out

freealg/_algebraic_form/_homotopy5.py

@@ -0,0 +1,185 @@
+# SPDX-FileCopyrightText: Copyright 2026, Siavash Ameli
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileType: SOURCE
+#
+# Robust Stieltjes branch evaluation for algebraic P(z,m)=0 using
+# global 1D dynamic programming (Viterbi) along a complex line.
+
+import numpy
+
+
+def _poly_coeffs_in_m(a_coeffs, z):
+    a = a_coeffs
+    dz = a.shape[0] - 1
+    s = a.shape[1] - 1
+    zp = numpy.array([z**i for i in range(dz + 1)], dtype=numpy.complex128)
+    coeff_m = numpy.empty(s + 1, dtype=numpy.complex128)
+    for j in range(s + 1):
+        coeff_m[j] = numpy.dot(a[:, j], zp)
+    return coeff_m
+
+
+def _roots_m(a_coeffs, z):
+    coeff_m = _poly_coeffs_in_m(a_coeffs, z)
+    c = coeff_m[::-1]
+    while c.size > 1 and numpy.abs(c[0]) == 0:
+        c = c[1:]
+    if c.size <= 1:
+        return numpy.array([], dtype=numpy.complex128)
+    return numpy.roots(c)
+
+
+def _pick_anchor(z, roots, tol_im, lam_asym):
+    if roots.size == 0:
+        return numpy.nan + 1j * numpy.nan
+    sgn = 1.0 if numpy.imag(z) >= 0 else -1.0
+    ok = (sgn * numpy.imag(roots) > tol_im)
+    if numpy.any(ok):
+        cand = roots[ok]
+    else:
+        cand = roots
+    cost = lam_asym * numpy.abs(z * cand + 1.0)
+    return cand[int(numpy.argmin(cost))]
+
+
+def _viterbi_1d(z_list, roots_all, *, lam_space, lam_asym,
+                lam_tiny_im, tiny_im, tol_im):
+    n, s = roots_all.shape
+    big = 1.0e300
+
+    cost0 = numpy.zeros((n, s), dtype=float)
+    back = numpy.zeros((n, s), dtype=numpy.int64)
+    dp = numpy.full((n, s), big, dtype=float)
+
+    for k in range(n):
+        z = z_list[k]
+        r = roots_all[k]
+        sgn = 1.0 if numpy.imag(z) >= 0 else -1.0
+
+        ok = (sgn * numpy.imag(r) > tol_im)
+        cost0[k, ~ok] += big * 1.0e-6
+
+        if lam_tiny_im != 0.0 and tiny_im is not None:
+            imabs = numpy.abs(numpy.imag(r))
+            hing = numpy.maximum(0.0, float(tiny_im) - imabs)
+            cost0[k] += lam_tiny_im * hing
+
+        if lam_asym != 0.0:
+            cost0[k] += lam_asym * numpy.abs(z * r + 1.0)
+
+    m0 = _pick_anchor(z_list[0], roots_all[0], tol_im, lam_asym)
+    mN = _pick_anchor(z_list[-1], roots_all[-1], tol_im, lam_asym)
+
+    init = cost0[0] + lam_space * numpy.abs(roots_all[0] - m0)
+    dp[0] = init
+
+    for k in range(1, n):
+        r = roots_all[k]
+        rp = roots_all[k - 1]
+        for j in range(s):
+            trans = dp[k - 1] + lam_space * numpy.abs(r[j] - rp)
+            idx = int(numpy.argmin(trans))
+            dp[k, j] = trans[idx] + cost0[k, j]
+            back[k, j] = idx
+
+    last = dp[-1] + lam_space * numpy.abs(roots_all[-1] - mN)
+    jn = int(numpy.argmin(last))
+
+    path = numpy.empty(n, dtype=numpy.complex128)
+    for k in range(n - 1, -1, -1):
+        path[k] = roots_all[k, jn]
+        if k > 0:
+            jn = int(back[k, jn])
+    return path
+
+
+class StieltjesPoly(object):
+    """Callable m(z) for P(z,m)=0 using robust branch selection."""
+
+    def __init__(self, a_coeffs, *, viterbi_opt=None):
+        self.a_coeffs = numpy.asarray(a_coeffs, dtype=numpy.complex128)
+        self.viterbi_opt = dict(viterbi_opt or {})
+
+    def evaluate_scalar(self, z, target=None):
+        r = _roots_m(self.a_coeffs, z)
+        if r.size == 0:
+            return numpy.nan + 1j * numpy.nan
+        tol_im = float(self.viterbi_opt.get("tol_im", 1e-14))
+        lam_asym = float(self.viterbi_opt.get("lam_asym", 1.0))
+        sgn = 1.0 if numpy.imag(z) >= 0 else -1.0
+        ok = (sgn * numpy.imag(r) > tol_im)
+        cand = r[ok] if numpy.any(ok) else r
+        cost = lam_asym * numpy.abs(z * cand + 1.0)
+        if target is not None and numpy.isfinite(target):
+            lam_space = float(self.viterbi_opt.get("lam_space", 1.0))
+            cost = cost + lam_space * numpy.abs(cand - target)
+        return cand[int(numpy.argmin(cost))]
+
+    def __call__(self, z):
+        z = numpy.asarray(z, dtype=numpy.complex128)
+        scalar = (z.ndim == 0)
+        if scalar:
+            z = z.reshape((1,))
+
+        if z.ndim == 1 and z.size >= 2:
+            z_list = z.ravel()
+            s = self.a_coeffs.shape[1] - 1
+            roots_all = numpy.empty((z_list.size, s), dtype=numpy.complex128)
+            ok_all = numpy.ones(z_list.size, dtype=bool)
+            for k in range(z_list.size):
+                r = _roots_m(self.a_coeffs, z_list[k])
+                if r.size != s:
+                    ok_all[k] = False
+                    if r.size == 0:
+                        roots_all[k] = numpy.nan + 1j * numpy.nan
+                    elif r.size < s:
+                        rr = numpy.empty(s, dtype=numpy.complex128)
+                        rr[:] = numpy.nan + 1j * numpy.nan
+                        rr[:r.size] = r
+                        roots_all[k] = rr
+                    else:
+                        roots_all[k] = r[:s]
+                else:
+                    roots_all[k] = r
+
+            opt = {
+                "lam_space": 1.0,
+                "lam_asym": 1.0,
+                "lam_tiny_im": 200.0,
+                "tiny_im": None,
+                "tol_im": 1e-14,
+            }
+            opt.update(self.viterbi_opt)
+
+            if opt["tiny_im"] is None:
+                opt["tiny_im"] = 0.5 * numpy.abs(numpy.imag(z_list[0]))
+
+            m_path = _viterbi_1d(
+                z_list, roots_all,
+                lam_space=float(opt["lam_space"]),
+                lam_asym=float(opt["lam_asym"]),
+                lam_tiny_im=float(opt["lam_tiny_im"]),
+                tiny_im=float(opt["tiny_im"]),
+                tol_im=float(opt["tol_im"]),
+            )
+
+            if not numpy.all(ok_all):
+                out = m_path.copy()
+                prev = None
+                for i in range(z_list.size):
+                    if not ok_all[i] or not numpy.isfinite(out[i]):
+                        out[i] = self.evaluate_scalar(z_list[i], target=prev)
+                    prev = out[i]
+                m_path = out
+
+            out = m_path.reshape(z.shape)
+            return out.reshape(()) if scalar else out
+
+        out = numpy.empty(z.size, dtype=numpy.complex128)
+        zf = z.ravel()
+        prev = None
+        for i in range(zf.size):
+            out[i] = self.evaluate_scalar(zf[i], target=prev)
+            prev = out[i]
+        out = out.reshape(z.shape)
+        return out.reshape(()) if scalar else out

freealg/_algebraic_form/_moments.py

@@ -9,7 +9,7 @@ import numpy
 # Moments
 # =======
 
-class MomentsESD(object):
+class Moments(object):
     """
     Moments :math:`\\mu_n(t)` generated from eigenvalues, under
     free decompression, where
@@ -23,15 +23,21 @@ class MomentsESD(object):
     Parameters
     ----------
 
-    eig : array_like
-        1D array of eigenvalues (or samples). Internally it is converted to a
-        floating-point :class:`numpy.ndarray`.
+    source : array_like or callable
+        Either
+
+        * a 1D array of eigenvalues (or samples), or
+        * a callable returning the raw moments at zero, ``source(n) = m_n``.
+
+        If an array is provided, moments are estimated via sample averages.
+        If a callable is provided, it is assumed to return exact values of
+        :math:`m_n`.
 
     Attributes
     ----------
 
-    eig : numpy.ndarray
-        Eigenvalue samples.
+    eig : numpy.ndarray or None
+        Eigenvalue samples, if provided.
 
     Methods
     -------
@@ -56,31 +62,23 @@ class MomentsESD(object):
 
     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):
+    def __init__(self, source):
         """
         Initialization.
         """
+        self.eig = None
+        self._moment_fn = None
 
-        self.eig = numpy.asarray(eig, dtype=float)
+        if callable(source):
+            self._moment_fn = source
+        else:
+            self.eig = numpy.asarray(source, dtype=float)
 
         # Memoized moments m_n
         self._m = {0: 1.0}
@@ -107,12 +105,25 @@ class MomentsESD(object):
         -------
 
         m_n : float
-            The raw moment :math:`m_n = \\mathbb{E}[\\lambda^n]`, estimated by
-            the sample mean of ``eig**n``.
+            The raw moment :math:`m_n = \\mathbb{E}[\\lambda^n]`.
+
+        Notes
+        -----
+
+        If the instance was initialized with eigenvalue samples, the moment is
+        estimated by the sample mean of ``eig**n``. If initialized with a
+        callable, the callable is used directly.
         """
+        n = int(n)
+        if n < 0:
+            raise ValueError("Moment order n must be >= 0.")
 
         if n not in self._m:
-            self._m[n] = numpy.mean(self.eig ** n)
+            if self._moment_fn is not None:
+                self._m[n] = float(self._moment_fn(n))
+            else:
+                self._m[n] = float(numpy.mean(self.eig ** n))
+
         return self._m[n]
 
     # ======
@@ -136,6 +147,9 @@ class MomentsESD(object):
             Array of shape ``(n,)`` containing :math:`(a_{n,0},
             \\dots, a_{n,n-1})`.
         """
+        n = int(n)
+        if n < 0:
+            raise ValueError("Order n must be >= 0.")
 
         if n in self._a:
             return self._a[n]
@@ -161,36 +175,7 @@ class MomentsESD(object):
 
         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
 
@@ -205,8 +190,7 @@ class MomentsESD(object):
 
         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
+        # Compute R_{n,k} via convolutions
         R = numpy.zeros(n - 1, dtype=float)
         for i in range(1, n):
             conv = numpy.convolve(self._a[i], self._a[n - i])
@@ -255,13 +239,15 @@ class MomentsESD(object):
 
         For ``n == 0``, it returns ``1.0``.
         """
-
+        n = int(n)
+        if n < 0:
+            raise ValueError("Order n must be >= 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))
+        return float(numpy.dot(a_n, numpy.exp(k * t)))
 
 
 # ===========================