feat: add support for the eta parameter to ancestral samplers

wbruna · wbruna · commit eb8095ccee80 · 2026-03-29T16:58:48.000-03:00
diff --git a/examples/cli/README.md b/examples/cli/README.md
@@ -109,15 +109,15 @@ Generation Options:
                                            medium
   --skip-layer-start <float>               SLG enabling point (default: 0.01)
   --skip-layer-end <float>                 SLG disabling point (default: 0.2)
-  --eta <float>                            eta in DDIM, only for DDIM and TCD (default: 0)
+  --eta <float>                            noise multiplier (default: 0 for ddim_trailing, tcd, res_multistep and res_2s; 1 for euler_a and dpm++2s_a)
   --flow-shift <float>                     shift value for Flow models like SD3.x or WAN (default: auto)
   --high-noise-cfg-scale <float>           (high noise) unconditional guidance scale: (default: 7.0)
   --high-noise-img-cfg-scale <float>       (high noise) image guidance scale for inpaint or instruct-pix2pix models (default: same as --cfg-scale)
   --high-noise-guidance <float>            (high noise) distilled guidance scale for models with guidance input (default: 3.5)
   --high-noise-slg-scale <float>           (high noise) skip layer guidance (SLG) scale, only for DiT models: (default: 0)
   --high-noise-skip-layer-start <float>    (high noise) SLG enabling point (default: 0.01)
   --high-noise-skip-layer-end <float>      (high noise) SLG disabling point (default: 0.2)
-  --high-noise-eta <float>                 (high noise) eta in DDIM, only for DDIM and TCD (default: 0)
+  --high-noise-eta <float>                 (high noise) noise multiplier (default: 0 for ddim_trailing, tcd, res_multistep and res_2s; 1 for euler_a and dpm++2s_a)
   --strength <float>                       strength for noising/unnoising (default: 0.75)
   --pm-style-strength <float>
   --control-strength <float>               strength to apply Control Net (default: 0.9). 1.0 corresponds to full destruction of information in init image
diff --git a/examples/common/common.hpp b/examples/common/common.hpp
@@ -1197,7 +1197,7 @@ struct SDGenerationParams {
              &sample_params.guidance.slg.layer_end},
             {"",
              "--eta",
-             "eta in DDIM, only for DDIM and TCD (default: 0)",
+             "noise multiplier (default: 0 for ddim_trailing, tcd, res_multistep and res_2s; 1 for euler_a and dpm++2s_a)",
              &sample_params.eta},
             {"",
              "--flow-shift",
@@ -1229,7 +1229,7 @@ struct SDGenerationParams {
              &high_noise_sample_params.guidance.slg.layer_end},
             {"",
              "--high-noise-eta",
-             "(high noise) eta in DDIM, only for DDIM and TCD (default: 0)",
+             "(high noise) noise multiplier (default: 0 for ddim_trailing, tcd, res_multistep and res_2s; 1 for euler_a and dpm++2s_a)",
              &high_noise_sample_params.eta},
             {"",
              "--strength",
diff --git a/examples/server/README.md b/examples/server/README.md
@@ -189,15 +189,15 @@ Default Generation Options:
                                            medium
   --skip-layer-start <float>               SLG enabling point (default: 0.01)
   --skip-layer-end <float>                 SLG disabling point (default: 0.2)
-  --eta <float>                            eta in DDIM, only for DDIM and TCD (default: 0)
+  --eta <float>                            noise multiplier (default: 0 for ddim_trailing, tcd, res_multistep and res_2s; 1 for euler_a and dpm++2s_a)
   --flow-shift <float>                     shift value for Flow models like SD3.x or WAN (default: auto)
   --high-noise-cfg-scale <float>           (high noise) unconditional guidance scale: (default: 7.0)
   --high-noise-img-cfg-scale <float>       (high noise) image guidance scale for inpaint or instruct-pix2pix models (default: same as --cfg-scale)
   --high-noise-guidance <float>            (high noise) distilled guidance scale for models with guidance input (default: 3.5)
   --high-noise-slg-scale <float>           (high noise) skip layer guidance (SLG) scale, only for DiT models: (default: 0)
   --high-noise-skip-layer-start <float>    (high noise) SLG enabling point (default: 0.01)
   --high-noise-skip-layer-end <float>      (high noise) SLG disabling point (default: 0.2)
-  --high-noise-eta <float>                 (high noise) eta in DDIM, only for DDIM and TCD (default: 0)
+  --high-noise-eta <float>                 (high noise) noise multiplier (default: 0 for ddim_trailing, tcd, res_multistep and res_2s; 1 for euler_a and dpm++2s_a)
   --strength <float>                       strength for noising/unnoising (default: 0.75)
   --pm-style-strength <float>
   --control-strength <float>               strength to apply Control Net (default: 0.9). 1.0 corresponds to full destruction of information in init image
diff --git a/src/denoiser.hpp b/src/denoiser.hpp
@@ -802,10 +802,10 @@ static sd::Tensor<float> sample_k_diffusion(sample_method_t method,
                 sd::Tensor<float> denoised = std::move(denoised_opt);
                 sd::Tensor<float> d        = (x - denoised) / sigma;
                 float sigma_up, sigma_down;
-                generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1]);
+                generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1], eta);
                 float dt                   = sigma_down - sigmas[i];
                 x += d * dt;
-                if (sigmas[i + 1] > 0) {
+                if (sigmas[i + 1] > 0 && sigma_up > 0.0f) {
                     x += sd::Tensor<float>::randn_like(x, rng) * sigma_up;
                 }
             }
@@ -883,7 +883,7 @@ static sd::Tensor<float> sample_k_diffusion(sample_method_t method,
                 }
                 sd::Tensor<float> denoised = std::move(denoised_opt);
                 float sigma_up, sigma_down;
-                generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1]);
+                generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1], eta);
                 auto t_fn                  = [](float sigma) -> float { return -log(sigma); };
                 auto sigma_fn              = [](float t) -> float { return exp(-t); };
 
@@ -903,7 +903,7 @@ static sd::Tensor<float> sample_k_diffusion(sample_method_t method,
                     x                           = (sigma_fn(t_next) / sigma_fn(t)) * (x) - (exp(-h) - 1) * denoised2;
                 }
 
-                if (sigmas[i + 1] > 0) {
+                if (sigmas[i + 1] > 0 && sigma_up > 0.0f) {
                     x += sd::Tensor<float>::randn_like(x, rng) * sigma_up;
                 }
             }
diff --git a/src/stable-diffusion.cpp b/src/stable-diffusion.cpp
@@ -2225,6 +2225,7 @@ void sd_sample_params_init(sd_sample_params_t* sample_params) {
     sample_params->scheduler                   = SCHEDULER_COUNT;
     sample_params->sample_method               = SAMPLE_METHOD_COUNT;
     sample_params->sample_steps                = 20;
+    sample_params->eta                         = INFINITY;
     sample_params->custom_sigmas               = nullptr;
     sample_params->custom_sigmas_count         = 0;
     sample_params->flow_shift                  = INFINITY;
@@ -2438,6 +2439,25 @@ static scheduler_t resolve_scheduler(sd_ctx_t* sd_ctx,
     return scheduler;
 }
 
+static float resolve_eta(sd_ctx_t* sd_ctx,
+                         float eta,
+                         enum sample_method_t sample_method) {
+    if (eta == INFINITY) {
+        switch(sample_method) {
+            case DDIM_TRAILING_SAMPLE_METHOD:
+            case TCD_SAMPLE_METHOD:
+            case RES_MULTISTEP_SAMPLE_METHOD:
+            case RES_2S_SAMPLE_METHOD:
+                 return 0.0f;
+            case EULER_A_SAMPLE_METHOD:
+            case DPMPP2S_A_SAMPLE_METHOD:
+                 return 1.0f;
+            default: ;
+        }
+    }
+    return eta;
+}
+
 struct GenerationRequest {
     std::string prompt;
     std::string negative_prompt;
@@ -2586,6 +2606,7 @@ struct GenerationRequest {
 struct SamplePlan {
     enum sample_method_t sample_method            = SAMPLE_METHOD_COUNT;
     enum sample_method_t high_noise_sample_method = SAMPLE_METHOD_COUNT;
+    float eta                                     = 0.f;
     int sample_steps                              = 0;
     int high_noise_sample_steps                   = 0;
     int total_steps                               = 0;
@@ -2597,6 +2618,7 @@ struct SamplePlan {
                const sd_img_gen_params_t* sd_img_gen_params,
                const GenerationRequest& request) {
         sample_method = sd_img_gen_params->sample_params.sample_method;
+        eta           = sd_img_gen_params->sample_params.eta;
         sample_steps  = sd_img_gen_params->sample_params.sample_steps;
         resolve(sd_ctx, &request, &sd_img_gen_params->sample_params);
     }
@@ -2644,6 +2666,8 @@ struct SamplePlan {
                                                                      sd_ctx->sd->version);
         }
 
+        eta = resolve_eta(sd_ctx, eta, sample_method);
+
         if (high_noise_sample_steps < 0) {
             for (size_t i = 0; i < sigmas.size(); ++i) {
                 if (sigmas[i] < moe_boundary) {
@@ -3123,7 +3147,7 @@ SD_API sd_image_t* generate_image(sd_ctx_t* sd_ctx, const sd_img_gen_params_t* s
                                                    latents.control_image,
                                                    request.control_strength,
                                                    request.guidance,
-                                                   request.eta,
+                                                   plan.eta,
                                                    request.shifted_timestep,
                                                    plan.sample_method,
                                                    plan.sigmas,

Original file line number	Diff line number	Diff line change
`@@ -802,10 +802,10 @@ static sd::Tensor<float> sample_k_diffusion(sample_method_t method,`
`802`	`802`	`sd::Tensor<float> denoised = std::move(denoised_opt);`
`803`	`803`	`sd::Tensor<float> d = (x - denoised) / sigma;`
`804`	`804`	`float sigma_up, sigma_down;`
`805`		`- generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1]);`
	`805`	`+ generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1], eta);`
`806`	`806`	`float dt = sigma_down - sigmas[i];`
`807`	`807`	`x += d * dt;`
`808`		`- if (sigmas[i + 1] > 0) {`
	`808`	`+ if (sigmas[i + 1] > 0 && sigma_up > 0.0f) {`
`809`	`809`	`x += sd::Tensor<float>::randn_like(x, rng) * sigma_up;`
`810`	`810`	`}`
`811`	`811`	`}`
`@@ -883,7 +883,7 @@ static sd::Tensor<float> sample_k_diffusion(sample_method_t method,`
`883`	`883`	`}`
`884`	`884`	`sd::Tensor<float> denoised = std::move(denoised_opt);`
`885`	`885`	`float sigma_up, sigma_down;`
`886`		`- generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1]);`
	`886`	`+ generate_ancestral_step(sigma_up, sigma_down, sigmas[i], sigmas[i + 1], eta);`
`887`	`887`	`auto t_fn = [](float sigma) -> float { return -log(sigma); };`
`888`	`888`	`auto sigma_fn = [](float t) -> float { return exp(-t); };`
`889`	`889`
`@@ -903,7 +903,7 @@ static sd::Tensor<float> sample_k_diffusion(sample_method_t method,`
`903`	`903`	`x = (sigma_fn(t_next) / sigma_fn(t)) * (x) - (exp(-h) - 1) * denoised2;`
`904`	`904`	`}`
`905`	`905`
`906`		`- if (sigmas[i + 1] > 0) {`
	`906`	`+ if (sigmas[i + 1] > 0 && sigma_up > 0.0f) {`
`907`	`907`	`x += sd::Tensor<float>::randn_like(x, rng) * sigma_up;`
`908`	`908`	`}`
`909`	`909`	`}`