"""INT8 quantisation of a small fully connected classifier, with a bit-exact integer model. The script builds a synthetic 8 x 8 "digit" dataset with a fixed seed, trains a linear classifier (64 inputs, 10 classes) in floating point, then quantises it the way an FPGA datapath runs it: * inputs: affine INT8, scale 1/255, zero point -128 (pixels are in [0, 1]) * weights: symmetric INT8 in [-127, 127], one scale per output channel * bias: INT32 with scale s_x * s_w[n]; the input zero point is folded into it * accumulator: INT32 sum of INT8 x INT8 products (what systolic_array.sv computes) * requantisation: fixed-point multiplier M0 (Q0.31) and a right shift (what requant.sv computes) Run: /Volumes/M2-Dev/conda/envs/toptech/bin/python int8_layer.py """ from __future__ import annotations from dataclasses import dataclass import math import numpy as np SEED = 2026 N_CLASSES = 10 SIDE = 8 NOISE = 0.2 # standard deviation of the added pixel noise # Seven-segment style glyphs on an 8 x 8 grid: segments a..g. _SEGMENTS = { "a": [(1, c) for c in range(2, 6)], "b": [(r, 6) for r in range(1, 4)], "c": [(r, 6) for r in range(4, 7)], "d": [(7, c) for c in range(2, 6)], "e": [(r, 1) for r in range(4, 7)], "f": [(r, 1) for r in range(1, 4)], "g": [(4, c) for c in range(2, 6)], } _DIGITS = ["abcdef", "bc", "abged", "abgcd", "fgbc", "afgcd", "afgedc", "abc", "abcdefg", "abcdfg"] def prototypes() -> np.ndarray: """Return the 10 clean 8 x 8 glyphs as an array of shape (10, 8, 8) with values 0 or 1.""" protos = np.zeros((N_CLASSES, SIDE, SIDE)) for digit, segs in enumerate(_DIGITS): for s in segs: for r, c in _SEGMENTS[s]: protos[digit, r, c] = 1.0 return protos def make_dataset(n_per_class: int, seed: int) -> tuple[np.ndarray, np.ndarray]: """Noisy, shifted copies of the glyphs. Returns x (n, 64) in [0, 1] and labels y (n,).""" rng = np.random.default_rng(seed) protos = prototypes() xs, ys = [], [] for digit in range(N_CLASSES): for _ in range(n_per_class): img = np.roll(protos[digit], shift=tuple(rng.integers(-1, 2, size=2)), axis=(0, 1)) img = img * rng.uniform(0.6, 1.0) + rng.normal(0.0, NOISE, size=img.shape) xs.append(np.clip(img, 0.0, 1.0).ravel()) ys.append(digit) order = rng.permutation(len(ys)) return np.array(xs)[order], np.array(ys)[order] def train_linear(x: np.ndarray, y: np.ndarray, epochs: int = 1500, lr: float = 0.5, seed: int = SEED) -> tuple[np.ndarray, np.ndarray]: """Softmax regression by full-batch gradient descent. Returns W (10, 64) and b (10,).""" rng = np.random.default_rng(seed) w = rng.normal(0.0, 0.01, size=(N_CLASSES, x.shape[1])) b = np.zeros(N_CLASSES) onehot = np.eye(N_CLASSES)[y] for _ in range(epochs): logits = x @ w.T + b logits -= logits.max(axis=1, keepdims=True) p = np.exp(logits) p /= p.sum(axis=1, keepdims=True) grad = (p - onehot) / len(y) w -= lr * (grad.T @ x + 1e-4 * w) b -= lr * grad.sum(axis=0) return w, b # ---------------------------------------------------------------- quantisation helpers def quantize_affine(x: np.ndarray, scale: float, zero_point: int) -> np.ndarray: """q = clip(round(x / scale) + zero_point, -128, 127), as int64.""" q = np.round(x / scale).astype(np.int64) + zero_point return np.clip(q, -128, 127) def quantize_weights_per_channel(w: np.ndarray) -> tuple[np.ndarray, np.ndarray]: """Symmetric INT8 per output row: s[n] = max|w[n]| / 127, q in [-127, 127].""" scale = np.abs(w).max(axis=1) / 127.0 q = np.clip(np.round(w / scale[:, None]), -127, 127).astype(np.int64) return q, scale def affine_params(lo: float, hi: float) -> tuple[float, int]: """Scale and zero point for an INT8 range that covers [lo, hi] and contains 0.""" lo, hi = min(lo, 0.0), max(hi, 0.0) scale = (hi - lo) / 255.0 zero_point = int(round(-128 - lo / scale)) return scale, zero_point def quantize_multiplier(m: float) -> tuple[int, int]: """Write 0 < m < 1 as m0 * 2^-(31 + shift) with 2^30 <= m0 < 2^31 and 0 <= shift <= 31.""" if not 0.0 < m < 1.0: raise ValueError(f"multiplier {m} outside (0, 1)") frac, exp = math.frexp(m) # m = frac * 2^exp, 0.5 <= frac < 1, exp <= 0 m0 = round(frac * (1 << 31)) if m0 == 1 << 31: # rounding reached 1.0: renormalise m0 //= 2 exp += 1 shift = -exp if not 0 <= shift <= 31: raise ValueError(f"multiplier {m} needs shift {shift}, outside 0..31") return m0, shift def requantize(acc: int, bias: int, m0: int, shift: int, zp: int, relu: bool = False) -> int: """Bit-exact model of requant.sv for one value (Python ints, so nothing overflows).""" s = int(acc) + int(bias) p = s * int(m0) r = (p + (1 << (30 + shift))) >> (31 + shift) # >> on Python ints is an arithmetic shift y = r + int(zp) lo = int(zp) if relu else -128 return max(lo, min(127, y)) def int_matmul(a: np.ndarray, b: np.ndarray) -> np.ndarray: """Exact integer matrix product in int64 (the reference for the systolic array).""" return a.astype(np.int64) @ b.astype(np.int64) def tiled_matmul(a: np.ndarray, b: np.ndarray, n: int) -> np.ndarray: """A (M x K) times B (K x P) computed in n x n output tiles, as an n x n array would.""" m, k = a.shape k2, p = b.shape assert k == k2 mp, pp = -(-m // n) * n, -(-p // n) * n # pad to whole tiles with zeros a_pad = np.zeros((mp, k), dtype=np.int64) b_pad = np.zeros((k, pp), dtype=np.int64) a_pad[:m], b_pad[:, :p] = a, b c = np.zeros((mp, pp), dtype=np.int64) for r in range(0, mp, n): for col in range(0, pp, n): c[r:r + n, col:col + n] = a_pad[r:r + n] @ b_pad[:, col:col + n] return c[:m, :p] @dataclass class QuantLayer: """Everything the FPGA needs for one INT8 fully connected layer.""" qw: np.ndarray # (10, 64) int weights sw: np.ndarray # (10,) weight scales sx: float zx: int bias_eff: np.ndarray # (10,) int32 bias with the input zero point folded in m0: np.ndarray # (10,) Q0.31 multipliers shift: np.ndarray # (10,) right shifts sy: float zy: int def quantize_layer(w: np.ndarray, b: np.ndarray, x_calib: np.ndarray) -> QuantLayer: sx, zx = 1.0 / 255.0, -128 qw, sw = quantize_weights_per_channel(w) qb = np.round(b / (sx * sw)).astype(np.int64) # sum_k qw (qx - zx) = sum_k qw qx - zx * sum_k qw: fold the second term into the bias. bias_eff = qb - zx * qw.sum(axis=1) y_calib = x_calib @ w.T + b sy, zy = affine_params(float(y_calib.min()), float(y_calib.max())) mults = [quantize_multiplier(sx * s / sy) for s in sw] m0 = np.array([m for m, _ in mults], dtype=np.int64) shift = np.array([s for _, s in mults], dtype=np.int64) assert np.all(np.abs(bias_eff) < 2**31) return QuantLayer(qw, sw, sx, zx, bias_eff, m0, shift, sy, zy) def run_int8(layer: QuantLayer, x: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """Integer inference. Returns (qx, acc, qy): INT8 inputs, INT32 accumulators, INT8 logits.""" qx = quantize_affine(x, layer.sx, layer.zx) acc = int_matmul(qx, layer.qw.T) # what the systolic array produces assert np.all(np.abs(acc) < 2**31) qy = np.empty_like(acc) for i in range(acc.shape[0]): for n in range(acc.shape[1]): qy[i, n] = requantize(acc[i, n], layer.bias_eff[n], layer.m0[n], layer.shift[n], layer.zy) return qx, acc, qy def build(seed: int = SEED) -> dict: """Train, quantise and evaluate. Returns the arrays the tests and figures use.""" x_train, y_train = make_dataset(150, seed) x_test, y_test = make_dataset(50, seed + 1) w, b = train_linear(x_train, y_train) layer = quantize_layer(w, b, x_train) logits_f = x_test @ w.T + b qx, acc, qy = run_int8(layer, x_test) return { "w": w, "b": b, "layer": layer, "x_test": x_test, "y_test": y_test, "logits_f": logits_f, "qx": qx, "acc": acc, "qy": qy, "acc_float": float(np.mean(logits_f.argmax(axis=1) == y_test)), "acc_int8": float(np.mean(qy.argmax(axis=1) == y_test)), "agree": float(np.mean(qy.argmax(axis=1) == logits_f.argmax(axis=1))), } def main() -> None: r = build() lay = r["layer"] print(f"test samples: {len(r['y_test'])}") print(f"float accuracy: {r['acc_float']:.3f} int8 accuracy: {r['acc_int8']:.3f} " f"same class: {r['agree']:.3f}") print(f"input scale 1/255, zero point {lay.zx}") print(f"output scale {lay.sy:.5f}, zero point {lay.zy}") print(f"weight scales: {np.array2string(lay.sw, precision=5)}") m_real = lay.sx * lay.sw[0] / lay.sy print(f"channel 0: M = {m_real:.6e} -> m0 = {lay.m0[0]}, shift = {lay.shift[0]}") print(f"largest |accumulator| = {np.abs(r['acc']).max()}") if __name__ == "__main__": main()