1 rri_metrics

rri_metrics

Stable public API for prepared RRI scoring and VIN ordinal supervision.

The package root exposes the prepared RRI payload/formula and empirical RriOrdinalBinner targets consumed by VIN. Oracle evidence preparation, rollout reducers, plotting, and stateful diagnostics remain in their owning submodules so importing aria_nbv.rri_metrics does not imply those secondary APIs are stable.

Oracle geometry and RRI values are label/evaluation data. CORAL logits, decoded ranks, and expected bin values are learned actor-side predictions; candidate hard-validity masks remain separate from both surfaces.

1.1 Package guide

aria_nbv.rri_metrics owns prepared Relative Reconstruction Improvement (RRI), finite-horizon return kernels, ranking diagnostics, ordinal binning, and stateful metric adapters. Oracle evidence preparation lives in aria_nbv.oracle; operational rollout validity lives in aria_nbv.rollouts.inspection.audits.

1.2 Prepared RRI

from aria_nbv.rri_metrics import RriConfig, compute_rri

result = compute_rri(before_distances, after_distances, config=RriConfig())
candidate_rri = result.rri

The differentiable formula is

RRI_t(q) = (D(P_t, M) - D(P_{t|q}, M)) / (D(P_t, M) + epsilon)

Here P_t and P_{t|q} are the prepared current and candidate-successor states supplied by the caller. The formula does not assume that preparation distributes over a point-set union.

The shared default is epsilon = 1e-12; callers may override it explicitly. RRI is dimensionless and may be negative for a valid candidate. Invalidity is therefore never encoded as a low or zero RRI value; it remains a separate hard mask and reason-code contract.

Persisted RRI and root-gain values retain the numerical policy used when they were generated. New Oracle-generated rollout manifests record the formula revision, additive denominator and log guards, and epsilon under generation.metric_policy. A missing policy marks a historical or otherwise unknown numerical contract. Rollout schema versions describe the stored layout, so consumers must not infer the denominator policy from schema_version alone.

1.3 Select the Right Module

Module	Responsibility	Differentiable
`point_mesh`	Point-to-mesh and mesh-to-point distance primitives.	Where PyTorch3D permits
`rri`	Prepared candidate-aligned RRI formula and diagnostics.	Yes
`returns`	Step gains, endpoint gains, and finite-horizon return kernels.	Tensor kernels only
`ranking`	Top-k hits, selected-action comparison, regret, and rank.	No
`ordinal`	Empirical RRI binning for one-step CORAL supervision.	No
`torchmetrics_single`	Stateful one-step evaluation.	No
`torchmetrics_multi`	Stateful selected-rollout evaluation.	No

The package root intentionally exports only compute_rri, RriConfig, RriResult, and RriOrdinalBinner. Import specialized reducers from their leaf modules.

1.4 Finite-Horizon Semantics

returns.py owns reusable mathematical reducers; rollout stores own factual transition rows; QH Lightning owns fitted targets and metric lifecycle. Direct conditional-Q regression and CORAL decoding are scorer concerns and do not change the RRI label definition.

The exact equations, shapes, and masking preconditions live in source docstrings and the generated API reference. Scientific interpretation belongs to the active method chapter.

1.5 Verification

cd aria_nbv
uv run ruff check aria_nbv/rri_metrics
uv run pytest tests/vin/test_rri_binning.py tests/vin/test_coral.py

Run the focused return or ranking tests when changing those leaf modules.

1.6 Classes

Name	Description
RriConfig	Numerical contract for prepared RRI computation.
RriOrdinalBinner	Map finite oracle RRI values to globally fitted ordinal classes.
RriResult	Batch of oracle RRI labels and directional distance diagnostics.

1.6.1 RriConfig

rri_metrics.RriConfig(epsilon=DEFAULT_RRI_EPSILON)

Numerical contract for prepared RRI computation.

1.6.1.1 Attributes

Name	Description
epsilon	Positive additive denominator guard for reconstruction errors.

1.6.2 RriOrdinalBinner

rri_metrics.RriOrdinalBinner(
    num_classes=0,
    edges=(lambda: torch.empty((0,), dtype=torch.float32))(),
    midpoints=None,
    bin_means=None,
    bin_stds=None,
    bin_counts=None,
    _rri_chunks=list(),
)

Map finite oracle RRI values to globally fitted ordinal classes.

K classes are separated by K-1 nondecreasing empirical quantile edges. The fitted statistics are dimensionless because RRI is normalized. Fitting accumulates transient CPU chunks; JSON persistence stores the compact fitted artifact used by training and evaluation.

1.6.2.1 Attributes

Name	Description
num_classes	Number of ordinal classes `K`; fitted binners require `K >= 2`.
edges	`Tensor["K-1", float32]` dimensionless quantile edges in ascending order.
midpoints	Optional `Tensor["K", float32]` dimensionless extrapolated class midpoints.
bin_means	Optional `Tensor["K", float32]` empirical oracle-RRI mean per class.
bin_stds	Optional `Tensor["K", float32]` empirical oracle-RRI standard deviation per class.
bin_counts	Optional `Tensor["K", float32]` finite sample counts used to derive priors.
is_fitted	Report whether `K` and the required `K-1` edges are present.

1.6.2.2 Methods

Name	Description
transform	Bucketize oracle RRI values into a flat candidate/sample axis.
labels_to_levels	Expand `Tensor["...", int64]` labels to `Tensor["... K-1", float32]` levels.
rri_to_levels	Flatten RRI values and return `Tensor["N K-1", float32]` CORAL levels.
class_midpoints	Return dimensionless class representatives derived from quantile edges.
class_priors	Return `Tensor["K", float32]` empirical class priors or a uniform fallback.
threshold_priors	Return `Tensor["K-1", float32]` cumulative priors `P(y > k)`.
expected_from_probs	Compute expected RRI proxy from class probabilities.
to_dict	Return the fitted JSON payload with CPU-native edges and optional statistics.
from_dict	Construct a CPU binner from a payload produced by :meth:`to_dict`.
save	Atomically save a fitted JSON artifact and return its resolved path.
load	Load a fitted CPU binner from a resolved JSON artifact path.
load_fit_data	Load flattened RRI samples from a saved binner fit-data file.
fit_from_iterable	Fit global quantile edges from a stream of finite oracle RRI chunks.

1.6.2.2.1 transform

rri_metrics.RriOrdinalBinner.transform(rri)

Bucketize oracle RRI values into a flat candidate/sample axis.

1.6.2.2.1.1 Parameters

Name	Type	Description	Default
rri `Tensor["...", float32]`		Finite, hard-valid, dimensionless oracle RRI values.	required

1.6.2.2.1.2 Returns

Name	Type	Description
	Tensor	`Tensor["N", int64]` flattened labels in `[0, K-1]`. A value
	Tensor	equal to an edge is assigned to the lower adjacent class because
	Tensor	`torch.bucketize(..., right=False)` is used.

1.6.2.2.2 labels_to_levels

rri_metrics.RriOrdinalBinner.labels_to_levels(labels)

Expand Tensor["...", int64] labels to Tensor["... K-1", float32] levels.

1.6.2.2.3 rri_to_levels

rri_metrics.RriOrdinalBinner.rri_to_levels(rri)

Flatten RRI values and return Tensor["N K-1", float32] CORAL levels.

1.6.2.2.4 class_midpoints

rri_metrics.RriOrdinalBinner.class_midpoints()

Return dimensionless class representatives derived from quantile edges.

1.6.2.2.4.1 Returns

Name	Type	Description
	Tensor	`Tensor["K", float32]` class midpoints. Interior values average
	Tensor	adjacent edges; endpoint values extrapolate half an edge spacing.

1.6.2.2.4.2 Notes

If midpoints is not already stored, extrapolation requires at least two edges, corresponding to K >= 3.

1.6.2.2.5 class_priors

rri_metrics.RriOrdinalBinner.class_priors()

Return Tensor["K", float32] empirical class priors or a uniform fallback.

1.6.2.2.6 threshold_priors

rri_metrics.RriOrdinalBinner.threshold_priors()

Return Tensor["K-1", float32] cumulative priors P(y > k).

1.6.2.2.7 expected_from_probs

rri_metrics.RriOrdinalBinner.expected_from_probs(probs)

Compute expected RRI proxy from class probabilities.

1.6.2.2.7.1 Parameters

Name	Type	Description	Default
probs `Tensor["... K", float32]`		Actor-predicted class probabilities aligned with this binner’s class order.	required

1.6.2.2.7.2 Returns

Name	Type	Description
	Tensor	`Tensor["...", float32]` dimensionless continuous RRI proxies
	Tensor	using empirical bin means when present, otherwise midpoints.

1.6.2.2.8 to_dict

rri_metrics.RriOrdinalBinner.to_dict()

Return the fitted JSON payload with CPU-native edges and optional statistics.

1.6.2.2.9 from_dict

rri_metrics.RriOrdinalBinner.from_dict(data)

Construct a CPU binner from a payload produced by :meth:to_dict.

1.6.2.2.10 save

rri_metrics.RriOrdinalBinner.save(path, *, overwrite=False)

Atomically save a fitted JSON artifact and return its resolved path.

Relative paths are resolved through aria_nbv.configs.PathConfig. Unless overwrite is true, an existing target receives a numeric suffix instead of being replaced.

1.6.2.2.11 load

rri_metrics.RriOrdinalBinner.load(path)

Load a fitted CPU binner from a resolved JSON artifact path.

1.6.2.2.12 load_fit_data

rri_metrics.RriOrdinalBinner.load_fit_data(path)

Load flattened RRI samples from a saved binner fit-data file.

1.6.2.2.12.1 Parameters

Name	Type	Description	Default
path	str \| Path	Path to a `.pt` file that stores `rri_chunks`.	required

1.6.2.2.12.2 Returns

Name	Type	Description
	Tensor	`Tensor["N", float32]` of finite RRI samples.

1.6.2.2.13 fit_from_iterable

rri_metrics.RriOrdinalBinner.fit_from_iterable(
    iterable,
    *,
    num_classes=15,
    target_items=None,
    max_skips=0,
    fit_data_path=None,
    resume=False,
    save_every=1,
    on_progress=None,
)

Fit global quantile edges from a stream of finite oracle RRI chunks.

1.6.2.2.13.1 Parameters

Name	Type	Description	Default
iterable	Iterable[Tensor \| tuple[Tensor, Any]]	Stream of RRI tensors or `(rri, metadata)` pairs. Each yielded tensor counts as one successful item after finite filtering, regardless of its number of scalar samples.	required
num_classes	int	Requested class count `K >= 2`.	`15`
target_items	int \| None	Optional number of successful yielded items to collect before fitting; this is not a scalar-sample count.	`None`
max_skips	int	Maximum all-nonfinite items before failure; `0` allows unlimited skips until the iterable is exhausted.	`0`
fit_data_path	str \| Path \| None	Optional `.pt` checkpoint for CPU RRI chunks.	`None`
resume	bool	Load existing fit chunks from `fit_data_path` before consuming `iterable`.	`False`
save_every	int	Successful-item interval for atomic fit-data writes; non-positive values disable periodic writes but not the final or exception write.	`1`
on_progress	Callable[[int, int, Tensor \| None, Any \| None], None] \| None	Optional callback receiving successful-item count, skip count, the latest finite tensor on its input device, and yielded metadata.	`None`

1.6.2.2.13.2 Returns

Name	Type	Description
Fitted	RriOrdinalBinner	class:`RriOrdinalBinner` with CPU edges, means, standard
	RriOrdinalBinner	deviations, and counts.

1.6.2.2.13.3 Notes

All fit data is stored on CPU.
Fit data is saved on Ctrl-C / exceptions when fit_data_path is provided.
The iterable may yield either rri tensors or (rri, meta) tuples.
Callers must apply hard candidate validity before yielding; this function removes non-finite values but has no validity mask.

1.6.3 RriResult

rri_metrics.RriResult(
    rri,
    pm_dist_before,
    pm_dist_after,
    pm_acc_before,
    pm_comp_before,
    pm_acc_after,
    pm_comp_after,
    fscore_tau=None,
)

Batch of oracle RRI labels and directional distance diagnostics.

C is the finite-candidate axis. Reference-only distances are broadcast to that axis so every diagnostic stays aligned with its candidate row. For the bidirectional squared point–mesh error $D$, the label is

\[ \mathrm{RRI}_t(q)=\frac{D(P_t,M)-D(P_{t\mid q},M)} {D(P_t,M)+\epsilon}. \]

Here $P_t$ and $P_{t\mid q}$ are the prepared current and candidate- successor states supplied to compute_rri; this payload does not assume that preparation distributes over a point-set union.

RRI is dimensionless and can be negative when candidate evidence worsens the reconstruction. A low or negative value is still a valid oracle label; candidate invalidity is an upstream hard-mask/reason-code contract and is not encoded in this payload. In the thesis pipeline, the matched target mesh and rendered candidate geometry are oracle-only supervision, not actor-visible VIN inputs.

1.6.3.1 Attributes

Name	Description
rri	`Tensor["C", float32]` dimensionless relative reconstruction improvement.
pm_dist_before	`Tensor["C", float32]` broadcast pre-view bidirectional error, in square metres.
pm_dist_after	`Tensor["C", float32]` post-view bidirectional error per candidate, in square metres.
pm_acc_before	`Tensor["C", float32]` broadcast pre-view point-to-mesh error, in square metres.
pm_comp_before	`Tensor["C", float32]` broadcast pre-view mesh-to-point error, in square metres.
pm_acc_after	`Tensor["C", float32]` post-view point-to-mesh error, in square metres.
pm_comp_after	`Tensor["C", float32]` post-view mesh-to-point error, in square metres.
fscore_tau	Optional `Tensor["C ...", float32]` per-candidate F-scores at configured thresholds.

1.6.3.2 Methods

Name	Description
to_serializable	Serialize tensors into a cache-friendly CPU payload without changing candidate order.
from_serializable	Reconstruct one candidate-aligned result on a requested device.
to	Return a copy with every present tensor moved to `device`.

1.6.3.2.1 to_serializable

rri_metrics.RriResult.to_serializable()

Serialize tensors into a cache-friendly CPU payload without changing candidate order.

1.6.3.2.2 from_serializable

rri_metrics.RriResult.from_serializable(payload, *, device)

Reconstruct one candidate-aligned result on a requested device.

1.6.3.2.2.1 Parameters

Name	Type	Description	Default
payload	dict[str, Any]	Serialized payload produced by :meth:`to_serializable`.	required
device	torch.device	Destination device for tensors.	required

1.6.3.2.2.2 Returns

Name	Type	Description
	'RriResult'	Reconstructed RRI result.

1.6.3.2.3 to

rri_metrics.RriResult.to(device)

Return a copy with every present tensor moved to device.

1.7 Functions

Name	Description
compute_rri	Compute RRI from prepared before/after point-mesh distances.

1.7.1 compute_rri

rri_metrics.compute_rri(before, after, *, config=_DEFAULT_RRI_CONFIG)

Compute RRI from prepared before/after point-mesh distances.

The caller owns evidence preparation, cropping, and fusion. This function owns only the differentiable reconstruction-improvement formula.

# rri_metrics { #aria_nbv.rri_metrics } `rri_metrics` Stable public API for prepared RRI scoring and VIN ordinal supervision. The package root exposes the prepared RRI payload/formula and empirical :class:`RriOrdinalBinner` targets consumed by VIN. Oracle evidence preparation, rollout reducers, plotting, and stateful diagnostics remain in their owning submodules so importing :mod:`aria_nbv.rri_metrics` does not imply those secondary APIs are stable. Oracle geometry and RRI values are label/evaluation data. CORAL logits, decoded ranks, and expected bin values are learned actor-side predictions; candidate hard-validity masks remain separate from both surfaces.  ## Package guide `aria_nbv.rri_metrics` owns prepared Relative Reconstruction Improvement (RRI), finite-horizon return kernels, ranking diagnostics, ordinal binning, and stateful metric adapters. Oracle evidence preparation lives in `aria_nbv.oracle`; operational rollout validity lives in `aria_nbv.rollouts.inspection.audits`. ## Prepared RRI ```python from aria_nbv.rri_metrics import RriConfig, compute_rri result = compute_rri(before_distances, after_distances, config=RriConfig()) candidate_rri = result.rri ``` The differentiable formula is ```text RRI_t(q) = (D(P_t, M) - D(P_{t|q}, M)) / (D(P_t, M) + epsilon) ``` Here `P_t` and `P_{t|q}` are the prepared current and candidate-successor states supplied by the caller. The formula does not assume that preparation distributes over a point-set union. The shared default is `epsilon = 1e-12`; callers may override it explicitly. RRI is dimensionless and may be negative for a valid candidate. Invalidity is therefore never encoded as a low or zero RRI value; it remains a separate hard mask and reason-code contract. Persisted RRI and root-gain values retain the numerical policy used when they were generated. New Oracle-generated rollout manifests record the formula revision, additive denominator and log guards, and epsilon under `generation.metric_policy`. A missing policy marks a historical or otherwise unknown numerical contract. Rollout schema versions describe the stored layout, so consumers must not infer the denominator policy from `schema_version` alone. ## Select the Right Module | Module | Responsibility | Differentiable | | --- | --- | ---: | | `point_mesh` | Point-to-mesh and mesh-to-point distance primitives. | Where PyTorch3D permits | | `rri` | Prepared candidate-aligned RRI formula and diagnostics. | Yes | | `returns` | Step gains, endpoint gains, and finite-horizon return kernels. | Tensor kernels only | | `ranking` | Top-k hits, selected-action comparison, regret, and rank. | No | | `ordinal` | Empirical RRI binning for one-step CORAL supervision. | No | | `torchmetrics_single` | Stateful one-step evaluation. | No | | `torchmetrics_multi` | Stateful selected-rollout evaluation. | No | The package root intentionally exports only `compute_rri`, `RriConfig`, `RriResult`, and `RriOrdinalBinner`. Import specialized reducers from their leaf modules. ## Finite-Horizon Semantics `returns.py` owns reusable mathematical reducers; rollout stores own factual transition rows; QH Lightning owns fitted targets and metric lifecycle. Direct conditional-Q regression and CORAL decoding are scorer concerns and do not change the RRI label definition. The exact equations, shapes, and masking preconditions live in source docstrings and the [generated API reference](index.qmd). Scientific interpretation belongs to the active [method chapter](../typst/thesis/sections/04-method/04-05-finite-candidate-value-model.typ). ## Verification ```sh cd aria_nbv uv run ruff check aria_nbv/rri_metrics uv run pytest tests/vin/test_rri_binning.py tests/vin/test_coral.py ``` Run the focused return or ranking tests when changing those leaf modules.  ## Classes | Name | Description | | --- | --- | | [RriConfig](#aria_nbv.rri_metrics.RriConfig) | Numerical contract for prepared RRI computation. | | [RriOrdinalBinner](#aria_nbv.rri_metrics.RriOrdinalBinner) | Map finite oracle RRI values to globally fitted ordinal classes. | | [RriResult](#aria_nbv.rri_metrics.RriResult) | Batch of oracle RRI labels and directional distance diagnostics. | ### RriConfig { #aria_nbv.rri_metrics.RriConfig } ```python rri_metrics.RriConfig(epsilon=DEFAULT_RRI_EPSILON) ``` Numerical contract for prepared RRI computation. #### Attributes | Name | Description | | --- | --- | | [epsilon](#aria_nbv.rri_metrics.RriConfig.epsilon) | Positive additive denominator guard for reconstruction errors. | ### RriOrdinalBinner { #aria_nbv.rri_metrics.RriOrdinalBinner } ```python rri_metrics.RriOrdinalBinner( num_classes=0, edges=(lambda: torch.empty((0,), dtype=torch.float32))(), midpoints=None, bin_means=None, bin_stds=None, bin_counts=None, _rri_chunks=list(), ) ``` Map finite oracle RRI values to globally fitted ordinal classes. ``K`` classes are separated by ``K-1`` nondecreasing empirical quantile edges. The fitted statistics are dimensionless because RRI is normalized. Fitting accumulates transient CPU chunks; JSON persistence stores the compact fitted artifact used by training and evaluation. #### Attributes | Name | Description | | --- | --- | | [num_classes](#aria_nbv.rri_metrics.RriOrdinalBinner.num_classes) | Number of ordinal classes ``K``; fitted binners require ``K >= 2``. | | [edges](#aria_nbv.rri_metrics.RriOrdinalBinner.edges) | ``Tensor["K-1", float32]`` dimensionless quantile edges in ascending order. | | [midpoints](#aria_nbv.rri_metrics.RriOrdinalBinner.midpoints) | Optional ``Tensor["K", float32]`` dimensionless extrapolated class midpoints. | | [bin_means](#aria_nbv.rri_metrics.RriOrdinalBinner.bin_means) | Optional ``Tensor["K", float32]`` empirical oracle-RRI mean per class. | | [bin_stds](#aria_nbv.rri_metrics.RriOrdinalBinner.bin_stds) | Optional ``Tensor["K", float32]`` empirical oracle-RRI standard deviation per class. | | [bin_counts](#aria_nbv.rri_metrics.RriOrdinalBinner.bin_counts) | Optional ``Tensor["K", float32]`` finite sample counts used to derive priors. | | [is_fitted](#aria_nbv.rri_metrics.RriOrdinalBinner.is_fitted) | Report whether ``K`` and the required ``K-1`` edges are present. | #### Methods | Name | Description | | --- | --- | | [transform](#aria_nbv.rri_metrics.RriOrdinalBinner.transform) | Bucketize oracle RRI values into a flat candidate/sample axis. | | [labels_to_levels](#aria_nbv.rri_metrics.RriOrdinalBinner.labels_to_levels) | Expand ``Tensor["...", int64]`` labels to ``Tensor["... K-1", float32]`` levels. | | [rri_to_levels](#aria_nbv.rri_metrics.RriOrdinalBinner.rri_to_levels) | Flatten RRI values and return ``Tensor["N K-1", float32]`` CORAL levels. | | [class_midpoints](#aria_nbv.rri_metrics.RriOrdinalBinner.class_midpoints) | Return dimensionless class representatives derived from quantile edges. | | [class_priors](#aria_nbv.rri_metrics.RriOrdinalBinner.class_priors) | Return ``Tensor["K", float32]`` empirical class priors or a uniform fallback. | | [threshold_priors](#aria_nbv.rri_metrics.RriOrdinalBinner.threshold_priors) | Return ``Tensor["K-1", float32]`` cumulative priors ``P(y > k)``. | | [expected_from_probs](#aria_nbv.rri_metrics.RriOrdinalBinner.expected_from_probs) | Compute expected RRI proxy from class probabilities. | | [to_dict](#aria_nbv.rri_metrics.RriOrdinalBinner.to_dict) | Return the fitted JSON payload with CPU-native edges and optional statistics. | | [from_dict](#aria_nbv.rri_metrics.RriOrdinalBinner.from_dict) | Construct a CPU binner from a payload produced by :meth:`to_dict`. | | [save](#aria_nbv.rri_metrics.RriOrdinalBinner.save) | Atomically save a fitted JSON artifact and return its resolved path. | | [load](#aria_nbv.rri_metrics.RriOrdinalBinner.load) | Load a fitted CPU binner from a resolved JSON artifact path. | | [load_fit_data](#aria_nbv.rri_metrics.RriOrdinalBinner.load_fit_data) | Load flattened RRI samples from a saved binner fit-data file. | | [fit_from_iterable](#aria_nbv.rri_metrics.RriOrdinalBinner.fit_from_iterable) | Fit global quantile edges from a stream of finite oracle RRI chunks. | ##### transform { #aria_nbv.rri_metrics.RriOrdinalBinner.transform } ```python rri_metrics.RriOrdinalBinner.transform(rri) ``` Bucketize oracle RRI values into a flat candidate/sample axis. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |--------------------------------|--------|------------------------------------------------------|------------| | rri ``Tensor["...", float32]`` | | Finite, hard-valid, dimensionless oracle RRI values. | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------------------|------------------------------------------------------------------| | | [Tensor](`torch.Tensor`) | ``Tensor["N", int64]`` flattened labels in ``[0, K-1]``. A value | | | [Tensor](`torch.Tensor`) | equal to an edge is assigned to the lower adjacent class because | | | [Tensor](`torch.Tensor`) | ``torch.bucketize(..., right=False)`` is used. | ##### labels_to_levels { #aria_nbv.rri_metrics.RriOrdinalBinner.labels_to_levels } ```python rri_metrics.RriOrdinalBinner.labels_to_levels(labels) ``` Expand ``Tensor["...", int64]`` labels to ``Tensor["... K-1", float32]`` levels. ##### rri_to_levels { #aria_nbv.rri_metrics.RriOrdinalBinner.rri_to_levels } ```python rri_metrics.RriOrdinalBinner.rri_to_levels(rri) ``` Flatten RRI values and return ``Tensor["N K-1", float32]`` CORAL levels. ##### class_midpoints { #aria_nbv.rri_metrics.RriOrdinalBinner.class_midpoints } ```python rri_metrics.RriOrdinalBinner.class_midpoints() ``` Return dimensionless class representatives derived from quantile edges. ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------------------|-------------------------------------------------------------------| | | [Tensor](`torch.Tensor`) | ``Tensor["K", float32]`` class midpoints. Interior values average | | | [Tensor](`torch.Tensor`) | adjacent edges; endpoint values extrapolate half an edge spacing. | ###### Notes {.doc-section .doc-section-notes} If `midpoints` is not already stored, extrapolation requires at least two edges, corresponding to ``K >= 3``. ##### class_priors { #aria_nbv.rri_metrics.RriOrdinalBinner.class_priors } ```python rri_metrics.RriOrdinalBinner.class_priors() ``` Return ``Tensor["K", float32]`` empirical class priors or a uniform fallback. ##### threshold_priors { #aria_nbv.rri_metrics.RriOrdinalBinner.threshold_priors } ```python rri_metrics.RriOrdinalBinner.threshold_priors() ``` Return ``Tensor["K-1", float32]`` cumulative priors ``P(y > k)``. ##### expected_from_probs { #aria_nbv.rri_metrics.RriOrdinalBinner.expected_from_probs } ```python rri_metrics.RriOrdinalBinner.expected_from_probs(probs) ``` Compute expected RRI proxy from class probabilities. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |------------------------------------|--------|-----------------------------------------------------------------------------|------------| | probs ``Tensor["... K", float32]`` | | Actor-predicted class probabilities aligned with this binner's class order. | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------------------|-----------------------------------------------------------------| | | [Tensor](`torch.Tensor`) | ``Tensor["...", float32]`` dimensionless continuous RRI proxies | | | [Tensor](`torch.Tensor`) | using empirical bin means when present, otherwise midpoints. | ##### to_dict { #aria_nbv.rri_metrics.RriOrdinalBinner.to_dict } ```python rri_metrics.RriOrdinalBinner.to_dict() ``` Return the fitted JSON payload with CPU-native edges and optional statistics. ##### from_dict { #aria_nbv.rri_metrics.RriOrdinalBinner.from_dict } ```python rri_metrics.RriOrdinalBinner.from_dict(data) ``` Construct a CPU binner from a payload produced by :meth:`to_dict`. ##### save { #aria_nbv.rri_metrics.RriOrdinalBinner.save } ```python rri_metrics.RriOrdinalBinner.save(path, *, overwrite=False) ``` Atomically save a fitted JSON artifact and return its resolved path. Relative paths are resolved through :class:`aria_nbv.configs.PathConfig`. Unless `overwrite` is true, an existing target receives a numeric suffix instead of being replaced. ##### load { #aria_nbv.rri_metrics.RriOrdinalBinner.load } ```python rri_metrics.RriOrdinalBinner.load(path) ``` Load a fitted CPU binner from a resolved JSON artifact path. ##### load_fit_data { #aria_nbv.rri_metrics.RriOrdinalBinner.load_fit_data } ```python rri_metrics.RriOrdinalBinner.load_fit_data(path) ``` Load flattened RRI samples from a saved binner fit-data file. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |--------|----------------------------------------|----------------------------------------------------|------------| | path | [str](`str`) \| [Path](`pathlib.Path`) | Path to a ``.pt`` file that stores ``rri_chunks``. | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------------------|-------------------------------------------------| | | [Tensor](`torch.Tensor`) | ``Tensor["N", float32]`` of finite RRI samples. | ##### fit_from_iterable { #aria_nbv.rri_metrics.RriOrdinalBinner.fit_from_iterable } ```python rri_metrics.RriOrdinalBinner.fit_from_iterable( iterable, *, num_classes=15, target_items=None, max_skips=0, fit_data_path=None, resume=False, save_every=1, on_progress=None, ) ``` Fit global quantile edges from a stream of finite oracle RRI chunks. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| | iterable | [Iterable](`collections.abc.Iterable`)\[[Tensor](`torch.Tensor`) \| [tuple](`tuple`)\[[Tensor](`torch.Tensor`), [Any](`typing.Any`)\]\] | Stream of RRI tensors or ``(rri, metadata)`` pairs. Each yielded tensor counts as one successful item after finite filtering, regardless of its number of scalar samples. | _required_ | | num_classes | [int](`int`) | Requested class count ``K >= 2``. | `15` | | target_items | [int](`int`) \| None | Optional number of successful yielded items to collect before fitting; this is not a scalar-sample count. | `None` | | max_skips | [int](`int`) | Maximum all-nonfinite items before failure; ``0`` allows unlimited skips until the iterable is exhausted. | `0` | | fit_data_path | [str](`str`) \| [Path](`pathlib.Path`) \| None | Optional ``.pt`` checkpoint for CPU RRI chunks. | `None` | | resume | [bool](`bool`) | Load existing fit chunks from `fit_data_path` before consuming `iterable`. | `False` | | save_every | [int](`int`) | Successful-item interval for atomic fit-data writes; non-positive values disable periodic writes but not the final or exception write. | `1` | | on_progress | [Callable](`collections.abc.Callable`)\[\[[int](`int`), [int](`int`), [Tensor](`torch.Tensor`) \| None, [Any](`typing.Any`) \| None\], None\] \| None | Optional callback receiving successful-item count, skip count, the latest finite tensor on its input device, and yielded metadata. | `None` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|---------------------------------------------------------------------|----------------------------------------------------------| | Fitted | [RriOrdinalBinner](`aria_nbv.rri_metrics.ordinal.RriOrdinalBinner`) | class:`RriOrdinalBinner` with CPU edges, means, standard | | | [RriOrdinalBinner](`aria_nbv.rri_metrics.ordinal.RriOrdinalBinner`) | deviations, and counts. | ###### Notes {.doc-section .doc-section-notes} - All fit data is stored on CPU. - Fit data is saved on Ctrl-C / exceptions when ``fit_data_path`` is provided. - The iterable may yield either ``rri`` tensors or ``(rri, meta)`` tuples. - Callers must apply hard candidate validity before yielding; this function removes non-finite values but has no validity mask. ### RriResult { #aria_nbv.rri_metrics.RriResult } ```python rri_metrics.RriResult( rri, pm_dist_before, pm_dist_after, pm_acc_before, pm_comp_before, pm_acc_after, pm_comp_after, fscore_tau=None, ) ``` Batch of oracle RRI labels and directional distance diagnostics. ``C`` is the finite-candidate axis. Reference-only distances are broadcast to that axis so every diagnostic stays aligned with its candidate row. For the bidirectional squared point--mesh error $D$, the label is $$ \mathrm{RRI}_t(q)=\frac{D(P_t,M)-D(P_{t\mid q},M)} {D(P_t,M)+\epsilon}. $$ Here $P_t$ and $P_{t\mid q}$ are the prepared current and candidate- successor states supplied to :func:`compute_rri`; this payload does not assume that preparation distributes over a point-set union. RRI is dimensionless and can be negative when candidate evidence worsens the reconstruction. A low or negative value is still a valid oracle label; candidate invalidity is an upstream hard-mask/reason-code contract and is not encoded in this payload. In the thesis pipeline, the matched target mesh and rendered candidate geometry are oracle-only supervision, not actor-visible VIN inputs. #### Attributes | Name | Description | | --- | --- | | [rri](#aria_nbv.rri_metrics.RriResult.rri) | ``Tensor["C", float32]`` dimensionless relative reconstruction improvement. | | [pm_dist_before](#aria_nbv.rri_metrics.RriResult.pm_dist_before) | ``Tensor["C", float32]`` broadcast pre-view bidirectional error, in square metres. | | [pm_dist_after](#aria_nbv.rri_metrics.RriResult.pm_dist_after) | ``Tensor["C", float32]`` post-view bidirectional error per candidate, in square metres. | | [pm_acc_before](#aria_nbv.rri_metrics.RriResult.pm_acc_before) | ``Tensor["C", float32]`` broadcast pre-view point-to-mesh error, in square metres. | | [pm_comp_before](#aria_nbv.rri_metrics.RriResult.pm_comp_before) | ``Tensor["C", float32]`` broadcast pre-view mesh-to-point error, in square metres. | | [pm_acc_after](#aria_nbv.rri_metrics.RriResult.pm_acc_after) | ``Tensor["C", float32]`` post-view point-to-mesh error, in square metres. | | [pm_comp_after](#aria_nbv.rri_metrics.RriResult.pm_comp_after) | ``Tensor["C", float32]`` post-view mesh-to-point error, in square metres. | | [fscore_tau](#aria_nbv.rri_metrics.RriResult.fscore_tau) | Optional ``Tensor["C ...", float32]`` per-candidate F-scores at configured thresholds. | #### Methods | Name | Description | | --- | --- | | [to_serializable](#aria_nbv.rri_metrics.RriResult.to_serializable) | Serialize tensors into a cache-friendly CPU payload without changing candidate order. | | [from_serializable](#aria_nbv.rri_metrics.RriResult.from_serializable) | Reconstruct one candidate-aligned result on a requested device. | | [to](#aria_nbv.rri_metrics.RriResult.to) | Return a copy with every present tensor moved to ``device``. | ##### to_serializable { #aria_nbv.rri_metrics.RriResult.to_serializable } ```python rri_metrics.RriResult.to_serializable() ``` Serialize tensors into a cache-friendly CPU payload without changing candidate order. ##### from_serializable { #aria_nbv.rri_metrics.RriResult.from_serializable } ```python rri_metrics.RriResult.from_serializable(payload, *, device) ``` Reconstruct one candidate-aligned result on a requested device. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |---------|-----------------------------------------------------|---------------------------------------------------------|------------| | payload | [dict](`dict`)\[[str](`str`), [Any](`typing.Any`)\] | Serialized payload produced by :meth:`to_serializable`. | _required_ | | device | [torch](`torch`).[device](`torch.device`) | Destination device for tensors. | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|---------------|---------------------------| | | \'RriResult\' | Reconstructed RRI result. | ##### to { #aria_nbv.rri_metrics.RriResult.to } ```python rri_metrics.RriResult.to(device) ``` Return a copy with every present tensor moved to ``device``. ## Functions | Name | Description | | --- | --- | | [compute_rri](#aria_nbv.rri_metrics.compute_rri) | Compute RRI from prepared before/after point-mesh distances. | ### compute_rri { #aria_nbv.rri_metrics.compute_rri } ```python rri_metrics.compute_rri(before, after, *, config=_DEFAULT_RRI_CONFIG) ``` Compute RRI from prepared before/after point-mesh distances. The caller owns evidence preparation, cropping, and fusion. This function owns only the differentiable reconstruction-improvement formula.