Implementation:Sktime Pytorch forecasting Utils

Knowledge Sources	Sktime_Pytorch_forecasting
Domains	Time_Series, Forecasting, Deep_Learning
Last Updated	2026-02-08 08:00 GMT

Overview

Core tensor utility functions and mix-in classes for PyTorch forecasting operations including masking, padding, device management, and output formatting.

Description

The Utils module provides a comprehensive set of helper functions and classes used throughout the pytorch-forecasting library. Key functions include create_mask for generating boolean sequence masks, padded_stack for stacking variable-length tensors with padding, move_to_device for recursively transferring nested tensor structures across devices, autocorrelation for computing FFT-based autocorrelation, and to_list for normalizing values into lists.

The module also provides two important mix-in classes: OutputMixIn gives namedtuples dictionary-like access capabilities (with __getitem__, get, items, keys, and iget methods), and TupleOutputMixIn enables converting model outputs to immutable named tuples via to_network_output for graph tracing compatibility.

Usage

Use these utilities when building custom models, processing variable-length sequences, managing tensor devices, or formatting model outputs. They are fundamental building blocks referenced across the entire pytorch-forecasting codebase.

Code Reference

Source Location

• Repository: Sktime_Pytorch_forecasting
• File: pytorch_forecasting/utils/_utils.py
• Lines: 1-616

Signatures

Functions

def integer_histogram(
    data: torch.LongTensor, min: None | int = None, max: None | int = None
) -> torch.Tensor

def groupby_apply(
    keys: torch.Tensor,
    values: torch.Tensor,
    bins: int = 95,
    reduction: str = "mean",
    return_histogram: bool = False,
) -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]

def profile(
    function: Callable, profile_fname: str, filter: str = "", period=0.0001, **kwargs
)

def get_embedding_size(n: int, max_size: int = 100) -> int

def create_mask(
    size: int, lengths: torch.LongTensor, inverse: bool = False
) -> torch.BoolTensor

def autocorrelation(input, dim=0)

def unpack_sequence(
    sequence: torch.Tensor | rnn.PackedSequence,
) -> tuple[torch.Tensor, torch.Tensor]

def concat_sequences(
    sequences: list[torch.Tensor] | list[rnn.PackedSequence],
) -> torch.Tensor | rnn.PackedSequence

def padded_stack(
    tensors: list[torch.Tensor],
    side: str = "right",
    mode: str = "constant",
    value: int | float = 0,
) -> torch.Tensor

def to_list(value: Any) -> list[Any]

def unsqueeze_like(tensor: torch.Tensor, like: torch.Tensor)

def apply_to_list(obj: list[Any] | Any, func: Callable) -> list[Any] | Any

def move_to_device(
    x: dict[str, torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]]
    | torch.Tensor
    | list[torch.Tensor]
    | tuple[torch.Tensor],
    device: str | torch.DeviceObjType,
) -> dict[str, torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]]
    | torch.Tensor
    | list[torch.Tensor]
    | tuple[torch.Tensor]

def detach(
    x: dict[str, torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]]
    | torch.Tensor
    | list[torch.Tensor]
    | tuple[torch.Tensor],
) -> dict[str, torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]]
    | torch.Tensor
    | list[torch.Tensor]
    | tuple[torch.Tensor]

def masked_op(
    tensor: torch.Tensor, op: str = "mean", dim: int = 0, mask: torch.Tensor = None
) -> torch.Tensor

def repr_class(
    obj,
    attributes: list[str] | dict[str, Any],
    max_characters_before_break: int = 100,
    extra_attributes: dict[str, Any] = None,
) -> str

Classes

class OutputMixIn:
    def __getitem__(self, k)
    def get(self, k, default=None)
    def items(self)
    def keys(self)
    def iget(self, idx: int | slice)

class TupleOutputMixIn:
    def to_network_output(self, **results)

class InitialParameterRepresenterMixIn:
    def __repr__(self) -> str
    def extra_repr(self) -> str

Import

from pytorch_forecasting.utils._utils import (
    create_mask,
    padded_stack,
    to_list,
    move_to_device,
    autocorrelation,
    OutputMixIn,
    TupleOutputMixIn,
)

I/O Contract

Inputs

Name	Type	Required	Description
size	int	Yes	Second dimension size for create_mask
lengths	torch.LongTensor	Yes	Tensor of sequence lengths for create_mask
inverse	bool	No	If True, mask is inverted in create_mask (default: False)
tensors	list[torch.Tensor]	Yes	List of tensors to stack for padded_stack
side	str	No	Padding side: "left" or "right" for padded_stack (default: "right")
mode	str	No	Padding mode: "constant", "reflect", "replicate", or "circular" (default: "constant")
value	int or float	No	Padding value for constant mode (default: 0)
x	dict, torch.Tensor, list, or tuple	Yes	Object to move for move_to_device
device	str or torch.DeviceObjType	Yes	Target device for move_to_device (e.g., "cpu", "cuda")
input	torch.Tensor	Yes	Input tensor for autocorrelation
dim	int	No	Dimension for autocorrelation computation (default: 0)

Outputs

Name	Type	Description
mask	torch.BoolTensor	Boolean mask of shape (len(lengths), size) from create_mask
stacked	torch.Tensor	Padded and stacked tensor from padded_stack
moved	dict, torch.Tensor, list, or tuple	Input object relocated to target device from move_to_device
autocorr	torch.Tensor	Autocorrelation of input tensor from autocorrelation
result	list[Any]	Value wrapped in list from to_list

Usage Examples

import torch
from pytorch_forecasting.utils._utils import create_mask, padded_stack, to_list, move_to_device

# Create a boolean mask for variable-length sequences
lengths = torch.tensor([3, 5, 2])
mask = create_mask(size=5, lengths=lengths, inverse=True)
# mask[i, j] is True if lengths[i] > j

# Stack tensors of different lengths with padding
tensors = [torch.randn(3), torch.randn(5), torch.randn(2)]
stacked = padded_stack(tensors, side="right", value=0)
# stacked shape: (3, 5)

# Convert a single value to a list
values = to_list(42)
# values == [42]

# Move a batch dictionary to GPU
batch = {"input": torch.randn(32, 10), "target": torch.randn(32, 5)}
batch = move_to_device(batch, device="cuda")

Related Pages

• Principle:Sktime_Pytorch_forecasting_Tensor_Utilities