Generative workflows: model-owning samplers#

The generative driver runs any callable that matches the GeneratingFunction protocol: (inputs=None, *, num_samples=1, rng=None, **kwargs) -> Batch.

In the model-owning sampler pattern, a callable object holds the trained model and implements __call__. The callable exposes metadata attributes such as device, required_inputs, and outputs, and packages raw coordinate arrays into a Batch. The driver reads these metadata attributes as defaults without managing model internals directly.

We walk through two sampling approaches: 1. Single-pass latent decoding with a GAN. 2. Iterative Euler integration with a diffusion model.

Both samplers return a Batch, matching the output contract needed for driver hooks, device checks, and pipeline chaining.

import torch

from nvalchemi.data import AtomicData, Batch
from nvalchemi.gen import AtomisticGenerator
from nvalchemi.models.gen import DemoDiffusionModel, DemoGANModel

Model-owning GAN sampler: single-pass decode#

Single-pass decoders implement the GeneratingFunction protocol directly.

We hold the model inside the sampler rather than handing it to the driver. Exposing required_inputs and outputs lets the driver and pipeline stages validate tensor fields without inspecting the model itself.

Packaging generated atoms into a Batch satisfies the output contract. Downstream stages, hooks, and dynamics can consume the output immediately.

class DemoGANGenerate:
    """Model-owning GAN sampler: draw a latent, decode it."""

    def __init__(self, model: DemoGANModel) -> None:
        self.model = model
        self.required_inputs = model.model_config.required_inputs
        self.outputs = model.model_config.outputs

    @property
    def device(self) -> torch.device:
        return next(self.model.parameters()).device

    def __call__(
        self,
        inputs: Batch | None = None,
        *,
        num_samples: int = 1,
        rng: torch.Generator | None = None,
        **kwargs,
    ) -> Batch:
        n = inputs.num_graphs if isinstance(inputs, Batch) else num_samples
        z = torch.randn(n, self.model.latent_dim, generator=rng, device=self.device)
        positions = self.model.decode(z).reshape(n, self.model.num_atoms, 3)
        numbers = torch.full((self.model.num_atoms,), 6, dtype=torch.long)
        return Batch.from_data_list(
            [AtomicData(positions=p, atomic_numbers=numbers) for p in positions]
        )

Model-owning diffusion sampler: iterative Euler loop#

Multi-step generation uses the same callable interface as single-pass decoding. From the driver’s perspective, the sampling algorithm is an internal detail.

Defaults for noise schedules and step counts live on the instance. Callers can override them on any sample call by passing keyword arguments.

class DemoDiffusionGenerate:
    """Model-owning diffusion sampler: a small EDM Euler loop."""

    def __init__(
        self,
        model: DemoDiffusionModel,
        *,
        num_steps: int = 4,
        sigma_max: float = 2.0,
        sigma_min: float = 0.01,
    ) -> None:
        self.model = model
        self.num_steps = num_steps
        self.sigma_max = sigma_max
        self.sigma_min = sigma_min
        self.required_inputs = model.model_config.required_inputs
        self.outputs = model.model_config.outputs

    @property
    def device(self) -> torch.device:
        return next(self.model.parameters()).device

    def __call__(
        self,
        inputs: Batch | None = None,
        *,
        num_samples: int = 1,
        rng: torch.Generator | None = None,
        **kwargs,
    ) -> Batch:
        num_steps = kwargs.pop("num_steps", self.num_steps)
        sigma_max = kwargs.pop("sigma_max", self.sigma_max)
        sigma_min = kwargs.pop("sigma_min", self.sigma_min)
        n = inputs.num_graphs if isinstance(inputs, Batch) else num_samples
        device = self.device
        sigmas = torch.linspace(sigma_max, sigma_min, num_steps + 1, device=device)
        x = torch.randn(n, self.model.num_atoms, 3, generator=rng, device=device)
        x = x * sigmas[0]
        for i in range(num_steps):
            s_cur, s_next = sigmas[i], sigmas[i + 1]
            drift = (x - self.model.forward(x, s_cur.expand(n))) / s_cur
            x = x + (s_next - s_cur) * drift
        numbers = torch.full((self.model.num_atoms,), 6, dtype=torch.long)
        return Batch.from_data_list(
            [AtomicData(positions=p, atomic_numbers=numbers) for p in x]
        )

Driving the sampler: sessions and reproduction#

AtomisticGenerator coordinates sampling, device transfers, and hooks.

Entering a with gan: session sets up the RNG state, creates a CUDA stream on GPU, and manages compiled model lifetimes. Repeated draws inside the session advance the RNG deterministically. Nothing here needs gradients, so both drivers set enable_inference_mode=True: sessions then run under torch.inference_mode and avoid autograd tracking.

gan = AtomisticGenerator(
    generator_func=DemoGANGenerate(DemoGANModel()), seed=42, enable_inference_mode=True
)

with gan:
    first = gan.sample(num_samples=4)
    second = gan.sample(num_samples=4)

print(
    f"GAN batch: {first.num_graphs} graphs, "
    f"{first.num_nodes_per_graph.tolist()} atoms each"
)
GAN batch: 4 graphs, [3, 3, 3, 3] atoms each

Driving the diffusion sampler: per-call overrides#

The driver setup looks identical across model families. We wrap the diffusion sampler just like the GAN.

Extra keyword arguments passed to sample() forward directly to the sampler. Here num_steps=8 overrides the default 4-step schedule for a single call.

diffusion = AtomisticGenerator(
    generator_func=DemoDiffusionGenerate(DemoDiffusionModel(), num_steps=4),
    seed=42,
    enable_inference_mode=True,
)

with diffusion:
    batch = diffusion.sample(num_samples=2, num_steps=8)  # per-call override

print(f"Diffusion batch: {batch.num_graphs} graphs at sigma_max=2.0")
Diffusion batch: 2 graphs at sigma_max=2.0

Batch input handling#

Passing a batch as the first argument provides input structures to the driver. If the sampler defines a condition attribute or the driver receives a condition_func, the driver runs that transform before generation; without one, the input batch passes directly to the callable. These demo samplers are unconditional: they read inputs.num_graphs and emit one structure per input graph. A genuinely conditional model would read the input structures’ features here instead.

conditioning = Batch.from_data_list(
    [
        AtomicData(
            positions=torch.rand(5, 3),
            atomic_numbers=torch.full((5,), 6, dtype=torch.long),
        )
        for _ in range(3)
    ]
)

with gan:
    conditioned = gan.sample(conditioning)

print(
    f"Conditional call: {conditioned.num_graphs} draws from {conditioning.num_graphs} inputs"
)
Conditional call: 3 draws from 3 inputs

Total running time of the script: (0 minutes 0.008 seconds)

Gallery generated by Sphinx-Gallery