pynkode/notebooks/dispersion_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "source": [
    "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"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2025-03-21T09:28:57.936307Z",
     "start_time": "2025-03-21T09:28:57.933359Z"
    }
   },
   "outputs": [],
   "execution_count": 5
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "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."
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-21T09:28:57.950591Z",
     "start_time": "2025-03-21T09:28:57.945584Z"
    }
   },
   "cell_type": "code",
   "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"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ],
      "text/markdown": "\n## Example Keypad\n5 X 4 keypad (5 keys, 4 properties per key).\n"
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ],
      "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|"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "execution_count": 6
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "### Create Property Rotation Array"
  },
  {
   "cell_type": "code",
   "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"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2025-03-21T09:28:57.961890Z",
     "start_time": "2025-03-21T09:28:57.959507Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Property Rotation: [0 3 1 2]\n"
     ]
    }
   ],
   "execution_count": 7
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "### Apply the Rotation"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-21T09:28:57.976227Z",
     "start_time": "2025-03-21T09:28:57.973183Z"
    }
   },
   "cell_type": "code",
   "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)))"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ],
      "text/markdown": "||position 0|position 1|position 2|position 3|\n|-|-|-|-|-|\n|key 0|1|30|55|400|\n|key 1|2|40|11|500|\n|key 2|3|50|22|100|\n|key 3|4|10|33|200|\n|key 4|5|20|44|300|"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "execution_count": 8
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}