nvalchemi.training.distillation.build_mixed_loader#

nvalchemi.training.distillation.build_mixed_loader(reference_dataset, replay_buffer, *, replay_ratio, batch_size, num_batches=None, shuffle=True, generator=None, seed=0)[source]#

Build a loader that draws a fixed reference/replay mixture in every batch.

The two sources are composed into a MultiDataset and drawn by a MultiDatasetBatchSampler. The ratio is resolved to whole samples of batch_size, so every batch has exactly the same composition, at a granularity of 1 / batch_size. For example, replay_ratio=0.25 and batch_size=8 give six reference and two replay samples every step. Rebuild the loader after every segment. The sampler reads the child dataset lengths once, at construction, so it never samples frames added later.

Parameters:
  • reference_dataset (BatchDatasetProtocol | None) – Reference dataset, typically a teacher-labeled store. None trains on generated data only and requires replay_ratio=1.0.

  • replay_buffer (ReplayBuffer) – Buffer of generated frames. When it is empty, the loader draws from the reference dataset only.

  • replay_ratio (float) – Fraction of every batch drawn from replay_buffer, in [0, 1].

  • batch_size (int) – Samples per batch across both sources.

  • num_batches (int | None, optional) – Batches per epoch, honored on every path, including the single-source ones. Default None uses the sampler’s "dataset_size" policy, or one pass over a single source.

  • shuffle (bool, optional) – Randomize sample order within each child and each batch. Default True.

  • generator (torch.Generator | None, optional) – Generator for reproducible mixing. A single-source loader without num_batches draws from the global RNG instead. Default None.

  • seed (int, optional) – Base seed of the batch sampler when it owns its generator. The sampler combines it with the epoch set on it. Default 0.

Returns:

Loader yielding Batch objects of the requested composition.

Return type:

DataLoader

Raises:

ValueError – If replay_ratio is outside [0, 1], if both sources are empty, if reference_dataset is None while replay_ratio < 1, if the two sources differ in batch levels, fields, a field’s dtype, or emission device, or if the ratio allocates no samples to one of them.

Examples

>>> from nvalchemi.training.distillation import build_mixed_loader
>>> loader = build_mixed_loader(
...     reference_dataset,
...     buffer,
...     replay_ratio=0.25,
...     batch_size=8,
...     num_batches=64,
... )

Notes

Collation is not a merge. append() drops a field that only one side holds, and zero-fills a whole level that only one side holds. Both sources must therefore carry the same schema, which is compared on a probe batch from each. That schema is the replay-frame contract: the structure, the propagator state that travels with it, and the teacher_* labels. It has none of the energy, forces, or stress fields the labeling hook strips. A reference dataset that carries plain reference labels is therefore rejected. Label it with label_dataset(), requesting the signals the propagator’s scorer produces. The sampler draws with replacement, so a buffer holding fewer frames than its allocation is oversampled.