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
MultiDatasetand drawn by aMultiDatasetBatchSampler. The ratio is resolved to whole samples of batch_size, so every batch has exactly the same composition, at a granularity of1 / batch_size. For example,replay_ratio=0.25andbatch_size=8give 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.
Nonetrains on generated data only and requiresreplay_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
Noneuses 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
Batchobjects of the requested composition.- Return type:
- Raises:
ValueError – If replay_ratio is outside
[0, 1], if both sources are empty, if reference_dataset isNonewhilereplay_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 theteacher_*labels. It has none of theenergy,forces, orstressfields the labeling hook strips. A reference dataset that carries plain reference labels is therefore rejected. Label it withlabel_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.