1 rollouts.replay.state

rollouts.replay.state

In-memory replay transitions and trajectories.

This module contains DTOs for selected finite-candidate transitions. Persisted Zarr rows remain separate contracts in aria_nbv.rollouts.storage.

1.1 Classes

Name	Description
CounterfactualRolloutResult	Retained replay leaves and tree controls for one physical root pose.
CounterfactualSelectionRecord	Selected compact-valid row and the distribution used to draw it.
CounterfactualStepResult	One selected transition and its finite-candidate decision context.
CounterfactualTrajectory	One retained root-to-leaf path through the replay tree.

1.1.1 CounterfactualRolloutResult

rollouts.replay.state.CounterfactualRolloutResult(
    root_pose_world,
    root_camera_pose_world,
    trajectories,
    horizon,
    branch_factor,
    beam_width,
    selection_policy,
    score_label='score',
    root_time_ns=None,
    root_trajectory_index=None,
    root_frame_index=None,
)

Retained replay leaves and tree controls for one physical root pose.

H is maximum depth, B is base sibling expansion count, and L = len(trajectories) is the retained branch/beam axis after pruning. Each step retains its own variable-width candidate shell.

1.1.1.1 Attributes

Name	Description
root_pose_world	World-from-corrected-reference pose shared by all trajectories; fixes the root frame after the local-Z rig-basis twist.
root_camera_pose_world	Physical world-from-camera anchor at depth zero.
trajectories	Retained root-to-leaf paths on the branch/beam axis L.
horizon	Maximum number of selected transitions H per path.
branch_factor	Base sibling expansion count B before beam pruning.
beam_width	Maximum retained partial paths per depth, or None for no cap.
selection_policy	Action-selection policy shared by the replay call.
score_label	Stable semantic name for per-action selection scores.
root_time_ns	Source capture timestamp in nanoseconds, when available.
root_trajectory_index	Source trajectory index used to reconstruct root evidence.
root_frame_index	Source frame index associated with the root pose.

1.1.2 CounterfactualSelectionRecord

rollouts.replay.state.CounterfactualSelectionRecord(
    valid_index,
    logits,
    probabilities,
    log_probabilities,
    entropy,
    selected_log_probability,
    selection_rng_seed=None,
)

Selected compact-valid row and the distribution used to draw it.

V is the number of hard-valid actions in the step-local candidate shell. Every tensor in this record is aligned to V rather than the full shell axis N.

1.1.2.1 Attributes

Name	Description
valid_index	Selected zero-based row on the compact valid-candidate axis V.
logits	Selection logits as Tensor["V", float32] before softmax.
probabilities	Normalized action probabilities as Tensor["V", float32].
log_probabilities	Natural-log action probabilities as Tensor["V", float32].
entropy	Categorical entropy of probabilities, in nats.
selected_log_probability	Log probability assigned to valid_index, in nats.
selection_rng_seed	Deterministic seed used for this selection draw.

1.1.3 CounterfactualStepResult

rollouts.replay.state.CounterfactualStepResult(
    step_index,
    candidates,
    selected_valid_index,
    selected_shell_index,
    selection_score,
    selection_score_label='score',
    selection_scores=None,
    selection_policy='unknown',
    selection_temperature=None,
    selection_logits=None,
    selection_probabilities=None,
    selection_log_probabilities=None,
    selection_entropy=None,
    selected_log_probability=None,
    selection_rng_seed=None,
    candidate_rng_seed=None,
    orbit_direction=None,
    orbit_progress_before_rad=None,
    orbit_increment_rad=None,
    orbit_remaining_before_rad=None,
)

One selected transition and its finite-candidate decision context.

N is the generated shell width and V its compact hard-valid subset. Candidate generation owns N and its validity mask; selection vectors use V and map back through selected_shell_index.

1.1.3.1 Attributes

Name	Description
step_index	Zero-based rollout depth on the horizon axis H.
candidates	Full N-row shell, validity masks, valid views, and provenance.
selected_valid_index	Selected zero-based row on the compact valid axis V.
selected_shell_index	Corresponding zero-based row on the full shell axis N.
selection_score	Policy score of the selected action; never a validity sentinel.
selection_score_label	Stable semantic name for the selection-score channel.
selection_scores	Optional scores as Tensor["V", float32] in compact-valid order.
selection_policy	Policy identifier used to choose the action.
selection_temperature	Softmax temperature when sampling from a score distribution.
selection_logits	Optional selection logits as Tensor["V", float32].
selection_probabilities	Optional action probabilities as Tensor["V", float32].
selection_log_probabilities	Optional log action probabilities as Tensor["V", float32].
selection_entropy	Categorical selection entropy in nats.
selected_log_probability	Log probability of the selected compact-valid row, in nats.
selection_rng_seed	Deterministic per-node seed used for stochastic selection.
candidate_rng_seed	Deterministic per-node seed used for candidate generation.
orbit_direction	Persistent directed-orbit traversal direction, when enabled.
orbit_progress_before_rad	Committed signed angular progress before this transition, in radians.
orbit_increment_rad	Direction-aligned wrapped increment committed by this transition, in radians.
orbit_remaining_before_rad	Positive directed angle remaining before this transition, in radians.
selected_pose_world	Return the selected valid pose in world coordinates.
selected_view	Return the selected candidate camera from the compact valid table.

1.1.4 CounterfactualTrajectory

rollouts.replay.state.CounterfactualTrajectory(
    root_pose_world,
    root_time_ns=None,
    root_trajectory_index=None,
    root_frame_index=None,
    steps=list(),
    cumulative_score=0.0,
    terminated_early=False,
    termination_reason=None,
)

One retained root-to-leaf path through the replay tree.

A trajectory has at most H transitions and T = len(steps) + 1 poses: the root reference rig followed by selected camera endpoints. Update helpers return new records so sibling branches do not share step lists.

1.1.4.1 Attributes

Name	Description
root_pose_world	World-from-corrected-reference pose at depth zero. The fixed local-Z rig-basis twist is already applied; no camera extrinsic is implied.
root_time_ns	Source capture timestamp in nanoseconds, when available.
root_trajectory_index	Source trajectory-sample index used to reconstruct root evidence.
root_frame_index	Source frame index associated with the root camera pose.
steps	Selected transitions in increasing zero-based horizon order.
cumulative_score	Sum of policy selection scores along this retained path.
terminated_early	Whether expansion stopped before the configured horizon.
termination_reason	Explicit replay-owned reason when expansion stops before the horizon.

1.1.4.2 Methods

Name	Description
final_pose_world	Return the root pose or final selected pose.
pose_chain_world	Return root and selected poses in trajectory order.
history_centers_world	Return camera centres as Tensor["T 3", float32] in world metres.
selected_shell_path	Return the stable full-shell action history identifying this state.
reference_pose_world	Return the pose from which step_index expands.
with_appended_step	Return a new trajectory with one selected transition appended.
mark_terminated	Return an immutable-style copy marked as terminated before the horizon.

1.1.4.2.1 final_pose_world

rollouts.replay.state.CounterfactualTrajectory.final_pose_world()

Return the root pose or final selected pose.

1.1.4.2.2 pose_chain_world

rollouts.replay.state.CounterfactualTrajectory.pose_chain_world()

Return root and selected poses in trajectory order.

1.1.4.2.2.1 Returns

Name	Type	Description
	PoseTW	Batched PoseTW backed by Tensor["T 12", float32], where
	PoseTW	T = len(steps) + 1.

1.1.4.2.3 history_centers_world

rollouts.replay.state.CounterfactualTrajectory.history_centers_world()

Return camera centres as Tensor["T 3", float32] in world metres.

1.1.4.2.4 selected_shell_path

rollouts.replay.state.CounterfactualTrajectory.selected_shell_path()

Return the stable full-shell action history identifying this state.

1.1.4.2.5 reference_pose_world

rollouts.replay.state.CounterfactualTrajectory.reference_pose_world(step_index)

Return the pose from which step_index expands.

1.1.4.2.6 with_appended_step

rollouts.replay.state.CounterfactualTrajectory.with_appended_step(step)

Return a new trajectory with one selected transition appended.

1.1.4.2.7 mark_terminated

rollouts.replay.state.CounterfactualTrajectory.mark_terminated(
    reason='no_selectable_candidate',
)

Return an immutable-style copy marked as terminated before the horizon.