freealg 0.5.4__py3-none-any.whl → 0.6.1__py3-none-any.whl

freealg/_sample.py

@@ -15,7 +15,7 @@ from scipy.integrate import cumulative_trapezoid
 from scipy.interpolate import PchipInterpolator
 from scipy.stats import qmc
 
-__all__ = ['qmc_sample']
+__all__ = ['sample']
 
 
 # =============
@@ -32,60 +32,75 @@ def _quantile_func(x, rho, clamp=1e-4, eps=1e-8):
     rho_clamp[rho < clamp] = eps
     cdf = cumulative_trapezoid(rho_clamp, x, initial=0)
     cdf /= cdf[-1]
+    cdf_inv = PchipInterpolator(cdf, x, extrapolate=False)
 
-    return PchipInterpolator(cdf, x, extrapolate=False)
+    return cdf_inv
 
 
-# ==========
-# qmc sample
-# ==========
+# ======
+# sample
+# ======
 
-def qmc_sample(x, rho, num_pts, seed=None):
+def sample(x, rho, num_pts, method='qmc', seed=None):
     """
-    Low-discrepancy sampling from a univariate density estimate using
-    Quasi-Monte Carlo.
+    Low-discrepancy sampling from density estimate.
 
     Parameters
     ----------
 
-    x : numpy.array, shape (n,)
-        Sorted abscissae at which the density has been evaluated.
+    x : numpy.array
+        Sorted abscissae at which the density has been evaluated. Shape `(n,)`.
 
-    rho : numpy.array, shape (n,)
+    rho : numpy.array
         Density values corresponding to `x`. Must be non-negative and define
         a valid probability density (i.e., integrate to 1 over the support).
+        Shape `(n,)`.
 
     num_pts : int
         Number of sample points to generate from the density estimate.
 
+    method : {``'mc'``, ``'qmc'``}, default= ``'qmc'``
+        Method of drawing samples from uniform distribution:
+
+        * ``'mc'``: Monte Carlo
+        * ``'qmc'``: Quasi Monte Carlo
+
     seed : int, default=None
         Seed for random number generator
 
     Returns
     -------
+
     samples : numpy.array, shape (num_pts,)
         Samples drawn from the estimated density using a one-dimensional Halton
         sequence mapped through the estimated quantile function.
 
     See Also
     --------
-    scipy.stats.qmc.Halton
-        Underlying Quasi-Monte Carlo engine used for generating low-discrepancy
-        points.
+
+    freealg.supp
+    freealg.kde
+
+    Notes
+    -----
+
+    The underlying Quasi-Monte Carlo engine uses ``scipy.stats.qmc.Halton``
+    function for generating low-discrepancy points.
 
     Examples
     --------
 
     .. code-block:: python
+        :emphasize-lines: 8
 
         >>> import numpy
-        >>> from freealg import qmc_sample
+        >>> from freealg import sample
 
         >>> # density of Beta(3,1) on [0,1]
         >>> x = numpy.linspace(0, 1, 200)
         >>> rho = 3 * x**2
 
-        >>> samples = qmc_sample(x, rho, num_pts=1000)
+        >>> samples = sample(x, rho, num_pts=1000, method='qmc')
         >>> assert samples.shape == (1000,)
 
         >>> # Empirical mean should be close to 3/4
@@ -94,8 +109,17 @@ def qmc_sample(x, rho, num_pts, seed=None):
 
     rng = numpy.random.default_rng(seed)
     quantile = _quantile_func(x, rho)
-    engine = qmc.Halton(d=1, rng=rng)
-    u = engine.random(num_pts)
+
+    # Draw from uniform distribution
+    if method == 'mc':
+        u = rng.random(num_pts)
+    elif method == 'qmc':
+        engine = qmc.Halton(d=1, rng=rng)
+        u = engine.random(num_pts)
+    else:
+        raise NotImplementedError('"method" is invalid.')
+
+    # Draw from distribution by mapping from inverse CDF
     samples = quantile(u)
 
     return samples.ravel()

freealg/_series.py

@@ -183,13 +183,13 @@ def wynn_rho(Sn, beta=0.0):
     -------
 
     S : numpy.ndarray
-        A 1D array of shape ``(d,)`` giving the rho‑accelerated estimate
+        A 1D array of shape ``(d,)`` giving the rho-accelerated estimate
         of the series limit for each component.
 
     Notes
     -----
 
-    Let ``S_n`` be the *n*‑th partial sum of the (possibly divergent)
+    Let ``S_n`` be the *n*-th partial sum of the (possibly divergent)
     sequence.  Wynn's rho algorithm builds a triangular table
     ``rho[k, n]`` (row *k*, column *n*) as follows:
 
@@ -200,7 +200,7 @@ def wynn_rho(Sn, beta=0.0):
                     (n + beta + k - 1) / (rho[k-1, n+1] - rho[k-1, n])
 
     Only even rows (k even) provide improved approximants.  As with
-    ``wynn_epsilon``, we apply the scalar recursion component‑wise so that a
+    ``wynn_epsilon``, we apply the scalar recursion component-wise so that a
     slowly converging component does not stall the others.
     """
 
@@ -255,7 +255,7 @@ def wynn_rho(Sn, beta=0.0):
 
 def levin_u(Sn, omega=None, beta=0.0):
     """
-    Levin u‑transform (vector form).
+    Levin u-transform (vector form).
 
     Parameters
     ----------
@@ -339,13 +339,13 @@ def weniger_delta(Sn):
     -------
 
     S : numpy.ndarray
-        Array of shape (d,) giving the Δ²‑accelerated limit estimate for each
-        component.
+        Array of shape (d,) giving the delta2 accelerated limit estimate for
+        each component.
     """
 
     N, d = Sn.shape
 
-    # Need at least three partial sums to form Δ²
+    # Need at least three partial sums to form delta2
     if N < 3:
         return Sn[-1, :].copy()
 
@@ -384,14 +384,14 @@ def brezinski_theta(Sn):
     ----------
 
     Sn : numpy.ndarray
-        A 2‑D array of the size ``(N, d)``, where `N` is the number of partial
+        A 2-D array of the size ``(N, d)``, where `N` is the number of partial
         sums and `d` is the vector size.
 
     Returns
     -------
 
     S : numpy.ndarray
-        A 1‑D array of the size ``(d,)`` – the theta‑accelerated estimate of
+        A 1-D array of the size ``(d,)``. The theta-accelerated estimate of
         the series limit in each vector component.
     """
 

freealg/_support.py

@@ -14,7 +14,7 @@ import numpy
 import numba
 from scipy.stats import gaussian_kde
 
-__all__ = ['support_from_density', 'detect_support']
+__all__ = ['support_from_density', 'supp']
 
 
 # ====================
@@ -34,26 +34,26 @@ def support_from_density(dx, density):
     n = density.shape[0]
     target = 1.0 / dx
 
-    # 1) compute total_sum once
+    # compute total_sum once
     total_sum = 0.0
     for t in range(n):
         total_sum += density[t]
 
-    # 2) set up our “best‐so‐far” trackers
+    # set up our "best-so-far" trackers
     large = 1e300
     best_nonneg_sum = large
     best_nonneg_idx = -1
     best_nonpos_sum = -large
     best_nonpos_idx = -1
 
-    # 3) seed with first element (i.e. prefix_sum for k=1)
+    # seed with first element (i.e. prefix_sum for k=1)
     prefix_sum = density[0]
     if prefix_sum >= 0.0:
         best_nonneg_sum, best_nonneg_idx = prefix_sum, 1
     else:
         best_nonpos_sum, best_nonpos_idx = prefix_sum, 1
 
-    # 4) sweep j from 2...n–1, updating prefix_sum on the fly
+    # sweep j from 2, ..., n-1, updating prefix_sum on the fly
     optimal_i, optimal_j = 1, 2
     minimal_cost = large
 
@@ -88,7 +88,7 @@ def support_from_density(dx, density):
             minimal_cost = total_cost
             optimal_i, optimal_j = i_cand, j
 
-        # update our prefix‐sum trackers
+        # update our prefix-sum trackers
         if prefix_sum >= 0.0:
             if prefix_sum < best_nonneg_sum:
                 best_nonneg_sum, best_nonneg_idx = prefix_sum, j
@@ -99,36 +99,34 @@ def support_from_density(dx, density):
     return optimal_i, optimal_j
 
 
-# ==============
-# detect support
-# ==============
+# ====
+# supp
+# ====
 
-def detect_support(eigs, method='asymp', k=None, p=0.001, **kwargs):
+def supp(eigs, method='asymp', k=None, p=0.001):
     """
     Estimates the support of the eigenvalue density.
 
     Parameters
     ----------
 
-    method : {``'range'``, ``'asymp'``, ``'jackknife'``, ``'regression'``,
-                ``'interior'``, ``'interior_smooth'``}, \
-            default= ``'asymp'``
+    method : {``'range'``, ``'asymp'``, ``'jackknife'``, ``'regression'``, \
+            ``'interior'``, ``'interior_smooth'``}, default= ``'asymp'``
         The method of support estimation:
 
         * ``'range'``: no estimation; the support is the range of the
-            eigenvalues.
+          eigenvalues.
         * ``'asymp'``: assume the relative error in the min/max estimator is
-            1/n.
-        * ``'jackknife'``: estimates the support using Quenouille's [1]
-            jackknife estimator. Fast and simple, more accurate than the
-            range.
+          :math:`1/n`.
+        * ``'jackknife'``: estimates the support using Quenouille's [1]_
+          jackknife estimator. Fast and simple, more accurate than the range.
         * ``'regression'``: estimates the support by performing a regression
-            under the assumption that the edge behavior is of square-root
-            type. Often most accurate.
+          under the assumption that the edge behavior is of square-root type.
+          Often most accurate.
         * ``'interior'``: estimates a support assuming the range overestimates;
-            uses quantiles (p, 1-p).
+          uses quantiles :math:`(p, 1-p)`.
         * ``'interior_smooth'``: same as ``'interior'`` but using kernel
-            density estimation, from [2]_.
+          density estimation, from [2]_.
 
     k : int, default = None
         Number of extreme order statistics to use for ``method='regression'``.
@@ -140,6 +138,21 @@ def detect_support(eigs, method='asymp', k=None, p=0.001, **kwargs):
         This value should be between 0 and 1, ideally a small number close to
         zero.
 
+    Returns
+    -------
+
+    lam_m : float
+        Lower end of support interval :math:`[\\lambda_{-}, \\lambda_{+}]`.
+
+    lam_p : float
+        Upper end of support interval :math:`[\\lambda_{-}, \\lambda_{+}]`.
+
+    See Also
+    --------
+
+    freealg.sample
+    freealg.kde
+
     References
     ----------
 

freealg/_util.py

@@ -13,14 +13,60 @@
 
 import numpy
 import scipy
+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__ = ['compute_eig', 'beta_kde', 'force_density']
+__all__ = ['resolve_complex_dtype', 'compute_eig', 'kde', 'force_density']
+
+
+# =====================
+# resolve complex dtype
+# =====================
+
+def resolve_complex_dtype(dtype):
+    """
+    Convert a user-supplied dtype name to a NumPy dtype object and fall back
+    safely if the requested precision is unavailable.
+    """
+
+    # Normalise the string
+    dtype = str(dtype).lower()
+
+    if not isinstance(numpy.dtype(dtype), numpy.dtype):
+        raise ValueError(f'{dtype} is not a recognized numpy dtype.')
+    elif not numpy.issubdtype(numpy.dtype(dtype), numpy.complexfloating):
+        raise ValueError(f'{dtype} is not a complex dtype.')
+
+    if dtype in {'complex128', '128'}:
+        cdtype = numpy.complex128
+
+    elif dtype in ['complex256', '256', 'longcomplex', 'clongcomplex']:
+
+        complex256_found = False
+        for name in ['complex256', 'clongcomplex']:
+            if hasattr(numpy, name):
+                cdtype = getattr(numpy, name)
+                complex256_found = True
+
+        if not complex256_found:
+            raise RuntimeWarning(
+                'NumPy on this platform has no 256-bit complex type. ' +
+                'Falling back to complex128.')
+            cdtype = numpy.complex128
+
+    else:
+        raise ValueError('Unsupported dtype.')
+
+    return cdtype
 
 
 # ===========
@@ -37,50 +83,107 @@ def compute_eig(A, lower=False):
     return eig
 
 
-# ========
-# beta kde
-# ========
+# ===
+# kde
+# ===
 
-def beta_kde(eig, xs, lam_m, lam_p, h):
+def kde(eig, xs, lam_m, lam_p, h, kernel='beta', plot=False):
     """
-    Beta-kernel KDE with automatic guards against NaNs.
+    Kernel density estimation of eigenvalues.
 
     Parameters
     ----------
-    eig    : (n,) 1-D array of samples
-    xs     : evaluation grid (must lie within [lam_m, lam_p])
-    lam_m, lam_p : float, support endpoints  (lam_m < lam_p)
-    h      : bandwidth in rescaled units (0 < h < 1)
 
-    Returns
-    -------
-    pdf    : ndarray  same length as xs
-    """
+    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``.
 
-    span = lam_p - lam_m
-    if span <= 0:
-        raise ValueError("lam_p must be larger than lam_m")
+    lam_p : float
+        Upper end of the support endpoints  with ``lam_m < lam_p``.
 
-    # map samples and grid to [0, 1]
-    u = (eig - lam_m) / span
-    t = (xs - lam_m) / span
+    h : float
+        Kernel bandwidth in rescaled units where ``0 < h < 1``.
 
-    if u.min() < 0 or u.max() > 1:
-        mask = (u > 0) & (u < 1)
-        u = u[mask]
+    kernel : {``'gaussian'``, ``'beta'``}, default= ``'beta'``
+        Kernel function using either Gaussian or Beta distribution.
 
-    pdf = numpy.zeros_like(xs, dtype=float)
-    n = len(u)
+    plot : bool, default=False
+        If `True`, the KDE is plotted.
 
-    # tiny positive number to keep shape parameters >0
-    eps = 1e-6
-    for ui in u:
-        a = max(ui / h + 1.0, eps)
-        b = max((1.0 - ui) / h + 1.0, eps)
-        pdf += beta.pdf(t, a, b)
+    Returns
+    -------
+
+    pdf : numpy.ndarray
+        Probability distribution function with the same length as ``xs``.
+
+    See Also
+    --------
+
+    freealg.supp
+    freealg.sample
+    """
 
-    pdf /= n * span                        # renormalise
-    pdf[(t < 0) | (t > 1)] = 0.0           # exact zeros outside
+    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
+
+        if u.min() < 0 or u.max() > 1:
+            mask = (u > 0) & (u < 1)
+            u = u[mask]
+
+        pdf = numpy.zeros_like(xs, dtype=float)
+        n = len(u)
+
+        # tiny positive number to keep shape parameters > 0
+        eps = 1e-6
+        for ui in u:
+            a = max(ui / h + 1.0, eps)
+            b = max((1.0 - ui) / h + 1.0, eps)
+            pdf += beta.pdf(t, a, b)
+
+        pdf /= n * span                        # renormalise
+        pdf[(t < 0) | (t > 1)] = 0.0           # exact zeros outside
+
+    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
 
@@ -95,8 +198,8 @@ def force_density(psi0, support, density, grid, alpha=0.0, beta=0.0):
       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)
+           f(lam_m) psi = 0         (zero at left edge)
+           f(lam_p) psi = 0         (zero at right edge)
     """
 
     lam_m, lam_p = support

freealg/distributions/_kesten_mckay.py

@@ -78,7 +78,7 @@ class KestenMcKay(object):
     ----------
 
     .. [1] Kesten, H. (1959). Symmetric random walks on groups. Transactions of
-           the American Mathematical Society, 92(2), 336–354.
+           the American Mathematical Society, 92(2), 336-354.
 
     .. [2] McKay, B. D. (1981). The expected eigenvalue distribution of a large
            regular graph. Linear Algebra and its Applications, 40, 203-216

freealg/distributions/_marchenko_pastur.py

@@ -290,7 +290,7 @@ class MarchenkoPastur(object):
             m1 = (-B + sqrtD) / (2 * A)
             m2 = (-B - sqrtD) / (2 * A)
 
-            # pick correct branch only for non‑masked entries
+            # pick correct branch only for non-masked entries
             upper = z[not_mask].imag >= 0
             branch = numpy.empty_like(m1)
             branch[upper] = numpy.where(sign*m1[upper].imag > 0, m1[upper],

freealg/distributions/_meixner.py

@@ -83,7 +83,7 @@ class Meixner(object):
 
     .. [1] Saitoh, N. & Yosnida, M. (2001). The infinite divisibility and
            orthogonal polynomials with a constant recursion formula in free
-           probability theory. Probab. Math. Statist., 21, 159–170.
+           probability theory. Probab. Math. Statist., 21, 159-170.
 
     Examples
     --------
@@ -315,7 +315,7 @@ class Meixner(object):
         m1 = (-B + sqrtD) / (2 * A)
         m2 = (-B - sqrtD) / (2 * A)
 
-        # pick correct branch only for non‑masked entries
+        # pick correct branch only for non-masked entries
         upper = z.imag >= 0
         branch = numpy.empty_like(m1)
         branch[upper] = numpy.where(

freealg/distributions/_wachter.py

@@ -290,7 +290,7 @@ class Wachter(object):
         m1 = (-B + sqrtD) / (2 * A)
         m2 = (-B - sqrtD) / (2 * A)
 
-        # pick correct branch only for non‑masked entries
+        # pick correct branch only for non-masked entries
         upper = z.imag >= 0
         branch = numpy.empty_like(m1)
         branch[upper] = numpy.where(sign*m1[upper].imag > 0, m1[upper],