nvalchemi.training.distillation.InitialStructures#

class nvalchemi.training.distillation.InitialStructures(dataset, *, max_atoms=None, max_edges=None, max_batch_size=None, recycle=False)[source]#

An OrderedStructureSampler that a recipe can name.

The sampler is the loop’s reference InitialStructuresSource. This subclass adds to_spec_dict() and from_spec_dict(). They describe the sampler by the store its dataset reads, the budgets declared on it, and whether it recycles its rows. An OnPolicyConfig holding 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() with on_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 declared max_atoms or max_edges on its own never fits any room, so it is passed over with a warning instead of holding the position forever; oversized_rows records 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:

InitialStructures

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.