nvalchemi.gen.GenerationPipeline#

class nvalchemi.gen.GenerationPipeline(*, stages)[source]#

Sequential composition of generation and batch-processing stages.

Parameters:

stages (Annotated[list[Any], MinLen(min_length=1)])

stages#

Ordered pipeline stages: AtomisticGenerator instances, dynamics engines, or Batch -> Batch callables.

Type:

list[Any]

Notes

Field-contract validation. Every AtomisticGenerator stage must declare required_inputs / outputs (set on the AtomisticGenerator directly or defaulted from the generating function’s attributes); construction raises otherwise. For each adjacent AtomisticGenerator -> AtomisticGenerator link, the downstream stage’s required_inputs must be covered by the upstream stage’s outputs: the dynamics link contract (AIMNet2 charges -> Ewald) applied to generation. Authors of custom generating functions own keeping their stage’s declaration in sync with what the function actually writes. Non-AtomisticGenerator stages carry no declarations and are not validated (their outputs are unknown at construction).

The first stage’s required_inputs describe its conditioning input and are not validated (the pipeline cannot know what a user’s inputs carries).

Sessions and compile. GenerationPipeline is a context manager: entry creates one dedicated CUDA stream (when the first AtomisticGenerator stage’s resolved device is CUDA) and shares it with every stage that follows the _stream convention – AtomisticGenerator stages with dedicated_stream set, and any other stage that accepts a pre-set stream (dynamics engines and fused stages honor it) – then enters each stage’s own session.

Stage calling convention. A stage with a run method (a dynamics engine or a fused stage) is driven to completion with stage.run(batch, **kwargs) – its own hooks fire inside its loop. Any other stage is called as stage(batch, **kwargs). A dynamics stage must carry its own exit criterion (convergence or n_steps); the fold offers no step budget of its own.

compile(**kwargs)[source]#

Compile every AtomisticGenerator stage’s generating function.

Per-stage compilation (see AtomisticGenerator.compile()); non-AtomisticGenerator stages are skipped. There is no whole-fold compile: the Batch plumbing and hook dispatch between stages would graph-break for no real capture. (Cross-stage tensor fusion is a separate research item.)

Parameters:

**kwargs (Any) – Forwarded to each stage’s AtomisticGenerator.compile().

Returns:

This instance, for fluent chaining.

Return type:

GenerationPipeline

model_config = {'arbitrary_types_allowed': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_GenerationPipeline__context)[source]#

Initialize session state.

Parameters:

_GenerationPipeline__context (Any)

Return type:

None

stream(inputs=None, *, max_batches=None, stage_kwargs=None)[source]#

Stream pipeline outputs, mirroring AtomisticGenerator.stream().

One fold per input item; inputs is the data source.

Parameters:
  • inputs (Any) – Iterable of inputs, or None for repeated unconditional draws.

  • max_batches (int | None) – Cap on batches yielded (None means unbounded).

  • stage_kwargs (Mapping[str, Any] | Sequence[Mapping[str, Any] | None] | None) – Per-call options addressed to stages, forwarded to __call__() on every fold.

Yields:

Any – One output per fold, exactly as produced.

Return type:

Iterator[Any]