1 vin.types.prediction

vin.types.prediction

Prediction containers emitted by VIN candidate scorers.

VinPrediction is the one-step training-visible output contract consumed by Lightning, metrics, diagnostics, and downstream candidate ranking code. QhScoreOutput is the separate finite-horizon contract consumed by fitted-Q optimization and inference.

1.1 Classes

Name Description
QhCoralAuxiliary Training-only CORAL tensors attached to a scalar value prediction.
QhScoreOutput Candidate-aligned finite-horizon predictions before policy masking.
VinPrediction VIN predictions for a candidate set.

1.1.1 QhCoralAuxiliary

vin.types.prediction.QhCoralAuxiliary(logits, bin_edges, bin_values)

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

1.1.1.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.1.2 QhScoreOutput

vin.types.prediction.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.2.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.3 VinPrediction

vin.types.prediction.VinPrediction(
    logits,
    prob,
    expected,
    expected_normalized,
    candidate_valid,
    voxel_valid_frac=None,
    semidense_candidate_vis_frac=None,
)

VIN predictions for a candidate set.

This is the primary output of aria_nbv.vin.models.scene_myopic.VinModelV3. It is consumed by the Lightning training loop (loss + metrics) and by downstream NBV selection (ranking candidates by predicted improvement). The expected score is a learned one-step ranking proxy; rollout-level endpoint metrics and cumulative target RRI are produced by rollout stores and oracle re-scoring, not by this container.

The candidate axis is row-aligned with the input poses and PyTorch3D camera batch. VinModelV3 uses row-wise maps, shared-token queries, and symmetric normalization without candidate-index embeddings. A joint permutation of aligned inputs therefore produces the same permutation of every N_q output in deterministic evaluation; training-time dropout preserves this symmetry only in distribution.

Typical usage in training (see aria_nbv/lightning/one_step/module.py): - logits / prob: CORAL ordinal loss and optional auxiliary losses. - expected_normalized: correlation/top-k metrics and candidate ranking proxy. - voxel_valid_frac / semidense_candidate_vis_frac: optional scheduled coverage reweighting of the loss + diagnostics. - candidate_valid: conservative validity heuristic used for logging and optional filtering in analysis/visualization.

1.1.3.1 Attributes

Name Description
logits Tensor["B N_q K-1", float32] CORAL threshold logits.
prob Tensor["B N_q K", float32] class probabilities from the logits.
expected Tensor["B N_q", float32] expected class value in [0, K-1].
expected_normalized Tensor["B N_q", float32] expected value normalized to [0, 1].
candidate_valid Tensor["B N_q", bool] candidate validity diagnostic.
voxel_valid_frac Tensor["B N_q", float32] candidate voxel-coverage proxy, if available.
semidense_candidate_vis_frac Tensor["B N_q", float32] candidate semidense-visibility proxy, if available.
semidense_valid_frac Read-only compatibility alias for semidense_candidate_vis_frac.
Back to top