1 vin.modules

vin.modules

Reusable neural building blocks for VIN scorer architectures.

The package owns torch.nn.Module components that are shared across active and planned VIN scorers, while top-level architecture orchestration remains in aria_nbv.vin.models.

1.1 Attributes

Name	Description
QhCoralSupportProvenance	Closed publishable CORAL support-provenance union.
QhHistoryEncoderConfig	Persisted union of H0/H1 causal-history representation configurations.
QhSceneChannel	Persisted root-EVL channels admitted by root_moments_v1.
QhSceneEncoderConfig	Versioned S0/S1 scene-carrier configurations persisted with the scorer.
QhStateFusionConfig	Discriminated A0/A1 interaction configuration persisted with the scorer.
QhValueDecoderConfig	Persisted union of terminal scalar-Q decoder configurations.

1.2 Classes

Name	Description
PoseConditionedGlobalPool	Attend over a coarse voxel field with candidate pose queries.
QhCausalTransformerHistoryEncoder	Encode selected poses as an ordered, strictly causal prefix.
QhCausalTransformerHistoryEncoderConfig	Configure the H1 ordered causal-pose history ablation.
QhCoralAuxiliary	Training-only CORAL tensors attached to a scalar value prediction.
QhCoralValueDecoder	Decode shared features through cumulative ordinal Q thresholds.
QhCoralValueDecoderConfig	Configure a fixed-support CORAL decoder for continuous fitted-Q targets.
QhCrossAttentionStateFusion	Let each candidate query independently read the shared state tokens.
QhCrossAttentionStateFusionConfig	Configure the A1 candidate-to-state cross-attention interaction.
QhDecodedValue	One decoder’s scalar value and optional objective-specific payload.
QhGeometryOnlySceneEncoder	Zero scene features without observing the scene payload.
QhGeometryOnlySceneEncoderConfig	Ablate root-scene evidence while retaining scorer geometry paths.
QhIndependentMlpStateFusion	Fuse the same named state tokens independently for each candidate.
QhIndependentMlpStateFusionConfig	Configure the A0 identical-feature independent-row MLP control.
QhLegacyFixedCoralSupport	Ambiguous fixed support admitted only for explicit historical inspection.
QhLegacySelectedSurfacePointSceneEncoderConfig	Read the historical S1 discriminator without granting reuse authority.
QhMeanPoolHistoryEncoder	Return the masked mean of past selected-pose features.
QhMeanPoolHistoryEncoderConfig	Configure the parameter-free H0 masked-mean history control.
QhPredeclaredPhysicalCoralSupport	Support fixed by a physical rule before empirical target inspection.
QhRegressionValueDecoder	Decode shared candidate-state features by direct scalar regression.
QhRegressionValueDecoderConfig	Configure the canonical direct continuous-Q regression decoder.
QhRootMomentsSceneEncoder	Encode immutable root evidence as global moments.
QhRootMomentsSceneEncoderConfig	Configure the explicit parameter-free S0 root-moments control.
QhSelectedSurfacePointSceneEncoder	Add a bounded causal selected-surface residual to root moments.
QhSelectedSurfacePointSceneEncoderConfig	Configure the privileged S1 selected-surface point memory.
QhTrainFittedCoralSupport	Support fitted only from a frozen ordered training population.
QhVolumeReadout	Fuse one causal state volume and attend its supported spatial tokens.
QhVolumeReadoutConfig	Configure causal volume construction and candidate-local token reading.
SceneFieldProjection	Project scalar voxel evidence channels into VIN field features.
SceneFieldProjectionConfig	Configure the trainable VIN scene-field projection.
SemidenseGridEncoder	Encode semidense projection grids with a small convolutional head.
SemidenseGridEncoderConfig	Configure the VIN semidense projection-grid CNN.
VinScorerHead	Predict ordinal RRI logits from per-candidate feature vectors.
VinScorerHeadConfig	Configure the shared VIN ordinal scoring head.
VolumeEncoder	Encode fixed evidence and support without changing the grid geometry.
VolumeEncoderConfig	Configure a native-Torch dense evidence-volume encoder.

1.2.1 PoseConditionedGlobalPool

vin.modules.PoseConditionedGlobalPool(
    field_dim,
    pose_dim,
    pool_size,
    num_heads,
    pos_grid_encoder,
)

Attend over a coarse voxel field with candidate pose queries.

The module summarizes a projected voxel field into one descriptor per candidate pose. It down-samples the field into tokens, encodes each token’s normalized position grid, and uses candidate pose embeddings as attention queries over voxel content.

Positional embeddings are added only to keys. Values stay pure field-content projections, so attention weights depend on position while the returned descriptors remain content summaries conditioned by pose.

Each candidate query attends to the same voxel-token set independently; queries never attend to one another. Permuting the N_q pose rows thus permutes the N_q outputs. The normalized position encoder makes the block reference-frame-aware, but does not enforce SE(3) equivariance or a graph-isomorphism invariant.

1.2.1.1 Methods

Name	Description
forward	Return pose-conditioned global field descriptors.

1.2.1.1.1 forward

vin.modules.PoseConditionedGlobalPool.forward(field, pose_enc, *, pos_grid)

Return pose-conditioned global field descriptors.

1.2.1.1.1.1 Parameters

Name	Type	Description	Default
field	Tensor	Tensor["B C D H W"] projected voxel field.	required
pose_enc	Tensor	Tensor["B N_q E", float32] candidate pose embeddings.	required
pos_grid	Tensor	Tensor["B 3 D H W"] normalized voxel positions.	required

1.2.1.1.1.2 Returns

Name	Type	Description
	Tensor	Tensor["B N_q C", float32] global features for each candidate.

1.2.2 QhCausalTransformerHistoryEncoder

vin.modules.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.2.1 Methods

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

1.2.2.1.1 forward

vin.modules.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.3 QhCausalTransformerHistoryEncoderConfig

vin.modules.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.3.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.4 QhCoralAuxiliary

vin.modules.QhCoralAuxiliary(logits, bin_edges, bin_values)

Training-only CORAL tensors attached to a scalar value prediction.

1.2.4.1 Attributes

Name	Type	Description
logits	Tensor	Tensor["B S N K-1", floating] cumulative logits for \(P(y > k)\). Candidate order matches conditional_q.
bin_edges	Tensor	Tensor["K-1", floating] strictly increasing boundaries used to map continuous fitted-Q targets to ordinal labels via torch.bucketize. These edges never mask or rank actions.
bin_values	Tensor	Tensor["K", floating] strictly increasing continuous-Q representatives used to decode class marginals. Lightning uses the outer representatives only for support-saturation diagnostics.

1.2.5 QhCoralValueDecoder

vin.modules.QhCoralValueDecoder(config, *, in_dim, hidden_dim, dropout)

Decode shared features through cumulative ordinal Q thresholds.

CORAL shares one projection across thresholds and learns ordered-rank evidence for a discretized scalar target. The runtime still diagnoses adjacent cumulative-probability violations and repairs negative marginal class mass before decoding, because neither ranking nor Bellman backup may consume an invalid probability vector. This repair does not make the threshold probabilities calibrated; that remains an evaluation question.

1.2.5.1 Methods

Name	Description
validate_configured_support	Reject persisted ordinal support that disagrees with configuration.
require_publishable_support	Reject historical fixed support lacking construction provenance.
forward	Return ordinal logits and their continuous conditional-Q expectation.

1.2.5.1.1 validate_configured_support

vin.modules.QhCoralValueDecoder.validate_configured_support()

Reject persisted ordinal support that disagrees with configuration.

bin_edges and bin_values are persistent buffers because they helped define the training labels and the scalar decode, respectively. Loading a same-shaped state dictionary can otherwise overwrite support constructed from the manifest without a PyTorch shape error. Bundle publication, warm start, and inference therefore call this method after reconstruction or state loading so the manifest-advertised ordinal experiment remains identical to the executable decoder.

1.2.5.1.2 require_publishable_support

vin.modules.QhCoralValueDecoder.require_publishable_support()

Reject historical fixed support lacking construction provenance.

1.2.5.1.3 forward

vin.modules.QhCoralValueDecoder.forward(features)

Return ordinal logits and their continuous conditional-Q expectation.

The repaired marginal probabilities are used only to form :math:\sum_k p_k u_k. This scalar has the same fitted-Q units as the regression decoder and is therefore safe for the unchanged backup and hard-masked ranking paths. The attached threshold logits retain the standard CORAL loss without a second scorer forward pass.

1.2.6 QhCoralValueDecoderConfig

vin.modules.QhCoralValueDecoderConfig()

Configure a fixed-support CORAL decoder for continuous fitted-Q targets.

For K ordered classes, bin_edges contains K-1 boundaries and bin_values contains K continuous representatives. A target :math:y is assigned bucketize(y, edges) and trained with standard CORAL cumulative binary cross-entropy. At inference, repaired class probabilities :math:p_k decode to :math:Q^{cond}=\sum_k p_k u_k using the fixed representatives u_k.

Edge and representative identity is part of the checkpoint manifest. The outer classes remain open-ended, but their decoded values saturate at the first and last representatives; experiments must therefore report target support and saturation rather than interpreting ordinal bins as calibrated uncertainty.

1.2.6.1 Notes

support is the single owner of boundaries, representatives, source population, split role, construction method, return units, and artifact digest. train_fitted_v1 is closed to training rows and predeclared_physical_v1 is fixed before empirical outcomes. The legacy discriminator exists only to read historical configurations and is rejected by bundle publication, warm start, and inference.

1.2.6.2 Attributes

Name	Description
kind	Discriminator persisted in scorer and bundle configuration.
support	Versioned support plus its construction provenance and artifact identity.
preinit_bias	Use the upstream CORAL threshold-bias initialization.
target_type	Return the runtime CORAL decoder class.
bin_edges	Return the support’s fitted-Q label boundaries.
bin_values	Return the support’s continuous-Q representatives.

1.2.7 QhCrossAttentionStateFusion

vin.modules.QhCrossAttentionStateFusion(
    config,
    *,
    hidden_dim,
    state_token_count,
    dropout,
)

Let each candidate query independently read the shared state tokens.

A1 computes :math:c_{t,i}=\operatorname{CrossAttn}(x_{t,i},Z_t,Z_t). State tokens are shared within one state, but candidate queries never serve as keys or values. Consequently no candidate can change another candidate’s context, and no candidate mask is required inside this module. Padding is sanitized by the scorer before fusion and zeroed at its output boundary; authoritative action validity remains adapter-owned.

1.2.7.1 Methods

Name	Description
forward	Return Tensor["B S N H", float32] A1 candidate contexts.

1.2.7.1.1 forward

vin.modules.QhCrossAttentionStateFusion.forward(candidate_queries, state_tokens)

Return Tensor["B S N H", float32] A1 candidate contexts.

1.2.8 QhCrossAttentionStateFusionConfig

vin.modules.QhCrossAttentionStateFusionConfig()

Configure the A1 candidate-to-state cross-attention interaction.

1.2.8.1 Attributes

Name	Description
kind	Discriminator persisted in scorer and inference-bundle configuration.
attention_heads	Parallel candidate-to-state attention heads; must divide scorer width.
target_type	Return the runtime A1 state-fusion class.

1.2.9 QhDecodedValue

vin.modules.QhDecodedValue(conditional_q, coral=None)

One decoder’s scalar value and optional objective-specific payload.

conditional_q always has the candidate-aligned leading shape and is the only value consumed by Bellman backup or online ranking. coral exists only for the ordinal training objective; regression leaves it None.

1.2.9.1 Attributes

Name	Description
conditional_q	Tensor["...", float32] conditional value in additive fitted-Q units.
coral	Ordinal training payload, or None for direct regression.

1.2.10 QhGeometryOnlySceneEncoder

vin.modules.QhGeometryOnlySceneEncoder(config, *, scene_channels, dropout=0.0)

Zero scene features without observing the scene payload.

Candidate/target poses, causal pose history and budget/horizon remain in the enclosing scorer. This control tests the added value of root EVL and semidense evidence under identical downstream capacity and input admission. It does not establish sufficiency for value prediction. The enclosing scorer retains source-profile admission checks.

1.2.10.1 Methods

Name	Description
forward	Return float32 zeros of shape (B, F) on the actor device.

1.2.10.1.1 forward

vin.modules.QhGeometryOnlySceneEncoder.forward(actor)

Return float32 zeros of shape (B, F) on the actor device.

Only batch size and device of step_mask are read. Scene, point, depth, reward and label values do not contribute to the output.

1.2.11 QhGeometryOnlySceneEncoderConfig

vin.modules.QhGeometryOnlySceneEncoderConfig()

Ablate root-scene evidence while retaining scorer geometry paths.

1.2.11.1 Attributes

Name	Description
kind	Explicit information-subset control; never aliases root moments.
target_type	Return the parameter-free zero scene carrier.

1.2.12 QhIndependentMlpStateFusion

vin.modules.QhIndependentMlpStateFusion(
    config,
    *,
    hidden_dim,
    state_token_count,
    dropout,
)

Fuse the same named state tokens independently for each candidate.

For candidate query :math:x_{t,i} and ordered state-token tuple :math:Z_t, A0 computes :math:c_{t,i}=\operatorname{MLP}([x_{t,i};\operatorname{vec}(Z_t)]). The fixed token order is semantic—not sampled candidate order—and lets the control retain every input available to A1 without content-adaptive token selection. The shared row-wise map preserves candidate permutation equivariance and duplicate-row identity by construction.

1.2.12.1 Methods

Name	Description
forward	Return Tensor["B S N H", float32] A0 candidate contexts.

1.2.12.1.1 forward

vin.modules.QhIndependentMlpStateFusion.forward(candidate_queries, state_tokens)

Return Tensor["B S N H", float32] A0 candidate contexts.

1.2.12.1.1.1 Parameters

Name	Type	Description	Default
candidate_queries	Tensor	Candidate-local value queries with shape [B,S,N,H]. Rows are processed independently.	required
state_tokens	Tensor	Shared named tokens with shape [B,S,K,H] in the scorer-defined semantic order, where K equals the manifest-bound constructor value.	required

1.2.13 QhIndependentMlpStateFusionConfig

vin.modules.QhIndependentMlpStateFusionConfig()

Configure the A0 identical-feature independent-row MLP control.

1.2.13.1 Attributes

Name	Description
kind	Discriminator persisted in scorer and inference-bundle configuration.
target_type	Return the runtime A0 state-fusion class.

1.2.14 QhLegacyFixedCoralSupport

vin.modules.QhLegacyFixedCoralSupport()

Ambiguous fixed support admitted only for explicit historical inspection.

1.2.14.1 Attributes

Name	Description
provenance_kind	Non-publishable legacy discriminator.
bin_edges	Historical label boundaries with no verified construction provenance.
bin_values	Historical representatives with no verified construction provenance.

1.2.15 QhLegacySelectedSurfacePointSceneEncoderConfig

vin.modules.QhLegacySelectedSurfacePointSceneEncoderConfig()

Read the historical S1 discriminator without granting reuse authority.

The old ...selected_surface_points_v1 label did not say whether the residual projection was random- or identity-initialized. It can therefore reconstruct an archived state dictionary for inspection, but cannot define a new fit, warm start, inference runtime, or scientific bundle. New work uses QhSelectedSurfacePointSceneEncoderConfig, whose discriminator makes the zero-residual initialization part of architecture identity.

1.2.15.1 Attributes

Name	Description
kind	Ambiguous historical discriminator classified as unknown_legacy_v1.
pixel_stride	Historical deterministic raster stride.
view_chunk_size	Historical selected-view chunk bound.
point_hidden_dim	Historical shared point-feature width.
coordinate_scale_m	Historical current-camera coordinate divisor.
target_type	Return the runtime class solely for historical inspection.

1.2.16 QhMeanPoolHistoryEncoder

vin.modules.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.16.1 Methods

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

1.2.16.1.1 forward

vin.modules.QhMeanPoolHistoryEncoder.forward(
    history_features,
    history_mask,
    step_mask,
)

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

1.2.17 QhMeanPoolHistoryEncoderConfig

vin.modules.QhMeanPoolHistoryEncoderConfig()

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

1.2.17.1 Attributes

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

1.2.18 QhPredeclaredPhysicalCoralSupport

vin.modules.QhPredeclaredPhysicalCoralSupport()

Support fixed by a physical rule before empirical target inspection.

1.2.18.1 Attributes

Name	Description
provenance_kind	Promotable support-provenance discriminator.
construction_method	Construction family that is independent of observed target outcomes.
split_role	Explicit statement that no empirical dataset split selected the support.
physical_rule	Versioned rule identifier from which boundaries and representatives derive.

1.2.18.2 Methods

Name	Description
create	Construct a self-addressed physically predeclared support artifact.

1.2.18.2.1 create

vin.modules.QhPredeclaredPhysicalCoralSupport.create(
    source_population_digest,
    ordered_input_digest,
    physical_rule,
    bin_edges,
    bin_values,
)

Construct a self-addressed physically predeclared support artifact.

1.2.19 QhRegressionValueDecoder

vin.modules.QhRegressionValueDecoder(config, *, in_dim, hidden_dim, dropout)

Decode shared candidate-state features by direct scalar regression.

This is the canonical decoder because its output and Huber target already share the additive root-gain return units required by Bellman recursion. It adds no bin support, ordinal interpretation, or return-distribution hypothesis to the representation comparison.

1.2.19.1 Methods

Name	Description
forward	Return direct Tensor["...", float32] conditional-Q values.

1.2.19.1.1 forward

vin.modules.QhRegressionValueDecoder.forward(features)

Return direct Tensor["...", float32] conditional-Q values.

1.2.20 QhRegressionValueDecoderConfig

vin.modules.QhRegressionValueDecoderConfig()

Configure the canonical direct continuous-Q regression decoder.

1.2.20.1 Attributes

Name	Description
kind	Discriminator persisted in scorer and bundle configuration.
initial_output_bias	Optional explicit native-Q scalar output bias; None preserves seeded initialization.
target_type	Return the runtime direct-regression decoder class.

1.2.21 QhRootMomentsSceneEncoder

vin.modules.QhRootMomentsSceneEncoder(
    config=None,
    *,
    scene_channels,
    dropout=0.0,
)

Encode immutable root evidence as global moments.

For every configured scalar EVL field :math:x_c, the encoder records :math:(\mu_c,\sigma_c,\min x_c,\max x_c). Let :math:T_{r\leftarrow w} be root-from-world and :math:p_k^w a supported semidense point. Root-frame points :math:p_k^r=T_{r\leftarrow w}p_k^w contribute coordinate-wise mean and population standard deviation. Two final scalars distinguish no points from measured all-zero geometry: presence is :math:1[|P|>0], while support is the finite supported-count divided by that chain’s persisted point length. The latter is the pre-collation row capacity carried by :attr:VinSnippet.lengths; batch padding is only a storage detail and cannot change a physical state feature. Empty chains use support zero rather than dividing by zero.

The resulting width is 4 * len(scene_channels) + 8. Source tensors are detached because this carrier consumes persisted actor observations; it is not an end-to-end EFM3D training path. Jointly translating the world points and root pose leaves the point moments invariant. The evidence is immutable within one stored chain; scorer orchestration owns repetition over states and downstream candidate and step masks.

1.2.21.1 Methods

Name	Description
forward	Return Tensor["B F", float32] root-scene features.

1.2.21.1.1 forward

vin.modules.QhRootMomentsSceneEncoder.forward(actor)

Return Tensor["B F", float32] root-scene features.

B is taken from actor.step_mask and F == output_dim. Missing configured EVL fields, non-finite source values, malformed point capacity, and non-finite active root poses fail closed instead of being encoded as ordinary zeros.

1.2.22 QhRootMomentsSceneEncoderConfig

vin.modules.QhRootMomentsSceneEncoderConfig()

Configure the explicit parameter-free S0 root-moments control.

1.2.22.1 Attributes

Name	Description
kind	Versioned scene-carrier discriminator persisted with the scorer.
target_type	Return the runtime root-moments encoder class.

1.2.23 QhSelectedSurfacePointSceneEncoder

vin.modules.QhSelectedSurfacePointSceneEncoder(
    config,
    *,
    scene_channels,
    dropout,
)

Add a bounded causal selected-surface residual to root moments.

For state :math:s_t, the carrier admits only selected observations :math:0\le j<t. Selection at decision :math:j realizes camera :math:\mathsf{C}_{j+1}. The persisted camera and pose define :math:\boldsymbol{T}_{\mathsf{C}_{j+1}}^{\mathsf{R}_0}; canonical backprojection therefore returns root-frame points. The scorer supplies factual :math:\boldsymbol{T}_{\mathsf{C}_t}^{\mathsf{R}_0}, and the encoder forms :math:p^{\mathsf{C}_t}=\boldsymbol{T}_{\mathsf{R}_0}^{\mathsf{C}_t}p^{\mathsf{R}_0}. Dividing XYZ by the configured metric scale yields each set element; no target, candidate, budget, horizon, reward, label, or authoritative action mask enters this path.

A shared MLP maps every valid sampled point independently. Masked mean and elementwise maximum are invariant to point order. They are not generally invariant to partial duplication: overlapping observations receive one vote per valid sampled pixel, so S1 is explicitly a density-weighted surface-set control. Three diagnostics remain learned inputs: presence, valid sampled pixels divided by causal sampled-pixel capacity, and observations with any valid point divided by causal observation count. Empty prefixes produce an exact zero residual.

Geometry validation, backprojection, frame transforms, and point-set reductions remain float32 under mixed-precision training. Autocast is retained for the learned point encoder and final residual projection, so reduced-precision execution cannot change geometric support or make the float32 sum/max accumulators dtype-incompatible.

The output is Tensor["B S F_root", float32]. It adds a learned point update to the unchanged static root moments and zeros padded states. Let :math:g_t^{\mathrm{S1}} denote the pooled point statistic and :math:W_{\mathrm{pt}} the bias-free final projection. Initializing :math:W_{\mathrm{pt}}^{(0)}=0 makes :math:\Phi_t^{\mathrm{S1},(0)}=\Phi_t^{\mathrm{root}} exactly. This is an experimental-control property, not a claim that the surface branch is initially useless: for downstream loss :math:L, :math:\partial L/\partial W_{\mathrm{pt}} can be nonzero immediately because :math:g_t^{\mathrm{S1}} is already nonzero. The upstream point MLP receives zero gradient on that first step through the zero projection and begins learning once the projection departs from zero.

The fixed width and identity start prevent S1 from changing downstream scorer shapes or initial predictions. This carrier still cannot distinguish observed free space from unknown space or retain ray direction after fusion; those are S2 responsibilities.

1.2.23.1 Methods

Name	Description
forward	Return fixed-width state features for every realized decision state.

1.2.23.1.1 forward

vin.modules.QhSelectedSurfacePointSceneEncoder.forward(
    actor,
    *,
    current_pose_relative_root,
)

Return fixed-width state features for every realized decision state.

1.2.23.1.1.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched CF+ actor whose selected-observation prefix has exact [B,S,S,H,W] causal support.	required
current_pose_relative_root	PoseTW	PoseTW["B S 12"] storing root-from-current-camera poses derived once by the scorer.	required

1.2.23.1.1.2 Returns

Name	Type	Description
	Tensor	Tensor["B S F_root", float32] equal to repeated root moments
	Tensor	plus the selected-surface residual on realized states, and zero on
	Tensor	padded states.

1.2.24 QhSelectedSurfacePointSceneEncoderConfig

vin.modules.QhSelectedSurfacePointSceneEncoderConfig()

Configure the privileged S1 selected-surface point memory.

The raster stride and view-chunk bound are representation identity. They determine which stored pixels become set elements and the largest number of selected views backprojected at once. coordinate_scale_m only nondimensionalizes current-camera XYZ before the shared point MLP; it is neither a clipping radius nor an asserted scene extent. The residual’s zero-output initialization is part of this versioned architecture: a fresh S1 model is exactly its source-matched H0 control, without adding a config switch or a second initialization profile.

1.2.24.1 Attributes

Name	Description
kind	Active identity-start S1 carrier and representation_semantics value.
pixel_stride	Deterministic row/column stride applied before canonical depth backprojection.
view_chunk_size	Maximum flattened selected-view rows backprojected in one call.
point_hidden_dim	Shared point-feature width before invariant mean/maximum pooling.
coordinate_scale_m	Metric divisor for current-camera XYZ supplied to the point MLP.
target_type	Return the runtime selected-surface encoder class.

1.2.25 QhTrainFittedCoralSupport

vin.modules.QhTrainFittedCoralSupport()

Support fitted only from a frozen ordered training population.

1.2.25.1 Attributes

Name	Description
provenance_kind	Promotable support-provenance discriminator.
construction_method	Training construction: empirical quantiles, or fixed edges with train-bin means.
split_role	Closed leakage boundary; validation and test targets are never admissible.

1.2.25.2 Methods

Name	Description
create	Address supplied support and its declared training construction.

1.2.25.2.1 create

vin.modules.QhTrainFittedCoralSupport.create(
    source_population_digest,
    ordered_input_digest,
    bin_edges,
    bin_values,
    construction_method='empirical_quantiles_v1',
)

Address supplied support and its declared training construction.

The caller owns fitting and its frozen training population. For predeclared_edges_train_means_v1, edges must be predeclared and representatives must be means of the corresponding training bins. This factory validates numeric support and binds construction identity; it does not inspect targets or perform the fitting itself.

1.2.26 QhVolumeReadout

vin.modules.QhVolumeReadout(config)

Fuse one causal state volume and attend its supported spatial tokens.

Each state is constructed from immutable root evidence and exactly the selected observations with indices j < s. All state volumes are encoded once in one batched encoder call. For each candidate, the existing target OBB lattice and candidate-to-target ray supply tokens. Their learned volume values are concatenated with deterministic scene channels, candidate-frame relative XYZ, and a target/ray region identity before masked attention.

A candidate occupies its own attention batch row. Candidate rows cannot exchange features, action validity is never read, and an all-unsupported token set returns finite zero learned features plus explicit support or mass/absence statistics. Weighted modes normalize each region separately and retain a fixed one-half mixture without empty-region renormalization. No state survives beyond one :meth:forward call.

1.2.26.1 Methods

Name	Description
forward	Return candidate-aligned volume features for every causal state.

1.2.26.1.1 forward

vin.modules.QhVolumeReadout.forward(actor)

Return candidate-aligned volume features for every causal state.

1.2.26.1.1.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched QH actor. root_only rejects any privileged selected carrier. selected_depth requires the exact CF-GT causal prefix and integrates it in factual index order.	required

1.2.26.1.1.2 Returns

Name	Type	Description
	QhCandidateFeatures	class:QhCandidateFeatures with Tensor["B S N F", float32]
	QhCandidateFeatures	values. The learned prefix of width attention_dim is available
	QhCandidateFeatures	for positive-measure in-map tokens, including explicit unknown
	QhCandidateFeatures	space (legacy attention does not require positive measure). Legacy
	QhCandidateFeatures	outputs append four measured-support statistics; weighted outputs
	QhCandidateFeatures	append fourteen region-wise mass/fraction/absence columns, all
	QhCandidateFeatures	defined for every materialized candidate.

1.2.27 QhVolumeReadoutConfig

vin.modules.QhVolumeReadoutConfig()

Configure causal volume construction and candidate-local token reading.

1.2.27.1 Attributes

Name	Description
propagation_exclude_fields	Readout identity and regularization never overwrite nested configs.
kind	Closed candidate-readout discriminator.
aggregation	Legacy joint attention or versioned, measure-aware region-wise reductions.
evidence_mode	Immutable root evidence or privileged causal selected-depth fusion.
fusion	Fixed chart, grid, source normalization, and fusion tolerances.
encoder	Learned two-scale volume encoder or projection-only ablation.
ray_samples	Existing candidate-to-target ray sample count, including endpoints.
attention_dim	Candidate-local token and attended-feature width.
attention_heads	Multi-head attention count; candidates never share an attention row.
dropout	Attention dropout used only in training mode.
candidate_chunk_size	Maximum candidate rows sampled and attended at once.
feature_spec	Return learned feature and explicit support-statistic identities.
target_type	Return the configured candidate-local volume readout.

1.2.28 SceneFieldProjection

vin.modules.SceneFieldProjection(config)

Project scalar voxel evidence channels into VIN field features.

The class subclasses torch.nn.Sequential so models can assign it directly to field_proj while preserving historical checkpoint keys such as field_proj.0.weight, field_proj.1.weight, and field_proj.1.bias.

1.2.29 SceneFieldProjectionConfig

vin.modules.SceneFieldProjectionConfig()

Configure the trainable VIN scene-field projection.

1.2.29.1 Attributes

Name	Description
target_type	Factory target for BaseConfig.setup_target.
in_channels	Number of ordered scalar scene-field channels.
field_dim	Projected voxel feature dimension.
field_gn_groups	Requested GroupNorm groups, clamped to a divisor of field_dim.

1.2.30 SemidenseGridEncoder

vin.modules.SemidenseGridEncoder(config)

Encode semidense projection grids with a small convolutional head.

The class subclasses torch.nn.Sequential intentionally: when assigned to VinModelV3.semidense_cnn, learnable parameters keep the historical checkpoint keys semidense_cnn.0.*, semidense_cnn.2.*, and semidense_cnn.6.*. Do not wrap the layers in a child module unless a checkpoint migration is planned.

1.2.30.1 Methods

Name	Description
encode_projection_features	Return one CNN feature vector per batch/candidate projection.

1.2.30.1.1 encode_projection_features

vin.modules.SemidenseGridEncoder.encode_projection_features(
    proj_data,
    *,
    batch_size,
    num_candidates,
    device,
    dtype,
)

Return one CNN feature vector per batch/candidate projection.

1.2.30.1.1.1 Parameters

Name	Type	Description	Default
proj_data	dict[str, Tensor]	Projection output from aria_nbv.vin.geometry.semidense_projection.project_points_to_candidate_cameras.	required
batch_size	int	Batch size B.	required
num_candidates	int	Number of candidate cameras N_q.	required
device	torch.device	Device for the intermediate projection grid.	required
dtype	torch.dtype	Floating point dtype for the grid and returned features.	required

1.2.30.1.1.2 Returns

Name	Type	Description
	Tensor	Tensor["B N_q F", float32] where F is
	Tensor	SemidenseGridEncoderConfig.out_dim.

1.2.31 SemidenseGridEncoderConfig

vin.modules.SemidenseGridEncoderConfig()

Configure the VIN semidense projection-grid CNN.

1.2.31.1 Attributes

Name	Description
target_type	Factory target for BaseConfig.setup_target.
grid_size	Spatial side length of the deterministic projection grid.
channels	Hidden channel width for the convolutional layers.
out_dim	Output feature dimension per candidate projection.

1.2.32 VinScorerHead

vin.modules.VinScorerHead(config, *, in_dim=None)

Predict ordinal RRI logits from per-candidate feature vectors.

VinScorerHead is the shared MLP-plus-CORAL head used when a VIN scorer represents candidate quality as ordinal Relative Reconstruction Improvement bins. It consumes the final feature tensor produced by an architecture and returns threshold logits compatible with aria_nbv.vin.ordinal.

The MLP and CORAL layer act on the last dimension only and introduce no candidate-to-candidate interaction or graph structure. Row permutations are exactly equivariant in evaluation mode (or with zero dropout); sampled training dropout preserves that symmetry only in distribution.

1.2.32.1 Methods

Name	Description
forward	Return CORAL threshold logits for candidate features.

1.2.32.1.1 forward

vin.modules.VinScorerHead.forward(x)

Return CORAL threshold logits for candidate features.

1.2.32.1.1.1 Parameters

Name	Type	Description	Default
x	Tensor	Tensor["... F", float32] feature vectors, where leading dimensions are preserved as candidate or batch axes.	required

1.2.32.1.1.2 Returns

Name	Type	Description
	Tensor	Tensor["... K-1", float32] CORAL logits for K ordinal RRI classes.

1.2.33 VinScorerHeadConfig

vin.modules.VinScorerHeadConfig()

Configure the shared VIN ordinal scoring head.

1.2.33.1 Attributes

Name	Description
target_type	Factory target for BaseConfig.setup_target.
hidden_dim	Hidden dimension for MLP layers.
num_layers	Number of MLP layers before the CORAL layer.
dropout	Dropout probability in the MLP.
num_classes	Number of ordinal bins (VIN-NBV uses 15).
coral_preinit_bias	Whether to initialize CORAL threshold biases with ordinal defaults.
activation	Activation function.

1.2.33.2 Methods

Name	Description
setup_target	Instantiate the configured scoring head.

1.2.33.2.1 setup_target

vin.modules.VinScorerHeadConfig.setup_target(in_dim=None)

Instantiate the configured scoring head.

1.2.33.2.1.1 Parameters

Name	Type	Description	Default
in_dim	int | None	Optional input feature width passed to VinScorerHead.	None

1.2.33.2.1.2 Returns

Name	Type	Description
	VinScorerHead	Runtime scoring module.

1.2.34 VolumeEncoder

vin.modules.VolumeEncoder(config)

Encode fixed evidence and support without changing the grid geometry.

The input projection receives the deterministic evidence channels together with a separate binary support channel. The full encoder refines the fine grid, constructs a 2C half-resolution carrier, and fuses its upsampled context back into the original grid. Learned features never redefine support: callers retain and sample the supplied mask independently.

1.2.34.1 Attributes

Name	Description
output_channels	Return the encoded feature width.

1.2.34.2 Methods

Name	Description
forward	Encode one or more evidence grids while preserving their resolution.

1.2.34.2.1 forward

vin.modules.VolumeEncoder.forward(evidence, availability)

Encode one or more evidence grids while preserving their resolution.

1.2.34.2.1.1 Parameters

Name	Type	Description	Default
evidence Tensor["B C D H W", float32]		Deterministic volume channels. C must equal VolumeEncoderConfig.input_channels.	required
availability Tensor["B 1 D H W", bool]		Explicit measured support. It is an input feature and remains owned by the caller.	required

1.2.34.2.1.2 Returns

Name	Type	Description
	Tensor	Tensor["B C_e D H W", float] learned features on the input
	Tensor	device. Gradients propagate to floating evidence and encoder weights.

1.2.34.2.1.3 Raises

Name	Type	Description
	ValueError	If ranks, shapes, dtype, device, or finite-value contracts are violated, or a full encoder receives a grid too small for its coarse scale.

1.2.35 VolumeEncoderConfig

vin.modules.VolumeEncoderConfig()

Configure a native-Torch dense evidence-volume encoder.

1.2.35.1 Attributes

Name	Description
kind	Closed serialization identity for the multiscale encoder.
input_channels	Deterministic evidence channels, excluding the explicit support mask.
width	Fine-scale learned feature width; the coarse scale uses twice this width.
max_group_norm_groups	Largest permitted GroupNorm group count, reduced to a channel divisor.
projection_only	Use only the input projection for the matched spatial-capacity ablation.
target_type	Return the configured dense encoder type.

1.3 Functions

Name	Description
largest_divisor_leq	Return the largest divisor of n that is less than or equal to a cap.

1.3.1 largest_divisor_leq

vin.modules.largest_divisor_leq(n, max_divisor)

Return the largest divisor of n that is less than or equal to a cap.

torch.nn.GroupNorm requires num_groups to divide num_channels exactly. VIN configs often expose an upper-bound group count for tuning, so this helper maps that requested cap to the nearest valid divisor.

1.3.1.1 Parameters

Name	Type	Description	Default
n	int	Channel dimension that must be divided by the result.	required
max_divisor	int	Maximum permitted group count.	required

1.3.1.2 Returns

Name	Type	Description
	int	Largest valid group count, always at least 1.