# How to Configure the Timestep Shift Parameter for Flow Matching Schedulers in LongLive

> Configure the timestep shift parameter in LongLive Flow Matching Schedulers via YAML or WanDiffusionWrapper to control noise distribution. Learn how to optimize your model training.

- Repository: [NVIDIA Research Projects/LongLive](https://github.com/NVlabs/LongLive)
- Tags: how-to-guide
- Published: 2026-05-24

---

**Set `model_kwargs.timestep_shift` in your YAML configuration or pass `timestep_shift` directly to `WanDiffusionWrapper` to control noise distribution in the `FlowMatchScheduler`.**

The **timestep shift parameter** controls how noise is distributed across diffusion timesteps in the NVlabs/LongLive flow-matching pipeline. This configuration value, exposed as `timestep_shift` in the Python API and `shift` internally within the scheduler, directly transforms the sigma schedule through a non-linear scaling operation defined in [`utils/scheduler.py`](https://github.com/NVlabs/LongLive/blob/main/utils/scheduler.py).

## Configuration Entry Points

LongLive exposes the timestep shift through three primary entry points:

**YAML Configuration** – Define `model_kwargs.timestep_shift` in training or inference config files. The loader in [`utils/config.py`](https://github.com/NVlabs/LongLive/blob/main/utils/config.py) (lines 30‑33) merges this value into `model_kwargs` via the `normalize_config` helper. Example location: [`configs/train_ar.yaml`](https://github.com/NVlabs/LongLive/blob/main/configs/train_ar.yaml) (lines 12‑15).

**Python API (Standard)** – Pass `timestep_shift` to the `WanDiffusionWrapper` constructor in [`utils/wan_5b_wrapper.py`](https://github.com/NVlabs/LongLive/blob/main/utils/wan_5b_wrapper.py) (lines 78‑84). This wrapper defaults to `8.0` if unspecified.

**Python API (Sequence Parallel)** – For distributed inference using `SPWanDiffusionWrapper5B`, set the parameter in [`pipeline/causal_diffusion_inference_sp.py`](https://github.com/NVlabs/LongLive/blob/main/pipeline/causal_diffusion_inference_sp.py) (lines 32‑36), which defaults to `5.0`.

## Technical Implementation

### FlowMatchScheduler Core Logic

The scheduler implementation in [`utils/scheduler.py`](https://github.com/NVlabs/LongLive/blob/main/utils/scheduler.py) (lines 6‑31) defines the transformation:

```python
class FlowMatchScheduler:
    def __init__(self, num_inference_steps=100, num_train_timesteps=1000,
                 shift: float = 3.0, sigma_max: float = 1.0,
                 sigma_min: float = 0.003 / 1.002, ...):
        self.shift = shift

```

During `set_timesteps`, the shift value transforms the raw sigma schedule:

```python
self.sigmas = self.shift * self.sigmas / (1 + (self.shift - 1) * self.sigmas)

```

This formula compresses or expands the sigma curve. A larger `shift` value stretches the schedule toward high-noise regions, causing the diffusion process to take larger steps early and finer steps later.

### Parameter Propagation Pipeline

Configuration values flow through the system in three stages:

1. **Config Loading** – [`utils/config.py`](https://github.com/NVlabs/LongLive/blob/main/utils/config.py) (lines 30‑33) copies `timestep_shift` from the YAML into the runtime `model_kwargs` dictionary.

2. **Wrapper Instantiation** – The wrapper classes forward the value to the scheduler constructor:

```python
self.scheduler = FlowMatchScheduler(
    shift=timestep_shift, sigma_min=0.0, extra_one_step=True
)

```

3. **Runtime Override** – Hydra command-line arguments like `+model_kwargs.timestep_shift=7.2` merge into the config before wrapper construction.

## Impact of Shift Values on Generation

The `timestep_shift` value determines the granularity of the diffusion process:

- **`1.0`** – No transformation applied; the scheduler uses a standard linear sigma schedule.
- **`> 1.0`** – Compresses sigma values toward the high-noise end (t=0), resulting in larger denoising steps early in the process and slower refinement later. Values between `4.0` and `8.0` are typical for video generation.
- **`< 1.0`** – Expands the low-noise region, yielding finer granularity at high timesteps (rarely used in practice).

Because LongLive uses flow-matching training with `denoising_loss_type: flow`, the shift parameter directly influences loss weighting across timesteps. Tuning this value allows explicit trade-offs between generation speed and output fidelity.

## Code Examples

### YAML Configuration (Training)

Define the parameter in your training config:

```yaml

# configs/train_ar.yaml

model_kwargs:
  model_name: Wan2.2-TI2V-5B
  timestep_shift: 5.0
  num_frame_per_block: 8
  local_attn_size: -1

```

### Command-Line Override

Override the config value at runtime using Hydra syntax:

```bash
python train.py \
  +model_kwargs.timestep_shift=7.2 \
  +model_kwargs.model_name=Wan2.2-TI2V-5B

```

### Direct Python Usage

Instantiate the wrapper directly with a custom shift value:

```python
from utils.wan_5b_wrapper import WanDiffusionWrapper

wrapper = WanDiffusionWrapper(
    model_name="Wan2.2-TI2V-5B",
    timestep_shift=4.5,
    is_causal=False,
)

# Verify the scheduler received the value

print("Shift:", wrapper.scheduler.shift)
print("Sigmas:", wrapper.scheduler.sigmas)

```

### Inspecting the Scheduler State

After construction, verify the effective schedule:

```python
print("Timesteps:", wrapper.scheduler.timesteps)
print("Sigma schedule shape:", wrapper.scheduler.sigmas.shape)

```

## Summary

- The **timestep shift** controls noise distribution via the formula `shift * sigmas / (1 + (shift - 1) * sigmas)` in [`utils/scheduler.py`](https://github.com/NVlabs/LongLive/blob/main/utils/scheduler.py).
- Set the value through `model_kwargs.timestep_shift` in YAML configs, command-line overrides, or direct constructor arguments to `WanDiffusionWrapper`.
- Default values differ by entry point: `3.0` (scheduler internal), `8.0` (standard wrapper), and `5.0` (sequence-parallel wrapper).
- Values greater than `1.0` compress the schedule toward high-noise timesteps, affecting the diffusion speed-fidelity trade-off.
- The parameter propagates through [`utils/config.py`](https://github.com/NVlabs/LongLive/blob/main/utils/config.py) (lines 30‑33) before reaching the scheduler instantiation in [`utils/wan_5b_wrapper.py`](https://github.com/NVlabs/LongLive/blob/main/utils/wan_5b_wrapper.py) (lines 78‑84).

## Frequently Asked Questions

### What is the default timestep shift value in LongLive?

The **default value depends on the entry point**. The `FlowMatchScheduler` class itself defaults to `3.0`, while `WanDiffusionWrapper` in [`utils/wan_5b_wrapper.py`](https://github.com/NVlabs/LongLive/blob/main/utils/wan_5b_wrapper.py) overrides this to `8.0`. For sequence-parallel inference using `SPWanDiffusionWrapper5B` in [`pipeline/causal_diffusion_inference_sp.py`](https://github.com/NVlabs/LongLive/blob/main/pipeline/causal_diffusion_inference_sp.py), the default is `5.0`.

### How does the timestep shift parameter affect video generation quality?

The **shift value alters the sigma schedule non-linearly**. Values above `1.0` concentrate sampling steps in the high-noise (early) phase of diffusion, which can improve motion coherence in video generation by allowing larger updates during noisy phases, while values closer to `1.0` provide more uniform step distribution.

### Can I change the timestep shift value for inference without modifying config files?

**Yes**, pass the value via Hydra command-line syntax when launching inference scripts: `+model_kwargs.timestep_shift=6.0`. This merges the override into the configuration dictionary processed by [`utils/config.py`](https://github.com/NVlabs/LongLive/blob/main/utils/config.py) before the scheduler is instantiated.

### Where is the shift parameter actually stored in the codebase?

The **parameter is stored as `self.shift`** inside the `FlowMatchScheduler` instance in [`utils/scheduler.py`](https://github.com/NVlabs/LongLive/blob/main/utils/scheduler.py) (line 10). It is passed during construction by the wrapper classes in [`utils/wan_5b_wrapper.py`](https://github.com/NVlabs/LongLive/blob/main/utils/wan_5b_wrapper.py) and [`pipeline/causal_diffusion_inference_sp.py`](https://github.com/NVlabs/LongLive/blob/main/pipeline/causal_diffusion_inference_sp.py), which read it from the `model_kwargs` dictionary prepared by [`utils/config.py`](https://github.com/NVlabs/LongLive/blob/main/utils/config.py).