igl.core

Geometry-agnostic primitives: encoder, Green kernel, solver, trainer, losses.

Encoders

igl.core.encoder.MLPEncoder

Bases: Module

MLP encoder: depth × (Linear → Norm → Activation) → Linear.

Parameters:

Name	Type	Description	Default
input_dim	int	Ambient dimension D.	required
max_dim	int	Latent dimension d_max.	required
hidden	int | Sequence[int]	Either a single width applied uniformly to every hidden layer (default 256), or a sequence of per-layer widths (e.g. (256, 128, 64) for a pyramidal encoder).	256
depth	int | None	Optional explicit depth. When hidden is an int, defaults to 2. When hidden is a sequence and depth is provided, the two must agree.	None
norm	NormTypeLike	Type of normalization in each block (default :data:igl.NormType.LAYER). Accepts the enum or a matching string.	LAYER
activation	ActivationTypeLike	Activation function (default :data:igl.ActivationType.SILU). Accepts the enum or a matching string.	SILU

Raises:

Type	Description
IGLConfigError	If any dimension is non-positive, hidden is an empty sequence, or depth contradicts len(hidden).

igl.core.encoder.LinearEncoder

Bases: Module

Single nn.Linear projection from ambient to latent space.

Parameters:

Name	Type	Description	Default
input_dim	int	Ambient dimension D.	required
max_dim	int	Latent dimension d_max.	required

igl.core.encoder.build_mlp_encoder(input_dim, max_dim, *, config)

Parameters:

Name	Type	Description	Default
input_dim	int	Ambient dimension D.	required
max_dim	int	Latent dimension d_max.	required
config	EncoderConfig	Encoder configuration. config.kind must be :data:igl.EncoderKind.MLP.	required

Raises:

Type	Description
IGLConfigError	If config.kind is not :data:igl.EncoderKind.MLP.

Green kernel

igl.core.kernel.GreenKernel

Bases: Module

Multi-scale, multi-operator Green's-function kernel.

Parameters:

Name	Type	Description	Default
latent_dim	int	Latent dimension d_max.	required
n_anchors	int	Number of anchor positions R.	64
n_scales	int	Total number of scales K (split across operators if operator is a sequence).	4
operator	str | Sequence[str]	Single operator name (e.g. "gaussian") or a non-empty sequence of names for a multi-operator configuration.	'gaussian'
sigma_log_range	tuple[float, float]	(low, high) log-scale range used to initialise log_sigma linearly across the K scales (default (-1.5, 1.5)).	(-1.5, 1.5)
anchor_init_std	float	Standard deviation for the Gaussian initialisation of anchor positions (default 0.5).	0.5
null_space	NullSpaceBasis | None	Optional :class:igl.types.NullSpaceBasis (e.g. :class:igl.spectral.ConstantNullSpace) whose evaluate(z) output is concatenated as extra columns to the design matrix. These columns receive their own lstsq weights without Tikhonov shrinkage — useful to give the local kernel a DC mode it doesn't otherwise carry.	None

operator_names property

Names of the operators in registration order.

compute_design_matrix(z, *, gate_mask=None)

Build the design matrix from latent coordinates.

Parameters:

Name	Type	Description	Default
z	Tensor	Latent coordinates of shape [N, d].	required
gate_mask	Tensor | None	Optional [d] binary mask (1 for active dims). Used by Matryoshka random truncation during training. Passing None is equivalent to a mask of all ones.	None

Returns:

Type	Description
Tensor	Design matrix of shape [N, R].

forward(z, *, gate_mask=None)

Alias of :meth:compute_design_matrix.

Solver

igl.core.solver.direct_solve_weights(phi, y, *, l2=0.001)

Solve the Tikhonov-regularised least-squares problem.

The solution is computed via QR (torch.linalg.lstsq) on the stacked system [Φ; √λ I] w ≈ [y; 0] so the regularisation is correctly applied even when Φ is rank-deficient.

Parameters:

Name	Type	Description	Default
phi	Tensor	Design matrix [N, R].	required
y	Tensor	Targets [N, C] or [N, 1].	required
l2	float	Tikhonov coefficient relative to Φ's mean column norm (default 1e-3).	0.001

Returns:

Type	Description
Tensor	w of shape [R, C]. If the solve produces non-finite entries
Tensor	(e.g. catastrophic conditioning), the function emits a
Tensor

Normalization

igl.core.normalization.normalize_phi(phi, mode)

Normalize the design matrix per row.

Parameters:

Name	Type	Description	Default
phi	Tensor	Design matrix of shape [N, R].	required
mode	NormalizeModeLike	A :class:NormalizeMode member or matching string.	required

Returns:

Type	Description
Tensor	The normalised matrix, same shape as phi.

Raises:

Type	Description
IGLConfigError	If mode is not a recognised value.

Loss strategies

igl.core.loss.CrossEntropyLoss

Multiclass cross-entropy with one-hot lstsq targets.

Parameters:

Name	Type	Description	Default
n_classes	int	Number of classes C.	required

Attributes:

Name	Type	Description
higher_is_better	bool	Always True — the metric is accuracy.

curve_score(pred, target)

0/1 classification error rate — used for dimension-curve elbow detection.

Cross-entropy saturates on easy tasks and smears the elbow; error rate is discrete and gives sharper transitions.

loss(pred, target)

Cross-entropy loss; target is one-hot, taken back to class indices.

metric(pred, target)

Top-1 classification accuracy.

target(y)

Convert integer class labels [N] to one-hot float targets [N, C].

igl.core.loss.MSELoss

Mean squared error for scalar or multi-output regression.

Attributes:

Name	Type	Description
higher_is_better	bool	Always False — the metric is MSE.

curve_score(pred, target)

MSE — already lower-is-better and non-saturating; same as metric.

target(y)

Ensure the target is at least 2-D [N, C].

Trainer

igl.core.trainer.MatryoshkaTrainer

Train an :class:IGLModule with Matryoshka VP.

Parameters:

Name	Type	Description	Default
config	MatryoshkaConfig | None	:class:MatryoshkaConfig. Optional — defaults are used when omitted.	None
loss	LossStrategy	:class:LossStrategy describing the task (classification, regression, …).	required
sampler	MatryoshkaSampler | None	Optional explicit :class:MatryoshkaSampler. When None, one is built from config.sampling and config.alpha.	None

fit(module, x_train, y_train, *, x_val=None, y_val=None, extra_losses=())

Fit module on the training tensors and return the history.

Parameters:

Name	Type	Description	Default
module	IGLModule	An :class:IGLModule.	required
x_train	Tensor	Training inputs [N, D].	required
y_train	Tensor	Training targets.	required
x_val	Tensor | None	Optional validation inputs.	None
y_val	Tensor | None	Optional validation targets.	None
extra_losses	Sequence[ExtraLoss]	Optional :class:igl.types.ExtraLoss regularizers — e.g. :class:igl.spd.OrthogonalityPenalty. Each is called per batch (subject to its every frequency); the returned tensor is multiplied by the extra's weight and added to the task loss before backprop.	()

Returns:

Name	Type	Description
A	TrainingHistory

Raises:

Type	Description
IGLConvergenceError	If the training loss becomes non-finite.

igl.core.trainer.TrainingHistory dataclass

Per-epoch training history returned by :meth:MatryoshkaTrainer.fit.