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

> Explore TRELLIS.2 sampler types like FlowEulerSampler and their parameters. Understand sigma_min, guidance_strength, and guidance_interval for advanced noise control.

- Repository: [Microsoft/TRELLIS.2](https://github.com/microsoft/TRELLIS.2)
- Tags: api-reference
- Published: 2026-08-04

---

**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)](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)](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/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)](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)](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)](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:

```python
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

```python
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

```python
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

```python
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

```python
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)](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)](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)](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)](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)](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/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/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/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.