Files
2026-11-03 19:46:08 +08:00

268 lines
9.1 KiB
Python

"""Circular buffer for storing a history of batched tensor data.
Understanding Dimensions
========================
Internal storage shape: (max_len, batch_size, ...)
↑ ↑
time environments
axis axis
External view (buffer property): (batch_size, max_len, ...)
↑ ↑
environments time
axis axis
Why different?
- Internal: time-first for clean API (self._buffer[pointer] = data)
- External: batch-first for typical use (iterate over environments)
Backfill Behavior
=================
When you first append to a new or reset batch row, that first value is copied
to ALL history slots for that row:
buffer = CircularBuffer(max_len=3, batch_size=2, device="cpu")
buffer.append(torch.tensor([[5.0], [10.0]]))
# buffer.buffer contains (shape: 2, 3, 1):
# Batch 0: [5.0, 5.0, 5.0] <- all slots filled with first value
# Batch 1: [10.0, 10.0, 10.0] <- all slots filled with first value
Why backfill?
You always have valid data. If training expects 3 frames of history, you
don't want garbage/zeros for the first 2 timesteps.
Per-Batch Reset
===============
Reset affects specific batch rows. The circular pointer advances globally, but
reset rows get "first-append" treatment on their next write:
buffer = CircularBuffer(max_len=3, batch_size=3, device="cpu")
buffer.append(torch.tensor([[1.0], [10.0], [100.0]])) # t0
buffer.append(torch.tensor([[2.0], [20.0], [200.0]])) # t1
buffer.append(torch.tensor([[3.0], [30.0], [300.0]])) # t2
# buffer.buffer:
# Batch 0: [1.0, 2.0, 3.0]
# Batch 1: [10.0, 20.0, 30.0]
# Batch 2: [100.0, 200.0, 300.0]
buffer.reset(batch_ids=[1]) # Reset only batch 1
# buffer.buffer after reset:
# Batch 0: [1.0, 2.0, 3.0] <- unchanged
# Batch 1: [0.0, 0.0, 0.0] <- zeroed
# Batch 2: [100.0, 200.0, 300.0] <- unchanged
# current_length: [3, 0, 3] <- batch 1 has 0 valid frames
buffer.append(torch.tensor([[4.0], [99.0], [400.0]])) # t3
# buffer.buffer after append:
# Batch 0: [2.0, 3.0, 4.0] <- oldest overwritten (normal)
# Batch 1: [99.0, 99.0, 99.0] <- BACKFILLED with 99.0
# Batch 2: [200.0, 300.0, 400.0] <- oldest overwritten (normal)
Key insight:
Reset only affects specific batch rows. The pointer keeps advancing for
everyone, but reset rows get backfilled on their next append.
"""
from __future__ import annotations
from collections.abc import Sequence
import torch
class CircularBuffer:
"""Fixed-length circular buffer for batched tensor history.
Stores history with shape (max_len, batch_size, ...) internally.
The `buffer` property returns chronologically ordered data (oldest to newest)
with shape (batch_size, max_len, ...).
Storage and Retrieval
---------------------
Internal storage (circular):
┌─────┬─────┬─────┐
│ 2 │ 3 │ 1 │ <- pointer at index 1 (newest = 3)
└─────┴─────┴─────┘
idx:0 idx:1 idx:2
buffer property returns (chronological, oldest→newest):
┌─────┬─────┬─────┐
│ 1 │ 2 │ 3 │
└─────┴─────┴─────┘
LIFO Retrieval via __getitem__
-------------------------------
Given buffer with [1, 2, 3] (oldest to newest):
buffer[lag=0] -> 3 (most recent)
buffer[lag=1] -> 2 (one step back)
buffer[lag=2] -> 1 (oldest)
Per-Batch Reset
---------------
After reset(batch_ids=[1]):
Batch 0: [1, 2, 3] (unchanged)
Batch 1: [0, 0, 0] (zeroed, current_length=0)
Batch 2: [1, 2, 3] (unchanged)
Next append backfills reset rows with first value.
Args:
max_len: Maximum number of historical frames to retain.
batch_size: Size of the batch dimension.
device: Torch device for storage.
"""
def __init__(self, max_len: int, batch_size: int, device: str) -> None:
if max_len < 1:
raise ValueError(f"Buffer size must be >= 1, got {max_len}")
self._max_len = max_len
self._batch_size = batch_size
self._device = device
self._pointer: int = -1
self._buffer: torch.Tensor | None = None
self._all_indices = torch.arange(batch_size, device=device)
self._num_pushes = torch.zeros(batch_size, dtype=torch.long, device=device)
self._max_len_tensor = torch.full(
(batch_size,), max_len, dtype=torch.long, device=device
)
@property
def batch_size(self) -> int:
return self._batch_size
@property
def device(self) -> str:
return self._device
@property
def max_length(self) -> int:
return self._max_len
@property
def current_length(self) -> torch.Tensor:
"""Per-batch count of valid frames. Shape: (batch_size,)."""
return torch.minimum(self._num_pushes, self._max_len_tensor)
@property
def is_initialized(self) -> bool:
"""Check if the buffer has been initialized with at least one append."""
return self._buffer is not None
@property
def buffer(self) -> torch.Tensor:
"""History in chronological order (oldest to newest).
Returns:
Tensor of shape (batch_size, max_len, ...) where index 0 is oldest
and index -1 is newest.
"""
if self._buffer is None:
raise RuntimeError("Buffer not initialized. Call append() first.")
start = (self._pointer + 1) % self._max_len
idx = (torch.arange(self._max_len, device=self._device) + start) % self._max_len
buf = self._buffer.index_select(0, idx) # (max_len, batch, ...)
return buf.transpose(0, 1) # (batch, max_len, ...)
def reset(self, batch_ids: Sequence[int] | torch.Tensor | None = None) -> None:
"""Zero out values and counters for specified batch rows.
Args:
batch_ids: Batch indices to reset, or None to reset all.
"""
ids: Sequence[int] | torch.Tensor | slice = (
slice(None) if batch_ids is None else batch_ids
)
self._num_pushes[ids] = 0
if self._buffer is not None:
self._buffer[:, ids] = 0.0
def backfill(self, data: torch.Tensor, batch_ids: torch.Tensor) -> None:
"""Fill the given rows' entire history with one frame, without advancing time.
Unlike append, the global pointer does not move and other rows are
untouched. Used after a partial reset: the reset rows get their first
post-reset frame in every slot (the same backfill their next append would
apply) while the remaining rows keep their history intact.
Args:
data: Tensor of shape (batch_size, ...); only rows at batch_ids are read.
batch_ids: Batch indices to backfill.
"""
if data.shape[0] != self._batch_size:
raise ValueError(f"Expected batch size {self._batch_size}, got {data.shape[0]}")
if self._buffer is None:
raise RuntimeError("Buffer not initialized. Call append() first.")
data = data.to(self._device)
self._buffer[:, batch_ids] = data[batch_ids].unsqueeze(0)
self._num_pushes[batch_ids] = 1
def append(self, data: torch.Tensor) -> None:
"""Append a new frame for all batch elements.
Args:
data: Tensor of shape (batch_size, ...).
"""
if data.shape[0] != self._batch_size:
raise ValueError(f"Expected batch size {self._batch_size}, got {data.shape[0]}")
data = data.to(self._device)
if self._buffer is None:
self._pointer = -1
self._buffer = torch.empty(
(self._max_len, *data.shape), dtype=data.dtype, device=self._device
)
self._pointer = (self._pointer + 1) % self._max_len
self._buffer[self._pointer] = data
# Backfill entire history with first frame for newly initialized batches.
# The condition and data are reshaped to broadcast against the buffer's
# (max_len, batch_size, ...) shape for data of any rank.
is_first_push = self._num_pushes == 0
condition = is_first_push.view(1, self._batch_size, *([1] * (data.ndim - 1)))
torch.where(condition, data.unsqueeze(0), self._buffer, out=self._buffer)
self._num_pushes += 1
def __getitem__(self, key: torch.Tensor | int) -> torch.Tensor:
"""Retrieve lagged frames per batch (LIFO).
Args:
key: Per-batch lags (Tensor) or shared lag (int). Shape (batch_size,) or scalar.
"""
if self._buffer is None:
raise RuntimeError("Buffer not initialized. Call append() first.")
if isinstance(key, int):
key = torch.full((self._batch_size,), key, dtype=torch.long, device=self._device)
else:
if key.ndim == 0:
key = key.expand(self._batch_size)
key = key.to(device=self._device, dtype=torch.long)
if key.numel() != self._batch_size:
raise ValueError(f"Expected {self._batch_size} lags, got {key.numel()}")
# Clamp to the oldest retained frame: without the max_len bound, a lag
# beyond the buffer length would wrap around to a newer frame once
# num_pushes exceeds max_len.
pushes = self._num_pushes.clamp_min(1)
max_lag = torch.minimum(pushes, self._max_len_tensor) - 1
valid = torch.minimum(key, max_lag).clamp_min(0)
idx = torch.remainder(self._pointer - valid, self._max_len)
return self._buffer[idx, self._all_indices]