README.md

---
base_model: fal/ideogram-v4-instant
base_model_relation: quantized
license: other
license_name: ideogram-4-non-commercial
license_link: https://huggingface.co/fal/ideogram-v4-instant/blob/main/LICENSE.md
library_name: diffusers
pipeline_tag: text-to-image
tags:
- orbitquant
- quantized
- diffusers
- diffusion-transformer
- ideogram4
- instant
- non-commercial
- w4a6
extra_gated_prompt: By requesting access, you acknowledge the Ideogram Non-Commercial Model Agreement linked above.
extra_gated_fields:
  I agree to use this model only as permitted by the Ideogram Non-Commercial Model Agreement: checkbox
---

# Ideogram 4 Instant — OrbitQuant W4A6

This is a compact OrbitQuant transformer-component artifact derived from
[`fal/ideogram-v4-instant`](https://huggingface.co/fal/ideogram-v4-instant).
It contains the single conditional Instant transformer only. The NF4 Qwen3-VL
text encoder, VAE, tokenizer, and scheduler are loaded from the pinned official
Ideogram components repository; the base and unconditional transformers from
that repository are not loaded.

> **Modified model and non-commercial license.** `model.safetensors` contains
> OrbitQuant-packed derivatives of the fal BF16 weights. This is not an official
> Ideogram or fal product and is not endorsed, approved, or validated by either
> organization. Use and redistribution are limited to the Ideogram 4
> Non-Commercial Model Agreement included as `LICENSE.md`.

## What is included

- Recipe: `W4A6` (`w4a6`)
- OrbitQuant: `v0.6.0` at `9bfa3be9a88dd7972bc8d055ad37e1210cc1a155`
- Source revision: `a548f3dc66285ea0da1ed299383a131f37dfcb6b`
- Components revision: `1874bc70267ba2c823a7239e1d70dd308c8d64dc`
- Universal policy coverage: `241` OrbitQuant
  projections, `34` AdaLN INT4 modules, and
  `4` BF16 skips
- Calibration data: none
- Artifact size: `4.726 GB`

## Install and load

The fal checkpoint was published before its single-branch Diffusers changes
landed upstream. Diffusers 0.39.0 still tries to access the absent
`unconditional_transformer`. This repository therefore includes a narrow,
idempotent compatibility patch that changes behavior only when that component
is `None` and preserves the native nonzero terminal sigma.

```bash
pip install "orbitquant[hf]==0.6.0" "diffusers==0.39.0" \
  "transformers>=5.13,<6" "bitsandbytes>=0.49" accelerate
hf download WaveCut/Ideogram-v4-Instant-OrbitQuant-W4A6 scripts/patch_diffusers_ideogram4_instant.py \
  --local-dir ./ideogram4-w4a6
python ./ideogram4-w4a6/scripts/patch_diffusers_ideogram4_instant.py
```

The default native packed runtime provisions its matching wheel on first use.
The optional Triton extra is not required for this load path and should only be
added when its Triton requirement is compatible with the installed PyTorch.

```python
import json
import torch
from diffusers import Ideogram4Pipeline, Ideogram4Transformer2DModel
from huggingface_hub import snapshot_download
from orbitquant.artifacts import load_orbitquant_artifact

artifact_dir = snapshot_download("WaveCut/Ideogram-v4-Instant-OrbitQuant-W4A6")
config = Ideogram4Transformer2DModel.load_config(
    "fal/ideogram-v4-instant",
    subfolder="transformer",
    revision="a548f3dc66285ea0da1ed299383a131f37dfcb6b",
)

old_dtype = torch.get_default_dtype()
torch.set_default_dtype(torch.bfloat16)
try:
    with torch.device("cuda"):
        transformer = Ideogram4Transformer2DModel.from_config(config)
finally:
    torch.set_default_dtype(old_dtype)

load_orbitquant_artifact(
    transformer,
    artifact_dir,
    device="cuda",
    runtime_mode="auto_fused",
    activation_kernel_backend="auto",
)
pipe = Ideogram4Pipeline.from_pretrained(
    "ideogram-ai/ideogram-4-nf4-diffusers",
    revision="1874bc70267ba2c823a7239e1d70dd308c8d64dc",
    transformer=transformer,
    unconditional_transformer=None,
    torch_dtype=torch.bfloat16,
).to("cuda")

caption = {
    "high_level_description": "A bold typographic poster centered on exact words.",
    "compositional_deconstruction": {
        "background": "Warm white paper with even studio lighting.",
        "elements": [{
            "type": "text",
            "text": "ORBIT QUANT",
            "desc": "Large crisp black and orange geometric lettering.",
        }],
    },
}
image = pipe(
    json.dumps(caption, ensure_ascii=False, separators=(",", ":")),
    height=1024,
    width=1024,
    num_inference_steps=8,
    mu=0.0,
    std=1.75,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("ideogram4-instant-orbitquant-w4a6.png")
```

Guidance arguments are intentionally omitted: fal distilled CFG into the
single conditional branch.

## Original vs OrbitQuant benchmark

Both sides use the exact same structured JSON prompt, seed, 1024×1024
resolution, 8 steps, `mu=0.0`, and `std=1.75`, generated back to back on one
host: a vast.ai NVIDIA RTX A6000 48 GB (GA102, the same silicon class as the
A40 used previously) with PyTorch `2.9.1+cu128`, CUDA 12.8, Diffusers
0.39.0, and OrbitQuant `0.7.0` with the native kernel
package provisioned (`orbitquant kernels-install`; dispatch: native_packed_matmul, triton_packed_adaln_int4).

| Metric | BF16 original | OrbitQuant W4A6 |
| --- | ---: | ---: |
| Transformer/artifact load | `8.976 s` | `36.406 s` |
| First generation | `19.185 s` | `31.798 s` |
| Hot median generation | `17.454 s` | `28.847 s` |
| Peak CUDA allocated | `26.287 GB` | `25.568 GB` |
| Nonempty 1024×1024 outputs | `10/10` | `10/10` |

Earlier cards showed OrbitQuant hot medians measured with OrbitQuant 0.6.0 on
a pod whose torch build (2.8.0) had no published native kernel variant, so
every layer silently used the slow generic path. OrbitQuant 0.7.0 both ships
that variant and degrades gracefully when provisioning is impossible; the
table above reflects the packed kernels actually running.

The timing and memory figures are measurements from this host, not universal
performance claims. Low-bit recipes can visibly change detail, composition,
or typography; inspect the paired matrix rather than relying on a single
aggregate score.

![BF16 original versus OrbitQuant W4A6](assets/image_generation_comparison_matrix.webp)

## Comparison prompt set

| # | Stress case | Seed | Exact required text |
| ---: | --- | ---: | --- |
| 1 | Fine-detail astrolabe | `41001` | - |
| 2 | Layered character composition | `41002` | - |
| 3 | Exact counting and choreography | `41003` | - |
| 4 | Dense color and object binding | `41004` | - |
| 5 | Nested spatial relationships | `41005` | - |
| 6 | Cinematic night-market panorama | `41006` | - |
| 7 | Editorial Latin typography | `41007` | ORBIT QUANT<br>DATA WITHOUT CALIBRATION |
| 8 | Russian Constructivist typography | `41008` | КВАНТОВАЯ ОРБИТА<br>МОСКВА 2049<br>КВАНТОВАНИЕ |
| 9 | Japanese typography and mixed style | `41009` | 量子の軌道<br>東京の未来 |
| 10 | Chinese typography, reflection, and occlusion | `41010` | 量子轨道<br>未来之城 |

<details>
<summary>Exact structured JSON captions</summary>

1. **Fine-detail astrolabe**: `{"high_level_description":"A museum-grade macro photograph of a single ornate brass astronomical clock with mechanically coherent detail.","compositional_deconstruction":{"background":"Black velvet with dramatic Rembrandt lighting and shallow atmospheric falloff.","elements":[{"type":"obj","desc":"One ornate brass astronomical clock covered with interlocking gears, engraved constellations, enamel moon phases, hair-thin hands, tiny screws, worn gilt edges, and dust caught in the mechanisms; extreme material detail, large-format photography."}]}}`
2. **Layered character composition**: `{"high_level_description":"A lacquered white android and an elderly watchmaker jointly repair a mechanical hummingbird in a crowded Art Nouveau workshop.","compositional_deconstruction":{"background":"Rain and a passing tram are visible through the workshop window; hundreds of tools and clock parts fill the midground under cinematic tungsten and cyan light.","elements":[{"type":"obj","desc":"A lacquered white android on the left, leaning toward the workbench with intricate but anatomically coherent hands."},{"type":"obj","desc":"An elderly watchmaker on the right, facing the android with a detailed expressive face and careful hands."},{"type":"obj","desc":"A mechanical hummingbird centered between them, held over the workbench; coherent mirror reflections and editorial realism."}]}}`
3. **Exact counting and choreography**: `{"high_level_description":"Exactly seven masked dancers perform on exactly seven separate illuminated platforms inside a flooded opera house.","compositional_deconstruction":{"background":"A vast baroque opera house with balconies reflected in dark water, floating candles, volumetric stage haze, and readable background architecture.","elements":[{"type":"obj","desc":"Exactly seven dancers and no extra people, one dancer per platform, alternating crimson and ivory costumes from left to right, each in a distinct pose; sharp theatrical photography."}]}}`
4. **Dense color and object binding**: `{"high_level_description":"An elaborate surreal fashion tableau with exactly three models and strict color-object pairings.","compositional_deconstruction":{"background":"A rococo greenhouse with rare orchids, patterned tile floor, and prismatic sunlight, rendered with magazine-cover precision.","elements":[{"type":"obj","desc":"The left model wears a cobalt-blue coat and holds a yellow glass sphere."},{"type":"obj","desc":"The center model wears a saffron dress and holds a green ceramic pyramid."},{"type":"obj","desc":"The right model wears an emerald suit and holds a red velvet cube; preserve every color-object pairing exactly."}]}}`
5. **Nested spatial relationships**: `{"high_level_description":"A meticulous isometric cutaway diorama of a vertical city with nested spatial relationships.","compositional_deconstruction":{"background":"Architectural-section drawing mixed with photoreal materials, dozens of tiny rooms, stairs and people, with a yellow airship passing behind the entire structure.","elements":[{"type":"obj","desc":"A glass greenhouse sits directly above a silver subway car."},{"type":"obj","desc":"A red fox stands inside the greenhouse beneath a hanging moon lamp."},{"type":"obj","desc":"A violinist waits below the subway platform; clean depth and unambiguous vertical ordering."}]}}`
6. **Cinematic night-market panorama**: `{"high_level_description":"A sweeping cinematic panorama of a rain-soaked floating night market at blue hour with deep focus and coherent perspective.","compositional_deconstruction":{"background":"A terraced megacity rises through mist beneath a storm, with hundreds of warm windows, wet reflections, steam, umbrellas, ropes and signage.","elements":[{"type":"obj","desc":"In the foreground, a chef plates translucent dumplings under a red silk canopy."},{"type":"obj","desc":"In the midground, children chase paper lanterns across narrow bridges while merchants unload exotic fruit from wooden boats; realistic faces, anamorphic highlights, documentary-level detail."}]}}`
7. **Editorial Latin typography**: `{"high_level_description":"A sophisticated Swiss International Style exhibition poster photographed behind slightly reflective museum glass.","compositional_deconstruction":{"background":"Strict modular grid, red, black and white screenprint, tiny registration marks, embossed paper fibers, dramatic gallery shadows, and no other text.","elements":[{"type":"text","text":"ORBIT QUANT","desc":"The exact large uppercase headline ORBIT QUANT in sharp geometric sans-serif letterforms."},{"type":"text","text":"DATA WITHOUT CALIBRATION","desc":"The exact smaller subtitle DATA WITHOUT CALIBRATION, crisp and correctly ordered."}]}}`
8. **Russian Constructivist typography**: `{"high_level_description":"A richly detailed Russian Constructivist science-fiction poster with crisp exact Cyrillic lettering.","compositional_deconstruction":{"background":"Diagonal red and black geometry on cream paper, a cosmonaut portrait, orbital diagrams, halftone grain, folded corners, layered ink, and no additional text.","elements":[{"type":"text","text":"КВАНТОВАЯ ОРБИТА","desc":"The exact dominant Cyrillic headline КВАНТОВАЯ ОРБИТА."},{"type":"text","text":"МОСКВА 2049","desc":"The exact subtitle МОСКВА 2049."},{"type":"text","text":"КВАНТОВАНИЕ","desc":"A small exact stamp reading КВАНТОВАНИЕ."}]}}`
9. **Japanese typography and mixed style**: `{"high_level_description":"An elaborate Japanese art magazine cover combining Edo woodblock printing with a futuristic Tokyo skyline.","compositional_deconstruction":{"background":"Giant indigo waves curl around glass towers, red-crowned cranes cross a gold moon, tiny pedestrians and trains fill the lower streets, with visible washi fibers and layered spot colors.","elements":[{"type":"text","text":"量子の軌道","desc":"The exact balanced vertical title 量子の軌道 in precise Japanese glyphs."},{"type":"text","text":"東京の未来","desc":"The exact subtitle 東京の未来 in a clean editorial layout."}]}}`
10. **Chinese typography, reflection, and occlusion**: `{"high_level_description":"A luxurious Chinese retro-futurist department-store window at night with exact typography, layered reflections, and deliberate occlusion.","compositional_deconstruction":{"background":"Multiple glass layers, silk textures, blue-and-white porcelain, passing bicycles, cinematic rain, and fine product-photography detail.","elements":[{"type":"obj","desc":"A curved chrome robot is partly occluded by peonies; the calligraphy and neon street reflect coherently across its body."},{"type":"text","text":"量子轨道","desc":"The exact gold title 量子轨道."},{"type":"text","text":"未来之城","desc":"The exact red subtitle 未来之城."}]}}`

</details>

## Quantization manifest

- Method: `orbitquant`
- Bits: `W4A6`
- Runtime mode: `auto_fused`
- Activation kernel backend: `auto`
- Weight quantization backend: `triton_cuda`
- Target policy: `universal`
- Rotation: `rpbh`, seed `0`
- Block size: `paper`
- Codebook: `lloyd_max` version `2`
- AdaLN policy: `int4_rtn_group64_bf16_activation`, group size `64`

## Files

- `model.safetensors`: packed OrbitQuant weights plus required BF16 state
- `quantization_config.json`, `orbitquant_manifest.json`, `model_index.json`
- `orbitquant_codebooks.safetensors`, `orbitquant_rotations.safetensors`
- `benchmark/`: paired raw timing/memory records and compact summaries
- `assets/image_generation_comparison_matrix.webp`: visible 10-prompt comparison
- `prompts.json`: exact structured captions, seeds, and inference settings
- `LICENSE.md`, `NOTICE`, `MODIFICATIONS.md`: license and derivative notices
- `SHA256SUMS`: checksums for the published tree

## Limitations

- Non-commercial use only under the included agreement.
- This is a transformer-component artifact, not a standalone pipeline.
- Source and components are gated; accept both upstream access agreements.
- Today the included Diffusers 0.39 compatibility patch is required for the
  fal Instant single-branch path. Remove it once equivalent upstream support is
  released and revalidated.
- W4A4 has the specialized CUDA fast path. Other named recipes use the generic
  packed runtime available in OrbitQuant and may have different speed tradeoffs.
- The matrix is native paired output evidence, not a GenEval/FID claim.

## References

- [Source model](https://huggingface.co/fal/ideogram-v4-instant)
- [Shared Ideogram components](https://huggingface.co/ideogram-ai/ideogram-4-nf4-diffusers)
- [OrbitQuant](https://github.com/iamwavecut/OrbitQuant)
- [OrbitQuant paper](https://arxiv.org/abs/2607.02461)