# /// script
# requires-python = ">=3.10"
# dependencies = ["numpy"]
# ///
# Copyright (c) 2026 Aayush Sharma · SPDX-License-Identifier: MIT
# https://thedataengineering.com/lab-code/LICENSE.txt
"""One outlier sets the width.

Frame-of-reference bit packing of a 128-value block: the width is set by
max - min. Without an outlier, with one, and with the outlier moved to a
patch list (PFOR).
"""
import argparse, json
import numpy as np

p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
p.add_argument("--block", type=int, default=128, help="Values per block.")
p.add_argument("--json", help="Also write the results to this JSON file.")
args = p.parse_args()
rng = np.random.default_rng(0)
block = rng.integers(1_000_000, 1_000_256, args.block)
bits = lambda x: int(x).bit_length()
w_plain = bits(block.max() - block.min())
block2 = block.copy(); block2[17] = 2**31
w_out = bits(block2.max() - block2.min())
pos_bits = bits(args.block - 1)
rows = [{"encoding": "no outlier", "bits": args.block * w_plain, "width": w_plain},
        {"encoding": "one outlier", "bits": args.block * w_out, "width": w_out},
        {"encoding": "PFOR: width 8 + one patch", "bits": args.block * w_plain + pos_bits + 32, "width": w_plain}]
for r in rows: print(f"{r['encoding']:<28} width {r['width']:2d} bits   {r['bits']:,} bits per block")

if args.json:
    with open(args.json, "w") as f:
        json.dump({"tables": {"encodings": rows, "summary": [{"outlier_x": rows[1]["bits"] / rows[0]["bits"], "pfor_x": rows[2]["bits"] / rows[0]["bits"]}]}}, f)