1 vin.candidate_scorer

vin.candidate_scorer

Structural scorer contract for VIN-compatible candidate models.

This module provides the narrow one-step interface that aria_nbv.lightning.one_step.module needs from a candidate scorer, its prediction protocol, and configuration-to-objective classification. The current implementation is aria_nbv.vin.models.scene_myopic.VinModelV3, the seminar-era one-step RRI scorer. Future target-conditioned myopic scorers should implement the same forward surface when they are trainable through the existing Lightning loss path.

The contract deliberately keeps rollout value targets out of aria_nbv.vin.types.VinPrediction. Multi-step scoring uses the separate aria_nbv.vin.models.target_finite_horizon.TargetFiniteHorizonScorer contract, whose structured output is optimized by aria_nbv.lightning.finite_horizon.module. Endpoint gain, selected-transition returns, and authoritative hard masks remain owned outside this one-step protocol.

1.1 Attributes

Name Description
CandidateScorerConfig Config-as-factory type for candidate scorer architecture slots.
CandidateScorerTrainingContract Training-objective contract selected by a candidate scorer config.

1.2 Classes

Name Description
CandidateScorer Protocol for trainable candidate scorers consumed by VIN Lightning.
CandidateScorerPrediction Minimal prediction attributes used by the current Lightning loss path.

1.2.1 CandidateScorer

vin.candidate_scorer.CandidateScorer()

Protocol for trainable candidate scorers consumed by VIN Lightning.

Implementations score each candidate pose row from actor-visible scene evidence and return a aria_nbv.vin.types.VinPrediction. The current Lightning objective also expects a CORAL head at head_coral so it can compute expected RRI proxies and initialize ordinal bin values.

1.2.1.1 Implementers

aria_nbv.vin.models.scene_myopic.VinModelV3 is the current one-step scorer. Future target-conditioned myopic scorers can satisfy this protocol when they still emit per-candidate ordinal logits. Finite-horizon QH scorers use their dedicated actor input, structured output, and Lightning objective instead of this protocol.

1.2.1.2 Attributes

Name Description
head_coral CORAL head used for ordinal probability and expected-value helpers.

1.2.1.3 Methods

Name Description
init_bin_values Initialize scorer-owned CORAL bin representatives.
forward Score candidate poses for one actor-visible snippet.
parameters Return trainable parameters, matching torch.nn.Module.parameters.
summarize_vin Return a debug summary for scorer inputs and modules.
1.2.1.3.1 init_bin_values
vin.candidate_scorer.CandidateScorer.init_bin_values(values, *, overwrite=False)

Initialize scorer-owned CORAL bin representatives.

1.2.1.3.2 forward
vin.candidate_scorer.CandidateScorer.forward(
    efm,
    *,
    candidate_poses_world_cam,
    reference_pose_world_rig,
    p3d_cameras,
    backbone_out=None,
)

Score candidate poses for one actor-visible snippet.

1.2.1.3.2.1 Parameters
Name Type Description Default
efm EfmSnippetView | VinSnippetView Actor-visible EFM/VIN snippet view containing semidense scene evidence. required
candidate_poses_world_cam PoseTW PoseTW["B N_q 12"] world←camera candidate poses. required
reference_pose_world_rig PoseTW PoseTW["B 12"] world←rig reference pose used to express candidates in the local frame. required
p3d_cameras PerspectiveCameras PyTorch3D camera batch aligned with candidate poses. required
backbone_out EvlBackboneOutput | None Optional cached EVL output; when omitted the scorer may compute it from efm if it owns a backbone. None
1.2.1.3.2.2 Returns
Name Type Description
VinPrediction Per-candidate logits, probabilities, expected scores, and optional
VinPrediction validity/coverage diagnostics.
1.2.1.3.3 parameters
vin.candidate_scorer.CandidateScorer.parameters(recurse=True)

Return trainable parameters, matching torch.nn.Module.parameters.

1.2.1.3.4 summarize_vin
vin.candidate_scorer.CandidateScorer.summarize_vin(
    batch,
    *,
    include_torchsummary=True,
    torchsummary_depth=3,
)

Return a debug summary for scorer inputs and modules.

1.2.2 CandidateScorerPrediction

vin.candidate_scorer.CandidateScorerPrediction()

Minimal prediction attributes used by the current Lightning loss path.

This protocol documents the structural subset of aria_nbv.vin.types.VinPrediction consumed by VinLightningModule. Optional coverage fields are read with getattr in the trainer, so they do not need to be present on future prediction dataclasses unless coverage weighting or diagnostics should use them.

1.2.2.1 Attributes

Name Description
logits Tensor["B N_q K-1", float32] CORAL threshold logits.
prob Tensor["B N_q K", float32] ordinal class probabilities.
expected_normalized Tensor["B N_q", float32] expected normalized ranking score.
candidate_valid Optional Tensor["B N_q", bool] scorer diagnostic validity mask.

1.3 Functions

Name Description
candidate_scorer_training_contract Classify a candidate scorer config by its Lightning objective contract.

1.3.1 candidate_scorer_training_contract

vin.candidate_scorer.candidate_scorer_training_contract(config)

Classify a candidate scorer config by its Lightning objective contract.

1.3.1.1 Parameters

Name Type Description Default
config CandidateScorerConfig Candidate scorer config accepted by experiment and Lightning configuration parsing. required

1.3.1.2 Returns

Name Type Description
CandidateScorerTrainingContract Contract string used by training entry points to reject incompatible
CandidateScorerTrainingContract objective families before constructing placeholder modules.
Back to top