nvalchemi.training.distillation.InitialStructures#
- class nvalchemi.training.distillation.InitialStructures(dataset, *, max_atoms=None, max_edges=None, max_batch_size=None, recycle=False)[source]#
An
OrderedStructureSamplerthat a recipe can name.The sampler is the loop’s reference
InitialStructuresSource. This subclass addsto_spec_dict()andfrom_spec_dict(). They describe the sampler by the store its dataset reads, the budgets declared on it, and whether it recycles its rows. AnOnPolicyConfigholding it can therefore be written to a recipe and rebuilt from one. A streaming source has no stable position to serialize, so it omits both methods and stays runtime-only. Writing a recipe from a config that holds such a source raises an error that names it.Examples
>>> from nvalchemi.training.distillation import InitialStructures, WithinBudget >>> structures = InitialStructures(dataset, max_atoms=10_000) >>> state = structures.initial_batch() >>> fresh = structures.draw(limit=2, fits=WithinBudget(atoms=64)) >>> rebuilt = InitialStructures.from_spec_dict(structures.to_spec_dict())
A
draw()withon_miss="stop"— the backfill under a trajectory lifetime — stops at a row that does not fit the room left, since the room grows back to the declared budget as trajectories retire. A row larger than the declaredmax_atomsormax_edgeson its own never fits any room, so it is passed over with a warning instead of holding the position forever;oversized_rowsrecords it.- Parameters:
dataset (BatchDatasetProtocol)
max_atoms (int | None)
max_edges (int | None)
max_batch_size (int | None)
recycle (bool)
- draw(*, limit=None, fits=None, on_miss='stop')[source]#
Serve the next structures while they pass fits, past oversized rows.
- Parameters:
limit (int | None, optional) – Maximum number of structures to serve. Default
None(the rest of the shard).fits (FitPolicy | None, optional) – Policy called with the atom and edge totals the drawn structures would hold with each candidate included. Default
None(every structure fits).on_miss ({"stop", "skip"}, optional) – How the scan treats a candidate that does not fit, as in
draw(). Under"stop"a row larger than the declared budget on its own is passed over and warned about once, and never ends the draw. Default"stop".
- Returns:
Structures in row order, each stamped with its own
system_id.- Return type:
list[AtomicData]
- classmethod from_spec_dict(spec)[source]#
Rebuild the source that
to_spec_dict()described.- Parameters:
spec (Mapping[str, Any]) – Reference produced by
to_spec_dict().- Returns:
Source over the referenced store, opened at its first row.
- Return type:
- Raises:
pydantic.ValidationError – If spec carries a key no source accepts, names no store to read the structures from, or gives a budget that is not a positive count. It derives from
ValueError, so a caller that already reports a bad recipe reports this one the same way.
- property oversized_rows: frozenset[int]#
Dataset rows a stopping
draw()passed over as larger than the budget.
- to_spec_dict()[source]#
Return the JSON-ready reference by which a recipe names this source.
- Returns:
The store the structures are read from, the budgets the caller declared, and
recycle. The position is run state and belongs in a restart bundle instead. The rank shard is set by the launcher and belongs in neither.- Return type:
dict[str, Any]
- Raises:
ValueError – If the dataset holds its samples in memory, which no recipe can name.