1 vin.models

vin.models

Top-level VIN model namespace for runnable scorer implementations.

aria_nbv.vin.models.scene_myopic owns the preserved seminar-era VinModelV3. aria_nbv.vin.models.target_finite_horizon owns the production actor-only Q_H scorer over persisted chain views.

1.1 Classes

Name	Description
QhScoreOutput	Candidate-aligned finite-horizon predictions before policy masking.
TargetFiniteHorizonScorer	Predict candidate feasibility and conditional finite-horizon value.
TargetFiniteHorizonScorerConfig	Configure the actor-only finite-horizon value scorer.
TargetVolumetricScorer	Reuse spatial scoring while replacing only candidate evidence readout.
TargetVolumetricScorerConfig	Select the causal learned-volume readout at the existing scoring seam.
VinModelV3	VIN-Core head for one-step RRI prediction.
VinModelV3Config	Configuration for VinModelV3 (streamlined one-step VIN baseline).

1.1.1 QhScoreOutput

vin.models.QhScoreOutput(
    conditional_q,
    feasibility_logits,
    value_auxiliary=None,
)

Candidate-aligned finite-horizon predictions before policy masking.

The scorer owns construction and float32 conversion. This passive container does not validate, copy, or detach tensors: autograd and storage ownership remain with their producers. B is batch, S is query state, N is candidate; a queried horizon conditions Q separately from the factual remaining budget.

1.1.1.1 Attributes

Name	Type	Description
conditional_q	Tensor	Tensor["B S N", float32] values conditional on an action being feasible. Materialized invalid rows are deliberately finite but are neither Q-supervised nor deployable.
feasibility_logits	Tensor	Tensor["B S N", float32] binary-validity logits. Positive values denote greater predicted feasibility.
value_auxiliary	QhCoralAuxiliary | None	Optional decoder-specific training payload. CORAL supplies cumulative threshold logits and fixed Q-bin edges; regression supplies None. Bellman backup and online ranking always consume conditional_q, never this auxiliary payload.

1.1.2 TargetFiniteHorizonScorer

vin.models.TargetFiniteHorizonScorer(config)

Predict candidate feasibility and conditional finite-horizon value.

The module exposes one deep interface: a batched QhActorTensors enters and one candidate-aligned QhScoreOutput leaves. Every materialized row is encoded independently of action_mask. Candidate rows never attend to one another, so jointly permuting candidate poses and masks permutes both outputs identically and invalid rows cannot influence valid rows.

1.1.2.1 Theory

The public family is

\[ Q_h(s_t,e,q_{t,i}\mid b_t),\qquad 1\le h\le b_t\le H_{\max}. \]

b_t is the factual number of acquisitions still available in the stored state; h is the number of rewards represented by this query. They are separately normalized by H_max and encoded by separate MLPs, so an off-diagonal query changes the value estimand without falsifying the actor state. None means the factual diagonal h=b_t. Realized rows reject h=0 or h>b_t; padded states use h=0 only. Q_0=0 is a mathematical backup boundary and has no learned output.

The physical trunk reads candidate root/current-relative pose and a compact root-scene summary. Its feasibility head therefore cannot read the target, requested horizon, remaining budget, labels, or action_mask. Conditional Q additionally reads candidate-to-target geometry and five shared state tokens: root scene, target, causal pose history, budget, and requested horizon. Candidate rows are independent queries over those shared tokens; no attention axis crosses candidates.

Geometry uses explicit transform direction. candidate_pose_relative_root is root-from-candidate :math:T_{r\leftarrow c_i}. The physical trunk also forms current-from-candidate :math:T_{c_t\leftarrow c_i}. Conditional Q receives candidate-from-target :math:T_{c_i\leftarrow e}, so the same target induces a different relation for every candidate without making feasibility target-dependent.

The target token encodes the root-relative target pose plus metric extents. Target source is an experiment-profile fact rather than something inferred from tensor shape. Scene context is the deliberately lossy root_moments_v1 carrier. Causal history first expresses the exact selected-pose prefix from the current camera. H0 takes its masked mean; the optional H1 carrier adds relative age and causal temporal attention before returning the same one-token interface. H1 remains an S0-pose trajectory ablation: it does not invent selected observations or make compact root moments a sufficient dynamic reconstruction state.

The CF+ H0 role is the source-protocol-matched counterfactual for S1. It requires the same strictly causal CF-GT carrier and data population, but the prediction graph consumes none of its numeric payload. Consequently any change confined to selected depth, depth-valid support, calibration, or selected-camera poses must leave both raw heads exactly unchanged. S1 instead uses canonical float32 backprojection and a fixed-width, density-weighted point-set residual. Its scene feature remains shared across candidate rows and target independent; candidate-relative point queries are deliberately deferred. Its final bias-free residual projection starts at zero, and dynamic scene rows traverse the same per-state linear path as static H0. Thus matched zero-residual S1 and H0 predictions are bitwise equal at initialization rather than merely close despite shape-dependent GEMM rounding. Neither CF+ role is deployable, and comparing CF0 with CF+ H0 does not identify an S1 representation gain.

1.1.2.2 Notes

Syntactic admission does not assert empirical support. Lightning owns which horizons receive targets, while a verified inference bundle owns the manifest-bound set of horizons that may be deployed.

1.1.2.3 Methods

Name	Description
validate_artifact_state	Validate non-learned architecture state against scorer configuration.
forward	Return mask-independent candidate predictions in stored order.

1.1.2.3.1 validate_artifact_state

vin.models.TargetFiniteHorizonScorer.validate_artifact_state(
    require_publishable=False,
)

Validate non-learned architecture state against scorer configuration.

Learned weights may vary while the scorer configuration stays fixed, but CORAL edges and representatives are experiment identity: they determine supervision labels and convert ordinal mass back into the continuous units used by Bellman backup and policy ranking. This hook gives bundle owners one decoder-agnostic validation seam and leaves direct regression as the no-extra-state baseline.

1.1.2.3.2 forward

vin.models.TargetFiniteHorizonScorer.forward(actor, *, requested_horizon=None)

Return mask-independent candidate predictions in stored order.

1.1.2.3.2.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched actor-visible chain with candidate support Tensor["B S N", bool], compact root EVL evidence, and—only for the named privileged S1 profile—the complete causal selected-depth prefix.	required
requested_horizon	Tensor | None	Optional Tensor["B S", int64] value query. Legacy None selects recorded remaining budget and admits 1 <= h <= b_t <= H_max. Continuing requires explicit 1 <= h <= H_max independent of recorded countdown and omits the budget feature. Padding is zero in both profiles.	None

1.1.2.3.2.2 Returns

Name	Type	Description
	QhScoreOutput	Candidate-aligned conditional Q and feasibility logits. Both are
	QhScoreOutput	finite on materialized realized rows and zero only on padding.
	QhScoreOutput	CORAL additionally returns threshold logits and its fixed support
	QhScoreOutput	in value_auxiliary for Lightning supervision and diagnostics;
	QhScoreOutput	policy backup and ranking still use only conditional_q.

1.1.3 TargetFiniteHorizonScorerConfig

vin.models.TargetFiniteHorizonScorerConfig()

Configure the actor-only finite-horizon value scorer.

1.1.3.1 Attributes

Name	Description
hidden_dim	Shared candidate and state token width.
pose_encoder	R6D plus LFF encoder used for target, candidate, and history poses.
scene_channels	Ordered compact root-EVL fields pooled into the state token.
representation_semantics	Versioned scene-token meaning bound into scorer and artifact identity.
scene_encoder	Optional explicit scene carrier; None preserves legacy S0 identity.
history_encoder	H0/H1 representation of the strictly causal selected-pose prefix.
state_fusion	A0/A1 interaction over the identical candidate query and state tokens.
dropout	Training-only dropout in state fusion and the value decoder.
value_decoder	Terminal scalar-Q decoder over the shared candidate-state feature.
max_horizon	Largest admitted acquisition horizon; remaining budget is normalized by this value.
horizon_query_semantics	Legacy budget-bounded query or explicit continuing lookahead independent of replay length.
experiment_profile	Named source role admitted by the scorer.
target_type	Return the concrete scorer constructed by :meth:setup_target.

1.1.4 TargetVolumetricScorer

vin.models.TargetVolumetricScorer(config)

Reuse spatial scoring while replacing only candidate evidence readout.

The inherited scorer owns actor preparation, physical feasibility, pose and history encoding, state fusion, value decoding, padding, and QhScoreOutput. This specialization changes the configured value readout to a causal evidence volume and adds no second scoring implementation.

1.1.5 TargetVolumetricScorerConfig

vin.models.TargetVolumetricScorerConfig()

Select the causal learned-volume readout at the existing scoring seam.

1.1.5.1 Attributes

Name	Description
propagation_exclude_fields	Model/readout evidence identities are compared rather than propagated.
model_kind	Closed model discriminator for the volumetric scorer.
evidence_mode	Root-only CF0 evidence or privileged causal selected-depth evidence.
representation_semantics	Serialized representation identity bound to source and evidence mode.
readout	Required concrete volume readout; static readouts are intentionally excluded.
target_type	Return the volumetric specialization.

1.1.6 VinModelV3

vin.models.VinModelV3(config)

VIN-Core head for one-step RRI prediction.

VIN v3 focuses on pose encoding, compact voxel evidence, and semidense projection stats, while enforcing fail-fast contracts to avoid silent collapse. It ranks candidates for immediate RRI; bounded rollout values such as \(Q_H\) are separate thesis models trained on rollout replay.

Candidate-set symmetry is structural: learned blocks use row-wise maps, candidate queries over shared scene/trajectory tokens, and symmetric GroupNorm statistics across rows. There are no candidate-index embeddings or order-sensitive candidate operations. In deterministic evaluation, jointly permuting candidate poses and aligned camera rows therefore permutes every N_q output the same way; stochastic training dropout preserves only distributional equivariance. This is not graph-isomorphism invariance because the model constructs no candidate graph. Its reference-frame pose and positional encodings are coordinate-conditioned inductive biases and do not enforce SE(3) equivariance.

1.1.6.1 Attributes

Name	Description
pose_encoder_lff	Return the LFF sub-encoder when present (else None).

1.1.6.2 Methods

Name	Description
train	Set training mode and discard inference-only prepared scene state.
forward	Score an aligned candidate set with cached actor-visible evidence.
forward_with_debug	Run VIN v3 forward pass and return intermediate tensors.
init_bin_values	Initialize learnable bin representatives for CORAL expectation.
summarize_vin	Summarize VIN v3 inputs/outputs for a single oracle-labeled batch.

1.1.6.2.1 train

vin.models.VinModelV3.train(mode=True)

Set training mode and discard inference-only prepared scene state.

1.1.6.2.2 forward

vin.models.VinModelV3.forward(
    efm,
    candidate_poses_world_cam,
    reference_pose_world_rig,
    p3d_cameras,
    backbone_out=None,
)

Score an aligned candidate set with cached actor-visible evidence.

1.1.6.2.2.1 Parameters

Name	Type	Description	Default
efm	EfmSnippetView | VinSnippetView	EFM snippet view or VIN snippet view for the current snippet.	required
candidate_poses_world_cam	PoseTW	PoseTW["B N_q 12"] world-from-camera poses.	required
reference_pose_world_rig	PoseTW	PoseTW["B 12"] world-from-rig pose.	required
p3d_cameras	PerspectiveCameras	PyTorch3D cameras aligned with the flattened B * N_q candidate rows.	required
backbone_out	EvlBackboneOutput | None	Required cached actor-visible EVL evidence. None is accepted by the signature only to produce a fail-fast error.	None

1.1.6.2.2.2 Returns

Name	Type	Description
	VinPrediction	VinPrediction with Tensor["B N_q K-1", float32] CORAL logits,
	VinPrediction	Tensor["B N_q K", float32] probabilities, and aligned expected
	VinPrediction	scores and diagnostic validity fields.

1.1.6.2.3 forward_with_debug

vin.models.VinModelV3.forward_with_debug(
    efm,
    candidate_poses_world_cam,
    reference_pose_world_rig,
    p3d_cameras,
    backbone_out=None,
)

Run VIN v3 forward pass and return intermediate tensors.

1.1.6.2.3.1 Parameters

Name	Type	Description	Default
efm	EfmSnippetView | VinSnippetView	EFM snippet view or VIN snippet view for the current snippet.	required
candidate_poses_world_cam	PoseTW	PoseTW["B N_q 12"] world-from-camera poses.	required
reference_pose_world_rig	PoseTW	PoseTW["B 12"] world-from-rig pose.	required
p3d_cameras	PerspectiveCameras	PyTorch3D cameras aligned with B * N_q rows.	required
backbone_out	EvlBackboneOutput | None	Required cached actor-visible EVL evidence.	None

1.1.6.2.3.2 Returns

Name	Type	Description
	tuple[VinPrediction, VinV3ForwardDiagnostics]	Prediction and B/N_q-aligned intermediate tensors.

1.1.6.2.4 init_bin_values

vin.models.VinModelV3.init_bin_values(values, *, overwrite=False)

Initialize learnable bin representatives for CORAL expectation.

1.1.6.2.4.1 Parameters

Name	Type	Description	Default
values	Tensor	Tensor["K"] target bin representatives (e.g., bin means).	required
overwrite	bool	If True, overwrite existing bin values.	False

1.1.6.2.5 summarize_vin

vin.models.VinModelV3.summarize_vin(
    batch,
    *,
    include_torchsummary=True,
    torchsummary_depth=3,
)

Summarize VIN v3 inputs/outputs for a single oracle-labeled batch.

This is intended for quick sanity checks when validating the streamlined baseline against sweep-derived expectations.

1.1.6.2.5.1 Parameters

Name	Type	Description	Default
batch	VinOracleBatch	Oracle-labeled batch to inspect.	required
include_torchsummary	bool	Whether to include a torchsummary block.	True
torchsummary_depth	int	Depth for torchsummary.	3

1.1.6.2.5.2 Returns

Name	Type	Description
	str	Human-readable summary string.

1.1.7 VinModelV3Config

vin.models.VinModelV3Config()

Configuration for VinModelV3 (streamlined one-step VIN baseline).

1.1.7.1 Attributes

Name	Description
target_type	Factory target for BaseConfig.setup_target (config-as-factory).
backbone	Optional EVL config kept for caller-side materialization of voxel features.
pose_encoder	Pose encoder configuration (R6D + LFF; stable relative pose encoding).
pos_grid_encoder_lff	LFF encoder for XYZ voxel position keys used by global pooling.
head_hidden_dim	Hidden dimension for the scorer MLP (optuna favored compact heads).
head_num_layers	Number of MLP layers before the CORAL layer (best trials used 1).
head_dropout	Dropout probability in the MLP (sweep best used near-zero dropout).
num_classes	Number of ordinal bins (VIN-NBV uses 15 for sweep comparability).
coral_preinit_bias	Pre-initialize CORAL biases for faster, more stable ordinal learning.
field_dim	Channel dimension of the projected voxel field (compact by design).
field_gn_groups	Requested GroupNorm groups (clamped to a divisor of field_dim) for stability.
semidense_proj_grid_size	Grid size for semidense projection stats (higher for tiny-CNN cues).
semidense_proj_max_points	Maximum semidense points used for projection stats (sweep best used 4096).
semidense_cnn_enabled	Whether to encode a tiny 2D CNN over the semidense projection grid.
semidense_cnn_channels	Hidden channel width for the semidense projection CNN.
semidense_cnn_out_dim	Output feature dimension of the semidense projection CNN.
use_traj_encoder	Whether to encode snippet trajectories and append trajectory context.
traj_encoder	Optional trajectory encoder for snippet rig poses (R6D + LFF).
use_voxel_valid_frac_gate	Deprecated: voxel gate removed. Keep False (use FiLM only).
semidense_obs_count_min	Global minimum of semidense observation count n_obs (cache summary).
semidense_obs_count_max	Global maximum of semidense observation count n_obs (cache summary).
semidense_obs_count_p95	Global 95th percentile of semidense observation count n_obs (cache summary).
semidense_obs_count_mean	Global mean of semidense observation count n_obs (cache summary).
semidense_obs_count_std	Global standard deviation of semidense observation count n_obs (cache summary).
semidense_inv_dist_std_min	Global minimum of semidense inverse depth std 1/sigma_d (cache summary).
semidense_inv_dist_std_max	Global maximum of semidense inverse depth std 1/sigma_d (cache summary).
semidense_inv_dist_std_p95	Global 95th percentile of semidense inverse depth std 1/sigma_d (cache summary).
semidense_inv_dist_std_mean	Global mean of semidense inverse depth std 1/sigma_d (cache summary).
semidense_inv_dist_std_std	Global standard deviation of semidense inverse depth std 1/sigma_d (cache summary).
apply_cw90_correction	Undo rotate_yaw_cw90 on poses (requires CW90-corrected cameras).
global_pool_grid_size	Target grid size for pose-conditioned global pooling (best trials used ~5).
scene_field_channels	Ordered list of scene-field channels to include in the voxel field.