freealg.AlgebraicForm.is_decompressible#

AlgebraicForm.is_decompressible(ratio=2, n_ratios=5, K=(6, 8, 10), L=3, tol=1e-08, verbose=False, return_info=False)#

Check if the given distribution can be decompressed.

To this end, this function checks if the evolved polynomial under the free decompression admits a valid Stieltjes root.

Note

This function is not always reliable!

Parameters:
ratiofloat, default=2

The maximum ratio of decompressed matrix size to the original size.

n_ratiosint, default=5

Number of ratios to test from 1 (no decompression) to the given maximum ratio.

Ksequence of int, default=(6, 8, 10)

Truncation orders K used to build the Laurent cancellation system. Each K enforces powers p in [-L, ..., K].

Lint, default=3

Number of negative powers to enforce. The enforced power range is p in [-L, ..., K] for each K.

tolfloat, default=1e-10

Pass threshold for the best residual over K. The residual is max_p |c_p| over enforced powers, where c_p are the Laurent coefficients of \(P_t(1/w, m(w))\).

verbosebool, default=True

If True, print a per-t summary and the per-K diagnostics.

return_infobool, default=False

If True, debugging info is also returned.

Returns:
statusarray

Boolean array of True or False for each time in ``t`. True means decompressible, and False means not decompressible.

infodict

Dictionary with the following keys

  • 'ratios': List of decompression ratios that is checked.

  • 'ok': status of the decompressiblity at the tested ratio.

  • 'res': details of test for each ratio.

Raises:
ValueError

If K is empty, or if any K or L is not positive.

See also

branch_points

Geometric branch-point estimation; complementary to this asymptotic check.

Notes

This is a “”no-FD-run” diagnostic: it only uses the base algebraic relation \(P(z,m)=0\) (stored in self.coeffs) and tests the pushed relation under free decompression (FD) at selected expansion factors t.

The FD pushforward used here is the characteristic change-of-variables

  • \(\tau = e^t\)

  • \(y = \tau * m\)

  • \(\zeta = z + (1 - \tau^{-1}) m^{-1}\)

  • \(P_t(z, m) = P(\zeta, y)\)

A necessary condition for FD tracking to remain well-posed is that, for each \(\tau > 1\)), the pushed relation admits a “Stieltjes branch at infinity”, i.e., a solution branch with the large \(\vert z \vert\) behavior

\[m(z) = -\frac{1}{z} + O(z^{-2})\]

as \(\vert z \vert \to \infty\) in \(\Im(z) > 0\).

This routine enforces that asymptotic structure by constructing a truncated Laurent expansion in \(w = 1/z\). It solves for coefficients in

\[m(z) = -(\frac{\alpha}{z} + \frac{\mu_1}{z^2} + \frac{\mu_2|{z^3} + \dots)\]

so that the Laurent series of \(P_t(1/w, m(w))\) cancels on a prescribed range of powers. Concretely, for each truncation order K, we enforce the cancellation of powers p in [-L, ..., K] and measure the maximum absolute residual among those enforced coefficients. The best (smallest) residual across K is used for the main pass/fail decision.

  • K controls how many asymptotic constraints are enforced. Larger K is usually stricter but can become sensitive to coefficient noise (e.g. from a fitted polynomial).

  • L controls how many negative powers are enforced. A safe default is deg_z + 2; here we expose it directly so you can tune it per model.

Examples

>>> from freealg import AlgebraicForm
>>> from freealg.distributions import CompoundFreePoisson
>>> from freealg import submatrix

>>> # Create compound free Poisson law
>>> cfp = CompoundFreePoisson(t=[2.0, 5.5], w=[0.75, 0.25],
...                           lam=0.1)

>>> # Get a matrix realization of the distribution
>>> A = cfp.matrix(size=4000, seed=0)

>>> # Compress the matrix to smaller size
>>> As = submatrix(A, size=2000)

>>> # Use the distribution above to create an algebraic form
>>> af = AlgebraicForm(As)
>>> af.fit(deg_m=3, deg_z=1)

>>> # Check the decompressibility of compound free Poisson
>>> status = af.is_decompressible()

>>> print(status)
True