freealg 0.0.3__py3-none-any.whl → 0.1.0__py3-none-any.whl

freealg/distributions/wigner.py

@@ -0,0 +1,552 @@
+# 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
+import networkx as nx
+from scipy.interpolate import interp1d
+from .._plot_util import plot_density, plot_hilbert, plot_stieltjes, \
+    plot_stieltjes_on_disk, plot_samples
+
+try:
+    from scipy.integrate import cumtrapz
+except ImportError:
+    from scipy.integrate import cumulative_trapezoid as cumtrapz
+
+__all__ = ['Wigner']
+
+
+# ======
+# Wigner
+# ======
+
+class Wigner(object):
+    """
+    Wigner semicircle distribution.
+
+    Methods
+    -------
+
+    density
+        Spectral density of distribution.
+
+    hilbert
+        Hilbert transform of distribution.
+
+    stieltjes
+        Stieltjes transform of distribution.
+
+    sample
+        Sample from distribution.
+
+    matrix
+        Generate matrix with its empirical spectral density of distribution
+
+    Notes
+    -----
+
+    The Marchenko-Pastur distribution has the absolutely-continuous density
+
+    .. math::
+
+        \\mathrm{d} \\rho(x) = \\frac{1}{2 \\pi}
+        \\sqrt{(4 - x^2}
+        \\mathbf{1}_{x \\in [\\lambda_{-}, \\lambda_{+}]} \\mathrm{d}{x}
+
+    with :math:`\\lambda_{\\pm} = \\pm 2` being the edges of the support
+
+    References
+    ----------
+
+    .. [1] Wigner, E. P. (1955). Characteristic vectors of bordered matrices
+           with infinite dimensions. Annals of Mathematics, 62(3), 548-564.421
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        >>> from freealg.distributions import Wigner
+        >>> wg = Wigner()
+    """
+
+    # ====
+    # init
+    # ====
+
+    def __init__(self):
+        """
+        Initialization.
+        """
+
+        self.lam_p = 2.0
+        self.lam_m = -2.0
+        self.support = (self.lam_m, self.lam_p)
+
+    # =======
+    # density
+    # =======
+
+    def density(self, x=None, plot=False, latex=False, save=False):
+        """
+        Density of distribution.
+
+        Parameters
+        ----------
+
+        x : numpy.array, default=None
+            The locations where density is evaluated at. If `None`, an interval
+            slightly larger than the support interval of the spectral density
+            is used.
+
+        rho : numpy.array, default=None
+            Density. If `None`, it will be computed.
+
+        plot : bool, default=False
+            If `True`, density is plotted.
+
+        latex : bool, default=False
+            If `True`, the plot is rendered using LaTeX. This option is
+            relevant only if ``plot=True``.
+
+        save : bool, default=False
+            If not `False`, the plot is saved. If a string is given, it is
+            assumed to the save filename (with the file extension). This option
+            is relevant only if ``plot=True``.
+
+        Returns
+        -------
+
+        rho : numpy.array
+            Density.
+
+        Examples
+        --------
+
+        .. code-block::python
+
+            >>> from freealg.distributions import Wigner
+            >>> wg = Wigner()
+            >>> rho = wg.density(plot=True)
+
+        .. image:: ../_static/images/plots/wg_density.png
+            :align: center
+            :class: custom-dark
+        """
+
+        # Create x if not given
+        if x is None:
+            radius = 0.5 * (self.lam_p - self.lam_m)
+            center = 0.5 * (self.lam_p + self.lam_m)
+            scale = 1.25
+            x_min = numpy.floor(center - radius * scale)
+            x_max = numpy.ceil(center + radius * scale)
+            x = numpy.linspace(x_min, x_max, 500)
+
+        rho = numpy.zeros_like(x)
+        mask = numpy.logical_and(x >= self.lam_m, x <= self.lam_p)
+
+        rho[mask] = (1.0 / (2.0 * numpy.pi)) * \
+            numpy.sqrt(4.0 - x[mask]**2)
+
+        if plot:
+            plot_density(x, rho, label='', latex=latex, save=save)
+
+        return rho
+
+    # =======
+    # hilbert
+    # =======
+
+    def hilbert(self, x=None, plot=False, latex=False, save=False):
+        """
+        Hilbert transform of the distribution.
+
+        Parameters
+        ----------
+
+        x : numpy.array, default=None
+            The locations where Hilbert transform is evaluated at. If `None`,
+            an interval slightly larger than the support interval of the
+            spectral density is used.
+
+        plot : bool, default=False
+            If `True`, Hilbert transform is plotted.
+
+        latex : bool, default=False
+            If `True`, the plot is rendered using LaTeX. This option is
+            relevant only if ``plot=True``.
+
+        save : bool, default=False
+            If not `False`, the plot is saved. If a string is given, it is
+            assumed to the save filename (with the file extension). This option
+            is relevant only if ``plot=True``.
+
+        Returns
+        -------
+
+        hilb : numpy.array
+            Hilbert transform.
+
+        Examples
+        --------
+
+        .. code-block::python
+
+            >>> from freealg.distributions import Wigner
+            >>> wg = Wigner()
+            >>> hilb = wg.hilbert(plot=True)
+
+        .. image:: ../_static/images/plots/wg_hilbert.png
+            :align: center
+            :class: custom-dark
+        """
+
+        # Create x if not given
+        if x is None:
+            radius = 0.5 * (self.lam_p - self.lam_m)
+            center = 0.5 * (self.lam_p + self.lam_m)
+            scale = 1.25
+            x_min = numpy.floor(center - radius * scale)
+            x_max = numpy.ceil(center + radius * scale)
+            x = numpy.linspace(x_min, x_max, 500)
+
+        def _P(x):
+            return x
+
+        def _Q(x):
+            return 1.0
+
+        P = _P(x)
+        Q = _Q(x)
+        Delta2 = P**2 - 4.0 * Q
+        Delta = numpy.sqrt(numpy.maximum(Delta2, 0))
+        sign = numpy.sign(P)
+        hilb = (P - sign * Delta) / (2.0 * Q)
+
+        # using negative sign convention
+        hilb = -hilb
+
+        if plot:
+            plot_hilbert(x, hilb, support=self.support, latex=latex, save=save)
+
+        return hilb
+
+    # =======================
+    # m mp numeric vectorized
+    # =======================
+
+    def _m_mp_numeric_vectorized(self, z, alt_branch=False, tol=1e-8):
+        """
+        Stieltjes transform (principal or secondary branch)
+        for Marchenko–Pastur distribution on upper half-plane.
+        """
+
+        m = numpy.empty_like(z, dtype=complex)
+
+        # Use quadratic form
+        sign = -1 if alt_branch else 1
+        A = 1.0
+        B = z
+        D = B**2 - 4 * A
+        sqrtD = numpy.sqrt(D)
+        m1 = (-B + sqrtD) / (2 * A)
+        m2 = (-B - sqrtD) / (2 * A)
+
+        # pick correct branch
+        upper = z.imag >= 0
+        branch = numpy.empty_like(m1)
+        branch[upper] = numpy.where(sign*m1[upper].imag > 0, m1[upper],
+                                    m2[upper])
+        branch[~upper] = numpy.where(sign*m1[~upper].imag < 0, m1[~upper],
+                                     m2[~upper])
+        m = branch
+
+        return m
+
+    # ============
+    # m mp reflect
+    # ============
+
+    def _m_mp_reflect(self, z, alt_branch=False):
+        """
+        Analytic continuation using Schwarz reflection.
+        """
+
+        mask_p = z.imag >= 0.0
+        mask_n = z.imag < 0.0
+
+        m = numpy.zeros_like(z)
+
+        f = self._m_mp_numeric_vectorized
+        m[mask_p] = f(z[mask_p], alt_branch=False)
+        m[mask_n] = f(z[mask_n], alt_branch=alt_branch)
+
+        return m
+
+    # =========
+    # stieltjes
+    # =========
+
+    def stieltjes(self, x=None, y=None, plot=False, on_disk=False, latex=False,
+                  save=False):
+        """
+        Stieltjes transform of distribution.
+
+        Parameters
+        ----------
+
+        x : numpy.array, default=None
+            The x axis of the grid where the Stieltjes transform is evaluated.
+            If `None`, an interval slightly larger than the support interval of
+            the spectral density is used.
+
+        y : numpy.array, default=None
+            The y axis of the grid where the Stieltjes transform is evaluated.
+            If `None`, a grid on the interval ``[-1, 1]`` is used.
+
+        plot : bool, default=False
+            If `True`, Stieltjes transform is plotted.
+
+        on_disk : bool, default=False
+            If `True`, the Stieltjes transform is mapped on unit disk. This
+            option relevant only if ``plot=True``.
+
+        latex : bool, default=False
+            If `True`, the plot is rendered using LaTeX. This option is
+            relevant only if ``plot=True``.
+
+        save : bool, default=False
+            If not `False`, the plot is saved. If a string is given, it is
+            assumed to the save filename (with the file extension). This option
+            is relevant only if ``plot=True``.
+
+        Returns
+        -------
+
+        m1 : numpy.array
+            Stieltjes transform on principal branch.
+
+        m12 : numpy.array
+            Stieltjes transform on secondary branch.
+
+        Examples
+        --------
+
+        .. code-block:: python
+
+            >>> from freealg.distributions import Wigner
+            >>> wg = Wigner()
+            >>> m1, m2 = wg.stieltjes(plot=True)
+
+        .. image:: ../_static/images/plots/wg_stieltjes.png
+            :align: center
+            :class: custom-dark
+
+        Plot on unit disk using Cayley transform:
+
+        .. code-block:: python
+
+            >>> m1, m2 = mp.stieltjes(plot=True, on_disk=True)
+
+        .. image:: ../_static/images/plots/wg_stieltjes_disk.png
+            :align: center
+            :class: custom-dark
+        """
+
+        if (plot is True) and (on_disk is True):
+            n_r = 1000
+            n_t = 1000
+            r_min, r_max = 0, 2.5
+            t_min, t_max = 0, 2.0 * numpy.pi
+            r = numpy.linspace(r_min, r_max, n_r)
+            t = numpy.linspace(t_min, t_max, n_t + 1)[:-1]
+            grid_r, grid_t = numpy.meshgrid(r, t)
+
+            grid_x_D = grid_r * numpy.cos(grid_t)
+            grid_y_D = grid_r * numpy.sin(grid_t)
+            zeta = grid_x_D + 1j * grid_y_D
+
+            # Cayley transform mapping zeta on D to z on H
+            z_H = 1j * (1 + zeta) / (1 - zeta)
+
+            m1_D = self._m_mp_reflect(z_H, alt_branch=False)
+            m2_D = self._m_mp_reflect(z_H, alt_branch=True)
+
+            plot_stieltjes_on_disk(r, t, m1_D, m2_D, support=self.support,
+                                   latex=latex, save=save)
+
+            return m1_D, m2_D
+
+        # Create x if not given
+        if x is None:
+            radius = 0.5 * (self.lam_p - self.lam_m)
+            center = 0.5 * (self.lam_p + self.lam_m)
+            scale = 2.0
+            x_min = numpy.floor(2.0 * (center - 2.0 * radius * scale)) / 2.0
+            x_max = numpy.ceil(2.0 * (center + 2.0 * radius * scale)) / 2.0
+            x = numpy.linspace(x_min, x_max, 500)
+
+        # Create y if not given
+        if y is None:
+            y = numpy.linspace(-1, 1, 400)
+
+        x_grid, y_grid = numpy.meshgrid(x, y)
+        z = x_grid + 1j * y_grid              # shape (Ny, Nx)
+
+        m1 = self._m_mp_reflect(z, alt_branch=False)
+        m2 = self._m_mp_reflect(z, alt_branch=True)
+
+        if plot:
+            plot_stieltjes(x, y, m1, m2, support=self.support, latex=latex,
+                           save=save)
+
+        return m1, m2
+
+    # ======
+    # sample
+    # ======
+
+    def sample(self, size, x_min=None, x_max=None, plot=False, latex=False,
+               save=False):
+        """
+        Sample from distribution.
+
+        Parameters
+        ----------
+
+        size : int
+            Size of sample.
+
+        x_min : float, default=None
+            Minimum of sample values. If `None`, the left edge of the support
+            is used.
+
+        x_max : float, default=None
+            Maximum of sample values. If `None`, the right edge of the support
+            is used.
+
+        plot : bool, default=False
+            If `True`, samples histogram is plotted.
+
+        latex : bool, default=False
+            If `True`, the plot is rendered using LaTeX. This option is
+            relevant only if ``plot=True``.
+
+        save : bool, default=False
+            If not `False`, the plot is saved. If a string is given, it is
+            assumed to the save filename (with the file extension). This option
+            is relevant only if ``plot=True``.
+
+        Returns
+        -------
+
+        s : numpy.ndarray
+            Samples.
+
+        Notes
+        -----
+
+        This method uses inverse transform sampling.
+
+        Examples
+        --------
+
+        .. code-block::python
+
+            >>> from freealg.distributions import Wigner
+            >>> wg = Wigner()
+            >>> s = wg.sample(2000)
+
+        .. image:: ../_static/images/plots/wg_samples.png
+            :align: center
+            :class: custom-dark
+        """
+
+        if x_min is None:
+            x_min = self.lam_m
+
+        if x_max is None:
+            x_max = self.lam_p
+
+        # Grid and PDF
+        xs = numpy.linspace(x_min, x_max, size)
+        pdf = self.density(xs)
+
+        # CDF (using cumulative trapezoidal rule)
+        cdf = cumtrapz(pdf, xs, initial=0)
+        cdf /= cdf[-1]  # normalize CDF to 1
+
+        # Inverse CDF interpolator
+        inv_cdf = interp1d(cdf, xs, bounds_error=False,
+                           fill_value=(x_min, x_max))
+
+        # Sample and map
+        u = numpy.random.rand(size)
+        samples = inv_cdf(u)
+
+        if plot:
+            radius = 0.5 * (self.lam_p - self.lam_m)
+            center = 0.5 * (self.lam_p + self.lam_m)
+            scale = 1.25
+            x_min = numpy.floor(center - radius * scale)
+            x_max = numpy.ceil(center + radius * scale)
+            x = numpy.linspace(x_min, x_max, 500)
+            rho = self.density(x)
+            plot_samples(x, rho, x_min, x_max, samples, latex=latex, save=save)
+
+        return samples
+
+    # ======
+    # matrix
+    # ======
+
+    def matrix(self, size):
+        """
+        Generate matrix with the spectral density of the distribution.
+
+        Parameters
+        ----------
+
+        size : int
+            Size :math:`n` of the matrix.
+
+        Returns
+        -------
+
+        A : numpy.ndarray
+            A matrix of the size :math:`n \\times n`.
+
+        Examples
+        --------
+
+        .. code-block::python
+
+            >>> from freealg.distributions import Wigner
+            >>> wg = Wigner()
+            >>> A = wg.matrix(2000)
+        """
+
+        # Parameters
+        n = size
+        p = 1.0 / size
+
+        # Random graph
+        G = nx.erdos_renyi_graph(n, p)
+
+        # Adjancency
+        A = nx.to_numpy_array(G)  # shape (n,n), 0/1 entries
+
+        # Center & scale to get the semicircle
+        A_c = (A - p) / numpy.sqrt(n * p * (1-p))
+
+        return A_c

freealg/freeform.py

@@ -22,6 +22,7 @@ from ._damp import jackson_damping, lanczos_damping, fejer_damping, \
 from ._plot_util import plot_fit, plot_density, plot_hilbert, plot_stieltjes
 from ._pade import fit_pade, eval_pade
 from ._decompress import decompress
+from ._sample import qmc_sample
 
 __all__ = ['FreeForm']
 
@@ -173,8 +174,8 @@ class FreeForm(object):
     # ===
 
     def fit(self, method='jacobi', K=10, alpha=0.0, beta=0.0, reg=0.0,
-            damp=None, force=False, pade_p=1, pade_q=1, plot=False,
-            latex=False, save=False):
+            damp=None, force=False, pade_p=0, pade_q=1, odd_side='left',
+            optimizer='ls', plot=False, latex=False, save=False):
         """
         Fit model to eigenvalues.
 
@@ -209,15 +210,30 @@ class FreeForm(object):
             If `True`, it forces the density to have unit mass and to be
             strictly positive.
 
-        pade_p : int, default=1
-            Degree of polynomial :math:`P(z)`. See notes below.
+        pade_p : int, default=0
+            Degree of polynomial :math:`P(z)` is :math:`q+p` where :math:`p`
+            can only be ``-1``, ``0``, or ``1``. See notes below.
 
         pade_q : int, default=1
-            Degree of polynomial :math:`Q(z)`. See notes below.
+            Degree of polynomial :math:`Q(z)` is :math:`q`. See notes below.
+
+        odd_side : {``'left'``, ``'right'``}, default= ``'left'``
+            In case of odd number of poles (when :math:`q` is odd), the extra
+            pole is set to the left or right side of the support interval,
+            while all other poles are split in half to the left and right. Note
+            that this is only for the initialization of the poles. The
+            optimizer will decide best location by moving them to the left or
+            right of the support.
+
+        optimizer : {``'ls'``, ``'de'``}, default= ``'ls'``
+            Optimizer for Pade approximation, including:
+
+            * ``'ls'``: least square (local, fast)
+            * ``'de'``: differential evolution (global, slow)
 
         plot : bool, default=False
-            If `True`, the approximation coefficients and pade approximaton to
-            the Hilbert traosnform are plotted.
+            If `True`, the approximation coefficients and Pade approximation to
+            the Hilbert transform are plotted.
 
         latex : bool, default=False
             If `True`, the plot is rendered using LaTeX. This option is
@@ -234,6 +250,20 @@ class FreeForm(object):
         psi : (K+1, ) numpy.ndarray
             Coefficients of fitting Jacobi polynomials
 
+        Notes
+        -----
+
+        The Pade approximation for the glue function :math:`G(z)` is
+
+        .. math::
+
+            G(z) = \\frac{P(z)}{Q(z)},
+
+        where :math:`P(z)` and :math:`Q(z)` are polynomials of order
+        :math:`p+q` and :math:`q` respectively. Note that :math:`p` can only
+        be -1, 0, or 1, effectively making Pade approximation of order
+        :math:`q-1:q`, :math:`q:q`, or :math:`q-1:q`.
+
         Examples
         --------
 
@@ -299,17 +329,16 @@ class FreeForm(object):
         g_supp = 2.0 * numpy.pi * self.hilbert(x_supp)
 
         # Fit a pade approximation
-        self._pade_sol = fit_pade(x_supp, g_supp, self.lam_m,
-                                  self.lam_p, pade_p, pade_q, delta=1e-8,
-                                  B=numpy.inf, S=numpy.inf)
+        # self._pade_sol = fit_pade(x_supp, g_supp, self.lam_m,
+        #                           self.lam_p, pade_p, pade_q, delta=1e-8,
+        #                           B=numpy.inf, S=numpy.inf)
+        self._pade_sol = fit_pade(x_supp, g_supp, self.lam_m, self.lam_p,
+                                  p=pade_p, q=pade_q, odd_side=odd_side,
+                                  safety=1.0, max_outer=40, xtol=1e-12,
+                                  ftol=1e-12, optimizer=optimizer, verbose=0)
 
         if plot:
-            # Unpack optimized parameters
-            s = self._pade_sol['s']
-            a = self._pade_sol['a']
-            b = self._pade_sol['b']
-
-            g_supp_approx = eval_pade(x_supp[None, :], s, a, b)[0, :]
+            g_supp_approx = eval_pade(x_supp[None, :], self._pade_sol)[0, :]
             plot_fit(psi, x_supp, g_supp, g_supp_approx, support=self.support,
                      latex=latex, save=save)
 
@@ -513,13 +542,8 @@ class FreeForm(object):
         """
         """
 
-        # Unpack optimized parameters
-        s = self._pade_sol['s']
-        a = self._pade_sol['a']
-        b = self._pade_sol['b']
-
         # Glue function
-        g = eval_pade(z, s, a, b)
+        g = eval_pade(z, self._pade_sol)
 
         return g
 
@@ -633,7 +657,7 @@ class FreeForm(object):
         m1[mask_m, :] = numpy.conjugate(
             stieltjes(numpy.conjugate(z[mask_m, :])))
 
-        # Second Reimann sheet
+        # Second Riemann sheet
         m2[mask_p, :] = m1[mask_p, :]
         m2[mask_m, :] = -m1[mask_m, :] + self._glue(z[mask_m, :])
 
@@ -721,7 +745,7 @@ class FreeForm(object):
         m1[mask_m] = numpy.conjugate(
             stieltjes(numpy.conjugate(z[mask_m].reshape(-1, 1)))).reshape(-1)
 
-        # Second Reimann sheet
+        # Second Riemann sheet
         m2[mask_p] = m1[mask_p]
         m2[mask_m] = -m1[mask_m] + self._glue(
             z[mask_m].reshape(-1, 1)).reshape(-1)
@@ -734,7 +758,7 @@ class FreeForm(object):
     # decompress
     # ==========
 
-    def decompress(self, size, x=None, delta=1e-4, iterations=500,
+    def decompress(self, size, x=None, delta=1e-6, iterations=500,
                    step_size=0.1, tolerance=1e-4, plot=False, latex=False,
                    save=False):
         """
@@ -782,6 +806,10 @@ class FreeForm(object):
         rho : numpy.array
             Spectral density
 
+        eigs : numpy.array
+            Estimated eigenvalues as low-discrepancy samples of the estimated
+            spectral density.
+
         See Also
         --------
 
@@ -809,9 +837,12 @@ class FreeForm(object):
         rho, x, (lb, ub) = decompress(self, size, x=x, delta=delta,
                                       iterations=iterations,
                                       step_size=step_size, tolerance=tolerance)
+        x, rho = x.ravel(), rho.ravel()
 
         if plot:
-            plot_density(x.reshape(-1), rho.reshape(-1), support=(lb, ub),
+            plot_density(x, rho, support=(lb, ub),
                          label='Decompression', latex=latex, save=save)
 
-        return rho
+        eigs = numpy.sort(qmc_sample(x, rho, size))
+
+        return rho, eigs