pytorch/tensordict

A dict[str, torch.Tensor] that behaves like one tensor, and TensorClass: typed, batched dataclasses that compile.

What it solves

Handling groups of tensors in PyTorch—such as training batches, particle systems, or nested data structures—often requires repetitive, manual operations for every individual tensor. TensorDict simplifies this by grouping these tensors into a single object that behaves like a single tensor, eliminating the need for manual recursion or repetitive code.

How it works

A TensorDict stores tensors that share the same leading dimensions (the batch size). Because they are grouped, operations like moving data to a GPU, slicing, shuffling, or stacking are applied to the entire collection at once. It supports nested structures, lazy stacking of variable-sized data, and memory-mapped storage for handling large datasets without loading everything into RAM. It is fully compatible with PyTorch features like torch.compile, vmap, and torch.func.

Who it’s for

It is designed for researchers and developers working on complex PyTorch projects, including reinforcement learning, physics simulations, weather modeling, genomics, and robotics, where managing large, structured batches of data is a core challenge.

Highlights

  • Unified Operations: Perform actions like .to(device), slicing, and stacking on entire groups of tensors simultaneously.
  • Nested Support: Handles nested dictionaries of tensors, allowing for complex data hierarchies.
  • Memory Efficiency: Supports memory-mapped files to work with datasets larger than available memory.
  • Performance Ready: Fully compatible with torch.compile and functional programming tools like vmap.
  • TensorClass: Provides a dataclass-like interface for defining typed fields and methods that automatically operate on batches.

Related

  • Project
  • Project
  • Project
  • Project
  • Project