nvalchemi.gen.AtomisticGenerator#

class nvalchemi.gen.AtomisticGenerator(*, hooks=<factory>, step_count=0, generator_func, condition_func=None, device=None, dedicated_stream=True, required_inputs=None, outputs=None, num_samples=1, seed=None, enable_inference_mode=False, compile_generate=False, compile_kwargs=<factory>)[source]#

Generative inference driver: optionally condition the inputs, generate, optionally materialize to a Batch.

Parameters:
  • hooks (list[Hook])

  • step_count (Annotated[int, Ge(ge=0)])

  • generator_func (GeneratingFunction)

  • condition_func (ConditionFunction | None)

  • device (Annotated[device, BeforeValidator(func=~nvalchemi._serialization._wrap_custom_type.<locals>._before, json_schema_input_type=PydanticUndefined), PlainSerializer(func=str, return_type=PydanticUndefined, when_used=always)] | None)

  • dedicated_stream (bool)

  • required_inputs (frozenset[str] | None)

  • outputs (frozenset[str] | None)

  • num_samples (Annotated[int, Ge(ge=1)])

  • seed (int | None)

  • enable_inference_mode (bool)

  • compile_generate (bool)

  • compile_kwargs (dict[str, Any])

generator_func#

The GeneratingFunction driving generation. Required; the function owns the model when there is one.

Type:

GeneratingFunction

condition_func#

Optional ConditionFunction run before generation: maps the call’s raw inputs to the conditioned value the generating function is then called with. It prepares the request – it does not constrain what comes out. Takes precedence over the generating function’s own condition attribute. When neither is provided, no conditioning happens – the inputs pass through untouched and the BEFORE_CONDITION/AFTER_CONDITION stages do not fire.

Type:

ConditionFunction | None

device#

Optional execution device. When unset, the generating function’s device attribute is used. Bare "cuda" is resolved to the current GPU at construction, and that GPU remains fixed for this generator. If neither declares a device, no managed device or output-device check applies.

Type:

_SerializableOptionalDevice

dedicated_stream#

When True (default), entering a session creates a dedicated CUDA stream if the resolved device is CUDA. When False, no stream is created even then.

Type:

bool

hooks#

Generation hooks, each with a GenerationStage stage. Validated at registration; see HookRegistryMixin. Serialized as attribute-faithful class specs (each __init__ parameter read back from the same-named attribute).

Type:

list[Hook]

required_inputs#

Batch fields this generator’s input reads (empty means unconditional). Defaults from the generating function’s required_inputs attribute; required by GenerationPipeline for link validation.

Type:

frozenset[str] | None

outputs#

Batch fields this generator’s output carries (written or forwarded). Defaults from the generating function’s outputs attribute.

Type:

frozenset[str] | None

num_samples#

Independent draws requested per call, passed straight through to the generating function (per-entry vs total-draw semantics are the function’s own). Per-call override via sample()’s num_samples keyword.

Type:

int

seed#

Optional base seed. Inside a session (with gen:) one torch.Generator is seeded at entry and advanced per draw; outside a session each call derives torch.Generator().manual_seed(seed + step_count). A per-call rng= kwarg overrides both.

Type:

int | None

step_count#

Runtime counter of generation calls – incremented in a finally, so failed calls count too. Drives hook frequency gating. Excluded from serialization.

Type:

int

compile_generate#

Compile the generating function with torch.compile – immediately via compile(), or lazily at session entry. Default False.

Type:

bool

compile_kwargs#

Keyword arguments forwarded to torch.compile.

Type:

dict[str, Any]

Notes

generator_func and the other callables are held as arbitrary types (arbitrary_types_allowed=True).

AtomisticGenerator is a context manager (with gen:): a session owns a dedicated CUDA stream (when the resolved device is CUDA and dedicated_stream is set), a session-scoped RNG, lazy compilation, and context-manager hooks. See __enter__().

compile(**kwargs)[source]#

Compile the generating function with torch.compile.

Merges kwargs with compile_kwargs (values passed here win), sets compile_generate, and wraps generator_func. Calling again re-compiles with the new kwargs.

Only the generating function is compiled; hook dispatch runs eagerly because it builds data structures and would graph-break anyway. Note the boundary: a function returning a Batch builds it through pydantic, which dynamo cannot trace – driver-level compile captures the tensor-pure prefix and breaks at materialization, and fullgraph=True cannot work there at all. For real capture, compile the model inside the generating function and leave the driver eager. Non-tensor-pure generating functions will graph-break under torch.compile; compile the model inside such functions directly instead.

Parameters:

**kwargs (Any) – Forwarded to torch.compile.

Returns:

This instance, for fluent chaining.

Return type:

AtomisticGenerator

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid'}#

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

model_post_init(_AtomisticGenerator__context)[source]#

Bind the execution device, register hooks, and initialize run state.

Hook stage values arriving as raw ints or name strings (e.g. deserialized from a spec payload) are coerced to GenerationStage before registration.

Parameters:

_AtomisticGenerator__context (Any)

Return type:

None

sample(inputs=None, *, num_samples=None, **kwargs)[source]#

Generate samples for the given inputs.

Runs the per-call pipeline shown in the module docstring: condition (only if a condition callable resolved for the call), generate on the session’s CUDA stream, and the Batch path (hooks, device and field checks) when the sample is a Batch. Hooks fire at the GenerationStage points – each stage only when the step it brackets ran – and share one GenerationContext for the whole call.

Parameters:
  • inputs (Any) – The input for this call – a Batch, another tensor container, or None for unconditional generation. When a condition step resolved for the call it runs on this value first and the generating function receives the conditioned result; otherwise the input is forwarded untouched.

  • num_samples (int | None) – Per-call override for num_samples, passed straight through to the generating function.

  • **kwargs (Any) – Per-call options forwarded to the generating function (e.g. mask for inpainting). One reserved kwarg, rng=, is consumed by sample itself to override the session/seeded RNG for this call.

Returns:

The generating function’s output: a Batch on the contract path – AFTER_GENERATE hooks have run (post-filter, so possibly with fewer graphs than were sampled), and the device and declared-field checks passed. A zero-graph Batch (built via empty()) passes through as-is (subsetting a batch to zero graphs still raises IndexError). Any other container forfeits the Batch machinery: returned untouched, AFTER_GENERATE hooks skipped, and it cannot feed dynamics stages in a pipeline.

Return type:

Any

Raises:
  • TypeError – If the call declares required_inputs but the inputs cannot carry fields, or AFTER_GENERATE hooks leave ctx.batch as something other than a Batch.

  • ValueError – If num_samples resolves to less than 1, declared fields are missing from the inputs or the returned batch, or a device resolved (via device or generator_func.device) but the returned batch lives on a different device.

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

Iterate over inputs, calling sample() once per item.

Pass any iterable of inputs, or None for repeated unconditional draws. stream(None) without max_batches is an infinite iterator.

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

  • max_batches (int | None) – Stop after this many batches; None follows inputs. When inputs is None and max_batches is unset the stream is unbounded.

  • **kwargs (Any) – Per-call options forwarded to sample().

Yields:

Any – Each sample() result exactly as produced: a Batch when the function returns one, otherwise the raw sample. A function may signal total rejection with empty() – that zero-graph batch is yielded, so rejection-aware consumers should check num_graphs == 0. Retrying rejected draws is the consumer’s job.

Return type:

Iterator[Any]