nvalchemi.gen.GeneratingFunction#

class nvalchemi.gen.GeneratingFunction(*args, **kwargs)[source]#

Callable that encapsulates a family-specific generation strategy.

A GeneratingFunction owns everything generation needs – including the model, when there is one (held as a closure or an attribute of a callable object) – samples from it, and returns the generated artifact.

Conditioning may live inside the function, or as a condition attribute the driver calls before generation (see below); with neither, the inputs pass through untouched as the first positional argument.

num_samples semantics are the function’s own (per-conditioning-entry draws vs an unconditional total); the driver passes its num_samples straight through.

rng is None unless the driver has a seed, a session, or a per-call rng= – handle None (torch sampling ops accept it). Outside a session the resolved RNG is CPU-resident even when generating on CUDA; inside a session it lives on the resolved device. When you draw on a device, make sure the generator matches it (e.g. torch.randn(..., generator=rng, device=...)).

Return a Batch: that is the output contract. The driver fires the AFTER_GENERATE hooks on it, validates its device and declared outputs, and pipelines compose it (including driving dynamics on it). Any other container is a fallback with real losses: sample() passes it through untouched, the AFTER_GENERATE hooks are skipped, and it cannot feed dynamics stages. Inside the function, a TensorDict survives torch.compile where arbitrary containers graph-break under compile_generate; convert it to a Batch before returning. Library-native sampling loops (e.g. PhysicsNeMo diffusion samplers) plug in through a thin adapter with this signature.

Optional attributes. A callable object (rather than a plain function) may carry attributes the AtomisticGenerator reads as defaults when the driver does not set them explicitly:

  • condition – a ConditionFunction mapping the call’s raw inputs to the conditioned value the function is then called with (e.g. tiling a conditioning Batch so each graph gets num_samples draws). The driver runs it between the BEFORE_CONDITION and AFTER_CONDITION dispatches, which fire only when a condition step is provided; an explicit driver condition_func takes precedence over this attribute. There is no default condition: functions implement their own per use case, binding any extra context in their closure.

  • device – a torch.device (or parseable device string), used when the driver’s device is unset.

  • required_inputs / outputs – batch-field declarations, used when the driver does not pass them at construction.