1 lightning.one_step

lightning.one_step

One-step VIN training admission, objective, and experiment lifecycle.

1.1 Package guide

This package owns one-step data admission, the CORAL training objective and Lightning lifecycle. The scorer in aria_nbv.vin receives actor-visible evidence; oracle labels in VinOracleBatch supply supervision. Full-shell finite-horizon replay belongs to finite_horizon.

1.2 Composition and ordering

AriaNBVExperimentConfig is the composition interface. setup_target() establishes seeds and output ownership, constructs the shared trainer, resolves checkpoint-aware module configuration, constructs the data module and admits the requested stage. It returns (trainer, module, datamodule). setup_target_and_run() delegates fit/validation/test to Lightning with the resolved checkpoint. run() dispatches configured training, binner fitting, Optuna, summary and config export modes. Resume and interruption recovery retain Lightning training state; they differ from QH inference-only bundle loading.

VinDataModule owns input admission and loader policy. VinLightningModule owns the fitted binner, ordinal loss, metrics and checkpoint state. Training validates that binner classes match the decoder. The batch mask and finite supervision/logits select supported rows; scorer coverage predictions remain diagnostic. Shared training machinery constructs the trainer, callbacks and optimizer configuration; task-specific losses stay here.

1.3 Supported workflows

The public command-line training path remains the one-step CORAL control:

cd aria_nbv
uv run nbv-train --help
uv run nbv-summary --help

AriaNBVExperimentConfig, VinDataModuleConfig, and VinLightningModuleConfig provide the corresponding config-as-factory Python surface.

from aria_nbv.lightning import AriaNBVExperimentConfig

experiment = AriaNBVExperimentConfig.model_validate(config_payload)
trainer, module, datamodule = experiment.setup_target()

1.3.1 Existing online and offline data sources

VinDataModuleConfig already owns both one-step input modes through its discriminated source field. Reuse this boundary instead of adding a parallel DataModule or training entry point:

kind = "online" selects VinOracleOnlineDatasetConfig, which streams raw EFM snippets through the existing Oracle label pipeline. It is iterable and requires num_workers = 0;
kind = "offline" selects VinOfflineSourceConfig, which reads immutable VIN stores. It is map-style and supports worker processes, shuffling, and optional padded multi-sample batches.

The canonical complete examples are online_only.toml and offline_only.toml. Both feed the same VinDataModule, VinOracleBatch, one-step Lightning module, and experiment lifecycle. Source construction belongs to the online Oracle pipeline or VIN store reader; Lightning owns stage admission and loader policy.

use_train_as_val reuses the training dataset only for bounded online diagnostics. It is not held-out evaluation. The source-union and worker constraints are guarded by test_vin_datamodule_sources.py.

1.4 Verification

Use the package’s public interface and the narrowest affected test:

data sources and batch collation;
resume, interruption and binner refitting;
CLI and Optuna.

Detailed field, tensor and failure contracts live in the linked source docstrings.

# lightning.one_step { #aria_nbv.lightning.one_step } `lightning.one_step` One-step VIN training admission, objective, and experiment lifecycle.  ## Package guide This package owns one-step data admission, the CORAL training objective and Lightning lifecycle. The scorer in `aria_nbv.vin` receives actor-visible evidence; oracle labels in `VinOracleBatch` supply supervision. Full-shell finite-horizon replay belongs to [finite_horizon](lightning.finite_horizon.qmd). ## Composition and ordering [AriaNBVExperimentConfig](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/aria_nbv/lightning/one_step/experiment.py) is the composition interface. `setup_target()` establishes seeds and output ownership, constructs the shared trainer, resolves checkpoint-aware module configuration, constructs the data module and admits the requested stage. It returns `(trainer, module, datamodule)`. `setup_target_and_run()` delegates fit/validation/test to Lightning with the resolved checkpoint. `run()` dispatches configured training, binner fitting, Optuna, summary and config export modes. Resume and interruption recovery retain Lightning training state; they differ from QH inference-only bundle loading. [VinDataModule](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/aria_nbv/lightning/one_step/datamodule.py) owns input admission and loader policy. [VinLightningModule](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/aria_nbv/lightning/one_step/module.py) owns the fitted binner, ordinal loss, metrics and checkpoint state. Training validates that binner classes match the decoder. The batch mask and finite supervision/logits select supported rows; scorer coverage predictions remain diagnostic. [Shared training machinery](lightning.training.qmd) constructs the trainer, callbacks and optimizer configuration; task-specific losses stay here. ## Supported workflows The public command-line training path remains the one-step CORAL control: ```sh cd aria_nbv uv run nbv-train --help uv run nbv-summary --help ``` `AriaNBVExperimentConfig`, `VinDataModuleConfig`, and `VinLightningModuleConfig` provide the corresponding config-as-factory Python surface. ```python from aria_nbv.lightning import AriaNBVExperimentConfig experiment = AriaNBVExperimentConfig.model_validate(config_payload) trainer, module, datamodule = experiment.setup_target() ``` ### Existing online and offline data sources `VinDataModuleConfig` already owns both one-step input modes through its discriminated `source` field. Reuse this boundary instead of adding a parallel DataModule or training entry point: - `kind = "online"` selects `VinOracleOnlineDatasetConfig`, which streams raw EFM snippets through the existing Oracle label pipeline. It is iterable and requires `num_workers = 0`; - `kind = "offline"` selects `VinOfflineSourceConfig`, which reads immutable VIN stores. It is map-style and supports worker processes, shuffling, and optional padded multi-sample batches. The canonical complete examples are [`online_only.toml`](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/.configs/online_only.toml) and [`offline_only.toml`](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/.configs/offline_only.toml). Both feed the same `VinDataModule`, `VinOracleBatch`, one-step Lightning module, and experiment lifecycle. Source construction belongs to the online Oracle pipeline or VIN store reader; Lightning owns stage admission and loader policy. `use_train_as_val` reuses the training dataset only for bounded online diagnostics. It is not held-out evaluation. The source-union and worker constraints are guarded by [`test_vin_datamodule_sources.py`](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_vin_datamodule_sources.py). ## Verification Use the package's public interface and the narrowest affected test: - [data sources](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_vin_datamodule_sources.py) and [batch collation](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_vin_batch_collate.py); - [resume](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_resume_checkpoint.py), [interruption](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_interrupt_checkpoint.py) and [binner refitting](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_binner_auto_refit.py); - [CLI](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_cli.py) and [Optuna](https://github.com/JanDuchscherer104/ARIA-NBV/blob/main/aria_nbv/tests/lightning/test_optuna_integration.py). Detailed field, tensor and failure contracts live in the linked source docstrings.