1 lightning.finite_horizon.diagnostics

lightning.finite_horizon.diagnostics

Finite-horizon diagnostic admission, checkpoint roles and evaluation.

1.1 Package guide

Diagnostics authenticate research evidence while keeping prediction horizon, recording cutoff and physical continuation separate. They do not publish an inference bundle or decide a campaign’s progression.

checkpoints.py binds receipts, selected/final roles and weight digests before loading.
evaluation.py evaluates fixed-label H1 and supported recursive residuals, and fits TRAIN-only constants.
history.py admits history schemas and controls; failed/incomplete telemetry stays explicit.
population.py preserves config/store/scene identity and slices a TRAIN root with an empty causal history.

QhExperiment owns lifecycle ordering, loader/device dispatch and publication. The neighboring selection.py owns closed policy and saved-epoch ranking. Campaigns in studies/ retain their protocols. Stored receipt admission never replays current trainer defaults. Support, action validity and padding remain separate masks; moving fitted-target losses are not policy returns.

Verification: test_qh_diagnostic_owners.py, test_qh_diagnostic_dispatch.py, test_qh_diagnostic_history.py, test_qh_diagnostic_experiment.py, test_qh_regret_checkpoint_selection.py and test_qh_commissioning.py.

Failure-time gradient observations reuse training_diagnostics.level: off retains the fail-fast guard without capture, basic records detached objective, support, prediction/target ranges and bounded chain identities, and detailed adds bounded state/horizon identities. Healthy attempts cache only detached, bounded tensor prefixes; reductions and device-to-host copies occur on failure. Sample summaries declare prefix support and original population sizes, and do not replace full scientific loss statistics. Invalid unscaled gradients record named parameters, counts and read-only precision/scaler state before clipping. The failure receipt binds gradient-failure-context.json by SHA-256; its typed reader rejects altered bytes. Capture/publication errors remain telemetry and must not replace the original fit exception; publication failures also attach exception notes when history is disabled. History counts completed module optimizer updates, retaining the last successful loss across skipped AMP attempts.

Interrupted-checkpoint analysis uses load_interrupted_checkpoint followed by evaluate_interrupted_checkpoint, independently of completed fit receipts. Admission authenticates the externally pinned original archive, frozen protocol, charged launch, failed terminal receipt and saved update/configuration, then reopens TRAIN and validation support. Cold and interrupted weights retain those roles and failed-attempt status. Evaluation rechecks validation identity and rechecks every loaded online/target parameter and buffer against the admitted tensor-state seal, then uses the same fixed-label H1 and phase-zero operational-teacher row producers as completed diagnostics. Its separate receipt binds the actual current evaluator source, rejecting a mismatched supplied digest. It grants no resume, deployment or completed-comparison status. Scene/recipe pairing, TRAIN-fitted controls and uncertainty remain study/reporting decisions. Verification: test_qh_interrupted_checkpoint.py, including completed-receipt byte parity and rejection before inference when population or update identity changes.

Fixed-label H1 evaluation defaults to CPU. Its explicit device="cuda" request loads authenticated checkpoint weights on CPU, admits the exact population, then transfers the model and complete chain batches for inference. GPU receipts record inference_device and evaluator_source_package_digest; CPU receipt fields remain unchanged. Candidate rows retain the same dtype, tie rules, support and sequential reductions after one detached device-to-host transfer per chain. Verification: test_qh_h1_device.py and the existing H1 reducer parity tests.

For fixed-checkpoint fitting diagnostics, explicitly select QhDiagnosticH1EvaluationRequest(population_role="train_diagnostic", ...). Selected and final ordinary-fit checkpoints retain their existing byte/role authentication; the requested complete TRAIN config, scene population, provenance, target descriptors and ordered store manifests must match the fit. This role does not slice the root canary or alter checkpoint selection. A TRAIN-fitted constant can use the same role only on an exact member of its reopened, authenticated training populations; scene overlap alone is insufficient. The existing constant guard against overlapping held-out scenes remains active. New in-sample receipts identify qh-diagnostic-h1-evaluation-v2, population_role="train_diagnostic" and evaluation_semantics="in_sample_full_train_original_labels_v1". Original test/validation and single-root population_role="train" canary receipts stay unchanged. All roles reuse original-label state rows, preserving unsupported outcomes, deterministic tie choices and candidate/state denominators. See test_qh_h1_train_diagnostic.py; no fitting is needed to evaluate these weights.

# lightning.finite_horizon.diagnostics { #aria_nbv.lightning.finite_horizon.diagnostics } `lightning.finite_horizon.diagnostics` Finite-horizon diagnostic admission, checkpoint roles and evaluation.  ## Package guide Diagnostics authenticate research evidence while keeping prediction horizon, recording cutoff and physical continuation separate. They do not publish an inference bundle or decide a campaign’s progression. - `checkpoints.py` binds receipts, selected/final roles and weight digests before loading. - `evaluation.py` evaluates fixed-label H1 and supported recursive residuals, and fits TRAIN-only constants. - `history.py` admits history schemas and controls; failed/incomplete telemetry stays explicit. - `population.py` preserves config/store/scene identity and slices a TRAIN root with an empty causal history. `QhExperiment` owns lifecycle ordering, loader/device dispatch and publication. The neighboring `selection.py` owns closed policy and saved-epoch ranking. Campaigns in `studies/` retain their protocols. Stored receipt admission never replays current trainer defaults. Support, action validity and padding remain separate masks; moving fitted-target losses are not policy returns. Verification: `test_qh_diagnostic_owners.py`, `test_qh_diagnostic_dispatch.py`, `test_qh_diagnostic_history.py`, `test_qh_diagnostic_experiment.py`, `test_qh_regret_checkpoint_selection.py` and `test_qh_commissioning.py`. Failure-time gradient observations reuse `training_diagnostics.level`: `off` retains the fail-fast guard without capture, `basic` records detached objective, support, prediction/target ranges and bounded chain identities, and `detailed` adds bounded state/horizon identities. Healthy attempts cache only detached, bounded tensor prefixes; reductions and device-to-host copies occur on failure. Sample summaries declare prefix support and original population sizes, and do not replace full scientific loss statistics. Invalid unscaled gradients record named parameters, counts and read-only precision/scaler state before clipping. The failure receipt binds `gradient-failure-context.json` by SHA-256; its typed reader rejects altered bytes. Capture/publication errors remain telemetry and must not replace the original fit exception; publication failures also attach exception notes when history is disabled. History counts completed module optimizer updates, retaining the last successful loss across skipped AMP attempts. Interrupted-checkpoint analysis uses `load_interrupted_checkpoint` followed by `evaluate_interrupted_checkpoint`, independently of completed fit receipts. Admission authenticates the externally pinned original archive, frozen protocol, charged launch, failed terminal receipt and saved update/configuration, then reopens TRAIN and validation support. Cold and interrupted weights retain those roles and failed-attempt status. Evaluation rechecks validation identity and rechecks every loaded online/target parameter and buffer against the admitted tensor-state seal, then uses the same fixed-label H1 and phase-zero operational-teacher row producers as completed diagnostics. Its separate receipt binds the actual current evaluator source, rejecting a mismatched supplied digest. It grants no resume, deployment or completed-comparison status. Scene/recipe pairing, TRAIN-fitted controls and uncertainty remain study/reporting decisions. Verification: `test_qh_interrupted_checkpoint.py`, including completed-receipt byte parity and rejection before inference when population or update identity changes. Fixed-label H1 evaluation defaults to CPU. Its explicit `device="cuda"` request loads authenticated checkpoint weights on CPU, admits the exact population, then transfers the model and complete chain batches for inference. GPU receipts record `inference_device` and `evaluator_source_package_digest`; CPU receipt fields remain unchanged. Candidate rows retain the same dtype, tie rules, support and sequential reductions after one detached device-to-host transfer per chain. Verification: `test_qh_h1_device.py` and the existing H1 reducer parity tests. For fixed-checkpoint fitting diagnostics, explicitly select `QhDiagnosticH1EvaluationRequest(population_role="train_diagnostic", ...)`. Selected and final ordinary-fit checkpoints retain their existing byte/role authentication; the requested complete TRAIN config, scene population, provenance, target descriptors and ordered store manifests must match the fit. This role does not slice the root canary or alter checkpoint selection. A TRAIN-fitted constant can use the same role only on an exact member of its reopened, authenticated training populations; scene overlap alone is insufficient. The existing constant guard against overlapping held-out scenes remains active. New in-sample receipts identify `qh-diagnostic-h1-evaluation-v2`, `population_role="train_diagnostic"` and `evaluation_semantics="in_sample_full_train_original_labels_v1"`. Original test/validation and single-root `population_role="train"` canary receipts stay unchanged. All roles reuse original-label state rows, preserving unsupported outcomes, deterministic tie choices and candidate/state denominators. See `test_qh_h1_train_diagnostic.py`; no fitting is needed to evaluate these weights.