autogluon.timeseries 1.4.1b20251115__py3-none-any.whl → 1.5.0b20251221__py3-none-any.whl

autogluon/timeseries/models/toto/_internal/backbone/rotary_embedding_torch.py

@@ -0,0 +1,342 @@
+# Source: https://github.com/lucidrains/rotary-embedding-torch
+# MIT License
+#
+# Copyright (c) 2021 Phil Wang
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+from math import pi
+from typing import Literal
+
+import torch
+from einops import rearrange, repeat
+from torch import Tensor, broadcast_tensors, einsum, is_tensor, nn, tensor
+from torch.amp import autocast
+from torch.nn import Module
+
+# helper functions
+
+
+def exists(val):
+    return val is not None
+
+
+def default(val, d):
+    return val if exists(val) else d
+
+
+def slice_at_dim(t, dim_slice: slice, *, dim):
+    dim += t.ndim if dim < 0 else 0
+    colons = [slice(None)] * t.ndim
+    colons[dim] = dim_slice
+    return t[tuple(colons)]
+
+
+# rotary embedding helper functions
+
+
+def rotate_half(x):
+    x = rearrange(x, "... (d r) -> ... d r", r=2)
+    x1, x2 = x.unbind(dim=-1)
+    x = torch.stack((-x2, x1), dim=-1)
+    return rearrange(x, "... d r -> ... (d r)")
+
+
+@autocast("cuda", enabled=False)
+def apply_rotary_emb(freqs, t, start_index=0, scale=1.0, seq_dim=-2, freqs_seq_dim=None):
+    dtype = t.dtype
+
+    if not exists(freqs_seq_dim):
+        if freqs.ndim == 2 or t.ndim == 3:
+            freqs_seq_dim = 0
+
+    if t.ndim == 3 or exists(freqs_seq_dim):
+        seq_len = t.shape[seq_dim]
+        freqs = slice_at_dim(freqs, slice(-seq_len, None), dim=freqs_seq_dim)
+
+    rot_dim = freqs.shape[-1]
+    end_index = start_index + rot_dim
+
+    assert rot_dim <= t.shape[-1], (
+        f"feature dimension {t.shape[-1]} is not of sufficient size to rotate in all the positions {rot_dim}"
+    )
+
+    # Split t into three parts: left, middle (to be transformed), and right
+    t_left = t[..., :start_index]
+    t_middle = t[..., start_index:end_index]
+    t_right = t[..., end_index:]
+
+    # Apply rotary embeddings without modifying t in place
+    t_transformed = (t_middle * freqs.cos() * scale) + (rotate_half(t_middle) * freqs.sin() * scale)
+
+    out = torch.cat((t_left, t_transformed, t_right), dim=-1)
+
+    return out.type(dtype)
+
+
+# learned rotation helpers
+
+
+def apply_learned_rotations(rotations, t, start_index=0, freq_ranges=None):
+    if exists(freq_ranges):
+        rotations = einsum("..., f -> ... f", rotations, freq_ranges)
+        rotations = rearrange(rotations, "... r f -> ... (r f)")
+
+    rotations = repeat(rotations, "... n -> ... (n r)", r=2)
+    return apply_rotary_emb(rotations, t, start_index=start_index)
+
+
+# classes
+
+
+class RotaryEmbedding(Module):
+    def __init__(
+        self,
+        dim,
+        custom_freqs: Tensor | None = None,
+        freqs_for: Literal["lang", "pixel", "constant"] = "lang",
+        theta=10000,
+        max_freq=10,
+        num_freqs=1,
+        learned_freq=False,
+        use_xpos=False,
+        xpos_scale_base=512,
+        interpolate_factor=1.0,
+        theta_rescale_factor=1.0,
+        seq_before_head_dim=False,
+        cache_if_possible=True,
+        cache_max_seq_len=8192,
+    ):
+        super().__init__()
+        # proposed by reddit user bloc97, to rescale rotary embeddings to longer sequence length without fine-tuning
+        # has some connection to NTK literature
+        # https://www.reddit.com/r/LocalLLaMA/comments/14lz7j5/ntkaware_scaled_rope_allows_llama_models_to_have/
+
+        theta *= theta_rescale_factor ** (dim / (dim - 2))
+
+        self.freqs_for = freqs_for
+
+        if exists(custom_freqs):
+            freqs = custom_freqs
+        elif freqs_for == "lang":
+            freqs = 1.0 / (theta ** (torch.arange(0, dim, 2)[: (dim // 2)].float() / dim))
+        elif freqs_for == "pixel":
+            freqs = torch.linspace(1.0, max_freq / 2, dim // 2) * pi
+        elif freqs_for == "constant":
+            freqs = torch.ones(num_freqs).float()
+
+        self.cache_if_possible = cache_if_possible
+        self.cache_max_seq_len = cache_max_seq_len
+
+        self.register_buffer("cached_freqs", torch.zeros(cache_max_seq_len, dim), persistent=False)
+        self.cached_freqs_seq_len = 0
+
+        self.freqs = nn.Parameter(freqs, requires_grad=learned_freq)
+
+        self.learned_freq = learned_freq
+
+        # dummy for device
+
+        self.register_buffer("dummy", torch.tensor(0), persistent=False)
+
+        # default sequence dimension
+
+        self.seq_before_head_dim = seq_before_head_dim
+        self.default_seq_dim = -3 if seq_before_head_dim else -2
+
+        # interpolation factors
+
+        assert interpolate_factor >= 1.0
+        self.interpolate_factor = interpolate_factor
+
+        # xpos
+
+        self.use_xpos = use_xpos
+
+        if not use_xpos:
+            return
+
+        scale = (torch.arange(0, dim, 2) + 0.4 * dim) / (1.4 * dim)
+        self.scale_base = xpos_scale_base
+
+        self.register_buffer("scale", scale, persistent=False)
+        self.register_buffer("cached_scales", torch.zeros(cache_max_seq_len, dim), persistent=False)
+        self.cached_scales_seq_len = 0
+
+        # add apply_rotary_emb as static method
+
+        self.apply_rotary_emb = staticmethod(apply_rotary_emb)
+
+    @property
+    def device(self):
+        return self.dummy.device
+
+    def get_seq_pos(self, seq_len, device=None, dtype=None, offset=0):
+        device = default(device, self.device)
+        dtype = default(dtype, self.cached_freqs.dtype)
+
+        return (torch.arange(seq_len, device=device, dtype=dtype) + offset) / self.interpolate_factor
+
+    def rotate_queries_or_keys(self, t, seq_dim=None, offset=0, scale=None):
+        seq_dim = default(seq_dim, self.default_seq_dim)
+
+        assert not self.use_xpos or exists(scale), (
+            "you must use `.rotate_queries_and_keys` method instead and pass in both queries and keys, for length extrapolatable rotary embeddings"
+        )
+
+        device, dtype, seq_len = t.device, t.dtype, t.shape[seq_dim]
+
+        seq = self.get_seq_pos(seq_len, device=device, dtype=dtype, offset=offset)
+
+        freqs = self.forward(seq, seq_len=seq_len, offset=offset)
+
+        if seq_dim == -3:
+            freqs = rearrange(freqs, "n d -> n 1 d")
+
+        return apply_rotary_emb(freqs, t, scale=default(scale, 1.0), seq_dim=seq_dim)
+
+    def rotate_queries_with_cached_keys(self, q, k, seq_dim=None, offset=0):
+        dtype, device, seq_dim = q.dtype, q.device, default(seq_dim, self.default_seq_dim)
+
+        q_len, k_len = q.shape[seq_dim], k.shape[seq_dim]
+        assert q_len <= k_len
+
+        q_scale = k_scale = 1.0
+
+        if self.use_xpos:
+            seq = self.get_seq_pos(k_len, dtype=dtype, device=device)
+
+            q_scale = self.get_scale(seq[-q_len:]).type(dtype)
+            k_scale = self.get_scale(seq).type(dtype)
+
+        rotated_q = self.rotate_queries_or_keys(q, seq_dim=seq_dim, scale=q_scale, offset=k_len - q_len + offset)
+        rotated_k = self.rotate_queries_or_keys(k, seq_dim=seq_dim, scale=k_scale**-1)
+
+        rotated_q = rotated_q.type(q.dtype)
+        rotated_k = rotated_k.type(k.dtype)
+
+        return rotated_q, rotated_k
+
+    def rotate_queries_and_keys(self, q, k, seq_dim=None):
+        seq_dim = default(seq_dim, self.default_seq_dim)
+
+        assert self.use_xpos
+        device, dtype, seq_len = q.device, q.dtype, q.shape[seq_dim]
+
+        seq = self.get_seq_pos(seq_len, dtype=dtype, device=device)
+
+        freqs = self.forward(seq, seq_len=seq_len)
+        scale = self.get_scale(seq, seq_len=seq_len).to(dtype)
+
+        if seq_dim == -3:
+            freqs = rearrange(freqs, "n d -> n 1 d")
+            scale = rearrange(scale, "n d -> n 1 d")
+
+        rotated_q = apply_rotary_emb(freqs, q, scale=scale, seq_dim=seq_dim)
+        rotated_k = apply_rotary_emb(freqs, k, scale=scale**-1, seq_dim=seq_dim)
+
+        rotated_q = rotated_q.type(q.dtype)
+        rotated_k = rotated_k.type(k.dtype)
+
+        return rotated_q, rotated_k
+
+    def get_scale(self, t: Tensor, seq_len: int | None = None, offset=0):
+        assert self.use_xpos
+
+        should_cache = self.cache_if_possible and exists(seq_len) and (offset + seq_len) <= self.cache_max_seq_len
+
+        if should_cache and exists(self.cached_scales) and (seq_len + offset) <= self.cached_scales_seq_len:
+            return self.cached_scales[offset : (offset + seq_len)]
+
+        scale = 1.0
+        if self.use_xpos:
+            power = (t - len(t) // 2) / self.scale_base
+            scale = self.scale ** rearrange(power, "n -> n 1")
+            scale = repeat(scale, "n d -> n (d r)", r=2)
+
+        if should_cache and offset == 0:
+            self.cached_scales[:seq_len] = scale.detach()
+            self.cached_scales_seq_len = seq_len
+
+        return scale
+
+    def get_axial_freqs(self, *dims, offsets: (tuple[int | float, ...] | Tensor | None) = None):
+        Colon = slice(None)
+        all_freqs = []
+
+        # handle offset
+
+        if exists(offsets):
+            if not is_tensor(offsets):
+                offsets = tensor(offsets)
+
+            assert len(offsets) == len(dims)
+
+        # get frequencies for each axis
+
+        for ind, dim in enumerate(dims):
+            offset = 0
+            if exists(offsets):
+                offset = offsets[ind]
+
+            if self.freqs_for == "pixel":
+                pos = torch.linspace(-1, 1, steps=dim, device=self.device)
+            else:
+                pos = torch.arange(dim, device=self.device)
+
+            pos = pos + offset
+
+            freqs = self.forward(pos, seq_len=dim)
+
+            all_axis = [None] * len(dims)
+            all_axis[ind] = Colon
+
+            new_axis_slice = (Ellipsis, *all_axis, Colon)
+            all_freqs.append(freqs[new_axis_slice])
+
+        # concat all freqs
+
+        all_freqs = broadcast_tensors(*all_freqs)
+        return torch.cat(all_freqs, dim=-1)
+
+    @autocast("cuda", enabled=False)
+    def forward(self, t: Tensor, seq_len: int | None = None, offset=0):
+        should_cache = (
+            self.cache_if_possible
+            and not self.learned_freq
+            and exists(seq_len)
+            and self.freqs_for != "pixel"
+            and (offset + seq_len) <= self.cache_max_seq_len
+        )
+
+        if should_cache and exists(self.cached_freqs) and (offset + seq_len) <= self.cached_freqs_seq_len:
+            return self.cached_freqs[offset : (offset + seq_len)].detach()
+
+        freqs = self.freqs
+
+        freqs = einsum("..., f -> ... f", t.type(freqs.dtype), freqs)
+        freqs = repeat(freqs, "... n -> ... (n r)", r=2)
+
+        if should_cache and offset == 0:
+            self.cached_freqs[:seq_len] = freqs.detach()
+            self.cached_freqs_seq_len = seq_len
+
+        return freqs

autogluon/timeseries/models/toto/_internal/backbone/scaler.py

@@ -4,7 +4,6 @@
 # Copyright 2025 Datadog, Inc.
 
 import warnings
-from typing import Optional
 
 import torch
 from einops import repeat
@@ -21,7 +20,7 @@ def compute_causal_statistics(
     use_bessel_correction: bool = True,
     stabilize_with_global: bool = False,
     scale_factor_exponent: float = 10.0,
-    prefix_length: Optional[int] = None,
+    prefix_length: int | None = None,
 ) -> tuple[torch.Tensor, torch.Tensor]:
     """
     Compute causal mean and scale statistics along a specified dimension using
@@ -260,7 +259,7 @@ class CausalPatchStdMeanScaler(Scaler):
         data: torch.Tensor,
         padding_mask: torch.Tensor,
         weights: torch.Tensor,
-        prefix_length: Optional[int] = None,
+        prefix_length: int | None = None,
     ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
         assert data.shape == weights.shape, "data and weights must have same shape"
         assert len(data.shape) == 3, "Input data must have shape [batch, variates, time_steps]"

autogluon/timeseries/models/toto/_internal/backbone/transformer.py

@@ -3,12 +3,11 @@
 # This product includes software developed at Datadog (https://www.datadoghq.com/)
 # Copyright 2025 Datadog, Inc.
 
-from typing import Optional, Union, cast
+from typing import cast
 
 import torch
 import torch.nn.functional as F
 from einops import rearrange
-from rotary_embedding_torch import RotaryEmbedding
 
 from .attention import (
     AttentionAxis,
@@ -18,6 +17,7 @@ from .attention import (
 )
 from .kvcache import KVCache
 from .rope import TimeAwareRotaryEmbedding
+from .rotary_embedding_torch import RotaryEmbedding
 
 
 class SwiGLU(torch.nn.Module):
@@ -37,7 +37,7 @@ class RMSNorm(torch.nn.Module):
         super(RMSNorm, self).__init__()
         self.eps = eps
         if include_weight:
-            self.scale: Optional[torch.nn.Parameter] = torch.nn.Parameter(torch.ones(dim))
+            self.scale: torch.nn.Parameter | None = torch.nn.Parameter(torch.ones(dim))
         else:
             self.scale = None
 
@@ -86,7 +86,7 @@ class TransformerLayer(torch.nn.Module):
         num_heads: int,
         mlp_hidden_dim: int,
         dropout: float,
-        rotary_emb: Optional[RotaryEmbedding] = None,
+        rotary_emb: RotaryEmbedding | None = None,
         attention_axis: AttentionAxis = AttentionAxis.TIME,
         RMS_norm: bool = True,
         use_memory_efficient_attention: bool = True,
@@ -99,8 +99,8 @@ class TransformerLayer(torch.nn.Module):
         self.attention_axis = attention_axis
 
         if RMS_norm:
-            self.norm1: Union[RMSNorm, torch.nn.LayerNorm] = RMSNorm(embed_dim)
-            self.norm2: Union[RMSNorm, torch.nn.LayerNorm] = RMSNorm(embed_dim)
+            self.norm1: RMSNorm | torch.nn.LayerNorm = RMSNorm(embed_dim)
+            self.norm2: RMSNorm | torch.nn.LayerNorm = RMSNorm(embed_dim)
 
         else:
             self.norm1 = torch.nn.LayerNorm(embed_dim)
@@ -138,8 +138,8 @@ class TransformerLayer(torch.nn.Module):
         self,
         layer_idx: int,
         inputs: torch.Tensor,
-        attention_mask: Optional[torch.Tensor] = None,
-        kv_cache: Optional[KVCache] = None,
+        attention_mask: torch.Tensor | None = None,
+        kv_cache: KVCache | None = None,
     ) -> torch.Tensor:
         pre_norm_1 = self.norm1(inputs)
         hidden_state = inputs + self.attention(layer_idx, pre_norm_1, attention_mask, kv_cache).contiguous()
@@ -221,7 +221,7 @@ class Transformer(torch.nn.Module):
         self,
         num_heads: int,
         dtype: torch.dtype,
-        id_mask: Optional[torch.Tensor] = None,
+        id_mask: torch.Tensor | None = None,
     ) -> torch.Tensor:
         """
         Unified method to create and process space-wise masks.
@@ -302,7 +302,7 @@ class Transformer(torch.nn.Module):
         self,
         inputs: torch.Tensor,
         id_mask: torch.Tensor,
-        kv_cache: Optional[KVCache] = None,
+        kv_cache: KVCache | None = None,
     ) -> torch.Tensor:
         batch, _, seq_len, _ = inputs.shape
         # Get the sequence length by looking up a timewise layer in the kv cache.

autogluon/timeseries/models/toto/_internal/dataset.py

@@ -4,7 +4,7 @@
 # Copyright 2025 Datadog, Inc.
 
 from functools import reduce
-from typing import NamedTuple, Union
+from typing import NamedTuple
 
 import numpy as np
 import pandas as pd
@@ -142,7 +142,7 @@ def replace_extreme_values(t: torch.Tensor, replacement: float = 0.0) -> torch.T
     return torch.where(is_extreme_value(t), torch.tensor(replacement, dtype=t.dtype, device=t.device), t)
 
 
-def freq_to_seconds(freq: Union[str, pd.offsets.BaseOffset]) -> float:
+def freq_to_seconds(freq: str | pd.offsets.BaseOffset) -> float:
     # Modified from: https://github.com/DataDog/toto/blob/846d599f4b8d377db3088d5cd1a736d050cef5ac/toto/inference/gluonts_predictor.py#L58
     if isinstance(freq, str):
         freq = pd.tseries.frequencies.to_offset(freq)

autogluon/timeseries/models/toto/_internal/forecaster.py

@@ -4,7 +4,7 @@
 # Copyright 2025 Datadog, Inc.
 
 from dataclasses import dataclass
-from typing import Optional, Union, cast
+from typing import cast
 
 import numpy as np
 import torch
@@ -24,9 +24,9 @@ from .dataset import (
 @dataclass(frozen=True)
 class Forecast:
     mean: torch.Tensor
-    samples: Optional[torch.Tensor]
+    samples: torch.Tensor | None
 
-    def quantile(self, q: Union[float, torch.Tensor]) -> torch.Tensor:
+    def quantile(self, q: float | torch.Tensor) -> torch.Tensor:
         """
         Compute the quantile of the forecast samples.
         """
@@ -88,7 +88,7 @@ class TotoForecaster:
         self,
         inputs: MaskedTimeseries,
         prediction_length: int,
-        num_samples: Optional[int] = None,
+        num_samples: int | None = None,
         samples_per_batch: int = 10,
         use_kv_cache: bool = True,
     ) -> Forecast:
@@ -187,8 +187,8 @@ class TotoForecaster:
         prediction_length: int,
         timestamp_seconds: torch.Tensor,
         time_interval_seconds: torch.Tensor,
-        input_padding_mask: Optional[torch.Tensor] = None,
-        id_mask: Optional[torch.Tensor] = None,
+        input_padding_mask: torch.Tensor | None = None,
+        id_mask: torch.Tensor | None = None,
         use_kv_cache: bool = False,
     ) -> torch.Tensor:
         """
@@ -262,8 +262,8 @@ class TotoForecaster:
         num_samples: int,
         timestamp_seconds: torch.Tensor,
         time_interval_seconds: torch.Tensor,
-        input_padding_mask: Optional[torch.Tensor] = None,
-        id_mask: Optional[torch.Tensor] = None,
+        input_padding_mask: torch.Tensor | None = None,
+        id_mask: torch.Tensor | None = None,
         sampling_batch_size: int = 10,
         use_kv_cache: bool = False,
     ) -> torch.Tensor:

autogluon/timeseries/models/toto/dataloader.py

@@ -1,6 +1,6 @@
 import functools
 import time
-from typing import Any, Callable, Iterator, Optional, Union
+from typing import Any, Callable, Iterator
 
 import numpy as np
 import torch
@@ -44,9 +44,9 @@ class TotoDataLoader:
     def __init__(
         self,
         dataset: TotoInferenceDataset,
-        freq: Optional[str] = None,
+        freq: str | None = None,
         batch_size: int = 1,
-        time_limit: Optional[Union[int, float]] = None,
+        time_limit: int | float | None = None,
         device: Any = None,
     ):
         self.device = torch.device(device)
@@ -60,7 +60,7 @@ class TotoDataLoader:
         self.freq: str = freq or dataset.freq or "h"
 
     @staticmethod
-    def _get_timeout_callback(seconds: Optional[float]) -> Callable:
+    def _get_timeout_callback(seconds: float | None) -> Callable:
         start_time = time.monotonic()
 
         def callback() -> None: