mflux-debugging

Diagnose MLX port divergences by comparing exported tensors against PyTorch reference runs.

2.4k|187|Updated Aug 10, 2024
One-click install
npx skills add https://github.com/mflux-community/mflux --skill mflux-debugging-mflux-community
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mflux-debugging
Source: https://github.com/mflux-community/mflux/tree/main/.cursor/skills/mflux-debugging
Command: npx skills add https://github.com/mflux-community/mflux --skill mflux-debugging-mflux-community

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Porting generative image models from PyTorch/diffusers to MLX often produces subtle numerical mismatches that are hard to locate. This Skill provides a repeatable export-then-compare workflow to prove numerical parity or isolate the exact layer where outputs diverge. ## Core Features & Use Cases - Export-then-compare workflow: Dump deterministic tensors from the PyTorch reference, load them in MLX, and compare with explicit rtol/atol thresholds. - RNG parity handling: Export exact initial latents from the reference and inject them into the MLX denoising loop, avoiding false mismatches from differing random generators. - Divergence checklist: Covers common causes such as NCHW vs NHWC layouts, broadcasting errors, dtype casting, RoPE details, and scheduler math. - Use Case: When an MLX-ported transformer produces different images than diffusers, export per-block hidden states from both sides, binary-search the forward path, and pinpoint the first diverging checkpoint. ## Quick Start Ask the AI to debug why the MLX model output diverges from the diffusers reference by exporting and comparing intermediate tensors.

Frequently Asked Questions about mflux-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug numerical parity between MLX and PyTorch models?▼

Export deterministic tensors from the PyTorch reference using np.savez or torch.save, then load them in MLX and compare shape, dtype, max_abs_diff, and max_rel_diff with explicit rtol/atol thresholds. Add earlier checkpoints to binary-search the forward path when a comparison fails.

Why do MLX and PyTorch outputs differ even with the same seed?▼

PyTorch and MLX use different random number generators, so matching integer seeds does not produce matching noise. Export the exact initial latents from the reference with torch.Generator and load them into the MLX run instead of relying on seed parity.

What tolerance should I use when comparing fp16 tensors?▼

Use atol=1e-2 and rtol=1e-2 for fp16/bf16 comparisons, and atol=1e-5, rtol=1e-5 for fp32. Always inspect actual tensor values like the first 10 elements, since summary statistics can hide systematic drift or sign flips.

What are common causes of divergence when porting diffusers models to MLX?▼

Common causes include NCHW vs NHWC layout mistakes, broadcasting scale or shift vectors on the wrong axis, silent fp32 upcasting in norms or softmax, RoPE reshape ordering, and scheduler timestep indexing or sigma schedule differences.

Should I run PyTorch reference comparisons on CPU or MPS?▼

Always run reference comparisons on MPS, not CPU, to avoid misleading behavior. Prefer bfloat16 over float16 on MPS for reference dumps, since float16 can produce NaNs.