ComfyUI-ContextualRepulsion

One node, instant batch diversity. Same prompt, wildly different images.

A ComfyUI custom node that increases batch diversity in Diffusion Transformer (DiT) models by applying repulsion to text conditioning embeddings during the denoising process.

Based on the paper "On-the-fly Repulsion in the Contextual Space for Rich Diversity in Diffusion Transformers" (SIGGRAPH 2026, arXiv:2603.28762).

The Problem

When generating multiple images with the same prompt (batch_size >= 2), diffusion models tend to produce very similar outputs — similar compositions, poses, styles, and colors. This is known as typicality bias.

The Solution

This node pushes text conditioning embeddings apart across the batch so each image is guided toward a different interpretation of the same prompt. The result: images that are diverse in composition and style while still faithfully following your prompt.

• No extra models or LoRAs needed
• No prompt engineering tricks
• Just plug in one node and increase your batch size

Supported Models

Model	Status	Notes
Anima DiT (animayume series)	✅ Tested	Fully supported and validated
SD3 / SD3.5	🔜 Coming soon	Architecture compatible, testing in progress
Flux	🔜 Coming soon	Architecture compatible, testing in progress
Other DiT models using c_crossattn	⚠️ Experimental	Should work in principle, not yet validated

We are actively expanding model support. Contributions and test reports are welcome!

Installation

Option 1: ComfyUI Manager (Recommended)

Search for ComfyUI-ContextualRepulsion in ComfyUI Manager and click Install.

Option 2: Manual

Clone into your ComfyUI custom_nodes directory:

cd ComfyUI/custom_nodes
git clone https://github.com/Hyun-Puer/ComfyUI-ContextualRepulsion.git

No additional dependencies required — uses only PyTorch (already included with ComfyUI).

Usage

1. Set batch_size >= 2 in the EmptyLatentImage node (e.g., 4)
2. Add the Contextual Repulsion (Diversity) node (found under model_patches)
3. Connect it between your model loader and the sampler:

Model Loader → [Contextual Repulsion] → KSampler → VAEDecode → Preview

That's it. You should immediately see more variety across your batch.

Parameters

Parameter	Default	Range	Description
repulsion_scale	0.1	0.0 – 5.0	How strongly embeddings are pushed apart. Start with 0.05 – 0.2 for subtle variation, 0.3 – 1.0 for strong diversity.
timestep_cutoff	0.35	0.0 – 1.0	Fraction of denoising steps during which repulsion is active. 0.35 = first 35% of steps.
gradient_steps	3	1 – 10	Number of gradient descent steps per denoising step. 1–3 is usually sufficient.

Quick Guide

Goal	Settings
Subtle variation	scale=0.1, cutoff=0.35, steps=3
Moderate diversity	scale=0.3, cutoff=0.35, steps=3
Maximum diversity	scale=0.5+, cutoff=0.5, steps=5
Disable (zero overhead)	scale=0.0

Tip: Increase repulsion_scale first. If you're still getting similar outputs, then raise timestep_cutoff. Getting artifacts? Lower both values.

How It Works

1. Intercepts the text conditioning embeddings before each model forward pass
2. Computes a cosine similarity kernel across all batch samples
3. Calculates the Vendi Score diversity loss (von Neumann entropy of the kernel)
4. Applies gradient descent to push embeddings apart, increasing angular separation
5. Only active during early denoising steps where global composition is determined

The repulsion gradient is normalized relative to embedding magnitude, so repulsion_scale behaves consistently regardless of model architecture or embedding dimensions. Only conditional embeddings are modified — unconditional embeddings are left unchanged so CFG works correctly.

References

• Paper: On-the-fly Repulsion in the Contextual Space for Rich Diversity in Diffusion Transformers
• Project page: contextual-repulsion.github.io

License

MIT