1 rri_metrics.returns

rri_metrics.returns

Differentiable gains and returns for finite-horizon NBV evaluation.

This module provides reducers that share the hard-mask contract used by rollout replay: invalid or unsupervised actions are ignored, never converted into low rewards. For root error \(d_0\), final error \(d_H\), and selected root-normalized rewards \(r_t\),

\[ G_0^{(H)}=\sum_{t=0}^{H-1}\gamma^t r_t, \qquad J_e^{(H)}=\frac{d_0-d_H}{d_0+\epsilon}. \]

Python mapping reducers serve inspection/UI paths; tensor reducers remain differentiable for batched evaluation and future finite-candidate Q_H use.

1.1 Classes

Name	Description
TargetRolloutMetricSummary	Selected-trajectory target-RRI and endpoint metric summary.
TorchRolloutMetrics	Batched target-rollout metrics for selected trajectories.

1.1.1 TargetRolloutMetricSummary

rri_metrics.returns.TargetRolloutMetricSummary(
    cumulative_return,
    endpoint_gain,
    log_gain,
    initial_error,
    final_error,
    steps,
)

Selected-trajectory target-RRI and endpoint metric summary.

1.1.1.1 Attributes

Name	Description
cumulative_return	Discounted G_t^(H) over selected root-normalized rewards.
endpoint_gain	Endpoint target-error gain J_e^(H) when point-mesh errors exist.
log_gain	Endpoint log target-error gain when point-mesh errors exist.
initial_error	Initial target point-mesh error used for endpoint metrics.
final_error	Final target point-mesh error used for endpoint metrics.
steps	Number of selected rollout steps represented by the input metrics.

1.1.2 TorchRolloutMetrics

rri_metrics.returns.TorchRolloutMetrics(
    discounted_return,
    endpoint_gain,
    endpoint_log_gain,
    valid_steps,
    valid_endpoint,
)

Batched target-rollout metrics for selected trajectories.

1.1.2.1 Attributes

Name	Type	Description
discounted_return	Tensor	Tensor["B"] discounted sum of selected root-normalized target gains.
endpoint_gain	Tensor	Tensor["B"] root-normalized endpoint target-error gain (d_0 - d_H) / (d_0 + eps).
endpoint_log_gain	Tensor	Tensor["B"] log target-error reduction log(d_0 + eps) - log(d_H + eps).
valid_steps	Tensor	Tensor["B"] count of finite selected rewards included in discounted_return.
valid_endpoint	Tensor	Tensor["B"] mask for trajectories with finite, non-negative endpoint errors.

1.2 Functions

Name	Description
discounted_selected_return	Compute discounted returns over selected rewards.
endpoint_log_gain	Compute endpoint log gain through the tensor-first kernel.
endpoint_log_gain_tensor	Compute endpoint log target-error reduction.
endpoint_target_gain	Compute endpoint gain through the tensor-first kernel.
endpoint_target_gain_tensor	Compute root-normalized endpoint gain from target point-mesh errors.
finite_horizon_target_return	Compute a discounted return through the tensor-first kernel.
log_error_gain	Compute logarithmic reconstruction-error reduction.
root_normalized_gain	Compute gain divided by the additive guarded rollout-root error.
selected_target_reward	Return the selected-step root-normalized reward used by rollout/Q_H.
selected_target_rri	Return the selected-step target RRI from one metric mapping.
summarize_selected_rollout_tensors	Summarize selected target-rollout tensors in one batched call.
summarize_target_rollout_metrics	Summarize one selected trajectory using the canonical tensor kernels.
target_point_mesh_error_after	Return selected-step target point-mesh error after adding the view.
target_point_mesh_error_before	Return selected-step target point-mesh error before adding the view.

1.2.1 discounted_selected_return

rri_metrics.returns.discounted_selected_return(
    rewards,
    valid_mask=None,
    *,
    gamma=1.0,
)

Compute discounted returns over selected rewards.

1.2.1.1 Parameters

Name	Type	Description	Default
rewards	Tensor	Tensor["B H"] or Tensor["H"] selected per-step rewards, normally target_root_gain.	required
valid_mask	Tensor | None	Optional boolean tensor with the same shape as rewards. Non-finite rewards are ignored even when this mask is True.	None
gamma	float	Non-negative discount factor.	1.0

1.2.1.2 Returns

Name	Type	Description
	Tensor	Tensor with shape Tensor["B"] for 2-D inputs or scalar shape for
	Tensor	1-D inputs. Rows with no valid finite rewards return NaN.

1.2.2 endpoint_log_gain

rri_metrics.returns.endpoint_log_gain(
    selected_metric_rows,
    *,
    eps=DEFAULT_RRI_EPSILON,
)

Compute endpoint log gain through the tensor-first kernel.

1.2.3 endpoint_log_gain_tensor

rri_metrics.returns.endpoint_log_gain_tensor(
    initial_error,
    final_error,
    *,
    eps=DEFAULT_RRI_EPSILON,
)

Compute endpoint log target-error reduction.

1.2.3.1 Parameters

Name	Type	Description	Default
initial_error	Tensor	Initial target point-mesh error d_0.	required
final_error	Tensor	Final target point-mesh error d_H.	required
eps	float	Positive log guard.	DEFAULT_RRI_EPSILON

1.2.3.2 Returns

Name	Type	Description
	Tensor	Tensor broadcast from the input shapes. Entries with non-finite or
	Tensor	negative endpoint errors return NaN.

1.2.4 endpoint_target_gain

rri_metrics.returns.endpoint_target_gain(
    selected_metric_rows,
    *,
    eps=DEFAULT_RRI_EPSILON,
)

Compute endpoint gain through the tensor-first kernel.

1.2.5 endpoint_target_gain_tensor

rri_metrics.returns.endpoint_target_gain_tensor(
    initial_error,
    final_error,
    *,
    eps=DEFAULT_RRI_EPSILON,
)

Compute root-normalized endpoint gain from target point-mesh errors.

1.2.5.1 Parameters

Name	Type	Description	Default
initial_error	Tensor	Initial target point-mesh error d_0.	required
final_error	Tensor	Final target point-mesh error d_H.	required
eps	float	Positive denominator guard.	DEFAULT_RRI_EPSILON

1.2.5.2 Returns

Name	Type	Description
	Tensor	Tensor broadcast from the input shapes. Entries with non-finite or
	Tensor	negative endpoint errors return NaN.

1.2.6 finite_horizon_target_return

rri_metrics.returns.finite_horizon_target_return(
    selected_metric_rows,
    *,
    gamma=1.0,
)

Compute a discounted return through the tensor-first kernel.

1.2.7 log_error_gain

rri_metrics.returns.log_error_gain(before, after, *, eps=DEFAULT_RRI_EPSILON)

Compute logarithmic reconstruction-error reduction.

1.2.8 root_normalized_gain

rri_metrics.returns.root_normalized_gain(
    before,
    after,
    root_error,
    *,
    eps=DEFAULT_RRI_EPSILON,
)

Compute gain divided by the additive guarded rollout-root error.

1.2.9 selected_target_reward

rri_metrics.returns.selected_target_reward(metrics)

Return the selected-step root-normalized reward used by rollout/Q_H.

1.2.10 selected_target_rri

rri_metrics.returns.selected_target_rri(metrics)

Return the selected-step target RRI from one metric mapping.

1.2.11 summarize_selected_rollout_tensors

rri_metrics.returns.summarize_selected_rollout_tensors(
    rewards,
    initial_error,
    final_error,
    valid_mask=None,
    *,
    gamma=1.0,
    eps=DEFAULT_RRI_EPSILON,
)

Summarize selected target-rollout tensors in one batched call.

1.2.11.1 Parameters

Name	Type	Description	Default
rewards	Tensor	Tensor["B H"] selected rewards, normally root-normalized target gains.	required
initial_error	Tensor	Tensor["B"] initial target point-mesh errors.	required
final_error	Tensor	Tensor["B"] final target point-mesh errors.	required
valid_mask	Tensor | None	Optional Tensor["B H"] mask for reward supervision.	None
gamma	float	Non-negative discount factor.	1.0
eps	float	Denominator and log guard for endpoint metrics.	DEFAULT_RRI_EPSILON

1.2.11.2 Returns

Name	Type	Description
	TorchRolloutMetrics	TorchRolloutMetrics with one value per trajectory.

1.2.12 summarize_target_rollout_metrics

rri_metrics.returns.summarize_target_rollout_metrics(
    selected_metric_rows,
    *,
    gamma=1.0,
    eps=DEFAULT_RRI_EPSILON,
)

Summarize one selected trajectory using the canonical tensor kernels.

1.2.13 target_point_mesh_error_after

rri_metrics.returns.target_point_mesh_error_after(metrics)

Return selected-step target point-mesh error after adding the view.

1.2.14 target_point_mesh_error_before

rri_metrics.returns.target_point_mesh_error_before(metrics)

Return selected-step target point-mesh error before adding the view.