1 lightning.finite_horizon.studies.matched_evidence
lightning.finite_horizon.studies.matched_evidence
Admit prospective matched QH learning evidence without reopening weights.
Runtime checkpoint loading authenticates actual tensors. Cold publication binds its retained fit and evaluation receipts through externally pinned archive bytes; it establishes reported observations, not resume compatibility or policy value. Physical scenes, rather than candidate/state/horizon rows, are uncertainty units.
1.1 Classes
| Name | Description |
|---|---|
| ArtifactRef | One archive-relative product and exact retained byte identity. |
| CellEvaluations | Final primary and validation-selected secondary checkpoint roles. |
| MatchedCellDisposition | Scientific availability independent of charged runtime attempts. |
| MatchedEvaluationIndex | Sealed evaluation bindings; absent cells remain explicitly unavailable. |
| MatchedSceneContrast | Joint-minus-score-only or model-minus-control paired physical scenes. |
| MatchedStudy | Immutable admitted dispositions, observations and conditional intervals. |
| OperationalSupportIdentity | Ordered materialized teacher support, including invalid actions. |
| RoleEvaluations | Canonical original-label H1 and operational-feasibility receipts. |
1.1.1 ArtifactRef
lightning.finite_horizon.studies.matched_evidence.ArtifactRef()One archive-relative product and exact retained byte identity.
1.1.1.1 Attributes
| Name | Description |
|---|---|
| path | Canonical archive-relative product path; absolute paths, traversal and noncanonical spellings reject |
| sha256 | Lowercase hexadecimal SHA-256 of exact retained product bytes, verified before decoding the |
1.1.2 CellEvaluations
lightning.finite_horizon.studies.matched_evidence.CellEvaluations()Final primary and validation-selected secondary checkpoint roles.
1.1.2.1 Attributes
| Name | Description |
|---|---|
| final | Primary fixed-successful-update-budget checkpoint evaluation pair, bound to the completed fit final |
| selected | Secondary validation-selected checkpoint evaluation pair, retaining its distinct selection/update |
1.1.3 MatchedCellDisposition
lightning.finite_horizon.studies.matched_evidence.MatchedCellDisposition(
cell,
seed,
arm,
disposition,
attempt_charged,
completed_result_admitted,
)Scientific availability independent of charged runtime attempts.
1.1.3.1 Attributes
| Name | Description |
|---|---|
| cell | Registered fit-arm/seed cell identity retained even when launch, fitting or evaluation did not |
| seed | Prespecified initialization seed identifying a paired arm comparison; results and intervals remain |
| arm | Registered score-only or joint objective arm; the declared feasibility-loss coefficient |
| disposition | Observed fit/evaluation availability status, including failed, interrupted, unlaunched or |
| attempt_charged | Whether launch or terminal evidence charges the prespecified runtime attempt, independently of |
| completed_result_admitted | True only after completed fit and both checkpoint-role evaluations pass support/source admission; |
1.1.4 MatchedEvaluationIndex
lightning.finite_horizon.studies.matched_evidence.MatchedEvaluationIndex()Sealed evaluation bindings; absent cells remain explicitly unavailable.
1.1.4.1 Attributes
| Name | Description |
|---|---|
| schema_version | Exact version-one sealed evaluation-index schema required before admitting any matched product. |
| protocol_sha256 | SHA-256 of frozen prospective matched-study protocol bytes; must match the independently loaded |
| evaluator_source_package_digest | Authenticated evaluator source-package identity shared by referenced evaluation products, distinct |
| constant | Constant-predictor validation control artifact on the same original-label physical-state/candidate |
| cells | Cell-name mapping to admitted final/selected evaluation pairs. Absent cells remain unavailable and |
1.1.5 MatchedSceneContrast
lightning.finite_horizon.studies.matched_evidence.MatchedSceneContrast(
seed,
role,
metric,
comparison,
scenes,
values,
mean,
ci95,
)Joint-minus-score-only or model-minus-control paired physical scenes.
1.1.5.1 Attributes
| Name | Description |
|---|---|
| seed | Fixed fit seed for this contrast; bootstrap uncertainty does not pool seeds or describe a seed |
| role | Checkpoint role final or selected, retaining fixed-budget primary versus validation-selected |
| metric | Compared metric identity: regret/MAE use recorded Q/reward units; operational BCE and Brier use |
| comparison | Signed left-minus-right comparison identity, such as joint_minus_score-only or an arm minus |
| scenes | Sorted paired physical-scene identities; each aligns one-to-one with values, after |
| values | Finite signed per-scene left-minus-right effects aligned with scenes, in metric units; scenes, |
| mean | Equal-physical-scene arithmetic mean of values in the same metric units; conditional on the fixed |
| ci95 | Exploratory paired physical-scene bootstrap 2.5/97.5 percentile endpoints in metric units, or None |
1.1.6 MatchedStudy
lightning.finite_horizon.studies.matched_evidence.MatchedStudy(
provenance_json,
cell_dispositions,
contrasts,
scene_observations,
state_dispositions,
feasibility_summary_json,
)Immutable admitted dispositions, observations and conditional intervals.
1.1.6.1 Attributes
| Name | Description |
|---|---|
| provenance_json | Detached immutable JSON of admitted fitting/evaluator/protocol/config/source bindings, the |
| cell_dispositions | Registered cell-order availability and attempt-charge records, retaining failed/unlaunched cells |
| contrasts | Admitted signed paired-scene contrasts, separately indexed by seed, checkpoint role, metric and |
| scene_observations | Detached rows ordered as (cell, seed, checkpoint_role, metric, physical_scene, value), after |
| state_dispositions | Audit rows ordered as (cell, checkpoint_role, scene_id, store_index, rollout_row_id, state_index, |
| feasibility_summary_json | Detached JSON of admitted cell/checkpoint-role candidate-pooled operational-teacher summaries, |
| provenance | Return a detached projection of the admitted provenance. |
1.1.7 OperationalSupportIdentity
lightning.finite_horizon.studies.matched_evidence.OperationalSupportIdentity()Ordered materialized teacher support, including invalid actions.
1.1.7.1 Attributes
| Name | Description |
|---|---|
| sha256 | SHA256 of canonical state/candidate/Boolean-teacher rows. |
| state_count | Number of realized recorded states, independent of candidate widths. |
| materialized_candidate_count | All real candidates; padding is excluded and invalid actions retained. |
| positive_candidate_count | Recorded operational-valid candidates within materialized support. |
1.1.8 RoleEvaluations
lightning.finite_horizon.studies.matched_evidence.RoleEvaluations()Canonical original-label H1 and operational-feasibility receipts.
1.1.8.1 Attributes
| Name | Description |
|---|---|
| h1 | Original-label H1 utility-evaluation artifact for this checkpoint role, retaining exact ordered |
| joint | Operational-feasibility and requested-horizon evaluation artifact for the same checkpoint role; its |
1.2 Functions
| Name | Description |
|---|---|
| admit_archived_matched_study | Admit sealed matched receipts and observations without checkpoint payloads. |
| operational_support_identity | Seal operational teacher support directly from admitted actor tensors. |
| validate_matched_exposure | Authenticate 40 exact TRAIN passes and canonical per-chain H1–H16 counts. |
| validate_matched_receipt_controls | Compare actual fitted controls with the sealed prospective scientific inputs. |
1.2.1 admit_archived_matched_study
lightning.finite_horizon.studies.matched_evidence.admit_archived_matched_study(
archive,
prefix,
)Admit sealed matched receipts and observations without checkpoint payloads.
Completed/evaluation-pending, failed, launched/interrupted and unlaunched dispositions survive publication. Only evaluated completed cells contribute comparisons. Archive acquisition authenticates all bytes first; the explicit current fit schema, scientific controls, source/cold/population/exposure and checkpoint/evaluation bindings are then verified before reductions.
1.2.2 operational_support_identity
lightning.finite_horizon.studies.matched_evidence.operational_support_identity(
chains,
)Seal operational teacher support directly from admitted actor tensors.
Use candidate_mask & step_mask rather than action_mask to preserve invalid-action classification observations. No predictions enter the seal. Chains and states retain canonical reader order. Only counts and a digest enter the protocol; candidate arrays stay in their original evidence owner.
1.2.3 validate_matched_exposure
lightning.finite_horizon.studies.matched_evidence.validate_matched_exposure(
protocol,
events,
coverage,
)Authenticate 40 exact TRAIN passes and canonical per-chain H1–H16 counts.
A successful update is one whole chain. Horizon queries are dependent supervision, never new physical-scene samples. Pairing requires identical exposure bytes across arms, checked separately by study admission.
1.2.4 validate_matched_receipt_controls
lightning.finite_horizon.studies.matched_evidence.validate_matched_receipt_controls(
payload,
protocol,
completed,
directory,
seed,
arm,
commissioning,
)Compare actual fitted controls with the sealed prospective scientific inputs.
Canonical fitting binds three contract hashes and ephemeral checkpoint paths. Other scientific controls are compared literally; the only arm difference is BCE weight. Run identity and observer paths do not alter the objective.