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, for draw(). Either way, the initial batch is packed as one draw() call with a WithinBudget policy and on_miss="stop" would pack it. A backfill that fills the room a graduation freed passes its own policy with on_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_row counts positions in rows. A system_id is not a position: ids count only the structures the run has started, not the rows a policy passed over. next_system_id is therefore tracked separately from next_row.

A sampler built with recycle=True never reports itself exhausted. When its position reaches the end of the shard, it wraps to the front, and wraps counts how often that happened. The system_id numbers keep increasing across a wrap. One draw() 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 None puts no atom bound on it.

  • max_edges (int | None, optional) – Total stored edges the initial batch may hold. Default None puts no edge bound on it.

  • max_batch_size (int | None, optional) – Total structures the initial batch may hold. Default None puts no bound on the count. With all three None, 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 leaves next_row on 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 under on_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 status it graduated with. step() would keep such a structure frozen at exit_status, so its steps would move nothing.

Returns:

Initial batch, stamped with clean bookkeeping and numbered from next_system_id.

Return type:

Batch

Raises:

ValueError – If the sampler has nothing left to serve, or if the structure at next_row is 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, or world_size. One error names every missing key. A bundle written under the former cursor key 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_row: int#

Position in rows of the next structure served.

property next_system_id: int#

system_id stamped 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 the velocities and atomic_masses that 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:

Batch

Raises:

ValueError – If this sampler owns no rows at all.

property rank: int#

Rank whose shard rows holds; 0 until shard() runs.

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: rank r takes every world_size-th structure, starting at offset r. 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 next system_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 the rank and world_size of the shard they count in. The dataset, the declared budgets, and recycle are configuration, not state, so they are left out.

Return type:

dict[str, int]

property world_size: int#

Ranks the dataset was dealt across; 1 until shard() runs.

property wraps: int#

How often a recycling position has wrapped to the front of the shard.