1 lightning.finite_horizon.diagnostics.evaluation

lightning.finite_horizon.diagnostics.evaluation

Verified diagnostic checkpoint loading and frozen scientific evaluation.

These transactions retain admitted population support, checkpoint roles and original reductions. QH residuals remain checkpoint-dependent diagnostics, not observed policy returns. Experiment composition supplies public loader and constant-fit callbacks so dispatch remains with QhExperiment.

1.1 Classes

Name	Description
QhDiagnosticH1ConstantFit	Scene-equal H1 constant bound to the training populations used to fit it.

1.1.1 QhDiagnosticH1ConstantFit

lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit(
    value,
    training_identity,
    training_identity_sha256,
)

Scene-equal H1 constant bound to the training populations used to fit it.

1.1.1.1 Attributes

Name	Description
value	Mean H1 reward after candidate, state, and scene-equal aggregation.
training_identity	Ordered config, provenance, descriptor, store-manifest, and scene identity per training dataset.
training_identity_sha256	Canonical digest binding both `value` and `training_identity`.

1.2 Functions

Name	Description
evaluate_diagnostic_h1	Retain original-label H1 predictions and state regret without fitting.
evaluate_diagnostic_horizons	Retain held-out objective residuals without claiming policy return.
evaluate_diagnostic_joint	Retain scene-identifiable QH residuals and operational probabilities.
evaluate_interrupted_checkpoint	Evaluate authenticated partial weights on their sealed validation scenes.
fit_h1_constant	Fit a scene-equal constant from original training H1 labels only.
q1_metrics	Report canonical state-balanced metrics and bounded supported Q1 spread.

1.2.1 evaluate_diagnostic_h1

lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_h1(
    request,
    *,
    checkpoint_loader,
    constant_fitter,
    implementation=None,
)

Retain original-label H1 predictions and state regret without fitting.

The checkpoint and diagnostic fit receipt are verified before use. The dataset configuration must equal the one bound for its explicit role; every realized state receives a row, including unsupported/non-finite outcomes. Candidate ties select the lowest admitted index. CUDA model and batch transfer follows population admission; GPU receipts additionally bind the inference device and current evaluator package digest. CPU receipt fields retain their original representation. Explicit train_diagnostic uses the complete ordinary-fit TRAIN population or an exact fitted-constant training population and emits a separately marked in-sample v2 receipt. Historical held-out and single-root canary receipts remain v1.

1.2.2 evaluate_diagnostic_horizons

lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_horizons(
    request,
    *,
    checkpoint_loader,
)

Retain held-out objective residuals without claiming policy return.

Recursive targets use the checkpoint’s online/target networks and the original factual rewards. A lower TD residual alone cannot establish counterfactual long-horizon ranking or reconstruction benefit.

1.2.3 evaluate_diagnostic_joint

lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_joint(
    request,
    *,
    checkpoint_loader,
    implementation,
)

Retain scene-identifiable QH residuals and operational probabilities.

Reopen and verify the fit-bound held-out population before inference. One canonical transaction supplies dense Q1 and either factual bounded queries or the versioned continuing schedule; its same online output supplies feasibility probabilities. Continuing evaluation uses phase 0. Targets depend on the checkpoint’s delayed network and are residual diagnostics, not observed optimal continuation labels. Every materialized candidate supplies its recorded binary action mask, including invalid actions; padding supplies no classification label.

1.2.4 evaluate_interrupted_checkpoint

lightning.finite_horizon.diagnostics.evaluation.evaluate_interrupted_checkpoint(
    admitted,
    *,
    dataset,
    output_receipt_path,
    evaluator_source_package_digest,
    practical_tie_band=0.0,
    device='cpu',
)

Evaluate authenticated partial weights on their sealed validation scenes.

The reference must come from load_interrupted_checkpoint. Reopening verifies full population/support before inference. The full loaded online/target parameter/buffer seal and actual evaluator implementation are rechecked. Fixed-label H1 and the recorded operational-teacher probabilities reuse the completed-evaluation row producers, preserving their masks and deterministic candidate ties. Continuing residuals retain phase-zero fitted targets; they are not policy values. Physical-scene/recipe pairing and uncertainty remain study-owner reductions of these rows, never pooled candidate inference.

This writes a fresh interrupted-evaluation receipt exclusively. The original failed attempt stays failed, and its cold/interrupted weight role cannot acquire selected/final or completed-comparison status through evaluation.

1.2.5 fit_h1_constant

lightning.finite_horizon.diagnostics.evaluation.fit_h1_constant(train)

Fit a scene-equal constant from original training H1 labels only.

Candidates average within state, states within scene, then scenes equally. This control uses no held-out or recursive return labels.

1.2.6 q1_metrics

lightning.finite_horizon.diagnostics.evaluation.q1_metrics(module, batch)

Report canonical state-balanced metrics and bounded supported Q1 spread.

Prediction spread uses explicit Q1 queries without changing factual budgets. All operands are selected on the declared dense-label mask before arithmetic. q1_loss is the decoder-specific horizon-one objective state mean: continuous Huber for regression, or cumulative threshold BCE for CORAL. Recursive horizons and optional pairwise/feasibility losses are excluded. The Q1-only canonical transaction makes no target-scorer query. Regression retains native_horizon1_state_mean_v2; CORAL identifies its loss as coral_threshold_horizon1_state_mean_v1. MAE and selected-action regret retain continuous Q units for both decoders. Saved readouts are not rewritten. A positive CORAL regression coefficient adds native-Q Huber to threshold BCE and reports coral_threshold_plus_native_huber_horizon1_state_mean_v1 with separate unweighted and weighted component means.

# lightning.finite_horizon.diagnostics.evaluation { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation } `lightning.finite_horizon.diagnostics.evaluation` Verified diagnostic checkpoint loading and frozen scientific evaluation. These transactions retain admitted population support, checkpoint roles and original reductions. QH residuals remain checkpoint-dependent diagnostics, not observed policy returns. Experiment composition supplies public loader and constant-fit callbacks so dispatch remains with QhExperiment. ## Classes | Name | Description | | --- | --- | | [QhDiagnosticH1ConstantFit](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit) | Scene-equal H1 constant bound to the training populations used to fit it. | ### QhDiagnosticH1ConstantFit { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit } ```python lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit( value, training_identity, training_identity_sha256, ) ``` Scene-equal H1 constant bound to the training populations used to fit it. #### Attributes | Name | Description | | --- | --- | | [value](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit.value) | Mean H1 reward after candidate, state, and scene-equal aggregation. | | [training_identity](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit.training_identity) | Ordered config, provenance, descriptor, store-manifest, and scene identity per training dataset. | | [training_identity_sha256](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.QhDiagnosticH1ConstantFit.training_identity_sha256) | Canonical digest binding both :attr:`value` and :attr:`training_identity`. | ## Functions | Name | Description | | --- | --- | | [evaluate_diagnostic_h1](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_h1) | Retain original-label H1 predictions and state regret without fitting. | | [evaluate_diagnostic_horizons](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_horizons) | Retain held-out objective residuals without claiming policy return. | | [evaluate_diagnostic_joint](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_joint) | Retain scene-identifiable QH residuals and operational probabilities. | | [evaluate_interrupted_checkpoint](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_interrupted_checkpoint) | Evaluate authenticated partial weights on their sealed validation scenes. | | [fit_h1_constant](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.fit_h1_constant) | Fit a scene-equal constant from original training H1 labels only. | | [q1_metrics](#aria_nbv.lightning.finite_horizon.diagnostics.evaluation.q1_metrics) | Report canonical state-balanced metrics and bounded supported Q1 spread. | ### evaluate_diagnostic_h1 { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_h1 } ```python lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_h1( request, *, checkpoint_loader, constant_fitter, implementation=None, ) ``` Retain original-label H1 predictions and state regret without fitting. The checkpoint and diagnostic fit receipt are verified before use. The dataset configuration must equal the one bound for its explicit role; every realized state receives a row, including unsupported/non-finite outcomes. Candidate ties select the lowest admitted index. CUDA model and batch transfer follows population admission; GPU receipts additionally bind the inference device and current evaluator package digest. CPU receipt fields retain their original representation. Explicit ``train_diagnostic`` uses the complete ordinary-fit TRAIN population or an exact fitted-constant training population and emits a separately marked in-sample v2 receipt. Historical held-out and single-root canary receipts remain v1. ### evaluate_diagnostic_horizons { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_horizons } ```python lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_horizons( request, *, checkpoint_loader, ) ``` Retain held-out objective residuals without claiming policy return. Recursive targets use the checkpoint's online/target networks and the original factual rewards. A lower TD residual alone cannot establish counterfactual long-horizon ranking or reconstruction benefit. ### evaluate_diagnostic_joint { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_joint } ```python lightning.finite_horizon.diagnostics.evaluation.evaluate_diagnostic_joint( request, *, checkpoint_loader, implementation, ) ``` Retain scene-identifiable QH residuals and operational probabilities. Reopen and verify the fit-bound held-out population before inference. One canonical transaction supplies dense Q1 and either factual bounded queries or the versioned continuing schedule; its same online output supplies feasibility probabilities. Continuing evaluation uses phase 0. Targets depend on the checkpoint's delayed network and are residual diagnostics, not observed optimal continuation labels. Every materialized candidate supplies its recorded binary action mask, including invalid actions; padding supplies no classification label. ### evaluate_interrupted_checkpoint { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.evaluate_interrupted_checkpoint } ```python lightning.finite_horizon.diagnostics.evaluation.evaluate_interrupted_checkpoint( admitted, *, dataset, output_receipt_path, evaluator_source_package_digest, practical_tie_band=0.0, device='cpu', ) ``` Evaluate authenticated partial weights on their sealed validation scenes. The reference must come from ``load_interrupted_checkpoint``. Reopening verifies full population/support before inference. The full loaded online/target parameter/buffer seal and actual evaluator implementation are rechecked. Fixed-label H1 and the recorded operational-teacher probabilities reuse the completed-evaluation row producers, preserving their masks and deterministic candidate ties. Continuing residuals retain phase-zero fitted targets; they are not policy values. Physical-scene/recipe pairing and uncertainty remain study-owner reductions of these rows, never pooled candidate inference. This writes a fresh interrupted-evaluation receipt exclusively. The original failed attempt stays failed, and its cold/interrupted weight role cannot acquire selected/final or completed-comparison status through evaluation. ### fit_h1_constant { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.fit_h1_constant } ```python lightning.finite_horizon.diagnostics.evaluation.fit_h1_constant(train) ``` Fit a scene-equal constant from original training H1 labels only. Candidates average within state, states within scene, then scenes equally. This control uses no held-out or recursive return labels. ### q1_metrics { #aria_nbv.lightning.finite_horizon.diagnostics.evaluation.q1_metrics } ```python lightning.finite_horizon.diagnostics.evaluation.q1_metrics(module, batch) ``` Report canonical state-balanced metrics and bounded supported Q1 spread. Prediction spread uses explicit Q1 queries without changing factual budgets. All operands are selected on the declared dense-label mask before arithmetic. ``q1_loss`` is the decoder-specific horizon-one objective state mean: continuous Huber for regression, or cumulative threshold BCE for CORAL. Recursive horizons and optional pairwise/feasibility losses are excluded. The Q1-only canonical transaction makes no target-scorer query. Regression retains ``native_horizon1_state_mean_v2``; CORAL identifies its loss as ``coral_threshold_horizon1_state_mean_v1``. MAE and selected-action regret retain continuous Q units for both decoders. Saved readouts are not rewritten. A positive CORAL regression coefficient adds native-Q Huber to threshold BCE and reports ``coral_threshold_plus_native_huber_horizon1_state_mean_v1`` with separate unweighted and weighted component means.