JSS autowig examples

basic.ipynb

dependent.ipynb

index.ipynb

run.bat

echo OFF

echo "AutoWIG Examples"
echo "================"
echo ""
echo "This script will run the four examples presented in the"
echo "accompanying paper. Corresponding Jupyter notebooks can"
echo "also be run individually, echo using, the following"
echo "commands,"
echo ""

echo ON

jupyter nbconvert --to notebook --execute basic.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'
jupyter nbconvert --to notebook --execute subset.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'
jupyter nbconvert --to notebook --execute template.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'
jupyter nbconvert --to notebook --execute dependent.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'

echo OFF

echo "In order to visualize the Jupyter notebooks execute the "
echo "folowing command"
echo ""
echo "jupyter notebook index.ipynb"

run.sh

set +x
set +e

echo "AutoWIG Examples"
echo "================"
echo ""
echo "This script will run the four examples presented in the"
echo "accompanying paper. Corresponding Jupyter notebooks can"
echo "also be run individually, echo using, the following"
echo "commands,"
echo ""

set -x

# git clone http://github.com/StatisKit/AutoWIG.git --depth=1
# mv AutoWIG/doc/examples/basic basic
# rm -rf AutoWIG
# jupyter nbconvert --to notebook --execute basic.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'
# git clone http://github.com/StatisKit/PyClangLite.git --depth=1
# jupyter nbconvert --to notebook --execute subset.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'
# rm -rf PySTL
# git clone http://github.com/StatisKit/PySTL.git --depth=1
# jupyter nbconvert --to notebook --execute template.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'
git clone http://github.com/pfernique/StructureAnalysis.git
cd StructureAnalysis
git checkout -b remove_tool origin/remove_tool
cd ..
jupyter nbconvert --to notebook --execute dependent.ipynb --allow-errors --inplace --ExecutePreprocessor.timeout=3600 --NotebookApp.kernel_spec_manager_class='environment_kernels.EnvironmentKernelSpecManager'

set -e
set +x

echo "In order to visualize the Jupyter notebooks execute the "
echo "folowing command"
echo ""
echo "jupyter notebook index.ipynb"

subset.ipynb

template.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Wrapping a template library\n",
    "\n",
    "A template library is a library where there are only template classes that can be instantiated.\n",
    "Wrapping such libraries therefore requires **AutoWIG** to be able to consider various *C++* template classes instantiations during the `Parse` step.\n",
    "It is therefore required to install the `pyclanglite` `parser`.\n",
    "The **Standard Template Library (STL)** library is a *C++* library that provides a set of common *C++* template classes such as containers and associative arrays.\n",
    "These classes can be used with any built-in or user-defined type that supports some elementary operations (e.g. copying, assignment).\n",
    "It is divided in four components called algorithms, containers, functional and iterators.\n",
    "**STL** containers (e.g. `std::vector`, `std::set`) are used in many *C++* libraries.\n",
    "In such a case, it does not seem relevant that every wrapped *C++* library contains wrappers for usual **STL** containers (e.g. `std::vector< double >`, `std::set< int >`).\n",
    "We therefore proposed *Python* bindings for sequence containers (i.e. `pair`, `array`, `vector`, `deque`, `forward_list` and `list` of the `std` namespace) and associative containers (`set`, `multiset`, `map`, `multimap`, `unordered_set`, `unordered_multiset`, `unordered_map` and `unordered_multimap` of the `std` namespace).\n",
    "These template instantiations are done for *C++* fundamental types (`bool`, `signed char`, `unsigned char`, `char`, `wchar_t`, `int` (with sign modifiers `signed` and `signed` combined or not with size modifiers `short`, `long` and `long long`), `float`, `double`, `long double`) and strings (`string`, `wstring` of the `std` namespace).\n",
    "For ordered associative containers both `std::less` and `std::greater` comparators are used.\n",
    "We here only illustrate the procedure on the `std::vector` template class.\n",
    "For the complete procedure refers to the `AutoWIG.py` file situed at the root of the **PySTL** [repository](https://github.com/StatisKit/PySTL)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preamble\n",
    "The code source is available in the `PySTL` directory.\n",
    "As presented below, in order to wrap a template library, the user needs to write headers containing aliases for desired template class instantiations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "!pygmentize PySTL/src/cpp/vector.h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This directory already contains wrappers, we therefore need to remove them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from path import path\n",
    "srcdir = path('PySTL')/'src'/'py'\n",
    "for wrapper in srcdir.walkfiles('*.cpp'):\n",
    "    wrapper.unlink()\n",
    "for wrapper in srcdir.walkfiles('*.h'):\n",
    "    wrapper.unlink()\n",
    "wrapper = srcdir/'stl'/'vector'/'_vector.py'\n",
    "if wrapper.exists():\n",
    "    wrapper.unlink()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we need to install and compile the *C++* library.\n",
    "This is done using available **Conda** recipes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "!conda build -q PySTL/conda/libpystl -c statiskit\n",
    "!conda install -y -q libpystl --use-local -c statiskit"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Wrapping the *C++* library\n",
    "\n",
    "Once these preliminaries done, we can proceed to the actual generation of wrappers for the **PySTL** *C++* library.\n",
    "For this, we import **AutoWIG** and create an empty Abstract Semantic Graph (ASG)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import autowig\n",
    "asg = autowig.AbstractSemanticGraph()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we parse headers with relevant compilation flags."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%time\n",
    "import sys\n",
    "prefix = path(sys.prefix)\n",
    "autowig.parser.plugin = 'pyclanglite'\n",
    "asg = autowig.parser(asg,\n",
    "                     [prefix/'include'/'pystl'/'vector.h'],\n",
    "                     flags = ['-x', 'c++', '-std=c++11',\n",
    "                              '-I' + str((prefix/'include').abspath())],\n",
    "                     bootstrap = 1,\n",
    "                     silent = True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since most of **AutoWIG** guidelines are respected, the `default` `controller` implementation is suitable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%time\n",
    "autowig.controller.plugin = 'default'\n",
    "asg = autowig.controller(asg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to wrap the library we need to select the `boost_python_internal` `generator` implementation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%time\n",
    "autowig.generator.plugin = 'boost_python_internal'\n",
    "wrappers = autowig.generator(asg,\n",
    "                  module = './PySTL/src/py/_vector.cpp',\n",
    "                  prefix = '_vector_wrapper_',\n",
    "                  decorator = './PySTL/src/py/stl/vector/_vector.py',\n",
    "                  closure = True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The wrappers are only generated in-memory.\n",
    "It is therefore needed to write them on the disk to complete the process."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%time\n",
    "wrappers.write()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is an example of the generated wrappers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "pygmentize PySTL/src/py/_vector.cpp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the wrappers are written on disk, we need to compile and install the *Python* bindings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "!conda build PySTL/conda/python-stl-vector -c statiskit \n",
    "!conda install -y python-stl-vector --use-local -c statiskit"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the *C++* library *Python* bindings\n",
    "\n",
    "Finally, we can hereafter use the *C++* library in the *Python* interpreter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from stl import vector\n",
    "v = vector.Int()\n",
    "v.push_back(-1)\n",
    "v.push_back(0)\n",
    "v.push_back(1)\n",
    "v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "list(v)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "v[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "v[0] = -2\n",
    "v[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "vector.Int([0, 1])"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}