pytorch/tensordict

What it solves

TensorDict solves the problem of managing complex, nested collections of tensors that need to be treated as a single unit. In standard PyTorch, managing a dictionary of tensors requires manually repeating operations like slicing, device transfers (.to(device)), and arithmetic across every individual tensor. TensorDict provides a unified container that allows these operations to be applied to the entire structure at once, ensuring that all tensors (leaves) share a consistent batch size.

How it works

It functions as a batched, nested dict[str, Tensor] that behaves like a PyTorch tensor. When an operation is performed on a TensorDict, it is automatically dispatched to all the underlying tensors. For example, slicing a TensorDict returns a new TensorDict containing the same structure but with all leaves sliced. It uses PyTorch foreach kernels for high-throughput arithmetic and non-blocking transfers for efficient device movement.

Who it’s for

It is designed for developers building high-performance PyTorch workloads where the unit of data is a structured batch rather than a single tensor. This is particularly common in reinforcement learning (RL) trajectories, LLM post-training samples, robotics trajectories, and scientific ML pipelines.

Highlights

• Tensor-like operations: Supports indexing, slicing, reshaping, stacking, and concatenation across the entire nested structure.
• Casting and Device Management: Single-call device and dtype casting for all leaves.
• High-Performance Memory: Includes memory-mapping (memmap) for large datasets, lazy stacks, and preallocation to reduce memory overhead.
• Functional Programming: Supports @tensorclass for structured tensor objects and compatibility with torch.vmap and to_module for managing model parameters.
• Compile-aware: Dedicated coverage for torch.compile to ensure efficiency in hot paths of training loops.