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
GeneratingFunctiondriving generation. Required; the function owns the model when there is one.- Type:
- condition_func#
Optional
ConditionFunctionrun 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 ownconditionattribute. When neither is provided, no conditioning happens – the inputs pass through untouched and theBEFORE_CONDITION/AFTER_CONDITIONstages do not fire.- Type:
ConditionFunction | None
- device#
Optional execution device. When unset, the generating function’s
deviceattribute 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. WhenFalse, no stream is created even then.- Type:
bool
- hooks#
Generation hooks, each with a
GenerationStagestage. Validated at registration; seeHookRegistryMixin. 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_inputsattribute; required byGenerationPipelinefor link validation.- Type:
frozenset[str] | None
- outputs#
Batch fields this generator’s output carries (written or forwarded). Defaults from the generating function’s
outputsattribute.- 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()’snum_sampleskeyword.- Type:
int
- seed#
Optional base seed. Inside a session (
with gen:) onetorch.Generatoris seeded at entry and advanced per draw; outside a session each call derivestorch.Generator().manual_seed(seed + step_count). A per-callrng=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 viacompile(), or lazily at session entry. DefaultFalse.- Type:
bool
- compile_kwargs#
Keyword arguments forwarded to
torch.compile.- Type:
dict[str, Any]
Notes
generator_funcand the other callables are held as arbitrary types (arbitrary_types_allowed=True).AtomisticGeneratoris a context manager (with gen:): a session owns a dedicated CUDA stream (when the resolved device is CUDA anddedicated_streamis 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), setscompile_generate, and wrapsgenerator_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
Batchbuilds it through pydantic, which dynamo cannot trace – driver-level compile captures the tensor-pure prefix and breaks at materialization, andfullgraph=Truecannot 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 undertorch.compile; compile the model inside such functions directly instead.- Parameters:
**kwargs (Any) – Forwarded to
torch.compile.- Returns:
This instance, for fluent chaining.
- Return type:
- 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
stagevalues arriving as raw ints or name strings (e.g. deserialized from a spec payload) are coerced toGenerationStagebefore 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
Batchpath (hooks, device and field checks) when the sample is aBatch. Hooks fire at theGenerationStagepoints – each stage only when the step it brackets ran – and share oneGenerationContextfor the whole call.- Parameters:
inputs (Any) – The input for this call – a
Batch, another tensor container, orNonefor 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.
maskfor inpainting). One reserved kwarg,rng=, is consumed bysampleitself to override the session/seeded RNG for this call.
- Returns:
The generating function’s output: a
Batchon the contract path –AFTER_GENERATEhooks have run (post-filter, so possibly with fewer graphs than were sampled), and the device and declared-field checks passed. A zero-graphBatch(built viaempty()) passes through as-is (subsetting a batch to zero graphs still raisesIndexError). Any other container forfeits theBatchmachinery: returned untouched,AFTER_GENERATEhooks skipped, and it cannot feed dynamics stages in a pipeline.- Return type:
Any
- Raises:
TypeError – If the call declares
required_inputsbut the inputs cannot carry fields, orAFTER_GENERATEhooks leavectx.batchas something other than aBatch.ValueError – If
num_samplesresolves to less than 1, declared fields are missing from the inputs or the returned batch, or a device resolved (viadeviceorgenerator_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
Nonefor repeated unconditional draws.stream(None)withoutmax_batchesis an infinite iterator.- Parameters:
inputs (Any) – Iterable of inputs, or
Nonefor unconditional draws.max_batches (int | None) – Stop after this many batches;
Nonefollowsinputs. WheninputsisNoneandmax_batchesis unset the stream is unbounded.**kwargs (Any) – Per-call options forwarded to
sample().
- Yields:
Any – Each
sample()result exactly as produced: aBatchwhen the function returns one, otherwise the raw sample. A function may signal total rejection withempty()– that zero-graph batch is yielded, so rejection-aware consumers should checknum_graphs == 0. Retrying rejected draws is the consumer’s job.- Return type:
Iterator[Any]