update readme

notebooks/Dispersion.ipynb

@@ -0,0 +1,224 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-03-21T10:41:27.004729Z",
+     "start_time": "2025-03-21T10:41:26.963236Z"
+    },
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "import os\n",
+    "sys.path.append(os.path.abspath('..'))  # Adds the parent directory to path\n",
+    "from src.user_keypad import UserKeypad\n",
+    "from IPython.display import Markdown, display\n",
+    "from src.models import KeypadSize\n",
+    "from src.utils import random_property_rotation, keypad_md_table\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Keypad Dispersion\n",
+    "\n",
+    "Keypad dispersion refers to an operation that redistributes the properties assigned to each key on a keypad, ensuring that no property shares a key with a property that was previously adjacent to it.\n",
+    "Keypads are only dispersable if `numb_of_keys <= properites_per_key`. It's used during nKode enrollment to infer property selection.\n",
+    "\n",
+    "A keypad dispersion is completed in two steps:\n",
+    "1. Create a property rotation array; a randomly permuted subset of indices, selected without replacement from a range equal to the number of keys on a keypad, with its length truncated to match the number of properties assigned per key.\n",
+    "2. Rotate each position, similar to a ring or combination lock, by a distance equal to its corresponding value in the property rotation array."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-03-21T10:41:27.020289Z",
+     "start_time": "2025-03-21T10:41:27.014493Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "\n",
+       "## Example Keypad\n",
+       "5 X 4 keypad (5 keys, 4 properties per key).\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Markdown object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/markdown": [
+       "||position 0|position 1|position 2|position 3|\n",
+       "|-|-|-|-|-|\n",
+       "|key 0|1|10|11|100|\n",
+       "|key 1|2|20|22|200|\n",
+       "|key 2|3|30|33|300|\n",
+       "|key 3|4|40|44|400|\n",
+       "|key 4|5|50|55|500|"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Markdown object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "keypad_size = KeypadSize(numb_of_keys=5, props_per_key=4)\n",
+    "props = [1, 10, 11, 100]\n",
+    "keypad_list = []\n",
+    "for key_numb in range(1,keypad_size.numb_of_keys+1):\n",
+    "    keypad_list.extend([key_numb * prop for prop in props])\n",
+    "\n",
+    "user_keypad = UserKeypad(keypad_size=keypad_size, keypad=np.array(keypad_list))\n",
+    "display(Markdown(f\"\"\"\n",
+    "## Example Keypad\n",
+    "{keypad_size.numb_of_keys} X {keypad_size.props_per_key} keypad ({keypad_size.numb_of_keys} keys, {keypad_size.props_per_key} properties per key).\n",
+    "\"\"\"))\n",
+    "display(Markdown(keypad_md_table(user_keypad.keypad, keypad_size)))\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Create Property Rotation Array"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-03-21T10:41:27.065332Z",
+     "start_time": "2025-03-21T10:41:27.056656Z"
+    },
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Property Rotation: [4 2 0 1]\n"
+     ]
+    }
+   ],
+   "source": [
+    "prop_rotation = np.random.choice(keypad_size.numb_of_keys, size=keypad_size.props_per_key, replace=False)\n",
+    "print(f\"Property Rotation: {prop_rotation}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Apply the Rotation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-03-21T10:41:27.074908Z",
+     "start_time": "2025-03-21T10:41:27.072449Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "||position 0|position 1|position 2|position 3|\n",
+       "|-|-|-|-|-|\n",
+       "|key 0|2|40|11|500|\n",
+       "|key 1|3|50|22|100|\n",
+       "|key 2|4|10|33|200|\n",
+       "|key 3|5|20|44|300|\n",
+       "|key 4|1|30|55|400|"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Markdown object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "dispersed_interface = random_property_rotation(\n",
+    "    user_keypad.keypad_matrix(),\n",
+    "    prop_rotation\n",
+    ")\n",
+    "display(Markdown(keypad_md_table(dispersed_interface.reshape(-1), keypad_size)))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "hello\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"hello\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}