TensorDictModelΒΆ
Use TensorDictModel to define a class-based
schema that maps directly to a TensorDict.
Define a modelΒΆ
import torch
import pandera.tensordict as pa
class RL(pa.TensorDictModel):
"""Schema for reinforcement learning data."""
# Type annotation specifies the dtype (torch.float32, torch.int64, etc.)
observation: torch.float32 = pa.Field(shape=(None, 10))
action: torch.int64 = pa.Field(shape=(None,))
reward: torch.float32 = pa.Field()
Use PyTorch dtypes in type annotations (e.g., torch.float32, torch.int64)
to specify the expected data type. Use Field() to
define additional constraints.
Validate with a modelΒΆ
from tensordict import TensorDict
td = TensorDict(
{"observation": torch.randn(32, 10), "action": torch.randint(0, 4, (32,)), "reward": torch.randn(32)},
batch_size=[32],
)
validated = RL.validate(td)
Field configurationΒΆ
Use Field() to customize field options:
shape: Expected shape tuple (useNonefor variable dimensions)checks: List of Check instances or check argumentsnullable: Whether the key can be missingdefault: Default value if missing
class RLWithConfig(pa.TensorDictModel):
"""RL schema with field-level checks."""
observation: torch.float32 = pa.Field(
shape=(None, 10),
ge=-1.0,
le=1.0,
)
action: torch.int64 = pa.Field(
shape=(None,),
isin=[0, 1, 2, 3],
)
reward: torch.float32 = pa.Field(
gt=0.0,
)
class Config:
batch_size = (32,)
Configuring the modelΒΆ
Use a nested Config class to configure schema-level options:
batch_size: Expected batch size tuple (useNonefor variable dimensions)
class RLWithBatchSize(pa.TensorDictModel):
observation: torch.float32 = pa.Field(shape=(None, 10))
action: torch.int64 = pa.Field(shape=(None,))
class Config:
batch_size = (64,)
Lazy validationΒΆ
Use lazy=True to collect all validation errors:
from tensordict import TensorDict
# Create invalid data with wrong dtypes
td_wrong_dtype = TensorDict(
{"observation": torch.randn(32, 10).to(torch.float64), "action": torch.randint(0, 4, (32,)), "reward": torch.randn(32)},
batch_size=[32],
)
try:
RL.validate(td_wrong_dtype, lazy=True)
except pa.SchemaErrors as e:
print(f"Found {len(e.schema_errors)} validation errors:")
for err in e.schema_errors:
print(f" - {err.reason_code}")
Found 1 validation errors:
- SchemaErrorReason.WRONG_DATATYPE
Type CoercionΒΆ
Model schemas support dtype coercion with the coerce=True option:
class RLWithCoercion(pa.TensorDictModel):
observation: torch.float32 = pa.Field(shape=(None, 10))
class Config:
batch_size = (32,)
coerce = True
# Input with wrong dtype
td = TensorDict(
{"observation": torch.randn(32, 10).to(torch.float64)},
batch_size=[32],
)
# Dtype is automatically coerced during validation
validated = RLWithCoercion.validate(td)
assert validated["observation"].dtype == torch.float32
Model inheritanceΒΆ
Models can be inherited to create more specific schemas:
class BaseRL(pa.TensorDictModel):
observation: torch.float32 = pa.Field(shape=(None, 10))
class Config:
batch_size = (32,)
class ExtendedRL(BaseRL):
action: torch.int64 = pa.Field(shape=(None,))
# ExtendedRL has both 'observation' and 'action'
schema = ExtendedRL.to_schema()
Custom checks in model fieldsΒΆ
Model fields accept one-off :class:~pandera.api.checks.Check objects
through the checks argument, so a schema with a custom check (a valid
one-hot row, an ignore-index label, β¦) no longer has to fall back to the
object API.
from pandera import Check
def is_one_hot(t):
return (t.sum(dim=-1) == 1.0) & ((t == 0) | (t == 1)).all(dim=-1)
class Policy(pa.TensorDictModel):
probs: torch.float32 = pa.Field(
shape=(None, 3),
checks=Check(is_one_hot, name="one_hot", element_wise=False),
)
class Config:
batch_size = (3,)
valid = TensorDict(
{"probs": torch.tensor([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]])},
batch_size=[3],
)
Policy.validate(valid)
TensorDict batch_size=[3]
- probs: f32[3]
Intrinsic checks (like ge, le, isin) can be combined with explicit
Check objects on the same field.
Nested (tuple) keys in modelsΒΆ
TensorDicts can nest, and TorchRL uses that for keys like
("next", "observation"). A model field maps to a nested key with
pa.Field(alias=...):
class NestedRL(pa.TensorDictModel):
next_observation: torch.float32 = pa.Field(
shape=(None, 10),
alias=("next", "observation"),
)
next_reward: torch.float32 = pa.Field(
shape=(None,),
alias=("next", "reward"),
)
class Config:
batch_size = (4,)
nested = TensorDict(
{
"next": TensorDict(
{
"observation": torch.randn(4, 10),
"reward": torch.randn(4),
},
batch_size=[4],
),
},
batch_size=[4],
)
NestedRL.validate(nested)
TensorDict batch_size=[4]
next: 2 entries
- observation: f32[10]
- reward: f32[]
@check_types integrationΒΆ
The check_types() decorator validates function
arguments and return values annotated with TensorDict[Model]:
from pandera import check_types
from pandera.typing.tensordict import TensorDict as TDT
@check_types
def rl_step(td: TDT[RL]) -> TDT[RL]:
return td
# Invalid input (wrong dtype) is caught at the function boundary
bad = TensorDict(
{
"observation": torch.randn(32, 10).to(torch.float64),
"action": torch.randint(0, 4, (32,)),
"reward": torch.randn(32),
},
batch_size=[32],
)
try:
rl_step(bad)
except pa.errors.SchemaError as exc:
print(f"check_types rejected input: {exc.reason_code}")
check_types rejected input: SchemaErrorReason.WRONG_DATATYPE
See alsoΒΆ
TensorDictSchema β dictionary-based schema
Checks and Lazy Validation β value checks
Configuration β validation configuration