Graph-mode convert — bake a calibrated model into quantized modules.
convert_fx is the graph-mode counterpart of
lucid.quantization.convert and the final step of the graph-mode
static-PTQ pipeline (prepare_fx → calibrate → convert_fx). It swaps
each observed float module for its quantized inference equivalent, quantizing
weights to int8 codes and folding the calibrated activation qparams into each
layer. Because prepare_fx already wrapped the quant boundaries, the
result is a plain, self-contained quantized model that both runs directly and
traces cleanly through lucid.compile — where the quantized graph fuses
into a single executable.
This is a thin pass-through over lucid.quantization.convert, so it
shares all of its behavior: MLX-backend routing of the Linear family to the
real weight-only quantized_matmul GEMM (~3.15x decode speed-up at
M = 1, ~3.55x smaller weights) when that backend is active, the
reference dequant path otherwise, and the same deep-copy-by-default contract.
Parameters
modelnn.Moduleprepare_fx and then run through calibration,
so its observed submodules carry frozen activation qparams.inplacebool= FalseTrue mutate and return model itself; if False (default)
convert a deep copy and leave the calibrated model intact.Returns
nn.ModuleThe converted, eval-mode quantized model — ready to run or hand to
lucid.compile.
Notes
- Delegates to
lucid.quantization.convert; the only reason to call this variant is symmetry withprepare_fx(the wrapping already happened at prepare time, so nothing extra is needed here). - Convert only after calibration — an uncalibrated model bakes in meaningless activation qparams.
- The MLX compute win lands in the inference / generation regime and fades
toward parity in compute-bound training GEMMs; force exact reference
numerics with
backends.quantized.engine = "reference".
Examples
>>> import lucid, lucid.nn as nn
>>> import lucid.quantization as Q
>>> model = nn.Sequential(nn.Linear(128, 64), nn.ReLU(), nn.Linear(64, 10))
>>> model.qconfig = Q.get_default_qconfig()
>>> prepared = Q.prepare_fx(model)
>>> for _ in range(8):
... _ = prepared(lucid.randn(32, 128))
>>> qmodel = Q.convert_fx(prepared)
>>> compiled = lucid.compile(qmodel) # single fused quantized graphSee Also
- lucid.quantization.prepare_fx—The graph-mode observer-insertion step.
- lucid.quantization.convert—The eager-mode bake step this delegates to.
- lucid.compile—Fuses the converted quantized graph into one executable.