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.

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 - 1/\tau) / m\)

  • \(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) = -1/z + O(1/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) = -(alpha/z + mu_1/z^2 + mu_2/z^3 + ...)\]

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

>>> import freealg AlgebraicForm
>>> from freealg.distributions import CompoundPoisson

>>> # Create compound free Poisson law
>>> cp = CompoundPoisson(t1=2.0, t2=5.5, w1=0.75, c=0.1)
>>> af = AlgebraicForm(cp)

>>> # Check the decompressibility of compound free Poisson
>>> status, info = af.is_decompressible(ratio=2, n_ratios=5,
...                                     verbose=True)

>>> status
True