1 vin.modules.qh_actor_preparation

vin.modules.qh_actor_preparation

Shared actor validation and causal pose preparation for concrete QH models.

This parameter-free stage preserves candidate/step padding, explicit scalar horizon queries, shape admission and factual predecessor semantics. It reads action validity only to validate the actor contract; no returned numeric feature or candidate support depends on authoritative action validity.

1.1 Classes

Name Description
QhActorPreparation Prepare one actor once for feature-independent concrete model stages.
QhActorPreparationConfig Configure the maximum scalar query horizon.
QhPreparedActor Validated B,S,N support and sanitized root-relative geometry.

1.1.1 QhActorPreparation

vin.modules.qh_actor_preparation.QhActorPreparation(config)

Prepare one actor once for feature-independent concrete model stages.

1.1.1.1 Methods

Name Description
forward Validate support, budget and geometry before scoring.
validated_requested_horizon Admit explicit continuing queries or budget-bounded legacy queries.
current_pose_relative_root Return root-from-current-camera \(T_{r\leftarrow c_t}\).
expand_pose Insert and expand pose axes without copying pose storage.
sanitize_pose Reject active non-finite poses and replace inactive rows by identity.
validate_actor Admit boolean support and recorded countdown metadata before arithmetic.
1.1.1.1.1 forward
vin.modules.qh_actor_preparation.QhActorPreparation.forward(
    actor,
    requested_horizon=None,
)

Validate support, budget and geometry before scoring.

1.1.1.1.1.1 Parameters
Name Type Description Default
actor QhActorTensors Batched factual actor; materialization and action validity are separate. Active geometry must be finite. required
requested_horizon Tensor | None Optional Tensor["B S", int64] on the actor device. Legacy queries default to factual remaining budget and cannot exceed it. Continuing queries are required explicitly and are bounded only by configured lookahead capacity. None
1.1.1.1.1.2 Returns
Name Type Description
QhPreparedActor Prepared support and differentiable root-relative poses. At state
QhPreparedActor zero the current pose is identity; later realized states require
QhPreparedActor their immediate predecessor in the factual prefix.
1.1.1.1.1.3 Raises
Name Type Description
ValueError If support shapes, dtypes/devices, causality, scalar bounds, active geometry or predecessor availability disagree.
1.1.1.1.2 validated_requested_horizon
vin.modules.qh_actor_preparation.QhActorPreparation.validated_requested_horizon(
    actor,
    requested_horizon,
)

Admit explicit continuing queries or budget-bounded legacy queries.

Continuing finite lookahead is independent of the recorded replay countdown. The original countdown remains audit metadata on the actor; this method never rewrites it or fabricates successor states.

1.1.1.1.3 current_pose_relative_root
vin.modules.qh_actor_preparation.QhActorPreparation.current_pose_relative_root(
    actor,
    history_pose,
)

Return root-from-current-camera \(T_{r\leftarrow c_t}\).

At chain state \(s_t\), the current camera is the root identity for \(t=0\) and the immediately preceding selected candidate for \(t>0\). A realized non-root state without that predecessor is not a causal transition and fails closed rather than inventing a pose.

1.1.1.1.4 expand_pose
vin.modules.qh_actor_preparation.QhActorPreparation.expand_pose(pose, *sizes)

Insert and expand pose axes without copying pose storage.

1.1.1.1.5 sanitize_pose
vin.modules.qh_actor_preparation.QhActorPreparation.sanitize_pose(
    pose,
    active,
    *,
    name,
)

Reject active non-finite poses and replace inactive rows by identity.

1.1.1.1.6 validate_actor
vin.modules.qh_actor_preparation.QhActorPreparation.validate_actor(actor)

Admit boolean support and recorded countdown metadata before arithmetic.

These checks establish shape/device agreement, contiguous realized states and complete strictly causal history support; pose finiteness and predecessor availability are checked by forward’s subsequent preparation stages. This method does not validate an experiment profile, which remains a concrete scorer responsibility.

1.1.2 QhActorPreparationConfig

vin.modules.qh_actor_preparation.QhActorPreparationConfig()

Configure the maximum scalar query horizon.

1.1.2.1 Attributes

Name Description
max_horizon Maximum scalar lookahead; also bounds factual budgets for the legacy profile.
horizon_query_semantics Bounded defaults to recorded budget; continuing requires an independent explicit query.
target_type Return the parameter-free actor preparation stage.

1.1.3 QhPreparedActor

vin.modules.qh_actor_preparation.QhPreparedActor(
    candidate_mask,
    history_mask,
    candidate_pose,
    history_pose,
    target_pose,
    current_pose,
    requested_horizon,
)

Validated B,S,N support and sanitized root-relative geometry.

Candidate poses have B,S,N axes; history poses B,S,S; target B; current B,S. Horizon is the requested scalar B,S query, separate from factual remaining budget. Masks are boolean; padded poses are neutral identity. Pose storage retains the input floating dtype/device; these are transforms, with translations in metres. Preparation preserves autograd and does not mutate actor tensors. Sanitized poses allocate storage; the returned horizon may alias the requested input or factual budget.

1.1.3.1 Attributes

Name Description
candidate_mask Tensor["B S N", bool] materialized candidates in realized states; independent of hard action validity.
history_mask Tensor["B S S", bool] strictly causal selected-pose support; second S indexes factual history slots.
candidate_pose Root-rig-from-candidate-camera PoseTW with storage shape B S N 12; inactive rows are identity.
history_pose Root-rig-from-selected-camera PoseTW with storage shape B S S 12; unsupported history is identity.
target_pose Root-rig-from-target PoseTW with storage shape B 12; chains with no realized state use identity.
current_pose Root-rig-from-current-camera PoseTW with storage shape B S 12; root and padded states use identity.
requested_horizon Tensor["B S", int64] query horizon, zero on padding; continuing admits [1,max_horizon], legacy additionally bounds it by recorded remaining budget.
Back to top