cython-empty.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e5b265f7",
   "metadata": {},
   "source": [
    "![Cython](figures/Cython_logo.svg)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2f19274",
   "metadata": {},
   "source": [
    "Cython is a bit like numba.\n",
    "Let's start with an example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2fa6aede",
   "metadata": {},
   "outputs": [],
   "source": [
    "# We start with our optimized Python implementation.\n",
    "# Parameter 'f' has been renamed to 'func', to distinguish it from the 'f' function.\n",
    "\n",
    "def f(x):\n",
    "    return x**4 - 3 * x\n",
    "\n",
    "def integrate_f(func, a, b, n):\n",
    "    dx = (b - a) / n\n",
    "    s = 0.0\n",
    "    for i in range(n):\n",
    "        s += func(a + (i + 0.5) * dx) * dx\n",
    "    return s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b922655b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# We increase the number of points (from 3k to 1M) for easier measurement.\n",
    "\n",
    "integrate_f(f, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be214b63",
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit integrate_f(f, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5aeedd8d",
   "metadata": {},
   "source": [
    "Our first step is to load the `cython` extension and apply `%%cython` magic to the whole cell.\n",
    "\n",
    "`f`, `integrate_f` are renamed to `f2`, `integrate_f2`.\n",
    "\n",
    "The code is otherwise unchanged."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef2473e2",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f69350ec",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6d525486",
   "metadata": {},
   "outputs": [],
   "source": [
    "integrate_f2(f2, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59fc7d8d",
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit integrate_f2(f2, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98b8aa1c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# f2 and integrate_f2 are now compiled functions\n",
    "\n",
    "f2, integrate_f2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24bb1c45",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "609640e5",
   "metadata": {},
   "source": [
    "Our next step is to set types of the function parameters.\n",
    "\n",
    "This is called \"type specialiation\".\n",
    "\n",
    "Our code is not valid Python anymore, only Cython can understand it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "220208fe",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d678165",
   "metadata": {},
   "outputs": [],
   "source": [
    "integrate_f3(f3, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dacfa770",
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit integrate_f3(f3, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1c73c3f",
   "metadata": {},
   "source": [
    "Our next step is to also provide types of internal variables.\n",
    "\n",
    "We also use `-a` to tell `%%cython` to generate annotated output with hints about Python ↔ C-code interation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66631a64",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "509c1109",
   "metadata": {},
   "outputs": [],
   "source": [
    "integrate_f4(f4, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "905a11e1",
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit integrate_f4(f4, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d342ae19",
   "metadata": {},
   "source": [
    "## Exercise 01-cython-primes\n",
    "\n",
    "Please open [01-cython-primes/exercise.ipynb](01-cython-primes/exercise.ipynb) and follow instructions therein."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd189948",
   "metadata": {},
   "source": [
    "### Cython function type specialization\n",
    "\n",
    "We see strong yellow in the internal loop:\n",
    "every time we call `f`, which is a Python function, conversion from Python types to C types and back must be done. \n",
    "\n",
    "This is slow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2c0289b",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "# We do \"function specialization\", by changing 'f5' to be a C function.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "266819fc",
   "metadata": {},
   "outputs": [],
   "source": [
    "integrate_f5(f5, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0525bf8b",
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit integrate_f5(f5, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "474e8870",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "fdbe9245",
   "metadata": {},
   "source": [
    "### Cython formula optimization\n",
    "\n",
    "As a final optimization step, we can replace the call to `x**4`,\n",
    "which generates a call to the C function `pow()`, with a series of multiplications.\n",
    "\n",
    "We can also reorder the expression a bit to save one multiplication."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fafd612b",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "664e6f3f",
   "metadata": {},
   "outputs": [],
   "source": [
    "integrate_f6(f6, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "22d23d2c",
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit integrate_f6(f6, -10, +10, 1_000_000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52768b44",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "## Exercise: 02-cython-distrib\n",
    "\n",
    " Please open a terminal, `cd` to `02-cython-distrib/`, and follow the instructions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eb773961",
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython import display\n",
    "display.display(display.Markdown(open('02-cython-distrib/README.md').read()))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8e77134",
   "metadata": {},
   "source": [
    "# Cython and Numpy Arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8cbf32a",
   "metadata": {},
   "source": [
    "## Array summing\n",
    "\n",
    "Let's start by summing up an array.\n",
    "\n",
    "`const double [:]` means that the parameter is a immutable 1D memoryview.\n",
    "\n",
    "We can use this function on numpy arrays."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3a3a353",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "import numpy as np\n",
    "\n",
    "def mysum(A):\n",
    "    n = A.shape[A.ndim - 1]    \n",
    "    s = 0.0\n",
    "    for i in range(n):\n",
    "        s += A[i]\n",
    "    return s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "91ac4b82",
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.linspace(0, 10, 54)\n",
    "mysum(x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4d67db06",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "b2825e05",
   "metadata": {},
   "source": [
    "## Exercise 03-cython-mean3filter\n",
    "\n",
    "Please open [03-cython-mean3filter/exercise.ipynb](03-cython-mean3filter/exercise.ipynb) and follow instructions therein."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c687d0c",
   "metadata": {},
   "source": [
    "### Summary: why cython?\n",
    "\n",
    "Cython is clearly more work, but:\n",
    "\n",
    "- it is less magic, so you can really understand what is going on\n",
    "- you have control over the details\n",
    "- is it very old (1st pyrex release April 2002) and widespread\n",
    "- very portable — the compiled .so file or the generated .c file can be distributed\n",
    "- Cython speed is close to C\n",
    "- Cython cdef functions can call C/C++ code — Cython is great for wrapping external libraries\n",
    "\n",
    "When to use Cython:\n",
    "\n",
    "- number-crunching functions that cannot be vectorized with Numpy or other librararies\n",
    "- functions with complicated internal logic of conditions\n",
    "- code which needs to call library in C/C++/Fortan/other compiled code\n",
    "- to \"wrap\" a library in C/C++/Fortan/other compiled code to make it useful from Python\n",
    "  (esp. when numpy arrays are used)\n",
    "  \n",
    "When to use Numba instead:\n",
    "- in general numba is easier, so try it first\n",
    "- use cython when numba is not appropriate (because it doesn't work, or you need to distribute the compiled code, or you need to wrap external libraries)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4ffcb71",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3a3d1100",
   "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}