01 Loading a network.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Loading a network\n",
    "\n",
    "In this part, we are going to learn to create or load a network with pycaffe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "\"\"\"Initialization (see \"00 Basic solver usage\").\"\"\"\n",
    "import os\n",
    "\n",
    "import caffe\n",
    "CAFFE_ROOT=\"/caffe\"\n",
    "os.chdir(CAFFE_ROOT) # change the current directory to the caffe root, to help\n",
    "                     # with the relative paths\n",
    "USE_GPU = True\n",
    "if USE_GPU:\n",
    "    caffe.set_device(0)\n",
    "    caffe.set_mode_gpu()\n",
    "else:\n",
    "    caffe.set_mode_cpu()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading a network.\n",
    "\n",
    "Load the network and set it to the testing phase. To set it to testing phase,\n",
    "use `caffe.TRAIN`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "network_path = \"examples/mnist/lenet_train_test.prototxt\"\n",
    "loaded_network = caffe.Net(network_path, caffe.TEST) # caffe.TEST for testing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading a pretrained network\n",
    "\n",
    "The network is initialized with the weights in the weights file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "weights_path = \"examples/mnist/lenet_iter_10000.caffemodel\"\n",
    "loaded_network = caffe.Net(network_path, weights_path, caffe.TRAIN)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a network in Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from caffe import layers\n",
    "\n",
    "\"\"\"Network specification\"\"\"\n",
    "net = caffe.NetSpec()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding a layer\n",
    "\n",
    "- `name`: is the first output name (e.g. `net.data`)\n",
    "- `type`: is the variable type (e.g. `layers.Convolution`)\n",
    "- `top`: is the return value(s) (e.g. `net.conv1`, or the tuple `(net.data, net.label)`). However, if you have more than one top, you should specify the `ntop` parameter.\n",
    "- `bottom`: first (positional) argument(s)\n",
    "- layer parameters: anything that would go in `<layer>_param`, add them as keyword argument. If you need a sub-scope (as for `weight_filler`), use a python dictionary."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Data layer\n",
    "\n",
    "Two outputs (net.data and net.label) are the `top` in the prototxt.\n",
    "`backend` is specified in the caffe protobuf definition as a DB field, which then becomes\n",
    "\n",
    "    enum DB {\n",
    "      LEVELDB = 0;\n",
    "      LMDB = 1;\n",
    "    }\n",
    "    \n",
    "So the `backend=1` means `LMDB`.\n",
    "\n",
    "This line is equivalent to the prototxt:\n",
    "\n",
    "```\n",
    "layer {\n",
    "  name: \"data\"\n",
    "  type: \"Data\"\n",
    "  top: \"data\"\n",
    "  top: \"label\"\n",
    "  data_param {\n",
    "    source: \"examples/mnist/mnist_train_lmdb\"\n",
    "    batch_size: 64\n",
    "    backend: LMDB\n",
    "  }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Parameters\n",
    "batch_size = 64\n",
    "input_file = \"examples/mnist/mnist_train_lmdb\"\n",
    "net.data, net.label = layers.Data(batch_size=batch_size, source=input_file, ntop=2, backend=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Convolution layer\n",
    "\n",
    "Here, we have parameters with sub-scopes (`weight_filler`), so we define them with a Python dictionnary.\n",
    "\n",
    "The statement is equivalent to the prototxt:\n",
    "\n",
    "```\n",
    "layer {\n",
    "  name: \"conv1\"\n",
    "  type: \"Convolution\"\n",
    "  bottom: \"data\"\n",
    "  top: \"conv1\"\n",
    "  convolution_param {\n",
    "    num_output: 20\n",
    "    kernel_size: 5\n",
    "    weight_filler {\n",
    "      type: \"xavier\"\n",
    "    }\n",
    "    bias_filler {\n",
    "      type: \"constant\"\n",
    "    }\n",
    "  }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "net.conv1 = layers.Convolution(net.data, num_output=20, kernel_size=5,\n",
    "                               weight_filler={\"type\": \"xavier\"},\n",
    "                               bias_filler={\"type\": \"constant\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Fully connected layer\n",
    "\n",
    "Here, we specify a learning rate parameter with the `param` keyword argument\n",
    "\n",
    "Equivalent prototxt:\n",
    "\n",
    "```\n",
    "layer {\n",
    "  name: \"ip2\"\n",
    "  type: \"InnerProduct\"\n",
    "  bottom: \"conv1\"\n",
    "  top: \"ip2\"\n",
    "  param {\n",
    "    lr_mult: 2\n",
    "  }\n",
    "  inner_product_param {\n",
    "    num_output: 10\n",
    "  }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "net.ip2 = layers.InnerProduct(net.conv1, param={\"lr_mult\": 2}, num_output=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Loss layer\n",
    "\n",
    "This layer has two inputs, so two positional arguments.\n",
    "\n",
    "Equivalent prototxt:\n",
    "    \n",
    "```   \n",
    "layer {\n",
    "  name: \"loss\"\n",
    "  type: \"SoftMaxWithLoss\"\n",
    "  bottom: \"conv1\"\n",
    "  bottom: \"label\"\n",
    "  top: \"loss\"\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "net.loss = layers.SoftmaxWithLoss(net.ip2, net.label)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Conversion to a prototxt definiton."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "layer {\n",
      "  name: \"data\"\n",
      "  type: \"Data\"\n",
      "  top: \"data\"\n",
      "  top: \"label\"\n",
      "  data_param {\n",
      "    source: \"examples/mnist/mnist_train_lmdb\"\n",
      "    batch_size: 64\n",
      "    backend: LMDB\n",
      "  }\n",
      "}\n",
      "layer {\n",
      "  name: \"conv1\"\n",
      "  type: \"Convolution\"\n",
      "  bottom: \"data\"\n",
      "  top: \"conv1\"\n",
      "  convolution_param {\n",
      "    num_output: 20\n",
      "    kernel_size: 5\n",
      "    weight_filler {\n",
      "      type: \"xavier\"\n",
      "    }\n",
      "    bias_filler {\n",
      "      type: \"constant\"\n",
      "    }\n",
      "  }\n",
      "}\n",
      "layer {\n",
      "  name: \"ip2\"\n",
      "  type: \"InnerProduct\"\n",
      "  bottom: \"conv1\"\n",
      "  top: \"ip2\"\n",
      "  param {\n",
      "    lr_mult: 2\n",
      "  }\n",
      "  inner_product_param {\n",
      "    num_output: 10\n",
      "  }\n",
      "}\n",
      "layer {\n",
      "  name: \"loss\"\n",
      "  type: \"SoftmaxWithLoss\"\n",
      "  bottom: \"ip2\"\n",
      "  bottom: \"label\"\n",
      "  top: \"loss\"\n",
      "}\n",
      "\n"
     ]
    }
   ],
   "source": [
    "proto = net.to_proto()\n",
    "print(proto)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Serialized into a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "str_proto = str(proto)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Write the prototxt definition to a file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "output_file = \"my_net.prototxt\" # CAFFE_ROOT/output_file\n",
    "with open(output_file, \"w\") as f:\n",
    "    f.write(str_proto)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load the file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "my_net = caffe.Net(output_file, caffe.TRAIN)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have a network, what can we do with it? This is the next part of the tutorial."
   ]
  }
 ],
 "metadata": {
  "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.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}