Skip to content

Features

features

Feature map utilities and public classes.

Feature

Bases: ABC

Abstract base class for all feature maps.

This class defines the interface that all feature map implementations must follow. It provides methods for computing feature transformations and accessing feature parameters.

params abstractmethod property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing all configurable parameters of the feature map.

local_dim abstractmethod property 

local_dim: int

Return the local feature dimension.

ProductFeatures dataclass 

ProductFeatures(
    fmap: Feature | Sequence[Feature],
    d_dim: int | None = None,
)

Container for per-dimension feature maps.

Represents tensor-product feature structures by grouping per-dimension feature maps into a single container. This class is immutable.

Parameters:

  • fmap (Feature | Sequence[Feature]) –

    Feature map(s) per dimension. A single feature will be broadcast to d_dim copies. Internally converted to and stored as a tuple.

  • d_dim (int | None, default: None ) –

    Number of dimensions / feature maps. If None, inferred from fmap when fmap is a sequence. Must be a positive integer.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import PolyFeature, ProductFeatures
>>> prod = ProductFeatures(fmap=PolyFeature(m_order=3), d_dim=2)
>>> len(prod)
2
>>> prod.local_dims
(3, 3)
>>> prod[0](jnp.array([1, 2, 3]))
Array([[1, 1, 1],
   [1, 2, 4],
   [1, 3, 9]], dtype=int32)

local_dims property 

local_dims: tuple[int, ...]

Get the output dimension of each feature map.

Returns:

  • tuple[int, ...] –

    Tuple of local dimensions, one per feature map.

BSplineFeature dataclass 

BSplineFeature(
    k_order: int,
    n_knots: int,
    shift: float = 0.0,
    k_col: int | None = None,
)

Bases: Feature

Uniform B-spline features.

Computes compact-support uniform B-spline basis features on a uniform knot grid in the unit interval. For each sample, only k_order + 1 adjacent basis functions are active.

Notes
  • Expected input domain is x in [0, 1].
  • Spline terminology: k_order is the spline order (degree = order - 1 in some literature, but here order is used consistently throughout).

Parameters:

  • k_order (int) –

    Spline order (determines local support and smoothness).

  • n_knots (int) –

    Number of uniform knot intervals over [0, 1].

  • shift (float, default: 0.0 ) –

    Constant shift applied to all features.

  • k_col (int | None, default: None ) –

    Optional column index to use when input is 2D. If None, input is expected to be 1D.

References

[1] K. Qin, "General matrix representations for B-splines", The Visual Computer, 2000.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import BSplineFeature
>>> feature = BSplineFeature(k_order=2, n_knots=5)
>>> feature(jnp.array([0.1, 0.3, 0.8]))
Array([[0.125, 0.75 , 0.125, 0.   , 0.   , 0.   , 0.   ],
   [0.   , 0.125, 0.75 , 0.125, 0.   , 0.   , 0.   ],
   [0.   , 0.   , 0.   , 0.   , 0.5  , 0.5  , 0.   ]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: k_order, n_knots, shift, and k_col.

local_dim property 

local_dim: int

Return the local feature dimension.

VoltFeature dataclass 

VoltFeature(m_order: int, p_input: int = 1)

Bases: Feature

Volterra features with zero-padded history.

For each time index t, the returned feature row is [1, u_t, u_(t-1), ..., u_(t-m_order+1)] for each input channel. Missing past samples are filled with zeros.

Parameters:

  • m_order (int) –

    Memory length (order) of the Volterra features.

  • p_input (int, default: 1 ) –

    Number of input channels. Used to compute local_dim.

References

[1] K. Batselier, Z. Chen, N. Wong, "Tensor Network alternating linear scheme for MIMO Volterra system identification", Automatica, 2017.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import VoltFeature
>>> feature = VoltFeature(m_order=3, p_input=1)
>>> feature(jnp.array([0.1, 0.3, 0.8]))
Array([[1. , 0.1, 0. , 0. ],
   [1. , 0.3, 0.1, 0. ],
   [1. , 0.8, 0.3, 0.1]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: m_order, p_input.

local_dim property 

local_dim: int

Return the local feature dimension.

VoltHistFeature dataclass 

VoltHistFeature(m_order: int, p_input: int = 1)

Bases: VoltFeature

Volterra features using existing history (no zero padding).

For each time index t, the feature vector is [1, u_t, u_{t-1}, ..., u_{t-m_order+1}] for each input channel.

The number of output samples is n_out = n_in - m_order + 1.

Therefore, to obtain n_samples output samples, the input must contain n_samples + m_order - 1 rows.

Parameters:

  • m_order (int) –

    Memory length (order) of the Volterra features.

  • p_input (int, default: 1 ) –

    Number of input channels. Used to compute local_dim.

References

[1] K. Batselier, Z. Chen, N. Wong, "Tensor Network alternating linear scheme for MIMO Volterra system identification", Automatica, 2017.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import VoltHistFeature
>>> feature = VoltHistFeature(m_order=3, p_input=1)
>>> feature(jnp.array([0.1, 0.3, 0.8]))
Array([[1. , 0.8, 0.3, 0.1]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: m_order, p_input.

local_dim property 

local_dim: int

Return the local feature dimension.

PolyFeature dataclass 

PolyFeature(
    m_order: int,
    shift: float = 0.0,
    k_col: int | None = None,
)

Bases: Feature

Pure polynomial features.

Computes polynomial basis functions up to a specified order. For input x, the feature vector is [1, x, x**2, ..., x**(m_order-1)] with optional shift applied to all features.

Parameters:

  • m_order (int) –

    Maximum polynomial order (number of features).

  • shift (float, default: 0.0 ) –

    Constant shift applied to all features.

  • k_col (int | None, default: None ) –

    Optional column index when input is 2D. If None, input is expected to be 1D.

References

[1] F. Wesel, K. Batselier, "Quantized Fourier and Polynomial Features for more Expressive Tensor Network Models", AISTATS, 2024. Definition 3.1.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import PolyFeature
>>> feature = PolyFeature(m_order=3)
>>> feature(jnp.array([1.0, 2, 3]))
Array([[1., 1., 1.],
   [1., 2., 4.],
   [1., 3., 9.]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: m_order, shift, k_col.

local_dim property 

local_dim: int

Return the local feature dimension.

PolyNormFeature dataclass 

PolyNormFeature(
    m_order: int,
    shift: float = 0.0,
    k_col: int | None = None,
)

Bases: PolyFeature

Normalized pure polynomial features.

Extends PolyFeature with L2 normalization applied to each sample. Each polynomial basis vector is normalized to unit norm.

Parameters:

  • m_order (int) –

    Maximum polynomial order (number of features).

  • shift (float, default: 0.0 ) –

    Constant shift applied to all features.

  • k_col (int | None, default: None ) –

    Optional column index when input is 2D. If None, input is expected to be 1D.

References

[1] K. Konstantinidis, Y. L. Xu, Q. Zhao, D. P. Mandic, "Variational Bayesian Tensor Networks with Structured Posteriors", ICASSP, 2022.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import PolyNormFeature
>>> feature = PolyNormFeature(m_order=3)
>>> feature(jnp.array([1.0, 2, 3]))
Array([[0.57735026, 0.57735026, 0.57735026],
   [0.21821788, 0.43643576, 0.8728715 ],
   [0.10482848, 0.31448543, 0.9434563 ]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: m_order, shift, k_col.

local_dim property 

local_dim: int

Return the local feature dimension.

QuantPolyFeature dataclass 

QuantPolyFeature(q_order: int, k_col: int | None = None)

Bases: Feature

Quantized polynomial features.

For input x, the feature vector is [1, x**(2**q_order)], where the exponent is restricted to powers of two. This yields a quantized polynomial basis with exponentially spaced polynomial degrees.

Parameters:

  • q_order (int) –

    Quantization order. The polynomial exponent is 2**q_order.

  • k_col (int | None, default: None ) –

    Optional column index to use when input is 2D. If None, input is expected to be 1D.

References

[1] F. Wesel, K. Batselier, "Quantized Fourier and Polynomial Features for more Expressive Tensor Network Models", AISTATS, 2024. Definition 3.4.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import QuantPolyFeature
>>> feature = QuantPolyFeature(q_order=2)
>>> feature(jnp.array([1.0, 2, 3]))
Array([[ 1.,  1.],
   [ 1., 16.],
   [ 1., 81.]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: q_order, k_col.

local_dim property 

local_dim: int

Return the local feature dimension.

SquaredExpFeature dataclass 

SquaredExpFeature(
    m_order: int,
    scale: float = 1.0,
    v_bound: float = 1.0,
    s_var: float = 1.0,
    shift: float = 0.0,
    k_col: int | None = None,
)

Bases: Feature

Gaussian (squared exponential) kernel features.

Implements a finite-dimensional basis approximation of the Gaussian (squared exponential) kernel. Uses sinusoidal basis functions weighted by Gaussian kernel parameters.

Parameters:

  • m_order (int) –

    Number of basis functions.

  • scale (float, default: 1.0 ) –

    Length-scale (bandwidth) parameter of the Gaussian kernel. Controls how rapidly the function can vary.

  • v_bound (float, default: 1.0 ) –

    Domain bound used in the Hilbert space approximation.

  • s_var (float, default: 1.0 ) –

    Signal variance of the Gaussian kernel. Controls the overall magnitude of the function.

  • shift (float, default: 0.0 ) –

    Constant shift applied to all features.

  • k_col (int | None, default: None ) –

    Optional column index to use when input is 2D. If None, input is expected to be 1D.

References

[1] A. Solin, S. Särkkä, "Hilbert Space Methods for Reduced-Rank Gaussian Process Regression", Statistics and Computing, 2020. See Eqs. (55)-(56) for the one-dimensional case.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import SquaredExpFeature
>>> feature = SquaredExpFeature(m_order=3, scale=1, v_bound=1)
>>> feature(jnp.array([0.2, 0.4]))
Array([[ 0.81256217, -0.07891964, -0.0036117 ],
   [ 0.6912067 , -0.12769459,  0.00189878]], dtype=float32)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: m_order, scale, v_bound, s_var, shift, k_col.

local_dim property 

local_dim: int

Return the local feature dimension.

FourierFeature dataclass 

FourierFeature(
    m_order: int,
    scale: float = 1.0,
    shift: float = 0.0,
    k_col: int | None = None,
)

Bases: Feature

Complex Fourier features.

Computes complex exponential Fourier basis functions. The resulting feature map is suitable for representing periodic functions and forms the basis of Fourier feature approximations.

Parameters:

  • m_order (int) –

    Number of Fourier basis functions (feature dimension).

  • scale (float, default: 1.0 ) –

    Frequency scaling parameter. Controls the spacing of the Fourier basis functions.

  • shift (float, default: 0.0 ) –

    Constant shift applied to all features.

  • k_col (int | None, default: None ) –

    Optional column index to use when input is 2D. If None, input is expected to be 1D.

References

[1] S. Wahls, V. Koivunen, H. V. Poor, M. Verhaegen, "Learning multidimensional Fourier series with tensor trains", GlobalSIP, 2014.

[2] F. Wesel, K. Batselier, "Quantized Fourier and Polynomial Features for more Expressive Tensor Network Models", AISTATS, 2024. Definition 3.2.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import FourierFeature
>>> feature = FourierFeature(m_order=2, scale=1)
>>> feature(jnp.array([0.2, 0.4]))
Array([[0.30901697-0.95105654j, 1.+0.j],
   [-0.80901706-0.5877852j, 1.+0.j]], dtype=complex64)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: m_order, scale, shift, k_col.

local_dim property 

local_dim: int

Return the local feature dimension.

QuantFourierFeature dataclass 

QuantFourierFeature(
    q_order: int,
    m_order: int,
    scale: float = 1.0,
    k_col: int | None = None,
)

Bases: Feature

Quantized complex Fourier features.

Computes complex Fourier basis functions whose frequencies are quantized according to q_order. Compared to standard Fourier features, the frequencies are spaced exponentially rather than uniformly.

Parameters:

  • q_order (int) –

    Quantization order controlling the exponential frequency spacing.

  • m_order (int) –

    Number of Fourier basis functions.

  • scale (float, default: 1.0 ) –

    Frequency scaling parameter.

  • k_col (int | None, default: None ) –

    Optional column index to use when input is 2D. If None, input is expected to be 1D.

References

[1] S. Wahls, V. Koivunen, H. V. Poor, M. Verhaegen, "Learning multidimensional Fourier series with tensor trains", GlobalSIP, 2014.

[2] F. Wesel, K. Batselier, "Quantized Fourier and Polynomial Features for more Expressive Tensor Network Models", AISTATS, 2024. Corollary 3.6.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.features import QuantFourierFeature
>>> feature = QuantFourierFeature(q_order=1, m_order=4, scale=1)
>>> feature(jnp.array([0.1, 0.5]))
Array([[0.809017-5.8778524e-01j, 0.809017+5.8778524e-01j],
   [-1.+8.7422777e-08j, -1.-8.7422777e-08j]], dtype=complex64)

params property 

params: dict[str, object]

Return the object configuration.

Returns:

  • dict –

    Dictionary containing the configuration parameters: q_order, m_order, scale, k_col.

local_dim property 

local_dim: int

Return the local feature dimension.