freealg 0.6.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

freealg/_freeform/__init__.py

@@ -0,0 +1,16 @@
+# 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
+from ._linalg import eigvalsh, cond, norm, trace, slogdet
+from ._support import supp
+from ._sample import sample
+from ._density_util import kde
+
+__all__ = ['FreeForm', 'eigvalsh', 'cond', 'norm', 'trace', 'slogdet', 'supp',
+           'sample', 'kde']

freealg/{_decompress.py → _freeform/_decompress.py}

@@ -855,16 +855,6 @@ def decompress(freeform, alpha, x, roots_init=None, method='newton',
     density
     stieltjes
 
-    Notes
-    -----
-
-    Work in progress.
-
-    References
-    ----------
-
-    .. [1] tbd
-
     Examples
     --------
 

freealg/_freeform/_density_util.py

@@ -0,0 +1,243 @@
+# 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.stats import gaussian_kde
+from scipy.stats import beta
+# from statsmodels.nonparametric.kde import KDEUnivariate
+from scipy.optimize import minimize
+import matplotlib.pyplot as plt
+import texplot
+from ._plot_util import _auto_bins
+
+# Fallback to previous API
+if not hasattr(numpy, 'trapezoid'):
+    numpy.trapezoid = numpy.trapz
+
+__all__ = ['kde', 'force_density']
+
+
+# ===
+# kde
+# ===
+
+def kde(eig, xs, lam_m, lam_p, h, kernel='beta', plot=False):
+    """
+    Kernel density estimation of eigenvalues.
+
+    Parameters
+    ----------
+
+    eig : numpy.array
+        1D array of samples of size `n`.
+
+    xs : numpy.array
+        1D array of evaluation grid (must lie within ``[lam_m, lam_p]``)
+
+    lam_m : float
+        Lower end of the support endpoints  with ``lam_m < lam_p``.
+
+    lam_p : float
+        Upper end of the support endpoints  with ``lam_m < lam_p``.
+
+    h : float
+        Kernel bandwidth in rescaled units where ``0 < h < 1``.
+
+    kernel : {``'gaussian'``, ``'beta'``}, default= ``'beta'``
+        Kernel function using either Gaussian or Beta distribution.
+
+    plot : bool, default=False
+        If `True`, the KDE is plotted.
+
+    Returns
+    -------
+
+    pdf : numpy.ndarray
+        Probability distribution function with the same length as ``xs``.
+
+    See Also
+    --------
+
+    freealg.supp
+    freealg.sample
+
+    References
+    ----------
+
+    .. [1] `R-package documentation for Beta kernel
+           <https://search.r-project.org/CRAN/refmans/DELTD/html/Beta.html>`__
+
+    .. [2] Chen, S. X. (1999). Beta Kernel estimators for density functions.
+           *Computational Statistics and Data Analysis* 31 p. 131--145.
+
+    Notes
+    -----
+
+    In Beta kernel density estimation, the shape parameters :math:`a` and
+    :math:`b` of the :math:`\\mathrm{Beta}(a, b)` distribution are computed
+    for each data point :math:`u` as:
+
+    .. math::
+
+        a = (u / h) + 1.0
+        b = ((1.0 - u) / h) + 1.0
+
+    This is a standard way of using Beta kernel (see R-package documentation
+    [1]_). These equations are derived from *moment matching* method, where
+
+    .. math::
+
+        \\mathrm{Mean}(\\mathrm{Beta}(a,b)) = u
+        \\mathrm{Var}(\\mathrm{Beta}(a,b)) = (1-u) u h
+
+    Solving these two equations for :math:`a` and :math:`b` yields the
+    relations above. See [2]_ (page 134).
+    """
+
+    if kernel == 'gaussian':
+        pdf = gaussian_kde(eig, bw_method=h)(xs)
+
+        # Adaptive KDE
+        # k = KDEUnivariate(eig)
+        # k.fit(kernel='gau', bw='silverman', fft=False, weights=None,
+        #       gridsize=1024, adaptive=True)
+        # pdf = k.evaluate(xs)
+
+    elif kernel == 'beta':
+
+        span = lam_p - lam_m
+        if span <= 0:
+            raise ValueError('"lam_p" must be larger than "lam_m".')
+
+        # map samples and grid to [0, 1]
+        u = (eig - lam_m) / span
+        t = (xs - lam_m) / span
+
+        # keep only samples strictly inside (0,1)
+        if (u.min() < 0) or (u.max() > 1):
+            u = u[(u > 0) & (u < 1)]
+
+        n = u.size
+        if n == 0:
+            return numpy.zeros_like(xs, dtype=float)
+
+        # Shape parameters "a" and "b" or the kernel Beta(a, b), which is
+        # computed for each data point "u" (see notes above). These are
+        # vectorized.
+        a = (u / h) + 1.0
+        b = ((1.0 - u) / h) + 1.0
+
+        # # tiny positive number to keep shape parameters > 0
+        eps = 1e-6
+        a = numpy.clip(a, eps, None)
+        b = numpy.clip(b, eps, None)
+
+        # Beta kernel
+        pdf_matrix = beta.pdf(t[None, :], a[:, None], b[:, None])
+
+        # Average and re-normalize back to x variable
+        pdf = pdf_matrix.sum(axis=0) / (n * span)
+
+        # Exact zeros outside [lam_m, lam_p]
+        pdf[(t < 0) | (t > 1)] = 0.0
+
+    else:
+        raise NotImplementedError('"kernel" is invalid.')
+
+    if plot:
+        with texplot.theme(use_latex=False):
+            fig, ax = plt.subplots(figsize=(6, 4))
+
+            x_min = numpy.min(xs)
+            x_max = numpy.max(xs)
+            bins = numpy.linspace(x_min, x_max, _auto_bins(eig))
+            _ = ax.hist(eig, bins, density=True, color='silver',
+                        edgecolor='none', label='Samples histogram')
+            ax.plot(xs, pdf, color='black', label='KDE')
+            ax.set_xlabel(r'$x$')
+            ax.set_ylabel(r'$\\rho(x)$')
+            ax.set_xlim([xs[0], xs[-1]])
+            ax.set_ylim(bottom=0)
+            ax.set_title('Kernel Density Estimation')
+            ax.legend(fontsize='x-small')
+            plt.show()
+
+    return pdf
+
+
+# =============
+# force density
+# =============
+
+def force_density(psi0, support, density, grid, alpha=0.0, beta=0.0):
+    """
+    Starting from psi0 (raw projection), solve
+      min  0.5 ||psi - psi0||^2
+      s.t. F_pos psi >= 0           (positivity on grid)
+           psi[0] = psi0[0]         (mass)
+           f(lam_m) psi = 0         (zero at left edge)
+           f(lam_p) psi = 0         (zero at right edge)
+    """
+
+    lam_m, lam_p = support
+
+    # Objective and gradient
+    def fun(psi):
+        return 0.5 * numpy.dot(psi-psi0, psi-psi0)
+
+    def grad(psi):
+        return psi - psi0
+
+    # Constraints:
+    constraints = []
+
+    # Enforce positivity
+    constraints.append({'type': 'ineq',
+                        'fun': lambda psi: density(grid, psi)})
+
+    # Enforce unit mass
+    constraints.append({
+        'type': 'eq',
+        'fun': lambda psi: numpy.trapz(density(grid, psi), grid) - 1.0
+    })
+
+    # Enforce zero at left edge
+    if beta <= 0.0 and beta > -0.5:
+        constraints.append({
+            'type': 'eq',
+            'fun': lambda psi: density(numpy.array([lam_m]), psi)[0]
+        })
+
+    # Enforce zero at right edge
+    if alpha <= 0.0 and alpha > -0.5:
+        constraints.append({
+            'type': 'eq',
+            'fun': lambda psi: density(numpy.array([lam_p]), psi)[0]
+        })
+
+    # Solve a small quadratic programming
+    res = minimize(fun, psi0, jac=grad,
+                   constraints=constraints,
+                   # method='trust-constr',
+                   method='SLSQP',
+                   options={'maxiter': 1000, 'ftol': 1e-9, 'eps': 1e-8})
+
+    psi = res.x
+
+    # Normalize first mode to unit mass
+    x = numpy.linspace(lam_m, lam_p, 1000)
+    rho = density(x, psi)
+    mass = numpy.trapezoid(rho, x)
+    psi[0] = psi[0] / mass
+
+    return psi

freealg/{_linalg.py → _freeform/_linalg.py}

@@ -11,7 +11,7 @@
 # =======
 
 import numpy
-from ._util import compute_eig
+from .._util import compute_eig
 from .freeform import FreeForm
 
 __all__ = ['eigvalsh', 'cond', 'norm', 'trace', 'slogdet']

freealg/{_pade.py → _freeform/_pade.py}

@@ -13,7 +13,6 @@
 
 import numpy
 from numpy.linalg import lstsq
-from itertools import product
 from scipy.optimize import least_squares, differential_evolution
 
 __all__ = ['fit_pade', 'eval_pade']

freealg/{freeform.py → _freeform/freeform.py}

@@ -13,7 +13,8 @@
 
 import numpy
 from functools import partial
-from ._util import resolve_complex_dtype, compute_eig, kde, force_density
+from .._util import resolve_complex_dtype, compute_eig
+from ._density_util import kde, force_density
 from ._jacobi import jacobi_sample_proj, jacobi_kernel_proj, jacobi_density, \
     jacobi_stieltjes
 from ._chebyshev import chebyshev_sample_proj, chebyshev_kernel_proj, \
@@ -74,16 +75,6 @@ class FreeForm(object):
         Parameters for the :func:`supp` function can also be prescribed
         here when ``support=None``.
 
-    Notes
-    -----
-
-    TBD
-
-    References
-    ----------
-
-    .. [1] Reference.
-
     Attributes
     ----------
 
@@ -749,16 +740,6 @@ class FreeForm(object):
         density
         hilbert
 
-        Notes
-        -----
-
-        Notes.
-
-        References
-        ----------
-
-        .. [1] tbd
-
         Examples
         --------
 
@@ -973,16 +954,6 @@ class FreeForm(object):
         density
         stieltjes
 
-        Notes
-        -----
-
-        Work in progress.
-
-        References
-        ----------
-
-        .. [1] tbd
-
         Examples
         --------
 

freealg/_geometric_form/__init__.py

@@ -0,0 +1,13 @@
+# 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.
+
+from .geometric_form import GeometricForm
+# from ._elliptic_functions import ellipj
+# from ._continuation_genus1 import mobius_z
+
+__all__ = ['GeometricForm']

freealg/_geometric_form/_continuation_genus0.py

@@ -0,0 +1,175 @@
+# 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
+
+__all__ = ['joukowski_z', 'joukowski_w', 'fit_pade', 'eval_pade',
+           'generate_pade']
+
+
+# ===========
+# joukowski z
+# ===========
+
+def joukowski_z(w, a, b):
+
+    c = 0.5 * (a + b)
+    d = 0.5 * (b - a)
+    z = c + 0.5 * d * (w + 1.0 / w)
+
+    return z
+
+
+# ===========
+# joukowski w
+# ===========
+
+def joukowski_w(z, a, b):
+
+    c = 0.5 * (a + b)
+    d = 0.5 * (b - a)
+    xi = (z - c) / d
+    s = numpy.sqrt(xi * xi - 1.0)
+
+    # Stabilize sqrt branch: make s have same sign as xi (helps continuity)
+    s = numpy.where(numpy.real(xi) < 0.0, -s, s)
+
+    w1 = xi + s
+    w2 = xi - s
+    w = numpy.where(numpy.abs(w1) >= 1.0, w1, w2)
+
+    return w
+
+
+# ========
+# fit pade
+# ========
+
+def fit_pade(w, m1, deg_p=12, deg_q=12, ridge_lambda=0.0):
+    """
+    Fit m1 on w-plane using Pade rational approximation.
+    """
+
+    n_samples = m1.size
+
+    wp = numpy.ones((n_samples, deg_p + 1), dtype=complex)
+    for k in range(1, deg_p + 1):
+        wp[:, k] = wp[:, k - 1] * w
+
+    wq = numpy.ones((n_samples, deg_q + 1), dtype=complex)
+    for k in range(1, deg_q + 1):
+        wq[:, k] = wq[:, k - 1] * w
+
+    A = numpy.hstack([wp, -m1[:, None] * wq[:, 1:]])
+    bvec = m1
+
+    # Scale columns for better conditioning on LS
+    s = numpy.linalg.norm(A, axis=0)
+    s[s == 0] = 1.0
+    As = A / s[None, :]
+
+    if ridge_lambda is None:
+        ridge_lambda = 0.0
+
+    if ridge_lambda > 0.0:
+        # Scale ridge by average diagonal magnitude of AhA
+        # Since columns of As have unit norm, this is typically ~1.
+        alpha = ridge_lambda
+
+        # Solving augmented least square
+        n_coef = As.shape[1]
+        A_aug = numpy.vstack([As, numpy.sqrt(alpha) * numpy.eye(
+            n_coef, dtype=complex)])
+        b_aug = numpy.concatenate([bvec, numpy.zeros(n_coef, dtype=complex)])
+
+        coef, _, _, _ = numpy.linalg.lstsq(A_aug, b_aug, rcond=None)
+    else:
+        coef, _, _, _ = numpy.linalg.lstsq(As, bvec, rcond=None)
+
+    coef = coef / s
+
+    p = coef[:deg_p + 1]
+    q = numpy.zeros(deg_q + 1, dtype=complex)
+    q[0] = 1.0
+    q[1:] = coef[deg_p + 1:]
+
+    return p, q
+
+
+# =========
+# eval pade
+# =========
+
+def eval_pade(w, p, q):
+
+    num = numpy.zeros_like(w, dtype=complex)
+    den = numpy.zeros_like(w, dtype=complex)
+
+    for k in range(len(p) - 1, -1, -1):
+        num = num * w + p[k]
+
+    for k in range(len(q) - 1, -1, -1):
+        den = den * w + q[k]
+
+    return num / den
+
+
+# =============
+# generate pade
+# =============
+
+def generate_pade(m1_fn, a, b, deg_p=12, deg_q=12, n_samples=4096, r=1.2,
+                  n_r=1, r_min=None, ridge_lambda=0.0):
+
+    if r_min is None:
+        r_min = 1.0 + 0.05 * (r - 1.0) if r > 1.0 else 1.0
+
+    if n_r is None or n_r < 1:
+        n_r = 1
+
+    if n_samples % 2 != 0:
+        raise ValueError('n_samples should be even.')
+
+    if n_r == 1:
+        rs = numpy.array([r], dtype=float)
+    else:
+        rs = numpy.linspace(r_min, r, n_r)
+
+    W_list = []
+    M_list = []
+
+    n_half = n_samples // 2
+
+    for r_i in rs:
+
+        # Generate sample points along theta
+        theta = numpy.pi * (numpy.arange(n_half) + 0.5) / n_half
+        w = r_i * numpy.exp(1j * theta)
+        z = joukowski_z(w, a, b)
+        m1 = m1_fn(z)
+
+        W_list.append(w)
+        M_list.append(m1)
+
+        # Add conjugate points which enforces Schwarz reflection
+        W_list.append(numpy.conjugate(w))
+        M_list.append(numpy.conjugate(m1))
+
+    w_all = numpy.concatenate(W_list)
+    m1_all = numpy.concatenate(M_list)
+
+    # Fit on the sample data from m1
+    p, q = fit_pade(w_all, m1_all, deg_p=deg_p, deg_q=deg_q,
+                    ridge_lambda=ridge_lambda)
+
+    return p, q