nvalchemi.training.distillation.label_dataset#

nvalchemi.training.distillation.label_dataset(dataset, scorer, store, *, batch_size=32, device=None, resume=True, keep_neighbors=False, prefetch='auto')[source]#

Label dataset with teacher signals and persist the result to store.

Walks dataset in contiguous chunks of batch_size samples, scores each chunk with scorer, attaches every returned signal as a batch field, and writes the augmented chunk to a Zarr store holding the original fields plus the teacher fields, readable through the ordinary AtomicDataZarrReader / Dataset path.

Parameters:
  • dataset (BatchDatasetProtocol) – Source dataset; only __len__ and load_batches are used.

  • scorer (TeacherScorer) – Scorer producing the teacher signals for each chunk.

  • store (StoreLike) – Destination Zarr store: a path, a zarr store instance, or a dict.

  • batch_size (int, optional) – Number of samples scored per forward pass. Default 32.

  • device (torch.device | str | None, optional) – Device to move each chunk to before scoring. Default None (score on whatever device the dataset emits).

  • resume (bool, optional) – If True (default), an existing store is treated as a partial run: the first len(store) samples are skipped and labeling continues from there. A store already holding every sample is a no-op; one holding more samples than dataset has is refused. If False, an existing store is an error.

  • keep_neighbors (bool, optional) – If False (default), a source neighbor list is dropped rather than stored, because the cutoff it was built at lives on the batch and not in the store. True carries a sparse (COO) source list over; the dense tensors are dropped either way. Default False.

  • prefetch (bool | Literal["auto"], optional) – Whether to read each chunk while the previous one is scored and written. False reads, scores, and writes one chunk at a time. True reads one chunk ahead through the dataset’s fused-prefetch surface (prefetch_fused_batches / get_fused_batches), falling back to the sequential loop with a UserWarning when the dataset offers none. "auto" (default) reads the first two chunks sequentially and times the second one’s load against the scoring and writing of its chunk; when the load took at least half of that processing it reads ahead, then times the first chunk read entirely ahead against the sequential one per atom and falls back to sequential reads if reading ahead was not faster. A dataset without the surface stays sequential silently. Default "auto".

Returns:

Number of samples labeled by this call; 0 when a resumed store already covers the whole dataset.

Return type:

int

Raises:
  • ValueError – If batch_size is not positive, prefetch is not True, False, or "auto", scorer declares or returns a batch field outside the teacher_* namespace, store exists but cannot be read as an ALCHEMI Zarr store, resume is False and store exists, store holds soft-deleted samples or more samples than dataset has, store holds arrays that disagree about how many samples it contains, a teacher label does not hold one row per atom or per graph, a chunk carries a floating-point field in a dtype a store cannot hold, or a chunk would write a different field set, level, dtype, or row shape than the store holds.

  • TypeError – If scorer declares label_fields as a single string.

Examples

>>> from nvalchemi.training.distillation import label_dataset
>>> scorer = InProcessTeacherScorer(teacher, ["energy", "forces"])
>>> label_dataset(dataset, scorer, "labeled.zarr", batch_size=64)
1024

Notes

The first chunk defines the store schema, and every later chunk — on fresh and resumed runs alike — must write the same fields, levels, dtypes, and row shapes, since the writer would otherwise misalign, cast, or truncate labels silently. Each label is held to the chunk’s atom or graph count before it is attached, because the split into per-graph rows would otherwise drop whatever a scorer returned beyond it. Resuming assumes stored sample i is dataset sample i: soft-deleted samples, a store longer than the dataset, and a store whose arrays disagree with its committed sample count (what an interrupted append leaves) are refused, while drift within the dataset’s length is undetectable. Labels are attached with overwrite=True, so a scorer is held to the teacher_* namespace both by its declared label_fields and by every chunk it returns, to protect the reference fields it would otherwise replace.

Labels stored in float16 or float64 read back at the reading dataset’s positions dtype, because a dataset coerces every floating-point field it loads (check_fp_dtype_consistency()); the stored dtype governs the store’s size, not what training sees. Build the student’s neighbor list from the stored positions with a NeighborListHook at BEFORE_FORWARD.

Reading ahead overlaps the next chunk’s load with the current chunk’s scoring and write, so it saves up to one load per chunk when the store is slow to read (a network or object store, or shared storage) or when per-sample validation dominates the load. The dataset’s prefetch thread decodes and validates the chunk while the main thread launches the teacher’s kernels, and a dataset that targets a CUDA device also moves every sample there from that thread; on a fast local store the contention can cost more than the load it hides, and labeling runs a little slower than the sequential loop. "auto" therefore measures both forms on the first chunks rather than assuming; the per-chunk writes, resume bookkeeping, and store contents are the same in every mode. A dataset that emits host-resident chunks, with device passed here for the move, keeps the transfer on the main thread and reads ahead faster than one that transfers from the prefetch thread.