TRELLIS.2 Sampler Types and Parameters: FlowEulerSampler, CFG, and Guidance-Interval Explained

The TRELLIS.2 repository provides five distinct sampler implementations—FlowEulerSampler, FlowEulerCfgSampler, FlowEulerGuidanceIntervalSampler, ResumableSampler, and BalancedResumableSampler—each exposing specific parameters like sigma_min, guidance_strength, and guidance_interval to control noise scheduling, classifier-free guidance, and deterministic data loading.

The microsoft/TRELLIS.2 codebase implements a modular sampling backend for flow-matching networks used in 3D asset generation. Understanding the different sampler types and their parameters allows you to tune the denoising trajectory, apply conditional guidance, and manage distributed training pipelines effectively.

Flow-Matching Samplers: Core Architecture

All diffusion samplers in TRELLIS.2 inherit from the abstract base class Sampler defined in [trellis2/pipelines/samplers/base.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/base.py). The concrete implementations specialize Euler-style integration for the flow-matching formulation, with optional mixins adding classifier-free guidance (CFG) and time-interval gating.

FlowEulerSampler

The FlowEulerSampler class in [trellis2/pipelines/samplers/flow_euler.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/flow_euler.py) implements the base Euler integration without guidance.

• Key parameter: sigma_min: float — Determines the minimum noise scale in the schedule (\sigma(t) = \sigma_{\text{min}} + (1 - \sigma_{\text{min}}) \cdot t).
• Behavior: Repeatedly calls sample_once, converting the model’s velocity prediction to a noise-free prediction and stepping the latent variable forward.

FlowEulerCfgSampler

FlowEulerCfgSampler (also in [flow_euler.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/flow_euler.py)) mixes FlowEulerSampler with ClassifierFreeGuidanceSamplerMixin from [trellis2/pipelines/samplers/classifier_free_guidance_mixin.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/classifier_free_guidance_mixin.py).

• Additional parameters:
  • guidance_strength: float = 3.0 — Controls the strength of classifier-free guidance.
  • guidance_rescale: float = 0.0 — Optional rescaling factor to limit variance induced by CFG.
• Implementation: The _inference_model method runs the network twice (conditioned and unconditioned) and blends predictions according to guidance_strength.

FlowEulerGuidanceIntervalSampler

FlowEulerGuidanceIntervalSampler extends the CFG sampler with GuidanceIntervalSamplerMixin from [trellis2/pipelines/samplers/guidance_interval_mixin.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/guidance_interval_mixin.py).

• Additional parameter: guidance_interval: Tuple[float, float] = (0.0, 1.0) — Normalized time interval during which CFG is active.
• Logic: Inside the interval, the sampler applies the configured guidance_strength; outside the interval, it uses a neutral factor of 1.0 (no guidance).

Data Loading Samplers

For training pipelines, TRELLIS.2 provides deterministic, checkpointable samplers that work with PyTorch’s DataLoader.

ResumableSampler

Defined in [trellis2/utils/data_utils.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/utils/data_utils.py), ResumableSampler inherits from PyTorch’s Sampler class.

• Parameters: None explicit; requires a Dataset implementing a loads method.
• Purpose: Enables deterministic shuffling across distributed workers and allows training to resume from a checkpoint without altering the sampling order.

BalancedResumableSampler

BalancedResumableSampler subclasses ResumableSampler in the same file.

• Behavior: Balances batches across multiple domains (e.g., textures versus geometry) while preserving the resumable property. It asserts that the dataset provides a loads method.

Practical Usage Examples

All Euler-style samplers share the public .sample() method signature:

result = sampler.sample(
    model,                     # torch.nn.Module implementing the flow network

    noise,                     # initial latent noise tensor

    cond=cond_tensor,          # optional conditioning (e.g., text embedding)

    steps=50,                  # number of integration steps

    rescale_t=1.0,             # optional time-rescaling

    verbose=True,
)

The returned object exposes result.samples (final latent), result.pred_x_t (intermediate predictions), and result.pred_x_0 (denoised predictions at each step).

Basic Euler Sampling

from trellis2.pipelines.samplers.flow_euler import FlowEulerSampler
import torch

sampler = FlowEulerSampler(sigma_min=0.02)
out = sampler.sample(
    model=my_flow_model,
    noise=torch.randn(4, 8, 64, 64),
    steps=60,
    verbose=False,
)

latent = out.samples  # Final latent ready for decoding

Euler with Classifier-Free Guidance

from trellis2.pipelines.samplers.flow_euler import FlowEulerCfgSampler

cfg_sampler = FlowEulerCfgSampler(sigma_min=0.02)
out = cfg_sampler.sample(
    model=my_flow_model,
    noise=torch.randn(4, 8, 64, 64),
    cond=text_embedding,         # Positive conditioning

    neg_cond=negative_embedding,   # Negative conditioning

    guidance_strength=4.5,
    steps=50,
)

latent_cfg = out.samples

Euler with Guidance Interval

from trellis2.pipelines.samplers.flow_euler import FlowEulerGuidanceIntervalSampler

interval_sampler = FlowEulerGuidanceIntervalSampler(sigma_min=0.02)
out = interval_sampler.sample(
    model=my_flow_model,
    noise=torch.randn(4, 8, 64, 64),
    cond=text_embedding,
    neg_cond=negative_embedding,
    guidance_strength=3.0,
    guidance_interval=(0.4, 1.0),  # CFG active only after 40% of steps

    steps=50,
)

latent_interval = out.samples

Resumable Data Loading

from trellis2.utils.data_utils import BalancedResumableSampler
from torch.utils.data import DataLoader

train_dataset = MyDataset()  # Must implement .loads()

sampler = BalancedResumableSampler(dataset=train_dataset)
loader = DataLoader(train_dataset, sampler=sampler, batch_size=32)

for batch in loader:
    # Training loop can be paused/resumed without shuffling changes

    pass

Key Source Files

File	Description
[trellis2/pipelines/samplers/base.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/base.py)	Abstract Sampler base class
[trellis2/pipelines/samplers/flow_euler.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/flow_euler.py)	FlowEulerSampler, FlowEulerCfgSampler, FlowEulerGuidanceIntervalSampler
[trellis2/pipelines/samplers/classifier_free_guidance_mixin.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/classifier_free_guidance_mixin.py)	CFG blending logic
[trellis2/pipelines/samplers/guidance_interval_mixin.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/guidance_interval_mixin.py)	Time-gated guidance logic
[trellis2/utils/data_utils.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/utils/data_utils.py)	ResumableSampler and BalancedResumableSampler

Summary

• FlowEulerSampler provides pure Euler integration with a configurable sigma_min noise schedule.
• FlowEulerCfgSampler adds guidance_strength and guidance_rescale via the classifier-free guidance mixin.
• FlowEulerGuidanceIntervalSampler further accepts a guidance_interval tuple to limit CFG to specific time ranges.
• ResumableSampler and BalancedResumableSampler enable deterministic, checkpointable data loading for distributed training, requiring datasets to implement a loads method.
• All samplers expose a uniform .sample() interface returning latent outputs and intermediate predictions.

Frequently Asked Questions

What is the purpose of the sigma_min parameter in FlowEulerSampler?

The sigma_min parameter defines the minimum noise scale used in the sampling schedule (\sigma(t) = \sigma_{\text{min}} + (1 - \sigma_{\text{min}}) \cdot t). According to the source code in [flow_euler.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/flow_euler.py), this value controls how close the schedule starts to pure noise versus the data distribution, directly affecting the initial step size during Euler integration.

How does FlowEulerGuidanceIntervalSampler differ from FlowEulerCfgSampler?

While both samplers support classifier-free guidance, FlowEulerGuidanceIntervalSampler (implemented via GuidanceIntervalSamplerMixin in [guidance_interval_mixin.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/pipelines/samplers/guidance_interval_mixin.py)) accepts an additional guidance_interval tuple specifying the normalized time range (e.g., (0.4, 1.0)) during which guidance is active. Outside this interval, the sampler disables CFG by using a guidance factor of 1.0, allowing selective application of conditioning strength.

Why would I use ResumableSampler instead of PyTorch’s default Sampler?

ResumableSampler (defined in [data_utils.py](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/utils/data_utils.py)) is designed for deterministic training resumption. Unlike PyTorch’s default shuffling, it maintains a reproducible ordering across distributed workers and supports checkpointing via a loads interface on the dataset, ensuring that resuming training does not alter the data sampling sequence or introduce duplicate examples.

Can I use FlowEulerSampler without any conditioning?

Yes. The base FlowEulerSampler does not require conditioning inputs. It performs unconditional Euler integration on the noise tensor. Conditioning (and negative conditioning) becomes relevant only when using FlowEulerCfgSampler or FlowEulerGuidanceIntervalSampler, which override the inference logic to accept cond and neg_cond arguments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}