docs/examples/notebooks/cython_extension.ipynb

{
 "metadata": {
  "name": "cython_extension"
 },
 "nbformat": 3,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "source": [
      "Cython Magic Functions Extension"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "source": [
      "Loading the extension"
     ]
    },
    {
     "cell_type": "markdown",
     "source": [
      "IPtyhon has a `cythonmagic` extension that contains a number of magic functions for working with Cython code. This extension can be loaded using the `%load_ext` magic as follows:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%load_ext cythonmagic"
     ],
     "language": "python",
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "heading",
     "level": 2,
     "source": [
      "The %cython_inline magic"
     ]
    },
    {
     "cell_type": "markdown",
     "source": [
      "The `%%cython_inline` magic uses `Cython.inline` to compile a Cython expression. This allows you to enter and run a function body with Cython code. Use a bare `return` statement to return values. "
     ]
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "a = 10",
      "b = 20"
     ],
     "language": "python",
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%cython_inline",
      "return a+b"
     ],
     "language": "python",
     "outputs": [
      {
       "output_type": "pyout",
       "prompt_number": 9,
       "text": [
        "30"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "heading",
     "level": 2,
     "source": [
      "The %cython_pyximport magic"
     ]
    },
    {
     "cell_type": "markdown",
     "source": [
      "The `%%cython_pyximport` magic allows you to enter arbitrary Cython code into a cell. That Cython code is written as a `.pyx` file in the current working directory and then imported using `pyximport`.  You have the specify the name of the module that the Code will appear in. All symbols from the module are imported automatically by the magic function."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%cython_pyximport foo",
      "def f(x):",
      "    return 4.0*x"
     ],
     "language": "python",
     "outputs": [],
     "prompt_number": 18
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "f(10)"
     ],
     "language": "python",
     "outputs": [
      {
       "output_type": "pyout",
       "prompt_number": 19,
       "text": [
        "40.0"
       ]
      }
     ],
     "prompt_number": 19
    },
    {
     "cell_type": "heading",
     "level": 2,
     "source": [
      "The %cython magic"
     ]
    },
    {
     "cell_type": "markdown",
     "source": [
      "Probably the most important magic is the `%cython` magic.  This is similar to the `%%cython_pyximport` magic, but doesn't require you to specify a module name. Instead, the `%%cython` magic uses manages everything using temporary files in the `~/.cython/magic` directory.  All of the symbols in the Cython module are imported automatically by the magic.",
      "",
      "Here is a simple example of a Black-Scholes options pricing algorithm written in Cython:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%cython",
      "cimport cython",
      "from libc.math cimport exp, sqrt, pow, log, erf",
      "",
      "@cython.cdivision(True)",
      "cdef double std_norm_cdf(double x) nogil:",
      "    return 0.5*(1+erf(x/sqrt(2.0)))",
      "",
      "@cython.cdivision(True)",
      "def black_scholes(double s, double k, double t, double v,",
      "                 double rf, double div, double cp):",
      "    \"\"\"Price an option using the Black-Scholes model.",
      "    ",
      "    s : initial stock price",
      "    k : strike price",
      "    t : expiration time",
      "    v : volatility",
      "    rf : risk-free rate",
      "    div : dividend",
      "    cp : +1/-1 for call/put",
      "    \"\"\"",
      "    cdef double d1, d2, optprice",
      "    with nogil:",
      "        d1 = (log(s/k)+(rf-div+0.5*pow(v,2))*t)/(v*sqrt(t))",
      "        d2 = d1 - v*sqrt(t)",
      "        optprice = cp*s*exp(-div*t)*std_norm_cdf(cp*d1) - \\",
      "            cp*k*exp(-rf*t)*std_norm_cdf(cp*d2)",
      "    return optprice"
     ],
     "language": "python",
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "black_scholes(100.0, 100.0, 1.0, 0.3, 0.03, 0.0, -1)"
     ],
     "language": "python",
     "outputs": [
      {
       "output_type": "pyout",
       "prompt_number": 7,
       "text": [
        "10.327861752731728"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%timeit black_scholes(100.0, 100.0, 1.0, 0.3, 0.03, 0.0, -1)"
     ],
     "language": "python",
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1000000 loops, best of 3: 621 ns per loop",
        ""
       ]
      }
     ],
     "prompt_number": 14
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      ""
     ],
     "language": "python",
     "outputs": []
    }
   ]
  }
 ]
}