1 rollouts.replay.engine

rollouts.replay.engine

Bounded counterfactual pose rollout utilities.

This module owns regeneration of finite candidate tables at each step from the updated pose, history, and remaining budget. The candidate generator may be single-family or mixed, but the selected action must satisfy the actor-valid mask. Oracle scores are supervision/evaluation fields; actor-visible replay rows retain poses, masks, candidate provenance, and selected-action lineage.

The first thesis-core use is deterministic oracle lookahead and replay data for finite-candidate value learning. Online simulator training and continuous action control are outside this module’s current contract.

1.1 Theory

Rollout policies operate over valid finite candidate rows. Heuristic policies score distance from history or the current reference; random policies sample uniformly over eligible valid rows; oracle policies consume evaluator scores such as target root gain. Robust temperature-softmax selection uses finite-score logits

\[ \ell_i = \frac{s_i-\operatorname{median}(s)} {\tau\max(D(s), f, \epsilon_{\mathrm{dtype}})}, \]

where \(D(s)\) is the IQR for at least four finite scores and the standard deviation otherwise. The optional floor \(f\) is zero by default and may be positive only for root-normalized target gain scores. A masked softmax then operates over eligible valid candidates. Diversity guards may require sibling distance, yaw separation, target-bearing separation, and strategy diversity before branches are admitted into the rollout tree. Branch schedules control how many sibling transitions are retained per rollout depth.

1.2 Classes

Name Description
CounterfactualPoseGenerator Expand a multi-step counterfactual pose tree from the current generator.
CounterfactualPoseGeneratorConfig Configuration for multi-step finite-candidate rollout generation.
RootCandidateAdmissionError Raised before scoring when a root-shell admission policy rejects replay.
RootCandidateAdmissionRejection Structured reason for rejecting a materialized root candidate shell.

1.2.1 CounterfactualPoseGenerator

rollouts.replay.engine.CounterfactualPoseGenerator(config)

Expand a multi-step counterfactual pose tree from the current generator.

The generator returns in-memory trajectories only. Callers such as RolloutDatasetWriter provide source samples and oracle evaluators, then decide which rollout records and diagnostics are retained in standalone replay stores.

1.2.1.1 Methods

Name Description
resolve_root Resolve the physical, rollout, and camera roots without rendering.
resolve_typed_sample_root Resolve the exact no-render root used by typed-sample replay.
generate_from_typed_sample Generate rollout trajectories directly from one typed snippet.
generate Generate multi-step counterfactual rollouts from one root pose.
1.2.1.1.1 resolve_root
rollouts.replay.engine.CounterfactualPoseGenerator.resolve_root(
    reference_pose,
    camera_calib_template,
    root_time_ns=None,
    root_trajectory_index=None,
    root_frame_index=None,
)

Resolve the physical, rollout, and camera roots without rendering.

1.2.1.1.2 resolve_typed_sample_root
rollouts.replay.engine.CounterfactualPoseGenerator.resolve_typed_sample_root(
    sample,
    *,
    reference_pose=None,
    device=None,
)

Resolve the exact no-render root used by typed-sample replay.

1.2.1.1.3 generate_from_typed_sample
rollouts.replay.engine.CounterfactualPoseGenerator.generate_from_typed_sample(
    sample,
    *,
    reference_pose=None,
    score_candidates=None,
    admit_root_candidates=None,
    candidate_runtime_context=None,
)

Generate rollout trajectories directly from one typed snippet.

When provided, admit_root_candidates observes the materialized seeded root shell exactly once. A returned rejection raises RootCandidateAdmissionError before zero-valid handling or candidate evaluation. Omitting the callback preserves ordinary replay.

1.2.1.1.4 generate
rollouts.replay.engine.CounterfactualPoseGenerator.generate(
    reference_pose,
    gt_mesh,
    mesh_verts,
    mesh_faces,
    camera_calib_template,
    occupancy_extent,
    score_candidates=None,
    admit_root_candidates=None,
    candidate_runtime_context=None,
    root_time_ns=None,
    root_trajectory_index=None,
    root_frame_index=None,
)

Generate multi-step counterfactual rollouts from one root pose.

Root admission runs after candidate metadata is attached to the first shell and before any evaluator call. Accepted shells continue through the unchanged zero-valid, scoring, selection, and branching sequence.

1.2.2 CounterfactualPoseGeneratorConfig

rollouts.replay.engine.CounterfactualPoseGeneratorConfig()

Configuration for multi-step finite-candidate rollout generation.

Candidate sampling stays in pose_generation: each rollout step regenerates a shell from the current pose/history, applies hard validity masks, and selects valid actions by the configured policy. Persistence, source-row lineage, and Q_H replay views are owned by aria_nbv.rollouts.

1.2.2.1 Attributes

Name Description
target_type Return the finite-candidate replay generator constructed by this config.
policy Complete immutable branching and action-selection policy.

1.2.3 RootCandidateAdmissionError

rollouts.replay.engine.RootCandidateAdmissionError(rejection)

Raised before scoring when a root-shell admission policy rejects replay.

1.2.4 RootCandidateAdmissionRejection

rollouts.replay.engine.RootCandidateAdmissionRejection(
    reason,
    valid_candidate_count,
)

Structured reason for rejecting a materialized root candidate shell.

Root admission observes the same seeded shell that replay would score and select. The count is retained with the reason so execution callers can report support failures without reconstructing or rescoring the shell.

1.2.4.1 Attributes

Name Description
reason Stable machine-readable rejection reason.
valid_candidate_count Number of actor-valid rows in the rejected root shell.

1.3 Functions

Name Description
deterministic_selection_records Recompute deterministic replay choices from an admitted candidate table.

1.3.1 deterministic_selection_records

rollouts.replay.engine.deterministic_selection_records(
    scores,
    valid_poses,
    history_centers_world,
    policy,
    branch_count=1,
    strategy_id=None,
    target_bearing_yaw_rad=None,
    selection_seed=None,
    rank_order=None,
)

Recompute deterministic replay choices from an admitted candidate table.

1.3.1.1 Parameters

Name Type Description Default
scores torch.Tensor Floating Tensor["N"] containing the actual evaluator’s objective, even when the policy name denotes a distance heuristic. Directed policies supply their already prepared orbit objective. Nonfinite entries are ineligible and become negative-infinity logits. required
valid_poses PoseTW PoseTW["N 12"] for the actual candidate camera poses, in the same valid-row order as the scores. required
history_centers_world torch.Tensor Tensor["M 3"] in world metres, containing the replay root and previously selected pose centres in causal order, matching CounterfactualTrajectory.history_centers_world. The replay root can differ from the calibrated physical camera root. required
policy RolloutPolicySpec Deterministic replay policy and its existing diversity guards. required
branch_count int Positive maximum number of sibling decisions to retain. 1
strategy_id torch.Tensor | None Optional Tensor["N", int64] strategy identities. None
target_bearing_yaw_rad torch.Tensor | None Optional Tensor["N"] target bearings in radians. None
selection_seed int | None Recorded seed provenance; deterministic ranking uses no RNG. None
rank_order torch.Tensor | None Optional Tensor["N", int64] ranking permutation recorded on the original backend. Must order the finite objective descending; equal-score ordering is preserved as observed provenance. None

1.3.1.2 Returns

Name Type Description
list[CounterfactualSelectionRecord] One-hot decisions with logits equal to the finite ranked objective.
list[CounterfactualSelectionRecord] Empty output means no finite score. If all finite rows fail diversity
list[CounterfactualSelectionRecord] guards, the existing fallback selects the first finite row in table
list[CounterfactualSelectionRecord] order, rather than the maximum. Partial branching is retained.

1.3.1.3 Theory

Rows follow torch.argsort(scores, descending=True) without a new tie rule. A row passes only if every enabled causal-history and selected- sibling guard passes. Sibling guards have no earlier siblings on the first choice. This is the generation and portable-evidence decision owner; callers supply observed geometry rather than recorded decisions. Without rank_order, exact ties retain the installed backend’s sorting behavior, not a cross-device or cross-version guarantee. A validated recorded order allows portable replay of those same ties.

Back to top