freealg 0.0.1__py3-none-any.whl

freealg/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: Copyright 2025, 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.
+
+from .freeform import FreeForm
+
+__all__ = ['FreeForm']
+
+from .__version__ import __version__                          # noqa: F401 E402

freealg/__version__.py

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

freealg/_chebyshev.py

@@ -0,0 +1,201 @@
+# SPDX-FileCopyrightText: Copyright 2025, 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
+from scipy.special import eval_chebyu
+
+__all__ = ['chebyshev_proj', 'chebyshev_approx', 'chebyshev_stieltjes']
+
+
+# ==============
+# chebyshev proj
+# ==============
+
+def chebyshev_proj(eig, support, K=10, reg=0.0):
+    """
+    Estimate the coefficients \\psi_k in
+
+        \\rho(x) = w(t) \\sum_{k=0}^K \\psi_k U_k(t),
+
+    where t = (2x–(\\lambda_{-} + \\lambda_{+}))/ (\\lambda_{+} - \\lambda_{-})
+    in [-1, 1] and w(t) = \\sqrt{(1 - t^2}.
+
+    Parameters
+    ----------
+
+    eig : array_like, shape (N,)
+        The raw eigenvalues x_i.
+
+    support : tuple
+        The assumed compact support of rho.
+
+    K : int
+        Highest Chebyshev‐II order.
+
+    reg : float
+        Tikhonov‐style ridge on each coefficient (defaults to 0).
+
+    Returns
+    -------
+
+    psi : ndarray, shape (K+1,)
+        The projected coefficients \\psi_k.
+    """
+
+    lam_m, lam_p = support
+
+    # Map to [–1,1] interval
+    t = (2 * eig - (lam_m + lam_p)) / (lam_p - lam_m)
+    N = eig.size
+
+    # Inner‐product norm of each U_k under w(t) = sqrt{1–t^2} is \\pi/2
+    norm = numpy.pi / 2
+
+    psi = numpy.empty(K+1)
+    for k in range(K+1):
+
+        # empirical moment M_k = (1/N) \\sum U_k(t_i)
+        M_k = numpy.sum(eval_chebyu(k, t)) / N
+
+        # Regularization
+        if k == 0:
+            # Do not penalize at k=0, as this  keeps unit mass.
+            # k=0 has unit mass, while k>0 has zero mass by orthogonality.
+            penalty = 0
+        else:
+            penalty = reg * (k / (K + 1))**2
+
+        # Add regularization on the diagonal
+        psi[k] = M_k / (norm + penalty)
+
+    return psi
+
+
+# ================
+# chebyshev approx
+# ================
+
+def chebyshev_approx(x, psi, support):
+    """
+    Given \\psi_k, evaluate the approximate density \\rho(x).
+
+    Parameters
+    ----------
+
+    x : array_like
+        Points at which to evaluate \\rho.
+
+    psi : array_like, shape (K+1,)
+        Coefficients from chebyshev_proj.
+
+    support : tuple
+        Same support used for projection.
+
+    Returns
+    -------
+
+    rho_x : ndarray, same shape as x
+        Approximated spectral density on the original x‐axis.
+    """
+
+    lam_m, lam_p = support
+
+    # Map to [–1,1] interval
+    t = (2 * numpy.asarray(x) - (lam_m + lam_p)) / (lam_p - lam_m)
+
+    # Weight sqrt{1–t^2} (clip for numerical safety)
+    w = numpy.sqrt(numpy.clip(1 - t**2, a_min=0, a_max=None))
+
+    # Summation approximation
+    U = numpy.vstack([eval_chebyu(k, t) for k in range(len(psi))]).T
+    rho_t = w * (U @ psi)
+
+    # Adjust for dt to dx transformation
+    rho_x = rho_t * (2.0 / (lam_p - lam_m))
+
+    return rho_x
+
+
+# ===================
+# chebushev stieltjes
+# ===================
+
+def chebyshev_stieltjes(z, psi, support):
+    """
+    Compute the Stieltjes transform m(z) for a Chebyshev‐II expansion
+
+    rho(x) = (2/(lam_p - lam_m)) * sqrt(1−t(x)^2) * sum_{k=0}^K psi_k U_k(t(x))
+
+    via the closed‐form
+
+      \\int_{-1}^1 U_k(t) sqrt(1−t^2)/(u - t) dt = \\pi J(u)^(k+1),
+
+    where
+
+      u = (2(z−center))/span,
+      center = (lam_p + lam_m)/2,
+      span = lam_p - lam_m,
+      J(u) = u − sqrt(u^2−1)
+
+    and then
+
+      m(z) = - (2/ span) * \\sum{k=0}^K \\psi_k * [ \\pi J(u)^(k+1) ].
+
+    Parameters
+    ----------
+
+    z : complex or array_like of complex
+        Points in the complex plane.
+
+    psi : array_like, shape (K+1,)
+        Chebyshev‐II coefficients \\psi.
+
+    support : tuple
+        The support interval of the original density.
+
+    Returns
+    -------
+
+    m_z : ndarray of complex
+        The Stieltjes transform m(z) on the same shape as z.
+    """
+
+    z = numpy.asarray(z, dtype=numpy.complex128)
+    lam_m, lam_p = support
+    span = lam_p - lam_m
+    center = 0.5 * (lam_m + lam_p)
+
+    # map z -> u in the standard [-1,1] domain
+    u = (2.0 * (z - center)) / span
+
+    # inverse-Joukowski: pick branch sqrt with +Im
+    root = numpy.sqrt(u*u - 1)
+    Jm = u - root
+    Jp = u + root
+
+    # Make sure J is Herglotz
+    J = numpy.zeros_like(Jp)
+    J = numpy.where(Jp.imag > 0, Jm, Jp)
+
+    # build powers J^(k+1) for k=0..K
+    K = len(psi) - 1
+    # shape: (..., K+1)
+    Jpow = J[..., None] ** numpy.arange(1, K+2)
+
+    # sum psi_k * J^(k+1)
+    S = numpy.sum(psi * Jpow, axis=-1)
+
+    # assemble m(z)
+    m_z = - (2.0 / span) * numpy.pi * S
+
+    return m_z

freealg/_damp.py

@@ -0,0 +1,88 @@
+# SPDX-FileCopyrightText: Copyright 2025, 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
+
+__all__ = ['jackson_damping', 'lanczos_damping', 'fejer_damping',
+           'exponential_damping', 'parzen_damping']
+
+
+# ===============
+# jackson damping
+# ===============
+
+def jackson_damping(K):
+    """
+    Compute Jackson damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    g = ((K - k + 1) * numpy.cos(numpy.pi * k / (K + 1)) +
+         numpy.sin(numpy.pi * k / (K + 1)) / numpy.tan(numpy.pi / (K + 1))) \
+        / (K + 1)
+
+    return g
+
+
+# ===============
+# lanczos damping
+# ===============
+
+def lanczos_damping(K):
+    """
+    Compute Lanczos damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    sigma = numpy.sinc(k / K)
+
+    return sigma
+
+
+# =============
+# fejer damping
+# =============
+
+def fejer_damping(K):
+    """
+    Compute Fejer damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    return 1 - k / K
+
+
+# ===================
+# exponential damping
+# ===================
+
+def exponential_damping(K, alpha=6):
+    """
+    Compute exponential damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    return numpy.exp(-alpha * (k / K)**2)
+
+
+# ==============
+# parzen damping
+# ==============
+
+def parzen_damping(K):
+    """
+    Compute Parzen damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    return 1 - numpy.abs((k - K/2) / (K/2))**3

freealg/_jacobi.py

@@ -0,0 +1,188 @@
+# SPDX-FileCopyrightText: Copyright 2025, 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
+from scipy.special import eval_jacobi, roots_jacobi
+from scipy.special import gammaln, beta as Beta
+
+__all__ = ['jacobi_proj', 'jacobi_approx', 'jacobi_stieltjes']
+
+
+# ==============
+# jacobi sq norm
+# ==============
+
+def jacobi_sq_norm(k, alpha, beta):
+    """
+    Norm of P_k
+    Special-case k = 0 to avoid gamma(0) issues when alpha + beta + 1 = 0.
+    """
+
+    if k == 0:
+        return 2.0**(alpha + beta + 1) * Beta(alpha + 1, beta + 1)
+
+    # Use logs instead to avoid overflow in gamma function.
+    lg_num = (alpha + beta + 1) * numpy.log(2.0) \
+        + gammaln(k + alpha + 1) \
+        + gammaln(k + beta + 1)
+
+    lg_den = numpy.log(2*k + alpha + beta + 1) \
+        + gammaln(k + 1) \
+        + gammaln(k + alpha + beta + 1)
+
+    return numpy.exp(lg_num - lg_den)
+
+
+# ===========
+# jacobi pro
+# ===========
+
+def jacobi_proj(eig, support, K=10, alpha=0.0, beta=0.0, reg=0.0):
+    """
+    """
+
+    lam_m, lam_p = support
+
+    # Convert to [-1, 1] interval
+    x = (2.0 * eig - (lam_p + lam_m)) / (lam_p - lam_m)
+
+    psi = numpy.empty(K + 1)
+
+    # Empirical moments and coefficients
+    for k in range(K + 1):
+        moment = numpy.mean(eval_jacobi(k, alpha, beta, x))
+        N_k = jacobi_sq_norm(k, alpha, beta)  # normalization
+
+        if k == 0:
+            # Do not penalize at k=0, as this  keeps unit mass.
+            # k=0 has unit mass, while k>0 has zero mass by orthogonality.
+            penalty = 0
+        else:
+            penalty = reg * (k / (K + 1))**2
+
+        # Add regularization on the diagonal
+        psi[k] = moment / (N_k + penalty)
+
+    return psi
+
+
+# =============
+# jacobi approx
+# =============
+
+def jacobi_approx(x, psi, support, alpha=0.0, beta=0.0):
+    """
+    Reconstruct Jacobi approximation.
+
+    Parameters
+    ----------
+
+    psi : array_like, shape (K+1, )
+        Jacobi expansion coefficients.
+
+    x : array_like
+        Points (in original eigenvalue scale) to evaluate at.
+
+    support : tuple (lam_m, lam_p)
+
+    alpha : float
+        Jacobi parameter.
+
+    beta : float
+        Jacobi parameter.
+
+    Returns
+    -------
+
+    rho : ndarray
+    """
+
+    lam_m, lam_p = support
+    t = (2 * x - (lam_p + lam_m)) / (lam_p - lam_m)
+    w = (1 - t)**alpha * (1 + t)**beta
+    P = numpy.vstack([eval_jacobi(k, alpha, beta, t) for k in range(len(psi))])
+
+    rho_t = w * (psi @ P)                            # density in t–variable
+    rho_x = rho_t * (2.0 / (lam_p - lam_m))          # back to x–variable
+
+    return rho_x
+
+
+# ================
+# jacobi stieltjes
+# ================
+
+def jacobi_stieltjes(z, psi, support, alpha=0.0, beta=0.0, n_base=40):
+    """
+    Compute m(z) = sum_k psi_k * m_k(z) where
+
+    m_k(z) = \\int w^{(alpha, beta)}(t) P_k^{(alpha, beta)}(t) / (u(z)-t) dt
+
+    Each m_k is evaluated *separately* with a Gauss–Jacobi rule sized
+    for that k.  This follows the user's request: 1 quadrature rule per P_k.
+
+    Parameters
+    ----------
+
+    z : complex or ndarray
+
+    psi : (K+1,) array_like
+
+    support : (lambda_minus, lambda_plus)
+
+    alpha, beta : float
+
+    n_base : int
+        Minimum quadrature size.  For degree-k polynomial we use
+        n_quad = max(n_base, k+1).
+
+    Returns
+    -------
+
+    m1 : ndarray  (same shape as z)
+
+    m12 : ndarray  (same shape as z)
+    """
+
+    z = numpy.asarray(z, dtype=numpy.complex128)
+    lam_minus, lam_plus = support
+    span = lam_plus - lam_minus
+    centre = 0.5 * (lam_plus + lam_minus)
+    u_z = (2.0 / span) * (z - centre)          # map z -> u
+
+    m_total = numpy.zeros_like(z, dtype=numpy.complex128)
+
+    for k, psi_k in enumerate(psi):
+        # Select quadrature size tailored to this P_k
+        n_quad = max(n_base, k + 1)
+        t_nodes, w_nodes = roots_jacobi(n_quad, alpha, beta)  # (n_quad,)
+
+        # Evaluate P_k at the quadrature nodes
+        P_k_nodes = eval_jacobi(k, alpha, beta, t_nodes)     # (n_quad,)
+
+        # Integrand values at nodes: w_nodes already include the weight
+        integrand = w_nodes * P_k_nodes                      # (n_quad,)
+
+        # Broadcast over z: shape (n_quad, ...) / ...
+        # diff = u_z[None, ...] - t_nodes[:, None]           # (n_quad, ...)
+        diff = u_z[None, ...] - t_nodes[:, None, None]       # (n_quad, Ny, Nx)
+        # m_k  = (integrand[:, None] / diff).sum(axis=0)     # shape like z
+        m_k = (integrand[:, None, None] / diff).sum(axis=0)
+
+        # Accumulate with factor 2/span
+        m_total += psi_k * (2.0 / span) * m_k
+
+    # We use a negative sign convention
+    m_total = -m_total
+
+    return m_total

freealg/_pade.py

@@ -0,0 +1,139 @@
+# SPDX-FileCopyrightText: Copyright 2025, 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
+from itertools import product
+from scipy.optimize import least_squares, differential_evolution
+
+__all__ = ['fit_pade', 'eval_pade']
+
+
+# ========
+# fit pade
+# ========
+
+def fit_pade(x, f, lam_m, lam_p, p, q, delta=1e-8, B=numpy.inf, S=numpy.inf,
+             B_default=10.0, S_factor=2.0, maxiter_de=200):
+    """
+    Fit a [p/q] rational P/Q of the form:
+      P(x) = s * prod_{i=0..p-1}(x - a_i)
+      Q(x) = prod_{j=0..q-1}(x - b_j)
+
+    Constraints:
+      a_i ∈ [lam_m, lam_p]
+      b_j ∈ (-infty, lam_m - delta] cup [lam_p + delta, infty)
+
+    Approach:
+      - Brute‐force all 2^q left/right assignments for denominator roots
+      - Global search with differential_evolution, fallback to zeros if needed
+      - Local refinement with least_squares
+
+    Returns a dict with keys:
+      's'     : optimal scale factor
+      'a'     : array of p numerator roots (in [lam_m, lam_p])
+      'b'     : array of q denominator roots (outside the interval)
+      'resid' : final residual norm
+      'signs' : tuple indicating left/right pattern for each b_j
+    """
+
+    # Determine finite bounds for DE
+    if not numpy.isfinite(B):
+        B_eff = B_default
+    else:
+        B_eff = B
+    if not numpy.isfinite(S):
+        # scale bound: S_factor * max|f| * interval width + safety
+        S_eff = S_factor * numpy.max(numpy.abs(f)) * (lam_p - lam_m) + 1.0
+        if S_eff <= 0:
+            S_eff = 1.0
+    else:
+        S_eff = S
+
+    def map_roots(signs, b):
+        """Map unconstrained b_j -> real root outside the interval."""
+        out = numpy.empty_like(b)
+        for j, (s_val, bj) in enumerate(zip(signs, b)):
+            if s_val > 0:
+                out[j] = lam_p + delta + numpy.exp(bj)
+            else:
+                out[j] = lam_m - delta - numpy.exp(bj)
+        return out
+
+    best = {'resid': numpy.inf}
+
+    # Enumerate all left/right sign patterns
+    for signs in product([-1, 1], repeat=q):
+        # Residual vector for current pattern
+        def resid_vec(z):
+            s_val = z[0]
+            a = z[1:1+p]
+            b = z[1+p:]
+            P = s_val * numpy.prod(x[:, None] - a[None, :], axis=1)
+            roots_Q = map_roots(signs, b)
+            Q = numpy.prod(x[:, None] - roots_Q[None, :], axis=1)
+            return P - f * Q
+
+        def obj(z):
+            r = resid_vec(z)
+            return r.dot(r)
+
+        # Build bounds for DE
+        bounds = []
+        bounds.append((-S_eff, S_eff))      # s
+        bounds += [(lam_m, lam_p)] * p      # a_i
+        bounds += [(-B_eff, B_eff)] * q     # b_j
+
+        # 1) Global search
+        try:
+            de = differential_evolution(obj, bounds,
+                                        maxiter=maxiter_de,
+                                        polish=False)
+            z0 = de.x
+        except ValueError:
+            # fallback: start at zeros
+            z0 = numpy.zeros(1 + p + q)
+
+        # 2) Local refinement
+        ls = least_squares(resid_vec, z0, xtol=1e-12, ftol=1e-12)
+
+        rnorm = numpy.linalg.norm(resid_vec(ls.x))
+        if rnorm < best['resid']:
+            best.update(resid=rnorm, signs=signs, x=ls.x.copy())
+
+    # Unpack best solution
+    z_best = best['x']
+    s_opt = z_best[0]
+    a_opt = z_best[1:1+p]
+    b_opt = map_roots(best['signs'], z_best[1+p:])
+
+    return {
+        's':     s_opt,
+        'a':     a_opt,
+        'b':     b_opt,
+        'resid': best['resid'],
+        'signs': best['signs'],
+    }
+
+
+# =========
+# eval pade
+# =========
+
+def eval_pade(z, s, a, b):
+    """
+    """
+
+    Pz = s * numpy.prod([z - aj for aj in a], axis=0)
+    Qz = numpy.prod([z - bj for bj in b], axis=0)
+
+    return Pz / Qz