igl.nn

Bare PyTorch entry point for custom training loops.

igl.nn.module.IGLModule

Bases: Module

End-to-end IGL model: x → z → Φ → Φ w + b.

The readout weights source_weights are not learned by gradient descent — they are refreshed in closed form by :func:igl.direct_solve_weights (called by :class:MatryoshkaTrainer). The bias is a learnable parameter; the encoder and Green-kernel parameters are too — only the readout is closed-form.

Parameters:

Name	Type	Description	Default
input_dim	int	Ambient input dimension D.	required
max_dim	int	Latent dimension d_max. Always wins over config.max_dim if both are explicit (raises on mismatch).	required
output_dim	int	Output dimension (C classes or regression outputs).	required
n_anchors	int | None	Number of anchors R in the Green kernel. None defers to config.kernel.n_anchors (or :class:KernelConfig's default of 64).	None
n_scales	int | None	Number of kernel scales K. None defers to config.kernel.n_scales (default 4).	None
operator	OperatorNameLike | None	Single operator name. None defers to config.kernel.operator (default :data:igl.OperatorName.GAUSSIAN). For multi-operator setups (e.g. ("gaussian", "helmholtz")), build the kernel via :class:KernelConfig and pass through config.	None
encoder	EncoderProtocol | None	Optional pre-built encoder satisfying :class:igl.types.EncoderProtocol.	None
encoder_config	EncoderConfig | None	Optional :class:EncoderConfig from which to build an :class:MLPEncoder. Mutually exclusive with encoder.	None
normalize	NormalizeModeLike | None	Φ-normalization mode. None defers to config.kernel.normalize (default :data:igl.NormalizeMode.NW).	None
normalize_input	bool	If True, prepend an nn.BatchNorm1d(affine=False) to the encoder. Stabilises training when ambient input dimensions have wildly different scales. Default False — appropriate for inputs that have been pre-normalised (e.g. log-Eig tangent vectors from :class:igl.spd.LogEigVectorizer).	False
config	IGLConfig | None	Optional top-level :class:IGLConfig. When provided, populates defaults for any field passed as None. Explicit per-field kwargs always win.	None

Raises:

Type	Description
IGLConfigError	For dimension mismatches, conflicting parameters, non-positive dimensions, or an explicit max_dim that contradicts config.max_dim.

design_matrix(x, *, gate_mask=None)

Compute the normalised design matrix Φ from raw input x.

forward(x, *, gate_mask=None)

Forward pass returning Φ w + b of shape [N, output_dim].

latent(x)

Return the latent encoding z = Encoder(x).

set_source_weights(weights)

Replace the closed-form readout weights with weights [R, C].