1 data_handling.qh_data.batching

data_handling.qh_data.batching

Batch construction and tensor transfer for heterogeneous Q_H chains.

Collation pads time, candidate, history, and VIN point axes while preserving the distinct meanings of materialization, actor validity, label support, history validity, and realized steps. Derived masks remain factual views over that stored support; fitted-Q admission stays outside this module. This module owns padding, collation, derived support views, and recursive tensor transfer for QhBatch.

1.1 Classes

Name Description
QhBatch Padded Q_H chain batch with centralized tensor transfer.

1.1.1 QhBatch

data_handling.qh_data.batching.QhBatch(actor, supervision, keys, audits)

Padded Q_H chain batch with centralized tensor transfer.

B denotes chains, S padded rollout states, and N padded candidates. Candidate, action, label, history, and step masks retain their separate support meanings after collation. Tensor transfer and pinning recurse through actor and supervision fields while preserving CPU-only chain keys by identity.

1.1.1.1 Attributes

Name Description
actor Actor-visible tensors with leading B and common state, candidate, history, point, and pose extents.
supervision Oracle label support and factual transition tensors padded exactly like actor state/candidate axes.
keys Length-B CPU-only audit keys in input order; never transferred or exposed to the scorer.
audits Length-B optional diagnostic records aligned with keys and preserved by identity during transfer.
num_steps Return Tensor["B", int64] realized-state counts from step_mask.
selected_train_mask Return Tensor["B S", bool] selected rows with finite immediate-target support.
successor_backup_mask Return Tensor["B S N", bool] label-supported actions at each next state.
successor_action_mask Return Tensor["B S N", bool] actor-valid actions at each next state.
successor_record_present Return Tensor["B S", bool] indicating a recorded next actor state.
actor_successor_present Return Tensor["B S", bool] indicating any actor-valid next-state action.
successor_present Return Tensor["B S", bool] indicating any label-supported next-state action.
bootstrap_mask Return Tensor["B S", bool] rows eligible for a supported TD backup.

1.1.1.2 Methods

Name Description
pin_memory Return a batch with every nested tensor pinned and the same CPU key tuple.
to Move every nested tensor to device while leaving audit keys on the CPU.
1.1.1.2.1 pin_memory
data_handling.qh_data.batching.QhBatch.pin_memory()

Return a batch with every nested tensor pinned and the same CPU key tuple.

1.1.1.2.2 to
data_handling.qh_data.batching.QhBatch.to(device, *, non_blocking=True)

Move every nested tensor to device while leaving audit keys on the CPU.

1.1.1.2.2.1 Parameters
Name Type Description Default
device str | torch.device Destination accepted by torch.Tensor.to. required
non_blocking bool Request asynchronous transfer where the source and destination support it. MPS transfers are always blocking: temporary CPU batches must remain alive until their copies complete, matching Lightning’s MPS transfer policy. True
1.1.1.2.2.2 Returns
Name Type Description
QhBatch New batch with aligned actor and supervision tensors on device.

1.2 Functions

Name Description
collate_qh_chains Pad heterogeneous chain axes and validate factual mask implications.
move_qh_actor_tensors Move nested actor tensors, blocking on MPS to retain CPU-copy lifetimes.

1.2.1 collate_qh_chains

data_handling.qh_data.batching.collate_qh_chains(
    chains,
    *,
    objective_profile='legacy_selected_rows_v1',
)

Pad heterogeneous chain axes and validate factual mask implications.

1.2.1.1 Parameters

Name Type Description Default
chains list[QhChain] Non-empty complete chains in desired batch order. Each chain may have different state, candidate, VIN-point, and trajectory extents while preserving one fixed-task remaining-budget sequence. required

1.2.1.2 Returns

Name Type Description
QhBatch class:QhBatch whose axes cover every input and whose keys retain
QhBatch input order. Boolean support padding is false; rewards, discounts, and
QhBatch poses use zero; selected indices use -1; terminal padding is true;
QhBatch VIN point padding is NaN. Padding never creates actor-valid or
QhBatch label-supported entries, and validation enforces
QhBatch label_mask <= action_mask <= candidate_mask. The dense-valid
QhBatch objective additionally requires finite root-gain rewards exactly on
QhBatch realized actor-valid support. Diagnostic RRI may remain unavailable;
QhBatch both arrays are canonicalized to NaN outside realized support.

1.2.2 move_qh_actor_tensors

data_handling.qh_data.batching.move_qh_actor_tensors(
    actor,
    device,
    *,
    non_blocking=True,
)

Move nested actor tensors, blocking on MPS to retain CPU-copy lifetimes.

CUDA retains the caller’s asynchronous-transfer choice. CPU audit objects remain separate from the actor tensors consumed by the scorer.

Back to top