nvalchemi.dynamics.OrderedStructureSampler#
- class nvalchemi.dynamics.OrderedStructureSampler(dataset, *, max_atoms=None, max_edges=None, max_batch_size=None, recycle=False)[source]#
Structures served in dataset order from one position, for in-flight batching.
The reference
StructureSource, backed by a dataset. A run reads the sampler once to build the batch the first step propagates from. A driver layered on top then draws from it again to backfill each structure it graduates. Both reads advance the same position, so no structure is propagated twice within one pass over the rows. An unbudgeted sampler serves every row it owns as one batch, so the run has one trajectory per row. A budgeted sampler packs the initial batch while structures fit and leaves the remaining rows, in order, fordraw(). Either way, the initial batch is packed as onedraw()call with aWithinBudgetpolicy andon_miss="stop"would pack it. A backfill that fills the room a graduation freed passes its own policy withon_miss="skip".shard()narrows the sampler to the rows one rank owns. The rows are dealt strided and unpadded, so the shards are disjoint and no structure is propagated twice.next_rowcounts positions inrows. Asystem_idis not a position: ids count only the structures the run has started, not the rows a policy passed over.next_system_idis therefore tracked separately fromnext_row.A sampler built with
recycle=Truenever reports itself exhausted. When its position reaches the end of the shard, it wraps to the front, andwrapscounts how often that happened. Thesystem_idnumbers keep increasing across a wrap. Onedraw()reaches every row at most once, so a single call never serves two copies of one structure. Across calls there is no such guarantee: a trajectory that outlives a full pass over the shard shares the batch with a second copy of its structure.- Parameters:
dataset (BatchDatasetProtocol) – Structures, indexed in the order they are served.
max_atoms (int | None, optional) – Total atoms the initial batch may hold. Default
Noneputs no atom bound on it.max_edges (int | None, optional) – Total stored edges the initial batch may hold. Default
Noneputs no edge bound on it.max_batch_size (int | None, optional) – Total structures the initial batch may hold. Default
Noneputs no bound on the count. With all threeNone, the sampler is unbudgeted and serves every row it owns as one batch.recycle (bool, optional) – Whether the position wraps to the front of the shard when it reaches the end, instead of the sampler reporting itself exhausted. Default
False.
- Raises:
ValueError – If a budget is set and not positive.
Examples
>>> from nvalchemi.dynamics import OrderedStructureSampler, WithinBudget >>> sampler = OrderedStructureSampler(dataset, max_atoms=10_000) >>> batch = sampler.initial_batch() >>> fresh = sampler.draw(limit=2, fits=WithinBudget(atoms=64)) >>> sampler.next_row 6
- draw(*, limit=None, fits=None, on_miss='stop')[source]#
Serve the next structures while they pass fits.
- 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.
"stop"ends the draw and leavesnext_rowon the candidate; an initial batch is packed this way."skip"passes over the candidate and continues. A backfill uses"skip"to fill the room a graduation freed, so one oversized structure cannot block every refill behind it. Default"stop".
- Returns:
Structures in row order, each stamped with its own
system_id. Empty once the shard is exhausted, or once the first candidate misses underon_miss="stop". A recycling sampler wraps to the front of the shard instead of running out. One call still reaches every row at most once.- Return type:
list[AtomicData]
- property exhausted: bool#
Whether the shard has no structure left to hand out.
- initial_batch()[source]#
Return the batch the first step propagates from, advancing the position.
Any propagator bookkeeping the loaded structures carry is dropped, and this sampler installs fresh bookkeeping. A structure loaded from a store that a dynamics sink filled arrives with the
statusit graduated with.step()would keep such a structure frozen atexit_status, so its steps would move nothing.- Returns:
Initial batch, stamped with clean bookkeeping and numbered from
next_system_id.- Return type:
- Raises:
ValueError – If the sampler has nothing left to serve, or if the structure at
next_rowis larger than the declared budget.
- load_state_dict(state)[source]#
Resume this sampler at the position state recorded.
- Parameters:
state (Mapping[str, int]) – Bundle written by
state_dict()for the shard this sampler is already narrowed to.- Raises:
KeyError – If state lacks any of
next_row,wraps,next_system_id,rank, orworld_size. One error names every missing key. A bundle written under the formercursorkey is not read, so it raises too.ValueError – If state was written for another rank or another world size. Its position counts rows in a different shard.
- Return type:
None
- property next_system_id: int#
system_idstamped on the next structure handed out.
- probe()[source]#
Return the first row of the shard as a one-graph batch.
The row is loaded through the dataset’s own collation rather than read as an
AtomicData. The collation fills in thevelocitiesandatomic_massesthat a propagator reads but a store may not have kept.- Returns:
One-graph batch, for checks that must run before any compute is spent on the run.
- Return type:
- Raises:
ValueError – If this sampler owns no rows at all.
- property rows: tuple[int, ...]#
Dataset rows this sampler serves, in the order it serves them.
- shard(rank, world_size)[source]#
Narrow this sampler to the rows that rank rank of world_size owns.
distributed_shard()deals the rows strided: rankrtakes everyworld_size-th structure, starting at offsetr. The shards are disjoint, cover the dataset, and differ by at most one structure. The deal balances the number of structures, not the work, so sort the dataset by atom count when structure sizes differ widely. The shards are not padded, because a padded structure would be propagated twice. Sharding resets the position, its wrap count, and the nextsystem_id, so a sampler that has already run restarts from its first row instead of resuming.- Parameters:
rank (int) – Global rank claiming a shard.
world_size (int) – Number of ranks the dataset is dealt across. A single-rank run keeps the whole dataset, unchanged.
- Raises:
ValueError – If world_size is not positive or rank falls outside it.
- Return type:
None
- state_dict()[source]#
Return the position a restart resumes this sampler from.
- Returns:
next_row,wraps(how often the position has wrapped),next_system_id, and therankandworld_sizeof the shard they count in. The dataset, the declared budgets, andrecycleare configuration, not state, so they are left out.- Return type:
dict[str, int]
- property wraps: int#
How often a recycling position has wrapped to the front of the shard.