Models

yetanotherspdnet.model — complete classifiers taking a batch of SPD matrices (B, n, n) and returning logits (B, n_classes). They assemble the Layers, optional Batch normalization and, for the residual networks, the Residual blocks blocks. Their constructors expose every option of those layers; the Models and their options guide groups these arguments by role.

SPDnet

SPDNet classifier: [BiMap -> (BatchNorm) -> ReEig] x L -> LogEig -> Vec -> Linear.

RResNet

Flexible multi-stage Riemannian Residual Network on SPD manifold.

GBWBNRResNet

Riemannian Residual Network faithful to the GBWBN experiment architecture.
class SPDnet(
input_dim,
hidden_layers_size,
output_dim,
softmax=False,
reeig_eps=0.001,
bimap_parametrized=True,
bimap_parametrization_mode='static',
bimap_parametrization_options=None,
bimap_n_steps_ref_update=100,
batchnorm=False,
batchnorm_type='mean_only',
batchnorm_mean_type='geometric_arithmetic_harmonic',
batchnorm_mean_options=None,
batchnorm_momentum=0.01,
batchnorm_norm_strategy='classical',
batchnorm_minibatch_mode='constant',
batchnorm_minibatch_momentum=0.01,
batchnorm_minibatch_maxstep=100,
batchnorm_parametrization='softplus',
batchnorm_parametrization_mode='static',
batchnorm_n_steps_ref_update=100,
batchnorm_bw_options=None,
vec_type='vec',
use_logeig=True,
use_autograd=False,
device=device(type='cpu'),
dtype=torch.float64,
generator=None,
)[source]

SPDNet classifier: [BiMap -> (BatchNorm) -> ReEig] x L -> LogEig -> Vec -> Linear.

Implements the architecture of Huang & Van Gool (AAAI 2017), with optional Riemannian batch normalization after each BiMap.

Standard SPDnet model with hidden layers

Parameters:

  • input_dim (int) – Input dimension of SPDNet

  • hidden_layers_size (List[int]) – List of hidden layer sizes

  • output_dim (int) – Output dimension of SPDNet

  • softmax (bool, optional) – Whether to apply softmax to output. Default is False

  • reeig_eps (float, optional) – Regularization value for ReEig. Default is 1e-3

  • bimap_parametrized (bool, optional) – Whether to apply parametrization to enforce manifold constraints in BiMap. Default is True

  • bimap_parametrization_mode (str, optional) – Parametrization mode of BiMap if bimap_parametrized is True. Default is “static”. Choices are: “static” and “dynamic”

  • bimap_parametrization_options (dict, optional) – Options for the parametrization function in BiMap. Default is None

  • bimap_n_steps_ref_update (int, optional) – If bimap_parametrization_mode is “dynamic”, number of steps in between each reference point update. Default is 100

  • batchnorm (bool, optional) – Whether to apply BatchNormSPDMean to hidden layers. Default is False

  • batchnorm_type (str, optional) – The type of batch normalization layer to use. Default is “mean_only”. Choices are: “mean_only” and “mean_var_scalar”

  • batchnorm_mean_type (str, optional) – Choice of SPD mean of the batch normalization. Default is “geometric_arithmetic_harmonic”. Choices are: “affine_invariant”, “log_euclidean”, “arithmetic”, “harmonic”, “geometric_arithmetic_harmonic”, “adaptive_geometric_arithmetic_harmonic”, “bures_wasserstein”

  • batchnorm_mean_options (dict | None, optional) – Options for the SPD mean computation. For affine-invariant mean, one can typically set {‘n_iterations’: 5}. Currently, for others, no options available. Default is None

  • batchnorm_momentum (float, optional) – Momentum for running mean update. Default is 0.01

  • batchnorm_norm_strategy (str, optional) – Strategy for normalization. Default is “classical”. Choices are: “classical” and “minibatch”

  • batchnorm_minibatch_mode (str, optional) – How the minibatch momentum behaves during the training. Default is “constant”. Choices are: “constant”, “decay”, “growth”

  • batchnorm_minibatch_momentum (float, optional) – Momentum for mean regularization in minibatch normalization strategy Default is 0.01

  • batchnorm_minibatch_maxstep (int, optional) – If minibatch_mode is “decay” or “growth”, this is the training step at which the minibatch momentum attains its final value. Default is 100

  • batchnorm_parametrization (str, optional) – Parametrization to apply on covariance bias. Default is “softplus”. Choices are: “softplus”, “exp”

  • batchnorm_parametrization_mode (str, optional) – Parametrization mode. Default is “static”. Choices are: “static” and “dynamic”

  • batchnorm_n_steps_ref_update (int, optional) – If parametrization_mode is “dynamic”, number of steps in between each reference point update. Default is 100

  • batchnorm_bw_options (dict | None, optional) – GBWBN keyword arguments of BatchNormSPDMeanScalarVariance (bw_theta, bw_batch_stats_grad), used when batchnorm_type="mean_var_scalar". Default is None (the layer defaults)

  • vec_type (str, optional) – Whether to use Vec or Vech module. Default is “vec”. Choices are: “vec”, “vech”

  • use_logeig (bool, optional) – Whether to apply LogEig layer before vectorization. Default is True

  • use_autograd (bool | dict, optional) – Use torch autograd for gradient computation. Can be bool for all layers, or dict with keys: ‘bimap’, ‘reeig’, ‘logeig’, ‘batchnorm’, ‘vec’. Note that Vech module always uses manual gradient. Default is False

  • device (torch.device, optional) – Device to run model on. Default is torch.device(‘cpu’)

  • dtype (torch.dtype, optional) – Data type of the layer. Default is torch.float64

  • generator (torch.Generator, optional) – Generator to ensure reproducibility. Default is None

Variables:

  • spdnet_layers (torch.nn.Sequential) – The SPD part of the network (BiMap, BatchNorm, ReEig and LogEig layers).

  • vectorization (Vec or Vech) – Flattens the final symmetric matrices.

  • linear (torch.nn.Linear) – Euclidean classification head.

forward(X)[source]

Forward pass of SPDnet

Parameters:

X (torch.Tensor) – Input tensor of shape (…, input_dim, input_dim)

Returns:

torch.Tensor – Output tensor of shape (…, output_dim)

Return type:

Tensor

register_optimizer_hook(optimizer)[source]

Register optimizer hooks for all layers with dynamic parametrization. This method automatically finds all layers that use dynamic parametrization and registers the appropriate hooks

Parameters:

optimizer (torch.optim.Optimizer) – The optimizer used for training

class RResNet(
input_dim,
hidden_layers_size,
n_residual_blocks,
output_dim,
softmax=False,
reeig=False,
reeig_eps=0.001,
bimap_parametrized=True,
bimap_parametrization_mode='static',
bimap_parametrization_options=None,
bimap_n_steps_ref_update=100,
batchnorm=False,
batchnorm_type='mean_only',
batchnorm_mean_type='affine_invariant',
batchnorm_mean_options=None,
batchnorm_momentum=0.01,
batchnorm_norm_strategy='classical',
batchnorm_minibatch_mode='constant',
batchnorm_minibatch_momentum=0.01,
batchnorm_minibatch_maxstep=100,
batchnorm_parametrization='softplus',
batchnorm_parametrization_mode='static',
batchnorm_n_steps_ref_update=100,
batchnorm_bw_options=None,
spectrum_type='conv1d',
spectrum_hidden_dim=3,
spectrum_n_layers=2,
spectrum_kernel_size=5,
stiefel_parametrization_mode='static',
stiefel_n_steps_ref_update=100,
residual_metric='affine_invariant',
vec_type='vec',
use_logeig=True,
use_autograd=False,
device=device(type='cpu'),
dtype=torch.float64,
generator=None,
)[source]

Flexible multi-stage Riemannian Residual Network on SPD manifold.

Architecture (for each stage i):

BiMap(d_{i-1} -> d_i) -> [ReEig] -> [BatchNorm] -> ResidualBlock x n_residual_blocks[i]

then:

-> LogEig -> Vec/Vech -> Linear -> [Softmax]

Inspired by classical ResNet (multi-stage with dimension changes at each stage boundary), this architecture is more flexible than GBWBNRResNet: it supports multiple BiMap stages, optional ReEig at each stage, and multiple residual blocks per stage.

Parameters:

  • input_dim (int) – Input SPD matrix dimension

  • hidden_layers_size (list[int]) – Dimensions at each stage (after each BiMap)

  • n_residual_blocks (list[int]) – Number of residual blocks at each stage

  • output_dim (int) – Number of output classes

  • softmax (bool, optional) – Apply softmax. Default is False

  • reeig (bool, optional) – Apply ReEig after each BiMap. Default is False

  • reeig_eps (float, optional) – Minimum eigenvalue for ReEig. Default is 1e-3

  • bimap_parametrized (bool, optional) – Enforce Stiefel on BiMap. Default is True

  • bimap_parametrization_mode (str, optional) – “static” or “dynamic”. Default is “static”

  • bimap_parametrization_options (dict | None, optional) – Options for BiMap parametrization. Default is None

  • bimap_n_steps_ref_update (int, optional) – Steps between reference updates. Default is 100

  • batchnorm (bool, optional) – Apply batchnorm at each stage. Default is False

  • batchnorm_type (str, optional) – “mean_only” or “mean_var_scalar”. Default is “mean_only”

  • batchnorm_mean_type (str, optional) – SPD mean type. Default is “affine_invariant”

  • batchnorm_mean_options (dict | None, optional) – Options for mean computation. Default is None

  • batchnorm_momentum (float, optional) – Running mean momentum. Default is 0.01

  • batchnorm_norm_strategy (str, optional) – “classical” or “minibatch”. Default is “classical”

  • batchnorm_minibatch_mode (str, optional) – “constant”, “decay”, or “growth”. Default is “constant”

  • batchnorm_minibatch_momentum (float, optional) – Minibatch momentum. Default is 0.01

  • batchnorm_minibatch_maxstep (int, optional) – Max step for momentum schedule. Default is 100

  • batchnorm_parametrization (str, optional) – “softplus” or “exp”. Default is “softplus”

  • batchnorm_parametrization_mode (str, optional) – “static” or “dynamic”. Default is “static”

  • batchnorm_n_steps_ref_update (int, optional) – Steps between BN reference updates. Default is 100

  • batchnorm_bw_options (dict | None, optional) – GBWBN keyword arguments of BatchNormSPDMeanScalarVariance (bw_theta, bw_batch_stats_grad). Default is None

  • spectrum_type (str, optional) – “conv1d” or “mlp”. Default is “conv1d”

  • spectrum_hidden_dim (int, optional) – Hidden dimension for spectrum network. Default is 3

  • spectrum_n_layers (int, optional) – Hidden layers in spectrum network. Default is 2

  • spectrum_kernel_size (int, optional) – Kernel size for Conv1d. Default is 5

  • stiefel_parametrization_mode (str, optional) – Parametrization mode for Q matrices. Default is “static”

  • stiefel_n_steps_ref_update (int, optional) – Steps between Q reference updates. Default is 100

  • residual_metric (str, optional) – Residual step of the ResidualBlocks: “affine_invariant” (unit-length exponential-map step) or “log_euclidean” (exp(log X + V)). Default is “affine_invariant”

  • vec_type (str, optional) – “vec” or “vech”. Default is “vec”

  • use_logeig (bool, optional) – Apply LogEig before vectorization. Default is True

  • use_autograd (bool | dict, optional) – Autograd control. Bool for all, dict with keys: ‘bimap’, ‘reeig’, ‘logeig’, ‘batchnorm’, ‘vec’, ‘residual’. Default is False

  • device (torch.device, optional) – Device. Default is torch.device(“cpu”)

  • dtype (torch.dtype, optional) – Data type. Default is torch.float64

  • generator (torch.Generator | None, optional) – Generator for reproducibility. Default is None

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(X)[source]

Forward pass.

Parameters:

X (torch.Tensor of shape (..., input_dim, input_dim)) – Input SPD matrices

Returns:

torch.Tensor of shape (..., output_dim) – Output predictions

Return type:

Tensor

register_optimizer_hook(optimizer)[source]

Register optimizer hooks for all dynamic parametrizations.

class GBWBNRResNet(
input_dim,
hidden_dim,
output_dim,
softmax=False,
bimap_parametrized=True,
bimap_parametrization_mode='static',
bimap_parametrization_options=None,
bimap_n_steps_ref_update=100,
batchnorm=True,
batchnorm_type='mean_var_scalar',
batchnorm_mean_type='bures_wasserstein',
batchnorm_mean_options=None,
batchnorm_momentum=0.1,
batchnorm_norm_strategy='classical',
batchnorm_minibatch_mode='constant',
batchnorm_minibatch_momentum=0.01,
batchnorm_minibatch_maxstep=100,
batchnorm_parametrization='softplus',
batchnorm_parametrization_mode='static',
batchnorm_n_steps_ref_update=100,
batchnorm_bw_options=None,
spectrum_type='conv1d',
spectrum_hidden_dim=3,
spectrum_n_layers=2,
spectrum_kernel_size=5,
stiefel_parametrization_mode='static',
stiefel_n_steps_ref_update=100,
residual_metric='affine_invariant',
vec_type='vec',
use_logeig=True,
use_autograd=False,
device=device(type='cpu'),
dtype=torch.float64,
generator=None,
)[source]

Riemannian Residual Network faithful to the GBWBN experiment architecture.

Architecture:

BiMap(input_dim -> hidden_dim) -> [BatchNorm] -> ResidualBlock (spectral vector field + exp map) -> LogEig -> Vec/Vech -> Linear(hidden_dim^2 -> output_dim) -> [Softmax]

This architecture matches the paper experiments (HDM05, NTU60) which use: - A single BiMap for dimension reduction - A single residual block with spectral vector field - No ReEig (eigenvalue rectification not needed before residual block)

The residual block applies a geodesic step on the SPD manifold:

X_new = Exp_X(Q diag(f(spec(X))) Q^T)

where Q is a Stiefel-parametrized orthogonal matrix and f is a learnable spectrum mapping (Conv1d or MLP on eigenvalues).

Parameters:

  • input_dim (int) – Input SPD matrix dimension

  • hidden_dim (int) – Dimension after BiMap (also the residual block dimension)

  • output_dim (int) – Number of output classes

  • softmax (bool, optional) – Apply softmax to output. Default is False

  • bimap_parametrized (bool, optional) – Enforce Stiefel constraints on BiMap. Default is True

  • bimap_parametrization_mode (str, optional) – “static” or “dynamic” parametrization. Default is “static”

  • bimap_parametrization_options (dict | None, optional) – Options for BiMap parametrization. Default is None

  • bimap_n_steps_ref_update (int, optional) – Steps between reference updates for dynamic BiMap. Default is 100

  • batchnorm (bool, optional) – Apply batch normalization. Default is True

  • batchnorm_type (str, optional) – “mean_only” or “mean_var_scalar”. Default is “mean_var_scalar”

  • batchnorm_mean_type (str, optional) – SPD mean type for batchnorm. Default is “bures_wasserstein”

  • batchnorm_mean_options (dict | None, optional) – Options for mean computation. Default is None

  • batchnorm_momentum (float, optional) – Running mean momentum. Default is 0.1

  • batchnorm_norm_strategy (str, optional) – “classical” or “minibatch”. Default is “classical”

  • batchnorm_minibatch_mode (str, optional) – “constant”, “decay”, or “growth”. Default is “constant”

  • batchnorm_minibatch_momentum (float, optional) – Minibatch momentum. Default is 0.01

  • batchnorm_minibatch_maxstep (int, optional) – Max step for momentum schedule. Default is 100

  • batchnorm_parametrization (str, optional) – “softplus” or “exp”. Default is “softplus”

  • batchnorm_parametrization_mode (str, optional) – “static” or “dynamic”. Default is “static”

  • batchnorm_n_steps_ref_update (int, optional) – Steps between reference updates for BN. Default is 100

  • batchnorm_bw_options (dict | None, optional) – GBWBN keyword arguments of BatchNormSPDMeanScalarVariance (bw_theta, bw_batch_stats_grad). Default is None

  • spectrum_type (str, optional) – “conv1d” or “mlp” for spectral vector field. Default is “conv1d”

  • spectrum_hidden_dim (int, optional) – Hidden dimension for spectrum network. Default is 3

  • spectrum_n_layers (int, optional) – Number of hidden layers in spectrum network. Default is 2

  • spectrum_kernel_size (int, optional) – Kernel size for Conv1d spectrum. Default is 5

  • stiefel_parametrization_mode (str, optional) – Parametrization mode for Q matrix. Default is “static”

  • stiefel_n_steps_ref_update (int, optional) – Steps between Q reference updates. Default is 100

  • residual_metric (str, optional) – Residual step of the ResidualBlocks: “affine_invariant” (unit-length exponential-map step) or “log_euclidean” (exp(log X + V)). Default is “affine_invariant”

  • vec_type (str, optional) – “vec” or “vech”. Default is “vec”

  • use_logeig (bool, optional) – Apply LogEig before vectorization. Default is True

  • use_autograd (bool | dict, optional) – Autograd control. Bool for all, dict with keys: ‘bimap’, ‘logeig’, ‘batchnorm’, ‘vec’, ‘residual’. Default is False

  • device (torch.device, optional) – Device. Default is torch.device(“cpu”)

  • dtype (torch.dtype, optional) – Data type. Default is torch.float64

  • generator (torch.Generator | None, optional) – Generator for reproducibility. Default is None

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(X)[source]

Forward pass.

Parameters:

X (torch.Tensor of shape (..., input_dim, input_dim)) – Input SPD matrices

Returns:

torch.Tensor of shape (..., output_dim) – Output predictions

Return type:

Tensor

register_optimizer_hook(optimizer)[source]

Register optimizer hooks for all dynamic parametrizations.