00-preliminaries.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introductions, Scope, Goals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About me\n",
    "\n",
    "* Data Scientist at [HomeAway](https://www.homeaway.com/)\n",
    "* Author of [_Cython: A Guide for Python Programmers_](http://shop.oreilly.com/product/0636920033431.do) <img src=\"https://covers.oreillystatic.com/images/0636920033431/lrg.jpg\" width=250 height=250 />\n",
    "* Have taught Cython & interfacing with Python a lot:\n",
    "  * [SciPy 2013](https://youtu.be/gMvkiQ-gOW8), [SciPy 2015](https://youtu.be/JKCjsRDffXo) (notice a trend?)\n",
    "  * [Enthought's training material](https://training.enthought.com/course/INTERFACING)\n",
    "* Physicist -> Scientific Software Developer -> Solution Architect / Data Engineer -> Data Scientist.\n",
    "* Usual grab-bag of Big Data and Machine Learning components and languages:\n",
    "  * Currently: Python / Scala / R, Spark, PyData / SciPy stacks, TensorFlow, Theano, Keras, PyMC3.\n",
    "  * In past jobs: C, C++, Cython, SWIG.\n",
    "* Industries: Oil & Gas, Finance, National Labs, Travel."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Scope & Goals\n",
    "\n",
    "* Goal: learn a bit more how CPython works under the hood.\n",
    "* Goal: understand why CPython can be slow, and how Cython can make it fast(er).\n",
    "* Goal: gain enough exposure to Cython to tackle your own project, with some templates.\n",
    "* Non-goal: pointers, dynamic memory allocation / reference counting, Python C-API.\n",
    "  * Cython abstracts all of this away for us, unless we're wrapping C / C++ code.\n",
    "* Non-goal: wrapping C / C++ codebases with Cython.\n",
    "  * Gets into the weeds pretty quickly, requires more C / C++ expertise than assumed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What makes this tutorial different?\n",
    "\n",
    "* Thanks to cython integration with jupyter notebooks, much more hands-on.\n",
    "* Cover basic material more quickly\n",
    "  * Cut out interfacing with C / C++, remove some extraneous details.\n",
    "  * There's a book if you want to go in depth :)\n",
    "* More time on data-science focused verticals."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tools\n",
    "\n",
    "* We will be using the `Cython` IPython notebook extension.\n",
    "* Enables the `%%cython` cell magic command."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%load_ext Cython"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "'''\n",
    "Inside this cell is Cython code only.  \n",
    "\n",
    "Behind the scenes, Jupyter and Cython write out a `.pyx` file that is dynamically compiled on cell execution.  \n",
    "\n",
    "All the Python-level constructs are then imported into the current kernel namespace.\n",
    "'''\n",
    "\n",
    "def first_cython_func(int i):\n",
    "    return i * 3.1415926"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We *use* the function in a separate (Python) cell.\n",
    "first_cython_func(10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%cython?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "  %cython [-3] [-2] [-c COMPILE_ARGS] [--link-args LINK_ARGS] [-l LIB]\n",
    "              [-n NAME] [-L dir] [-I INCLUDE] [-+] [-f] [-a]\n",
    "\n",
    "Compile and import everything from a Cython code cell.\n",
    "\n",
    "The contents of the cell are written to a `.pyx` file in the\n",
    "directory `IPYTHONDIR/cython` using a filename with the hash of the\n",
    "code. This file is then cythonized and compiled. The resulting module\n",
    "is imported and all of its symbols are injected into the user's\n",
    "namespace. The usage is similar to that of `%%cython_pyximport` but\n",
    "you don't have to pass a module name::\n",
    "\n",
    "    %%cython\n",
    "    def f(x):\n",
    "        return 2.0*x\n",
    "\n",
    "To compile OpenMP codes, pass the required  `--compile-args`\n",
    "and `--link-args`.  For example with gcc::\n",
    "\n",
    "    %%cython --compile-args=-fopenmp --link-args=-fopenmp\n",
    "    ...\n",
    "\n",
    "optional arguments:\n",
    "  -3                    Select Python 3 syntax.\n",
    "  -2                    Select Python 2 syntax.\n",
    "  -c COMPILE_ARGS, --compile-args COMPILE_ARGS\n",
    "                        Extra flags to pass to compiler via the\n",
    "                        `extra_compile_args` Extension flag (can be specified\n",
    "                        multiple times).\n",
    "  --link-args LINK_ARGS\n",
    "                        Extra flags to pass to linker via the\n",
    "                        `extra_link_args` Extension flag (can be specified\n",
    "                        multiple times).\n",
    "  -l LIB, --lib LIB     Add a library to link the extension against (can be\n",
    "                        specified multiple times).\n",
    "  -n NAME, --name NAME  Specify a name for the Cython module.\n",
    "  -L dir                Add a path to the list of library directories (can be\n",
    "                        specified multiple times).\n",
    "  -I INCLUDE, --include INCLUDE\n",
    "                        Add a path to the list of include directories (can be\n",
    "                        specified multiple times).\n",
    "  -+, --cplus           Output a C++ rather than C file.\n",
    "  -f, --force           Force the compilation of a new module, even if the\n",
    "                        source has been previously compiled.\n",
    "  -a, --annotate        Produce a colorized HTML version of the source.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!ls .ipython/cython/cyfoo*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next notebook: [01-python-slow.ipynb](./01-python-slow.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "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.6.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}