tanat.metric.sequence.type.softdtw package

Submodules

tanat.metric.sequence.type.softdtw.kernels module

Numba kernels for SoftDTWSequenceMetric.

All functions are @njit (no Python objects). They operate on int32-encoded feature arrays produced by the entity metric’s prepare_batch_data.

Implementation: full (n+2) × (m+2) DP matrix with soft-minimum operator. The log-sum-exp trick is used for numerical stability.

tanat.metric.sequence.type.softdtw.kernels.compute_softdtw_matrix(result, start, end, arrays_a, lengths_a, arrays_b, lengths_b, dist_kernel, context, gamma, symmetric)

Parallel SoftDTW matrix kernel.

Processes rows [start, end).

tanat.metric.sequence.type.softdtw.kernels.compute_softdtw_pair(arr_a, arr_b, len_a, len_b, dist_kernel, context, gamma)

Compute SoftDTW distance for a single pair of int32-encoded sequences.

Uses the full (n+2) × (m+2) DP matrix.

Parameters:

• arr_a – int32-encoded sequence A.

• arr_b – int32-encoded sequence B.

• len_a – Length of A.

• len_b – Length of B.

• dist_kernel – Numba entity distance kernel.

• context – Opaque context tuple forwarded to dist_kernel.

• gamma – Regularisation parameter (float32 > 0).

Returns:

float32 SoftDTW distance, or nan when either sequence is empty.

tanat.metric.sequence.type.softdtw.metric module

SoftDTWSequenceMetric: Soft Dynamic Time Warping between sequences.

class tanat.metric.sequence.type.softdtw.metric.SoftDTWSequenceMetric(entity_metric: EntityMetric | str = 'hamming', gamma: float = 1.0, *, store_path: str | Path | None = None, chunk_size: int = 500, resume: bool = True, dtype: str = 'float32')

Bases: SequenceMetric

Soft Dynamic Time Warping distance between two sequences.

Replaces the min operator in the DTW recurrence with a differentiable soft-minimum parameterised by gamma:

\[\text{soft-min}(a, b, c; \gamma) = -\gamma \log\bigl( e^{-a/\gamma} + e^{-b/\gamma} + e^{-c/\gamma}\bigr)\]

As gamma → 0, SoftDTW converges to standard DTW. As gamma → ∞, it approaches the mean of all alignment costs.

Empty-sequence behaviour:

• Both empty → nan (no alignment possible).

• One empty → nan (no alignment possible).

References

Cuturi & Blondel (2017) — Soft-DTW: a Differentiable Loss Function for Time-Series, ICML.

Example:

sdtw = SoftDTWSequenceMetric(gamma=0.1)
d    = sdtw(seq_a, seq_b)
dm   = sdtw.compute_matrix(pool)

MEMMAP_SUPPORT: bool = True

Set to True in subclasses that implement disk-backed (memmap) computation. When False, passing store_path or an instance-level StorageOptions raises NotImplementedError early with a clear message.

SETTINGS_CLASS

alias of SoftDTWSettings

__init__(entity_metric: EntityMetric | str = 'hamming', gamma: float = 1.0, *, store_path: str | Path | None = None, chunk_size: int = 500, resume: bool = True, dtype: str = 'float32') → None

validate_composition(seq_a: Sequence, seq_b: Sequence | None = None) → None

Probe the first entity of each sequence through the entity metric.

class tanat.metric.sequence.type.softdtw.metric.SoftDTWSettings(*, entity_metric: EntityMetric = 'hamming', gamma: float = 1.0)

Bases: object

Settings for SoftDTWSequenceMetric.

Parameters:

• entity_metric – Entity-level distance metric. Default: "hamming".

• gamma – Regularisation parameter for the soft-min operator. Must be > 0. Large values produce a smoother (mean-like) approximation; small values approach standard DTW. Default: 1.0.

__init__(*args: Any, **kwargs: Any) → None

entity_metric: EntityMetric = 'hamming'

gamma: float = 1.0

model_dump(*, mode='python', **dump_kwargs)

Dump settings to a dict via Pydantic serialization.

Module contents

SoftDTWSequenceMetric package.

class tanat.metric.sequence.type.softdtw.SoftDTWSequenceMetric(entity_metric: EntityMetric | str = 'hamming', gamma: float = 1.0, *, store_path: str | Path | None = None, chunk_size: int = 500, resume: bool = True, dtype: str = 'float32')

Bases: SequenceMetric

Soft Dynamic Time Warping distance between two sequences.

Replaces the min operator in the DTW recurrence with a differentiable soft-minimum parameterised by gamma:

\[\text{soft-min}(a, b, c; \gamma) = -\gamma \log\bigl( e^{-a/\gamma} + e^{-b/\gamma} + e^{-c/\gamma}\bigr)\]

As gamma → 0, SoftDTW converges to standard DTW. As gamma → ∞, it approaches the mean of all alignment costs.

Empty-sequence behaviour:

• Both empty → nan (no alignment possible).

• One empty → nan (no alignment possible).

References

Cuturi & Blondel (2017) — Soft-DTW: a Differentiable Loss Function for Time-Series, ICML.

Example:

sdtw = SoftDTWSequenceMetric(gamma=0.1)
d    = sdtw(seq_a, seq_b)
dm   = sdtw.compute_matrix(pool)

MEMMAP_SUPPORT: bool = True

Set to True in subclasses that implement disk-backed (memmap) computation. When False, passing store_path or an instance-level StorageOptions raises NotImplementedError early with a clear message.

SETTINGS_CLASS

alias of SoftDTWSettings

__init__(entity_metric: EntityMetric | str = 'hamming', gamma: float = 1.0, *, store_path: str | Path | None = None, chunk_size: int = 500, resume: bool = True, dtype: str = 'float32') → None

validate_composition(seq_a: Sequence, seq_b: Sequence | None = None) → None

Probe the first entity of each sequence through the entity metric.

class tanat.metric.sequence.type.softdtw.SoftDTWSettings(*, entity_metric: EntityMetric = 'hamming', gamma: float = 1.0)

Bases: object

Settings for SoftDTWSequenceMetric.

Parameters:

• entity_metric – Entity-level distance metric. Default: "hamming".

• gamma – Regularisation parameter for the soft-min operator. Must be > 0. Large values produce a smoother (mean-like) approximation; small values approach standard DTW. Default: 1.0.

__init__(*args: Any, **kwargs: Any) → None

entity_metric: EntityMetric = 'hamming'

gamma: float = 1.0

model_dump(*, mode='python', **dump_kwargs)

Dump settings to a dict via Pydantic serialization.