dtw_loss_functions.soft_dtw_implementations.soft_dtw_cuda_ron.barycenters module — dtw_loss_functions documentation

# dtw_loss_functions.soft_dtw_implementations.soft_dtw_cuda_ron.barycenters module

SoftDTW Barycenter Averaging

Implements time series averaging using soft Dynamic Time Warping geometry. Based on the method from Cuturi & Blondel (ICML 2017).

Reference: https://github.com/tslearn-team/tslearn/blob/main/tslearn/barycenters/softdtw.py

dtw_loss_functions.soft_dtw_implementations.soft_dtw_cuda_ron.barycenters.softdtw_barycenter(X: Tensor, *, gamma: float = 1.0, weights: Tensor | None = None, max_iter: int = 100, lr: float = 0.1, init: Tensor | None = None, device: str | device | None = None, verbose: bool = False, fused: bool | None = None, early_stopping: bool = True, patience: int = 10, tol: float = 1e-05) → Tensor

  Compute a SoftDTW barycenter (time series average) through optimization.

  This function finds the barycenter that minimizes the weighted sum of SoftDTW distances to all input time series using gradient-based optimization.

  Parameters:

    - X – Input time series of shape (B, N, D) where: - B: batch size (number of sequences) - N: sequence length - D: feature dimension

    - gamma – SoftDTW regularization parameter. Default: 1.0

    - weights – Optional weights for each sequence, shape (B,). Default: uniform

    - max_iter – Maximum optimization iterations. Default: 100

    - lr – Learning rate for optimization. Default: 0.1

    - init – Initial barycenter, shape (N, D). If None, uses weighted mean. Default: None

    - device – Device to compute on. If None, uses X’s device. Default: None

    - verbose – Print iteration progress and timing. Default: False

    - fused – Fused mode selection. Default: None (auto-select) - None: Auto-select (use fused if CUDA available) - True: Require fused mode (error if not available) - False: Never use fused mode (always use standard distance matrix)

    - early_stopping – Stop early if loss plateaus. Default: True

    - patience – Iterations without improvement before stopping. Default: 10

    - tol – Absolute improvement threshold for early stopping. Default: 1e-5 Note: Uses absolute improvement (best_loss - loss_val > tol), which handles negative SoftDTW values correctly

  Returns:

    Barycenter of shape (N, D)

dtw_loss_functions.soft_dtw_implementations.soft_dtw_cuda_ron.barycenters.softdtw_barycenter_cpu(X: Tensor, *, gamma: float = 1.0, weights: Tensor | None = None, max_iter: int = 100, lr: float = 0.1, init: Tensor | None = None, verbose: bool = False, fused: bool | None = None, early_stopping: bool = True, patience: int = 10, tol: float = 1e-05) → Tensor

  Compute a SoftDTW barycenter on CPU (convenience wrapper).

  Parameters:

    - X – Input time series of shape (B, N, D)

    - gamma – SoftDTW regularization parameter. Default: 1.0

    - weights – Optional weights for each sequence. Default: uniform

    - max_iter – Maximum optimization iterations. Default: 100

    - lr – Learning rate for optimization. Default: 0.01

    - init – Initial barycenter. If None, uses weighted mean. Default: None

    - verbose – Print iteration progress and timing. Default: False

    - fused – Fused mode selection. Default: None (auto-select)

    - early_stopping – Stop early if loss plateaus. Default: True

    - patience – Iterations without improvement before stopping. Default: 10

    - tol – Improvement threshold for early stopping. Default: 1e-5

  Returns:

    Barycenter of shape (N, D)