notebooks/time_h3_apis.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "95776ece-9628-40ad-a6cb-bf68690167ec",
   "metadata": {},
   "source": [
    "# API Speed Comparison\n",
    "\n",
    "We time a simple toy computational task across the various APIs.\n",
    "\n",
    "We also compare the option of doing most of the computation in one of the faster APIs (using the `int` representation of H3 indexes),\n",
    "and then converting the results to the more familiar format of Python `str` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "cef5ba28-c8b0-42de-b55f-7a3d92436b32",
   "metadata": {},
   "outputs": [],
   "source": [
    "import h3\n",
    "import h3.api.numpy_int\n",
    "\n",
    "\n",
    "def compute(h3_lib, N=100):\n",
    "    h   = h3_lib.geo_to_h3(0, 0, 9)\n",
    "    out = h3_lib.k_ring(h, N)\n",
    "    out = h3_lib.compact(out)\n",
    "    \n",
    "    return out\n",
    "\n",
    "def compute_and_convert(h3_lib, N=100):\n",
    "    out = compute(h3_lib, N)\n",
    "    out = [h3.h3_to_string(h) for h in out]\n",
    "    \n",
    "    return out"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c933e85-5a9a-4d07-b4c4-20a88c97fa88",
   "metadata": {},
   "source": [
    "# Compute with each API\n",
    "\n",
    "**Benchmarking note**: `%%timeit sleep()` executes `sleep` before each **run** of the code to be timed in the remaining body of the cell; this helps to stabilize timing results (at least on my laptop)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "e636e193-22ff-440f-a5b8-4c073c8f8a57",
   "metadata": {},
   "outputs": [],
   "source": [
    "def sleep():\n",
    "    import time\n",
    "    time.sleep(2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e143ba5e-618b-47a9-913b-66f25877b240",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "59.8 ms ± 511 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute(h3.api.basic_str)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "6d80bca9-c0f5-4aaa-8488-f7bd174c7ee3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "35.4 ms ± 574 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute(h3.api.basic_int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "ac9eb860-eba1-41ec-8b33-3aa832758097",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.12 ms ± 52.8 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute(h3.api.memview_int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f2713e84-c4fb-4a60-b913-c1fb7ea7fd4b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.06 ms ± 49.3 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute(h3.api.numpy_int)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97e8e885-401b-42aa-a28e-534f828bf003",
   "metadata": {},
   "source": [
    "# Compute with `int` APIs and convert to `str`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "51c02c9f-0a03-4e84-943d-09969949b83d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "35.6 ms ± 462 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute_and_convert(h3.api.basic_int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "b11e3d6d-58d3-418f-9798-2a80dc16b133",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.76 ms ± 88.8 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute_and_convert(h3.api.memview_int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "5cf6e8a8-583d-4309-8ed2-5b4c31c8765a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7.61 ms ± 40.1 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit sleep()\n",
    "\n",
    "compute_and_convert(h3.api.numpy_int)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "381e7c85-a70a-4563-8504-29e39639821f",
   "metadata": {},
   "source": [
    "# Speedup\n",
    "\n",
    "We typically see about a 6--8x speedup between:\n",
    "\n",
    "- computing with the `h3.api.basic_str` interface\n",
    "- computing with the `h3.api.numpy_int` interface, and then converting the results back to `str`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "188da0e8-efd8-43f5-9f45-b821e085b8a7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7.8580814717477"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "### REMEMBER! Update the numbers from the `%%timeit`s above!\n",
    "\n",
    "c_str = 59.8\n",
    "cnc_numpy = 7.61\n",
    "\n",
    "c_str/cnc_numpy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "326bea04-304f-4b03-81f2-2fc77420e429",
   "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.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}