mixle.experimental.spectral_health module

Descriptive spectral receipts for real, finite weight tensors.

The singular spectrum, stable/effective rank, outlier count, and a power-law tail fit can describe a weight matrix without evaluation data. They do not, by themselves, establish that a model is under-trained, well-trained, memorizing, or otherwise healthy. This module therefore reports fit quality, tail sample size, and a conditional bootstrap interval, and always abstains from scientific diagnosis until a separately validated and calibrated diagnostic model is supplied.

class SpectralReceipt(matrix_shape, n_singular_values, spectral_norm, frobenius_norm, stable_rank, effective_rank, alpha, alpha_ci_low, alpha_ci_high, ks_d, lambda_min, tail_points, bootstrap_samples, tail_fit_status, tail_fit_accepted, n_spikes, verdict, diagnostic_reason)[source]

Bases: object

Descriptive statistics and an explicitly scoped tail-fit receipt.

Parameters:

  • matrix_shape (tuple[int, int])

  • n_singular_values (int)

  • spectral_norm (float)

  • frobenius_norm (float)

  • stable_rank (float)

  • effective_rank (float)

  • alpha (float | None)

  • alpha_ci_low (float | None)

  • alpha_ci_high (float | None)

  • ks_d (float | None)

  • lambda_min (float | None)

  • tail_points (int)

  • bootstrap_samples (int)

  • tail_fit_status (str)

  • tail_fit_accepted (bool)

  • n_spikes (int)

  • verdict (None)

  • diagnostic_reason (str)

singular_values(weight)[source]

Descending singular values; dimensions after the first are flattened into columns.

Parameters:

weight (Any)

Return type:

ndarray

stable_rank(s)[source]

||W||_F^2 / ||W||_2^2 – a soft, noise-robust rank in [1, min(shape)].

Parameters:

s (ndarray)

Return type:

float

effective_rank(s)[source]

Roy-Vetterli effective rank: exp of the Shannon entropy of the normalized spectrum.

Parameters:

s (ndarray)

Return type:

float

fit_tail_exponent(s, *, min_tail_points=50)[source]

Fit the eigenvalue-spectrum power-law tail, scanning lambda_min to minimize KS.

Returns (alpha, ks_d, lambda_min) on the eigenvalues lambda = s^2.

Parameters:
Return type:

tuple[float, float, float]

spectral_health(weight, *, min_tail_points=50, max_ks=0.1, bootstrap_samples=200, confidence=0.95, seed=0)[source]

Compute a descriptive receipt and abstain from uncalibrated health diagnosis.

Parameters:
Return type:

SpectralReceipt

model_spectral_report(named_weights)[source]

Receipt per named 2-D weight matrix. named_weights: mapping name -> array-like.

Parameters:

named_weights (Any)

Return type:

dict[str, SpectralReceipt]