Quanting.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3729baf4-f804-405e-8cbb-9d738464c433",
   "metadata": {},
   "source": [
    "**This is work in progress**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f87f26f-38e2-4f19-abe5-bfbc6dbe2419",
   "metadata": {},
   "source": [
    "ToDo:\n",
    "- how is quanting used in llm context?\n",
    "    - weight quanting\n",
    "    - activation quanting\n",
    "    - how quanted types are used (eg extra work for dequanting during fwd/bwd pass)\n",
    "    - difference between quanting for fwd and backward pass?\n",
    "- if & how quanting is used in diffusion context\n",
    "- quanting methods:\n",
    "    - hqq, hqq+\n",
    "    - awq\n",
    "    - 2bit quanting\n",
    "    - 1bit quanting\n",
    " \n",
    "\n",
    "Yes, I'm lazy and write 'quanting' instead 'quantizing'.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1fc513c-b527-48fd-be0b-d59376bcdda8",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "67482501-ba54-4a47-a7a4-1da45946895d",
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import pairwise\n",
    "\n",
    "import torch\n",
    "from torch import tensor\n",
    "import numpy as np\n",
    "\n",
    "from scipy.stats import norm\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "torch.set_printoptions(precision=3, linewidth=200, sci_mode=False)\n",
    "np.set_printoptions(precision=3, linewidth=200)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "226b5c93-fbfb-4f1c-9c60-c76ab2a23b0f",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "c9736a0b-5d4c-4a0c-a27e-9d00de9d3d91",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "## Naive Quanting"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "959b2c65-bf53-4d1c-8e90-c06f15d277b7",
   "metadata": {},
   "source": [
    "Let's make up 2 data types:\n",
    "- `PreciseNum` which uses 4 bits to represent numbers from -8 to 7 (so 16=2**4 different values)\n",
    "- `RoughNum` which uses 2 bits to represent numbers from 0 to 3\n",
    "\n",
    "Our goal is to convert data which is in `PreciseNum` format into `RoughNum`s (quanting) and recovering it (de-quanting)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dfb5f1c2-ee48-45b5-a661-088306ad5d52",
   "metadata": {},
   "source": [
    "The core idea of quanting is that we\n",
    "1. first match the ranges each types represent,\n",
    "2. then divide up the range into regions, whose number depends on how many different values the lower-bit type (for us: `RoughNum`) can represent,\n",
    "3. choose a representative point in each region,\n",
    "4. and lastly map each input value (of type `PreciseNum`) to the closest representative point.\n",
    "\n",
    "**todo umer:** and map repr to its low-bit equivalent"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "c022b15d-d2ec-4937-b268-fa8613abb237",
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC, abstractmethod\n",
    "\n",
    "abstract_class_property = lambda f: classmethod(property(abstractmethod(f)))\n",
    "class_property = lambda f: classmethod(property(f))\n",
    "\n",
    "class Number(ABC):\n",
    "    @abstract_class_property\n",
    "    def n_bits(cls): pass\n",
    "    @abstract_class_property\n",
    "    def max_val(cls): pass\n",
    "    @abstract_class_property\n",
    "    def min_val(cls): pass\n",
    "    \n",
    "    def __init__(self,x):\n",
    "        if not isinstance(x,int): raise ValueError(f'{self.__class__.__name__}  can only represent ints between  {self.min_val} and {self.max_val}')\n",
    "        if not (self.min_val <= x <= self.max_val): raise ValueError(f'{self.__class__.__name__}  can only represent ints between  {self.min_val} and {self.max_val}')\n",
    "        self.val = x\n",
    "        self.bits = [0] * self.n_bits   \n",
    "\n",
    "    def __repr__(self): return str(self.val)\n",
    "\n",
    "    def show(self): return str(self.val) + ' [' + ''.join(map(str,self.bits)) + ']' # eg '5 [101]'\n",
    "\n",
    "    @class_property\n",
    "    def range(cls): return (cls.min_val, cls.max_val)\n",
    "    \n",
    "    @classmethod\n",
    "    def range_iter(cls): return range(cls.min_val, cls.max_val+1)\n",
    "\n",
    "    def __eq__(self, other):\n",
    "        assert type(self)==type(other), f'Can\\'t compare self of type {type(self)} with other of type {type(other)}'\n",
    "        return self.bits == other.bits\n",
    "        \n",
    "\n",
    "class PreciseNum(Number):\n",
    "    @class_property\n",
    "    def n_bits(cls): return 4\n",
    "    @class_property\n",
    "    def max_val(cls): return 7\n",
    "    @class_property\n",
    "    def min_val(cls): return -8\n",
    "    \n",
    "    def __init__(self,x):\n",
    "        super().__init__(x)\n",
    "        x += 8 # shift (-8,7) to (0,15) for easier processing\n",
    "        for i in range(4):\n",
    "            self.bits[3-i] = x % 2\n",
    "            x //= 2\n",
    "\n",
    "\n",
    "class RoughNum(Number):\n",
    "    @class_property\n",
    "    def n_bits(cls): return 2\n",
    "    @class_property\n",
    "    def max_val(cls): return 3\n",
    "    @class_property\n",
    "    def min_val(cls): return 0\n",
    "    \n",
    "    def __init__(self,x):\n",
    "        super().__init__(x)       \n",
    "        for i in range(2):\n",
    "            self.bits[1-i] = x % 2\n",
    "            x //= 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "57db18d7-2115-4872-bda2-58d51ce30878",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(7, 5, -7, -8)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "PreciseNum(7), PreciseNum(5), PreciseNum(-7), PreciseNum(-8)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "928ceee0-24a9-4e2c-adf6-aa48a91a5a4b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, 2, 1, 0)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "RoughNum(3), RoughNum(2), RoughNum(1), RoughNum(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddb29577-ca85-4ea5-ad02-34f88bac0efe",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "6450f27e-e42f-4c5c-89ab-55cfbd1c0b1e",
   "metadata": {},
   "source": [
    "**Step 1:** Okay, let's match the ranges each type represent. We can choose an arbitrary target range as long as it's the same range for both data types. For the sake of illustration, let's choose a weird target range: `[-100, 200]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "f70c3f1c-ea4d-4ad7-a903-778787917e1f",
   "metadata": {},
   "outputs": [],
   "source": [
    "tgt_rng = [-100,200]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "9816fb59-9c3c-443d-8295-41e2bee086d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "def to_target_range(x, range_=tgt_rng):    \n",
    "    rng_min,rng_max = range_\n",
    "    normalized_x = (x.val - x.min_val) / (x.max_val - x.min_val) # scale from [x.min_val,x.max_val] to [0,1]    \n",
    "    return normalized_x * (rng_max - rng_min) + rng_min # Scale from [0,1] to [range_min, range_max]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "87ef5054-b94c-44d3-91b3-0a1fb1f6e53a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "160.0"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "to_target_range(PreciseNum(5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "e3410854-d341-43d0-9d58-b1f5d7e0317a",
   "metadata": {},
   "outputs": [],
   "source": [
    "for num_type in [PreciseNum, RoughNum]:\n",
    "    assert to_target_range(num_type(num_type.min_val)) == tgt_rng[0] # lowest value maps to start of range\n",
    "    assert to_target_range(num_type(num_type.max_val)) == tgt_rng[1] # lowest value maps to end of range"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "b319eca2-def7-4f2c-b5b4-60fbd1609fad",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mapping of range of PreciseNum to [-100, 200]\n",
      "-8 -> -100.00\n",
      "-7 ->  -80.00\n",
      "-6 ->  -60.00\n",
      "-5 ->  -40.00\n",
      "-4 ->  -20.00\n",
      "-3 ->    0.00\n",
      "-2 ->   20.00\n",
      "-1 ->   40.00\n",
      " 0 ->   60.00\n",
      " 1 ->   80.00\n",
      " 2 ->  100.00\n",
      " 3 ->  120.00\n",
      " 4 ->  140.00\n",
      " 5 ->  160.00\n",
      " 6 ->  180.00\n",
      " 7 ->  200.00\n",
      "--\n",
      "Mapping of range of RoughNum to [-100, 200]\n",
      " 0 -> -100.00\n",
      " 1 ->    0.00\n",
      " 2 ->  100.00\n",
      " 3 ->  200.00\n",
      "--\n"
     ]
    }
   ],
   "source": [
    "for num_type in [PreciseNum, RoughNum]:\n",
    "    print(f'Mapping of range of {num_type.__name__} to {tgt_rng}')\n",
    "    for x in num_type.range_iter():\n",
    "        in_target_rng = to_target_range(num_type(x))\n",
    "        print(f'{x:2} -> {in_target_rng:>7.2f}')\n",
    "    print('--')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36f1a834-ad56-4ee8-b515-1dd8b7c91c78",
   "metadata": {},
   "source": [
    "**Step 2:** Now we split the target range `[-100, 200]` into 4 regions, as `RoughNum` can handle `2**2` unique values.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "d478f29f-508e-42d7-9cc6-b05b1fd7a8c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# The 4 regions are defined by 5 boundaries\n",
    "reg_boundaries = [-100, -25, 50, 125, 200]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "af07bfa9-202a-49c1-9177-24d8275d4d5d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "27585d3a-ccff-4153-ac6d-e2feb97c43e1",
   "metadata": {},
   "source": [
    "**Step 3:** `RoughNum` can only hold 4 unique values. So we need to pick a representative from each of the 4 regions. Every number in a region will be mapped onto the representative. Eg, in our example, `PreciseNum(-8)` and `PreciseNum(-7)` map to `-100` and `-80` in our target range, which are both in the region `(-100,-25)`; so both will be mapped to the same representative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "421b8500-d756-4b00-a086-374cf7fba297",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "8bcfea4f-5560-4332-82f2-741e81f982ba",
   "metadata": {},
   "source": [
    "In principle, you can pick an abritrary representative for each region. But choosing the midpoint `(a+b)/2` give the smallest reconstruction error (ie mapping a `PreciseNum` and `RoughNum` and back, averaged over all possible `PreciseNum` values)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "033db73f-74af-4ef6-9779-9ee86f337a43",
   "metadata": {},
   "outputs": [],
   "source": [
    "def pick_repr(region):\n",
    "    a,b=region\n",
    "    return (a+b)/2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "e1d3cb74-753e-4cc4-bead-c683ddc7dff8",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[-62.5, 12.5, 87.5, 162.5]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "reprs = [pick_repr(r) for r in pairwise(reg_boundaries)]\n",
    "reprs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "51d89938-d891-48ee-9391-77818e9d6a8f",
   "metadata": {},
   "outputs": [],
   "source": [
    "for x1,x2 in pairwise(reprs): assert x1 <= x2 # representatives need to be in increasing order"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "60713113-61bb-43e3-81ef-b2192d0c5a81",
   "metadata": {},
   "outputs": [],
   "source": [
    "def to_repr(x):\n",
    "    # map a value in target range to its representative \n",
    "    for b,r in zip(reg_boundaries[1:], reprs):\n",
    "        if x <= b: return r\n",
    "    raise RuntimeError(f'Can\\'t map {x} to a representative')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "c94ac000-88e4-4a8f-a2aa-dc0245df6ff2",
   "metadata": {},
   "outputs": [],
   "source": [
    "for r in reprs: assert to_repr(r)==r # each representative should map onto itself"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c8c377bb-c0fd-472c-9543-b4dc6c22e7b8",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "818127cc-67ca-4409-b2e3-7ef2b0970106",
   "metadata": {},
   "outputs": [],
   "source": [
    "repr2rough = {repr: rough for repr, rough in zip(reprs, RoughNum.range_iter())}\n",
    "rough2repr = {rough: repr for repr, rough in repr2rough.items()}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "51f0e035-cebf-44fa-8e34-aa7f9f0f317f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "RoughNum 0 encodes values -62.50 in target range\n",
      "RoughNum 1 encodes values  12.50 in target range\n",
      "RoughNum 2 encodes values  87.50 in target range\n",
      "RoughNum 3 encodes values 162.50 in target range\n"
     ]
    }
   ],
   "source": [
    "for k,v in rough2repr.items(): print(f'RoughNum {k} encodes values {v:>6.2f} in target range')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b00d4669-bdb9-4fc9-92e4-1dc80c34273b",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "02e22bbb-2854-4075-8c16-49ab26df0c78",
   "metadata": {},
   "source": [
    "**Step 4:** Map input value (of type PreciseNum) to the closest representative point."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "fcebc4d7-835d-404d-9b6c-e7261332d756",
   "metadata": {},
   "outputs": [],
   "source": [
    "# todo umer: update comment\n",
    "def precise2rough(x):\n",
    "    assert isinstance(x, PreciseNum)\n",
    "    x = to_target_range(x) # eg PreciseNum(-7) -> (-100,-25)\n",
    "    x = to_repr(x)         # eg (-100,-25)      -> -62.5\n",
    "    x = repr2rough[x]      # eg -62.5           -> RoughNum(0)\n",
    "    return RoughNum(x)\n",
    "\n",
    "assert precise2rough(PreciseNum(-7)) == RoughNum(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "a8bb6126-6b3f-493f-83da-6e8874e1469f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mapping of PreciseNum -> RoughNum \n",
      "-8 -> 0\n",
      "-7 -> 0\n",
      "-6 -> 0\n",
      "-5 -> 0\n",
      "-4 -> 1\n",
      "-3 -> 1\n",
      "-2 -> 1\n",
      "-1 -> 1\n",
      " 0 -> 2\n",
      " 1 -> 2\n",
      " 2 -> 2\n",
      " 3 -> 2\n",
      " 4 -> 3\n",
      " 5 -> 3\n",
      " 6 -> 3\n",
      " 7 -> 3\n"
     ]
    }
   ],
   "source": [
    "print('Mapping of PreciseNum -> RoughNum ')\n",
    "for x in PreciseNum.range_iter(): print(f'{x:>2} -> {precise2rough(PreciseNum(x)).val}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3423e369-f672-4663-a98b-8a0d8e08355a",
   "metadata": {},
   "source": [
    "We've implemented naive quantization!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "13979a6b-d410-4be8-b341-aae49f49a556",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "03435743-b6e3-4575-80f9-484037808cee",
   "metadata": {},
   "source": [
    "**De-Quanting:**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68fc7fe8-3489-4258-8dc1-01c6a30d4856",
   "metadata": {},
   "source": [
    "For de-quanting, we (i) map a rough num into the target range, and then (ii) divide the target range into `2**4 = 16` regions, choose a representative (the mid point), and map the input to the closest representative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "da981c59-473d-42b1-a93a-6ac3e496ef5e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "For 4 bits / 16 values, the target range is divided into 16 regions of size 18.75\n",
      "The 17 boundaries are: [-100.0, -81.25, -62.5, -43.75, -25.0, -6.25, 12.5, 31.25, 50.0, 68.75, 87.5, 106.25, 125.0, 143.75, 162.5, 181.25, 200.0]\n"
     ]
    }
   ],
   "source": [
    "reg_size = (tgt_rng[1]-tgt_rng[0]) / 2**4\n",
    "print(f'For 4 bits / {2**4} values, the target range is divided into {2**4} regions of size {reg_size}')\n",
    "\n",
    "reg_boundaries_4bit = [-100 + i*18.75 for i in range(16+1)]\n",
    "print('The 17 boundaries are:',reg_boundaries_4bit)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "2440926e-404a-44e0-b400-66c65cf904a9",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The 16 representatives are: [-90.625, -71.875, -53.125, -34.375, -15.625, 3.125, 21.875, 40.625, 59.375, 78.125, 96.875, 115.625, 134.375, 153.125, 171.875, 190.625]\n"
     ]
    }
   ],
   "source": [
    "reprs_4bit = [pick_repr(r) for r in pairwise(reg_boundaries_4bit)]\n",
    "print('The 16 representatives are:',reprs_4bit)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "4527fa45-355f-4504-87ba-d2b540b97ca2",
   "metadata": {},
   "outputs": [],
   "source": [
    "def to_repr_4bit(x):\n",
    "    # map a value in target range to its representative \n",
    "    for b,r in zip(reg_boundaries_4bit[1:], reprs_4bit):\n",
    "        if x <= b: return r\n",
    "    raise RuntimeError(f'Can\\'t map {x} to a representative')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "37592aa8-c2bc-4fcd-9556-eb61d6c7e8a5",
   "metadata": {},
   "outputs": [],
   "source": [
    "repr4bit2precise = {repr: precise for repr, precise in zip(reprs_4bit, PreciseNum.range_iter())}\n",
    "precise2repr4bit = {precise: repr for repr, precise in repr4bit2precise.items()}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "df3a24ee-e88e-4274-a764-8b1299d78cd3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "PreciseNum -8 encodes value -90.62 in target range\n",
      "PreciseNum -7 encodes value -71.88 in target range\n",
      "PreciseNum -6 encodes value -53.12 in target range\n",
      "PreciseNum -5 encodes value -34.38 in target range\n",
      "PreciseNum -4 encodes value -15.62 in target range\n",
      "PreciseNum -3 encodes value   3.12 in target range\n",
      "PreciseNum -2 encodes value  21.88 in target range\n",
      "PreciseNum -1 encodes value  40.62 in target range\n",
      "PreciseNum  0 encodes value  59.38 in target range\n",
      "PreciseNum  1 encodes value  78.12 in target range\n",
      "PreciseNum  2 encodes value  96.88 in target range\n",
      "PreciseNum  3 encodes value 115.62 in target range\n",
      "PreciseNum  4 encodes value 134.38 in target range\n",
      "PreciseNum  5 encodes value 153.12 in target range\n",
      "PreciseNum  6 encodes value 171.88 in target range\n",
      "PreciseNum  7 encodes value 190.62 in target range\n"
     ]
    }
   ],
   "source": [
    "for k,v in precise2repr4bit.items(): print(f'PreciseNum {k:>2} encodes value {v:>6.2f} in target range')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "e94dee9a-62a1-4437-bc08-1e12a61c487a",
   "metadata": {},
   "outputs": [],
   "source": [
    "def rough2precise(x):\n",
    "    assert isinstance(x, RoughNum)\n",
    "    x = to_target_range(x)  # eg RoughNum(0)   -> (-100.0, -81.25)\n",
    "    x = to_repr_4bit(x)     # eg (-100.0, -81.25) -> -90.625\n",
    "    x = repr4bit2precise[x] # eg -90.625          -> PreciseNum(-8)\n",
    "    return PreciseNum(x)\n",
    "\n",
    "assert rough2precise(RoughNum(0)) == PreciseNum(-8)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "39f45eb5-4428-4c25-ba41-ae2bc0d35fda",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "PreciseNum --quanting--> RoughNum --dequanting--> PreciseNum\n",
      "-8 -> 0 -> -8\n",
      "-7 -> 0 -> -8\n",
      "-6 -> 0 -> -8\n",
      "-5 -> 0 -> -8\n",
      "-4 -> 1 -> -3\n",
      "-3 -> 1 -> -3\n",
      "-2 -> 1 -> -3\n",
      "-1 -> 1 -> -3\n",
      " 0 -> 2 ->  2\n",
      " 1 -> 2 ->  2\n",
      " 2 -> 2 ->  2\n",
      " 3 -> 2 ->  2\n",
      " 4 -> 3 ->  7\n",
      " 5 -> 3 ->  7\n",
      " 6 -> 3 ->  7\n",
      " 7 -> 3 ->  7\n"
     ]
    }
   ],
   "source": [
    "print('PreciseNum --quanting--> RoughNum --dequanting--> PreciseNum')\n",
    "for x in PreciseNum.range_iter():\n",
    "    x = PreciseNum(x)\n",
    "    x_rough = precise2rough(x)\n",
    "    x_reconstructed = rough2precise(x_rough)\n",
    "    print(f'{x.val:>2} -> {x_rough.val} -> {x_reconstructed.val:>2}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e31d71b2-434b-49d8-a5d7-8c7607137656",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "68aa297a-7ad3-4e04-a845-c92b0e3190d3",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "## Quantile Quanting"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31e6642f-f85d-4332-94a2-3ce69259f194",
   "metadata": {},
   "source": [
    "Currently, our quanting method doesn't consider how our input is distributed. If you know (or can estimate) the distribution of your input data, you can adapt your quanting method to it, making it less wasteful (ie average reconstruction error will be lower)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4245b665-d234-4a3d-ab7e-c2e442c50ef0",
   "metadata": {},
   "source": [
    "The input distribution matters in step 2 of quanting: Dividing the target range into regions. After converting our input data into the target region, we want each region to contain about the same number of elements.\n",
    "\n",
    "Let's take a normal distribution as an example. (This is interesting because the activations of a neural network for a given unit are normally distribution.) We'll see that the naive division into equally sized regions we used so far isn't well suited to normally distributed input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "62e4dc10-761f-4620-84af-762668fa474e",
   "metadata": {},
   "outputs": [],
   "source": [
    "def normal_precise_nums(mean=None, std=1, n_samples=1000):\n",
    "    if mean is None: mean = (PreciseNum.max_val+PreciseNum.min_val)/2 # the range of PreciseNum is centered around (8+(-7))/2 = -0.5\n",
    "    \n",
    "    x = torch.normal(mean=mean, std=std, size=(n_samples,))\n",
    "    x = x.clamp(*PreciseNum.range).round().int().tolist()\n",
    "    x = [PreciseNum(x_) for x_ in x]\n",
    "    assert isinstance(x[0], PreciseNum)\n",
    "    return x\n",
    "\n",
    "n_samples = 1000\n",
    "\n",
    "x = normal_precise_nums(std=3, n_samples=n_samples) # for illustration: normal distribution with mean 0 and std dev 3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "802d9ce9-1c18-4d15-95e8-ea994cc6e45a",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "fcbea264-af49-4339-aabb-02afa04101a4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Out of 1000 input data points...\n",
      "\t 96 are mapped into region (-100,  -25) (represented by -62.5)\n",
      "\t398 are mapped into region ( -25,   50) (represented by  12.5)\n",
      "\t402 are mapped into region (  50,  125) (represented by  87.5)\n",
      "\t104 are mapped into region ( 125,  200) (represented by 162.5)\n"
     ]
    }
   ],
   "source": [
    "from collections import Counter\n",
    "\n",
    "repr2freq = Counter([to_repr(to_target_range(x_)) for x_ in x]) # how often does an input end up in a region (defined by its representative)?\n",
    "repr2freq = {r:f for r,f in repr2freq.items() }\n",
    "assert sum(repr2freq.values()) == n_samples\n",
    "\n",
    "print(f'Out of {n_samples} input data points...')\n",
    "for i,r in enumerate(sorted(repr2freq.keys())): print(f'\\t{repr2freq [r]:>3} are mapped into region ({reg_boundaries[i]:>4}, {reg_boundaries[i+1]:>4}) (represented by {r:>5.1f})')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f6ee030e-aae9-4ad6-a05e-a921fe010d42",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "0ae099e0-123f-4981-811f-b87f5c528e7f",
   "metadata": {},
   "source": [
    "The number of data points mapped by each region are not equal at all. So our choice of how to divide the regions is wasteful. We can do better by explicitely dividing such that the expected number of points in each region is about the same.\n",
    "\n",
    "_Note_: The expected number of points in a region, as a percentage of total points, is called `probability mass`. Let's abbreviate it with `p'mass`. The total p'mass is always 1.\n",
    "\n",
    "If we wanted to compute the p'mass of region `(a_tgt,b_tgt)`, we can use the 'cumulative distribution function' (cdf) of the input distribution. In our case that's `scipy.stats.norm.cdf`. `cdf(b_prec)-cdf(a_prec)` is the p'mass of `(a_tgt,b_tgt)` where `a_prec` and `b_prec` are the values in `PreciceNum`'s range that map to `a_tgt` and `b_tgt` in the target range.\n",
    "\n",
    "What we want is to have regions of equal p'masses. For `2**2 = 4` regions, each region should have p'mass `1/4 = 0.25`. Therefore, we want numbers `a_i`such that `[cdf(a_i) for i in range(0,2**2+1) == [0.00, 0.25, 0.50, 0.75, 1.00]`.\n",
    "\n",
    "To get those numbers, we'll use the inverse of the cdf, which is the ppf ('probabilty percentile function')."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "e2981bee-4730-4bd1-870a-ed64bb77d7e3",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.stats import norm\n",
    "\n",
    "precise_mean = (PreciseNum.max_val+PreciseNum.min_val)/2\n",
    "precise_distribution = norm(precise_mean,3)\n",
    "\n",
    "cdf = precise_distribution.cdf\n",
    "ppf = precise_distribution.ppf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "63accc7e-4766-4b63-85c2-58cdb84fd172",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "For 4 regions, each region should have p'mass 0.25.\n",
      "\tIn the precise range, region (-8.00, -2.52) has pmass 0.2438.\n",
      "\tIn the precise range, region (-2.52, -0.50) has pmass 0.2500.\n",
      "\tIn the precise range, region (-0.50,  1.52) has pmass 0.2500.\n",
      "\tIn the precise range, region ( 1.52,  7.00) has pmass 0.2438.\n"
     ]
    }
   ],
   "source": [
    "pmass_per_region = 1 / RoughNum.n_bits**2\n",
    "print(f'For {RoughNum.n_bits**2} regions, each region should have p\\'mass {pmass_per_region}.')\n",
    "\n",
    "def clamp_prec(x,a=PreciseNum.min_val,b=PreciseNum.max_val):\n",
    "    if x < a: return a\n",
    "    if x > b: return b\n",
    "    return x\n",
    "        \n",
    "reg_boundaries_precise = [clamp_prec(ppf(i*pmass_per_region)) for i in range(RoughNum.n_bits**2 + 1)]\n",
    "\n",
    "for a_prec,b_prec in pairwise(reg_boundaries_precise):\n",
    "    pmass = cdf(b_prec)-cdf(a_prec)\n",
    "    print(f'\\tIn the precise range, region ({a_prec:>5.2f}, {b_prec:>5.2f}) has pmass {pmass:.4f}.')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f12dc89f-7a30-4420-9231-f4afcf38defc",
   "metadata": {},
   "source": [
    "Note that the edge regions appear to have a bit lower pmass due, which is due to clamping. But clamping maps the values outside of range onto the edges, so the pmass is recovered. So all regions have exactly the same pmass."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "943bfa3b-66e5-473b-abaa-7cb47e52f83b",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "246cd6cd-3982-4049-807b-741628241560",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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Q3l5ebRo0QKLxcKGDRtMx/FpBw4cYPDgwdSuXZty5cpRt25dRo8eTX5+vuloPmfKlCnExcUREhJC+/btWb16telIPm3s2LG0bduW8PBwoqKi6NWrFzt37jQdy++89NJLWCwWHnroIdNRfF5SUhK33XYblStXply5csTHx7NmzRrTsXyehqFSdt1111FQUMBPP/3E2rVrSUhI4LrrriMlJcV0NJ82e/Zsbr/9dgYNGsTGjRtZtmwZt9xyi+lYfuPRRx+lWrVqpmP4hR07duByuXj77bfZunUrr732GlOnTuWJJ54wHc2nzJw5kxEjRjB69GjWrVtHQkIC3bp1Iy0tzXQ0n/Xzzz8zbNgwVq5cycKFC3E6nVx99dVkZ2ebjuY3fvvtN95++22aN29uOorPO3HiBJdccgmBgYF89913bNu2jfHjx1OxYkXT0XyerjNUitLT06lSpQq//PILl156KQBZWVlERESwcOFCunbtajihbyooKCAuLo4xY8YwePBg03H8znfffceIESOYPXs2TZs2Zf369bRo0cJ0LL/y6quv8tZbb7Fv3z7TUXxG+/btadu2LZMnTwbA5XIRGxvL/fffz+OPP244nX84evQoUVFR/Pzzz1x22WWm4/i8kydP0qpVK958802ef/55WrRowcSJE03H8lmPP/44y5YtY+nSpaaj+B29M1SKKleuTMOGDfnwww/Jzs6moKCAt99+m6ioKFq3bm06ns9at24dSUlJWK1WWrZsSdWqVbnmmmvYsmWL6Wg+LzU1lSFDhvDRRx8RGhpqOo7fyszMpFKlSqZj+Iz8/HzWrl17xgtYVquVrl27smLFCoPJ/EtmZiaAfrfLyLBhw+jRo4deuC0jX331FW3atKFv375ERUXRsmVLpk+fbjqWX9AwVIosFgs//vgj69evJzw8nJCQECZMmMCCBQv0tmcp+uPV8GeeeYannnqKb775hooVK3L55Zdz/Phxw+l8l9vt5s477+S+++6jTZs2puP4rT179vDGG29w7733mo7iM9LT0yksLCQ6OvqM+6Ojo7XkuYy4XC4eeughLrnkEpo1a2Y6js/77LPPWLduHWPHjjUdxW/s27ePt956i/r16/P9998zdOhQHnjgAT744APT0XyehqEL8Pjjj2OxWP7yY8eOHbjdboYNG0ZUVBRLly5l9erV9OrVi+uvv54jR46Yfhpe53zr7nK5AHjyySfp06cPrVu35r333sNisTBr1izDz8L7nG/d33jjDbKyshg5cqTpyD7hfOv+v5KSkujevTt9+/ZlyJAhhpKLlLxhw4axZcsWPvvsM9NRfN6hQ4d48MEH+eSTTwgJCTEdx2+4XC5atWrFiy++SMuWLbnnnnsYMmQIU6dONR3N5+mcoQtw9OhRjh079pfH1KlTh6VLl3L11Vdz4sQJIiIiir5Wv359Bg8erHXmxXS+dV+2bBn/+Mc/WLp0KZ07dy76Wvv27enatSsvvPBCaUf1Kedb9379+vH1119jsViK7i8sLMRms3Hrrbfq1a1iOt+6BwUFAZCcnMzll19Ohw4deP/997Fa9VpXScnPzyc0NJQvvvjijF0pBw4cSEZGBvPmzTMXzg8MHz6cefPm8csvv1C7dm3TcXze3LlzufHGG7HZbEX3FRYWYrFYsFqt5OXlnfE1KRm1atXiqquu4p133im676233uL5558nKSnJYDLfF2A6gDeqUqUKVapU+dvjcnJyAP70R4nVai1690LO3/nWvXXr1gQHB7Nz586iYcjpdHLgwAFq1apV2jF9zvnW/fXXX+f5558v+jw5OZlu3boxc+ZM2rdvX5oRfdL51h1OvyN0xRVXFL0LqkGoZAUFBdG6dWsWLVpUNAy5XC4WLVrE8OHDzYbzYW63m/vvv585c+awZMkSDUJl5Morr2Tz5s1n3Ddo0CAaNWrEY489pkGolFxyySV/2jp+165d+rulDGgYKkUdO3akYsWKDBw4kFGjRlGuXDmmT5/O/v376dGjh+l4PisiIoL77ruP0aNHExsbS61atXj11VcB6Nu3r+F0vqtmzZpnfF6+fHkA6tatS40aNUxE8gtJSUlcfvnl1KpVi3HjxnH06NGir8XExBhM5ltGjBjBwIEDadOmDe3atWPixIlkZ2czaNAg09F81rBhw5gxYwbz5s0jPDy86Pwsu91OuXLlDKfzXeHh4X86LyssLIzKlSvrfK1S9K9//YtOnTrx4osv0q9fP1avXs20adOYNm2a6Wg+T8NQKYqMjGTBggU8+eST/OMf/8DpdNK0aVPmzZtHQkKC6Xg+7dVXXyUgIIDbb7+dU6dO0b59e3766SdtXCE+Z+HChezZs4c9e/b8aejUKuiS079/f44ePcqoUaNISUmhRYsWLFiw4E+bKkjJeeuttwC4/PLLz7j/vffe48477yz7QCKlqG3btsyZM4eRI0fy7LPPUrt2bSZOnMitt95qOprP0zlDIiIiIiLil7SwXERERERE/JKGIRERERER8UsahkRERERExC9pGBIREREREb+kYUhERERERPyShiEREREREfFLGoZERERERMQvaRgSERERERG/pGFIRERERET8koYhERERERHxSxqGRERERETEL/0fgacqygQz0AwAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 1000x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "domain = np.linspace(*PreciseNum.range, 100)\n",
    "plt.figure(figsize=(10, 5))\n",
    "plt.plot(domain, precise_distribution.pdf(domain))\n",
    "for boundary in reg_boundaries_precise: plt.axvline(x=boundary, color='gray', linestyle='--')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d84e1544-f04b-4f62-b230-4bccc282c501",
   "metadata": {},
   "source": [
    "**Important:** These are values in the precise range. But we want to divide up the target range."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "896e9e96-9668-4fc9-bdba-12ba8e1fa4cc",
   "metadata": {},
   "source": [
    "Let's write functions to map ranges into each other."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "eb22e663-5956-4203-8b07-14fc56290464",
   "metadata": {},
   "outputs": [],
   "source": [
    "def map_range(x, orig_range, dest_range): # maps x from orig_range into dest_range\n",
    "    min_orig,max_orig = orig_range\n",
    "    min_dest,max_dest = dest_range\n",
    "    normalized_x = (x - min_orig) / (max_orig - min_orig)  # scale from [min_orig, max_orig] to [0,1]    \n",
    "    return normalized_x * (max_dest - min_dest) + min_dest # Scale from [0,1] to [min_dest, max_dest]    \n",
    "\n",
    "precise_range = (PreciseNum.min_val, PreciseNum.max_val)\n",
    "rough_range   = (RoughNum.min_val,   RoughNum.max_val)\n",
    "\n",
    "def precise2tgt_range(x): return map_range(x, orig_range=precise_range, dest_range=tgt_rng)\n",
    "def rough2tgt_range(x):   return map_range(x, orig_range=rough_range,   dest_range=tgt_rng)\n",
    "\n",
    "def tgt2precice_range(x): return map_range(x, orig_range=tgt_rng, dest_range=precise_range)\n",
    "def tgt2rough_range(x):   return map_range(x, orig_range=tgt_rng, dest_range=rough_range)\n",
    "\n",
    "# assertions\n",
    "for t,p in zip(tgt_rng, precise_range): assert tgt2precice_range(t)==p # end points of ranges should map to each other\n",
    "for t,r in zip(tgt_rng, rough_range)  : assert tgt2rough_range(t)  ==r # end points of ranges should map to each other\n",
    "\n",
    "assert precise2tgt_range(tgt2precice_range(-100)) == -100 # mapping from precise -> target -> precise should not change anything\n",
    "assert rough2tgt_range(  tgt2rough_range(  -100)) == -100 # mapping from rough   -> target -> rough   should not change anything"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f252e92a-12d9-4756-88db-a8bccd819144",
   "metadata": {},
   "source": [
    "Cool, now we can use `precise2tgt_range` to map our regions in the precise range to regions in the target range."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "ec7bed67-fc6a-4fae-ae4b-c0c45bdcfc42",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "In the target range, region 0 is (-100.00,    9.53) (represented by -45.2).\n",
      "In the target range, region 1 is (   9.53,   50.00) (represented by  29.8).\n",
      "In the target range, region 2 is (  50.00,   90.47) (represented by  70.2).\n",
      "In the target range, region 3 is (  90.47,  200.00) (represented by 145.2).\n"
     ]
    }
   ],
   "source": [
    "reg_boundaries = [precise2tgt_range(b) for b in reg_boundaries_precise]\n",
    "reprs = [pick_repr(r) for r in pairwise(reg_boundaries)]\n",
    "\n",
    "for i, ((a_tgt,b_tgt), r) in enumerate(zip(pairwise(reg_boundaries), reprs)):\n",
    "    print(f'In the target range, region {i} is ({a_tgt:>7.2f}, {b_tgt:>7.2f}) (represented by {r:>5.1f}).')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "id": "a8fa42ec-1787-44fd-b8d6-7af39d926396",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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1keSJCQkJGDdunX47bff/nFaQENqbkP+HhZK9AoOtuz8+fPSoUOHpFmzZkmenp7SoUOHpEOHDkllZWWSJElSTU2NFBERIQ0cOFBKT0+XkpOTJV9fX2natGmm5zhz5ozk7u4uTZ06VTp27Ji0aNEiSaFQSMnJyaJeFv2X3bt3Sx999JGUnp4unT59Wvr2228lX19fady4caYxpaWlkr+/v/TII49ImZmZ0sqVKyV3d3fp888/F5icrmflypWSi4uLtGzZMuno0aPSE088ITVr1qzOSjdkvV588UVp+/bt0tmzZ6Vdu3ZJcXFxko+Pj1RcXCxJkiQ99dRTUuvWraXffvtNOnDggBQbGyvFxsYKTk3/q6yszPR7E4A0b9486dChQ9L58+clSZKk2bNnS82aNZM2bNggZWRkSA888IDUtm1bqbKy0vQcgwYNkrp16ybt3btX2rlzpxQWFiaNGTNG1EtyeNfbpmVlZdJLL70kpaamSmfPnpV+/fVXqXv37lJYWJhUVVVleg5uU+syefJkSa1WS9u3b5cKCgpMHxUVFaYxN6q5Dfl7WCQ2Q7dg/PjxEoB/fGzbts005ty5c9I999wjubm5ST4+PtKLL74o6fX6Os+zbds2KTo6WlIqlVJoaKj01VdfNe0LoWtKS0uTYmJiJLVaLbm6ukqdOnWS3nvvvTqFW5Ik6fDhw1K/fv0kFxcXKSgoSJo9e7agxNRQn3zyidS6dWtJqVRKvXv3lvbs2SM6EjXQ6NGjpZYtW0pKpVIKCgqSRo8eLZ06dcr09crKSunpp5+WmjdvLrm7u0vDhg2TCgoKBCam+mzbtq3e36Hjx4+XJKl2ee033nhD8vf3l1xcXKS77rpLOn78eJ3nuHTpkjRmzBjJ09NTUqlU0oQJE0xvSFLTu942raiokAYOHCj5+vpKzs7OUps2baRJkyb9400oblPrUt/2BFDnb9WG1NyG/D0sikySJKkJd0QRERERERFZBZ4zREREREREDonNEBEREREROSQ2Q0RERERE5JDYDBERERERkUNiM0RERERERA6JzRARERERETkkNkNEREREROSQ2AwREREREZFDYjNEREREREQOic0QERERERE5JDZDRERERETkkP4f2VOjqfOX/5YAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 1000x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "target_pdf = lambda x: precise_distribution.pdf(tgt2precice_range(x))\n",
    "\n",
    "domain = np.linspace(*tgt_rng, 100)\n",
    "plt.figure(figsize=(10, 5))\n",
    "plt.plot(domain, target_pdf(domain))\n",
    "for boundary in reg_boundaries: plt.axvline(x=boundary, color='gray', linestyle='--')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "593c8d67-2c2e-405d-8ab0-994ab48123f3",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "d0c4331c-95d5-4d4f-b972-4b03b5e0be12",
   "metadata": {},
   "source": [
    "Let's define `to_repr` again, so it used the updated `reg_boundaries`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "id": "371a57fb-927b-4725-bce2-60dd0ce81e7e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# same code as above\n",
    "def to_repr(x):\n",
    "    # map a value in target range to its representative \n",
    "    for b,r in zip(reg_boundaries[1:], reprs):\n",
    "        if x <= b: return r\n",
    "    raise RuntimeError(f'Can\\'t map {x} to a representative')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a6a6ee0-a5e2-452a-ba8b-31462d100b40",
   "metadata": {},
   "source": [
    "Let's experimentally check that about the same number of input elements end up in each region."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "id": "5ebb9f0d-257c-4fe7-9144-9063e1310789",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Out of 1000 input data points...\n",
      "\t288 are mapped into region (-100.00,    9.53) (represented by -45.2)\n",
      "\t243 are mapped into region (   9.53,   50.00) (represented by  29.8)\n",
      "\t236 are mapped into region (  50.00,   90.47) (represented by  70.2)\n",
      "\t233 are mapped into region (  90.47,  200.00) (represented by 145.2)\n"
     ]
    }
   ],
   "source": [
    "n_samples = 1000\n",
    "x = normal_precise_nums(std=3, n_samples=n_samples)\n",
    "\n",
    "repr2freq = Counter([to_repr(precise2tgt_range(x_.val)) for x_ in x]) # how often does an input end up in a region (defined by its representative)?\n",
    "repr2freq = {r:f for r,f in repr2freq.items() }\n",
    "assert sum(repr2freq.values()) == n_samples\n",
    "\n",
    "print(f'Out of {n_samples} input data points...')\n",
    "for i,r in enumerate(sorted(repr2freq.keys())): print(f'\\t{repr2freq [r]:>3} are mapped into region ({reg_boundaries[i]:>7.2f}, {reg_boundaries[i+1]:>7.2f}) (represented by {r:>5.1f})')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61ce260a-e9ae-451e-8f4f-1950ecb0f822",
   "metadata": {},
   "source": [
    "These points are now way more evenly distributed!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a917b1a8-0d3d-4ea9-bd05-73c81833d3c2",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "id": "695e400f-e40e-4dd7-86b6-3d2f7300e2e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "repr2rough = {repr: rough for repr, rough in zip(reprs, RoughNum.range_iter())}\n",
    "rough2repr = {rough: repr for repr, rough in repr2rough.items()}\n",
    "\n",
    "# todo umer: update comment\n",
    "def precise2rough(x):\n",
    "    assert isinstance(x, PreciseNum)\n",
    "    x = x.val\n",
    "    x = precise2tgt_range(x) # eg PreciseNum(-7) -> (-100,-25)\n",
    "    x = to_repr(x)           # eg (-100,-25)      -> -62.5\n",
    "    x = repr2rough[x]        # eg -62.5           -> RoughNum(0)\n",
    "    return RoughNum(x)\n",
    "\n",
    "assert precise2rough(PreciseNum(-7)) == RoughNum(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "id": "79a716b4-f89f-4ae5-96fc-e3135a3ae06c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mapping of PreciseNum -> RoughNum \n",
      "-8 -> 0\n",
      "-7 -> 0\n",
      "-6 -> 0\n",
      "-5 -> 0\n",
      "-4 -> 0\n",
      "-3 -> 0\n",
      "-2 -> 1\n",
      "-1 -> 1\n",
      " 0 -> 2\n",
      " 1 -> 2\n",
      " 2 -> 3\n",
      " 3 -> 3\n",
      " 4 -> 3\n",
      " 5 -> 3\n",
      " 6 -> 3\n",
      " 7 -> 3\n"
     ]
    }
   ],
   "source": [
    "print('Mapping of PreciseNum -> RoughNum ')\n",
    "for x in PreciseNum.range_iter(): print(f'{x:>2} -> {precise2rough(PreciseNum(x)).val}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3aa12dcc-7def-4309-878e-f3fa289d30a3",
   "metadata": {},
   "source": [
    "Note how the rough values 1 and 2 each now encode only 2 precise values, but the rough values 0 and 3 each now encode 6 precise values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea537a28-3377-44b7-9de6-206fa13cf3a8",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "id": "d97d8bbf-8998-4854-b119-ff0ea34604ca",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "PreciseNum --quanting--> RoughNum --dequanting--> PreciseNum\n",
      "-8 -> 0 -> -8\n",
      "-7 -> 0 -> -8\n",
      "-6 -> 0 -> -8\n",
      "-5 -> 0 -> -8\n",
      "-4 -> 0 -> -8\n",
      "-3 -> 0 -> -8\n",
      "-2 -> 1 -> -3\n",
      "-1 -> 1 -> -3\n",
      " 0 -> 2 ->  2\n",
      " 1 -> 2 ->  2\n",
      " 2 -> 3 ->  7\n",
      " 3 -> 3 ->  7\n",
      " 4 -> 3 ->  7\n",
      " 5 -> 3 ->  7\n",
      " 6 -> 3 ->  7\n",
      " 7 -> 3 ->  7\n"
     ]
    }
   ],
   "source": [
    "print('PreciseNum --quanting--> RoughNum --dequanting--> PreciseNum')\n",
    "for x in PreciseNum.range_iter():\n",
    "    x = PreciseNum(x)\n",
    "    x_rough = precise2rough(x)\n",
    "    x_reconstructed = rough2precise(x_rough)\n",
    "    print(f'{x.val:>2} -> {x_rough.val} -> {x_reconstructed.val:>2}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0cf0840d-5c06-44eb-b869-b63ed849d83e",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "803645f1-fe4c-4fce-9711-1f638cfd7380",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "c9d37fa9-b1fb-42b9-94fa-dbd5163eff8d",
   "metadata": {},
   "source": [
    "## Asymmetric Quantile Quanting"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87e1321a-fc9b-4bcd-b8da-5db1fc578441",
   "metadata": {},
   "source": [
    "You might have noticed that quanting and then dequanting 0 changes it to a non-zero values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "id": "4b1910e0-9fae-4294-98f5-ac441885df27",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A precise  0 is quanted into a rough 2, and dequanted into a precise  2.\n"
     ]
    }
   ],
   "source": [
    "x = PreciseNum(0)\n",
    "x_rough = precise2rough(x)\n",
    "x_reconstructed = rough2precise(x_rough)\n",
    "\n",
    "print(f'A precise {x.val:>2} is quanted into a rough {x_rough.val}, and dequanted into a precise {x_reconstructed.val:>2}.')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5151fbb0-e320-4ad6-8e07-4c388f5a98ac",
   "metadata": {},
   "source": [
    "This is bad, because **Todo Umer:** why exactly?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f3875e85-387b-4da8-9ff3-1180673e3a80",
   "metadata": {},
   "source": [
    "To fix this, we do something called 'asymmetric quanting'. This can be be applied to naive quanting as well, but we'll directly apply it to quantile quanting.\n",
    "\n",
    "With 2 bits, we have 4 rough values. So far, we have divided up the target region (with total p'mass of 1) into 4 areas of equal p'mass. The main idea now is to reserve a region around 0 and pick 0 as its representative, and then independently divide the negative numbers into 4/2-1 = 1 regions of equal p'mass and the positive numbers into 4/2 = 2 regions of equal p'mass. This totals 1 + 1 + 2 = 4 regions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "id": "c890e5cb-19ce-4d5a-9a12-c9c6a4ee431a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "For 2 bits, asymmetric quanting gives us 1 region(s) for negative numbers, 1 region around zero, and 2 regions for positive numbers.\n"
     ]
    }
   ],
   "source": [
    "bits = RoughNum.n_bits\n",
    "\n",
    "n_reg_pos = int((bits**2)/2)\n",
    "n_reg_neg = int(((bits**2)/2)-1)\n",
    "\n",
    "print(f'For {bits} bits, asymmetric quanting gives us {n_reg_neg} region(s) for negative numbers, 1 region around zero, and {n_reg_pos} regions for positive numbers.')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "id": "434f8c29-f561-4d4a-9de0-92964f7361e5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Each negative region has p'mass 0.50\n",
      "Each positive region has p'mass 0.25\n"
     ]
    }
   ],
   "source": [
    "pmass_per_neg_region = 0.5 / n_reg_neg\n",
    "pmass_per_pos_region = 0.5 / n_reg_pos\n",
    "\n",
    "print(f'Each negative region has p\\'mass {pmass_per_neg_region:.2f}')\n",
    "print(f'Each positive region has p\\'mass {pmass_per_pos_region:.2f}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ec7e770-9c3b-479a-83e5-a4288ae5453a",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2952f33-52f8-43da-9ee4-97d0dbaa8dd4",
   "metadata": {},
   "outputs": [],
   "source": [
    "def clamp_prec(x,a=PreciseNum.min_val,b=PreciseNum.max_val):\n",
    "    if x < a: return a\n",
    "    if x > b: return b\n",
    "    return x\n",
    "        \n",
    "reg_boundaries_precise = [\n",
    "    clamp_prec(ppf(i*pmass_per_region)) for i in range(RoughNum.n_bits**2 + 1)\n",
    "]\n",
    "\n",
    "for a_prec,b_prec in pairwise(reg_boundaries_precise):\n",
    "    pmass = cdf(b_prec)-cdf(a_prec)\n",
    "    print(f'\\tIn the precise range, region ({a_prec:>5.2f}, {b_prec:>5.2f}) has pmass {pmass:.4f}.')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08885377-2dab-4bac-92d5-6f604cf25d2a",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88dd1c0b-905b-4cc1-b8a7-901223356f9f",
   "metadata": {},
   "outputs": [],
   "source": [
    "q_ctrs = tensor([\n",
    "    *[norm.ppf(0.5 - area_region_neg*i) for i in range(1,n_ctr_neg+1)],\n",
    "    0,\n",
    "    *[norm.ppf(0.5 + area_region_pos*i) for i in range(1,n_ctr_pos+1)]\n",
    "])\n",
    "q_ctrs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2d73851c-2d70-4e48-bd14-57f8f770f693",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f'These are the {bits**2} numbers that our quanting scheme will map every input onto.')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43acf348-7280-49e3-9a47-2048f3112ce3",
   "metadata": {},
   "outputs": [],
   "source": [
    "domain = torch.linspace(-4, 4, 100)\n",
    "plt.figure(figsize=(10, 5))\n",
    "plt.plot(domain, norm.pdf(domain))\n",
    "#for c in q_ctrs: plt.axvline(x=c, color='gray', linestyle='--')\n",
    "plt.scatter(q_ctrs, [0]*len(q_ctrs), color='red', s=30)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1f6fd66-dabb-4489-8f6c-13c656154944",
   "metadata": {},
   "source": [
    "Let's check that the probability mass between is as expected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d20ac6b7-313f-4cc0-bf23-538c295b4892",
   "metadata": {},
   "outputs": [],
   "source": [
    "for c1,c2 in pairwise(q_ctrs[0:n_ctr_neg].tolist() + [0]):\n",
    "    # in negative region, p'mass between any 2 centers equals p'mass of (-inf, left most center)\n",
    "    assert np.isclose(norm.cdf(c2) - norm.cdf(c1),  norm.cdf(q_ctrs[0]))\n",
    "\n",
    "for c1,c2 in pairwise([0] + q_ctrs[n_ctr_pos:].tolist()):\n",
    "    # in positive region, p'mass between any 2 centers equals p'mass of (right most center, inf)\n",
    "    assert np.isclose(norm.cdf(c2) - norm.cdf(c1), 1-norm.cdf(q_ctrs[-1]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b4ea2444-10d1-4d13-a069-db7d535af019",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65cdf013-15fa-494a-9185-f1e89246a7ed",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fc1b3eec-47aa-4ac8-9911-902a3975976e",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7521823f-6c82-44e7-81a8-2750363d8806",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c183325-9f1f-45bc-8e14-853887edd18d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ebe2f295-bb0a-4050-b366-9a73f89bcf2a",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d69be0a0-dd7b-4f68-b26c-99dcc606bb8a",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7744c4b1-608a-4dc7-baa1-3b0ae3d7c85d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "db5f8868-2601-450e-9512-5b2c6505ba08",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4eeefd6d-ec4b-450f-9525-9e6eb0a56565",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}