igl.matryoshka

Truncation samplers and post-fit dimension-curve helpers.

igl.matryoshka.sampler.UniformSampler

Uniform sampler: k ~ Uniform{1, …, d_max}.

The simplest Matryoshka sampling strategy, and the default. It gives equal weight to all truncation levels and lets the encoder discover the true intrinsic dimension without prior bias.

igl.matryoshka.sampler.PowerLawSampler

Power-law sampler: P(k) ∝ k^{-α}.

Useful when prior knowledge suggests the effective dimension is small — biases sampling toward lower truncation levels so the encoder is more aggressively forced to compress.

Parameters:

Name	Type	Description	Default
alpha	float	Exponent (must be positive). Larger alpha puts more mass on small k. Default 1.0.	1.0

igl.matryoshka.dimension_curve.eval_dimension_curve(module, x_val, y_val, *, loss, source_l2=0.001)

Evaluate the trained module at every truncation level k.

For each k, freshly solves the readout weights via lstsq using only the first k latent dimensions, then computes the validation metric. Returns a {k: metric} mapping. The mapping iterates k = 1, 2, …, d_max in insertion order.

Parameters:

Name	Type	Description	Default
module	IGLModule | PrefixForward	Trained :class:IGLModule.	required
x_val	Tensor	Validation inputs [N, D].	required
y_val	Tensor	Validation targets.	required
loss	LossStrategy	Loss strategy used to compute the per-k metric.	required
source_l2	float	Tikhonov regularisation forwarded to :func:igl.direct_solve_weights.	0.001

Returns:

Type	Description
DimensionCurve	A dict mapping k → curve_score where curve_score is whatever
DimensionCurve
DimensionCurve
DimensionCurve	The curve score is always lower-is-better so :func:detect_elbow
DimensionCurve	can locate the knee.

igl.matryoshka.dimension_curve.detect_elbow(curve, *, ratio=2.0)

Locate the elbow of a dimension/loss curve in log-space.

Operates on log(loss) so a 5× loss reduction has the same log-delta whether it occurs at loss=0.1 or loss=0.001. Returns the largest k whose log-reduction exceeds max_log_delta / ratio.

Parameters:

Name	Type	Description	Default
curve	DimensionCurve	{k: loss} mapping (from :func:eval_dimension_curve). Must contain at least one entry.	required
ratio	float	A reduction must be at least max_log_delta / ratio to count as substantial. Default 2.0.	2.0

Returns:

Type	Description
int	The estimated intrinsic dimension d_eff.

Raises:

Type	Description
IGLConfigError	If curve is empty or ratio <= 0.

igl.greedy_knockout(module, x_val, y_val, *, loss, source_l2=0.001, ratio=2.0)

Delete coordinates greedily, least-harmful first, refitting each time.

Scores use :meth:LossStrategy.curve_score (always lower-is-better: error rate for classification, MSE for regression), so the certificate is task-scored rather than reconstruction-scored.

Parameters:

Name	Type	Description	Default
module	IGLModule	Trained :class:IGLModule.	required
x_val	Tensor	Validation inputs [N, D].	required
y_val	Tensor	Validation targets.	required
loss	LossStrategy	Loss strategy providing targets and the curve score.	required
source_l2	float	Tikhonov regularisation for the per-step readout refit.	0.001
ratio	float	Knee threshold forwarded to :func:detect_knockout_knee.	2.0

Returns:

Name	Type	Description
A	KnockoutResult
	KnockoutResult	and the certified knee.

igl.KnockoutResult dataclass

Outcome of :func:greedy_knockout.

Attributes:

Name	Type	Description
curve	dict[int, float]	{n_active: curve_score} for each greedy step, from max_dim active coordinates down to 1.
removal_order	list[int]	Coordinate indices in the order they were removed.
knee	int	The certified dimension, per :func:detect_knockout_knee.

igl.detect_knockout_knee(curve, *, ratio=2.0)

Locate the smallest number of active coordinates before the score blows up.

Walking from few to many active coordinates, the knee is the first count whose score is within ratio of the best score over the curve. A single-point curve returns 1 only when it genuinely holds the best score — the detector never fires unconditionally at n = 1.

Parameters:

Name	Type	Description	Default
curve	dict[int, float]	{n_active: curve_score} (lower is better).	required
ratio	float	Blow-up threshold relative to the best score.	2.0

Returns:

Type	Description
int	The certified dimension.