`igl.types`

Public Protocols, enum.StrEnum classes, and Literal companions.

Protocols

`igl.types.EncoderProtocol`

Bases: Protocol

A callable mapping ambient inputs to an max_dim-dimensional latent.

`igl.types.OperatorFn`

Bases: Protocol

Log-space kernel operator.

Given a distance tensor d and a width tensor sigma of broadcastable shapes, returns (log_abs, sign) so the multi-scale product kernel can be accumulated in log-space while tracking signs for oscillatory operators.

`igl.types.LossStrategy`

Bases: Protocol

Pluggable loss for :class:igl.MatryoshkaTrainer.

Implementations supply task-specific targets (one-hot encoding, pass-through, log-Euclidean SPD targets, …), the loss to minimise, a scalar metric for early-stopping decisions, and — separately — a curve score used by :func:igl.eval_dimension_curve to make dimension curves informative (e.g. error rate for classifiers, which doesn't saturate the way cross-entropy does).

Attributes:

Name	Type	Description
`higher_is_better`	`bool`	`True` when `metric()` should be maximised (e.g. accuracy), `False` when minimised (e.g. MSE, AIRM). `curve_score()` is always lower-is-better regardless of this flag.

A strategy may also define metric_tensor(pred, target) -> Tensor and curve_score_tensor(pred, target) -> Tensor returning the same values as 0-d tensors on the prediction's device. The trainer and the dimension curve prefer them, so an epoch (or a whole curve) needs a single host transfer; without them each call costs one synchronisation.

A strategy that synchronises with the host inside loss (an eigensolver, a .item()) should expose graph_capturable = False so the CUDA branch does not try to record the batch step into a CUDA graph; the default is True.

`igl.types.MatryoshkaSampler`

Bases: Protocol

Samples a truncation level k ∈ {1, …, d_max} per training step.

`igl.types.ExtraLoss`

Bases: Protocol

Optional regularizer that contributes a scalar term to the training loss.

Used by :class:igl.MatryoshkaTrainer to fold in geometry-specific penalties (e.g. the SPD orthogonality penalty from :class:igl.spd.OrthogonalityPenalty) without coupling the trainer to that geometry.

The trainer calls the extra loss once per batch (subject to :attr:every), adds weight * contribution to the task loss, and backpropagates through everything in one go. Implementations may return None to skip the contribution for this step (useful when the regularizer is only defined for k ≥ 2, for example).

Attributes:

Name	Type	Description
`weight`	`float`	Multiplier applied to the returned tensor before adding to the task loss.
`every`	`int`	Call frequency in batches (1 = every batch).

String enums

`igl.types.OperatorName`

Bases: StrEnum

Built-in kernel operator names. Canonical reference for kernel choices.

`igl.types.SamplingMode`

Bases: StrEnum

Truncation-level sampling strategies for Matryoshka training.

`igl.types.NormalizeMode`

Bases: StrEnum

Row-wise normalization applied to the design matrix Φ before lstsq.

NONE (default): identity. The closed-form solve already scales its ridge to Φ's column norms, so raw kernel values are a safe default for every operator and basis.
SOFTMAX: row-softmax. Shift-invariant per row, so the overall magnitude of a row (how close the point is to any anchor) is discarded.
L2: L2-normalise each row.
NW: Nadaraya–Watson (divide each row by its sum, with a small epsilon). Assumes non-negative rows; with an oscillatory operator or a spectral basis a row sum can cross zero and the division blows up.

`igl.types.NormType`

Bases: StrEnum

Normalization layer inserted after each hidden Linear of an MLP encoder.

`igl.types.ActivationType`

Bases: StrEnum

Activation function applied after each (Linear → Norm) block.

`igl.types.EncoderKind`

Bases: StrEnum

Kind of encoder built by :func:igl.build_mlp_encoder / future factories.

`igl.types.SchedulerType`

Bases: StrEnum

Learning-rate scheduler choices for :class:igl.MatryoshkaTrainer.

`igl.PrefixForward`

Bases: Protocol

A module trainable with Matryoshka prefix masking, without the VP solve.

Any nn.Module whose forward accepts a gate_mask keyword (a [max_dim] 0/1 tensor selecting the leading latent coordinates) satisfies this protocol and can be trained by :class:igl.MatryoshkaTrainer and scored by :func:igl.eval_dimension_curve by plain gradient descent — e.g. a prefix-masked autoencoder used as an instrument-vs-instrument control.