1 vin.modules.qh_history_encoders

vin.modules.qh_history_encoders

Modular causal-history summaries for the finite-horizon scorer.

The :math:Q_H actor carries, for every realized state :math:s_t, the strictly causal sequence of previously selected camera poses :math:(T_{r\leftarrow c_0},\ldots,T_{r\leftarrow c_{t-1}}) and an explicit history_mask. The scorer first expresses every selected pose from the current camera and applies its shared pose encoder. This module owns only the map from those row-aligned pose features to one fixed-width history summary; it does not read candidates, targets, rewards, action validity, requested horizon, or remaining budget.

mean_pool_v1 is the H0 control. It reproduces the original masked arithmetic mean exactly and therefore destroys order and multiplicity beyond their effect on the mean. It is parameter-free so pre-existing scorer state dictionaries retain their history_projection keys. The scorer omits its None alias from serialized legacy-equivalent configuration, so older bundle hashes and strict state loading remain valid.

causal_transformer_v1 is the H1 exploratory carrier. It adds a normalized relative-age feature to each current-camera-relative pose token, prepends a learned empty-history token, and applies causal self-attention. The final valid token summarizes the observed prefix; at :math:t=0, the empty token is the summary. Relative age binds chronology to the pose rather than exposing an arbitrary padded slot number. History length is allowed to be observable: it is factual causal state, while remaining budget :math:b_t and requested horizon :math:h remain separate scorer tokens. This does not make step index an independent feature and does not imply stationarity across acquisition lengths.

Both variants return the pose-feature width. The scorer’s existing history_projection then maps that summary into the shared state-token width. Keeping projection outside this seam makes H0 a literal behavioral and checkpoint-compatible control and confines H1’s extra capacity to one named module.

1.1 Attributes

Name Description
QhHistoryEncoderConfig Persisted union of H0/H1 causal-history representation configurations.

1.2 Classes

Name Description
QhCausalTransformerHistoryEncoder Encode selected poses as an ordered, strictly causal prefix.
QhCausalTransformerHistoryEncoderConfig Configure the H1 ordered causal-pose history ablation.
QhMeanPoolHistoryEncoder Return the masked mean of past selected-pose features.
QhMeanPoolHistoryEncoderConfig Configure the parameter-free H0 masked-mean history control.

1.2.1 QhCausalTransformerHistoryEncoder

vin.modules.qh_history_encoders.QhCausalTransformerHistoryEncoder(
    config,
    *,
    feature_dim,
    max_horizon,
    dropout,
)

Encode selected poses as an ordered, strictly causal prefix.

Let :math:a_{t,j}=(t-1-j)/H_{max} be the relative age of selected pose :math:j at decision state :math:t. H1 forms :math:z_{t,j}=p_{t,j}+g(a_{t,j}), prepends a learned empty token, and applies a causal Transformer. Reading the last materialized token permits that summary to attend to the entire observed prefix while preventing any token from reading a later slot. Padded keys are masked and their numeric contents cannot affect the result.

Current-camera-relative pose features already remove arbitrary world origin, while relative age distinguishes paths containing the same pose multiset in a different order. The representation is not claimed to be SE(3)-equivariant, a sufficient scene state, or superior to H0; those are empirical questions for matched held-out and policy evaluation.

1.2.1.1 Methods

Name Description
forward Return Tensor["B S F", float32] last-prefix summaries.
1.2.1.1.1 forward
vin.modules.qh_history_encoders.QhCausalTransformerHistoryEncoder.forward(
    history_features,
    history_mask,
    step_mask,
)

Return Tensor["B S F", float32] last-prefix summaries.

The input contains one independent sequence per decision state. A state’s history may be shorter than the materialized history axis, but any present entry must precede that state on the shared step axis. history_mask is the pose-support mask; authoritative action validity remains outside the representation module. The accompanying step_mask distinguishes the realized empty root state from padded states and lets the seam require an exact prefix rather than merely a subset of earlier slots.

1.2.2 QhCausalTransformerHistoryEncoderConfig

vin.modules.qh_history_encoders.QhCausalTransformerHistoryEncoderConfig()

Configure the H1 ordered causal-pose history ablation.

attention_heads must divide the configured pose-feature width. The feed-forward multiplier and layer count change representation capacity and are therefore persisted experiment identity rather than hidden runtime tuning.

1.2.2.1 Attributes

Name Description
kind Discriminator persisted in scorer and inference-bundle configuration.
attention_heads Parallel temporal-attention heads over one state’s selected prefix.
layers Number of causal Transformer encoder layers.
feedforward_multiplier Per-layer feed-forward width as a multiple of pose-feature width.
target_type Return the runtime H1 history encoder class.

1.2.3 QhMeanPoolHistoryEncoder

vin.modules.qh_history_encoders.QhMeanPoolHistoryEncoder(
    config,
    *,
    feature_dim,
    max_horizon,
    dropout,
)

Return the masked mean of past selected-pose features.

For current-relative pose features :math:p_{t,j} and causal support :math:m_{t,j}, H0 computes

.. math:: p_t = {(1,j m{t,j})}.

Thus the root state returns the all-zero pose summary before the scorer’s learned projection. Permuting valid history entries cannot change H0; that invariance is the control against which an order-sensitive carrier is measured.

1.2.3.1 Methods

Name Description
forward Return Tensor["B S F", float32] masked mean summaries.
1.2.3.1.1 forward
vin.modules.qh_history_encoders.QhMeanPoolHistoryEncoder.forward(
    history_features,
    history_mask,
    step_mask,
)

Return Tensor["B S F", float32] masked mean summaries.

1.2.4 QhMeanPoolHistoryEncoderConfig

vin.modules.qh_history_encoders.QhMeanPoolHistoryEncoderConfig()

Configure the parameter-free H0 masked-mean history control.

1.2.4.1 Attributes

Name Description
kind Discriminator persisted in scorer and inference-bundle configuration.
target_type Return the runtime H0 history encoder class.
Back to top