holonomy-lib 0.8.0__py3-none-any.whl

holonomy_lib/spectral/magnetic.py

@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Magnetic Laplacian for directed and signed-directed graphs.
+
+The standard real-valued graph Laplacians (`spectral.laplacian.*`)
+assume a symmetric adjacency. For a directed graph the asymmetry
+encodes information that any symmetrization throws away. The
+**magnetic Laplacian** (Lieb-Loss 1993; Fanuel et al. 2017; Furutani
+et al. 2020) recovers that information by attaching a complex phase
+factor `e^{i · 2π · q · (A_{ij} - A_{ji})}` to each edge, while keeping
+the magnitude structure symmetric. The result is a Hermitian operator
+whose eigenvalues are real and whose eigenvectors are complex; the
+phase of those eigenvectors carries the directional information.
+
+Definition (combinatorial form):
+
+  A_s   = (A + A^T) / 2                                (symmetrized)
+  D_s   = diag(Σ_j A_s[i, j])                          (symmetric degree)
+  H     = exp(i · 2π · q · (A - A^T))                  (Hermitian phase factor)
+  L^(q) = D_s - H ⊙ A_s
+
+For symmetric A this reduces to L = D - A regardless of q. For purely
+directed A (entries in {0, 1}, A ≠ A^T) the phase encodes "flow
+direction": q = 1/4 separates directed eigenmodes most clearly
+(Furutani 2020, §5).
+
+Four forms exposed:
+  combinatorial(A, q)                  : L^(q) = D_s − H ⊙ A_s
+  symmetric_normalized(A, q)           : L_sym^(q) = I − D_s^{−1/2} (H ⊙ A_s) D_s^{−1/2}
+  sign_magnetic_combinatorial(A, q)    : signed-directed analog,
+                                          unifies Kunegis signed + magnetic
+  sign_magnetic_symmetric_normalized(A, q)  : normalized signed-directed
+
+The signed forms implement MSGNN (He, Perlmutter, Reinert, Cucuringu
+2022, equations 1 and 2). They use the signed symmetric adjacency
+A_s = (A + A^T)/2, absolute degree D_abs[i,i] = sum_j
+(|A[i,j]| + |A[j,i]|)/2, and phase exp(i 2π q (A - A^T)).
+Both operators are positive semidefinite; the normalized spectrum
+lies in [0, 2]. Nonnegative input gives the ordinary magnetic
+Laplacian. Symmetric signed input gives the signed Laplacian for
+any charge. At q = 0 the phase disappears, leaving D_abs - A_s.
+For opposite-sign reciprocal edges, D_abs differs from sum_j |A_s|;
+this distinction is part of MSGNN's definition.
+
+All four functions return a complex Hermitian tensor of shape
+(B, n, n). Use `torch.linalg.eigh` on the result : its real-eigenvalue
+output is the spectrum and its complex eigenvectors are the
+directed-graph modes.
+
+References:
+  Lieb, E. H., Loss, M. (1993). Fluxes, Laplacians, and Kasteleyn's
+    theorem. Duke Mathematical Journal 71(2):337–363. The original
+    magnetic / flux-discrete Laplacian on graphs.
+  Fanuel, M., Alaiz, C. M., Suykens, J. A. K. (2017). Magnetic
+    eigenmaps for the visualization of directed networks. Applied and
+    Computational Harmonic Analysis 44(1):189–199. The modern spectral-
+    embedding application.
+  Furutani, S., Shibahara, T., Akiyama, M., Hato, K., Aida, M. (2020).
+    Graph Signal Processing for Directed Graphs based on the Hermitian
+    Laplacian. Journal of Machine Learning Research 21(122):1–37.
+    Gives the q = 1/4 default and the normalization conventions used
+    here. Section 5 covers the spectral interpretation.
+  Kunegis, J., Schmidt, S., Lommatzsch, A., Lerner, J., De Luca, E. W.,
+    Albayrak, S. (2010). Spectral analysis of signed graphs for
+    clustering, prediction and visualization. SDM 2010. The signed
+    Laplacian that the q = 0 signed-magnetic case reduces to.
+  He, Y., Perlmutter, M., Reinert, G., Cucuringu, M. (2022). MSGNN:
+    A Spectral Graph Neural Network Based on a Novel Magnetic Signed
+    Laplacian. LoG 2022, PMLR 198, §3.2, equations 1 and 2.
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+from holonomy_lib._graph_utils import drop_self_loops
+
+# Default magnetic charge q ∈ [0, 1) per Furutani et al. (2020), §5.
+# `q = 1/4` is the value that maximally separates the directed
+# eigenmodes for a cycle and is therefore the standard literature
+# default. **Scale of validity**: dimensionless ratio of magnetic flux
+# units; does not depend on n. Cataloged as `MAGNETIC_CHARGE_DEFAULT`.
+MAGNETIC_CHARGE_DEFAULT: float = 0.25
+
+
+def combinatorial(
+    A: torch.Tensor, q: float = MAGNETIC_CHARGE_DEFAULT,
+) -> torch.Tensor:
+    """Combinatorial magnetic Laplacian L^(q) = D_s − H ⊙ A_s.
+
+    Args:
+      A: (B, n, n) weighted adjacency. May be non-symmetric. Entries
+        may be negative (signed-directed graphs); the symmetrized
+        adjacency `A_s = (A + A^T)/2` keeps the "edge presence",
+        and the antisymmetric part `A − A^T` enters via the phase.
+      q: magnetic charge in [0, 1). Default 1/4 per Furutani 2020 §5.
+
+    Returns:
+      L: (B, n, n) complex Hermitian Laplacian. Use `torch.linalg.eigh`
+        to get real eigenvalues + complex eigenvectors.
+
+    References:
+      Furutani et al. (2020), eq. 8.
+      Lieb-Loss (1993).
+    """
+    _validate_real_adjacency(A, q)
+    A = drop_self_loops(A)
+    A_s = 0.5 * (A + A.mT)                       # symmetrized magnitude
+    D_s = A_s.sum(dim=-1)                         # (B, n) symmetric degree
+
+    H_times_As = _magnetic_phase_times_adj(A, A_s, q)
+
+    # D_s on the diagonal, embedded in the complex dtype.
+    D_diag = torch.diag_embed(D_s).to(H_times_As.dtype)
+    return D_diag - H_times_As
+
+
+def symmetric_normalized(
+    A: torch.Tensor, q: float = MAGNETIC_CHARGE_DEFAULT,
+) -> torch.Tensor:
+    """Symmetric-normalized magnetic Laplacian.
+
+    L_sym^(q) = I − D_s^{−1/2} (H ⊙ A_s) D_s^{−1/2}
+
+    For nonnegative A, spectrum ⊂ [0, 2] regardless of q (Furutani 2020, Prop. 1). Use
+    this form for spectral embeddings of directed graphs; the
+    eigenvectors at the bottom-k eigenvalues are the directed analog
+    of Laplacian eigenmaps.
+
+    Args:
+      A: (B, n, n) nonnegative weighted adjacency. May be non-symmetric.
+      q: magnetic charge in [0, 1).
+
+    Returns:
+      L_sym^(q): (B, n, n) complex Hermitian, spectrum in [0, 2].
+
+    References:
+      Furutani et al. (2020), Definition 4 and Prop. 1.
+    """
+    _validate_real_adjacency(A, q)
+    A = drop_self_loops(A)
+    A_s = 0.5 * (A + A.mT)
+    D_s = A_s.sum(dim=-1)                         # (B, n)
+
+    # Moore-Penrose pseudoinverse handling for isolated nodes, the same
+    # convention as `holonomy_lib.spectral.laplacian.symmetric_normalized`.
+    # The clamp keeps rsqrt finite on the branch `where` throws away, so
+    # an isolated node never puts an inf into the autograd graph
+    floor = torch.finfo(A.dtype).tiny
+    safe_D = D_s.clamp(min=floor)
+    d_inv_sqrt = torch.where(
+        D_s > 0, torch.rsqrt(safe_D), torch.zeros_like(D_s),
+    )                                              # (B, n)
+
+    H_times_As = _magnetic_phase_times_adj(A, A_s, q)
+
+    # D^{-1/2} (H ⊙ A_s) D^{-1/2} as an outer product of the two scalings.
+    # The real scale has to be cast to complex before it multiplies the
+    # complex phase matrix
+    scale = (
+        d_inv_sqrt.unsqueeze(dim=-1) * d_inv_sqrt.unsqueeze(dim=-2)
+    ).to(H_times_As.dtype)
+    normalized = H_times_As * scale
+
+    n = A.shape[-1]
+    eye = torch.eye(n, device=A.device, dtype=H_times_As.dtype).expand_as(
+        normalized,
+    )
+    return eye - normalized
+
+
+# ============================================================
+# Sign-magnetic Laplacian (signed-directed graphs)
+# ============================================================
+
+
+def sign_magnetic_combinatorial(
+    A: torch.Tensor, q: float = MAGNETIC_CHARGE_DEFAULT,
+) -> torch.Tensor:
+    """Sign-magnetic combinatorial Laplacian for signed-directed graphs.
+
+    L^(q,σ) = D_|.| − exp(i · 2π · q · (A − A^T)) ⊙ A_s^signed
+
+    where:
+      A_s^signed = (A + A^T) / 2                   (signed symmetric part)
+      A_s^|.|    = (|A| + |A|^T) / 2               (magnitude symmetric part)
+      D_|.|      = diag(Σ_j A_s^|.|[i, j])         (signless degree, à la
+                                                    Kunegis 2010)
+
+    Phase uses signed A, as in MSGNN equation 1. At q = 0 the phase
+    disappears. The absolute degree is computed before symmetrization,
+    so opposite-sign reciprocal edges still contribute to the degree.
+
+    Reduces to:
+      magnetic.combinatorial(A, q)   if A ≥ 0      (signs irrelevant)
+      laplacian.signed(A)            if A = A^T    (Θ ≡ 0, signs visible)
+      laplacian.combinatorial(A)     if A ≥ 0 ∧ A = A^T
+
+    Args:
+      A: (B, n, n) real-valued adjacency. May be non-symmetric and may
+        have negative entries.
+      q: magnetic charge in [0, 1). Default 1/4.
+
+    Returns:
+      L: (B, n, n) complex Hermitian positive-semidefinite Laplacian.
+
+    References:
+      He, Perlmutter, Reinert, Cucuringu (2022). MSGNN. LoG 2022,
+        PMLR 198, §3.2, equation 1 and Theorem 1.
+      Kunegis et al. (2010) for the q = 0 (signed-undirected) reduction.
+    """
+    _validate_real_adjacency(A, q)
+    A = drop_self_loops(A)
+    abs_A = A.abs()
+    A_s_signed = 0.5 * (A + A.mT)
+    A_s_abs = 0.5 * (abs_A + abs_A.mT)
+    D_abs = A_s_abs.sum(dim=-1)                       # (B, n)
+
+    H_times_As = _magnetic_phase_times_adj(A, A_s_signed, q)
+    D_diag = torch.diag_embed(D_abs).to(H_times_As.dtype)
+    return D_diag - H_times_As
+
+
+def sign_magnetic_symmetric_normalized(
+    A: torch.Tensor, q: float = MAGNETIC_CHARGE_DEFAULT,
+) -> torch.Tensor:
+    """Sign-magnetic symmetric-normalized Laplacian.
+
+    L_sym^(q,σ) = I − D_|.|^{−1/2} (exp(iΘ) ⊙ A_s^signed) D_|.|^{−1/2}
+
+    where Θ_{ij} = 2π · q · (A_{ij} − A_{ji}) and
+    D_|.|[i,i] = sum_j (|A[i,j]| + |A[j,i]|)/2. Use this form for
+    spectral embeddings of signed-directed graphs; the eigenvectors at
+    the bottom-k eigenvalues are the signed-directed analog of
+    Laplacian eigenmaps.
+
+    Args:
+      A: (B, n, n) real-valued adjacency, may be non-symmetric and signed.
+      q: magnetic charge in [0, 1).
+
+    Returns:
+      L_sym^(q,σ): (B, n, n) complex Hermitian, spectrum in [0, 2].
+        Isolated nodes have diagonal 1 under the pseudoinverse convention.
+
+    References:
+      He, Perlmutter, Reinert, Cucuringu (2022). MSGNN. LoG 2022,
+        PMLR 198, §3.2, equation 2 and Theorems 1 and 2.
+    """
+    _validate_real_adjacency(A, q)
+    A = drop_self_loops(A)
+    abs_A = A.abs()
+    A_s_signed = 0.5 * (A + A.mT)
+    A_s_abs = 0.5 * (abs_A + abs_A.mT)
+    D_abs = A_s_abs.sum(dim=-1)                       # (B, n)
+
+    # Same pseudoinverse handling as `laplacian.symmetric_normalized` and
+    # `magnetic.symmetric_normalized`: isolated nodes get d^{-1/2} = 0.
+    floor = torch.finfo(A.dtype).tiny
+    safe_D = D_abs.clamp(min=floor)
+    d_inv_sqrt = torch.where(
+        D_abs > 0, torch.rsqrt(safe_D), torch.zeros_like(D_abs),
+    )                                                  # (B, n)
+
+    H_times_As = _magnetic_phase_times_adj(A, A_s_signed, q)
+
+    scale = (
+        d_inv_sqrt.unsqueeze(dim=-1) * d_inv_sqrt.unsqueeze(dim=-2)
+    ).to(H_times_As.dtype)
+    normalized = H_times_As * scale
+
+    n = A.shape[-1]
+    eye = torch.eye(n, device=A.device, dtype=H_times_As.dtype).expand_as(
+        normalized,
+    )
+    return eye - normalized
+
+
+# ============================================================
+# Internal helpers
+# ============================================================
+
+
+def _validate_real_adjacency(A: torch.Tensor, q: float) -> None:
+    """Shared input validation for the magnetic Laplacian primitives.
+
+    Takes the adjacency and charge, returns nothing, raises `ValueError`
+    if `A` is not square in its last two dims, is not a real floating
+    dtype (complex and integer tensors both fail), or `q` is outside
+    [0, 1). Complex `A` is rejected outright: the phase factor
+    `H = exp(i · 2π · q · (A − A^T))` is only defined for real
+    antisymmetric arguments. Passing a complex `A` would let
+    `torch.cos`/`torch.sin` produce complex outputs and
+    `torch.complex(cos, sin)` would raise an opaque "expected real
+    tensors" error deep inside the helper.
+    """
+    if A.ndim < 2 or A.shape[-1] != A.shape[-2]:
+        raise ValueError(
+            f"A must be (..., n, n); got A.shape={tuple(A.shape)}"
+        )
+    if not A.is_floating_point():
+        raise ValueError(
+            f"A must be a real floating-point tensor; got dtype={A.dtype}. "
+            f"The magnetic Laplacian's phase factor is defined for real "
+            f"adjacencies only."
+        )
+    if not (0.0 <= q < 1.0):
+        raise ValueError(f"magnetic charge q must be in [0, 1), got {q}")
+
+
+def _magnetic_phase_times_adj(
+    A: torch.Tensor, A_s: torch.Tensor, q: float,
+) -> torch.Tensor:
+    """Return H ⊙ A_s where H_{ij} = exp(i · 2π · q · (A_{ij} - A_{ji})).
+
+    Takes the real adjacency `A` (for the phase) and the already
+    symmetrized `A_s` (signed or unsigned, the caller picks), both
+    `(..., n, n)`, and returns one complex tensor of the same shape. For
+    symmetric A the phase is identically 1 and the result reduces to
+    A_s + 0j, but we still pay for building the phase. For q = 0 the
+    phase is also identically 1, and that case skips the trig entirely.
+    """
+    if q == 0.0:
+        # no phase at all, so the answer is just A_s cast to complex
+        complex_dtype = _matching_complex_dtype(A.dtype)
+        return A_s.to(complex_dtype)
+
+    # the antisymmetric part A - A^T carries the direction of each edge.
+    # For a symmetric input it is all zeros, the phase is 1 everywhere,
+    # and q has no effect, which is the reduction the module promises
+    asym = A - A.mT                                # (B, n, n)
+    angle = (2.0 * math.pi * q) * asym             # (B, n, n) real
+    phase = torch.complex(torch.cos(angle), torch.sin(angle))
+    complex_dtype = phase.dtype
+    return phase * A_s.to(complex_dtype)
+
+
+def _matching_complex_dtype(real_dtype: torch.dtype) -> torch.dtype:
+    """Pick a complex dtype matching the precision of a real dtype.
+
+    float64 maps to complex128 and float32 to complex64. Anything else
+    (half, bfloat16) goes up to complex64, since half-precision complex
+    support in torch is thin.
+    """
+    if real_dtype == torch.float64:
+        return torch.complex128
+    if real_dtype == torch.float32:
+        return torch.complex64
+    return torch.complex64

holonomy_lib/spectral/spectral_dimension.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Spectral dimension from a graph / operator Laplacian spectrum.
+
+The spectral dimension `d_s` is the exponent governing the small-time decay of
+the heat-kernel return probability:
+
+    p(t) = (1/n) Σ_i exp(-t·λ_i)  ~  t^(-d_s/2)   as t → 0+,
+
+equivalently `d_s = -2 · d log p / d log t`. It need not be an integer (fractals,
+multifractal media) and on a finite graph it is read off as the slope of
+`log p` against `log t` over a scaling window: outside that window finite-size
+effects flatten it (`p → (#zero modes)/n` as `t → ∞`, biasing `d_s` toward 0).
+
+This estimates `d_s` as the least-squares slope of `log p(t)` against `log t`
+over a caller-supplied set of times `t`; choose them inside the power-law
+window. The input is the Laplacian spectrum (e.g. from
+`holonomy_lib.spectral.laplacian` + an eigensolver), so the same routine serves
+graphs, fractal approximants, and discretized continua.
+
+References:
+  Rammal, R., Toulouse, G. (1983). Random walks on fractal structures and
+    percolation clusters. J. Physique Lett. 44(1):L13-L22 (spectral dimension).
+  Durhuus, B., Jonsson, T., Wheater, J. F. (2007). The spectral dimension of
+    generic trees. J. Stat. Phys. 128:1237-1260 (return-probability form).
+  Hambly, B. M., Kigami, J., Kumagai, T. (2002). Multifractal formalisms for
+    the local spectral and walk dimensions. Math. Proc. Camb. Phil. Soc.
+    132:555-571 (local / pointwise version).
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+
+def spectral_dimension(
+    eigenvalues: torch.Tensor, t: torch.Tensor,
+) -> torch.Tensor:
+    """Spectral dimension `d_s = -2 · slope of log p(t) vs log t`, where
+    `p(t) = mean_i exp(-t·λ_i)` is the heat-kernel return probability.
+
+    Args:
+      eigenvalues: `(B, n)` Laplacian eigenvalues, `>= 0` (float-noise negatives
+        are clamped to 0). A `(n,)` input is treated as `B = 1`.
+      t: `(T,)` strictly positive sample times, `T >= 2`. Choose them inside the
+        power-law window: small enough that many modes contribute, large enough
+        that the spectral gap has not yet flattened `p`.
+    Returns:
+      `(B,)` estimated spectral dimension (a `(n,)` input returns shape `()`).
+
+    Notes:
+      `d_s` is a fitted asymptotic exponent, not exact on a finite spectrum: as
+      `t → ∞`, `p → (#zero modes)/n`, so an over-large `t` biases `d_s` toward 0.
+      See the module docstring for the window caveat.
+
+    References:
+      Rammal-Toulouse (1983); Durhuus-Jonsson-Wheater (2007).
+    """
+    if t.ndim != 1 or t.shape[0] < 2:
+        raise ValueError(
+            f"t must be a 1-D tensor of at least 2 sample times, got shape "
+            f"{tuple(t.shape)}"
+        )
+    if eigenvalues.ndim < 1:
+        raise ValueError(
+            f"eigenvalues must have a mode axis (ndim >= 1), got shape "
+            f"{tuple(eigenvalues.shape)}"
+        )
+    if eigenvalues.shape[-1] == 0:
+        raise ValueError("eigenvalues must contain at least one mode")
+    if not eigenvalues.is_floating_point() or not t.is_floating_point():
+        raise ValueError("eigenvalues and t must have real floating-point dtypes")
+    if not torch.isfinite(t).all() or (t <= 0).any():
+        raise ValueError("t must be finite and strictly positive")
+    if not torch.isfinite(eigenvalues).all():
+        raise ValueError("eigenvalues must be finite")
+
+    # a lone (n,) spectrum gets a batch axis of 1 here and loses it at the
+    # end. The clamp removes tiny negative eigenvalues from the eigensolver,
+    # which would otherwise make exp(-t·λ) grow with t
+    squeeze = eigenvalues.ndim == 1
+    lam = (eigenvalues.unsqueeze(0) if squeeze else eigenvalues).clamp(min=0.0)
+
+    # least-squares slope of log p against log t, per batch element. The
+    # slope is Σ (x - x̄)(y - ȳ) / Σ (x - x̄)², with x = log t shared by every
+    # batch element, so x is centered and its variance computed once
+    log_t = torch.log(t)                                    # (T,)
+    lt_centered = log_t - log_t.mean()                      # (T,)
+    variance = lt_centered.square().sum()
+    # all t equal (repeated values) means there is no slope to fit
+    if variance == 0:
+        raise ValueError("t must have nonzero log-time variance")
+    # Keep the sum in log space, since valid late times can underflow
+    # every exp(-t * lambda) even though the fitted slope is finite.
+    log_p = torch.logsumexp(-lam.unsqueeze(-2) * t.unsqueeze(-1), dim=-1)
+    log_p = log_p - math.log(lam.shape[-1])               # mean, not sum
+    lp_centered = log_p - log_p.mean(dim=-1, keepdim=True)  # (B, T)
+    slope = (lp_centered * lt_centered).sum(dim=-1) / variance
+    d_s = -2.0 * slope
+
+    return d_s.squeeze(0) if squeeze else d_s

holonomy_lib/tensor_calculus/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""holonomy_lib.tensor_calculus: multilinear algebra primitives.
+
+Currently implemented:
+  mode_product(T, A, axis): n-mode product T ×_axis A.
+  mode_unfolding(T, axis): matricize T by moving one axis to position 1,
+    after the batch axis.
+  hosvd(T, ranks, mode): truncated Higher-Order SVD.
+
+Planned:
+  CP / Tucker decompositions with ALS, Tensor-Train, manifold-valued
+  tensor fields, Einstein notation helpers.
+"""
+
+from holonomy_lib.tensor_calculus.decomposition import (
+    hosvd,
+    mode_product,
+    mode_unfolding,
+)
+
+__all__ = ["hosvd", "mode_product", "mode_unfolding"]

holonomy_lib/tensor_calculus/decomposition.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Tensor decompositions: HOSVD and the n-mode product machinery.
+
+This module assumes the leading dimension of every tensor is a batch
+dimension. So a tensor of order d is stored as a tensor of shape
+`(B, n_1, n_2, ..., n_d)` where B is the batch size. The "tensor modes"
+are axes 1 through d (axis 0 is batch).
+
+Operations implemented:
+
+  mode_product(T, A, axis)
+      n-mode product T ×_axis A. Contracts `T`'s `axis`-th dimension with
+      the last dimension of `A` (Kolda-Bader 2009 convention).
+
+  mode_unfolding(T, axis)
+      Matricize T by moving `axis` to position 1 and flattening the rest.
+      Output shape `(B, n_axis, prod_of_other_modes)`.
+
+  hosvd(T, ranks, mode)
+      Truncated Higher-Order SVD (De Lathauwer-De Moor-Vandewalle 2000).
+      Returns (core, factors). Each factor is the top-r_k left singular
+      vectors of T's mode-k unfolding.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from typing import Literal
+
+import torch
+
+from holonomy_lib.algebra.linear import truncated_svd
+
+
+def mode_product(
+    T: torch.Tensor, A: torch.Tensor, axis: int
+) -> torch.Tensor:
+    """n-mode product T ×_axis A.
+
+    Contracts axis `axis` of T (size n_axis) with the **last** axis of A
+    (also size n_axis), producing a tensor where axis `axis` has size
+    A.shape[-2] instead. Kolda-Bader (2009) §2.5 convention.
+
+    Args:
+      T: (B, n_1, ..., n_d).
+      A: (B, j, n_axis); last axis must match T's `axis`-th axis.
+      axis: which axis of T to contract, in [1, T.ndim − 1] (axis 0 is batch).
+
+    Returns:
+      Tensor of shape (B, ..., j, ...), where size j appears at position `axis`.
+
+    References:
+      Kolda, T. G., Bader, B. W. (2009). Tensor decompositions and
+        applications. SIAM Review 51(3):455–500, §2.5.
+    """
+    if axis <= 0 or axis >= T.ndim:
+        raise ValueError(
+            f"axis must be in [1, {T.ndim - 1}] (axis 0 is batch), got {axis}"
+        )
+    if A.ndim != 3:
+        raise ValueError(
+            f"A must be 3-D (B, j, n_axis); got A.shape={tuple(A.shape)}"
+        )
+    if A.shape[0] != T.shape[0]:
+        raise ValueError(
+            f"batch sizes disagree: T has B={T.shape[0]}, A has B={A.shape[0]}"
+        )
+    if A.shape[-1] != T.shape[axis]:
+        raise ValueError(
+            f"size mismatch: A.shape[-1]={A.shape[-1]} must equal "
+            f"T.shape[{axis}]={T.shape[axis]}"
+        )
+
+    B = T.shape[0]
+    n_axis = T.shape[axis]
+    j = A.shape[-2]
+
+    # Move the contracted axis of T to the last position, then reshape
+    # so that the contracted axis is the inner dim of a 2-D matmul.
+    T_perm = T.movedim(axis, -1)              # (B, ..., n_axis)
+    # Collapse the untouched modes into one K-sized axis.
+    other_modes = math.prod(T_perm.shape[1:-1])
+    T_flat = T_perm.reshape(B, other_modes, n_axis)
+    # Multiply: (B, K, n_axis) @ (B, n_axis, j) → (B, K, j)
+    out_flat = torch.bmm(T_flat, A.mT)        # uses A.mT = (B, n_axis, j)
+    # Undo the collapse. The untouched modes are back in their original order.
+    middle = list(T_perm.shape[1:-1])
+    out_perm = out_flat.reshape(B, *middle, j)
+    # Move the new (size-j) axis from last back to position `axis`:
+    return out_perm.movedim(-1, axis)
+
+
+def mode_unfolding(T: torch.Tensor, axis: int) -> torch.Tensor:
+    """Matricize T along `axis`: move `axis` to position 1, flatten the rest.
+
+    Other modes retain their original order and the last varies fastest
+    across columns (row-major ordering).
+
+    Args:
+      T: (B, n_1, ..., n_d).
+      axis: in [1, T.ndim − 1].
+
+    Returns:
+      (B, n_axis, prod of other tensor modes).
+
+    References:
+      Kolda, T. G., Bader, B. W. (2009), §2.4; mode-n matricization.
+    """
+    if axis <= 0 or axis >= T.ndim:
+        raise ValueError(
+            f"axis must be in [1, {T.ndim - 1}] (axis 0 is batch), got {axis}"
+        )
+    B = T.shape[0]
+    n_axis = T.shape[axis]
+    T_perm = T.movedim(axis, 1)  # (B, n_axis, ...)
+    return T_perm.reshape(B, n_axis, math.prod(T_perm.shape[2:]))
+
+
+def hosvd(
+    T: torch.Tensor,
+    ranks: Sequence[int],
+    mode: Literal["exact", "randomized"] = "exact",
+    generator: torch.Generator | None = None,
+) -> tuple[torch.Tensor, list[torch.Tensor]]:
+    """Truncated Higher-Order SVD (HOSVD).
+
+    For a tensor T ∈ R^{B × n_1 × ... × n_d}, returns factors
+    {U_k}_{k=1..d} and a core G such that
+
+        T ≈ G ×_1 U_1 ×_2 U_2 ×_3 ... ×_d U_d
+
+    where U_k has shape (B, n_k, r_k) with orthonormal columns and G
+    has shape (B, r_1, ..., r_d). The factors are taken as the top-r_k
+    left singular vectors of T's mode-k unfolding; the core is then
+
+        G = T ×_1 U_1ᵀ ×_2 U_2ᵀ ×_3 ... ×_d U_dᵀ.
+
+    Truncated HOSVD is in general **not** the best rank-(r_1,...,r_d)
+    Tucker approximation (that requires HOOI / ALS), but it is a
+    quasi-optimal initializer and is itself a useful approximation in
+    practice; see Vannieuwenhoven et al. (2012) for analysis.
+
+    Args:
+      T: (B, n_1, ..., n_d). Must have ndim ≥ 2 (one batch dim + ≥1 mode).
+      ranks: tuple of length d giving the truncation rank per tensor mode.
+        Each rank must be in [1, min(n_k, product of the other mode sizes)],
+        the available rank of that mode's reduced SVD.
+      mode: "exact" or "randomized"; passed through to `truncated_svd`.
+      generator: PyTorch RNG, forwarded to randomized SVDs.
+
+    Returns:
+      core: (B, r_1, ..., r_d).
+      factors: list of d tensors, factors[k-1] of shape (B, n_k, r_k).
+
+    References:
+      De Lathauwer, L., De Moor, B., Vandewalle, J. (2000). A multilinear
+        singular value decomposition. SIAM J. Matrix Anal. Appl.
+        21(4):1253–1278.
+      Vannieuwenhoven, N., Vandebril, R., Meerbergen, K. (2012). A new
+        truncation strategy for the higher-order singular value
+        decomposition. SIAM J. Sci. Comput. 34(2):A1027–A1052.
+      Kolda, T. G., Bader, B. W. (2009), §4.2; Tucker decomposition.
+    """
+    if T.ndim < 2:
+        raise ValueError(
+            f"T must have ≥1 batch dim and ≥1 tensor mode (ndim ≥ 2); "
+            f"got T.shape={tuple(T.shape)}"
+        )
+    d = T.ndim - 1  # number of tensor modes
+    if len(ranks) != d:
+        raise ValueError(
+            f"len(ranks)={len(ranks)} must equal tensor order d={d}"
+        )
+    for k, r_k in enumerate(ranks):
+        n_k = T.shape[k + 1]
+        other_modes = math.prod(T.shape[1:k + 1] + T.shape[k + 2:])
+        # The mode-k unfolding of each member is (n_k, other_modes), so its
+        # rank cannot exceed the smaller of the two.
+        max_rank = min(n_k, other_modes)
+        if r_k <= 0 or r_k > max_rank:
+            raise ValueError(
+                f"ranks[{k}]={r_k} must be in [1, {max_rank}]; "
+                f"mode {k + 1} unfolding has shape ({n_k}, {other_modes})"
+            )
+
+    # Step 1: factors. For each mode k, take top-r_k left singular vectors
+    # of the mode-k unfolding.
+    factors: list[torch.Tensor] = []
+    for k in range(1, d + 1):
+        T_k = mode_unfolding(T, axis=k)               # (B, n_k, prod_others)
+        U_k, _, _ = truncated_svd(
+            T_k, r=ranks[k - 1], mode=mode, generator=generator,
+        )
+        factors.append(U_k)
+
+    # Step 2: core G = T ×_1 U_1ᵀ ×_2 U_2ᵀ × ... ×_d U_dᵀ.
+    # Our `mode_product(T, A, axis)` contracts T's axis with A's last dim.
+    # We want to project axis k from size n_k down to r_k. Pass A =
+    # factors[k-1].mT so A has shape (B, r_k, n_k) and the result has r_k at
+    # axis k.
+    core = T
+    for k in range(1, d + 1):
+        core = mode_product(core, factors[k - 1].mT, axis=k)
+
+    return core, factors