Refresh OrbitQuant model cards

README.md

@@ -1,14 +1,51 @@
 ---
 base_model: Tongyi-MAI/Z-Image-Turbo
+license: apache-2.0
 tags:
 - orbitquant
 - quantized
 - diffusers
+- diffusion-transformer
 ---
 
 # Tongyi-MAI/Z-Image-Turbo OrbitQuant W2A4
 
-This is an OrbitQuant artifact generated from the source model listed above.
+This repository contains a compact OrbitQuant transformer-component artifact for the source Diffusers model listed above. It is intended to be loaded into the original pipeline, not used as a standalone Diffusers pipeline repository.
+
+OrbitQuant is a calibration-free post-training quantization method for image and video diffusion transformers. This artifact keeps the text encoders, VAE, embeddings, timestep MLP, and final heads in the source precision by default and replaces the transformer linear projections with OrbitQuant modules.
+
+## Usage
+
+Install the package from this repository, then load the base pipeline and patch its transformer component with this artifact:
+
+```python
+import torch
+from diffusers import DiffusionPipeline
+from huggingface_hub import snapshot_download
+from orbitquant import load_quantized_pipeline_component
+
+base_model = "Tongyi-MAI/Z-Image-Turbo"
+artifact_id = "WaveCut/Z-Image-Turbo-OrbitQuant-W2A4"
+
+artifact_dir = snapshot_download(artifact_id, repo_type="model")
+pipe = DiffusionPipeline.from_pretrained(
+    base_model,
+    torch_dtype=torch.bfloat16,
+)
+load_quantized_pipeline_component(
+    pipe,
+    artifact_dir,
+    component="transformer",
+    device="cuda",
+)
+pipe.to("cuda")
+
+result = pipe(
+    prompt="A precise product photo of a red ceramic mug on a wooden desk",
+)
+```
+
+For model-specific pipelines, you may replace `DiffusionPipeline` with the matching Diffusers class, such as `FluxPipeline`, `Flux2KleinPipeline`, `ZImagePipeline`, or `WanPipeline` when your Diffusers version provides it.
 
 ## Quantization
 
@@ -26,9 +63,24 @@ This is an OrbitQuant artifact generated from the source model listed above.
 - Block size policy: `largest_power_of_two_dividing_dim`
 - Codebook: `lloyd_max`
 - Codebook version: `1`
+- Quantized transformer modules: `238`
+- AdaLN INT4 modules: `32`
+- Skipped modules: `6`
 - Calibration data: none
 - Text encoders and VAE: left in source precision by default
 
+## Visual Comparison
+
+The following assets are stored in this artifact and compare the BF16 base generation against the OrbitQuant generation with the same prompt and seed.
+
+![assets/original_vs_orbitquant_z-image-native_seed0_W2A4_color-binding.webp](assets/original_vs_orbitquant_z-image-native_seed0_W2A4_color-binding.webp)
+
+![assets/original_vs_orbitquant_z-image-native_seed0_W2A4_counting.webp](assets/original_vs_orbitquant_z-image-native_seed0_W2A4_counting.webp)
+
+![assets/original_vs_orbitquant_z-image-native_seed0_W2A4_cyrillic-text-rendering.webp](assets/original_vs_orbitquant_z-image-native_seed0_W2A4_cyrillic-text-rendering.webp)
+
+![assets/original_vs_orbitquant_z-image-native_seed0_W2A4_english-text-rendering.webp](assets/original_vs_orbitquant_z-image-native_seed0_W2A4_english-text-rendering.webp)
+
 ## Source
 
 - Model: `Tongyi-MAI/Z-Image-Turbo`
@@ -36,6 +88,16 @@ This is an OrbitQuant artifact generated from the source model listed above.
 - Source license: `apache-2.0`
 - OrbitQuant paper: https://arxiv.org/abs/2607.02461
 
+## Artifact Files
+
+- `model.safetensors`: packed OrbitQuant/INT4 module tensors.
+- `quantization_config.json`: serialized OrbitQuant runtime settings.
+- `orbitquant_manifest.json`: source provenance, policies, module lists, and checksums.
+- `orbitquant_codebooks.safetensors`: Lloyd-Max codebooks.
+- `orbitquant_rotations.safetensors`: deterministic RPBH rotation metadata.
+
 ## Limitations
 
-The initial runtime may dequantize packed weights before BF16 matmul. Disk artifacts are compact; current CUDA/MPS kernels optimize selected activation codebook lookup/rescale stages and packed weight dequantization; full fused low-bit kernels are separate work.
+- This is a transformer-component artifact; load it into the source pipeline as shown above.
+- Runtime mode may dequantize packed weights before BF16 matmul. Disk artifacts are compact, while runtime VRAM depends on the selected backend.
+- Quality depends on the source model and bit setting. Very low-bit settings can degrade prompt following or visual detail.

SHA256SUMS

@@ -1,4 +1,4 @@
-a6adb8aac7ec6ed41f1f4c770511be9f3530e359e1689f79183277a812a01568  README.md
+7b22614723a9322935b2c9af7bab35bbef5c24489b06dfdba2101ee78ecb4de9  README.md
 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  assets/.gitkeep
 8c8731e445b7cefae4b0fb1aa5c716bc01b2c91f67e34d46bf6afc40a02aec0f  assets/original_vs_orbitquant_z-image-native_seed0_W2A4_color-binding.webp
 4a58042eadc55289dd18b1c0841e95dbd9a3f7ba4fa63178af43bfe4918ed8db  assets/original_vs_orbitquant_z-image-native_seed0_W2A4_counting.webp