Quantization Explorer

Back-to-back histograms for uniform mid-tread quantization. The top panel shows the original distribution of values; the bottom panel shows the same values after every entry snaps to one of 2^bits evenly spaced levels across range. Underneath, a mono readout prints max / mean / RMS error so the precision tax is visible at a glance — drag bits down and the smooth bell collapses into a handful of fat spikes; the max-error cell switches to cb-warning the moment any value misses its level.

Different from BitFieldExplorer — that one snaps a single number onto a bit-field row. This one buckets the entire distribution and aggregates the error.

Quantization · 4 bits16 levels · n = 1024

max error: 0.0666
mean |err|: 0.0339
RMS error: 0.0393

bits4 bits

Customize

Quantization

bits4 bits

range (± lo / hi)±1.0

Display

histogram bins24

show bits slider

Installation

npx shadcn@latest add https://craftbits.dev/r/quantization-explorer.json

Usage

import { QuantizationExplorer } from "@craft-bits/core";
 
<QuantizationExplorer values={weights} defaultBits={8} />

Drive bits externally:

<QuantizationExplorer
  values={weights}
  bits={bits}
  onBitsChange={setBits}
  range={[-2, 2]}
/>

Hide the slider for a purely declarative readout:

<QuantizationExplorer
  values={weights}
  bits={4}
  showBitsSlider={false}
/>

Anatomy

Uniform mid-tread quantizer. Every value is clipped to range and snapped to the nearest of 2^bits evenly spaced levels — the canonical post-training quantization recipe. The same nearest-level math is applied across the full input so the two histograms share an x-axis and the comparison reads top-to-bottom.
Shared y-axis for like-for-like comparison. Both panels are scaled to the same max(count) so a tall spike in the quantized panel is visibly taller than the matching spike upstairs — the collapse of mass onto a level grid is the teaching moment, and a per-panel rescale would hide it.
Three error readouts. Max absolute error is the worst-case ULP; mean absolute error is the bulk feel; RMS is what loss functions actually accumulate. The max cell switches to cb-warning when any error is non-zero so the "your bit budget isn't free" moment is visible without reading the digits.
Controlled or uncontrolled bits. bits plus onBitsChange for controlled, defaultBits for uncontrolled — the Radix idiom. The built-in slider is a real <input type="range"> so Tab / Arrow / Home / End all work for free; aria-valuetext spells out the level count.
SPRINGS.smooth for the bars. Histogram bars spring between heights when bits or values change; prefers-reduced-motion: reduce collapses every transition to an instant swap.

Props

Prop	Type	Default	Description
`values`	`readonly number[]`	required	Continuous, real-valued inputs to quantize. Non-finite entries are silently dropped.
`bits`	`number`	—	Controlled bit width, clamped to `[1, 12]`. Pair with `onBitsChange`.
`defaultBits`	`number`	`8`	Uncontrolled initial bit width.
`onBitsChange`	`(bits) => void`	—	Fires when the user drags the slider.
`range`	`readonly [number, number]`	`[-1, 1]`	`[lo, hi]` quantization range. Values outside saturate to the nearest endpoint.
`histogramBins`	`number`	`24`	Bin count for both histograms, clamped to `[8, 64]`.
`showBitsSlider`	`boolean`	`true`	Render the built-in bit-width slider.
`transition`	`Transition`	`SPRINGS.smooth`	Override the spring for histogram bar transitions.
`className`	`string`	—	Merged onto the root via `cn()`.

Accessibility

The outer element is role="figure" with an aria-labelledby heading and an aria-describedby aria-live="polite" summary that announces the bit width, level count, range, and all three error statistics whenever they change.
The SVG carries role="img" and inherits the same heading via aria-labelledby; decorative axis lines and tick labels are marked aria-hidden.
The bit-width slider is a native <input type="range"> with Arrow / Home / End keyboard support and an aria-valuetext that spells out the current level count.
Color is never the only signal: every readout has a textual label, and the max-error cell only switches to cb-warning as an emphasis on top of the always-visible numeric value.
Histogram bar animations respect prefers-reduced-motion: reduce and collapse to an instant swap when the user opts out.

Credits

Extracted from: craftingattention (app/src/lessons/primitives/viz/QuantizationExplorer.tsx). The source was a single-number-line viz bound to a hard-coded 8-weight set, an Explore / Predict mode strip, a 6-round quiz pool, narration heuristics, and the project's ModeStrip / TogglePill / ScoreDots / DoneCard / ChallengeBtn / FeedbackBadge chrome. The library version reframes the same teaching surface as a pure distribution-vs-quantization viz — arbitrary values, Radix-style controlled / uncontrolled bits, a configurable range and histogramBins, the built-in slider as the only interaction, and cb-accent / cb-warning / cb-fg-muted semantic tokens in place of the inline raw colour vars.