freealg 0.7.16__tar.gz → 0.7.18__tar.gz

{freealg-0.7.16 → freealg-0.7.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.7.16
+Version: 0.7.18
 Summary: Free probability for large matrices
 Home-page: https://github.com/ameli/freealg
 Download-URL: https://github.com/ameli/freealg/archive/main.zip

{freealg-0.7.16 → freealg-0.7.18}/freealg/__init__.py

@@ -6,15 +6,17 @@
 # under the terms of the license found in the LICENSE.txt file in the root
 # directory of this source tree.
 
-from ._free_form import FreeForm, eigvalsh, cond, norm, trace, slogdet, supp, \
-    sample, kde
-from ._algebraic_form import AlgebraicForm, decompress_newton
+from ._free_form import FreeForm, eigvalsh, cond, norm, trace, slogdet, kde
+from ._algebraic_form import AlgebraicForm
 from ._geometric_form import GeometricForm
 from . import visualization
 from . import distributions
+from ._sample import sample
+from ._support import supp
+from ._util import submatrix
 
-__all__ = ['FreeForm', 'distributions', 'visualization', 'eigvalsh', 'cond',
-           'norm', 'trace', 'slogdet', 'supp', 'sample', 'kde',
-           'AlgebraicForm', 'GeometricForm', 'decompress_newton']
+__all__ = ['FreeForm', 'AlgebraicForm', 'GeometricForm', 'distributions',
+           'visualization', 'eigvalsh', 'cond', 'norm', 'trace', 'slogdet',
+           'supp', 'sample', 'submatrix', 'kde']
 
 from .__version__ import __version__                          # noqa: F401 E402

freealg-0.7.18/freealg/__version__.py

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

{freealg-0.7.16 → freealg-0.7.18}/freealg/_algebraic_form/_branch_points.py

@@ -13,7 +13,7 @@
 
 import numpy
 
-__all__ = ['compute_branch_points']
+__all__ = ['estimate_branch_points']
 
 
 # =========
@@ -154,19 +154,19 @@ def _det_bareiss_poly(M, tol):
 # resultant discriminant
 # ======================
 
-def _resultant_discriminant(a_coeffs, tol):
+def _resultant_discriminant(coeffs, tol):
     """
     Numerically compute Disc_m(P)(z) as a polynomial in z (ascending coeffs),
     via Sylvester determinant evaluation on a circle + interpolation.
 
-    a_coeffs[i,j] is coeff of z^i m^j, shape (deg_z+1, s+1).
+    coeffs[i,j] is coeff of z^i m^j, shape (deg_z+1, s+1).
     """
 
     import numpy
 
-    a_coeffs = numpy.asarray(a_coeffs, dtype=numpy.complex128)
-    deg_z = a_coeffs.shape[0] - 1
-    s = a_coeffs.shape[1] - 1
+    coeffs = numpy.asarray(coeffs, dtype=numpy.complex128)
+    deg_z = coeffs.shape[0] - 1
+    s = coeffs.shape[1] - 1
     if s < 1 or deg_z < 0:
         return numpy.zeros(1, dtype=numpy.complex128)
 
@@ -180,7 +180,7 @@ def _resultant_discriminant(a_coeffs, tol):
         # m^(s-k)
         p_asc = numpy.zeros(s + 1, dtype=numpy.complex128)
         for j in range(s + 1):
-            p_asc[j] = numpy.polyval(a_coeffs[:, j][::-1], z)  # a_j(z)
+            p_asc[j] = numpy.polyval(coeffs[:, j][::-1], z)  # a_j(z)
         p_desc = p_asc[::-1]
 
         # Q(m) = dP/dm, descending
@@ -207,8 +207,8 @@ def _resultant_discriminant(a_coeffs, tol):
     # Sample points on a circle; scale radius using coefficient magnitude
     # (simple heuristic) (This only affects conditioning of interpolation, not
     # correctness.)
-    scale = float(numpy.max(numpy.abs(a_coeffs))) \
-        if numpy.max(numpy.abs(a_coeffs)) > 0 else 1.0
+    scale = float(numpy.max(numpy.abs(coeffs))) \
+        if numpy.max(numpy.abs(coeffs)) > 0 else 1.0
     R = 1.0 + 0.1 * scale
 
     N = D + 1
@@ -228,7 +228,7 @@ def _resultant_discriminant(a_coeffs, tol):
         c = numpy.zeros(1, dtype=numpy.complex128)
 
     # If numerics leave small imag, kill it (disc should be real-coeff if
-    # a_coeffs real)
+    # coeffs real)
     if numpy.linalg.norm(c.imag) <= \
             1e3 * tol * max(1.0, numpy.linalg.norm(c.real)):
         c = c.real.astype(numpy.float64)
@@ -236,11 +236,11 @@ def _resultant_discriminant(a_coeffs, tol):
     return c
 
 
-# =====================
-# compute branch points
-# =====================
+# ======================
+# estimate branch points
+# ======================
 
-def compute_branch_points(a_coeffs, tol=1e-12, real_tol=None):
+def estimate_branch_points(coeffs, tol=1e-12, real_tol=None):
     """
     Compute global branch points of the affine curve P(z,m)=0 by
     z-roots of Disc_m(P)(z) = Res_m(P, dP/dm).
@@ -252,8 +252,8 @@ def compute_branch_points(a_coeffs, tol=1e-12, real_tol=None):
     info : dict
     """
 
-    a_coeffs = numpy.asarray(a_coeffs, dtype=float)
-    s = a_coeffs.shape[1] - 1
+    coeffs = numpy.asarray(coeffs, dtype=float)
+    s = coeffs.shape[1] - 1
     if s < 1:
         if real_tol is None:
             real_tol = 1e3 * tol
@@ -269,11 +269,11 @@ def compute_branch_points(a_coeffs, tol=1e-12, real_tol=None):
     if real_tol is None:
         real_tol = 1e3 * tol
 
-    a_s = _poly_trim(a_coeffs[:, s], tol)
+    a_s = _poly_trim(coeffs[:, s], tol)
     a_s_zero = numpy.roots(a_s[::-1]) if a_s.size > 1 else \
         numpy.array([], dtype=complex)
 
-    disc = _resultant_discriminant(a_coeffs, tol)
+    disc = _resultant_discriminant(coeffs, tol)
     if disc.size <= 1:
         z_bp = numpy.array([], dtype=complex)
     else:

{freealg-0.7.16 → freealg-0.7.18}/freealg/_algebraic_form/_continuation_algebraic.py

@@ -301,7 +301,7 @@ def fit_polynomial_relation(z, m, s, deg_z, ridge_lambda=0.0, weights=None,
 # sanity check stieltjes branch
 # =============================
 
-def sanity_check_stieltjes_branch(a_coeffs, x_min, x_max, eta=0.1,
+def sanity_check_stieltjes_branch(coeffs, x_min, x_max, eta=0.1,
                                   n_x=64, y0=None, max_bad_frac=0.05):
     """
     Quick sanity check: does P(z,m)=0 admit a continuously trackable root with
@@ -322,7 +322,7 @@ def sanity_check_stieltjes_branch(a_coeffs, x_min, x_max, eta=0.1,
     z0 = 1j * y0
     m0_target = -1.0 / z0
 
-    c0 = _poly_coef_in_m(numpy.array([z0]), a_coeffs)[0]
+    c0 = _poly_coef_in_m(numpy.array([z0]), coeffs)[0]
     r0 = numpy.roots(c0[::-1])
     if r0.size == 0:
         return {'ok': False, 'frac_bad': 1.0, 'n_test': 0, 'n_bad': 0}
@@ -337,7 +337,7 @@ def sanity_check_stieltjes_branch(a_coeffs, x_min, x_max, eta=0.1,
     n_ok = 0
 
     for z in zs:
-        c = _poly_coef_in_m(numpy.array([z]), a_coeffs)[0]
+        c = _poly_coef_in_m(numpy.array([z]), coeffs)[0]
         r = numpy.roots(c[::-1])
         if r.size == 0 or not numpy.all(numpy.isfinite(r)):
             n_bad += 1
@@ -372,12 +372,12 @@ def sanity_check_stieltjes_branch(a_coeffs, x_min, x_max, eta=0.1,
 # eval P
 # ======
 
-def eval_P(z, m, a_coeffs):
+def eval_P(z, m, coeffs):
 
     z = numpy.asarray(z, dtype=complex)
     m = numpy.asarray(m, dtype=complex)
-    deg_z = int(a_coeffs.shape[0] - 1)
-    s = int(a_coeffs.shape[1] - 1)
+    deg_z = int(coeffs.shape[0] - 1)
+    s = int(coeffs.shape[1] - 1)
 
     shp = numpy.broadcast(z, m).shape
     zz = numpy.broadcast_to(z, shp).ravel()
@@ -388,7 +388,7 @@ def eval_P(z, m, a_coeffs):
 
     P = numpy.zeros(zz.size, dtype=complex)
     for j in range(s + 1):
-        aj = zp @ a_coeffs[:, j]
+        aj = zp @ coeffs[:, j]
         P = P + aj * mp[:, j]
 
     return P.reshape(shp)
@@ -398,16 +398,16 @@ def eval_P(z, m, a_coeffs):
 # poly coef in m
 # ==============
 
-def _poly_coef_in_m(z, a_coeffs):
+def _poly_coef_in_m(z, coeffs):
 
     z = numpy.asarray(z, dtype=complex).ravel()
-    deg_z = int(a_coeffs.shape[0] - 1)
-    s = int(a_coeffs.shape[1] - 1)
+    deg_z = int(coeffs.shape[0] - 1)
+    s = int(coeffs.shape[1] - 1)
     zp = powers(z, deg_z)
 
     c = numpy.empty((z.size, s + 1), dtype=complex)
     for j in range(s + 1):
-        c[:, j] = zp @ a_coeffs[:, j]
+        c[:, j] = zp @ coeffs[:, j]
     return c
 
 
@@ -489,10 +489,10 @@ def _roots_cubic(c0, c1, c2, c3):
 # eval roots
 # ==========
 
-def eval_roots(z, a_coeffs):
+def eval_roots(z, coeffs):
 
     z = numpy.asarray(z, dtype=complex).ravel()
-    c = _poly_coef_in_m(z, a_coeffs)
+    c = _poly_coef_in_m(z, coeffs)
 
     s = int(c.shape[1] - 1)
     if s == 1:

{freealg-0.7.16 → freealg-0.7.18}/freealg/_algebraic_form/_cusp.py

@@ -95,7 +95,7 @@ def _newton_3x3(F, x0, max_iter=60, tol=1e-12, bounds=None, max_step=None):
 __all__ = ["solve_cusp"]
 
 
-def _second_partials_fd(zeta, y, a_coeffs, eps_z=None, eps_y=None):
+def _second_partials_fd(zeta, y, coeffs, eps_z=None, eps_y=None):
     zeta = float(zeta)
     y = float(y)
 
@@ -104,13 +104,13 @@ def _second_partials_fd(zeta, y, a_coeffs, eps_z=None, eps_y=None):
     if eps_y is None:
         eps_y = 1e-7 * (1.0 + abs(y))
 
-    _, Pz_p, Py_p = eval_P_partials(zeta + eps_z, y, a_coeffs)
-    _, Pz_m, Py_m = eval_P_partials(zeta - eps_z, y, a_coeffs)
+    _, Pz_p, Py_p = eval_P_partials(zeta + eps_z, y, coeffs)
+    _, Pz_m, Py_m = eval_P_partials(zeta - eps_z, y, coeffs)
     Pzz = (Pz_p - Pz_m) / (2.0 * eps_z)
     Pzy1 = (Py_p - Py_m) / (2.0 * eps_z)
 
-    _, Pz_p, Py_p = eval_P_partials(zeta, y + eps_y, a_coeffs)
-    _, Pz_m, Py_m = eval_P_partials(zeta, y - eps_y, a_coeffs)
+    _, Pz_p, Py_p = eval_P_partials(zeta, y + eps_y, coeffs)
+    _, Pz_m, Py_m = eval_P_partials(zeta, y - eps_y, coeffs)
     Pzy2 = (Pz_p - Pz_m) / (2.0 * eps_y)
     Pyy = (Py_p - Py_m) / (2.0 * eps_y)
 
@@ -118,11 +118,11 @@ def _second_partials_fd(zeta, y, a_coeffs, eps_z=None, eps_y=None):
     return float(Pzz), float(Pzy), float(Pyy)
 
 
-def _cusp_F_real(zeta, y, s, a_coeffs):
+def _cusp_F_real(zeta, y, s, coeffs):
     # tau = 1 + exp(s)  => c = tau-1 = exp(s) > 0
     c = float(numpy.exp(float(s)))
 
-    P, Pz, Py = eval_P_partials(float(zeta), float(y), a_coeffs)
+    P, Pz, Py = eval_P_partials(float(zeta), float(y), coeffs)
     P = float(numpy.real(P))
     Pz = float(numpy.real(Pz))
     Py = float(numpy.real(Py))
@@ -130,7 +130,7 @@ def _cusp_F_real(zeta, y, s, a_coeffs):
     F1 = P
     F2 = (y * y) * Py - c * Pz
 
-    Pzz, Pzy, Pyy = _second_partials_fd(zeta, y, a_coeffs)
+    Pzz, Pzy, Pyy = _second_partials_fd(zeta, y, coeffs)
     F3 = y * (Pzz * (Py * Py) - 2.0 * Pzy * Pz * Py + Pyy * (Pz * Pz)) + \
         2.0 * (Pz * Pz) * Py
 
@@ -141,8 +141,8 @@ def _cusp_F_real(zeta, y, s, a_coeffs):
 # poly coeffs in y
 # ================
 
-def _poly_coeffs_in_y(a_coeffs, zeta):
-    a = numpy.asarray(a_coeffs)
+def _poly_coeffs_in_y(coeffs, zeta):
+    a = numpy.asarray(coeffs)
     deg_z = a.shape[0] - 1
     deg_y = a.shape[1] - 1
     z_pows = numpy.power(zeta, numpy.arange(deg_z + 1, dtype=numpy.int64))
@@ -156,9 +156,9 @@ def _poly_coeffs_in_y(a_coeffs, zeta):
 # pick realish root y
 # ===================
 
-def _pick_realish_root_y(a_coeffs, zeta):
+def _pick_realish_root_y(coeffs, zeta):
 
-    c_asc = _poly_coeffs_in_y(a_coeffs, zeta)
+    c_asc = _poly_coeffs_in_y(coeffs, zeta)
     c_desc = c_asc[::-1]  # descending for numpy.roots
 
     k = 0
@@ -179,7 +179,7 @@ def _pick_realish_root_y(a_coeffs, zeta):
 # ==========
 
 def solve_cusp(
-        a_coeffs,
+        coeffs,
         t_init,
         zeta_init,
         y_init=None,
@@ -191,11 +191,11 @@ def solve_cusp(
     Exact-derivative cusp solve for (zeta, y, t) with unknowns (zeta, y, s),
     where tau = 1 + exp(s), t = log(tau), x = zeta - (tau-1)/y.
 
-    a_coeffs: array shape (deg_z+1, deg_y+1), P(zeta,y)=
+    coeffs: array shape (deg_z+1, deg_y+1), P(zeta,y)=
     sum_{i,j} a[i,j]*zeta^i*y^j
     """
 
-    a = numpy.asarray(a_coeffs, dtype=numpy.complex128)
+    a = numpy.asarray(coeffs, dtype=numpy.complex128)
     deg_z = a.shape[0] - 1
     deg_y = a.shape[1] - 1
 

{freealg-0.7.16 → freealg-0.7.18}/freealg/_algebraic_form/_cusp_wrap.py

@@ -19,15 +19,15 @@ import scipy.optimize as opt
 # poly coeffs in y
 # ================
 
-def _poly_coeffs_in_y(a_coeffs, zeta):
+def _poly_coeffs_in_y(coeffs, zeta):
     """
     Build coefficients c_j(zeta) so that P(zeta, y) = sum_j c_j(zeta) y^j.
 
-    Assumes a_coeffs[i, j] multiplies z^i y^j (same layout as eval_P in
+    Assumes coeffs[i, j] multiplies z^i y^j (same layout as eval_P in
     _continuation_algebraic). Returns coefficients in ascending powers of y.
     """
 
-    a = numpy.asarray(a_coeffs)
+    a = numpy.asarray(coeffs)
     deg_z = a.shape[0] - 1
     deg_y = a.shape[1] - 1
 
@@ -44,14 +44,14 @@ def _poly_coeffs_in_y(a_coeffs, zeta):
 # pick realish root y
 # ===================
 
-def _pick_realish_root_y(a_coeffs, zeta):
+def _pick_realish_root_y(coeffs, zeta):
     """
     Pick a reasonable real-ish root y of P(zeta, y)=0 to seed Newton.
 
     Returns a float (real part of the selected root).
     """
 
-    c_asc = _poly_coeffs_in_y(a_coeffs, zeta)  # ascending in y
+    c_asc = _poly_coeffs_in_y(coeffs, zeta)  # ascending in y
     # numpy.roots wants descending order
     c_desc = c_asc[::-1]
     # strip leading ~0 coefficients
@@ -138,7 +138,7 @@ def cusp_wrap(self, t_grid, edge_kwargs=None, max_iter=80, tol=1e-12,
     tau = float(numpy.exp(t_star))
     c = tau - 1.0
 
-    a = numpy.asarray(self.a_coeffs, dtype=numpy.complex128)
+    a = numpy.asarray(self.coeffs, dtype=numpy.complex128)
     deg_z = a.shape[0] - 1
     deg_y = a.shape[1] - 1
 

{freealg-0.7.16 → freealg-0.7.18}/freealg/_algebraic_form/_decompress.py

@@ -62,7 +62,7 @@ def build_time_grid(sizes, n0, min_n_times=0):
 
 
 
-def fd_solve_w(z, t, a_coeffs, w_init, max_iter=50, tol=1e-12,
+def fd_solve_w(z, t, coeffs, w_init, max_iter=50, tol=1e-12,
                armijo=1e-4, min_lam=1e-6, w_min=1e-14):
     """
     Solve for w = m(t,z) from the implicit FD equation using damped Newton.
@@ -83,7 +83,7 @@ def fd_solve_w(z, t, a_coeffs, w_init, max_iter=50, tol=1e-12,
         Query point in the complex plane.
     t : float
         Time parameter (tau = exp(t)).
-    a_coeffs : ndarray
+    coeffs : ndarray
         Coefficients defining P(zeta,y) in the monomial basis.
     w_init : complex
         Initial guess for w.
@@ -117,7 +117,7 @@ def fd_solve_w(z, t, a_coeffs, w_init, max_iter=50, tol=1e-12,
     .. code-block:: python
 
         w, ok = fd_solve_w(
-            z=0.5 + 1e-6j, t=2.0, a_coeffs=a_coeffs, w_init=m1_fn(0.5 + 1e-6j),
+            z=0.5 + 1e-6j, t=2.0, coeffs=coeffs, w_init=m1_fn(0.5 + 1e-6j),
             max_iter=50, tol=1e-12
         )
     """
@@ -132,7 +132,7 @@ def fd_solve_w(z, t, a_coeffs, w_init, max_iter=50, tol=1e-12,
 
     for _ in range(max_iter):
 
-        a = numpy.asarray(a_coeffs, dtype=numpy.complex128)
+        a = numpy.asarray(coeffs, dtype=numpy.complex128)
         deg_z = a.shape[0] - 1
         deg_m = a.shape[1] - 1
 
@@ -195,13 +195,13 @@ def fd_solve_w(z, t, a_coeffs, w_init, max_iter=50, tol=1e-12,
         w = complex(best)
 
         # final residual check
-        F_end = eval_P_partials(z + alpha / w, tau * w, a_coeffs)[0]
+        F_end = eval_P_partials(z + alpha / w, tau * w, coeffs)[0]
         return w, (abs(F_end) <= 1e3 * tol)
 
     # -------------------
 
 
-    F_end = eval_P_partials(z + alpha / w, tau * w, a_coeffs)[0]
+    F_end = eval_P_partials(z + alpha / w, tau * w, coeffs)[0]
     return w, (abs(F_end) <= 10.0 * tol)
 
 
@@ -209,7 +209,7 @@ def fd_solve_w(z, t, a_coeffs, w_init, max_iter=50, tol=1e-12,
 # NEW FUNCTION
 # ============
 
-def fd_candidates_w(z, t, a_coeffs, w_min=1e-14):
+def fd_candidates_w(z, t, coeffs, w_min=1e-14):
     """
     Return candidate roots w solving P(z + alpha/w, tau*w)=0 with Im(w)>0 (if Im(z)>0).
     """
@@ -218,7 +218,7 @@ def fd_candidates_w(z, t, a_coeffs, w_min=1e-14):
     alpha = 1.0 - 1.0 / tau
     want_pos_imag = (z.imag > 0.0)
 
-    a = numpy.asarray(a_coeffs, dtype=numpy.complex128)
+    a = numpy.asarray(coeffs, dtype=numpy.complex128)
     deg_z = a.shape[0] - 1
     deg_m = a.shape[1] - 1
 
@@ -256,7 +256,7 @@ def fd_candidates_w(z, t, a_coeffs, w_min=1e-14):
         # residual filter (optional but helps)
         # -------------
         # TEST
-        # F = eval_P_partials(z + alpha / w, tau * w, a_coeffs)[0]
+        # F = eval_P_partials(z + alpha / w, tau * w, coeffs)[0]
         # if abs(F) < 1e-6:
         #     cands.append(complex(w))
         # ---------------
@@ -271,7 +271,7 @@ def fd_candidates_w(z, t, a_coeffs, w_min=1e-14):
 # decompress newton
 # =================
 
-def decompress_newton(z_list, t_grid, a_coeffs, w0_list=None,
+def decompress_newton(z_list, t_grid, coeffs, w0_list=None,
                       dt_max=0.1, sweep=True, time_rel_tol=5.0,
                       active_imag_eps=None, sweep_pad=20,
                       max_iter=50, tol=1e-12, armijo=1e-4,
@@ -285,7 +285,7 @@ def decompress_newton(z_list, t_grid, a_coeffs, w0_list=None,
         Query points z (typically x + 1j*eta with eta > 0), ordered along x.
     t_grid : array_like of float
         Strictly increasing time grid.
-    a_coeffs : ndarray
+    coeffs : ndarray
         Coefficients defining P(zeta,y) in the monomial basis.
     w0_list : array_like of complex
         Initial values at t_grid[0] (typically m0(z_list) on the physical
@@ -351,14 +351,14 @@ def decompress_newton(z_list, t_grid, a_coeffs, w0_list=None,
     # def solve_with_choice(iz, w_seed):
     #     # Neighbor-seeded candidate (spatial continuity)
     #     w_a, ok_a = fd_solve_w(
-    #         z_list[iz], t, a_coeffs, w_seed,
+    #         z_list[iz], t, coeffs, w_seed,
     #         max_iter=max_iter, tol=tol, armijo=armijo,
     #         min_lam=min_lam, w_min=w_min
     #     )
     #
     #     # Time-seeded candidate (time continuation)
     #     w_b, ok_b = fd_solve_w(
-    #         z_list[iz], t, a_coeffs, w_prev[iz],
+    #         z_list[iz], t, coeffs, w_prev[iz],
     #         max_iter=max_iter, tol=tol, armijo=armijo,
     #         min_lam=min_lam, w_min=w_min
     #     )
@@ -387,7 +387,7 @@ def decompress_newton(z_list, t_grid, a_coeffs, w0_list=None,
     # TEST
     def solve_with_choice(iz, w_seed):
         # candidate roots at this (t,z)
-        cands = fd_candidates_w(z_list[iz], t, a_coeffs, w_min=w_min)
+        cands = fd_candidates_w(z_list[iz], t, coeffs, w_min=w_min)
 
         # ---------------------
         # TEST
@@ -402,7 +402,7 @@ def decompress_newton(z_list, t_grid, a_coeffs, w0_list=None,
         if len(cands) == 0:
             # fallback to your existing single-root solver
             w, success = fd_solve_w(
-                z_list[iz], t, a_coeffs, w_prev[iz],
+                z_list[iz], t, coeffs, w_prev[iz],
                 max_iter=max_iter, tol=tol, armijo=armijo,
                 min_lam=min_lam, w_min=w_min
             )
@@ -452,7 +452,7 @@ def decompress_newton(z_list, t_grid, a_coeffs, w0_list=None,
                 # problems.
                 for iz in range(nz):
                     w, success = fd_solve_w(
-                        z_list[iz], t, a_coeffs, w_prev[iz],
+                        z_list[iz], t, coeffs, w_prev[iz],
                         max_iter=max_iter, tol=tol, armijo=armijo,
                         min_lam=min_lam, w_min=w_min
                     )