4.+Tutorial+-+Optimize+API.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#Optimize API"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose you've written an algorithm that's developed a signal (for example, a [Pipeline Factor](https://www.quantopian.com/tutorials/pipeline#lesson3)) that's predictive of future asset returns. You might think that the hard part is over, but you're still left with the daunting task of translating your signal into an algorithm that can turn a profit while also managing risk exposures.\n",
    "\n",
    "Traditionally in quantitative finance, the solution to the problem of maximizing returns while constraining risk has been to employ some form of [Portfolio Optimization](https://en.wikipedia.org/wiki/Portfolio_optimization), but performing sophisticated optimizations is challenging on today's Quantopian.\n",
    "\n",
    "Python libraries like [scipy.optimize](http://docs.scipy.org/doc/scipy/reference/optimize.html), [CVXOPT](http://cvxopt.org/), and [CVXPY](http://www.cvxpy.org/en/latest/) (all available on Quantopian today) provide generic tools for solving optimization problems. These libraries are powerful and flexible, but it takes significant expertise to convert the data structures available on Quantopian into the specific formats understood by these libraries.\n",
    "\n",
    "The [**Optimize API**](https://www.quantopian.com/help#optimize-title) is a suite of tools for defining and solving portfolio optimization problems directly in terms of financial domain concepts. Users interact with the Optimize API by providing an `Objective` and a list of `Constraint` objects to an API function that runs a portfolio optimization. The Optimize API hides most of the complex mathematics of portfolio optimization, allowing users to think in terms of high-level concepts like “maximize expected returns” and “constrain sector exposure” instead of abstract matrix products."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What is Portfolio Optimization?\n",
    "\n",
    "Many algorithms written on Quantopian reach a point where they need to solve an **optimization problem** of the following form:\n",
    "\n",
    "Given a list of stocks, choose a vector,\n",
    "\n",
    "$$w$$ \n",
    "\n",
    "of weights in each stock that maximizes (or minimizes) an **objective** function,\n",
    "\n",
    "$$F(w)$$ \n",
    "\n",
    "subject to a set of inequality **constraints**,\n",
    "\n",
    "\\begin{align} \n",
    "C_1(w) &\\leq h_1 \\\\ \n",
    "C_2(w) &\\leq h_2    \\\\\n",
    "&\\dots           \\\\\n",
    "C_N(w) &\\leq h_N    \\\\\n",
    "\\end{align}\n",
    "\n",
    "####Example:\n",
    "\n",
    "An algorithm builds a model that predicts expected returns for a list of stocks. The algorithm wants to allocate a limited amount of capital to those stocks in a way that gives it the greatest possible expected return without placing too big a bet on any single stock.\n",
    "\n",
    "We can frame this as an optimization problem as follows:\n",
    "\n",
    "Given an expected returns vector $r = [r_0, r_1, \\dots, r_n]$, a maximum single-stock weight $w_{max}$, and a maximum total weight $W_{max}$, find a portfolio weight vector $w = [w_0, w_1, \\dots, w_n]$ that solves the following system:\n",
    "\n",
    "\\begin{align}\n",
    "\\text{maximize}&& \\\\\n",
    "&&r \\cdot w \\\\\n",
    "\\text{subject to}&& \\\\\n",
    "&&w_i &\\leq w_{max} && 0 \\leq i \\leq n\\\\\n",
    "&& \\sum_{i=0}^{n}{|w_i|} &\\leq W_{max}\n",
    "\\end{align}\n",
    "\n",
    "A more sophisticated algorithm might introduce a more complex objective (e.g. \"maximize return with a penalty applied for expected volatility\"), or it might introduce more complex constraints (e.g. limit exposure to particular market sectors)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API Overview\n",
    "\n",
    "The Optimize API is defined in the [**`quantopian.optimize`**](https://www.quantopian.com/help#module-quantopian.optimize) module.\n",
    "\n",
    "The `optimize` module has three important concepts:\n",
    "\n",
    "1. [**`Objectives`**](https://www.quantopian.com/help#objectives): classes that define the function to be minimized or maximized by the optimizer.\n",
    "2. [**`Constraints`**](https://www.quantopian.com/help#objectives): classes that define constraints that the optimizer must respect when finding a new portfolio.\n",
    "3. [**`Entry Points`**](https://www.quantopian.com/help#running-optimizations), functions that actually run optimizations. The Optimize API has three entrypoints:\n",
    "  - `calculate_optimal_portfolio`, the primary entrypoint in research notebooks.\n",
    "  - `order_optimal_portfolio`, the primary entrypoint in trading algorithms.\n",
    "  - `run_optimization`, a lower-level entrypoint useful for debugging.\n",
    "\n",
    "To run a portfolio optimization **in a notebook**, you call `calculate_optimal_portfolio` and provide  up to three inputs: \n",
    "\n",
    "- An `Objective` to optimize.\n",
    "- A list of `Constraint`s to enforce.\n",
    "- (optionally) A [pandas Series](http://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.html) containing weights for the current portfolio. If no current weights are provided, the optimization proceeds assuming that the current portfolio is empty.\n",
    "\n",
    "To run a portfolio optimization **in a trading algorithm**, you call `order_optimal_portfolio` instead. \n",
    "`order_optimal_portfolio` accepts two inputs:\n",
    "\n",
    "- An `Objective` to optimize (same as above).\n",
    "- A list of `Constraints` to enforce (same as above).\n",
    "\n",
    "It is also possible to call `calculate_optimal_portfolio` from a trading algorithm to compute the portfolio that `order_optimal_portfolio` would attempt to achieve if invoked."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Calculate optimal portfolio weights given ``objective`` and ``constraints``.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    objective : Objective\n",
      "        The objective to be minimized or maximized.\n",
      "    constraints : list[Constraint]\n",
      "        List of constraints that must be satisfied by the new portfolio.\n",
      "    current_portfolio : pd.Series, optional\n",
      "        A Series containing the current portfolio weights, expressed as\n",
      "        percentages of the portfolio's liquidation value.\n",
      "    \n",
      "        When called from a trading algorithm, the default value of\n",
      "        ``current_portfolio`` is the algorithm's current portfolio.\n",
      "    \n",
      "        When called interactively, the default value of ``current_portfolio``\n",
      "        is an empty portfolio.\n",
      "\n",
      "    Returns\n",
      "    -------\n",
      "    optimal_portfolio : pd.Series\n",
      "        A Series containing portfolio weights that maximize (or minimize)\n",
      "        ``objective`` without violating any ``constraints``. Weights should be\n",
      "        interpreted in the same way as ``current_portfolio``.\n",
      "\n",
      "    Raises\n",
      "    ------\n",
      "    \n",
      "    InfeasibleConstraints\n",
      "        Raised when there is no possible portfolio that satisfies the received\n",
      "        constraints.\n",
      "    UnboundedObjective\n",
      "        Raised when the received constraints are not sufficient to put an upper\n",
      "        (or lower) bound on the calculated portfolio weights.\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    This function is a shorthand for calling ``run_optimization``, checking for\n",
      "    an error, and extracting the result's ``new_weights`` attribute.\n",
      "\n",
      "    If an optimization problem is feasible, the following are equivalent::\n",
      "\n",
      "        # Using calculate_optimal_portfolio.\n",
      "        >>> weights = calculate_optimal_portfolio(objective, constraints, portfolio)\n",
      "\n",
      "        # Using run_optimization.\n",
      "        >>> result = run_optimization(objective, constraints, portfolio)\n",
      "        >>> result.raise_for_status()  # Raises if the optimization failed.\n",
      "        >>> weights = result.new_weights\n",
      "\n",
      "    See Also\n",
      "    --------\n",
      "    :func:`quantopian.optimize.run_optimization`\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "import quantopian.optimize as opt\n",
    "print opt.calculate_optimal_portfolio.__doc__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lists of the currently available objectives and constraints can be found under **`quantopian.optimize.objectives`** and **`quantopian.optimize.constraints`**, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[quantopian.optimize.objectives.MaximizeAlpha,\n",
       " quantopian.optimize.objectives.Objective,\n",
       " quantopian.optimize.objectives.TargetWeights]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "opt.objectives"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[quantopian.optimize.constraints.Basket,\n",
       " quantopian.optimize.constraints.CannotHold,\n",
       " quantopian.optimize.constraints.Constraint,\n",
       " quantopian.optimize.constraints.DollarNeutral,\n",
       " quantopian.optimize.constraints.FactorExposure,\n",
       " quantopian.optimize.constraints.FixedWeight,\n",
       " quantopian.optimize.constraints.Frozen,\n",
       " quantopian.optimize.constraints.LongOnly,\n",
       " quantopian.optimize.constraints.MaxGrossExposure,\n",
       " quantopian.optimize.constraints.MaxTurnover,\n",
       " quantopian.optimize.constraints.NetExposure,\n",
       " quantopian.optimize.constraints.NetGroupExposure,\n",
       " quantopian.optimize.constraints.Pair,\n",
       " quantopian.optimize.constraints.PositionConcentration,\n",
       " quantopian.optimize.constraints.ReduceOnly,\n",
       " quantopian.optimize.constraints.ShortOnly]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "opt.constraints"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Maximize Expected Returns with Exposure and Concentration Constraints\n",
    "\n",
    "Let's look at how we can use the `optimize` API to solve the example outlined above:\n",
    "\n",
    "> An algorithm builds a model that predicts expected returns for a list of stocks. The algorithm wants to allocate a limited amount of capital to those stocks in a way that gives it the greatest possible expected return without placing too big a bet on any single stock.\n",
    "\n",
    "Since we're assuming we already have a returns model, we'll just use random numbers for this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "def fancy_returns_model(assets):\n",
    "    \"\"\"Not actually fancy.\"\"\"\n",
    "    # Generate a random number for each asset.\n",
    "    rng = np.random.RandomState(5)\n",
    "    return pd.Series(index=assets, data=rng.randn(len(assets)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll also add a few utility functions for plotting portfolio weights."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def draw_asset_barplot(weights, title, plot_kwargs=None):\n",
    "    \"\"\"Draw a bar plot from a Series with Asset labels.\"\"\"\n",
    "    return draw_barplot(\n",
    "        weights, \n",
    "        title, \n",
    "        xticks=[asset.symbol for asset in weights.index],\n",
    "        plot_kwargs=plot_kwargs, \n",
    "    )\n",
    "\n",
    "def draw_barplot(weights, title, xticks=None, plot_kwargs=None):\n",
    "    \"\"\"Draw a bar plot from a pd.Series.\"\"\"\n",
    "    \n",
    "    # Draw the plot. Forward plot_kwargs (if provided) as keywords to ``plot``.\n",
    "    axes = weights.plot(kind='bar', rot=0, fontsize=12, **(plot_kwargs or {}))\n",
    "    axes.grid(False, axis='x')\n",
    "    \n",
    "    # Set a title.\n",
    "    axes.set_title(title, {'fontsize': 14})\n",
    "    \n",
    "    # Set xtick labels, if provided.\n",
    "    if xticks is not None:\n",
    "        axes.set_xticklabels(xticks)\n",
    "\n",
    "    return axes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Choose a small universe to make the graphs manageable.\n",
    "universe = symbols(\n",
    "    ['AAPL', 'MSFT', 'TWTR', 'BP', 'XOM', 'MCD', 'QSR'],\n",
    "    symbol_reference_date='2016-10-07',\n",
    ")\n",
    "                     \n",
    "empty_portfolio = pd.Series(index=universe, data=0.0)\n",
    "expected_returns = fancy_returns_model(universe)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzoAAAHvCAYAAACc3aoBAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzt3X2c1XWB9//3OOBMIySil6MR4w3GzhahNoKIaCih3EiW\nXJY3aQsuy8rFwzKsTTKRUqDMNNLNVVSUy7rcLY2VgGvFNa4wWA0fZuzWpiSiuEImciMMynB+f/jz\nrJPcyTAMfnk+H48eD743c76f75zOOb7me3MqSqVSKQAAAAWyX1sPAAAAYHcTOgAAQOEIHQAAoHCE\nDgAAUDhCBwAAKByhAwAAFI7QAeA94/TTT8+9997b1sMA4D2gXVsPAIDd6/TTT8+qVatSWVlZnlcq\nlVJRUZHx48fns5/9bJuN7YEHHsjHP/7xdO7cebc/9pVXXpmZM2emffv25XkdOnTI8ccfnyuuuCJH\nHnnkTj3O7373u/zpT3/KySefvNvHCMCeI3QACmj8+PG54IIL2noYzTQ1NWXy5Mnp0aNHq4ROkgwc\nODDf+973ytOrV6/O5MmTM2rUqMyePbtZBG3Lj3/847Rv336XQuetoASg7Tl1DaCASqXSNpc988wz\nOfbYY/O73/2uPG/EiBG56qqrkrx5ROiuu+7KqFGjctxxx2XgwIH5t3/7t/K6L730UsaMGZOTTjop\nvXr1ype+9KW8+uqr5eWPPvpoPv3pT+f444/PJz/5ycyfPz9JcsIJJ2TdunUZPnx4pk6dmiR57LHH\nct5556WhoSGnnHJKbrrppvLjNDU15dprr02fPn1y6qmn5kc/+tG7/j0cdNBBufLKK/P888+X97dU\nKuXmm2/OGWeckeOOOy7nnHNOFi5cmCS55pprcu+99+aee+7JgAEDkiT19fXlfUjePCrVp0+fJMmK\nFStSX1+ff/qnf8pJJ52U+++/Pw888EA++clPZubMmTn99NPT0NCQL3/5y+Xn5Kmnnirv84knnpjL\nL78869ate9f7BsD2CR2AfcwxxxyTUaNGZeLEiUmSf/mXf8nSpUvz1a9+tbzOPffck7Fjx+axxx7L\nWWedlbFjx+b1119Pklx66aWpra3NI488koceeiivvfZavvnNbyZJVq5cmbFjx2bUqFH51a9+ldGj\nR+cLX/hCVq5cmVmzZqVUKuWBBx7IZZddlpUrV+Zv//Zv89nPfja/+tWvMn369Dz44IP5x3/8xyRv\nHlmZM2dO7r333jz00EN55pln8sorr7zr/X1r3G+5++678+CDD+b222/P4sWLc/7552fMmDFZu3Zt\nrrnmmpxwwgn5/Oc/n4cffnibj/nnR20effTRzJs3L8OHD0+SvPjii/nNb36T2bNn5957782cOXPy\n85//PEny5S9/Of369cuvfvWrPPTQQ1m7dm1uu+22d71fAGyf0AEooMmTJ+fYY48t/69nz5459thj\ny0cVRo8enfXr1+e+++7Lt771rVx99dXp0KFD+edPPfXUHHvssdl///3zN3/zN9m4cWMef/zx/OY3\nv8nvf//7XHHFFamurk6nTp1y2WWXZe7cuWlsbMycOXPywQ9+MEOGDEllZWWGDh2aKVOmvON6oSSZ\nNWtWjj766Hz6059ORUVFunXrlosuuij3339/kmTevHkZOnRounXrlqqqqnzxi1/MG2+88a5+DytX\nrsykSZPyoQ99KD169EjyZkBdfPHFOeKII1JZWZlzzz03Xbt2zdy5c3f593322WfngAMOKE+/9tpr\n+eIXv5jq6urU19fniCOOyNKlS5Mk69atS1VVVSoqKvL+978/d9xxR8aNG7fL2wZg61yjA1BAO7pG\np3379rnuuuty3nnn5fTTT88nPvGJZsuPOuqo8r/f9773pVOnTlm1alXWrFmTpqam9O3bt7z8retS\nVq1aleeffz5dunRp9liDBg1K8uZpXm+3fPny/Md//EeOPfbYZo91yCGHJHnzFLlTTjmlvKxjx445\n+OCDt7vfDz30UPnxtmzZkjfeeCNnn3127rjjjvJRmOXLl2fKlCn59re/Xd5mqVTKSy+9tN3H3p7D\nDz+82fT73//+ZuFYXV2dxsbGJMnll1+e6667Lj/96U/Tr1+/nHXWWfnoRz+6y9sGYOuEDkABbe8a\nnbc8//zzed/73pcXXnghTU1NzY66bNmy5R3rV1RUpKqqKtXV1XnyySe3+pgVFRU7te3kzf/479ev\n3zZP23r99dfT1NTUbN7WxvV2b78ZwZo1azJ48OD06dMnhx56aLPtfuMb3ygH2Lv152NKknbtmn+c\n7rfftk+YOPfcc3PGGWfkX//1XzNv3rycf/75ufLKK3PhhRfu0ngA2DqnrgHsg1599dVMmjQpN998\nc6qqqnL77bc3W758+fLyvzds2JBXX301hx12WI444ohs2rSp2fLGxsbytTNdu3bNs88+2+yx7rvv\nvvzhD394xxjq6ury9NNPN5v3yiuvZNOmTUmSQw89NP/1X/9VXrZ69ep3dY3OgQcemK985SuZPHly\nXn755WbbffuNGJJ3Hm16u/333z8bN24sT79935N3Xq+zI6tXr86BBx6YT3/607nlllvyt3/7t7nv\nvvve1WMAsGNCB2AfNHny5PTt2zcnnXRSJkyYkH/4h3/IsmXLysvnz5+ff//3f8/rr7+e2267LR06\ndMgJJ5yQY445Jg0NDbn22mvzyiuvZP369fnGN76RL3zhC0mSs846K6tWrcqPfvSjvPHGG5k3b16m\nTJmS6urqVFdXJ0meffbZvPbaaxk2bFjWr1+f73//+2lsbMyLL76YUaNGlY/wnHrqqZk9e3aWLl2a\n1157LTfeeGOqqqre1X5+6lOfyl/+5V9mwoQJ5Xnnn39+fvSjH2Xx4sXZsmVLHn744Zx11lnl/a+u\nrs4LL7xQvhPaEUcckXnz5mXz5s357W9/m3/9139tto2dPYKVvHnN0Kmnnpp58+Zly5YtWb9+fZ5+\n+ukcccQR72q/ANixFofOww8/nE996lMZOnRoLrzwwjzzzDPNlq9YsSI9evTIkCFDMnjw4AwZMqTZ\nnX0A2P22dTOCyy67LI8++mgeeeSRXHnllUmSD3/4w/mf//N/lm8vnSTDhw/PTTfdlN69e2fWrFm5\n+eaby6dn3XDDDWnXrl0GDBiQT3ziE1m/fn1uuOGGJMnBBx+cu+66Kz/84Q/Tu3fvfP/738/UqVPz\ngQ98IAcffHDOOOOMjBs3LjfccEPe//735wc/+EHmz5+fPn365Pzzz0/v3r0zZsyYJMlf/dVfZcCA\nAbngggsyaNCg1NfXp2vXru/6d3HNNddkwYIFmT17dnnfLr744lx++eVpaGjIzTffnBtvvLH8haLn\nnHNOHn300QwcODCbN2/O+PHj85vf/Ca9evXKd77znfz1X/91s8ffmSM6b61TW1ub66+/Pt/73vfS\n0NCQM844IxUVFbn66qvf9X4BsH0VpXfzp6g/s3LlygwbNiz/5//8nxx99NH54Q9/mAcffLDZdx2s\nWLEiF1988XZv0wnA3uP000/PJZdc4poRAN7TWnREp3379vnud7+bo48+OknS0NBQvn0mAABAW2lR\n6HTu3Dn9+vUrT8+fPz89e/Z8x3rr16/P2LFjM3jw4IwaNUoMAezF3u3F9QCwN9ptt5deuHBh7rnn\nntxzzz3N5h9wwAEZNmxYRo4cmQ984AO56667MmbMmMyZM2e7t98EoG041RiAImjRNTpvmTdvXq67\n7rrccsst+fCHP7zD9U844YTcd9996dat2zbXWbx4cUuHBQAAFFxDQ8NW57f4iM4vf/nLTJo0KXfe\neWezb9J+y5o1a7J27dpmd8ppampK+/btd/jY2xo0AADA9g6OtOjcscbGxowfPz4333zzViMnSZYs\nWZIRI0Zk9erVSd784rguXbrs0i1CAQAAdkaLjug8/PDDWb16da644ookb35pWkVFRaZMmZKpU6dm\n2rRpOfnkk3PBBRfkvPPOS2VlZWprazN16lQXuwIAAK1mt1yj0xoWL17s1DUAAGCbttcMbnsGAAAU\njtABAAAKR+gAAACFs9u+MBTg3WpqasrSpUvbehitqlu3bqmsrGzrYQDAPkfoAG1m6dKluejKH6bm\nwEPbeiitYsOaVZkx+YJ07969rYcCAPscoQO0qZoDD02Hg7q09TAAgIJxjQ4AAFA4QgcAACgcoQMA\nABSO0AEAAApH6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACkfo\nAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDC\nEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAAQOEIHQAA\noHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIH\nAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwWhw6Dz/8cD71qU9l6NChufDC\nC/PMM8+8Y52FCxfmnHPOyaBBg3LJJZdk5cqVLd0sAADANrUodFauXJkrr7wy3/3ud/Ozn/0sQ4cO\nzde//vVm62zcuDHjxo3LpEmTMnfu3PTv3z8TJkxo0aABAAC2p0Wh0759+3z3u9/N0UcfnSRpaGjI\n0qVLm62zaNGi1NXVpb6+PkkyfPjwLFiwIBs2bGjJpgEAALapRaHTuXPn9OvXrzw9f/789OzZs9k6\ny5YtS9euXcvTNTU16dSpU5YvX96STQMAAGxTu931QAsXLsw999yTe+65p9n8jRs3pqqqqtm86upq\nR3QAAIBWs1tCZ968ebnuuuty2223lU9je0tNTU02bdrUbF5jY2Nqamp2+LiLFy/eHcMD9lLPPfdc\nWw+h1S1ZsiTr1q1r62EAwD6nxaHzy1/+MpMmTcqdd96Zo4466h3LjzrqqMyePbs8vW7duqxduzZH\nHnnkDh+7oaGhpcMD9mIdO3ZMZr3U1sNoVT169Ej37t3behgAUEjbOzDSomt0GhsbM378+Nx8881b\njZwk6dOnT1588cU88cQTSZLp06enf//+qa6ubsmmAQAAtqlFR3QefvjhrF69OldccUWSpFQqpaKi\nIlOmTMnUqVMzbdq0VFVV5cYbb8zEiRPT2NiYurq6TJkyZbcMHgAAYGtaFDpDhw7N0KFDt7ps2rRp\n5X/36tUrM2fObMmmAAAAdlqLTl0DAADYGwkdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gA\nAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIR\nOgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACg\ncIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcA\nACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7Q\nAQAACkfoAAAAhdOurQcAAMDOa2pqytKlS9t6GK2qW7duqaysbOth8B4ndAAA3kOWLl2ai678YWoO\nPLSth9IqNqxZlRmTL0j37t3beii8xwkdAID3mJoDD02Hg7q09TBgr+YaHQAAoHCEDgAAUDhCBwAA\nKByhAwAAFE6Lb0awefPmXH/99bn77rszf/781NbWNlu+YsWKnHnmmamrq0upVEpFRUV69uyZKVOm\ntHTTAAAAW9Xi0Ln00ktzwgknpKKiYpvr1NbWZvbs2S3dFAAAwE5p8alr48aNy+jRo1MqlXbHeAAA\nAFqsxaFTX1+/w3XWr1+fsWPHZvDgwRk1alThv80XAABoW61+M4IDDjggw4YNy/jx4zNnzpz07ds3\nY8aMyZYtW1p70wAAwD6qxdfo7EinTp1y1VVXladHjBiRW265Jc8++2y6deu23Z9dvHhxaw8PaEPP\nPfdcWw+h1S1ZsiTr1q1r62EABeK9E3ZOq4fOmjVrsnbt2nTt2rU8r6mpKe3bt9/hzzY0NLTm0IA2\n1rFjx2TWS209jFbVo0ePdO/eva2HARSI9074b9s7MNLqp64tWbIkI0aMyOrVq5Mk9913X7p06dIs\nfAAAAHanFh3RWblyZQYOHJiKiopUVFSU/33HHXfk1ltvzbRp03LyySfnggsuyHnnnZfKysrU1tZm\n6tSp270dNQAAQEu0KHRqa2vz1FNPbXXZtGnTyv8eOXJkRo4c2ZJNAQAA7LRWP3UNAABgTxM6AABA\n4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4A\nAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKByh\nAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAK\nR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAA\ngMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4Qgd\nAACgcIQOAABQOEIHAAAoHKEDAAAUTotDZ/PmzZk8eXLq6+uzcuXKra6zcOHCnHPOORk0aFAuueSS\nba4HAACwO7Q4dC699NJ07tw5FRUVW12+cePGjBs3LpMmTcrcuXPTv3//TJgwoaWbBQAA2KYWh864\nceMyevTolEqlrS5ftGhR6urqUl9fnyQZPnx4FixYkA0bNrR00wAAAFvV4tB5K2C2ZdmyZenatWt5\nuqamJp06dcry5ctbumkAAICtavWbEWzcuDFVVVXN5lVXVzuiAwAAtJp2rb2BmpqabNq0qdm8xsbG\n1NTU7PBnFy9e3FrDAvYCzz33XFsPodUtWbIk69ata+thAAXivRN2TquHzlFHHZXZs2eXp9etW5e1\na9fmyCOP3OHPNjQ0tOLIgLbWsWPHZNZLbT2MVtWjR4907969rYcBFIj3Tvhv2zsw0uqnrvXp0ycv\nvvhinnjiiSTJ9OnT079//1RXV7f2pgEAgH1Ui47orFy5MgMHDkxFRUUqKirK/77jjjty6623Ztq0\naamqqsqNN96YiRMnprGxMXV1dZkyZcruGj8AAMA7tCh0amtr89RTT2112bRp08r/7tWrV2bOnNmS\nTQEAAOy0Vj91DQAAYE8TOgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0\nAACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDh\nCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAA\nUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKED\nAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH\n6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKJx2LX2AhQsX5vrrr8+GDRvSpUuXTJo0\nKbW1teXlK1asyJlnnpm6urqUSqVUVFSkZ8+emTJlSks3DQAAsFUtCp2NGzdm3LhxufPOO1NfX58Z\nM2ZkwoQJufXWW5utV1tbm9mzZ7dooAAAADurRaeuLVq0KHV1damvr0+SDB8+PAsWLMiGDRt2y+AA\nAAB2RYtCZ9myZenatWt5uqamJp06dcry5cubrbd+/fqMHTs2gwcPzqhRo7J06dKWbBYAAGC7WhQ6\nGzduTFVVVbN51dXVzY7oHHDAARk2bFjGjx+fOXPmpG/fvhkzZky2bNnSkk0DAABsU4uu0ampqcmm\nTZuazWtsbExNTU15ulOnTrnqqqvK0yNGjMgtt9ySZ599Nt26ddvu4y9evLglwwP2cs8991xbD6HV\nLVmyJOvWrWvrYQAF4r0Tdk6LQueoo45qdpOBdevWZe3atTnyyCPL89asWZO1a9c2O8Wtqakp7du3\n3+HjNzQ0tGR4wF6uY8eOyayX2noYrapHjx7p3r17Ww8DKBDvnfDftndgpEWnrvXp0ycvvvhinnji\niSTJ9OnT079//1RXV5fXWbJkSUaMGJHVq1cnSe6777506dKlWfgAAADsTi06olNVVZUbb7wxEydO\nTGNjY+rq6jJlypQ89dRTmTp1aqZNm5aTTz45F1xwQc4777xUVlamtrY2U6dOTUVFxe7aBwAAgGZa\n/IWhvXr1ysyZM5vNO/jggzNt2rTy9MiRIzNy5MiWbgoAAGCntOjUNQAAgL2R0AEAAAqnxaeuFUFT\nU1Phv8S0W7duqaysbOthAADAHiF0kixdujQXXfnD1Bx4aFsPpVVsWLMqMyZf4DaNAADsM4TO/6/m\nwEPT4aAubT0MAABgN3CNDgAAUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4Qgd\nAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4\nQgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAA\nFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gA\nAACFI3QAAIDCEToAAEDhtGvrAQAAe1ZTU1OWLl3a1sNoVd26dUtlZWVbDwNoQ0IHAPYxS5cuzUVX\n/jA1Bx7a1kNpFRvWrMqMyReke/fubT0UoA0JHQDYB9UceGg6HNSlrYcB0GpcowMAABSO0AEAAApH\n6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDgtDp2FCxfmnHPOyaBBg3LJJZdk5cqVu7QOAADA\n7tKi0Nm4cWPGjRuXSZMmZe7cuenfv38mTJjwrtcBAADYnVoUOosWLUpdXV3q6+uTJMOHD8+CBQuy\nYcOGd7UOAADA7tSi0Fm2bFm6du1anq6pqUmnTp2yfPnyd7UOAADA7tSuJT+8cePGVFVVNZtXXV3d\n7GjNzqyzN9iwZlVbD6HVFHnfmpqasnTp0rYeRqvq1q1bKisr23oYrabI//8s8r4lxX/9ee29dxV5\n395S5H0s8r4V/X0z2bveO1sUOjU1Ndm0aVOzeY2NjampqXlX62zL4sWLWzK8ndbU1JS/u7DnHtlW\n2zgsr7766h77fe5Jzz33XL5171OpOfDQth5Kq9iwZlX+7sKeOeKII9p6KK3Ca++9rcivP6+997pi\nv/Y8f+9dRX7fTPa+984Whc5RRx2V2bNnl6fXrVuXtWvX5sgjj3xX62xLQ0NDS4b3rvTu3XuPbYvd\np2PHjqk58KV0OKhLWw+l1fTo0SPdu3dv62G0Gq+9966iv/689tibef7em4r+vpns+ffO7QVxi67R\n6dOnT1588cU88cQTSZLp06enf//+qa6uflfrAAAA7E4tOqJTVVWVG2+8MRMnTkxjY2Pq6uoyZcqU\nPPXUU5k6dWqmTZu2zXUAAABaS4tCJ0l69eqVmTNnNpt38MEHZ9q0adtdBwAAoLW06NQ1AACAvZHQ\nAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACF\nI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAA\nQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACqddWw8AgPeuDWtWtfUQWkVR9wtgXyJ0ANgl\n3bp1y4zJF7T1MFpNt27d2noIALSA0AFgl1RWVqZ79+5tPQwA2CrX6AAAAIUjdAAAgMIROgAAQOEI\nHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7v0eE9r8jfYF7kfQMAaE1Ch/e0on8ze+Lb2QEAdoXQ4T3N\nN7MDALA1rtEBAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEA\nAApH6AAAAIUjdAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKJx2LfnhhQsX5vrrr8+GDRvSpUuX\nTJo0KbW1tc3WWbFiRc4888zU1dWlVCqloqIiPXv2zJQpU1o0cAAAgG3Z5dDZuHFjxo0blzvvvDP1\n9fWZMWNGJkyYkFtvvfUd69bW1mb27NktGigAAMDO2uVT1xYtWpS6urrU19cnSYYPH54FCxZkw4YN\nu21wAAAAu2KXQ2fZsmXp2rVrebqmpiadOnXK8uXL37Hu+vXrM3bs2AwePDijRo3K0qVLd3WzAAAA\nO7TLobNx48ZUVVU1m1ddXf2OIzoHHHBAhg0blvHjx2fOnDnp27dvxowZky1btuzqpgEAALZrh9fo\nPPTQQ7n++utTUVGRJOUbCpx//vnZtGlTs3UbGxtTU1PTbF6nTp1y1VVXladHjBiRW265Jc8++2y6\ndeu23W0vXrx4p3cEAAD2Zs8991xbD6HVLVmyJOvWrWvrYSTZidAZOHBgBg4c+I758+fPb3aDgXXr\n1mXt2rU58sgjm623Zs2arF27ttlpbk1NTWnfvv0OB9fQ0LDDdQAA4L2gY8eOyayX2noYrapHjx7p\n3r37Htve9g6M7PKpa3369MmLL76YJ554Ikkyffr09O/fP9XV1c3WW7JkSUaMGJHVq1cnSe677750\n6dKlWfifXqLpAAARQklEQVQAAADsTrt8e+mqqqrceOONmThxYhobG1NXV1f+bpynnnoqU6dOzbRp\n03LyySfnggsuyHnnnZfKysrU1tZm6tSp5VPhAAAAdrcWfWFor169MnPmzHfM79mzZ6ZNm1aeHjly\nZEaOHNmSTQEAAOy0XT51DQAAYG8ldAAAgMIROgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7Q\nAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACF\nI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACgcoQMAABSO0AEAAApH6AAAAIUjdAAAgMIROgAA\nQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFI7QAQAACkfoAAAAhSN0AACAwhE6AABA4QgdAACgcIQO\nAABQOEIHAAAoHKEDAAAUjtABAAAKR+gAAACFI3QAAIDCEToAAEDhCB0AAKBwhA4AAFA4QgcAACic\ndm09AAAA2FdsWLOqrYfQava2fRM6AACwB3Tr1i0zJl/Q1sNoVd26dWvrIZQJHQAA2AMqKyvTvXv3\nth7GPsM1OgAAQOEIHQAAoHCEDgAAUDhCBwAAKByhAwAAFE6LQmfz5s2ZPHly6uvrs3Llym2ut3Dh\nwpxzzjkZNGhQLrnkku2uCwAA0FItCp1LL700nTt3TkVFxTbX2bhxY8aNG5dJkyZl7ty56d+/fyZM\nmNCSzQIAAGxXi0Jn3LhxGT16dEql0jbXWbRoUerq6lJfX58kGT58eBYsWJANGza0ZNMAAADb1KLQ\neStetmfZsmXp2rVrebqmpiadOnXK8uXLW7JpAACAbWr1mxFs3LgxVVVVzeZVV1c7ogMAALSadjta\n4aGHHsr1119fvg6nVCqloqIif/M3f5Phw4fvcAM1NTXZtGlTs3mNjY2pqanZ4c8uXrx4h+sAAAD8\nuR2GzsCBAzNw4MBd3sBRRx2V2bNnl6fXrVuXtWvX5sgjj9zuzzU0NOzyNgEAgH1bq5+61qdPn7z4\n4ot54oknkiTTp09P//79U11d3dqbBgAA9lEVpe3dMm07Vq5cmYEDB6aioiKvv/562rdvn4qKisyd\nOzd//OMfM3Xq1EybNi1J8vjjj+faa69NY2Nj6urqMmXKlBx88MG7dUcAAADessuhAwAAsLdq9VPX\nAAAA9jShAwAAFI7QAQAACmeHt5dmx4YPH54NGzZkzpw5O72svr4+RxxxRCorK9PU1JT3v//9+dKX\nvpSTTjqpvHz+/Pmpra3dI/uwr6mvr8+ZZ56Z733ve83mf+1rX8tPfvKT/O53v0uS/Pu//3uuv/76\nrFq1Kk1NTTnooIPy5S9/OQ0NDVmxYkUGDBiQo48+Osl/f8fU8ccfn4aGhtx+++2pqKjIqlWr0r59\n+3Tq1CkVFRW5+uqr06dPnz2+z0VwzTXX5N/+7d+SJM8//3wOPfTQVFVV5YUXXsgJJ5yQu+66q7zu\n+PHjs2rVqvJNUZLkq1/9ampra/OLX/wijY2NeeONN/L888/n6KOPTqlUyjHHHJPvf//7Of3005O8\n+eXGpVIpW7ZsSX19fa6++mo3Umllb39v3LJlS+rq6vL1r389Xbt2fcfyrb13smf8/ve/z0UXXZSf\n/vSnOfzww5Mkf/zjH/PJT34yd9xxRz784Q/n7rvvzo9//OM0NTVly5YtOfHEE/OFL3whnTt3TpJc\ndNFFefbZZ/OLX/yi/F19STJz5sz83d/9XWbMmJFevXq1yf4V3c5+BibJXXfdlfvvvz+bN29OU1NT\n+vXrly996Uvp0KFDHnjggXzjG9/I4YcfnjfeeCMVFRU5/fTT87/+1/9Kx44d9/Ru7XPuueee/NM/\n/VOz19gXv/jFHHTQQVm9enWuu+66LFmyJEnSrl27fP7zn8+5556bJPvO51yJFvn9739fGj58eOmz\nn/1s6cknn9zpZfX19aWVK1eWpxcvXlzq3bt36ZVXXikvf+mll1p/B/ZRf/EXf1EaNGhQ6bXXXivP\ne+ONN0qf/OQnS/X19eV5/fr1K82fP788PXfu3NKJJ55YamxsLL3wwgulj3zkIzvc1le/+tXSD37w\ng927A5ROP/300hNPPFEqld58rR133HGlzZs3l5efccYZpf79+5eamprK8/r37196/PHHy9Pbeg5P\nO+208mOXSqXSli1bSt/85jdL48aNa41d4W3+/L3xhhtuKI0ePXqby//8vZM95wc/+EHpkksuKU9f\ndtllpZtuuqlUKr35vJ177rnl56qpqal0/fXXl4YOHVratGlTqVQqlT73uc+VTjvttNIvf/nLZo87\nevTo0mmnnVZ67LHH9tCe7Ht29jPw29/+dukzn/lMadWqVaVSqVTauHFj6Wtf+1rpwgsvLJVKpdL9\n999fGjFiRHn9devWlSZMmFA6++yzy88zrePGG2/c6mts2LBhpU2bNpUuv/zy0ne+853y+n/4wx9K\nJ554Yvm/R/eVzzmnrrXQAw88kGHDhuXss8/OAw88sNPLSqVSSm+74d3HPvax1NXV5cknnywvp3X1\n7t07//Iv/1KeXrBgQT760Y+Wp1955ZW8/PLLOfbYY8vzzjzzzDz44IOpqqrao2Plnd7+GvrQhz6U\njh07ll8/K1asyPve97586EMfym9+85skybJly/Lqq6/muOOO2+nHf0tFRUX69++f//zP/9zNe8Gf\n+/P3xj59+mTFihXbXP7n753sOaNGjcrq1avzwAMP5JFHHskf/vCHjBkzJq+++mruueeefOc738mh\nhx6aJNlvv/1yxRVXpKqqKjNnziw/ximnnJIHH3ywPL127do8//zz+eAHP7jH92dfs6PPwFdffTX/\n+3//73zrW9/K//gf/yPJm3/9v/rqq/PXf/3XW33MDh065JprrkmHDh2aPc/sXmvXrs3dd9+91dfY\n/vvvn5kzZ+bpp59Oz549yz9z1FFHZfbs2c3+m2Zf+JwTOi2wZcuWzJ07N2effXbOOuusPPLII9m8\nefMOl23L5s2bs//++++JoZNk8ODB+dnPflae/tnPfpbBgweXpzt37pyPfvSjueiii/LjH/84L7zw\nQpKU3/DZu/Tt2zcLFy5MkixatCgf+9jH0tDQUD7V7bHHHkvv3r3Trt27P2O3sbExP/nJT3L88cfv\n1jGzfa+//nr++Z//uXyKxbZ472wblZWVmTx5cm644YZce+21mTx5ctq3b59f//rX+cAHPpC6urp3\n/Mxpp52Wxx57rNn0ggUL8sYbbyRJ/u///b/5xCc+scf2YV+2o8/AX//61znssMNy5JFHNvu5/fff\nP/3799/uY/fv3z+LFi3ancPlbZ588skcfvjhW32N9e/fP4899lhOPfXUTJgwIbfddlt++9vfplQq\nlU8b3Zqifs4JnRb4xS9+kY9+9KPp1KlTOnbsmF69euWRRx7Z4bKtmT9/fl5++eV87GMf21PD36dV\nVFTkxBNPzNNPP51XX301mzZtypNPPpk+ffo0+wvHnXfemTPOOCMzZszIwIEDM2zYsDz00EPl5Zs3\nb86QIUMyZMiQDB48OEOGDMnNN9/cFru0z+vbt285ahYtWpTevXvnhBNOaDavb9++O/14V1xxRYYM\nGZIzzzwzJ554YmprazN+/PhWGTvNXXzxxRk8eHD69euXJUuW5Jxzztnmut4721b37t3zwQ9+MO3a\ntcuHP/zhJMmaNWu2+R9UhxxySNasWVOePuCAA/Kxj30s/+///b8kyezZszN48GBnNbSynfkMXLNm\nTQ455JBdevwOHTpk/fr1u3PIvM3atWu3+xpbt25dvvzlL+fyyy/PggUL8pnPfCannHJK/v7v/77Z\nuvvC55ybEbTAAw88kF/84hfp3bt3SqVSmpqasmHDhgwcODD333//Npe95eKLLy5fcNulS5fcfvvt\ned/73teGe7RvqaioyMCBAzN79uwcfPDB6du3byorK5ut06FDh4wdOzZjx47NK6+8kp/85Cf50pe+\nlJkzZ6aqqirt2rXL7Nmz22gPeLu+ffvmqquuysaNG/P444/nyiuvTMeOHfPb3/42r7/+eh577LGM\nGTNmpx/vhhtuyPHHH5833ngjgwYNymmnnZbq6upW3APeMmPGjPLpGL/61a9y4YUX5qc//Wn5P7r+\n/L1z2rRp3jvbyI9//ONUV1fnmGOOye23357Ro0fnoIMOyqpVq7a6/ssvv/yOC52HDh2aBx98MMcd\nd1xefvnl1NfX74mh7/N29Bl40EEHZeXKlbv02CtWrNju0QNapra2druvscMOOyxJcu655+bcc89N\nY2Njfv7zn+eb3/xmDjnkkHzmM59Jsm98zgmdXbR27do8/vjjefzxx8tvDE1NTfn4xz+eV155ZZvL\nVq9enYMOOihJ8w9z2saQIUPyve99L507d855552XJOW7/6xcuTIrVqwo/6W4c+fOGTVqVObMmZNn\nnnkmH/nIR9ps3LzTIYcckqOPPjo/+9nP0rFjx/KHbH19fWbNmpX99tsvxxxzzE4/3lt/1Wzfvn3G\njh2bb33rW7n//vtbZew09/a/5p9wwgnp0qVLFi9enDPPPDOJ9869xUsvvZSbbropP/rRj9K+fft8\n+tOfzplnnpnjjz8+a9asyX/+53/mL/7iL5r9zM9//vNcfPHFzeZ9/OMfz8SJEzNr1qzyc8yesb3P\nwOOOOy5/+tOf8tvf/jZ/+Zd/Wf6ZzZs35/vf//42/3C0ZcuWzJs3L2PHjm39HdhH1dfX509/+tM2\nX2MXXXRR5s+fn49//ONJ3ry2atCgQfn1r3+d3//+9+V194XPOaeu7aJZs2alT58+zf76UVlZmVNO\nOSWzZs3KSSed9I5l/fr1a3Y+rEPzbeet3/3xxx+flStX5umnn07v3r2bLfuv//qvjBkzpnxrxiR5\n6qmn8tJLL5Uv2PQc7l1OOumkzJgxIyeeeGJ5Xq9evTJjxoxtnra2M8/h2Wefnddffz0//elPd9tY\n2TnPPvtsli1blm7dupXned3tHb72ta9l5MiR6dq1aw477LCMGTMmX/va19KhQ4eMHj06X/nKV8rX\nNjY1NeWGG27Ili1bMmTIkGaPs//++6dfv3658847m10jQuvZmc/Ajh075pJLLslXvvKVLF++PEmy\ncePGfP3rX8/vfve78k153v563LBhQ6666qoceOCBnstW1LFjx3z+85/f5mtswIAB+epXv9osWl5+\n+eU8+uij5ef5zxX1c84RnV30z//8z+/4q1SSDBgwILfeemtGjhz5jmWf+MQncuutt+Zzn/tcs+8M\n2JqKiooMGDAgyX9/P8ttt932rq4xYNve/vsfOHBgNmzY8I5lxx13XK699tpMnDgx69evz5YtW3LI\nIYfkpptuyuGHH54VK1bs8Hmk9Wztd3/yySdn+vTpzf6S2Lt370ydOjUjRozY6cf583n77bdfLrvs\nskyePDlDhgxx4XsrqqioKJ+aViqVUlVVlW984xvlo3Fec3uHf/zHf8zq1avzV3/1V+V5n/vc5/Lg\ngw/m3nvvzciRI1NVVZVLL7202Xd8TJ8+vXxDkLc/l0OHDs1//Md/lIPW89y6duYzMEnGjh2bTp06\n5dJLL82WLVuy3377ZcCAAZk4cWJ5nSeffDJDhgxJU1NTNm3alAEDBuSOO+7Ifvv5W3pruuyyy9Kx\nY8fy++Xrr7+e3r175+67706HDh3Kd2X7h3/4hyRv/kHhc5/7XM4444wk+87nXEXJn8YAAOA96dvf\n/nZee+21ZgHKm+Q2AAC8Rw0dOjRz587NH//4x7Yeyl5H6AAAwHvURz7ykXz+85/POeeck6uvvrqt\nh7NXceoaAABQOI7oAAAAhSN0AACAwhE6AABA4QgdAACgcIQOAABQOP8ferqghXNImswAAAAASUVO\nRK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f32582ce090>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "draw_asset_barplot(expected_returns, 'Expected Returns');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since our goal is to maximize a function directly proportional to asset returns, we'll use **`opt.MaximizeAlpha`** as our objective function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Objective that maximizes ``weights.dot(alphas)`` for an alpha vector.\n",
      "\n",
      "    Ideally, ``alphas`` should contain coefficients such that ``alphas[asset]``\n",
      "    is proportional to the expected return of ``asset`` for the time horizon\n",
      "    over which the target portfolio will be held.\n",
      "\n",
      "    In the special case that ``alphas`` is an estimate of expected returns for\n",
      "    each asset, this objective simply maximizes the expected return of the\n",
      "    total portfolio.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    alphas : pd.Series[Asset -> float] or dict[Asset -> float]\n",
      "        Map from assets to alpha coefficients for those assets.\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    This objective should almost always be used with a `MaxGrossExposure`\n",
      "    constraint, and should usually be used with a `PositionConcentration`\n",
      "    constraint.\n",
      "\n",
      "    Without a constraint on gross exposure, this objective will raise an error\n",
      "    attempting to allocate an unbounded amount of capital to every asset with a\n",
      "    nonzero alpha.\n",
      "\n",
      "    Without a constraint on individual position size, this objective will\n",
      "    allocate all of its capital in the single asset with the largest expected\n",
      "    return.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.MaximizeAlpha.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<quantopian.optimize.objectives.MaximizeAlpha at 0x7f3256f1cad0>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "maximize_returns = opt.MaximizeAlpha(expected_returns)\n",
    "maximize_returns"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Objective` classes can render themselves in mathematical notation via the `.math` property:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/latex": [
       "\n",
       "\\begin{align*}\n",
       "&\\underset{\\boldsymbol{w}}{\\text{maximize}} && \\boldsymbol{\\alpha} \\cdot \\boldsymbol{w} \\\\\n",
       "&\\text{where} &&\\boldsymbol{\\alpha} = [0.441, -0.331, \\ldots, -0.909]\n",
       "\\end{align*}\n"
      ],
      "text/plain": [
       "<qexec.optimize.latex.LatexRepr at 0x7f32582d1690>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "maximize_returns.math"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The documentation for `MaximizeAlpha` warns us that we need to put a constraint on the gross exposure of our portfolio or else the optimizer will try to allocate an unbounded amount of capital, so we'll add a **`MaxGrossExposure`** constraint as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Constraint on the maximum gross exposure for the portfolio.\n",
      "\n",
      "    Requires that the sum of the absolute values of the portfolio weights be\n",
      "    less than ``max``.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    max : float\n",
      "        The maximum gross exposure of the portfolio.\n",
      "\n",
      "    Examples\n",
      "    --------\n",
      "    ``MaxGrossExposure(1.5)`` constrains the total value of the\n",
      "    portfolios longs and shorts to be no more than 1.5x the current portfolio\n",
      "    value.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.MaxGrossExposure.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def optimal_portfolio_constrained_exposure_only():\n",
    "    \"\"\"Calculate the optimal portfolio if we're only constrained by gross exposure.\"\"\"\n",
    "    \n",
    "    # Our objective function.\n",
    "    objective = opt.MaximizeAlpha(expected_returns)\n",
    "    \n",
    "    # A list containing our constraints.\n",
    "    constraints = [opt.MaxGrossExposure(1.0)]\n",
    "    \n",
    "    return opt.calculate_optimal_portfolio(objective, constraints, empty_portfolio)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzMAAAHvCAYAAABgyIHLAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzt3XlcVPXi//E3iEIIhWiugWJm0+ICCKJpoqYiZpa2WdKm\nPVyybmp1K0u0RS01l6ysS4V5s/u9qelVSctEiwI1/Anp1ajMDRUzNVAWBc7vD7+eLyPLYIH40dfz\nL88yx89wGGZec86ccbMsyxIAAAAAGMa9pgcAAAAAAH8GMQMAAADASMQMAAAAACMRMwAAAACMRMwA\nAAAAMBIxAwAAAMBIxAwAY7zzzju67777qmXbMTExev3116tl25V1+PBhDRo0SMHBwfr5559dru9w\nOLR+/XpJUlRUlP7nf/7nT//fRUVFuvfee/XJJ5/86W1caP7qz6Qic+fO1aBBg6pl2zitMo/JnTt3\nqkuXLtq7d+95GhWAC41HTQ8AwMVpx44dmjdvnjZu3Kjc3Fz5+/srMjJSI0eO1JVXXlnp7cyfP1/3\n33+/PDw8NHLkSI0cObIaR122uXPn6q233lKdOnUkSW5ubmrUqJH69++v4cOHq3bt2n9qu5mZmUpP\nT1ffvn0lSQkJCfrtt9+UkpIiT0/Pc9rWqlWr/tQYznjzzTfl7e2twYMH2/O2bt2qd999V5s2bVJB\nQYEaNmyoXr16aeTIkapbt+5f+v8qo+S+/zP+6s/EFTc3tzLnb9y4UQ888ECpfWhZltzc3LRhwwZ5\neXlV69hq2qeffqpPP/3UjvKWLVvqzjvv1L333lul/0/Lli316KOPaty4cfr3v/9dpdsGYAaOzACo\ncsnJyRo8eLAcDodWrFihLVu2aP78+crJydGgQYOUlZVVqe0cOXJEU6dO1cmTJ6t5xK7dcMMNSktL\nU1pamrZs2aKZM2dqyZIlevvtt895W2e+q3j16tX6/PPP7fnZ2dlq2LDhOYfMX3Xs2DHNnz9fo0eP\ntud9++23GjJkiNq1a6cvvvhCqampmj59ujZs2KCYmBgVFRVV65gupH3/Z5yJljO/M2lpaUpPT1da\nWpoxIfNnv1P7hRde0Lx58/T4449r48aN2rRpk8aOHasPPvhAzzzzTBWPUho8eLAyMzO1Zs2aKt82\ngAsfMQOgSlmWpQkTJujuu+/WiBEj5O/vL0kKCAjQtGnT1LhxY02dOlWStGHDBl133XVav369evfu\nrfbt22v48OE6fvy4srKydPPNN0uSOnXqpEWLFjmd2rNx40YFBwcrMTFRPXv2VHBwsKZOnaqMjAzd\ncccdCg4O1mOPPabCwkJJ0smTJzVhwgR17dpVoaGhuvvuu7Vly5Y/fT+vv/56xcTE6Msvv7TnrV27\n1v6/u3fv7hQ6c+fO1bBhw/Tcc8+pffv2mjdvnqZPn66vvvpK7dq10xtvvKF33nlH27ZtU7t27ZSR\nkaGcnBw999xzuvnmmxUcHKyHH3643NPPevTooY8//tjeB/PmzVOfPn3Uvn179e/fv8IXekuWLFGz\nZs0UEhJi337ixIkaPHiwhg0bpssvv1zu7u5q06aN4uLi5HA4dPjwYUlSVlaWHn/8cXXq1EkdOnTQ\nqFGj7FjNzMyUw+HQd999Z/9c7rvvPnv577//rscff1wREREKDQ3VkCFDtGPHjjL3/Weffaa+fftq\n9uzZCg4O1t69e13u05I/k+eee04vv/yyXnvtNXXs2FGdO3fW/Pnz7XWzs7P19NNPq2vXrgoJCdHw\n4cOVmZlpL1+3bp369u2rkJAQ/e1vf9OJEydc/YpUGAMzZ850Ok1tz549at++vb7//ntt3Lix1ONi\nxIgROn78uL1+Rb9ru3bt0iOPPKKwsDCFhYVp2LBhOnDggP1z+Nvf/uY0lpKnK8bExGj69OkaNGiQ\nHnroIUnSwYMHNWrUKHXq1ElhYWEaO3as/vjjjzLv14YNG7RkyRLNnTtXXbt2lYeHh2rVqqXOnTvr\nrbfe0ooVK/T1119LOv2YGDlypN5//3116dJF4eHheu2110ptMzU1VTfeeKOOHj1qzysqKlLHjh21\nevVq1alTRwMGDNA///nPcn/eAC5exAyAKrVt2zbt27dPMTExZS6PiYlRYmKiTp06JTc3N1mWpSVL\nlmjx4sVas2aNDh48qOnTp6tRo0b64IMPJJ1+gXTnnXdKcj61Jz8/X99++60SEhI0ZcoUxcfHa8aM\nGXr//fe1ZMkSff3110pMTJQkxcXFacOGDVq2bJk2bdqk8PDwUi/qzlVhYaFq1aolScrIyNDjjz+u\nkSNH6vvvv9fMmTM1f/58LVmyxF7/v//9r9q0aaO0tDSNGDFCAwYM0C233KK0tDSNHTtWI0eOtI8A\ntW7dWuPHj1dmZqaWLl2q5ORkNW3aVCNGjHD5jvnChQu1cOFCzZ49W6mpqXrggQf05JNPateuXWWu\n/9133ykiIsKePrMPy/p80hVXXKHJkyerUaNGkqTHHntMderU0Zo1a7R27VoVFhZq3LhxTrf56KOP\nFBcXp8TERB07dkzx8fGSpFmzZik/P1+JiYlKSUlRaGioJk6cWO6+P3LkiIqLi5WamqqAgIBz3qef\nf/65rr32Wn333XcaPXq0pk2bZr8of/bZZ5WXl6eVK1cqKSlJDRo0sO9HTk6OxowZo8GDB2vjxo26\n5557nPZreSraT4899pjy8vLsU6MmT56sgQMHqkOHDvZtSz4uDhw4oOnTp0ty/bv28ssvq2nTpkpO\nTtbXX3+tK6+80r5tZSQkJCg2NtaOvZEjR6pRo0ZKTEzUl19+qRMnTuill14q87ZffPGFQkJCdN11\n15Vads011ygiIsLp9L8tW7bo1KlTSkxM1LRp0/Thhx8qIyPD6XahoaFq2rSpEhIS7HkbNmyQZVnq\n3r27JKljx476f//v/xl7JA/An0fMAKhSe/bsUe3atXXVVVeVubxVq1YqKCiw3513c3PT0KFD5evr\nqwYNGuj+++/XV1995XSbil4UDh48WJ6enurRo4ek0+/G+/v7KygoSC1atLBfwI8YMUJLliyRv7+/\n3N3d1bdvXx06dMg+wnAuiouL9cMPP+iTTz5R//79JUmLFy9Wx44d1bt3b9WqVUvt27dXdHS00wsw\ny7IqfQGD7OxsffnllxozZoz8/f3l5eWlcePGad++fUpPT6/wtosWLdL9998vh8OhWrVq6a677lLz\n5s31xRdflLn+Tz/9pNatW9vTZ/ZhQEBAhf/Pjh07tG3bNv39739X3bp1dfnll2v06NFKTU11+rne\nc889ql+/vvz8/NSxY0f98ssvkk5HgoeHh+rUqaPatWtrzJgx+te//uX0f5Tc9zk5OXr00Ufl7n76\nqetc92njxo11++23q1atWoqKilJhYaF2796tI0eOaO3atXryySd1+eWXy9vbW0899ZTS0tK0a9cu\nffPNN/L09FRMTIw8PDzUuXNndezYscKfjWVZ6tSpk9q1a6d27dqpbdu2ateuncaPHy9JqlOnjl5+\n+WXNnj1by5cv144dO5wisKLHhavftezsbNWuXVseHh667LLLNGXKFM2YMaPC8ZZ0ww03qG3btpKk\nH374QRkZGXrqqafk5eUlPz8/PfHEE1q1apXy8/NL3XbPnj0KCgoqd9tXX311qQ/rn/ncWbdu3eTl\n5WX/fpQ0YMAA/ec//7Gnv/jiC/Xu3dv+HNs111yjgoIC7dmzp9L3E8DFgQsAAKhylmXZH3YuT8ll\nLVq0sP/dtGlTHTlypNLn6zdu3FiS7Bc1DRs2tJfVqVNHBQUFkqTffvtNr776qjZt2qQTJ07Y26/s\nO7lnTv+SJHd3dzVt2lT33Xefhg4dKknau3evrr76aqfbNG/eXCkpKaXGWhlnTnEquU1/f3/VrVtX\nmZmZ9ljKUtZYAgMDnU6bKunYsWO64oornOZVZh/u27dPdevWdfqZN2/eXJZlKTMzUw0aNJAkNWvW\nzF7u5eVlvwgeNmyYRo4cqW7duqlr167q2bOnbrnllnL/Px8fH/n4+NjT57pPSwb2mc+tFBQU2C+u\nS572ZVmWPDw8dODAAWVlZalJkyZOP4ugoCDt37+/3LFW5oP+oaGh6t27t5555hm99dZbpS6qUN7j\nwtXv2ujRo/X0009r/fr16tq1q/r27et05M2Vpk2b2v/eu3evioqK1LlzZ3vemd+LQ4cOKTAwsNTt\ni4uLK/1/nf1z9fLysh+zJd1+++166623tGfPHgUEBGjNmjWaNWuWvbxevXqSTh+9A3BpIWYAVKmW\nLVva73iXfDF2xs6dO3XZZZepcePG9ovrkh8mP/OCtKIX0SWdeZe+vOkzxowZo9q1a2vp0qVq1KiR\nduzYoTvuuKNS/4d0+t3qRYsWlbu8vBfQJe/HmVPSKuOvnC5TmbFUtOzMPty5c2epF82VHWPJ7ZW3\nT2688UatXbtWSUlJSkxM1HPPPafly5dr9uzZZa5/9s/vXPdpefff09NTbm5uSkxMtD/jVVJ6err9\n2aszKhPblVln79698vb21q+//lpqWXmPC1f7t1u3blq/fr3WrVuntWvXasSIEbrvvvvK/PB9WeFR\n8ufs6ekpLy+vSn++LCgoqMIjh7/++qtatmxpT5f3u3G2Zs2aKSwsTMuXL1dERITq1Kljn5In/d99\n/7MXLQBgLk4zA1ClHA6HgoKCnD5cXdLHH3+sqKgopxdMJU87yczMPKdLN1fWDz/8oHvuucf+rMfW\nrVurdPuBgYHauXOn07ydO3eW+c51ZQQEBMiyLKdTbrKysnTixIkyI/HssZx9qs7OnTvVvHnzMtf3\n8/PTsWPH7GmHw6HmzZvbn1spKScnR7fddpu2b9+ugIAAnThxQocOHbKX//LLL3J3d7dPUasooHJy\ncuTu7q7u3bvrpZde0ttvv63Vq1eX++Hys1XVPr3qqqvk7u6uH3/80Z5nWZb9ofmGDRs63UdJlfoe\nIFeWLl2qffv2KT4+Xm+//Xap06/Ke1y4+l07evSoLrvsMvXt21fTpk3TxIkT7e/bqVOnjtPpYbt3\n765wjM2bNy91+lZ+fn65R0Cio6PtK7edbefOnfruu+/sUzPP1R133KEvv/xSq1ev1q233uq07Mx4\nyopRABc3YgZAlXvppZe0dOlSTZkyRb///ruk06ckPf7448rKytJTTz1lr2tZluLj45WTk6NDhw7p\nk08+sU81OnOKzs6dO5WXl/eXxtSsWTOlpaWpsLBQycnJWr16tSRV+jLRrtx+++3asGGD1qxZo6Ki\nIn3//fdauXJlhV+s6OnpqQMHDignJ6fUpY79/f3VrVs3zZ49W0ePHtXx48c1bdo0XXvttbr++usr\nHMsdd9yhhQsXKiMjQ6dOndKCBQt06NAh+/tsznbNNdeU+tD1xIkTtWLFCr3yyiv6/fffVVxcrLS0\nND388MNq2LChHA6H2rRpo2uuuUavv/66cnNz9fvvv+vNN99Ut27d7NN+Knqn/O6779acOXOUn5+v\nwsJCpaenq169erriiisqte+rap/6+Pjo1ltv1fTp07V//34VFBRozpw5euCBB2RZljp37qzc3Fx9\n/PHHOnXqlNavX6/U1FSX263ovh85ckSvvfaaYmNj1aZNG915553252nO3La8x0VFv2sFBQXq06eP\nFi5cqFOnTqmgoEBbt261Q7ZFixZKS0vTgQMHdPz4cb333nsVXgq8VatW6tChg1555RUdOXJEx48f\n10svvVTuhRbat2+v++67TyNGjNAXX3yhU6dOqaioSElJSXrkkUd07733Oh1RORe9e/fWnj17tGzZ\nMt12221Oy3766Sd5enqWG+wALl6VipnCwkJNmTJFDoej3CeJ5ORkDRw4UFFRURo6dGiVvUAAYJ4O\nHTroX//6lw4cOKBbb71V7du314MPPqjGjRtr0aJFTu+eurm5qXfv3ho0aJB69eqlJk2aaOzYsZKk\n6667TsHBwRo8eHClLrt69lGAktOxsbFau3atwsPD9eGHH2rq1Km66aabNHToUGVkZFT6tLbytG3b\nVlOmTNGcOXMUFhamSZMm6cUXX1SvXr3Kvc2tt96qvXv3qnv37jp48GCp5VOnTlW9evXUv39/9enT\nR6dOnVJcXFyZ96/kvx9++GENGDBAo0aNUufOnfX555/ro48+KvczOzfddJM2bNjgNC8iIkILFy7U\n/v37FR0drdDQUI0fP15RUVGaN2+e/f+99dZbys7OVo8ePTRw4ED7Etxljetss2fP1ubNm3XTTTep\nU6dOSkxM1DvvvCOpcvu+on36448/ys3NrdKn1r3wwgtq1aqVBgwYoK5duyo9PV3vvvuu/QWpb7zx\nhubPn6/w8HAtWrSo3Kv1lVTyAgAlLwKwZs0avfrqq+rUqZM6deokSXriiSe0e/duffrpp/bYyntc\nVPS75unpqblz52rJkiUKDw/XzTffrN27d9tXM7vzzjvVtm1bRUdH28/ZJT+HVNbPa/r06fLw8LA/\n03T8+PEKLyjw4osvasyYMXr33XcVHh6usLAwzZkzR0888YQmTJhQ4c+svN9pSfL29lbv3r3VrFkz\ntWrVymnZmUu1n/nsHIBLh5tViRNMH330UXXo0EGzZs3SunXr7EP6Z+Tl5alnz5764IMP5HA4tGDB\nAn377beaN29etQ0cgPk2btyoBx98UJs3b9Zll11W08O5ZB09elQ9e/bU+++/r+Dg4JoeziWPx0X5\nYmJiFB0drcGDB9vzTp48qR49emjixIkVXkACwMWpUkdmxo0bp+HDh5d7yDwlJUWBgYFyOBySTl8R\nJikpSbm5uVU3UgBAtahXr54eeughzZ07t6aHApSpoKBA8fHx2rt3r26//XanZQsXLlSzZs0IGeAS\nVamYORMp5dm1a5fT9xF4e3vLz8+P670DgCEee+wx5ebm6pNPPqnpoQClhISEaPHixXrzzTedjlbt\n3LlTcXFx5/Q9OgAuLlVyaea8vLxSHyD08vLiyAyACoWHh2v79u01PQzo9OV4CZkLA4+L0rZt21bm\n/JYtWyopKek8jwbAhaRKYsbb27vUl1zl5+fL29u7wttV5mowAAAAAC5toaGhZc6vkpgJCgpSQkKC\nPZ2Tk6Ps7GyX34VQ0cAAXBwyMjI0fOoa+dRr5nplAx0/mql3n71FrVu3rumhAABwUaroAEiVfM9M\nRESE9u/fr82bN0uS4uPjFRkZaX9PAAAAAABUNZdHZrKystSrVy/7ev1n/v3+++9r3rx5iouLk6en\np2bOnKlJkyYpPz9fgYGBmjp16vkYPwAAAIBLlMuYadSokdLT08tcVvLL28LCwrRs2bKqGxkAAAAA\nVKBKTjMDAAAAgPONmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZ\nAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGI\nGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICR\niBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACA\nkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAA\ngJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAA\nAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYA\nAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIG\nAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRi\nBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAk\nYgYAAACAkSoVM8nJyRo4cKCioqI0dOhQZWVllVpn8eLF6tevn/r166ehQ4dq165dVT1WAAAAALC5\njJm8vDyNGzdOkydP1qpVqxQZGanY2FindXbu3Klp06YpPj5eK1euVK9evfT8889X26ABAAAAwGXM\npKSkKDAwUA6HQ5I0aNAgJSUlKTc3117nl19+UYsWLXTllVdKkiIiIvTzzz9X05ABAAAAoBIxs2vX\nLgUEBNjT3t7e8vPz0549e+x5wcHB2rdvn3766SdJ0urVq3XTTTdVw3ABAAAA4DQPVyvk5eXJ09PT\naZ6Xl5fTkZkGDRpo7Nixuv322+Xj46O6detqwYIFVT9aAAAAAPhfLo/MeHt7q6CgwGlefn6+vL29\n7ent27frrbfe0tq1a7VhwwY9+eSTGjFiRNWPFgAAAAD+l8sjM0FBQUpISLCnc3JylJ2drRYtWtjz\nkpOTFRISokaNGkmSoqOj9cwzz+jo0aOqV69ehdtPTU39k0MHYILdu3fX9BCq3datW5WTk1PTwwAA\n4JLjMmYiIiI0fvx4bd68WSEhIYqPj1dkZKS8vLzsdYKCgrRw4UIdO3ZMfn5+Wrduna688kqXISNJ\noaGhf+0eALig+fr6SisO1vQwqtWNN96o1q1b1/QwAAC4KFV08MNlzHh6emrmzJmaNGmS8vPzFRgY\nqKlTpyo9PV1z5sxRXFycunfvrm3btumee+6Ru7u7fHx8NGfOnCq9EwAAAABQksuYkaSwsDAtW7bM\naV79+vUVFxdnT48ePVqjR4+u2tEBAAAAQDlcXgAAAAAAAC5ExAwAAAAAIxEzAAAAAIxEzAAAAAAw\nEjEDAAAAwEjEDAAAAAAjETMAAAAAjETMAAAAADASMQMAAADASMQMAAAAACMRMwAAAACMRMwAAAAA\nMBIxAwAAAMBIxAwAAAAAIxEzAAAAAIxEzAAAAAAwEjEDAAAAwEjEDAAAAAAjETMAAAAAjETMAAAA\nADASMQMAAADASMQMAAAAACMRMwAAAACMRMwAAAAAMBIxAwAAAMBIxAwAAAAAIxEzAAAAAIxEzAAA\nAAAwEjEDAAAAwEjEDAAAAAAjETMAAAAAjETMAAAAADASMQMAAADASMQMAAAAACMRMwAAAACMRMwA\nAAAAMBIxAwAAAMBIxAwAAAAAIxEzAAAAAIxEzAAAAAAwEjEDAAAAwEjEDAAAAAAjETMAAAAAjETM\nAAAAADASMQMAAADASMQMAAAAACMRMwAAAACMRMwAAAAAMBIxAwAAAMBIxAwAAAAAIxEzAAAAAIxE\nzAAAAAAwEjEDAAAAwEjEDAAAAAAjETMAAAAAjETMAAAAADASMQMAAADASMQMAAAAACMRMwAAAACM\nRMwAAAAAMBIxAwAAAMBIxAwAAAAAIxEzAAAAAIxEzAAAAAAwEjEDAAAAwEjEDAAAAAAjETMAAAAA\njETMAAAAADASMQMAAADASMQMAAAAACMRMwAAAACMRMwAAAAAMBIxAwAAAMBIxAwAAAAAIxEzAAAA\nAIxEzAAAAAAwEjEDAAAAwEjEDAAAAAAjETMAAAAAjETMAAAAADBSpWImOTlZAwcOVFRUlIYOHaqs\nrKxS6xw6dEiPPPKIevTooQEDBuj777+v8sECAAAAwBkuYyYvL0/jxo3T5MmTtWrVKkVGRio2NrbU\n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\nAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRi\nBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAk\nYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABg\nJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAA\nYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAA\nAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEA\nAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgB\nAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImY\nAQAAAGAkYgYAAACAkYgZAAAAAEYiZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABiJ\nmAEAAABgJGIGAAAAgJGIGQAAAABGImYAAAAAGImYAQAAAGAkYgYAAACAkSoVM8nJyRo4cKCioqI0\ndOhQZWVl/al1AAAAAKCquIyZvLw8jRs3TpMnT9aqVasUGRmp2NjYc14HAAAAAKqSy5hJSUlRYGCg\nHA6HJGnQoEFKSkpSbm7uOa0DAAAAAFXJZczs2rVLAQEB9rS3t7f8/Py0Z8+ec1oHAAAAAKqSh6sV\n8vLy5Onp6TTPy8vL6ahLZda5EGRkZNT0EKpV69ata3oI1YZ9Z7bcPw7V9BCqzcV83864mB9/F/tj\n72LedxL7z3QX8/5j350/LmPG29tbBQUFTvPy8/Pl7e19TuuUJzU1tbJjhQv8LM11se+7t5/vX9ND\nqFY5OTkX/T68WLHfzMb+Mxv7z1wX0r5zGTNBQUFKSEiwp3NycpSdna0WLVqc0zplCQ0NPfcRAwAA\nAIAq8ZmZiIgI7d+/X5s3b5YkxcfHKzIyUl5eXue0DgAAAABUJTfLsixXK23atEmvvPKK8vPzFRgY\n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\nURo/frx8fHw0fPhwPfPMM/ZnDYuKijRjxgwVFxcrOjraaTt16tRRly5d9MEHHzh9ZgPVpzLPgb6+\nvho6dKieeeYZ7dmzR5KUl5enF198UTt27LAvhFPy8Zibm6sXXnhBV1xxBfuyGvn6+urBBx8s9zHW\ns2dPPfvss05hcvjwYX377bf2fj7bxfo8x5GZCvznP/8p9e6SJPXs2VPz5s3TI488UmrZLbfconnz\n5mnIkCFO19Qvi5ubm3r27Cnp/76/5L333junc/5RvpI//169eik3N7fUsvbt2+uVV17RpEmTdPz4\ncRUXF6tBgwaaNWuWmjRposzMTJf7EdWnrJ/9TTfdpPj4eKd3BMPDwzVnzhw9/PDDld7O2fPc3d31\nxBNPaMqUKYqOjubD5tXIzc3NPo3Msix5enrqpZdeso+q8Zi7MPz73//W0aNH9dBDD9nzhgwZouXL\nl+vjjz/WI488Ik9PT40cOdLpOzDi4+Pti3CU3Jf9+vXTf//7Xzta2c/VqzLPgZI0evRo+fn5aeTI\nkSouLpa7u7t69uypSZMm2ets2bJF0dHRKioqUkFBgXr27Kn3339f7u68J16dnnjiCfn6+tp/L0+e\nPKnw8HDNnz9fPj4+9tXO3n33XUmn3zQYMmSIevfuLenSeZ5zs3j7CwAAALhgvf766zpx4oRTZOI0\nkhoAAAC4gPXr10+rVq3Sb7/9VtNDueAQMwAAAMAF7IYbbtCDDz6ogQMHasKECTU9nAsKp5kBAAAA\nMBJHZgAAAAAYiZgBAAAAYCRiBgAAAICRiBkAAAAARiJmAAAAABjp/wMuSN6W52l5mgAAAABJRU5E\nrkJggg==\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f32614a54d0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "constrained_exposure_pf = optimal_portfolio_constrained_exposure_only()\n",
    "draw_asset_barplot(constrained_exposure_pf, 'Optimal Portfolio (Constrained Exposure Only)');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With no constraints other than maximizing expected return, the optimizer decided to allocate all of our capital to a single long position in `TWTR`. While this might be an acceptable portfolio for someone of a gambling disposition, we'd probably rather not put all our eggs in one basket.\n",
    "\n",
    "We can force the optimizer to diversify our portfolio by adding a **`PositionConcentration`** constraint:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Constraint enforcing minimum/maximum position weights.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    min_weights : pd.Series[Asset -> float] or dict[Asset -> float]\n",
      "        Map from asset to minimum position weight for that asset.\n",
      "    max_weights : pd.Series[Asset -> float] or dict[Asset -> float]\n",
      "        Map from asset to maximum position weight for that asset.\n",
      "    default_min_weight : float, optional\n",
      "        Value to use as a lower bound for assets not found in ``min_weights``.\n",
      "        Default is 0.0.\n",
      "    default_max_weight : float, optional\n",
      "        Value to use as a lower bound for assets not found in ``max_weights``.\n",
      "        Default is 0.0.\n",
      "    etf_lookthru : pd.DataFrame, optional\n",
      "        Indexed by constituent assets x ETFs, expresses the weight of each\n",
      "        constituent in each ETF.\n",
      "\n",
      "        A DataFrame containing ETF constituents data. Each column of the frame\n",
      "        should contain weights (from 0.0 to 1.0) representing the holdings for\n",
      "        an ETF. Each row should contain weights for a single stock in each\n",
      "        ETF. Columns should sum approximately to 1.0. If supplied, ETF\n",
      "        holdings in the current and target portfolio will be decomposed into\n",
      "        their constituents before constraints are applied.\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    Negative weight values are interpreted as bounds on the magnitude of short\n",
      "    positions. A minimum weight of 0.0 constrains an asset to be long-only. A\n",
      "    maximum weight of 0.0 constrains an asset to be short-only.\n",
      "\n",
      "    A common special case is to create a PositionConcentration constraint that\n",
      "    applies a shared lower/upper bound to all assets. An alternate constructor,\n",
      "    :meth:`PositionConcentration.with_equal_bounds`, provides a simpler API\n",
      "    supporting this use-case.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.PositionConcentration.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "        Special case constructor that applies static lower and upper bounds to\n",
      "        all assets.\n",
      "\n",
      "        ::\n",
      "\n",
      "            PositionConcentration.with_equal_bounds(min, max)\n",
      "\n",
      "        is equivalent to::\n",
      "\n",
      "            PositionConcentration(pd.Series(), pd.Series(), min, max)\n",
      "\n",
      "        Parameters\n",
      "        ----------\n",
      "        min : float\n",
      "            Minimum position weight for all assets.\n",
      "        max : float\n",
      "            Maximum position weight for all assets.\n",
      "        \n"
     ]
    }
   ],
   "source": [
    "print opt.PositionConcentration.with_equal_bounds.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Allow 15% of our liquidation value to be in any single short position.\n",
    "# Allow 30% of our liquidation value to be in any single long position.\n",
    "# Try changing these parameters to see how they change the results!\n",
    "MIN_POSITION_WEIGHT = -0.15\n",
    "MAX_POSITION_WEIGHT = 0.30\n",
    "\n",
    "def optimal_portfolio_constrained_exposure_and_concentration():\n",
    "    \"\"\"Calculate the optimal portfolio if we're constrained by exposure and concentration.\"\"\"\n",
    "    objective = opt.MaximizeAlpha(expected_returns)\n",
    "    constraints = [\n",
    "        opt.MaxGrossExposure(1.0),\n",
    "        opt.PositionConcentration.with_equal_bounds(\n",
    "            min=MIN_POSITION_WEIGHT, \n",
    "            max=MAX_POSITION_WEIGHT,\n",
    "        )\n",
    "    ]\n",
    "    return opt.calculate_optimal_portfolio(objective, constraints, empty_portfolio)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false,
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzoAAAHvCAYAAACc3aoBAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzs3Xt8FNX9//H3QmCX5WIIFfCSAKK4rXINhAREA4oEEbnE\nG2BQChbipcqlVeSrMVohFiRyE+o3akBF2yLKQ4lRbqZFE5DwhQgtQsFwN6gBE0w2kjC/P/hlmiVX\nskDg+Hr+lZn57MyZmZ3JvnfOzDosy7IEAAAAAAapV9cNAAAAAICzjaADAAAAwDgEHQAAAADGIegA\nAAAAMA5BBwAAAIBxCDoAAAAAjEPQAVCphQsXauTIkedk3jExMfrzn/98TuZdU99//72io6PVtWtX\n/ec//6m23uPxKC0tTZIUFRWlv/71r7VedklJie6991698847tZ7HhcbfbVKV+fPnKzo6+pzMG/91\n8OBBeTyeGh0PkDZt2qTOnTvL6/X6NZ/c3FzdeOON2rp161lqGQBJCqjrBgA4O3bs2KFFixZp48aN\nKigoUFBQkCIjIxUbG6tLL720xvNZvHixRo0apYCAAMXGxio2NvYctrpi8+fP14IFC9SwYUNJksPh\nUKtWrTR48GCNHz9eDRo0qNV8Dx48qKysLA0cOFCSlJKSou+++04ZGRlyOp1nNK/U1NRataHUvHnz\n5Ha7NWLECHvctm3b9Je//EVffvmlioqK1LJlS/Xv31+xsbFq3LixX8uribL7vjb83SbVcTgcFY7f\nuHGjRo8eXW4fWpYlh8OhDRs2yOVyndO2maSy7Vxq7969euWVV/T555/r+PHjCgoK0o033qhHHnlE\nv/rVr85TK2vn9HNAbaxevVrXXHON2rRpo+7du5+VcBIUFKRnnnlGEydO1Mcff3zG5yMAFeOKDmCA\n9PR0jRgxQh6PRx999JG2bNmixYsXKz8/X9HR0crJyanRfHJzc5WQkKCff/75HLe4etddd522bt2q\nrVu3asuWLUpMTNTy5cv1yiuvnPG8Sn8X+ZNPPtHHH39sj8/Ly1PLli3P+4eKY8eOafHixXrkkUfs\ncZ9//rnuu+8+de7cWZ9++qkyMzM1a9YsbdiwQTExMSopKTmnbbqQ9n1tlAaa0vfM1q1blZWVpa1b\nt140IedC+f3uqtqxY8cO3XnnnQoKCtIHH3ygLVu26NVXX9XBgwd19913Kz8//zy29Mydfg4oq6bb\nf86cOfrmm2/OZrMkSbfccouaNm1q1FVeoK4RdICLnGVZeuaZZ3T33XdrwoQJCgoKkiQFBwdr5syZ\nat26tRISEiRJGzZs0K9//WulpaXp1ltvVZcuXTR+/HgdP35cOTk5uvHGGyVJERERWrZsmU93oY0b\nN6pr165at26dbr75ZnXt2lUJCQnauXOnhg0bpq5du+rhhx9WcXGxJOnnn3/WM888oz59+ig0NFR3\n3323tmzZUuv1/M1vfqOYmBitWrXKHrd27Vp72X379vUJQfPnz9e4ceM0depUdenSRYsWLdKsWbO0\nZs0ade7cWbNnz9bChQu1fft2de7cWTt37lR+fr6mTp2qG2+8UV27dtWYMWMq7cLTr18/vf322/Y+\nWLRokQYMGKAuXbpo8ODBWr16daXrsnz5cl1xxRXq1q2b/fpnn31WI0aM0Lhx49SsWTPVq1dPHTt2\nVFJSkjwej77//ntJUk5Ojh599FFFRESoe/fueuihh+wgW9rt6IsvvrC3y8iRI+3pP/zwgx599FGF\nh4crNDRU9913n3bs2FHhvn///fc1cOBAzZkzR127dtX+/fur3adlt8nUqVP1/PPP68UXX1TPnj3V\nq1cvLV682K7Ny8vTH/7wB/Xp00fdunXT+PHjdfDgQXv6Z599poEDB6pbt2567LHH9NNPP1X3Fqny\ng2piYqJP17d9+/apS5cu2rRpkzZu3FjuuJgwYYKOHz9u11f1XsvOztZvf/tb9ejRQz169NC4ceN0\n+PBhezs89thjPm0p2wUyJiZGs2bNUnR0tB544AFJ0rfffquHHnpIERER6tGjhyZNmqQff/yx0nVb\nsmSJBgwYoK5du2rAgAF677337Gnz589XbGysXnvtNd1www0KCwvTiy++aE/Pzc3VuHHj1K1bN91+\n++3avHlzlVd0XnjhBUVEROiJJ56wr95cffXVeuWVV9S7d299++23klTtseTxePTpp59q5MiR6tq1\nq4YMGaJdu3bZ0z///HN7e99xxx329pJOnYvuvfdehYaGqk+fPnr55ZerXN/SLrKvvvqqZs2apdWr\nV6tz5846ceJEhdt/+/btiomJUVhYmHr16qUnnnhCBQUFkqTbb79du3bt0qOPPqonn3xSGzdulMfj\nUWFhoST/jk9Juvvuu+1jCID/CDrARW779u06cOCAYmJiKpweExOjdevW6cSJE3I4HLIsS8uXL9d7\n772n1atX69tvv9WsWbPUqlUrvf7665JOBaI777xTkm83Fq/Xq88//1wpKSmaMWOGkpOT9dJLL+m1\n117T8uXL9Y9//EPr1q2TJCUlJWnDhg1asWKFvvzyS4WFhZX7wHemiouLVb9+fUnSzp079eijjyo2\nNlabNm1SYmKiFi9erOXLl9v1//rXv9SxY0dt3bpVEyZM0JAhQ3TLLbdo69atmjRpkmJjY+0rRx06\ndNC0adN08OBBffDBB0pPT9fll1+uCRMmVPtN79KlS7V06VLNmTNHmZmZGj16tB5//HFlZ2dXWP/F\nF18oPDzcHi7dhxXdD3XJJZdo+vTpatWqlSTp4YcfVsOGDbV69WqtXbtWxcXFmjx5ss9rlixZoqSk\nJK1bt07Hjh1TcnKyJOnll1+W1+vVunXrlJGRodDQUD377LOV7vvc3FydPHlSmZmZCg4OPuN9+vHH\nH+vaa6/VF198oUceeUQzZ860P7A/+eSTKiws1MqVK7V+/Xr96le/stcjPz9fEydO1IgRI7Rx40bd\nc889Pvu1MlXtp4cffliFhYX629/+JkmaPn26hg8fru7du9uvLXtcHD58WLNmzZJU/Xvt+eef1+WX\nX6709HT94x//0KWXXmq/tiZSUlIUFxdnB8HY2Fi1atVK69at06pVq/TTTz/pueeeq/C1mzZt0osv\nvqhZs2bp//7v/zR16lQ9/fTTPu+9LVu26MSJE1q3bp1mzpypN954Qzt37pR0Krh4vV6lpaUpOTnZ\nJySdLjc3V19++aVGjRpVblqDBg30/PPP65prrpGkGh1Lr732mhISEpSenq5mzZpp3rx5kk6FhUce\neUQPPvigNm3apPHjx+uxxx5TTk6OcnJyNGHCBN1zzz3atGmTkpOT9eGHH9r7taL1ff3117Vz5079\n7ne/05AhQ9S/f39t3brV7gJ7+vafOHGirrvuOm3YsEEfffSRtm3bpldffVWS9NFHH0k6FahKv0Aq\ne4705/iUpJ49e+rAgQM6dOhQpfsBQM0RdICL3L59+9SgQQNdeeWVFU6/+uqrVVRUZH9r6HA4NHbs\nWDVt2lS/+tWvNGrUKK1Zs8bnNVV9YBwxYoScTqf69esn6dS3+EFBQWrXrp3atm1rf8CaMGGCli9f\nrqCgINWrV08DBw7UkSNH7CsTZ+LkyZP66quv9M4772jw4MGSpPfee089e/bUrbfeqvr166tLly66\n7bbblJKS4rMeNX2YQl5enlatWqWJEycqKChILpdLkydP1oEDB5SVlVXla5ctW6ZRo0bJ4/Gofv36\nuuuuu9SmTRt9+umnFdbv2rVLHTp0sIdL92FwcHCVy9mxY4e2b9+uJ554Qo0bN1azZs30yCOPKDMz\n02e73nPPPWrRooUCAwPVs2dP7d69W9KpABEQEKCGDRuqQYMGmjhxot59912fZZTd9/n5+XrwwQdV\nr96pfxVnuk9bt26toUOHqn79+oqKilJxcbH27t2r3NxcrV27Vo8//riaNWsmt9utKVOmaOvWrcrO\nztY///lPOZ1OxcTEKCAgQL169VLPnj2r3DaWZSkiIkKdO3dW586d1alTJ3Xu3FnTpk2TJDVs2FDP\nP/+85syZow8//FA7duzw+QBa1XFR3XstLy9PDRo0UEBAgBo1aqQZM2bopZdeqrK9ZV133XXq1KmT\nJOmrr77Szp07NWXKFLlcLgUGBur3v/+9UlNTK7zhvXv37tqwYYM6duwoSYqMjFSjRo30r3/9y6eu\n9N62m266SS6Xy35PrFmzRmPGjLHXu/SqRkUOHDggh8Ohtm3bVrk+NT2WBg8erJCQELlcLt100012\nmz7++GNdeeWVuu2221S/fn0NGjRICQkJql+/vj766CNdddVVGjZsmBwOh9q3b6+YmJhyQbiy9a1I\n2e0vSStWrNCkSZPkcDgUFBSkiIgIbdu2rcp1lvw/PiWpffv2cjgcPle3ANQeDyMADGBZln3jdWXK\nTiv7QeXyyy9Xbm5ujfunt27dWpLsBwW0bNnSntawYUMVFRVJkr777ju98MIL+vLLL/XTTz/Z86/p\nPSClXcokqV69err88ss1cuRIjR07VpK0f/9+tW/f3uc1bdq0UUZGRrm21kRpt6my8wwKClLjxo11\n8OBBuy0VqagtISEhPl2xyjp27JguueQSn3E12YcHDhxQ48aNfbZ5mzZtZFmWDh48aHcluuKKK+zp\nLpfL/oA8btw4xcbG6qabblKfPn10880365Zbbql0eU2aNFGTJk3s4TPdp2XDd+l9MkVFRdq/f78k\n+XQlsyxLAQEBOnz4sHJycnTZZZf5bIt27dpV+S13TR46EBoaqltvvVV//OMftWDBgnIPeKjsuKju\nvfbII4/oD3/4g9LS0tSnTx8NHDjQ54pddS6//HL77/3796ukpES9evWyx5W+L44cOaKQkBCf1xYX\nF2v+/Pn65JNP7PaeOHHCZ5+cvi1dLpeKiop07Ngxeb1en/dLu3btqj0XnDx5ssrpNT2Wyi63UaNG\n9vt0//79PtOkU0/0k059KfCvf/3L53i0LMvnIQiVrW9lym5/6VS3uYULF+qbb75RcXGxTp48aXcz\nrYq/x6d06n18ySWXKDc3t9rlAageQQe4yF111VX2N+UVfdO6Z88eNWrUSK1bt7Y/gJS9sb30Q011\nT1oqVfrtfmXDpSZOnKgGDRrogw8+UKtWrbRjxw4NGzasRsuQTn3LumzZskqnV/bhuux6lHZzqwl/\nbsKvSVuqmla6D/fs2VPuA3VN21h2fpXtk+uvv15r167V+vXrtW7dOk2dOlUffvih5syZU2H96dvv\nTPdpZevvdDrlcDi0bt06+56ysrKysux7vUrVJIjXpGb//v1yu90V3kxe2XFR3f696aablJaWps8+\n+0xr167VhAkTNHLkSP3xj38s95qKQkLZ7ex0OuVyuWp8P9v8+fOVkpKihQsX6rrrrpMkhYWF+dRU\n9n4oXa+y633y5MlK91vp+WXXrl267LLLKm1TTY+lytpV2sW2Ii6XSzfccIPdlexM5luZstt/z549\nevzxxzVlyhT76vWMGTP073//u9r5+Ht8lq29UB5MAVzs6LoGXOQ8Ho/atWvnc6N3WW+//baioqJ8\n/pmXfqMunfr29UweP11TX331le655x773pKadP04EyEhIdqzZ4/PuD179pT7xrumgoODZVmWTzeS\nnJwc/fTTT9V21QkJCSnXNWbPnj1q06ZNhfWBgYE6duyYPezxeNSmTRv7Ppmy8vPzdccdd+jf//63\ngoOD9dNPP+nIkSP29N27d6tevXp2t7eqwlV+fr7q1aunvn376rnnntMrr7yiTz75pMob3cs6W/v0\nyiuvVL169fT111/b4yzLsm/gb9mypc86Sjorv+vywQcf6MCBA0pOTtYrr7zicxxIlR8X1b3Xjh49\nqkaNGmngwIGaOXOmnn32Wfv3hBo2bOjzjf3evXurbGObNm1UVFSkffv22eO8Xm+l3/B/9dVX6tu3\nrx1y9u/fr7y8vCqXUSooKMi+ilaqqu3crFkzRURE6I033ig37cSJExo5cqT+8Y9/+HUsSaeOxdOD\n6F//+ld7m5/erSs3N7fKKzZn4t///rcCAgL0wAMP2E9j3L59e41e6+/xKZ06Dn788ccKvwAAcOYI\n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\nm6b33ntPO3bskCRt375dM2fO1JEjR1RSUqLmzZvrD3/4g0JDQ3Xw4EHdfPPNuuqqqyT99zemunbt\nqtDQUP3v//6vHA6Hjhw5ogYNGigwMFAOh0PPPPOMwsPDz/s6m+DZZ5/Vhg0bJEn79+9Xy5Yt5XQ6\ndeDAAXXv3l1vvPGGXfvUU0/pyJEjSkpKssc9+eSTatWqlf75z3/K6/XqxIkT2r9/v6666ipZlqWr\nr75a8+bNU79+/SSd+hFky7J08uRJeTwePfPMM2rRosX5XelfmLLnxpMnTyokJERPP/20goODy02v\n6NyJ82Pnzp2KiYnRBx98YD9F9bvvvtMdd9yh1157Tb/5zW+0ePFiLVu2TCUlJTp58qR69uypxx57\nTEFBQZKkmJgYffPNN/rnP/9p/wSFJK1YsUJPPPGE3nzzTfXo0aNO1s90Nf0fKElvvPGGli9fruLi\nYpWUlOiGG27QpEmT1KRJE73//vt67rnndNlll+nEiRNyOBzq16+fHn74YTVt2vR8r9YvzpIlS/T3\nv//d5xh7/PHH1bx5cx09elQvvPCCtm3bJkkKCAjQ/fffr7vuukuSfjn/5yz4ZefOnVZ0dLR1zz33\nWFu2bKnxNI/HY+Xk5NjDmZmZVlhYmJWbm2tP//bbb8/9CvxCXXvttVZUVJT1008/2eNOnDhh3XHH\nHZbH47HH3XDDDVZaWpo9nJqaavXs2dPyer3WgQMHrOuuu67aZT355JPWwoULz+4KwOrXr5+1efNm\ny7JOHWtdunSxiouL7em33nqrFRkZaZWUlNjjIiMjrS+//NIermwf9u3b1563ZVnWyZMnreeff96a\nPHnyuVgVlHH6ufGll16yxo8fX+n008+dOH8WLlxojR071h7+/e9/b7388suWZZ3ab3fddZe9r0pK\nSqyZM2dagwYNsoqKiizLsqz77rvP6tu3r/XFF1/4zHf8+PFW3759rY0bN56nNfnlqen/wD//+c/W\n3XffbR05csSyLMsqLCy0pk2bZo0aNcqyLMtavny5NWbMGLs+Pz/fiouLs4YMGWLvZ5wbiYmJFR5j\ngwcPtoqKiqyJEydas2bNsuv37Nlj9ezZ0/48+kv5P0fXNT+9//77Gjx4sIYMGaL333+/xtMsy/J5\nzHa3bt0UEhKiLVu22NNxboWFhenTTz+1h9evX6+OHTvaw7m5ufr+++/VuXNne9yAAQP04Ycfyul0\n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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3256323f50>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "constrained_concentration_pf = optimal_portfolio_constrained_exposure_and_concentration()\n",
    "plot = draw_asset_barplot(\n",
    "    constrained_concentration_pf, \n",
    "    \"Optimal Portfolio (Constrained Exposure and Concentration)\",\n",
    "    {'ylim': (-MAX_POSITION_WEIGHT - 0.1, MAX_POSITION_WEIGHT + 0.1)},\n",
    ")\n",
    "plot.axhline(MIN_POSITION_WEIGHT, color='r', linestyle='dashed')\n",
    "plot.axhline(MAX_POSITION_WEIGHT, color='r', linestyle='dashed');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With position size constraints, our portfolio is significantly more diverse than before.  The optimizer was forced to cap the long allocations to `TWTR` and `GM` at 30% of NLV (Net Liquidation Value), and it was forced to cap the short allocations to `MCD` and `BK` at 15% NLV.  The remaining 10% under the gross exposure cap went to `AAPL`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding Sector Constraints\n",
    "\n",
    "Eyeballing these distributions a bit, we might notice that we're heavily exposed to the technology and food service industries.  We can confirm that concern by using `Pipeline` to grab sector codes for our portfolio."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from quantopian.pipeline import Pipeline\n",
    "from quantopian.pipeline.classifiers.morningstar import Sector\n",
    "from quantopian.pipeline.filters import StaticAssets\n",
    "from quantopian.research import run_pipeline\n",
    "\n",
    "\n",
    "def get_sector_names(stocks, date):\n",
    "    \"\"\"Get sector codes for a set of stocks for a particular date.\"\"\"\n",
    "    result = run_pipeline(\n",
    "        Pipeline({'sector': Sector()}, screen=StaticAssets(stocks)),\n",
    "        start_date=date,\n",
    "        end_date=date\n",
    "    )\n",
    "    # result will have a pd.MultiIndex whose first level just contains `date`.\n",
    "    # Drop the first level so that we just get assets as our index.\n",
    "    sector_codes = result['sector'].reset_index(level=0, drop=True)\n",
    "    \n",
    "    # Convert integral sector codes to human-readable strings by doing a lookup\n",
    "    # from Sector.SECTOR_NAMES, which is a dict mapping codes to strings.\n",
    "    #\n",
    "    # This is purely for readability of the charts below. \n",
    "    # We could proceed with the rest of the notebook using sector codes and it would work just fine.\n",
    "    return sector_codes.map(Sector.SECTOR_NAMES)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Equity(24 [AAPL])              TECHNOLOGY\n",
       "Equity(4707 [MCD])      CONSUMER_CYCLICAL\n",
       "Equity(5061 [MSFT])            TECHNOLOGY\n",
       "Equity(8347 [XOM])                 ENERGY\n",
       "Equity(19675 [BP])                 ENERGY\n",
       "Equity(45815 [TWTR])           TECHNOLOGY\n",
       "Equity(48215 [QSR])     CONSUMER_CYCLICAL\n",
       "Name: sector, dtype: object"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sector_names = get_sector_names(universe, '2016-10-07')\n",
    "sector_names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzMAAAH+CAYAAACoQlD1AAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzs3Xlc1HXix/E3ioKoaVJYmahrq+NmXniglhymoubdWt55\ntK1GZWl5x5qGRxqpmed619a2oWiardVDdy2Pwops1YzyCBPTTFAugc/vD3981wlwsHDhk6/nX853\nPvOdz3yBmXn5/c53vIwxRgAAAABgmTIlPQEAAAAA+CWIGQAAAABWImYAAAAAWImYAQAAAGAlYgYA\nAACAlYgZAAAAAFYiZgDgGtqyZYvatGmj/v37exy7fv16BQcHS5I++eQTNW7cWBkZGdd6iteFRYsW\nFeln8EuEh4fr1VdfvSbrBgBcGTED4LoUHh6uhg0bqnHjxmrcuLFatGihfv366aOPPvpV633vvfd0\n9OhR5/KyZcvUrVs3vfbaa0W6vZeXlySpefPm+vzzz+Xr6/uL57Jr1y4NHz5cLVq0ULNmzdStWzct\nXrxY2dnZv3id/yt79+7VF1988avWsXr1auexjhw5ssg/g5KUlpammTNnqkOHDmrSpImCgoI0fPhw\nffbZZ8Wy/uLYrgBQmhAzAK5bEydO1Oeff67PP/9cH374obp27apHHnlEiYmJV72uvO8fnjdvnr79\n9ltneUpKigIDA4ttzkUVGxurUaNGqXPnzvrXv/6lPXv2aNKkSVq/fr0iIyP/5/O5WitWrFBCQkKB\n1xXlu55//PFHzZw5U1lZWcU9tWtq7NixOnDggP7617/qs88+0/bt29WgQQMNGzZMp0+f/tXrv9J2\n9YTv2AZQGhEzAK5bl785K1++vAYOHKjatWtr+/btkqSsrCzNnDlT4eHhatKkiR544AF98sknzm3C\nw8O1dOlSderUSRMnTtR9992nw4cP67HHHtP48eMVHh6upKQkzZgxQw888IAk6dNPP9WDDz6ooKAg\n3X333Xr++ecL3FOyZ88euVwupaenS5KSk5P12GOPqXXr1mrevLlGjRql5OTkAh/X+fPn9fzzz2vM\nmDG6//77VaFCBZUrV07BwcFasmSJqlevrvPnz0uSEhMTNWzYMLVq1UqtWrXSuHHjnOv27t2roKAg\nffjhh+rcubOaNm2qRx55RBcuXHDua9WqVQoPD1dQUJCGDh2qI0eOONe99tpr6tq1q5o0aaLOnTtr\ny5YtznWDBg3SkiVL9MwzzygoKEghISF65513JEl/+tOftH37ds2YMUODBg2SJLlcLq1du1ahoaF6\n+eWXJUmbN29Wt27d1LRpU4WFhWnJkiXOtmrXrp0kqXXr1vrHP/6hl19+WX369HHu/0o/h/Xr16t7\n9+6Ki4tzHtvTTz99xTfzZ8+e1cMPP6ymTZvqvvvu065duyRJQ4cOVXR0tNvYVatWqVu3bgWu58MP\nP1Tfvn2dAK5cubLGjh2rqKgolSlz6SU7KytL06dPV3h4uJo2baoBAwbo4MGDzjqOHz+uhx9+WM2a\nNVNYWJiWLVtW6Ha90u9VUlKSXC6X3nzzTbVu3VqxsbGFPn4AKDEGAK5DYWFhZt26dfmWd+nSxaxc\nudIYY8zMmTPNfffdZ44fP26ysrLM/PnzTfPmzU1KSoqzjvvuu88cPXrUuX39+vXN9u3b3e7n1Vdf\nNcYYc+bMGdOkSROzevVqk5WVZb7++msTHh5u5s+fb4wxJjY21gQHBxtjjNmzZ49xuVwmLS3NGGNM\nnz59zFNPPWXOnz9vzp07Zx5++GEzcODAAh/bO++8Yxo2bGgyMzOvuA0yMzNNSEiImTVrlsnMzDQn\nT540vXv3NuPGjXPm0KBBAzN+/HiTmppqTpw4YVq1amXWrl1rjDFm27ZtJjg42Bw4cMBcvHjRPPfc\nc+a+++5zrmvVqpX54osvTG5urtm+fbu56667TGJiojHGmIEDB5p27dqZDz/80GRnZ5s5c+aYVq1a\nFbjd8rbrwIEDzZkzZ4wxxnz33XfmzjvvNP/85z+NMcZ88cUXpmHDhuajjz5y237p6enGGGMWLFhg\n+vTpU+SfQ1BQkJk2bZpJT083Bw4cMHfeeaf54IMPCtyOYWFh5p577jHx8fEmMzPTvPjii6Zp06bm\n/PnzZsOGDaZt27YmNzfXGd+vXz+zdOnSAtfVq1cv8+CDD5pvv/220J/b9OnTzQMPPGCSk5NNZmam\nmTdvngkNDTXZ2dnGGGN69Ohhpk+fbjIzM83hw4dNy5Ytzbvvvlvgdi3o92rAgAHONq5fv7554okn\nzPnz5wudDwCUJPbMAICk9PR0rV27VidOnFCHDh0kSW+99ZYeeeQR3X777SpXrpxGjRql3Nxc/fvf\n/3Zu17ZtW4+HkZn//x/9TZs2KSAgQIMHD1a5cuVUt25d9evXz22PRUEOHjyoL7/8UuPGjVPFihV1\nww03KDIyUp988kmBhx4dP35ct912m8qXL3/F9f773/9WamqqRo8erfLly6t69eoaMWKE3n33XWfO\nxhgNHTpUlSpV0q233qpGjRo5h+HFxsaqS5cucrlc8vb21uOPP65HH31U2dnZevPNN9W7d281bNhQ\nXl5eCgkJUdu2bRUXF+fcf6NGjdSmTRuVLVtWHTp00Llz5/Tjjz/m2255OnXqpGrVqkmSatSooV27\ndjk/q4YNG6pOnTr5Pg/y83VIRfs5XLhwQaNHj5avr69cLpdq1ap1xcMPQ0JC1KxZM5UvX16PPPKI\nsrKy9Mknn6hjx45KS0vTzp07JUk//PCDEhISCt0zM2vWLKWlpalz587q2LGjJk6cqK1btzp7jYwx\nio2N1ciRIxUQEKDy5csrMjJSFy5c0O7du3XgwAEdOnRIjz76qMqXL6877rhDCxYsUO3atfNtk8J+\nr+Lj491+r3r06KGKFSsW+tgBoCR5l/QEAKCkzJgxQ7Nnz5Yk+fr6ql69elqxYoVq1KihlJQUpaSk\nqG7dus74smXLqkaNGvruu++cZbfddluR7++7775zW58k1apVS0lJSR5vV7FiRQUEBLjdzhijpKQk\n3XTTTfluk5OT43E+x48f1+233+4WPbVq1VJGRobOnDnjLKtRo4bzb19fX+cMa8ePH1eLFi2c66pU\nqaKIiAhJ0rFjx/Thhx86Z/kyxsgYoypVqjjjb7/9duffFSpUkKQrnr3t1ltvdbv86quvKjY2VqdO\nnVJubq6ys7OL9BmZovwcbrjhBlWqVKnAx12Qy9fn5+cnf39/nTp1ShUqVFBERIQ2btyoe+65R9u2\nbVOzZs10yy23FLie3//+94qLi9PBgwe1e/du7d27V+PGjdPtt9+udevWKScnRxcuXNBjjz3mnCzC\nGKPc3Fx9//33On/+vCpUqKCqVas662zZsmWh26Eov1c/3+4AUJoQMwCuWxMnTiz0dL1XelOc9yZS\nuhQ4RVXYOi9f36+ZS546dero5MmTSktLk5+f369eb95nNQoak5ubW+B1vr6+Gj16tEaMGFGk+ygK\nb+//vmS9+eabWrp0qRYuXKhWrVqpTJky6tWrV5HWU5SfQ2GPuTA/H2+McSKxV69eeuSRR5SRkaFt\n27ape/fuHtfncrnkcrn00EMPKTk5Wb1799Zrr72mIUOGSLoUcnfddVe+223btq3IH9Qv6s//8u0O\nAKUNh5kBuG5d6U2fv7+/Klas6HZoUVZWlpKSktwO2bkagYGB+uabb9yWJSYmejxMrWbNmrpw4YJO\nnTrldrsyZcqoZs2a+ca3bdtWFStW1KpVq/Jdl5SUpIiICCUnJyswMFBJSUlub2oTExNVsWJF+fv7\ne3w8NWvWdDtzW2pqqlasWKG0tDQFBgbq0KFDbuO///77Yjsj1hdffKFmzZqpdevWKlOmjM6fP+92\nSuwr+aU/hyu5fDukpaXpxx9/dPa+tGjRQv7+/tq0aZM+//xzZ+/Vzx0+fFjTpk3LF4jVq1dX3bp1\ndf78eVWqVEk33nij2wf+JTl7lWrWrKmMjAy3k0Ps2LGjwFOOF+X36mqDEwD+14gZACiAl5eXevTo\noaVLl+rEiRPKyMjQvHnzVKFCBd19992F3s7Hx0dHjhxxzgh2uS5duujkyZNat26dsrOzdfDgQf3t\nb39zO8vW5fLe+N911136/e9/r9mzZystLU1nzpzRggULFBISohtvvDHf7SpUqKCJEyfqlVde0aJF\ni5SamqqLFy/qo48+0rBhw9SiRQtVr15dISEh8vX11bx585SVlaXvvvtOy5YtU8+ePYu0jfr06aOt\nW7dq3759unjxol555RXFxsbKz89P/fr107vvvqsPPvhAOTk52rdvn3r27Kk9e/YUur7LQ8fX11fH\njx8vcDtKlw5RO3LkiH766SedPHlSzz77rG699VbnjXne9/N88803zhnh8lztz6Eotm/frv379+vi\nxYtatmyZqlSpoqCgIOf6Hj16aM6cOWrXrp3b4WuX8/f31+bNmzVp0iTnUMb09HS99dZb+vzzz9W+\nfXtJUr9+/bR48WIdPnxYOTk5euONN9SzZ0+dP39eLpdLDRo0UExMjC5cuKDExERNmjRJKSkp+bZr\nUX6viis+AeBaKVLM7Nq1S71791ZERISGDx9e4OlAT506pWHDhik8PFw9evRwO30pAJQ2Rfkf52ee\neUZNmjRRv379FBISokOHDmndunXO5zsKWke/fv304osvauzYsfnG3HrrrVq4cKHi4uIUHBysJ554\nQoMHD9ZDDz3kcY4LFy5USkqKwsPD1bt3b9WsWVMvvPBCoXPv0aOHli1bpr179yosLEytW7fWnDlz\nNHz4cE2bNk3SpehZsmSJEhISdPfdd2vw4MEKCQnRuHHjPG4b6dKpqZ9++mk9+eSTCg4O1qFDh5zT\n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\nEx8f/wunDgAA8Nt09OjRkp4CSon9+/crNTW1pKdRanmMmeDgYE2aNEn79u1Ts2bNtGrVKoWGhsrX\n19cZc/bsWY0dO1ZvvfWWAgIC9MknnygnJ8ftszaFCQoK+nWPAAAA4DemcuXK0tsnS3oaKAUaNmyo\nevXqlfQ0StSVdn54jBkfHx/FxMRo6tSpysjIUGBgoGbOnKmEhATNnz9fy5cvV/PmzTVy5EgNHTpU\nxhiVL19e8+bNU8WKFYv1gQAAAABAHo8xI0ktWrRQXFyc2zJ/f38tX77cudy/f3/179+/eGcHAAAA\nAIXweAIAAAAAACiNiBkAAAAAViJmAAAAAFiJmAEAAABgJWIGAAAAgJWIGQAAAABWImYAAAAAWImY\nAQAAAGAlYgYAAACAlYgZAAAAAFYiZgAAAABYiZgBAAAAYCViBgAAAICViBkAAAAAViJmAAAAAFiJ\nmAEAAABgJWIGAAAAgJWIGQAAAABWImYAAAAAWImYAQAAAGAlYgYAAACAlYgZAAAAAFYiZgAAAABY\niZgBAAAAYCViBgAAAICViBkAAAAAViJmAAAAAFiJmAEAAABgJWIGAAAAgJWIGQAAAABWImYAAAAA\nWImYAQAAAGAlYgYAAACAlYgZAAAAAFYiZgAAAABYiZgBAAAAYCViBgAAAICViBkAAAAAViJmAAAA\nAFiJmAEAAABgJWIGAAAAgJWIGQAAAABWImYAAAAAWImYAQAAAGAlYgYAAACAlYgZAAAAAFYiZgAA\nAABYiZgBAAAAYCViBgAAAICViBkAAAAAViJmAAAAAFiJmAEAAABgJWIGAAAAgJWIGQAAAABWImYA\nAAAAWImYAQAAAGAlYgYAAACAlYgZAAAAAFYiZgAAAABYiZgBAAAAYCViBgAAAICViBkAAAAAViJm\nAAAAAFiJmAEAAABgJWIGAAAAgJWKFDO7du1S7969FRERoeHDhys5OTnfmPfff189e/ZU165dNWDA\nAH399dfFPlkAAAAAyOMxZtLT0zVmzBhFR0dr69atCg0NVVRUlNuY5ORkTZgwQS+++KI2b96srl27\nasqUKdds0gAAAADgMWZ2796twMBAuVwuSVKfPn20c+dOpaWlOWPKlSunF198Ub/73e8kSUFBQUpM\nTLxGUwYAAACAIsTMkSNHVLNmTeeyn5+fqlatqmPHjjnLqlWrprvvvtu5vGPHDjVq1KiYpwoAAAAA\n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\nUVxc3FXdB1BaGWM8/p0/9dRTev7554vtPv39/dWkSRMdOHBAkrRo0SL1799fISEhzpg77rhDcXFx\n+uMf/yhJqlatmiIjI509M19//bXefvttPfPMM8U2L+C3oih/15crymtyUdZXs2ZNhYaGaunSpQVe\nv3r1arVp00Z9+/Z1lrlcLk2ZMkUxMTEe15/3XNG+fXtnWXBwsEaNGqWXXnpJkhQbG6uAgAD9+c9/\ndl7Tq1SpopdfflmzZ892blfYe4xy5cp5nAeuLWKmhHz22We65ZZbVLt2bbfl5cuXV2hoqD7++GOF\nhobmu129evVUrVo1ffHFF5IuBcHgwYP12Wefaf/+/fnGt2nTRjt37tT48eP1r3/9SxcuXFDFihVV\noUKFq5pvRESEtmzZ4lzevHmzOnfufFXr+LmMjAy99dZbzi7pK/n444/d3rjkCQ4OdnaD169fX926\ndVNMTIxWrFihBg0aqG3btpI8b++rUdjPpn79+vrd737nXI6NjdX999+vunXrqnLlygX+fIDfGi8v\nL3Xq1EmSCj3s42olJiZqz549atasmaRLf4Pt2rXLN87Pz8/tcv/+/ZWRkaG3335b0dHRioyMdN5o\nAfjlivKaXJCfB46Xl5cef/xx/eMf/1BycnKB91PQ6227du105swZHTt2zOM8C7p9WFiY9u/fr6ys\nrEKfT8qXL+92SNmV3mOgZPGZmRJy7tw53XTTTVe8vrAX3Ztuukk//fSTc0y5t7e3nn76aU2fPl2v\nv/6629gGDRro9ddf15o1azRhwgSdO3dOoaGhmjx5sm655ZYizdXLy0u1atWSn5+fDh48KJfLpX/+\n85967bXXtHjxYrexY8eOzfeZmY0bN8rb29vt+pycHJ08eVL9+vXT6NGjPc7B0/bK8/jjj6tLly7K\nzs7W+vXrr/r2RXHu3DmPn/FJSUnRF1984fzPUZ8+fbRhwwY1bNiwWOYAlKTBgwe7fWbG399f69at\ncxszYcIEPfHEEwW+kUhKSlKXLl2c23t5eSkkJMTZY5x3vTFGqampqlChgiZNmqQmTZpIuvT3dfkb\nprxj/3NyclSpUiXFxsZKuvTcFRUVpWHDhqlWrVrq379/sW8L4Ldq9erV2rhxo6T//p1Onz5dzZo1\nK/Jr6s+fK1JTU1WvXj23MVWqVNGwYcM0e/ZszZ071+26wt4LlSlTRlWrVtVPP/10xfs/d+5cgXF1\n0003KScnR+fPn1dKSorbfcTGxmrZsmWSpJ9++kkbNmxwPvdT2HsMlCxipoTceOONBf4vxOXXnzp1\nqsDrTp8+ne/N9L333qu1a9fq7bffzjf+zjvv1KxZsyRJ//nPf/TSSy9p9OjRev311+Xl5aXc3Nx8\nt8nNzXV7ApKkrl27atOmTcrOztZtt92mqlWr5rvd3Llzr7inJe/6ixcvKiIiQmFhYfkOVStI3vaq\nWbPmFcdVqlRJvXr10qlTp9w+dOhpe1+Noqxr06ZNOnPmjIKDgyVd2obly5fXhAkTnO0K2Grt2rUK\nCAi44pg//OEPatGihVauXJnvOaFGjRpue3p/7vLrd+7cqWnTpqlDhw7O9XnPj3nPB3/5y18kSfHx\n8fkOI2vcuLHq1aunvn37OoeQAPBsyJAh+U4OlKeor8k/f65Yv3692yHreQYOHKju3bvr008/zXc/\nBb0Xys3N1dmzZ+Xv76+kpKRC7//nzxV5Tp8+rbJly+qGG27Idx+9e/dW7969JUkNGzZUTk6Oc11h\n7zFQsjjMrIQ0adJEZ86ccY4Bz5Odna2YmBi1a9dO27Zty3e7r776SikpKWrUqFG+6yZMmKCYmBhl\nZGQ4y/bt2+f2xvsPf/iDxo4dq6+++kqSdPPNN+d7IkhLS9OpU6d06623ui3v3Lmz3nvvPb377rvq\n2rVrgY+rqJ+ZKVeunCIjI53I8qRVq1baunVrvuWxsbH68ssv3ZaVK1fO2ROUx9P2zszMLNI88uZS\n0OEzn376qROTcXFxzpmb9u7dq48//lhNmjTR9u3bi3w/QGlV1GPrn3zySa1bt04//PDDL76vu+++\nW9WrV3fb89O2bVu9++67RZ6Xt7d3vucEAL9cUV+Ti/pc4e3trWeeeUbR0dFut7nnnnsKfC+0Y8cO\n1ahRQzVq1Ljiegt7L/XBBx+oefPm8vb2Vps2bQo9JLag+Rf0HgMli5gpIZUrV9bw4cP1zDPPOMd8\npqena8qUKTp48KB69OihnJwczZo1S9nZ2ZKkEydOaPz48Xr00UfdDuXK43K51KZNG61evdpZtnHj\nRkVFRTknDMjOztbmzZudUxL27NlT27dvd97kZ2VlaebMmercuXO+/3mtXr26AgICtHXrVrf/Jf2l\nevTooaysLG3YsMHj2JEjR2rTpk1uY7dt26YXX3xRlSpV8nh7T9vbx8dHUtGeeHv27Kns7Gw9//zz\n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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3246663b50>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "def plot_sector_exposure(pf, sectors):\n",
    "    return draw_barplot(\n",
    "        pf.groupby(sectors).sum(),\n",
    "        'Portfolio Concentration by Sector',\n",
    "    );\n",
    "\n",
    "plot_sector_exposure(constrained_concentration_pf, sector_names);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we suspected, we're heavily exposed to the technology sector, and we're moderately exposed to cyclical consumer goods.\n",
    "\n",
    "We can tell the optimizer to try to build a sector neutral portfolio by adding a `NetGroupExposure` constraint:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Constraint requiring bounded net exposure to groups of assets.\n",
      "\n",
      "    Groups are defined by map from (asset -> label). Each unique label\n",
      "    generates a constraint specifying that the sum of the weights of assets\n",
      "    mapped to that label should fall between a lower and upper bounds.\n",
      "\n",
      "    Min/Max group exposures are specified as maps from (label -> float).\n",
      "\n",
      "    Examples of common group labels are sector, industry, and country.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    labels : pd.Series[Asset -> object] or dict[Asset -> object]\n",
      "        Map from asset -> group label.\n",
      "    min_weights : pd.Series[object -> float] or dict[object -> float]\n",
      "        Map from group label to minimum net exposure to assets in that group.\n",
      "    max_weights : pd.Series[object -> float] or dict[object -> float]\n",
      "        Map from group label to maximum net exposure to assets in that group.\n",
      "    etf_lookthru : pd.DataFrame, optional\n",
      "        Indexed by constituent assets x ETFs, expresses the weight of each\n",
      "        constituent in each ETF.\n",
      "\n",
      "        A DataFrame containing ETF constituents data. Each column of the frame\n",
      "        should contain weights (from 0.0 to 1.0) representing the holdings for\n",
      "        an ETF. Each row should contain weights for a single stock in each\n",
      "        ETF. Columns should sum approximately to 1.0. If supplied, ETF\n",
      "        holdings in the current and target portfolio will be decomposed into\n",
      "        their constituents before constraints are applied.\n",
      "\n",
      "    Examples\n",
      "    --------\n",
      "    Suppose we're interested in four stocks: AAPL, MSFT, TSLA, and GM.\n",
      "\n",
      "    AAPL and MSFT are in the technology sector. TSLA and GM are in the consumer\n",
      "    cyclical sector. We want no more than 50% of our portfolio to be in the\n",
      "    technology sector, and we want no more than 25% of our portfolio to be in\n",
      "    the consumer cyclical sector.\n",
      "\n",
      "    We can construct a constraint expressing the above preferences as follows:\n",
      "\n",
      "    .. code-block:: python\n",
      "\n",
      "        # Map from each asset to its sector.\n",
      "        labels = {AAPL: 'TECH', MSFT: 'TECH', TSLA: 'CC', GM: 'CC'}\n",
      "\n",
      "        # Maps from each sector to its min/max exposure.\n",
      "        min_exposures = {'TECH': -0.5, 'CC': -0.25}\n",
      "        max_exposures = {'TECH': 0.5, 'CC': 0.5}\n",
      "\n",
      "        constraint = NetGroupExposure(labels, min_exposures, max_exposures)\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    For a group that should not have a lower exposure bound, set::\n",
      "\n",
      "        min_weights[group_label] = opt.NotConstrained\n",
      "\n",
      "    For a group that should not have an upper exposure bound, set::\n",
      "\n",
      "        max_weights[group_label] = opt.NotConstrained\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.NetGroupExposure.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ALL_SECTOR_NAMES = Sector.SECTOR_NAMES.values()\n",
    "MIN_SECTOR_EXPOSURE = -0.0001\n",
    "MAX_SECTOR_EXPOSURE = 0.0001\n",
    "\n",
    "def optimal_portfolio_sector_neutral():\n",
    "    \"\"\"\n",
    "    Calculate the optimal portfolio if we're constrained by exposure, concentration,\n",
    "    and sector neutrality.\n",
    "    \"\"\"\n",
    "    objective = opt.MaximizeAlpha(expected_returns)\n",
    "    constraints = [\n",
    "        opt.MaxGrossExposure(1.0),\n",
    "        opt.PositionConcentration.with_equal_bounds(\n",
    "            min=MIN_POSITION_WEIGHT, \n",
    "            max=MAX_POSITION_WEIGHT,\n",
    "        ),\n",
    "        opt.NetPartitionExposure(\n",
    "            labels=sector_names,\n",
    "            min_weights={sector: MIN_SECTOR_EXPOSURE for sector in ALL_SECTOR_NAMES},\n",
    "            max_weights={sector: MAX_SECTOR_EXPOSURE for sector in ALL_SECTOR_NAMES},\n",
    "        )\n",
    "    ]\n",
    "    return opt.calculate_optimal_portfolio(objective, constraints, empty_portfolio)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzoAAAHvCAYAAACc3aoBAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzs3WtclHX+//H3KDqEsiGahwrULBvbUhTPWiKKoK6ZkJa5\nai21ZtluhVupW0RtamtGqZU/JRc1rd1V1E2J0g5sKKThQ0k389DiAQ00D6AcErz+N/w768hBZED0\n6+t5y+t7fea6PheXc3jPdRibZVmWAAAAAMAgdWq7AQAAAACobgQdAAAAAMYh6AAAAAAwDkEHAAAA\ngHEIOgAAAACMQ9ABAAAAYByCDgBcJu+9954eeuihGln26NGj9de//rVGll1ZR44cUUREhDp27Kjd\nu3dftN7hcCg5OVmSFBYWpr///e9VXndJSYkefPBBffjhh1VeBi5u48aNcjgcKigo0KRJk/TKK6/U\ndksAUC6CDgCUYceOHXr66afVs2dPBQQEKDg4WK+88ooOHz58SctZuHChiouLJUnjx4/X0qVLa6Ld\nCs2ZM0ft2rVThw4d1KFDBwUEBCg0NFRz5szR6dOnq7zcrKwsffLJJ87pxMREHT58WGlpabr11lsv\naVlJSUl64IEHqtzL7Nmz5eXlpZEjR0qS8vPzNX36dIWEhCggIECBgYGKjIzUli1bqryO823cuFHf\nffddtSxLklasWCGHw6H4+PhS8yZNmqQ5c+ZUy3p27Nih9evXu7UMm80mSfrzn/+sL774whlWAeBK\nQ9ABgAukpqZq5MiRcjgcWr16tbZs2aKFCxcqLy9PERERys7OrtRyjh49qunTp+uXX36p4Y4v7te/\n/rW2bt2qrVu3asuWLYqNjVVCQoLefffdS17Wud+Z/vTTT12CTm5urpo2bSq73V5tfVfG8ePHtXDh\nQk2YMME5NnHiRH3//fd6//33tWXLFn311Vdq166dfve73+nIkSNur3PBggXKyMio0mPL+51uHx8f\nvfPOO5ccpi/FsmXLlJKSckl9ladBgwZ6+OGHFRsbWx2tAUC1I+gAwHksy9JLL72kESNG6PHHH5ev\nr68kyc/PTzNmzFDz5s01ffp0SdI333yjdu3aKTk5WQMGDFBAQIDGjRunkydPKjs7W/fcc48kqUeP\nHlq2bJnmzJmjiIgISWePCHTs2FFffvml+vXrp44dO2r69OnauXOnhg0bpo4dO+rJJ590Hg365Zdf\n9NJLL+nuu+9WYGCgRowY4dbRiTvuuEOjR4/W2rVrnWNffPGFc919+/Z1CUFz5szRo48+qkmTJikg\nIEBz587VG2+8oc8//1wdOnTQm2++qffee0/bt29Xhw4dtHPnTuXl5WnSpEm655571LFjRz3yyCPl\nntIWHBysJUuWOPfB3LlzFRoaqoCAAA0ZMkTr1q0rd1sSEhJ00003qVOnTs6x9evXa8SIEfL395ck\neXt7a+LEiYqOjladOnWcf9O//OUvCg4OVseOHTVq1Cjt2LHDuYz9+/frscceU6dOndS3b1/Nnz9f\nkvT73/9eX331laZNm6bRo0dLkrKzs/XUU0+pR48e6ty5s5544glnIM7KypLD4dA///lP9ejRQwkJ\nCWVuR9u2bdWvXz+99tpr5W6rdDZgnttP/fr10+LFi53zLjyF8dy6d+/erZdffllLlizRokWL1K9f\nP+fffd68eQoNDdXkyZMlSRs2bNDw4cMVGBiou+++W6+99lq5Iej+++/Xrl279O2331bYMwDUBoIO\nAJxn+/btOnDggPMD7IVGjx6tL7/8UqdPn5bNZpNlWUpISNDy5cu1bt06/fTTT3rjjTfUrFkzLViw\nQNLZQHT//fdL+t9pP5JUWFio9evXKzExUdOmTVN8fLxmzpyp999/XwkJCfr3v/+tL7/8UpIUFxen\nb775RqtWrdKmTZvUtWtX/fGPf3RrW4uLi1W3bl1J0s6dO/XUU09p/Pjx+vbbbxUbG6uFCxe6fCj/\nz3/+o7vuuktbt27V448/rqFDh6p///7aunWrnn32WY0fP9555Kht27aaMmWKsrKytHLlSqWmpurG\nG2/U448/ftEjB0uXLtXSpUv19ttvKz09XWPGjNHTTz+tzMzMMus3bNig7t27u4y1adNGH3zwQanH\nDB061BleZ8yYoW3btumjjz7SN998o27dumn8+PEqKSmRJD311FNq1aqV0tLSNH/+fMXFxemzzz7T\nvHnzdOONN2ry5MnOkPHkk0+qfv36Wrdunb744gsVFxcrKirKZd3r16/XunXrnGG3LM8995w2bNig\n1NTUMudv27ZNL7zwgqKiorR582a9+eabmj17doWno537P/fyyy+rc+fOGjt2rD7//HPn/I8//ljz\n58/XtGnTVFRUpAkTJmjw4MFKT0/X0qVLtXr1ai1btqzMZTds2FDt2rVTWlpauesHgNpC0AGA8+zb\nt0/16tXTzTffXOb8W2+9VUVFRc5v6202myIjI+Xt7a0mTZpo1KhRLh8ipYpPCRo5cqTsdruCg4Ml\nnf2G3dfXV61bt1arVq2cH9Qff/xxJSQkyNfXV3Xq1NHAgQOVk5NTpdOwzpw5o++++04ffvihhgwZ\nIklavny5unXrpgEDBqhu3boKCAjQoEGDlJiY6LIdlb2ZQm5urtauXatnnnlGvr6+8vT0VFRUlA4c\nOHDRU76WLVumUaNGyeFwqG7duho+fLhatmypzz77rMz6Xbt2qW3bti5jr7/+uvLz8zVw4EANGDBA\nkydPVlJSkvMI2bmAOn78eDVt2lT169fXhAkTdOrUKaWlpen777/XDz/84Awwt956q2bPnq1WrVq5\n/D2ks9e9bN++Xc8//7waNGigX/3qV5owYYLS09Nd9s/QoUPVoEGDCrfd19dXTz/9tF5++eUyr59K\nSEjQPffco969e8tms6lDhw669957yz1KdH6f5enVq5fzyJfdbtfXX3/tDPp+fn4KCAjQtm3byn38\nbbfdpl27dlW4DgCoDR613QAAXGksy5JlWS5HXy50/rzzP/zeeOONOnr0aKWvd2jevLkkqX79+pKk\npk2bOufVr19fRUVFkqTDhw/rtdde06ZNm3Tq1Cnn8it7/c+5U8okqU6dOrrxxhv10EMPKTIyUtLZ\n07TatGnj8piWLVu6fFN/rtfKyMrKkiSXZfr6+qpBgwbKyspy9lKWsnrx9/d3LvNCx48f1/XXX+8y\ndtttt2nVqlXasWOH0tLStHHjRj3//PO6+eab9cEHH6ikpESnTp3SU0895dyXlmXpzJkzOnTokE6e\nPKnrrrtOPj4+zmV27dq1zPUfOHBADRo0cNl3LVu2lGVZysrKUpMmTSRJLVq0KHebzzdy5EitWLFC\n8+bN05NPPukyb9++fUpNTXX+/c79P6jo73kxN954o8t0YmKiFi5cqKysLJWUlKikpET33ntvuY9v\n1KiRDhw4UOX1A0BNIegAwHluueUWFRcXa+/evS4B5pwff/xR1113nZo3b+784H3uVCfpfx88KwpJ\n5zt3vUh50+c888wzqlevnlauXKlmzZppx44dGjZsWKXWIZ29GUF5px9J5Qem87fj3GluleHODRgq\n00tl5zkcDjkcDj388MPKzs5WeHi4li5dqrFjx0qSlixZorvuuqvU49auXVvpsFrRtp7fl4dH5d5y\nbTaboqOjNXr06FIBw9PTUyNGjFB0dHSllnXmzJmL1py/X1NTU/Xyyy9rxowZGjBggDw8PFxu8lBe\nvwBwJeLUNQA4j8PhUOvWrbVw4cIy5y9ZskRhYWEuHw7379/v/HdWVpZuuOGGau/ru+++0wMPPKBm\nzZpJUoWnElWFv7+/fvzxR5exH3/80XlK06Xy8/OTZVnas2ePcyw7O1unTp0qM0Be2Mv5jzvXS8uW\nLcus9/Hx0fHjx53Tu3bt0quvvlrqQ36zZs3Upk0bnTx5Ug0bNlSjRo1cbj4g/e9IlJ+fnwoLC13u\nsJecnKwNGzaUua2nTp1STk6Oc2zPnj2qU6eO/Pz8JF16GLjzzjs1bNgwvfrqqy7j/v7++uGHH1zG\nsrOznafk2e12FRYWOuft3bv3ktb93Xffyd/fX4MGDZKHh4dKSkpK/Y0udPToUTVq1KjS6wCAy4Wg\nAwAXeOWVV7Ry5UpNmzZNP//8s6Szpyc99dRTys7O1sSJE521lmUpPj5eeXl5ysnJ0Ycffqj+/ftL\nOvvtu3T2Q3pBQYFbPd10003aunWriouLlZqaqk8//VSSKn2r64u577779M0332jdunUqKSnRt99+\nqzVr1lR44bzdbtehQ4eUl5fnclRLOnuaWp8+ffT222/r2LFjOnnypGbMmKHbb79dd9xxR4W9DBs2\nTEuXLtXOnTt1+vRpLV68WDk5ORo4cGCZ9bfddpt27tzpnG7cuLHWrFmjKVOmOE+pKigo0PLly7V1\n61bnHcdGjhypuXPnateuXSopKdHf//533XfffTp58qQcDofatWun2NhYnTp1Snv27NGUKVOUm5sr\n6ey+3b9/v06ePKm77rpLt912m/76178qPz9fP//8s2bPnq0+ffo4A8Cl3rpZOnsUb/v27S43Ghgx\nYoQyMjL0z3/+U6dPn9bu3bv10EMP6V//+pckOW+ecPz4cR09erTUD6h6enrqwIEDysvLK3OdN910\nkw4fPqysrCwdPXpUr776qry9vV1C3IV2795d6hopALgSuB10UlNTFR4errCwMEVGRlb4pvvVV1/J\n4XDo4MGD7q4WAGpM586d9dFHH+nQoUP6zW9+o4CAAI0dO1bNmzfXsmXLnHftks5+Uz9gwABFREQo\nJCRELVq00LPPPitJateunTp27KiRI0fqgw8+uOh6L/zm/fzp6OhoffHFF+ratav+9re/afr06erV\n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\nAACAcS76Ozq4uIiICOXn5+uTTz6p9DyHw6GWLVuqbt26Kikp0a9+9Ss9++yz6tGjh3N+cnKymjVr\ndlm24VrjcDgUGhqqt99+22V8ypQpWr58uXbs2CFJ2r59u2bMmKGcnByVlJSoUaNG+tOf/qTAwEBl\nZWWpX79+uuWWWyT97zemOnbsqMDAQM2fP182m005OTmqV6+efHx8ZLPZ9NJLL6l79+6XfZtN8PLL\nL+ubb76RJO3fv19NmzaV3W7XgQMH1LlzZ/3tb39z1k6ePFk5OTmKi4tzjr3wwgtq1qyZvv76axUW\nFur06dPav3+/brnlFlmWpVtvvVWzZ89WcHCwpLM/gmxZls6cOSOHw6GXXnpJjRs3vrwbfY05/7Xx\nzJkz8vf314svvig/P79S88t67cTlsXPnTo0ePVorV6503kX18OHDuvfee/X+++/rjjvu0MKFC7Vs\n2TKVlJTozJkz6tatm/74xz/K19dXkjR69Gj997//1ddff+38CQpJWrVqlZ5//nktXrxYXbp0qZXt\nM11l3wMl6W9/+5sSEhJUXFyskpIS9e7dW88++6waNmyoFStW6JVXXlGLFi10+vRp2Ww2BQcH68kn\nn5S3t/fl3qxrzqJFi/TPf/7T5Tn29NNPq1GjRjp27Jhee+01bdu2TZLk4eGhsWPHavjw4ZJ07bzP\nWXDLzp07rYiICOuBBx6wtmzZUul5DofDys7Odk6np6dbXbt2tY4ePeqc/9NPP9X8Blyjbr/9diss\nLMw6deqUc+z06dPWvffeazkcDudY7969reTkZOd0UlKS1a1bN6uwsNA6cOCA9etf//qi63rhhRes\n9957r3o3AFZwcLC1efNmy7LOPtcCAgKs4uJi5/wBAwZYQUFBVklJiXMsKCjI2rRpk3O6vH3Yt29f\n57Ity7LOnDljvfrqq1ZUVFRNbArOc+Fr48yZM61x48aVO//C105cPu+9954VGRnpnP7DH/5gvfXW\nW5Zlnd1vw4cPd+6rkpISa8aMGdbgwYOtoqIiy7Is67e//a3Vt29fa8OGDS7LHTdunNW3b19r48aN\nl2lLrj2VfQ/861//ao0YMcLKycmxLMuyCgoKrClTplijRo2yLMuyEhISrEceecRZn5eXZ0VHR1tD\nhw517mfUjNjY2DKfY0OGDLGKioqsZ555xnrjjTec9T/++KPVrVs35+fRa+V9jlPX3LRixQoNGTJE\nQ4cO1YoVKyo9z7Isl9tsd+rUSf7+/tqyZYtzPmpW165d9dlnnzmnU1JSdNdddzmnjx49qiNHjqhD\nhw7OsdDQUH388cey2+2XtVeUdv5z6LbbbpO3t7fz+ZOVlaXrrrtOt912m7777jtJUmZmpo4fP66A\ngIBKL/8cm82moKAg/fDDD9W8FbjQha+N3bt3V1ZWVrnzL3ztxOXz2GOP6dixY1qxYoW+/PJL/fjj\nj3riiSd0/PhxLVq0SG+88YaaNm0qSapTp44mTpwou92uVatWOZdx99136+OPP3ZO5+bmav/+/br5\n5psv+/Zcay72Hnj8+HF98MEHev3113XDDTdIOvvt/0svvVTuT4g0bNhQL7/8sho2bOiyn1G9cnNz\ntXDhwjKfY/Xr19eqVau0a9cutW/f3vmY1q1bKzEx0eUzzbXwPkfQccOZM2eUlJSkoUOH6je/+Y2+\n/PJLFRcXX3ReeYqLi1W/fv3L0TokDRw4UGvWrHFOr1mzRgMHDnRO+/r66q677tLo0aO1bNkyHThw\nQJKcL/i4svTs2VOpqamSpLS0NHXq1EmBgYHOU902btyorl27ysPj0s/YLSws1PLly9WxY8dq7RkV\n++WXX/Svf/3LeYpFeXjtrB1169bVtGnTNHPmTP3lL3/RtGnTVK9ePW3dulU33nij/P39Sz2mb9++\n2rhxo8t0SkqKTp8+LUn69NNP1b9//8u2Ddeyi70Hbt26Vc2bN1erVq1cHle/fn0FBQVVuOygoCCl\npaVVZ7s4z5YtW9SiRYsyn2NBQUHauHGj7rnnHkVHR2vevHn6/vvvZVmW87TRspj6PkfQccPXX3+t\nu+66Sz4+PvL29laXLl305ZdfXnReWZKTk3XkyBF16tTpcrV/TbPZbOrWrZt27dql48ePq6ioSFu2\nbFH37t1dvuFYsGCBBgwYoMWLFyskJERDhgzR2rVrnfOLi4s1aNAgDRo0SAMHDtSgQYM0Z86c2tik\na17Pnj2doSYtLU1du3ZV586dXcZ69uxZ6eVNnDhRgwYNUmhoqLp166ZmzZpp8uTJNdI7XI0ZM0YD\nBw5U7969tW3bNoWHh5dby2tn7Wrbtq1uvvlmeXh46I477pAknThxotwPVE2aNNGJEyec0w0aNFCn\nTp3073//W5KUmJiogQMHclZDDavMe+CJEyfUpEmTKi2/YcOGOnnyZHW2jPPk5uZW+BzLy8vTn/70\nJz3zzDNKSUnRiBEjdPfdd+vdd991qb0W3ue4GYEbVqxYoa+//lpdu3aVZVkqKSlRfn6+QkJClJCQ\nUO68c8aMGeO84Pamm27S/Pnzdd1119XiFl1bbDabQkJClJiYqMaNG6tnz56qW7euS03Dhg01YcIE\nTZgwQUePHtXy5cv17LPPatWqVbLb7fLw8FBiYmItbQHO17NnT/35z39WQUGBNm3apEmTJsnb21vf\nf/+9fvnlF23cuFFPPPFEpZc3c+ZMdezYUadPn1ZYWJj69u0rT0/PGtwCnLN48WLn6RjffvutRo0a\npZUrVzo/dF342hkXF8drZy1ZtmyZPD09deutt2r+/PkaN26cGjVqpJycnDLrjxw5UupC58GDB+vj\njz9WQECAjhw5IofDcTlav+Zd7D2wUaNGys7OrtKys7KyKjx6APc0a9aswudY8+bNJUnDhw/X8OHD\nVVhYqK+++kqvvvqqmjRpohEjRki6Nt7nCDpVlJubq02bNmnTpk3OF4aSkhL16dNHR48eLXfesWPH\n1KhRI0mub+aoHYMGDdLbb78tX19fPfjgg5LkvPtPdna2srKynN8U+/r66rHHHtMnn3yi3bt369e/\n/nWt9Y3SmjRpoltuuUVr1qyRt7e3803W4XBo9erVqlOnjm699dZKL+/ct5r16tXThAkT9Prrrysh\nIaFGeoer87/N79y5s2666Salp6crNDRUEq+dV4qffvpJb731lj788EPVq1dPw4YNU2hoqDp27KgT\nJ07ohx9+0O233+7ymK+++kpjxoxxGevTp49iYmK0evVq5z7G5VHRe2BAQIB+/vlnff/992rXrp3z\nMcXFxZo9e3a5XxydOXNG69at04QJE2p+A65RDodDP//8c7nPsdGjRys5OVl9+vSRdPbaqrCwMG3d\nulU7d+501l4L73OculZFq1evVvfu3V2+/ahbt67uvvturV69Wj169Cg1r3fv3i7nw3Jovvac+9t3\n7NhR2dnZ2rVrl7p27eoy79ChQ3riiSect2aUpIyMDP3000/OCzbZh1eWHj16aPHixerWrZtzrEuX\nLlq8eHG5p61VZh8OHTpUv/zyi1auXFltvaJy/vvf/yozM1Nt2rRxjvG8uzJMmTJFv/vd7+Tn56fm\nzZvriSee0JQpU9SwYUONGzdOzz33nPPaxpKSEs2cOVNnzpzRoEGDXJZTv3599e7dWwsWLHC5RgQ1\npzLvgd7e3oqMjNRzzz2nffv2SZIKCgr04osvaseOHc6b8pz/fMzPz9ef//xnXX/99ezLGuTt7a2x\nY8eW+xzr16+fXnjhBZfQcuTIEa1fv965ny9k6vscR3Sq6F//+lepb6UkqV+/fpo7d65+97vflZrX\nv39/zZ07V7/97W9dfjOgLDabTf369ZP0v99nmTdv3iVdY4Dynf/3DwkJUX5+fql5AQEB+stf/qKY\nmBidPHlSZ86cUZMmTfTWW2+pRYsWysrKuuh+RM0p62/fq1cvxcfHu3yT2LVrV82aNUuPPPJIpZdz\n4VidOnX0hz/8QdOmTdOgQYO48L0G2Ww256lplmXp/7V3xygOAmEYhr+1sVHIPey9gGARu9SCYicE\njxDQMjdIISRFmrQ2HiNVLpEilYWC2S0Cw6bbJsS471PKFAPDzPD9IzO2bauqKnMax5ybhtPppNvt\npjRNzbc4jtU0jY7Ho7Isk23byvP86Y2P/X5vLgT5PZZRFOlyuZhAyzi/1l/2QElar9daLBbK81z3\n+12WZSkIApVladqcz2ctl0uN46i+7xUEgeq6lmVRS3+loijkuq5ZL4dhkO/7OhwOchzH3Mq22+0k\nPQoKcRwrDENJ/2ef+/qmNAYAAAB8pO12q67rngIoHojbAAAAwIeKokht2+p6vb67K5ND0AEAAAA+\nlOd5SpJEq9VKm83m3d2ZFH5dAwAAADA7nOgAAAAAmB2CDgAAAIDZIegAAAAAmB2CDgAAAIDZIegA\nAAAAmJ0fhZ+iIgCyI1sAAAAASUVORK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3246746210>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "optimal_sector_neutral_pf = optimal_portfolio_sector_neutral()\n",
    "plot = draw_asset_barplot(\n",
    "    optimal_sector_neutral_pf, \n",
    "    'Optimal Portfolio (Sector Neutral)',\n",
    "    {'ylim': (-MAX_POSITION_WEIGHT - 0.1, MAX_POSITION_WEIGHT + 0.1)},\n",
    ")\n",
    "plot.axhline(MIN_POSITION_WEIGHT, color='r', linestyle='dashed')\n",
    "plot.axhline(MAX_POSITION_WEIGHT, color='r', linestyle='dashed');"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA1QAAAH+CAYAAACbeU/8AAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzs3XucVXWh///36HCZYSqLb2ISo8jJpoeaF0RBLS5mXAQR\nRI1M81amaXXEE3mL48kI068mdhHl6+WgnSzTSMFBffiwo+SAokfT0vwKjAqKRR65zB4Q2L8/+LGP\nkzDQmvpi+Xz+xaz1WWuvtfaG2S/W2mtXlcvlcgAAAPiL7bC9NwAAAODvlaACAAAoSFABAAAUJKgA\nAAAKElQAAAAFCSoAAICCBBXAu8Ds2bNzyCGH5LOf/exWx955553p379/kuSxxx7Lvvvum9bW1r/1\nJr4r/OhHP9qm56CIIUOG5NZbb/2brBuALRNUANvRkCFDsvfee2fffffNvvvum379+mX8+PH59a9/\n3aH13n///Wlubq78fP3112fUqFH58Y9/vE3LV1VVJUkOPPDAPPnkk+natWvhbXnkkUdy2mmnpV+/\nfjnggAMyatSoXHvttVm3bl3hdf6/Mn/+/PzmN7/p0Dpuvvnmyr6eeeaZ2/wcbE8tLS2ZMmVKjjji\niOy3337p27dvTjvttPzXf/3XX2X9f43jCvBOIagAtrMLLrggTz75ZJ588snMnTs3Rx55ZM4444y8\n8MILf/G6Nn1X+9VXX51FixZVpq9YsSL19fV/tW3eVnfccUfOOuusDB8+PP/5n/+ZefPm5cILL8yd\nd96Zs88++//59vylbrjhhjz11FObnbfpWLfnT3/6U6ZMmZK1a9f+tTftb+q8887L7373u/yf//N/\n8l//9V958MEH87GPfSynnnpq/vjHP3Z4/e0d163ZluMO8P+SoALYzt76BrFz58753Oc+l9133z0P\nPvhgkmTt2rWZMmVKhgwZkv322y/HH398HnvsscoyQ4YMyXXXXZehQ4fmggsuyMiRI/P888/nnHPO\nyTe+8Y0MGTIkS5YsyXe+850cf/zxSZInnngin/nMZ9K3b98cdthh+fa3v73ZM0bz5s1LQ0NDSqVS\nkmTZsmU555xzMmDAgBx44IE566yzsmzZss3u16pVq/Ltb387EyZMyLhx41JTU5NOnTqlf//+mTZt\nWnr06JFVq1YlSV544YWceuqpOfjgg3PwwQdn4sSJlXnz589P3759M3fu3AwfPjz7779/zjjjjKxe\nvbryWDfddFOGDBmSvn375pRTTsnixYsr83784x/nyCOPzH777Zfhw4dn9uzZlXknnnhipk2blq9/\n/evp27dvBg4cmHvuuSdJ8sUvfjEPPvhgvvOd7+TEE09MkjQ0NGTGjBkZNGhQvv/97ydJZs2alVGj\nRmX//ffP4MGDM23atMqx+uQnP5kkGTBgQG6//fZ8//vfzzHHHFN5/PaehzvvvDNHHXVUZs6cWdm3\nf/mXf2k3KF5//fV84QtfyP7775+RI0fmkUceSZKccsopmTx5cpuxN910U0aNGrXZ9cydOzfHHXdc\nJcLf85735LzzzsukSZOyww4b3zqsXbs2l156aYYMGZL9998/J5xwQp599tnKOl566aV84QtfyAEH\nHJDBgwfn+uuv3+Jxbe91tWTJkjQ0NORnP/tZBgwYkDvuuGOL+w+wXZQB2G4GDx5cvuWWW942fcSI\nEeUbb7yxXC6Xy1OmTCmPHDmy/NJLL5XXrl1bnjp1avnAAw8sr1ixorKOkSNHlpubmyvLf/SjHy0/\n+OCDbR7n1ltvLZfL5fLy5cvL++23X/nmm28ur127tvx//+//LQ8ZMqQ8derUcrlcLt9xxx3l/v37\nl8vlcnnevHnlhoaGcktLS7lcLpePOeaY8rnnnltetWpV+Y033ih/4QtfKH/uc5/b7L7dc8895b33\n3ru8Zs2ado/BmjVrygMHDixfdtll5TVr1pRfffXV8tixY8sTJ06sbMPHPvax8je+8Y3yypUry0uX\nLi0ffPDB5RkzZpTL5XL5vvvuK/fv37/8u9/9rvzmm2+W/+3f/q08cuTIyryDDz64/Jvf/Ka8YcOG\n8oMPPljeZ599yi+88EK5XC6XP/e5z5U/+clPlufOnVtet25d+YorrigffPDBmz1um47r5z73ufLy\n5cvL5XK5/PLLL5f32muv8r333lsul8vl3/zmN+W99967/Otf/7rN8SuVSuVyuVy+5pprysccc8w2\nPw99+/Ytf+tb3yqXSqXy7373u/Jee+1VfuCBBzZ7HAcPHlz+xCc+UV6wYEF5zZo15SuvvLK8//77\nl1etWlX+xS9+UT700EPLGzZsqIwfP358+brrrtvsusaMGVP+zGc+U160aNEWn7dLL720fPzxx5eX\nLVtWXrNmTfnqq68uDxo0qLxu3bpyuVwujx49unzppZeW16xZU37++efLBx10UHnOnDmbPa6be12d\ncMIJlWP80Y9+tPzVr361vGrVqi1uD8D24gwVwDtIqVTKjBkzsnTp0hxxxBFJkp///Oc544wz8uEP\nfzidOnXKWWedlQ0bNuShhx6qLHfooYdu9ZK+8v9/ZuOuu+7KzjvvnJNOOimdOnVKnz59Mn78+DZn\nbjbn2WefzTPPPJOJEyemW7duee9735uzzz47jz322GYvA3vppZey6667pnPnzu2u96GHHsrKlSvz\nta99LZ07d06PHj1y+umnZ86cOZVtLpfLOeWUU1JXV5cPfehD+fjHP165JPKOO+7IiBEj0tDQkOrq\n6nzlK1/Jl7/85axbty4/+9nPMnbs2Oy9996pqqrKwIEDc+ihh2bmzJmVx//4xz+eQw45JDvuuGOO\nOOKIvPHGG/nTn/70tuO2ydChQ/OBD3wgSdKzZ8888sgjledq7733Tu/evd/2+aA/X0eybc/D6tWr\n87WvfS1du3ZNQ0NDdtttt3YvBR04cGAOOOCAdO7cOWeccUbWrl2bxx57LJ/+9KfT0tKShx9+OEny\nhz/8IU899dQWz1BddtllaWlpyfDhw/PpT386F1xwQRobGytnz8rlcu64446ceeaZ2XnnndO5c+ec\nffbZWb16dZqamvK73/0uzz33XL785S+nc+fO+ad/+qdcc8012X333d92TLb0ulqwYEGb19Xo0aPT\nrVu3Le47wPZSvb03AODd7jvf+U6++93vJkm6du2aPffcMzfccEN69uyZFStWZMWKFenTp09l/I47\n7piePXvm5Zdfrkzbddddt/nxXn755TbrS5LddtstS5Ys2epy3bp1y84779xmuXK5nCVLluR//a//\n9bZl1q9fv9Xteemll/LhD3+4TXjttttuaW1tzfLlyyvTevbsWflz165dK3cefOmll9KvX7/KvPe9\n730ZNmxYkuTFF1/M3LlzK3e/K5fLKZfLed/73lcZ/+EPf7jy55qamiRp966GH/rQh9r8fOutt+aO\nO+7Ia6+9lg0bNmTdunXb9JmpbXke3vve96aurm6z+705b11fbW1tunfvntdeey01NTUZNmxYfvnL\nX+YTn/hE7rvvvhxwwAHZZZddNruej3zkI5k5c2aeffbZNDU1Zf78+Zk4cWI+/OEP55Zbbsn69euz\nevXqnHPOOZUbmJTL5WzYsCGvvPJKVq1alZqamuy0006VdR500EFbPA7b8rr68+MO8E4hqAC2swsu\nuGCLt9Ju7435pjeyycbI2lZbWudb19eRbdmkd+/eefXVV9PS0pLa2toOr3fTZ3c2N2bDhg2bnde1\na9d87Wtfy+mnn75Nj7Etqqv/51fnz372s1x33XX5wQ9+kIMPPjg77LBDxowZs03r2ZbnYUv7vCV/\nPr5cLldCdcyYMTnjjDPS2tqa++67L0cdddRW19fQ0JCGhoacfPLJWbZsWcaOHZsf//jH+fznP59k\nY0zus88+b1vuvvvu2+abR2zr8//W4w7wTuKSP4DtrL03nt27d0+3bt3aXOa1du3aLFmypM3lU3+J\n+vr6LFy4sM20F154YauXDPbq1SurV6/Oa6+91ma5HXbYIb169Xrb+EMPPTTdunXLTTfd9LZ5S5Ys\nybBhw7Js2bLU19dnyZIlbd5Yv/DCC+nWrVu6d+++1f3p1atXmzsarly5MjfccENaWlpSX1+f5557\nrs34V1555a92p7jf/OY3OeCAAzJgwIDssMMOWbVqVZvb1ben6PPQnrceh5aWlvzpT3+qnIXq169f\nunfvnrvuuitPPvlk5Szen3v++efzrW99622R2qNHj/Tp0yerVq1KXV1d3v/+97e5CUWSytm1Xr16\npbW1tc0NS371q19t9usAtuV19ZdGL8D/S4IK4B2sqqoqo0ePznXXXZelS5emtbU1V199dWpqanLY\nYYdtcbkuXbpk8eLFlTvlvdWIESPy6quv5pZbbsm6devy7LPP5j/+4z/a3H3urTbFxz777JOPfOQj\n+e53v5uWlpYsX74811xzTQYOHJj3v//9b1uupqYmF1xwQX74wx/mRz/6UVauXJk333wzv/71r3Pq\nqaemX79+6dGjRwYOHJiuXbvm6quvztq1a/Pyyy/n+uuvz9FHH71Nx+iYY45JY2NjHn/88bz55pv5\n4Q9/mDvuuCO1tbUZP3585syZkwceeCDr16/P448/nqOPPjrz5s3b4vreGltdu3bNSy+9tNnjmGy8\nXHDx4sX57//+77z66qv55je/mQ996EOVONj0/V0LFy6s3Clxk7/0edgWDz74YJ5++um8+eabuf76\n6/O+970vffv2rcwfPXp0rrjiinzyk59scynhW3Xv3j2zZs3KhRdeWLmstFQq5ec//3mefPLJHH74\n4UmS8ePH59prr83zzz+f9evX57bbbsvRRx+dVatWpaGhIR/72Mdy1VVXZfXq1XnhhRdy4YUXZsWK\nFW87rtvyuvprBTDA30KHg+qRRx7J2LFjM2zYsJx22mmbvX1ue2OuuOKKDBs2LCNGjMiVV15Zmf7K\nK6/k1FNPzdChQzN27Ng2v/xWr16dCRMmZK+99mrzOOeff34OO+ywjBgxIsOHD8+IESN8cSDwjrYt\n//P+9a9/Pfvtt1/Gjx+fgQMH5rnnnsstt9xS+bzP5tYxfvz4XHnllTnvvPPeNuZDH/pQfvCDH2Tm\nzJnp379/vvrVr+akk07KySefvNVt/MEPfpAVK1ZkyJAhGTt2bHr16pXLL798i9s+evToXH/99Zk/\nf34GDx6cAQMG5Iorrshpp52Wb33rW0k2hte0adPy1FNP5bDDDstJJ52UgQMHZuLEiVs9NsnG28b/\ny7/8S/75n/85/fv3z3PPPVe5pXn//v1zwQUXZPLkyenbt28uuuiiTJw4Mf3799/isXvrtOOOOy63\n3XZbxo8fv9nx48ePT+/evTN48OCcfPLJGTVqVE4//fTcdddd+d73vpePfexj2X///TN+/Pjccsst\nbZb9S5+HLW3vW+eddNJJueqqq9KvX7/cf//9mTp1aptL5Y4++ui88cYbGT169BbX84EPfCA/+clP\nsm7dupxwwgnZb7/98olPfCIzZ87MD3/4wxx44IFJki996UsZMmRITjrppPTr1y+/+MUvcv3111dC\nbdq0afnDH/6QQw89NF/4whdy8sknV86K/flx3drryhkq4J2sqtyB//YplUo5/PDDc8MNN1S+m2Pu\n3Lm59tprt2nMrFmzMmPGjNxyyy0pl8s58cQTc+qpp+bTn/50Tj/99AwcODAnnnhinn322Zx++ul5\n4IEH0rlz54wePTpHHHFErr322jz99NOVxzr//PNz8MEHb/P/agLAu0lTU1O+/vWv58EHH/yLP58F\nwOZ16F/Tpqam1NfXp6GhIcnGyy4efvjhtLS0tDtm7ty5aWlpyZw5czJmzJhUV1enU6dOOeqoo9LY\n2JhVq1alqakpxx57bJKNH4rdddddK2epLrvssm3+0C8AvNtt2LAhL774Yr797W/n9NNPF1MAf0Ud\n+hd18eLFbT6IXFtbm5122ikvvvjiVsc0Nzdn0aJFbT58u+kDus3NzenevXvl2vNk44dWN314d1Oc\nbc5dd92VcePGZeTIkZVvqweAd7Np06ZlzJgxOfjgg3PiiSdu780B+IfSoXuQlkqldOnSpc20rl27\n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\nZs3Ktddem3Xr1uUjH/lIJk+enLq6upx//vl56KGH8t73vjflcjlVVVW57LLLss8++3R0NwEAAN6m\nQ2eoSqVSJkyYkMmTJ6exsTGDBg3KpEmTtnnMrFmz8thjj+Xuu+/OzJkzM3/+/Nx7771JkosvvjiD\nBw/OnDlzMnny5EyYMCFr167N0qVLc+mll2b69Om555570rNnz3zve9+rPN55552X2bNn55577sns\n2bPFFAAA8DfToaBqampKfX19GhoakiTHHHNMHn744bS0tLQ7Zu7cuWlpacmcOXMyZsyYVFdXp1On\nTjnqqKPS2NiYVatWpampKccee2ySpKGhIbvuumvmzZuXBx54IIccckjlDNe4cePS2NjYkd0AAAAo\npENBtXjx4vTq1avyc21tbXbaaae8+OKLWx3T3NycRYsWpb6+vjKvvr4+CxcuTHNzc7p3756uXbtW\n5vXq1SsLFy582/p69eqV5cuXZ+XKlUmSu+66K+PGjcvIkSMzbdq0juweAABAuzr0GapSqZQuXbq0\nmda1a9c2Z6jaG9Pa2prOnTu3mV4qlTa7TJcuXSrzunfvXpneuXPnVFVVpaWlJQcddFA2bNiQsWPH\nZtmyZTnllFOyyy67ZPTo0R3ZTQAAgM3qUFDV1tZmzZo1baa1tramtra23TGlUindunVLTU1N1q5d\n22Z6bW1tamtr09rautn11tTUtFnf2rVrUy6X061bt4wZM6YyfZdddsnxxx+fBx98cKtBtWDBgm3f\n6X8wzc3N23sTeAd5+umnK2d7AXh38x6BTbw/aF+Hgqp3796ZPXt25eeVK1dmxYoV2X333bdpzB57\n7JHm5uYMGDAgyca/uH369El9fX1ef/31lEql1NTUJNl46eC4ceNSXV2dRx99tLK+RYsW5YMf/GDq\n6ury3HPPZY899kinTp2SJOvWrUt19dZ3sW/fvh05DH/X3vOe9yR3v7q9N4N3iL333jt77rnn9t4M\nAN4BvEdgE+8PNtrSSZgOfYaqf//+Wbp0aR5//PEkyU033ZRBgwa1+exTe2OGDx+en/70pymVSlm9\nenVuu+22jBo1KnV1dTn00EMzY8aMJBtvbLF8+fL069cvhx9+eJqamrJ48eLK+kaOHJkkmTRpUm69\n9dYkyRtvvJGZM2dm8ODBHdlFAACALerQGaouXbrkqquuyiWXXJLW1tbU19dnypQpeeqppzJ16tRM\n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\nAQAAFCSoAAAAChJUAAAABQkqAACAggQVAABAQYIKAACgIEEFAABQkKACAAAoSFABAAAUJKgAAAAK\nElQAAAAFCSoAAICCBBUAAEBBggoAAKAgQQUAAFCQoAIAAChIUAEAABQkqAAAAAoSVAAAAAUJKgAA\ngIIEFQAAQEGCCgAAoCBBBQAAUJCgAgAAKEhQAQAAFCSoAAAAChJUAAAABQkqAACAggQVAABAQYIK\nAACgIEEFAABQkKACAAAoSFABAAAUJKgAAAAKElQAAAAFCSoAAICCBBUAAEBBggoAAKAgQQUAAFCQ\noAIAAChIUAEAABQkqAAAAAoSVAAAAAUJKgAAgIIEFQAAQEGCCgAAoCBBBQAAUJCgAgAAKEhQAQAA\nFCSoAAAAChJUAAAABQkqAACAggQVAABAQR0KqkceeSRjx47NsGHDctppp2XZsmV/8bgrrrgiw4YN\ny4gRI3LllVdWpr/yyis59dRTM3To0IwdOzbz5s2rzFu9enUmTJiQvfbaq83jvPnmm7nooosydOjQ\nHHnkkZkxY0ZHdg8AAKBdhYOqVCplwoQJmTx5chobGzNo0KBMmjTpLxo3a9asPPbYY7n77rszc+bM\nzJ8/P/fee2+S5OKLL87gwYMzZ86cTJ48ORMmTMjatWuTJJ/97GfTu3fvVFVVtXmsG2+8MStWrMic\nOXNy22235eabb84zzzxTdBcBAADaVTiompqaUl9fn4aGhiTJMccck4cffjgtLS1bHTd37ty0tLRk\nzpw5GTNmTKqrq9OpU6ccddRRaWxszKpVq9LU1JRjjz02SdLQ0JBdd921cpbqsssuy5gxY962TY2N\njTnuuOOSJHV1dRk6dGgaGxuL7iIAAEC7CgfV4sWL06tXr8rPtbW12WmnnfLiiy9u07jm5uYsWrQo\n9fX1lXn19fVZuHBhmpub071793Tt2rUyr1evXlm4cGGSVOJsc9u0ufUBAAD8LVQXXbBUKqVLly5t\npnXt2vVtZ6jaG9fa2prOnTu3mV4qlTa7TJcuXVIqldrdptbW1jbLbcsySZLdd3/7tMWLt32s8cYb\nb/w/yPje69bl1tdXZYcddqxMHn/stzY7/D9+dvFmpxv/9z++5Y3X0nvIkKR6M28T/o5ez8Ybb7zx\nf9XxP//5ZmdXlcvl8uaX3Oi+++7L5ZdfXvm8UrlcTlVVVcaPH59nnnkml19+eWXsYYcdlunTp7c5\ng3TTTTdtcdzXv/71nH/++RkwYECS5KGHHsqVV16Zb3/72/nSl76U//zP/6wsc+6552a//fbLSSed\nlCRZsmRJhg4dmqeffroypm/fvrnzzjsrZ6l+8pOf5OGHH873v//9Le7fggUL2tt9AACAJBt7489t\n9QzVEUcckSOOOOJt03/1q19l9uzZlZ9XrlyZFStWZPc/K77evXtvcdwee+yR5ubmSlA1NzenT58+\nqa+vz+uvv55SqZSampokGy/nGzduXLvb2qdPnzQ3N1eCatP62rO5gwIAALAtCn+Gqn///lm6dGke\nf/zxJBvPRA0aNKjN5562Nm748OH56U9/mlKplNWrV+e2227LqFGjUldXl0MPPbRy2/OmpqYsX748\n/fr1q6y3XC7nz0+uDRs2LLfccks2bNiQ1157LbNnz86IESOK7iIAAEC7tnrJX3seffTRXHrppWlt\nbU19fX2mTJmS7t2756mnnsrUqVMzffr0dsclyVVXXZXGxsZUVVVl1KhR+fKXv5wkWbZsWSZOnJil\nS5emrq4ukyZNyr777psnnngin//855Ns/N6pTp06paqqKk8++WTWrVuXf/3Xf838+fNTXV2dU045\npXKnQAAAgL+2DgUVAADAu1nhS/4AAADe7QQVAABAQYIKAACgoMJf7Ms/lhtvvDF33HFH1q1bl/Xr\n1+ewww7Lueeem7q6uvzhD3/IlVdemQULFqS6ujpdunTJ8ccfn8985jNJNn4n2OGHH56vfvWrOfPM\nMyvrvPPOOzN//vx85zvfSZL8+7//e372s59l/fr1efPNN9O3b99cfPHF6datW84///zstttu+dKX\nvtRmu4YMGZIrrrgiBxxwQIYMGZIPfOADuf3229uM+eEPf5ipU6fmgQceyK677pohQ4YkSeWOk5u+\nO+3cc8/Npz71qTbzy+VyNmzYkIaGhnzzm9+s3CylPU8++WS+973vZenSpSmXy+nZs2e+8pWvZP/9\n988vfvGLTJ8+Pb/85S+zww7/8/8Vp512Wvr27Zuzzjprq8f7zjvvzC9/+cvceOONb3vsPz9Or732\nWv73//7feeKJJ1JVVZVu3brlxBNPzJgxY9osd9lll+Xf//3f88ADD6RHjx6V6SeeeGKOO+64jBo1\naqv7De8kDQ0N2W233bLjjhu/gHjT3/PLLrss++yzTxoaGjJu3LhceumllWXmz5+fa665JjNmzMj8\n+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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f32465ec110>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plot = plot_sector_exposure(optimal_sector_neutral_pf, sector_names);\n",
    "plot.axhline(MIN_SECTOR_EXPOSURE, color='r', linestyle='dashed')\n",
    "plot.axhline(MAX_SECTOR_EXPOSURE, color='r', linestyle='dashed');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With our partition exposure constraint in place, the optimizer chooses to hedge our large `TWTR` position with shorts in `AAPL` in `MSFT`. The optimizer also reigns in the large long in `MCD` from 30% to 15%, because our 15% short exposure constraint prevents us from getting a equal-sized hedge in `QSR`, which is the only other `CONSUMER_CYCLICAL` stock in our universe. That leaves 10% of our capital unallocated, so the optimizer divides it evenly into a pair on `BP` and `XOM`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Constraining Risk Factor Exposures\n",
    "\n",
    "So far we've looked at constraining our portfolio by restricting how much value we allow the optimizer to allocate to groupings of assets at various levels of granularity:\n",
    "\n",
    "- We used `MaxGrossExposure` to limit the amount of value the optimizer allocated to the largest possible group: the group of **all assets**.\n",
    "- On the other end of the spectrum, we used `PositionConcentration` to limit how much value the optimizer allocated to the smallest possible groups: the groups containing individual assets.\n",
    "- Between these two extremes, we used `NetGroupExposure` to control how much value the optimizer allocated to any single sector.\n",
    "\n",
    "While these are all reasonable applications of the Optimize API, sometimes we want control our portfolio in ways that are more sophisticated than just controlling the value allocated to particular groups of assets.\n",
    "\n",
    "A different technique for controlling risk is to associate each asset in our portfolio with a set of **risk factors** that describe how an asset's price has moved historically with respect to some common source of risk. For each risk factor, we can then set upper and lower bounds on the **factor-weighted** exposure of our portfolio.\n",
    "\n",
    "The most commonly-used risk factor is market beta, which in the simplest case is calculated as the slope of a linear regression between an asset's returns and the returns of \"the market\". Other common risk factors are \"size\" (measured as a function of market cap, for example) and \"value\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from quantopian.pipeline.factors import RollingLinearRegressionOfReturns\n",
    "from quantopian.pipeline.data import Fundamentals\n",
    "\n",
    "def get_risk_factors(stocks, date):\n",
    "    # Measure beta as the slope of a linear regression of 60 days of daily close-to-close returns.\n",
    "    # Each asset's returns are regressed against the returns of SPY.\n",
    "    empirical_regression_coeffs = RollingLinearRegressionOfReturns(\n",
    "        target=symbols('SPY'),\n",
    "        returns_length=2,\n",
    "        regression_length=60,\n",
    "        mask=StaticAssets(stocks),\n",
    "    )\n",
    "    # RollingLinearRegressionOfReturns calculates a bunch of coefficients, \n",
    "    # but we only care about beta for this example.\n",
    "    empirical_beta = empirical_regression_coeffs.beta\n",
    "    \n",
    "    # Measure size by taking the z-score of the log of market cap.\n",
    "    # Taking the log of market cap is common because company sizes are\n",
    "    # distributed exponentially.\n",
    "    log_mcap_zscore = Fundamentals.market_cap.latest.log().zscore()\n",
    "    \n",
    "    # Measure value using book value yield.\n",
    "    book_value_yield = Fundamentals.book_value_yield.latest.zscore()\n",
    "    \n",
    "    factor_terms = {\n",
    "        'market': empirical_beta,\n",
    "        'size': log_mcap_zscore,\n",
    "        'value': book_value_yield,\n",
    "    }\n",
    "    \n",
    "    result = run_pipeline(\n",
    "        Pipeline(factor_terms, screen=StaticAssets(stocks)),\n",
    "        start_date=date,\n",
    "        end_date=date\n",
    "    )\n",
    "    # Drop dates from the index of the returned frame.\n",
    "    return result.reset_index(level=0, drop=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>market</th>\n",
       "      <th>size</th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Equity(24 [AAPL])</th>\n",
       "      <td>0.881295</td>\n",
       "      <td>3.049261</td>\n",
       "      <td>-0.035366</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Equity(4707 [MCD])</th>\n",
       "      <td>0.566868</td>\n",
       "      <td>2.210673</td>\n",
       "      <td>-0.062235</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Equity(5061 [MSFT])</th>\n",
       "      <td>1.088901</td>\n",
       "      <td>2.908003</td>\n",
       "      <td>-0.041585</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Equity(8347 [XOM])</th>\n",
       "      <td>0.933150</td>\n",
       "      <td>2.807673</td>\n",
       "      <td>0.000507</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Equity(19675 [BP])</th>\n",
       "      <td>1.039710</td>\n",
       "      <td>2.277613</td>\n",
       "      <td>0.047715</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                       market      size     value\n",
       "Equity(24 [AAPL])    0.881295  3.049261 -0.035366\n",
       "Equity(4707 [MCD])   0.566868  2.210673 -0.062235\n",
       "Equity(5061 [MSFT])  1.088901  2.908003 -0.041585\n",
       "Equity(8347 [XOM])   0.933150  2.807673  0.000507\n",
       "Equity(19675 [BP])   1.039710  2.277613  0.047715"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "risk_factors = get_risk_factors(universe, '2016-10-07')\n",
    "risk_factors.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets look at how our how heavily our previous sector-neutral portfolio is exposed to these risk factors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA0AAAAHvCAYAAAB9tr9QAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzt3Xt8VPWd//H3NLdhgBojF5VmBGLZqBisgZooK8Mld7FA\n3IfghYK4i1DUQqgKLI1BCWAQlovKSmSRUNzgirJCDCQg2QJBSKiNaFkVSNAA4WFBE8hMwmV+f/DL\nLGPIxYk64Pf1/Is5+Z7J56R0nBfnzInF7Xa7BQAAAAAG+Jm/BwAAAACAHwsBBAAAAMAYBBAAAAAA\nYxBAAAAAAIxBAAEAAAAwBgEEAAAAwBgEEAAYIC8vT3feeaceeOCBFte+/fbbiomJkSSVlJSoT58+\ncrlcP/SIAAD8KAL9PQAAmGzQoEE6fvy4AgICJEnBwcG68cYb9fjjj+vOO+/0+XkLCwv1y1/+Ujfc\ncIMkafny5Ro6dKimTZvWqv0tFoskqW/fvvrrX//q0wyVlZUaPHiwgoODPc/XYMCAAVq8eLFPz9tg\n//79+vvf/6677rqrTc/TYPfu3Ro9erRCQkK8trvdblksFn3wwQeyWq3fy/cCAPgPAQQAfjZ9+nTP\nmZn6+nqtXbtW48eP1zvvvKOIiIjv9FwNb9YXLVqktLQ0TwBVV1fLbrd/77O3xGKx6O233/7Ox9Ea\n//Vf/6WgoCCfAqjh5/RtP4XQaerYAAAXcAkcAPiZ2+32/Dk4OFgPPfSQunfvrm3btkm6EEVz587V\noEGDdNttt+n+++9XSUmJZ59Bgwbp1VdfVUJCgqZPn6577rlHn332mR5//HE988wzGjRokCorKzVn\nzhzdf//9kqS//OUvGjlypKKjo9W/f3/Nnj1bZ8+ebTTbBx98oMjISDmdTklSVVWVHn/8ccXGxqpv\n376aOHGiqqqqmj22i4/v277++mtNnjxZd911l/r166cxY8bo4MGDnq+fPHlSv//979W3b1/1799f\n8+bN0/nz5/Xss8/qT3/6k3JycjR48GBJUk1NjaZNm6a7775bv/rVrzR27Fh9/vnnnueKjIxUTk6O\nHA6Hli5d2qr/Pb5t4cKFSk1N9Tw+fPiwbrvtNpWUlGj37t266aabVFRUpPj4eN1222167LHHdOrU\nKc/6rVu3avjw4frVr36lgQMH6uWXX/Z8rby8XI888oj69eunfv366dFHH9XRo0clSdOmTdOTTz7p\nNUtkZKSKiookSQ8//LDmz5+v1NRUjRkzRpJ07NgxTZw4UbGxserXr5+mTJmir7/+WpLkcrk0bdo0\n3Xnnnbr99tuVmpqqXbt2NXncAPBTQgABwGXo/PnznsviFi5cqB07dmjVqlXas2eP+vfvrwkTJqim\npsaz/t1339Xy5cs1Z84cbdiwQZK0dOlSzZ07V1u3btX111+v6dOnKzc3VydOnNAjjzyi5ORk7dq1\nS6+//rq2bt2qV155pdEcFovF62zC7373OwUHB6uwsFBbt27V2bNnNXXqVJ+PMysrS8ePH9fmzZu1\nY8cOderUSTNmzPB8fcaMGTp//ryKior01ltvqbCwUK+//rqeffZZ9e3bV6NHj9aWLVs8aysrK/XO\nO++ouLhY119/vR577DGvoNm8ebPWrVunxx9/vMmZmgug3/3ud3I6nVq7dq0kKTMzUyNGjFDfvn09\n+65bt84z69GjRzV//nxJ0qeffqrHH39cEyZMUElJiRYuXKjXX39d69atkyQ999xzuv7661VcXKz/\n+Z//UefOnT37tkZeXp7S09P1+uuvS5ImTJigrl276v3331dBQYFOnz6t5557TpK0cuVK/e1vf1N+\nfr5KS0t133336ZlnntH58+db/f0A4EpFAAHAZcTpdConJ0dHjhxRXFycJOmtt97S+PHj9Ytf/EJB\nQUGaOHGizp8/rz//+c+e/e66664WL3FreGP/7rvvqkuXLho9erSCgoIUERGhUaNGKS8vr9n99+/f\nr48//lhPP/202rdvr5///OeaNGmSSkpK9NVXX/l0vBkZGcrOzlb79u0VHBys+Ph4ffzxx5IunP3Z\ntm2bxo8fr/bt26tr165asGCBbr/99kbPU11drYKCAk2ePFlhYWGyWq1KS0vTl19+qbKyMs+6hIQE\nhYWFNTmP2+1WbGys+vTpoz59+igqKkp9+vTxRFlwcLCee+45LVq0SO+++67279+vtLQ0z/4Wi0Xj\nxo1Tx44d1alTJz344IOeQHvrrbd0xx13KD4+XgEBAbrtttuUnJzs+blXV1crKChIgYGBateunebM\nmaMXX3yx1T/LW265RVFRUZKkjz76SJ9++qmmTp0qq9Wq0NBQPfHEE8rPz5fL5VJNTY0CAgI8n88a\nNWqUtm3bpp/9jLcFAH76+AwQAPjZnDlz9MILL0iSrFarevXqpRUrVqhbt26qrq5WdXW112doAgIC\n1K1bN3355Zeebddff32rv9+XX37Z6DM5N9xwgyorK1vcr3379urSpYvXfm63W5WVlerUqdMl9xsx\nYoTnLFLD51PGjBmjyZMn69ChQ5o3b54++ugjOZ1OnT9/XufOnZN04SYKbrdb3bp18zzXrbfeesnv\n0TD7xccVFham9u3bq7KyUn369JEkXXfddc0eY2s+AxQdHa34+Hg99dRTeumll9S+fXuvr3fv3t3z\n5+uvv14nTpyQ2+3WF198ccmfe8OlZ5MmTdIf/vAHFRUV6R//8R+VlJTkuRtfa1z8d+CLL77QuXPn\nvG6k0fCzP378uB544AFt2bJFAwYM0J133imHw6GUlBQFBvK2AMBPH690AOBnF98E4dvq6+ub3O/i\nS9MaLpdrjaaes6UPzrd2lm9r6iYIbrdb48eP1+2336733ntPYWFh2rJliyZNmiRJnrMRrbksq7nZ\nLtaaN/jNXQLX4IsvvpDNZtOhQ4cafa0h4C5+LovF0uLPfcCAASoqKtK2bdu0detWPfbYY3rggQf0\n1FNPNdrnUj+Ti/8OhISEyGq16sMPP2zyGN577z3t2rVL77//vrKysvTGG29ozZo1nAUC8JPHqxwA\n+Flzb7ivueYatW/fXgcOHPBsq6+vV2VlpdeZhu/Cbrd73WhAkg4cONDiJXTh4eE6ffq0jh8/7rXf\nz372M4WHh19yH4vF0uTxffXVVzpy5Igefvhhz2Vp+/bt83y9W7duslgsXpFRWlqqTZs2XXI2t9vt\n9XOqqqrS6dOnff45NeWdd97Rl19+qZUrV+rll1/WF1984fX1ix9XVlaqc+fOki79cz948KDn537y\n5Em1a9dOSUlJysrK0rPPPqvc3FxJFy69u/h3MVVUVDQ74w033KC6ujodPnzYs83lcunEiROSLlxq\nWV9fr9jYWE2fPl1r167Vhx9+qP3793/XHwcAXHEIIAC4jFksFv3mN7/Rq6++qiNHjsjlcmnRokVq\n166d+vfv3+R+ISEhKi8v97oDWYPk5GQdO3ZMq1ev1tmzZ7V//3698cYbXnc3u1hDwNx666365S9/\nqRdeeEG1tbX6+9//riVLlmjAgAG6+uqrm933UsLCwmSz2fSXv/xF9fX12rx5s3bv3i3pQrxcddVV\nGjJkiF5++WV9/fXXqqqqUnp6uicwrFarvvzyS9XU1CgsLEwDBgzQokWLdPLkSZ06dUpZWVn6h3/4\n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\nL86dO6fExERJUq9evdS7d29dddVVCg0NVadOnXTmzBmVlJTo2muvlST17dtXX3zxhWf/G264QeHh\n4Z7HbrdbL774osLCwvTP//zPkqT3339fSUlJ6tSpkyTp/vvv95wZAnBluPrqq/X555+roKBATqdT\nEydOVHBwcKN12dnZCgwM1G9/+1tJ0rZt2/TAAw8oMDBQVqtVv/nNb/j/P3CFSUhIUFFRkdxut86d\nO6dt27Zp6NChzb4/aMmf//xn3XHHHYqIiJB04b3B1q1bxa/FNEugvweAmQICAjxvYgICAmSz2by+\ndubMGS1ZskTvv/++zp8/r1OnTqlHjx6eNaGhoV7Pt2/fPn344YdeN0OoqalRQUGBduzYIelCdJ07\nd+6HPCwA37OoqCjNnDlTOTk5euaZZzRw4EDPP540+Oijj7RmzRq99dZbnm3V1dXKzMzUggUL5Ha7\ndebMGfXp0+fHHh9AG4SHh+u6667T3r17debMGfXs2VNdunTRiy++2OT7g5bU1NRoz549Sk5OlnTh\nH1CvuuoqnTx5UmFhYT/UoeAyQwDhsvTVV19p27ZtWrNmja666iq9+eabevfdd5tc37VrVy1btkz3\n33+/Bg0apN69e6tLly4aPny412VyAK488fHxio+PV3V1taZNm6bXXnvN87VTp05p6tSpmj17tq6+\n+mrP9i5duujRRx/VgAED/DEygO9JYmKitmzZovr6eiUlJWnjxo2ten8QEBCg8+fPex5XV1dLuvDa\ncOedd2rRokU/2jHg8sMlcPCLlk41nzhxQt26dfP8q8x7772n2traJtd36dJFv/jFL/TMM8/o6aef\nVn19vQYNGqSCggKdOHFC0oVrhxvuHBUYGKhvvvnm+zsgAD+IdevWea7v//nPf66ePXt63fUxIyND\ncXFxio2N9dpv8ODBWrt2rc6fPy+3261XXnlF27dv/1FnB9B28fHxKi4uVlFRkRITE/X3v/+9Ve8P\nOnfurP3790uS8vLyVF9fL0nq37+/SktLPZfNlZWVafbs2T/eAeGyQADBL5q7bbXFYlHnzp319ddf\nKyEhQVOnTtXvf/97HTt2TC+88EKzzzt06FBFRERo4cKFuvnmm/Uv//IvGj16tFJSUvT6669r8ODB\nkqSBAwcqNzdXTz755Pd6XAC+X4MHD9bHH3+shIQEpaSk6MCBA3rkkUckSceOHdO7776rgoICJScn\nKykpScnJyaqsrNSDDz6o66+/XikpKUpOTtbBgwcVHR3t56MB8F11795d58+f17XXXqvOnTvrnnvu\n0cmTJ1t8fzBx4kStWLFCQ4cO1cGDB3XjjTdKuhBGzz33nCZNmqSUlBQ9//zzSklJ8cehwY8sbj71\nBQAAAMAQnAECAAAAYAwCCAAAAIAxCCAAAAAAxiCAAAAAABiDAAIAAABgDAIIAAAAgDEIIAAAAADG\nIIAAAAAAGOP/AWGgqRHqicj3AAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f32451a31d0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "def plot_factor_exposures(pf, factor_loadings):\n",
    "    return draw_barplot(\n",
    "        pf.dot(factor_loadings),\n",
    "        'Portfolio Factor Exposures',\n",
    "    );\n",
    "plot_factor_exposures(optimal_sector_neutral_pf, risk_factors);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our sector neutral portfolio appears to have a strong negative exposure to our `market` and `size` factors. We can force the optimizer to control for these effects using a `FactorExposure` constraint."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Constraint requiring bounded net exposure to a set of risk factors.\n",
      "\n",
      "    Factor loadings are specified as a DataFrame of floats whose columns are\n",
      "    factor labels and whose index contains Assets. Minimum and maximum factor\n",
      "    exposures are specified as maps from factor label to min/max net exposure.\n",
      "\n",
      "    For each column in the loadings frame, we constrain::\n",
      "\n",
      "        (new_weights * loadings[column]).sum() >= min_exposure[column]\n",
      "        (new_weights * loadings[column]).sum() <= max_exposure[column]\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    loadings : pd.DataFrame\n",
      "         An (assets x labels) frame of weights for each (asset, factor) pair.\n",
      "    min_exposures : dict or pd.Series\n",
      "         Minimum net exposure values for each factor.\n",
      "    max_exposures : dict or pd.Series\n",
      "         Maximum net exposure values for each factor.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.FactorExposure.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "MIN_FACTOR_EXPOSURE = -0.01\n",
    "MAX_FACTOR_EXPOSURE = 0.01\n",
    "\n",
    "def optimal_portfolio_factor_neutral():\n",
    "    \"\"\"\n",
    "    Calculate the optimal portfolio if we're constrained by exposure, concentration,\n",
    "    sector, and market/size/value exposures.\n",
    "    \"\"\"\n",
    "    objective = opt.MaximizeAlpha(expected_returns)\n",
    "    constraints = [\n",
    "        opt.MaxGrossExposure(1.0),\n",
    "        opt.PositionConcentration.with_equal_bounds(\n",
    "            min=MIN_POSITION_WEIGHT, \n",
    "            max=MAX_POSITION_WEIGHT,\n",
    "        ),\n",
    "        opt.NetPartitionExposure(\n",
    "            labels=sector_names,\n",
    "            min_weights={sector: MIN_SECTOR_EXPOSURE for sector in ALL_SECTOR_NAMES},\n",
    "            max_weights={sector: MAX_SECTOR_EXPOSURE for sector in ALL_SECTOR_NAMES},\n",
    "        ),\n",
    "        opt.FactorExposure(\n",
    "            loadings=risk_factors,\n",
    "            min_exposures={'market': MIN_FACTOR_EXPOSURE, \n",
    "                           'size': MIN_FACTOR_EXPOSURE, \n",
    "                           'value': MIN_FACTOR_EXPOSURE},\n",
    "            max_exposures={'market': MAX_FACTOR_EXPOSURE, \n",
    "                           'size': MAX_FACTOR_EXPOSURE, \n",
    "                           'value': MAX_FACTOR_EXPOSURE}\n",
    "        )\n",
    "    ]\n",
    "    return opt.calculate_optimal_portfolio(objective, constraints, empty_portfolio)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzoAAAHvCAYAAACc3aoBAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzt3Xt8FPW9//H3EmDjAiVE5CImctGw3iAQCeFiCZeQAFow\nqRdEUAwtQmmrBluBQhqrgEWMIFYOouUi2uOBAFViLFCkoolgOBClKhiMQMAgJZBgsoEk8/uDH3tY\nciWbsPjl9Xw8eDyYme/MfL67md1973xn1mZZliUAAAAAMEgjXxcAAAAAAPWNoAMAAADAOAQdAAAA\nAMYh6AAAAAAwDkEHAAAAgHEIOgAAAACMQ9ABgEvklVde0QMPPNAg2x47dqz+/Oc/N8i2a+vYsWOK\ni4tTjx499PXXX9fY3ul0auvWrZKkmJgY/fd//3ed911WVqb7779fb731Vp23gZqde87WrVun2NhY\nlZaW+rokAKgSQQcAKvHll1/qscceU9++fRUaGqpBgwbp6aef1vfff39R21m+fLn7w+CkSZP05ptv\nNkS51Vq0aJFuuukmde/eXd27d1doaKiio6O1aNEinTlzps7bzc3N1XvvveeeTk1N1ffff6+MjAzd\ncMMNF7WttLQ03XfffXWu5aWXXpLD4dDo0aMlnf1Afuutt7r7fO5fXFxcnfdxzoX9ro/tOZ1OTZ48\nucKytWvXauzYsfWyn8LCQr399tv1sq1Ro0apXbt2euGFF+plewDQEAg6AHCB9PR0jR49Wk6nU+++\n+6527dql5cuXq7CwUHFxccrLy6vVdo4fP665c+fq9OnTDVxxzW655Rbt3r1bu3fv1q5du5ScnKyU\nlBT95S9/uehtnfud6ffff9/jA39BQYHatGkju91eb3XXxokTJ7R8+XJNmTLFY/7LL7/s7vO5f2vW\nrPF6fxf2+2JU9xvdu3bt0pYtWyrMt9lsddrXhT7++OMqz5rV5bfDp0yZolWrVunYsWPelgYADYKg\nAwDnsSxLs2bN0r333qtHH31UgYGBkqSgoCDNmzdP7dq109y5cyVJn3zyiW666SZt3bpVQ4cOVWho\nqCZOnKhTp04pLy9PP/3pTyVJffr00erVq7Vo0SL3GYXt27erR48e2rJliwYPHqwePXpo7ty52rt3\nr+6++2716NFDv/rVr9xng06fPq1Zs2bpjjvuUFhYmO69917t2rWrzv28+eabNXbsWG3cuNE975//\n/Kd73wMHDvQIQYsWLdKECRM0bdo0hYaGavHixXr++ee1efNmde/eXS+88IJeeeUV7dmzR927d9fe\nvXtVWFioadOm6ac//al69Oih8ePHVzmkbdCgQVq1apX7OVi8eLGio6MVGhqqu+66S5s2baqyLykp\nKerQoYN69uxZ6/7X9Hi6XC7NmjVLERER6tOnj6ZNm6bi4mItWbJEzz//vDZt2qTu3bvrzJkzOn36\ntObOnatBgwYpNDRU9913nz799FOPvi1ZskTR0dGaPn16lTVNnTpVzzzzTLXBeO/evRo/frzCw8PV\np08fJSYmutuf//d1/r5XrVqlDRs26IknntC///1vde/eXd9++62mTZumGTNmaMKECRo6dKgk6eDB\ng5o4caIiIiLUu3dvTZ48ucqzmDfffLNuvPHGejtLBAD1jaADAOfZs2ePDh06VOVwobFjx2rLli06\nc+aMbDabLMtSSkqK1qxZo02bNum7777T888/r7Zt2+r111+XdDYQ/fznP5fk+e28y+XSRx99pNTU\nVM2ZM0fLli3T/Pnz9dprryklJUX/+te/3N/wL126VJ988onWr1+vHTt2KDw8XL/97W+96mtpaan8\n/Pwknf0A/etf/1qTJk3Sp59+quTkZC1fvlwpKSnu9v/+97912223affu3Xr00Uc1cuRIDRkyRLt3\n79YTTzyhSZMmuc8chYSEaMaMGcrNzdW6deuUnp6ua6+9Vo8++miNZw/efPNNvfnmm1qwYIEyMzM1\nbtw4PfbYY8rJyam0/ccff6yIiIiL6ntNj+f8+fO1d+9evffee0pLS9M333yj+fPn65e//KVGjhyp\nqKgo7d69W02aNFFycrI++ugjrVixQjt27FD//v01adIkFRYWurf3zjvv6NVXX9WcOXMqrcdmsyk2\nNlZt27bVyy+/XGkbl8ulCRMmqHfv3kpPT9fatWu1Z88ej/ZVnf0ZMWKEx/Nz/fXXS5I++OADjRkz\nxh14Z86cKYfDoX/961/avHmzTp06Ve21X+Hh4crIyKhyOQD4EkEHAM5z4MABNWnSRNddd12ly2+4\n4QaVlJS4h6/ZbDbFx8erRYsWat26tcaMGaPNmzd7rFPdB/vRo0fLbrdr0KBBks5+Ax8YGKhOnTqp\nY8eO7g/3jz76qFJSUhQYGKhGjRpp2LBhOnr0aJ2GDZWXl+uzzz7TW2+9pbvuukuStGbNGvXu3VtD\nhw6Vn5+fQkNDNXz4cKWmpnr0o7Y3UygoKNDGjRv1+OOPKzAwUP7+/kpISNChQ4eUlZVV7bqrV6/W\nmDFj5HQ65efnp3vuuUfXX3+9/vGPf1Taft++fQoJCall78+q6fFcv369HnnkEbVq1UotW7bUs88+\nq8GDB1e6rTVr1mjixIm67rrr1KRJE02ePFnl5eX68MMP3W369eun4ODgGutKTEzUihUr9M0331RY\ntmXLFpWWlurRRx+Vn5+f2rVrp1/+8pdeDcdr27atBg4c6J5esmSJ5s6dq6ZNm6p58+YaNGiQPv/8\n8yrXDwkJ0b59++q8fwBoSI19XQAAXG4sy5JlWdVeG3H+so4dO7r/f+211+r48eO1vuahXbt2kqSm\nTZtKktq0aeNe1rRpU5WUlEiSvv/+ez377LPasWOHfvjhB/f2a3v9z7khZZLUqFEjXXvttXrggQcU\nHx8v6eyQpS5dunisc/3113t8W3+u1trIzc2VJI9tBgYGqlmzZsrNzXXXUpnKagkODnZv80InTpxQ\ny5YtK8yfMmWKGjU6+33eueczKipKzz//fLWPZ35+vgoKCtShQwf3trp06VKhJulsoCsoKPBY5ufn\npw4dOujQoUPueddee22V/T1f165ddf/99+uPf/yjli9f7rHs4MGDys/P93jszv2t1vWmEhfWlZWV\npRdffFFffvmlzpw5o7KyMrVt27bK9Vu1aqWTJ0/WeLwAgC8QdADgPJ07d1Zpaam+/fZbjwBzzv79\n+3XVVVepXbt27g/eZWVl7uXnPjDX9kPfuQ/iVU2f8/jjj6tJkyZat26d2rZtqy+//FJ33313rfYh\nnb0ZwerVq6tcXlVgOr8f54a51YY3N2CoTS21WbZo0SINGDCg0vbVPZ7nnoPy8vI613phTRfz2E2Z\nMkXDhw/XO++84zHf399fnTt31oYNG2q9rZr6cH5dBQUFmjhxou69914tXrxYzZs314oVKyoELgD4\nsWDoGgCcx+l0qlOnTlV+uFu1apViYmI8PiAePHjQ/f/c3Fxdc8019V7XZ599pvvuu8/97Xp1w4nq\nIjg4WPv37/eYt3///loNt6pMUFCQLMtSdna2e15eXp5++OGHSgPkhbWcv965Ws5dV3KhgIAAnThx\n4qLqq+7xbNmypX7yk594DB/bu3dvpUHx6quvVrNmzTzqPX36tHJzc2vsZ1WaNWump556Ss8995zH\n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\nAAAAADS8xjU12Lhxo+bNmyebzSZJsixLNptNo0ePVklJiUdbl8slh8PhMe9vf/ubunbtqm7dul10\ncZmZmRe9DgAAAADYrDqOJdu6datefvllvf3225KkwsJC9evXT9u3b5e/v7+73S9/+Uvt2bPHHZSO\nHz+ugIAAvfjiiwoPD6+HLgAAAACApzoHnZKSEg0ePFgLFy5Uz5499dJLL2nfvn1auHBhtesNGjRI\nq1atUvv27etUMAAAAADUpM4XzdjtdiUnJyspKUnR0dHKyspy3146KytLEyZMqHQ9m83GDQkAAAAA\nNKg6n9EBAAAAgMsVt0EDAAAAYByCDgAAAADjEHQAAAAAGKfG39FBzeLi4lRUVKT33nuv1sucTqeu\nv/56+fn5qaysTD/5yU/0xBNPqE+fPu7lW7duVdu2bS9JH640TqdT0dHRWrBggcf8GTNmaM2aNfry\nyy8lSXv27NG8efN09OhRlZWVqVWrVnryyScVFham3NxcDR48WJ07d5b0f78x1aNHD4WFhenVV1+V\nzWbT0aNH1aRJEwUEBMhms2nWrFmKiIi45H02wR//+Ed98sknkqSDBw+qTZs2stvtOnTokG6//Xb9\n9a9/dbedPn26jh49qqVLl7rnPfXUU2rbtq0+/PBDuVwunTlzRgcPHlTnzp1lWZZuuOEGvfTSSxo0\naJCksz+CbFmWysvL5XQ6NWvWLF199dWXttNXmPNfG8vLyxUcHKyZM2cqKCiowvLKXjtxaezdu1dj\nx47VunXr3HdR/f777/Wzn/1Mr732mm6++WYtX75cq1evVllZmcrLy9W7d2/99re/VWBgoCRp7Nix\n+uabb/Thhx+6f4JCktavX6/f//73WrlypXr16uWT/pmutu+BkvTXv/5VKSkpKi0tVVlZmfr3768n\nnnhCzZs319q1a/X000+rffv2OnPmjGw2mwYNGqRf/epXatGixaXu1hVnxYoV+p//+R+PY+yxxx5T\nq1atlJ+fr2effVaff/65JKlx48Z66KGHdM8990jSlfM+Z8Ere/futeLi4qz77rvP2rVrV62XOZ1O\nKy8vzz2dmZlphYeHW8ePH3cv/+677xq+A1eorl27WjExMdYPP/zgnnfmzBnrZz/7meV0Ot3z+vfv\nb23dutU9nZaWZvXu3dtyuVzWoUOHrFtuuaXGfT311FPWK6+8Ur8dgDVo0CBr586dlmWdPdZCQ0Ot\n0tJS9/KhQ4dakZGRVllZmXteZGSktWPHDvd0Vc/hwIED3du2LMsqLy+3/vSnP1kJCQkN0RWc58LX\nxvnz51sTJ06scvmFr524dF555RUrPj7ePf2b3/zGevHFFy3LOvu83XPPPe7nqqyszJo3b541YsQI\nq6SkxLIsy3rwwQetgQMHWh9//LHHdidOnGgNHDjQ2r59+yXqyZWntu+Bf/7zn617773XOnr0qGVZ\nllVcXGzNmDHDGjNmjGVZlpWSkmKNHz/e3b6wsNBKTEy0Ro4c6X6e0TCSk5MrPcbuuusuq6SkxHr8\n8cet559/3t1+//79Vu/evd2fR6+U9zmGrnlp7dq1uuuuuzRy5EitXbu21sssy/K4zXbPnj0VHBys\nXbt2uZejYYWHh+sf//iHe3rbtm267bbb3NPHjx/XsWPH1L17d/e86OhovfPOO7Lb7Ze0VlR0/jF0\n4403qkWLFu7jJzc3V1dddZVuvPFGffbZZ5KknJwcnThxQqGhobXe/jk2m02RkZH66quv6rkXuNCF\nr40RERHKzc2tcvmFr524dH7xi18oPz9fa9eu1ZYtW7R//35NnjxZJ06c0IoVK/T888+rTZs2kqRG\njRpp6tSpstvtWr9+vXsbd9xxh9555x33dEFBgQ4ePKjrrrvukvfnSlPTe+CJEyf0xhtv6LnnntM1\n11wj6ey3/7NmzaryJ0SaN2+uP/7xj2revLnH84z6VVBQoOXLl1d6jDVt2lTr16/Xvn371K1bN/c6\nnTp1UmpqqsdnmivhfY6g44Xy8nKlpaVp5MiRuvPOO7VlyxaVlpbWuKwqpaWlatq06aUoHZKGDRum\nDRs2uKc3bNigYcOGuacDAwN12223aezYsVq9erUOHTokSe4XfFxe+vbtq/T0dElSRkaGevbsqbCw\nMPdQt+3btys8PFyNG1/8iF2Xy6U1a9aoR48e9Vozqnf69Gn9/e9/dw+xqAqvnb7h5+enOXPmaP78\n+XrmmWc0Z84cNWnSRLt379a1116r4ODgCusMHDhQ27dv95jetm2bzpw5I0l6//33NWTIkEvWhytZ\nTe+Bu3fvVrt27dSxY0eP9Zo2barIyMhqtx0ZGamMjIz6LBfn2bVrl9q3b1/pMRYZGant27frpz/9\nqRITE7VkyRJ98cUXsizLPWy0Mqa+zxF0vPDhhx/qtttuU0BAgFq0aKFevXppy5YtNS6rzNatW3Xs\n2DH17NnzUpV/RbPZbOrdu7f27dunEydOqKSkRLt27VJERITHNxyvv/66hg4dqpUrVyoqKkp33XWX\nNm7c6F5eWlqq4cOHa/jw4Ro2bJiGDx+uRYsW+aJLV7y+ffu6Q01GRobCw8N1++23e8zr27dvrbc3\ndepUDR8+XNHR0erdu7fatm2r6dOnN0jt8DRu3DgNGzZM/fv31+eff67Y2Ngq2/La6VshISG67rrr\n1LhxY918882SpJMnT1b5gap169Y6efKke7pZs2bq2bOn/vWvf0mSUlNTNWzYMEY1NLDavAeePHlS\nrVu3rtP2mzdvrlOnTtVnyThPQUFBtcdYYWGhnnzyST3++OPatm2b7r33Xt1xxx36y1/+4tH2Snif\n42YEXli7dq0+/PBDhYeHy7IslZWVqaioSFFRUUpJSaly2Tnjxo1zX3DboUMHvfrqq7rqqqt82KMr\ni81mU1RUlFJTU3X11Verb9++8vPz82jTvHlzTZkyRVOmTNHx48e1Zs0aPfHEE1q/fr3sdrsaN26s\n1NRUH/UA5+vbt6/+8Ic/qLi4WDt27NC0adPUokULffHFFzp9+rS2b9+uyZMn13p78+fPV48ePXTm\nzBnFxMRo4MCB8vf3b8Ae4JyVK1e6h2N8+umnGjNmjNatW+f+0HXha+fSpUt57fSR1atXy9/fXzfc\ncINeffVVTZw4Ua1atdLRo0crbX/s2LEKFzqPGDFC77zzjkJDQ3Xs2DE5nc5LUfoVr6b3wFatWikv\nL69O287Nza327AG807Zt22qPsXbt2kmS7rnnHt1zzz1yuVz64IMP9Kc//UmtW7fWvffeK+nKeJ8j\n6NRRQUGBduzYoR07drhfGMrKyjRgwAAdP368ymX5+flq1aqVJM83c/jG8OHDtWDBAgUGBur++++X\nJPfdf/Ly8pSbm+v+pjgwMFC/+MUv9N577+nrr7/WLbfc4rO6UVHr1q3VuXNnbdiwQS1atHC/yTqd\nTr377rtq1KiRbrjhhlpv79y3mk2aNNGUKVP03HPPKSUlpUFqh6fzv82//fbb1aFDB2VmZio6OloS\nr52Xi++++04vvvii3nrrLTVp0kR33323oqOj1aNHD508eVJfffWVunbt6rHOBx98oHHjxnnMGzBg\ngJKSkvTuu++6n2NcGtW9B4aGhuo///mPvvjiC910003udUpLS/XSSy9V+cVReXm5Nm3apClTpjR8\nB65QTqdT//nPf6o8xsaOHautW7dqwIABks5eWxUTE6Pdu3dr79697rZXwvscQ9fq6N1331VERITH\ntx9+fn6644479O6776pPnz4VlvXv399jPCyn5n3n3GPfo0cP5eXlad++fQoPD/dYduTIEU2ePNl9\na0ZJysrK0nfffee+YJPn8PLSp08frVy5Ur1793bP69Wrl1auXFnlsLXaPIcjR47U6dOntW7dunqr\nFbXzzTffKCcnR126dHHP47i7PMyYMUOPPPKIgoKC1K5dO02ePFkzZsxQ8+bNNXHiRP3ud79zX9tY\nVlam+fPnq7y8XMOHD/fYTtOmTdW/f3+9/vrrHteIoOHU5j2wRYsWio+P1+9+9zsdOHBAklRcXKyZ\nM2fqyy+/dN+U5/zjsaioSH/4wx/UsmVLnssG1KJFCz300ENVHmODBw/WU0895RFajh07po8++sj9\nPF/I1Pc5zujU0d///vcK30pJ0uDBg7V48WI98sgjFZYNGTJEixcv1oMPPujxmwGVsdlsGjx4sKT/\n+32WJUuWXNQ1Bqja+Y9/VFSUioqKKiwLDQ3VM888o6SkJJ06dUrl5eVq3bq1XnzxRbVv3165ubk1\nPo9oOJU99v369dOyZcs8vkkMDw/XwoULNX78+Fpv58J5jRo10m9+8xvNmTNHw4cP58L3BmSz2dxD\n0yzLkt1u19NPP+0+G8cxd3l4++23lZ+fr4cfftg978EHH9Q777yjVatW6ZFHHpHdbtekSZM8fuNj\n2bJl7huCnP9cjhgxQv/+97/dgZbnuWHV5j1QkqZMmaKAgABNmjRJ5eXlatSokQYPHqykpCR3m127\ndmn48OEqKytTSUmJBg8erNdee02NGvFdekP6zW9+oxYtWrhfL0+fPq3w8HAtX75czZs3d9+V7b/+\n678knf1C4cEHH9TQoUMlXTnvczaLr8YAAACAH6U///nP+uGHHzwCKM4ibgMAAAA/UiNGjFBaWpq+\n//57X5dy2SHoAAAAAD9St9xyix566CHFxsZq1qxZvi7nssLQNQAAAADG4YwOAAAAAOMQdAAAAAAY\nh6ADAAAAwDgEHQAAAADGIegAAAAAMM7/A8ts2o71ew3aAAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3246b27190>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "optimal_factor_neutral_pf = optimal_portfolio_factor_neutral()\n",
    "plot = draw_asset_barplot(\n",
    "    optimal_factor_neutral_pf, \n",
    "    'Optimal Portfolio (Factor Neutral)',\n",
    "    {'ylim': (-MAX_POSITION_WEIGHT - 0.1, MAX_POSITION_WEIGHT + 0.1)},\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA0cAAAHvCAYAAACfaqQpAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzt3XuYlXW9///XyADDoIl4ICFGFHNT29AEDBADQRhAMQW9\n3NjWSt15yEOIWzxsI094gDSRzAwJN227tDTdKnESZQcXoKBGVlrJQQUPV4oBMgPKrN8f/lhfR2AY\nGQ2kx+Mv1z3ve/G5x2G5nt73uqekUCgUAgAA8E9ul+29AAAAgB2BOAIAAIg4AgAASCKOAAAAkogj\nAACAJOIIAAAgiTgC+Kc3efLkdO/ePaeccspWZ3/961+na9euSZIFCxbkkEMOSXV19Se9RAD4hyjd\n3gsAYPN69+6dN954I40aNUqSNGnSJAceeGDOP//8dO/efZufd8aMGfn85z+f/fbbL0ny05/+NIMG\nDcpll11Wr/1LSkqSJJ07d87vfve7bVrD8uXL06dPnzRp0qT4fBv17NkzY8eO3abn3ej555/Pm2++\nmSOOOKJBz7PRk08+mdNOOy1Nmzattb1QKKSkpCTz589PWVnZx/JnAbD9iCOAHdjll19ePKOzfv36\n3HfffTnrrLPy4IMPpn379h/puTa+kb/11lszfPjwYhytWrUqFRUVH/vat6akpCS//vWvP/Jx1Mev\nfvWrNG7ceJviaOP36cN2hgja0rEB8D6X1QHswAqFQvGfmzRpkn//939Pu3bt8sQTTyR5P5huuOGG\n9O7dO4ceemhOPvnkLFiwoLhP7969c+edd6aysjKXX355jj322PzlL3/J+eefn0svvTS9e/fO8uXL\nc/311+fkk09OkjzzzDP5t3/7t3Tq1Ck9evTIddddl/fee2+Ttc2fPz8dOnRIVVVVkuT111/P+eef\nn27duqVz584599xz8/rrr9d5bB88vg97++23M2zYsBxxxBHp0qVLvvnNb2bx4sXFr69cuTLf/e53\n07lz5/To0SM33nhjampq8v3vfz//8z//k0mTJqVPnz5JktWrV+eyyy7LV7/61Xz5y1/Ot771rfz1\nr38tPleHDh0yadKk9OrVK+PGjavXv48Pu+WWWzJkyJDi45deeimHHnpoFixYkCeffDJf+MIXMmvW\nrPTr1y+HHnpozj777KxZs6Y4P3PmzJxwwgn58pe/nKOOOiq333578WtLly7N6aefni5duqRLly45\n88wz8+qrryZJLrvsslx44YW11tKhQ4fMmjUrSXLqqadmzJgxGTJkSL75zW8mSV577bWce+656dat\nW7p06ZKLLroob7/9dpKkuro6l112Wbp3757DDjssQ4YMybx587Z43AA7E3EE8ClTU1NTvNTulltu\nyZw5c/Lf//3feeqpp9KjR4+cc845Wb16dXH+4Ycfzk9/+tNcf/31eeSRR5Ik48aNyw033JCZM2em\ndevWufzyy3Pvvffmrbfeyumnn56BAwdm3rx5ufvuuzNz5sz8+Mc/3mQdJSUltc5CfOc730mTJk0y\nY8aMzJw5M++9914uvvjibT7O0aNH54033si0adMyZ86c7LXXXrniiiuKX7/iiitSU1OTWbNm5f77\n78+MGTNy99135/vf/346d+6c0047LY899lhxdvny5XnwwQczd+7ctG7dOmeffXat2Jk2bVoeeOCB\nnH/++VtcU11x9J3vfCdVVVW57777kiSjRo3K4MGD07lz5+K+DzzwQHGtr776asaMGZMk+fOf/5zz\nzz8/55xzThYsWJBbbrkld999dx544IEkyTXXXJPWrVtn7ty5+b//+7/svffexX3rY/LkyRk5cmTu\nvvvuJMk555yTVq1a5fHHH8/06dPzzjvv5JprrkmSTJw4MX/6058yZcqULFy4MCeeeGIuvfTS1NTU\n1PvPA/i0EkcAnxJVVVWZNGlSVqxYkb59+yZJ7r///px11ln53Oc+l8aNG+fcc89NTU1Nfvvb3xb3\nO+KII7Z62dzGN/0PP/xw9tlnn5x22mlp3Lhx2rdvn6FDh2by5Ml17v/888/nD3/4Q0aMGJHmzZvn\nM5/5TM4777wsWLAgf/vb37bpeK+66qqMHz8+zZs3T5MmTdKvX7/84Q9/SPL+WaMnnngiZ511Vpo3\nb55WrVrl5ptvzmGHHbbJ86xatSrTp0/PsGHD0rJly5SVlWX48OF55ZVXsmjRouJcZWVlWrZsucX1\nFAqFdOvWLYccckgOOeSQdOzYMYccckgx2Jo0aZJrrrkmt956ax5++OE8//zzGT58eHH/kpKSnHHG\nGdltt92y11575etf/3ox3u6///585StfSb9+/dKoUaMceuihGThwYPH7vmrVqjRu3DilpaVp1qxZ\nrr/++vzgBz+o9/fyX//1X9OxY8ckye9///v8+c9/zsUXX5yysrK0aNEiF1xwQaZMmZLq6uqsXr06\njRo1Kn4ebOjQoXniiSeyyy7eMgA7P585AtiBXX/99bnpppuSJGVlZTnooIMyYcKEtGnTJqtWrcqq\nVatqfWanUaNGadOmTV555ZXittatW9f7z3vllVc2+QzQfvvtl+XLl291v+bNm2efffaptV+hUMjy\n5cuz1157bXa/wYMHF88+bfw8zDe/+c0MGzYsS5YsyY033pjf//73qaqqSk1NTTZs2JDk/Rs6FAqF\ntGnTpvhcX/rSlzb7Z2xc+wePq2XLlmnevHmWL1+eQw45JEmy77771nmM9fnMUadOndKvX79ccskl\n+dGPfpTmzZvX+nq7du2K/9y6deu89dZbKRQKefnllzf7fd94Odt5552X//zP/8ysWbNy5JFHZsCA\nAcW7BtbHB38GXn755WzYsKHWTT02fu/feOONnHLKKXnsscfSs2fPdO/ePb169coxxxyT0lJvGYCd\nn1c6gB3YB2/I8GHr16/f4n4fvNxt4yV49bGl59zah/jru5YP29INGQqFQs4666wcdthh+c1vfpOW\nLVvmsccey3nnnZckxbMY9bnUq661fVB93vzXdVndRi+//HLKy8uzZMmSTb62Me4++FwlJSVb/b73\n7Nkzs2bNyhNPPJGZM2fm7LPPzimnnJJLLrlkk3029z354M9A06ZNU1ZWlmeffXaLx/Cb3/wm8+bN\ny+OPP57Ro0fnF7/4Re655x5nj4Cdnlc5gB1YXW/G99xzzzRv3jwvvvhicdv69euzfPnyWmcoPoqK\niopaNz1IkhdffHGrl+W1bds277zzTt54441a++2yyy5p27btZvcpKSnZ4vH97W9/y4oVK3LqqacW\nL3V77rnnil9v06ZNSkpKagXIwoULM3Xq1M2urVAo1Po+vf7663nnnXe2+fu0JQ8++GBeeeWVTJw4\nMbfffntefvnlWl//4OPly5dn7733TrL57/vixYuL3/eVK1emWbNmGTBgQEaPHp3vf//7uffee5O8\nfznfB3/X1LJly+pc43777Zd169blpZdeKm6rrq7OW2+9leT9yzfXr1+fbt265fLLL899992XZ599\nNs8///xH/XYAfOqII4BPqZKSknzta1/LnXfemRUrVqS6ujq33nprmjVrlh49emxxv6ZNm2bp0qW1\n7pS20cCBA/Paa6/l5z//ed577708//zz+cUvflHrLmwftDFuvvSlL+Xzn/98brrppqxduzZvvvlm\nbrvttvTs2TN77LFHnftuTsuWLVNeXp5nnnkm69evz7Rp0/Lkk08meT9sdt999xx99NG5/fbb8/bb\nb+f111/PyJEji/FRVlaWV155JatXr07Lli3Ts2fP3HrrrVm5cmXWrFmT0aNH51/+5V/yxS9+cYtr\n+Khrfuutt3LjjTdm5MiR+dKXvpQTTzyx1g0kCoVCJk6cmNWrV+eNN97IL37xixx99NFJkuOPPz7z\n58/PjBkzsmHDhixYsCCPPvpohgwZknXr1qWysjL33HNP3n333axbty7PPfdc8Vbs7dq1y+9+97u8\n+uqrWbNmTe68885Nfh/TBx144IHp3Llzrr322rz11ltZs2ZNrr766uId784777yMHDkyq1evTqFQ\nyLPPPpsmTZps9bJDgJ1Bg+No7ty5GTx4cPr3758zzjhjs7dtrWtm6dKlGTx4cE4//fRa+7z66qs5\n/fTTU1lZmcGDB2f+/PkNXSrAp0p9fh/NJZdckkMPPTRDhw5Nz54988ILL+TnP/95mjVrtsXnGDp0\naG6++ebineQ+OLPvvvvmRz/6UR566KF07do1F154YU477bTiLaDrWuOPfvSjrFq1Kr17987gwYPT\ntm3bjB49epuOr1GjRrn66qtz1113pXv37pk2bVrGjRuXL3zhCxk0aFD+/ve/Z9SoUdl9993Tu3fv\nnHjiifnqV79a/G/J4MGDM2fOnPTt2zfvvfderr/++uyxxx4ZNGhQKisr8+6772b8+PH1WssHffCG\nDB+8KcOMGTNy3XXXpVu3bunWrVuS5IILLsiyZcvyy1/+svhn9OvXL0OGDEnfvn2z77775qKLLkqS\ndOzYMddff33Gjh2bLl265KqrrsqVV16Zvn37pmnTphk3blweeOCBHH744fnqV7+aZcuWFe9Wd+KJ\nJ6Zjx44ZOHBg8b+1u+66a53HNmbMmJSWlqZPnz45+uijs2bNmuINHkaNGpWVK1fmqKOOSufOnXPX\nXXfltttu22LkAuxMSgr1uYB6C6qqqtKnT59MmDCh+Dsi5syZkzvuuKNeM4sXL86FF16Yww8/PEuW\nLMmECROK+5155pnp2bNnTj311Dz//PM588wzM3PmzDRp0qRhRwwA/2BPPvlkvvGNb+Tpp58uhisA\nO54GnTmaN29eKioq0qFDhyTJkCFDMnv27Kxdu7ZeM82bN8+kSZNy8MEH13reNWvWZP78+TnppJOS\n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\nAgAASCKOAAAAkogjAACAJOIIAAAgiTgCAABIIo4AAACSiCMAAIAk4ggAACCJOAIAAEgijgAAAJKI\nIwAAgCR/JGiyAAAOnElEQVTiCAAAIIk4AgAASCKOAAAAkogjAACAJOIIAAAgiTgCAABIIo4AAACS\niCMAAIAk4ggAACCJOAIAAEgijgAAAJI0MI7mzp2bwYMHp3///jnjjDPy+uuvf+S5pUuXZvDgwTn9\n9NNr7fPqq6/m9NNPT2VlZQYPHpz58+c3ZKkAAAB12uY4qqqqyvDhwzNq1KhMmTIlvXr1ysiRIz/S\n3OLFi3P++efny1/+8ib7XXnllTnqqKMyderUjBo1KsOHD8/69eu3dbkAAAB12uY4mjdvXioqKtKh\nQ4ckyZAhQzJ79uysXbu23nPNmzfPpEmTcvDBB9faZ82aNZk/f35OOumkJEmHDh3SunVrZ48AAIBP\nzDbH0dKlS9O2bdvi4/Ly8rRo0SIvvfRSvedatWqVFi1abPLcy5YtS8uWLVNWVlbc1rZt2yxevHhb\nlwsAAFCnBl1W17Rp01rbysrKNjlzVN+5re3TtGnTVFVVbetyAQAA6lS6tYHp06dn9OjRKSkpSZIU\nCoWUlJRk6NChWbduXa3Z6urqlJeX19pWXl5er7mG7lPUrt2m25Yurf/sp3h+//fey/+sXJOvnzxq\ns+O/+OWVm90+9KRrzO9E8zU1G7L3tFFJ6f//13sH+fk0/4+f3/iasMsujYqbt/fPp/l//Pzav7+R\n/Xv3/n+vCR/0Kfp5Nm/evPmPbf7++zf/tdQjjvr27Zu+fftusn3WrFmZPHly8fHq1auzatWqtPvw\nG/b996/X3AdVVFRk5cqVqaqqSrNmzZK8f3neiSeeuLXlZt1mbtrw3MKFm509eAs3ePg0z+/evEnO\nP/azm53f7ZFGm91ufmebb5Sampri34Ud6efT/D9+fvfmTWpt3/4/n+b/8fOfTc3cmn/6/z6aN2/e\nfF3zG5UUCoVCnRNbsG7duvTp0ydjx47NYYcdlttuuy1/+ctfMnbs2I8898ADD+Thhx/Oz372s+K2\ns88+O4cddli+/e1vZ968eRkxYkRmzJiRxo0bb3FNCxcuTKdOnbblcAAAgH8CdTXDNsdRkjz11FO5\n9tprU11dnYqKitxwww3Zc889s2jRoowdOzbjx4+vc+7OO+/MuHHjUlNTk0KhkNLS0nTu3Dl33XVX\nXn/99YwYMSIrVqzIrrvumpEjR+aQQw7Z5gMFAAD4xOJoRyOOAACAutTVDNt8tzoAAICdiTgCAACI\nOAIAAEgijgAAAJKIIwAAgCTiCAAAIIk4AgAASCKOAAAAkogjAACAJOIIAAAgiTgCAABIIo4AAACS\niCMAAIAk4ggAACCJOAIAAEgijgAAAJKIIwAAgCTiCAAAIIk4AgAASCKOAAAAkogjAACAJOIIAAAg\niTgCAABIIo4AAACSiCMAAIAk4ggAACCJOAIAAEgijgAAAJKIIwAAgCTiCAAAIIk4AgAASCKOAAAA\nkogjAACAJOIIAAAgiTgCAABIIo4AAACSiCMAAIAk4ggAACCJOAIAAEgijgAAAJKIIwAAgCTiCAAA\nIIk4AgAASCKOAAAAkogjAACAJOIIAAAgiTgCAABIIo4AAACSiCMAAIAk4ggAACCJOAIAAEgijgAA\nAJKIIwAAgCTiCAAAIIk4AgAASCKOAAAAkogjAACAJOIIAAAgiTgCAABIIo4AAACSiCMAAIAk4ggA\nACCJOAIAAEgijgAAAJKIIwAAgCTiCAAAIIk4AgAASCKOAAAAkogjAACAJOIIAAAgiTgCAABIIo4A\nAACSiCMAAIAk4ggAACCJOAIAAEgijgAAAJKIIwAAgCTiCAAAIIk4AgAASCKOAAAAkiSlDdl57ty5\nGT16dNauXZs2bdpk1KhRadWq1UeaW7p0aS666KK0aNEiEyZMKO7Tu3fvlJaWprS0NIVCISUlJZk8\neXJDlgsAALBF2xxHVVVVGT58eCZMmJAOHTpk0qRJGTlyZO644456zy1evDgXXnhhDj/88CxZsqTW\nfiUlJbn77ruz7777busSAQAA6m2bL6ubN29eKioq0qFDhyTJkCFDMnv27Kxdu7bec82bN8+kSZNy\n8MEHb/L8hUIhhUJhW5cHAADwkWxzHC1dujRt27YtPi4vL0+LFi3y0ksv1XuuVatWadGixRb/jJtu\nuimDBg3KSSedlJkzZ27rUgEAALaqQZfVNW3atNa2srKyTc4c1Xfuw4499tgceeSR6dKlSxYsWJCz\nzjorDz74YK3QAgAA+LhsNY6mT5+e0aNHp6SkJEmKN0cYOnRo1q1bV2u2uro65eXltbaVl5fXa+7D\nLrroouI/d+7cOYcffnhmz56doUOH1rnfwoULt3ZIAAAAm9hqHPXt2zd9+/bdZPusWbNq3T1u9erV\nWbVqVdq1a1drbv/996/X3AetX78+S5cuzUEHHVTctmHDhpSW1r3cTp06beVoAAAANm+bP3PUtWvX\nrFixIk8//XSSZOLEienVq1fKyso+8tyHb75QXV2dU045JYsWLUqSvPDCC3nmmWfSvXv3bV0uAABA\nnUoKDbgl3FNPPZVrr7021dXVqaioyA033JA999wzixYtytixYzN+/Pg65+68886MGzcuNTU1KRQK\nKS0tTefOnXPXXXdl9uzZGTNmTNavX5+ysrJceOGF6dmz58d24AAAAB/UoDgCAADYWWzzZXUAAAA7\nE3EEAAAQcQQAAJBEHLGT+/Wvf51vfetbH2mfJUuWZMGCBZ/QioBPyqJFi3LmmWdu72UAO6Bx48bl\nyiuv3N7L4FNAHLHT2nivkY2/wLi+pk+fnqeeeuqTWBLwCerYsWPxLqkAsC3EETuU5cuXp0ePHhk/\nfnz69++f/v37Z9GiRTn77LPz1a9+NVdccUWS5Je//GUGDBiQysrKnHrqqXn11VeTvH+m6IILLsi3\nvvWtjB49utZzr1mzJoMGDcq0adOSJPfee28GDBiQPn36ZPjw4Vm3bl0ef/zx3HnnnZk0aVJuvPHG\nf+zBA/W2YcOG/Nd//Vf69++fysrKXHDBBZk5c2b69euXJDn11FMzcODADBw4MD179kzXrl2TvP9L\nxq+99tpUVlamT58++clPfrI9DwPYRieddFKmT59efDxjxoycfPLJW3x/8EG9e/cu/v7NDz+eMWNG\nBg0alL59++aMM87I22+//ckfDDsUccQO5+23384+++yTKVOm5KCDDsqwYcNy44035n//93/zyCOP\nZNGiRbn66qvzs5/9LFOnTk3btm1z++23F/efM2dOrr766lxyySXFbYVCIRdffHGOO+649OvXLwsW\nLMhtt92WSZMm5bHHHstuu+2WW2+9NUcddVT69u2b0047LSNGjNgehw/Uw+zZs7N8+fJMmTIlU6dO\nTYcOHdKkSZPimeJJkyZl8uTJmTx5cg488MCcc845SZKf/vSnWbx4cR599NE8+uijmTp1ambNmrU9\nDwXYBpWVlXnssceKj2fMmJG+ffvW+f5ga15++eWMGDEiP/zhDzN9+vR85Stfyfe+971PYvnswMQR\nO5wNGzakf//+SZKDDjooBx98cHbfffe0aNEie+21V959990sWLAgn/3sZ5MknTt3zssvv1zcf7/9\n9kvbtm2LjwuFQn7wgx+kZcuW+Y//+I8kyeOPP54BAwZkr732SpKcfPLJxTNKwI5vjz32yF//+tdM\nnz49VVVVOffcc9OkSZNN5saPH5/S0tJ84xvfSJI88cQTOeWUU1JaWpqysrJ87Wtf83cfPoUqKysz\na9asFAqFbNiwIU888UQGDRpU5/uDrfntb3+br3zlK2nfvn2S998bzJw5M34l6D+X0u29APiwRo0a\nFd/kNGrUKOXl5bW+9u677+a2227L448/npqamqxZsyb7779/caZFixa1nu+5557Ls88+W+vGDKtX\nr8706dMzZ86cJO8H2YYNGz7JwwI+Rh07dsyVV16ZSZMm5dJLL81RRx1V/J8qG/3+97/PPffck/vv\nv7+4bdWqVRk1alRuvvnmFAqFvPvuuznkkEP+0csHGqht27bZd9998/TTT+fdd9/NAQcckH322Sc/\n+MEPtvj+YGtWr16dp556KgMHDkzy/v9c3X333bNy5cq0bNnykzoUdjDiiE+dv/3tb3niiSdyzz33\nZPfdd88vf/nLPPzww1ucb9WqVe64446cfPLJ6d27dw4++ODss88+OeGEE2pdegd8uvTr1y/9+vXL\nqlWrctlll+Wuu+4qfm3NmjW5+OKLc91112WPPfYobt9nn31y5plnpmfPnttjycDHqH///nnsscey\nfv36DBgwII8++mi93h80atQoNTU1xcerVq1K8v7rQ/fu3XPrrbf+w46BHY/L6tjhbO309VtvvZU2\nbdoU/2/Ob37zm6xdu3aL8/vss08+97nP5dJLL82IESOyfv369O7dO9OnT89bb72V5P1rlTfe5aq0\ntDR///vfP74DAj52DzzwQPGzBJ/5zGdywAEH1Loz5VVXXZW+ffumW7dutfbr06dP7rvvvtTU1KRQ\nKOTHP/5xZs+e/Q9dO/Dx6NevX+bOnZtZs2alf//+efPNN+v1/mDvvffO888/nySZPHly1q9fnyTp\n0aNHFi5cWLwUb9GiRbnuuuv+cQfEDkEcscOp69bbJSUl2XvvvfP222+nsrIyF198cb773e/mtdde\ny0033VTn8w4aNCjt27fPLbfcki9+8Yv59re/ndNOOy3HHHNM7r777vTp0ydJctRRR+Xee+/NhRde\n+LEeF/Dx6dOnT/7whz+ksrIyxxxzTF588cWcfvrpSZLXXnstDz/8cKZPn56BAwdmwIABGThwYJYv\nX56vf/3rad26dY455pgMHDgwixcvTqdOnbbz0QDbol27dqmpqclnP/vZ7L333jn22GOzcuXKrb4/\nOPfcczNhwoQMGjQoixcvzoEHHpjk/Wi65pprct555+WYY47Jtddem2OOOWZ7HBrbUUnBp8wAAACc\nOQIAAEjEEQAAQBJxBAAAkEQcAQAAJBFHAAAAScQRAABAEnEEAACQRBwBAAAkSf4/uYPrZdCjmaAA\nAAAASUVORK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3244f5ccd0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plot = plot_factor_exposures(optimal_factor_neutral_pf, risk_factors);\n",
    "plot.axhline(MIN_FACTOR_EXPOSURE, color='r', linestyle='dashed')\n",
    "plot.axhline(MAX_FACTOR_EXPOSURE, color='r', linestyle='dashed');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Minimize Distance from Target Portfolio with Turnover Constraints\n",
    "\n",
    "Many algorithms written on Quantopian today perform stock selection via a process other than explicit returns/alpha-modeling. Pair-trading algorithms, for example, work by identifying pairs of [cointegrated](https://www.quantopian.com/posts/quantopian-lecture-series-integration-cointegration-and-stationarity) stocks and entering into a long position in one half of the pair and a short position in the other half of the pair.\n",
    "\n",
    "For these existing algorithms (or for new algorithms written in a style other than alpha-modeling), it may not be natural to express portfolio construction in terms of an explicit alpha-maximization problem.\n",
    "Nevertheless, it may still be useful to frame the portfolio construction process as an optimization problem using different objectives and constraints."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose we have an algorithm that trades in four pairs and periodically decides which of the pairs it should allocate capital toward. Via its own internal logic, the algorithm arrives at a \"target portfolio\" that expresses its ideal holdings. The algorithm wants to trade from its current holdings into its ideal holdings, but it doesn't turn over its entire portfolio at once because doing so may incur excessive transaction costs.  The algorithm also wants to ensure that it maintains a net exposure of 0 in all of its pairs.\n",
    "\n",
    "We can frame this as an optimization problem as follows:\n",
    "\n",
    "Minimize the distance between the new portfolio and the ideal portfolio, subject to the constraints that:\n",
    "\n",
    "1. The long components of our pairs have a weights $\\geq$ 0.\n",
    "2. The short components of our pairs have weights $\\leq$ 0.\n",
    "3. The sum of the weights in each of our pairs is 0.\n",
    "4. The sum of the absolute values of the changes in weight across all stocks is less than our max turnover.\n",
    "\n",
    "In fancy math language, we can say the following:\n",
    "\n",
    "Given a vector $W_{current}$ of current portfolio weights, a vector $W_{ideal}$ of ideal portfolio weights, a maximum turnover rate $T_{max}$, and a list of pairs of long/short stocks $P = [(l_1, s_1), (l_2, s_2), \\dots, (l_n, s_n)]$, choose a vector $w$ of weights that solves the following system:\n",
    "\n",
    "\\begin{align}\n",
    "\\text{minimize}&& \\\\\n",
    "&&||w - W_{ideal}||_2 \\\\\n",
    "\\text{subject to}&& \\\\\n",
    "&&w_l &\\geq 0&& l \\in [l_1, l_2, \\dots, l_n] \\\\\n",
    "&&w_s &\\leq 0&& s \\in [s_1, s_2, \\dots, s_n] \\\\\n",
    "&&w_l + w_s &= 0&& (l, s) \\in P \\\\\n",
    "&&||w - W_{current}||_1 &\\leq T_{max}&& \\\\\n",
    "\\end{align}\n",
    "\n",
    "(In the above, $||v||_1$ is the $L^1$ norm of $v$, or the [\"Taxicab Norm\"](https://en.wikipedia.org/wiki/Norm_%28mathematics%29#Taxicab_norm_or_Manhattan_norm), and $||v||_2$ is the $L^2$ norm of $v$, i.e, the standard [Euclidean Norm](https://en.wikipedia.org/wiki/Norm_%28mathematics%29#Euclidean_norm).)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While the mathematical definition of the problem here is a bit hairy, we can express the problem succintly using the `TargetWeights` objective and the `Pair` and `MaxTurnover` constraints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzoAAAHvCAYAAACc3aoBAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzt3X+clWWB9/HvIDA0QCJaai6j5i7NpqKICKTGKBHIbGmw\nWqbSbtSLly6PPYaaP9aQUsRcssxW11gXyNpnTSVWZOlR19hISIOUtWfdDEMSFcNfTMKgDOf5w5dn\nHUBABkEu3++/OPe5zn2ue87ch/OZ+z7n1FQqlUoAAAAK0mFXTwAAAGBHEzoAAEBxhA4AAFAcoQMA\nABRH6AAAAMUROgAAQHGEDkDhbrjhhnz2s5/d7HWzZs1KY2PjNq3ngQceSENDQ9auXbsDZ/c/nnrq\nqfTp0ydLly59W9b/dpk8eXKOOuqoXHvttVsde/HFF+dLX/pSki0/LgC0X43v0QHY/Zx11lk5/PDD\nc+GFF77l286cOTODBw9Oz54939LtHnjggXzuc5/L4sWL8573vGeT6xsaGtKxY8fsscceSZL3vOc9\nOfTQQ3PeeeflsMMOe8vzbI8VK1ZkyJAh6dy5c2pqapIk3bt3z5FHHpkLLrggBx544Have/r06Tnj\njDPSsWPHNDc355hjjsn111+fIUOGbPW2F198cdasWZNvf/vb233/AGwbR3QA3kVaW1tz1VVX5bnn\nnntb1v/d7343Dz/8cB5++OHce++9+fCHP5wxY8bk+eefb9d6t+dvcjU1NZk5c2Z1PrNnz063bt3y\nxS9+Ma+++up2zeH555/P5MmT88orryRJVq9enSTtCicA3h5CB2A3t2LFijQ0NOT+++/Ppz71qfTt\n2zef/exns3LlyiTJ9ddfn7/8y79Mkhx99NFpbm7OqFGjct1112XmzJkZOHBgdV33339/Tj311PTr\n1y/HH398rrzyyu2KjCTp2rVrxo8fn/Xr1+eBBx5Ikvz+97/P2LFjM3DgwAwYMCDnnHNOVq1a1WY7\nfvvb3yZJTjzxxNx0000ZNmxYLrnkklQqlVx99dU5/vjj07dv3zQ1NWXOnDlvev+VSqXN3Hv06JGL\nLrooy5cvz6OPPpokWblyZf7X//pfGTRoUI4++uicc8451Z/b6/P50Y9+lEGDBuWmm27KRz/60STJ\noEGDcuutt2b48OFJkpEjR+aaa65JkvzoRz9KU1NTjjjiiAwbNiz/8i//stn5fec738moUaOql3/1\nq1/lM5/5TPr165fjjjsuV155ZdavX//Wf/AAJBE6AMWYMWNGpk6dmvvuuy8vvvhipk2btsmY2bNn\np1KpZObMmTn33HOTpHpq17p16zJu3Lg0NTVl0aJF+eEPf5jZs2fntttu2+45bdiwIRs2bEjHjh2T\nJJdddlnq6uryH//xH7n33nvzxz/+MVdffXV1/Otzed2dd96Z733ve7nqqqsye/bs3HXXXbntttvy\nq1/9KhdccEH+9m//Ni+99NI2z6e1tTVJ0qlTpyTJ3/zN36Rz586555578u///u9Zv359xo8f3+Y2\nP//5z3PPPfdk7Nixufnmm5Mkv/jFL3Laaadl7ty51Z/nBRdckJ/+9KeZNGlSLr/88vzqV7/KxRdf\nnK9//ev5xS9+sclcampqqtv7/PPP5/Of/3xGjBiRhQsXZvr06fn3f//33HDDDdu8bQC0JXQACvHp\nT386e++9d3r06JEBAwZs8U39mztKU1tbm5/97Gc566yzkiS9evXKkUcemUceeWS75tPc3JwpU6ak\na9eu1aNGN910UyZPnpzOnTunW7duOfHEE9usf+N5HXvssamvr6+ur0OHDuncuXOSpLGxMYsXL86e\ne+65TfN57rnncvXVV+dDH/pQevfunUcffTS//vWv85WvfCVdu3bNe9/73owbNy6LFi2qHmVKkpNP\nPjldu3Zts66N5/n65dtuuy1/8Rd/kf79+6dDhw5pbGzMRz7ykS0eeUpeC7r3v//9GT16dDp16pRD\nDjkkp59++lZvB8Cb67irJwDAjnHAAQdU/92lS5e0tLS85XXMmTMn06dPz4oVK9La2prW1tZ88pOf\n3Obbjxs3Lh06vPY3tK5du6ZPnz6ZPn16unXrliRZsmRJvvWtb+XRRx/Nq6++mtbW1uy7775vur4P\nfOAD1X83NTVl1qxZOfHEEzNo0KB89KMfzcknn7zZD0Z43ciRI6tHTd773vemf//++Yd/+Id06NAh\nTz75ZLp27Zr3v//91fEHHnhgKpVKVqxYkX322SdJsv/++2/z9v/+97/P0Ucf3WZZfX19li1btsXb\nPfnkkznkkEPaLDvwwAOzYsWKbb5vANoSOgCFeD0wtteCBQty+eWX55prrsnHP/7xdOzYMePGjXtL\n67j++uszePDgzV63evXqjB07NqeddlpuvPHGdOvWLTNmzMj06dPfdH2vf4Jbkuy55575l3/5lzz0\n0EO57777MnXq1PzTP/1Tbr/99mpIbWzmzJmbBMTrXv9Agc154yl0r592ty3ebJ0bn5K3o24HwJtz\n6hpAAXbEC+L//M//TH19fUaMGJGOHTumtbW1+qb9HeHxxx/PmjVrMmbMmGqYvJXT4l555ZW8/PLL\nOfLII3PeeeflzjvvzLPPPpsFCxZsdnxNTc0WP0ihV69eefnll/Pss89Wly1dujQdOnRIr169qut4\nK+rr6/P444+3Wfa73/1uq5/KtrnbLV26tHraHgBvndABKMC2fjJaly5dkiTLli3Lyy+/3Oa6Aw44\nIH/4wx+yYsWKPP/88/n617+e7t27twmB9th///3ToUOH/OpXv0pLS0tuvfXWPP7441m9enXWrVu3\n1dtfccUVOffcc6sfjf3rX/86r776ajVKNra1n8nhhx+eP/uzP8s3vvGNrFmzJs8991y+853vZPDg\nwdlrr702u47Xf36PP/74Zr849VOf+lRmz56dxYsXp7W1NXfffXd+8Ytf5JRTTtniXEaMGJFnnnkm\nt9xyS9avX59HH300//zP/9zmU9kAeGvaHToLFizIyJEjM3z48IwZM6b6sZxv9JOf/CSnnHJKRowY\nkTPOOCOPPfZYe+8W4F1t4yMN23rkYe+9987HP/7xfPnLX86UKVPaXDds2LAMHjw4n/jEJ/KXf/mX\nOeyww3LhhRfmP//zP7fpi0m3Nod9990348ePz2WXXZbBgwfnsccey3e/+93sueeeGTZs2Cbr2Hh9\nF154Yfbaa6+MGDEiffv2zeWXX54rrrgiDQ0N2zWf5LXv/Vm9enVOPPHEjBw5Mr169ap+TPTm1vHn\nf/7n6du3b04//fTccsstm4wZPnx4zj333FxyySU55phjcsMNN+Tv//7vt/qFqfvvv3+++93vZtas\nWRk4cGC+9KUvZfTo0fmrv/qrrW4DAJtXU9neL0hIsnbt2gwZMiQ333xzGhoa8v3vfz8///nPc+ON\nN1bHPP300xk1alTuuOOO7LfffpkxY0buvPPO/OhHP9ohGwAAALCxdh3RWbhwYerr66t/TRs1alTm\nz5+fNWvWVMd07NgxU6ZMyX777ZfktS9Z29qnzwAAALRHu0Jn2bJlbc6NrqurS48ePbJ8+fLqsve9\n730ZNGhQkmT9+vW544478rGPfaw9dwsAALBF7QqdtWvXpra2ts2yLl26tDmi87oZM2bk2GOPzYMP\n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\n7NgxU6ZMyX777ZckGTRoUJYtW7b9MwYAANiK7Q6dZcuWpVevXtXLdXV16dGjR5YvX95m3Pve974M\nGjQoSbKybuUVAAAPcUlEQVR+/frccccd+djHPra9dwsAALBV7Tp1rba2ts2yLl26bHJE53UzZszI\nsccemwcffDDnnXfe9t4tAADAVnXc2oC7774711xzTWpqapIklUolNTU1Of3007Nu3bo2Y1taWlJX\nV7fZ9YwePTqjR4/OXXfdlc985jOZO3duOnfuvMX7XrRo0bZuBwAAQFVNpVKpbM8N582bl+9+97u5\n9dZbkyTNzc059thj88ADD6RLly7VcUuXLs2qVasyYMCA6rIBAwZk+vTp1ff3AAAA7EjbferawIED\n89RTT2Xx4sVJkmnTpqWxsbFN5CTJCy+8kPPPPz/PPvtskuSXv/xlWltb27y/BwAAYEfa7iM6SfLg\ngw/miiuuSEtLS+rr6zN58uTsvffeWbJkSa677rpMnTo1SfLDH/4wP/jBD1KpVNK5c+dccMEFOfbY\nY3fYRgAAALxRu0IHAADgnWi7T10DAAB4pxI6AABAcYQOAABQnK1+jw6vGTVqVNasWZN/+7d/2+br\nGhoacuCBB2aPPfZIa2tr3vve9+bLX/5yBg0aVL1+3rx52XfffXfKNuyuGhoaMmzYsHz7299us/zS\nSy/N7bffnkcffTRJ8utf/zrXXHNNnn322bS2tmavvfbKBRdckH79+mXFihUZMmRIPvjBDyb5n++D\n6tu3b/r165fvfe97qampybPPPptOnTqlR48eqampyVe/+tUMHDhwp2/z7mjGjBm5/fbbs379+qxf\nvz4HHXRQzj333Bx66KG56KKLMnv27Nx///1573vfW73NL3/5y5x55pmZPHlyTjnllF04+3K98Xko\nee13/4ADDqh+WAzts63PT0nyT//0T7njjjuyfv36tLa25rjjjsuXv/zldOvWLTNnzszXvva17L//\n/nn11VdTU1OTE088MX/zN3+T7t277+zN2m3NmDEjP/rRj9La2poNGzZkwIAB+d//+39nr732ygsv\nvJArr7wyjzzySJKkY8eO+dznPpdTTz01SXLiiScmee3LzyuVSjZs2JCGhoZ89atfzd57773Ltml3\n98bnoA0bNqS+vj6XXXZZ9dN3t/ZaiW33m9/8JmeddVZ+/OMfZ//990+S/OEPf8gnP/nJ/OM//mM+\n/OEPZ/r06bntttva7CNf+tKX0rNnzyTJWWedld/97nf52c9+Vv0OzSSZNWtWvvKVr+T73/9++vfv\nv0u2b7tU2Krf/OY3lVGjRlU+/elPVx566KFtvq6hoaGycuXK6uVFixZVjjnmmMrzzz9fvf6ZZ555\n+zdgN/ehD32oMnz48MrLL79cXfbqq69WPvnJT1YaGhqqy4477rjKvHnzqpfnzp1bGTBgQKWlpaXy\n5JNPVg499NCt3tdFF11UueGGG3bsBrwLTJkypfLpT3+6smrVqkqlUqls2LCh8n/+z/+p/r5fdNFF\nlRNOOKFy6623trndxIkTKyeccEJl5syZu2La7wobPw+xY23r89M3vvGNymmnnVZ59tlnK5VKpbJ2\n7drKpZdeWjnjjDMqlUqlcscdd1T++q//ujq+ubm5MmHChMrJJ59cWbdu3U7amt3btddeWzn11FOr\nv++tra2Va665pvKJT3yism7dusp5551X+bu/+7vq+Mcff7wyYMCA6v/dJ5xwQmXx4sXV6zds2FD5\n+te/Xhk/fvzO3ZDCbPwcNGXKlMrYsWPf9PqNXyvx1txwww2VMWPGVC+fe+65lW9961uVSuW1n/3m\n9pGmpqbq88yZZ55ZOeGEEyr3339/m/WOHTu2csIJJ1QeeOCBnbQlO4ZT17bBzJkz84lPfCInn3xy\nZs6cuc3XVSqVVN7woXZHHXVU6uvr89BDD1WvZ9scc8wx+b//9/9WL8+fPz+HH3549fLzzz+fVatW\n5YgjjqguGzZsWO68887U1tbu1Lm+27z00kuZMWNGrrnmmupfPWtqavLpT3869913X/baa68kyfHH\nH5+77rqrersNGzZk/vz56du37y6Z97vFxs9D7Hhbe3568cUXc8stt+Tqq6/O+973viSvHTX46le/\nmi984QubXWe3bt1y+eWXp1u3bpk1a9bbuwEFWL16daZPn56/+7u/y/vf//4kSYcOHXL++eenc+fO\nmTVrVh577LH06dOnepuDDz44c+bMafP/xhv3lZqamjQ2Nua///u/d96GFGjj56CBAwdmxYoVb3r9\nxq+VeGu++MUv5oUXXsjMmTNz33335fHHH88555yTF198MTNmzNjsPlJbW9vmeeb444/PnXfeWb28\nevXq/P73v8+f/Mmf7PTtaS+hsxUbNmzI3Llzc/LJJ+cv/uIvct9992X9+vVbve7NrF+/Pp07d94Z\nUy/KSSed1OZF8l133ZWTTjqperlnz545/PDDc9ZZZ+W2227Lk08+mSTVFxW8fR566KF84AMf2OyX\nANfV1VX/fcQRR+TJJ5/MqlWrkiS/+MUvcvjhh9sf2O1t7fnp4Ycfzn777ZeDDjqoze06d+6cxsbG\nLa67sbExCxcu3JHTLdJDDz2U/fffP/X19Ztc19jYmAceeCAf/ehHM2HChNx00035r//6r1Qqlerp\nOpvT0tKS22+/3R9jdqBXXnkl//qv/1o9TfDNeK20/fbYY49cddVVmTJlSq644opcddVV6dSpUx5+\n+OF84AMf2Ow+csIJJ+SBBx5oc3n+/Pl59dVXkyQ/+clP8rGPfWynbcOOJHS24mc/+1kOP/zw9OjR\nI927d0///v1z3333bfW6zZk3b15WrVqVo446amdNvwg1NTUZMGBAHnvssbz44otZt25dHnrooQwc\nOLDNX4FuvvnmfPzjH8/3v//9DB06NJ/4xCdy9913V69fv359RowYkREjRuSkk07KiBEjcv311++K\nTSrK6tWr27xYaG5urv58Bw8eXH0vSIcOHTJs2LDMmTMnyWsvBkeMGLFL5vxuM3r06Orv/ogRI/LV\nr351V0+pGNvy/PTSSy9ln3322a71d+vWLX/84x935JSLtPHz0Bvts88+aW5uzgUXXJDzzjsv8+fP\nz2mnnZbjjz8+f//3f99m7Pnnn58RI0Zk2LBhGTBgQPbdd99ccsklO2MTijZ69OicdNJJOe644/LI\nI49k5MiRbzrWa6X26927d/7kT/4kHTt2zIc//OEkrz0PbWkfeemll6qXu3btmqOOOir/8R//kSSZ\nM2dOTjrppN3y7AAfRrAVM2fOzM9+9rMcc8wxqVQqaW1tzZo1azJ06NDccccdb3rd60aPHl19A94B\nBxyQ733ve3nPe96zC7do91RTU5OhQ4dmzpw52XvvvfORj3yk+ubq13Xr1i3jxo3LuHHj8vzzz+f2\n22/Pl7/85cyaNSu1tbXp2LFj9UU2O07Pnj3z7LPPVi937969+sEcl112WVpaWqrXNTU15fLLL89n\nP/vZLFy4MBMmTMg999yz0+f8bvP973+/eqoCO97Wnp/22muvrFy5crvWvWLFii0edeA1++67b5vn\noTdatWpV9ttvvyTJqaeemlNPPTUtLS356U9/mq9//evZZ599ctpppyVJpkyZkr59++bVV1/N8OHD\nc8IJJ6RLly47bTtK9cbnoF/+8pc544wz8uMf/7j6B4CNXytNnTrVa6V2uO2229KlS5f86Z/+ab73\nve9l7Nix2Wuvvba4j2z8gRtNTU258847c+SRR2bVqlVpaGjYGVPf4YTOFqxevToPPvhgHnzwwep/\nWq2trRk8eHCef/75N73uhRdeqL4vwQuMHWfEiBH59re/nZ49e+Yzn/lMklQ/EWTlypVZsWJF9S9A\nPXv2zBe/+MX827/9W37729/m0EMP3WXzLt2RRx6Z5557Lo8++ugmT4Qb//Xnwx/+cFavXp077rgj\n/fv3T6dOnXbmVN+1dse/wu1utvT89Po+8l//9V/58z//8+pt1q9fn+985zs555xzNrvODRs25J57\n7sm4cePe/g3YzTU0NOS5557Lf//3f+dDH/pQm+t++tOf5qyzzsq8efMyePDgJK+9R2r48OF5+OGH\n85vf/KY69vV9pVOnThk3blyuvvrq3HHHHTtvQwr1xuego48+OgcccEAWLVqUYcOGJfFaaUd65pln\n8q1vfSv//M//nE6dOuVTn/pUhg0blr59++all156031k9OjRbZYNHjw4EydOzOzZs6uP0+7IqWtb\nMHv27AwcOLDNX+b22GOPHH/88Zk9e3YGDRq0yXXHHXdcm3O1vcBov9d/hn379s3KlSvz2GOP5Zhj\njmlz3dNPP51zzjmn+rGhSbJkyZI888wz1TcFeyzeHl27ds3ZZ5+dCy64IMuXL0/y2s/6rrvuyty5\nc3PggQe2Gd/U1JTrr7/eaWsUYVuen7p3754xY8bkwgsvrO4ja9euzWWXXZZHH320+oEpb3yOWrNm\nTf72b/82e+65Z5v3+7B53bt3z+c+97lceOGF1fdotra2ZsqUKdmwYUOGDBmSiy66qE20rFq1Kj//\n+c+rj9fGTj755Lzyyiv58Y9/vFO24d3id7/7XZYtW5ZDDjmkusz/zzvOpZdems9//vPp1atX9ttv\nv5xzzjm59NJL061bt4wdO/ZN95GN/0/u3LlzjjvuuNx888279XOQIzpb8K//+q+bFG6SDBkyJDfe\neGM+//nPb3Ldxz72sdx4440588wz23z++ObU1NRkyJAhSf7ne11uuummfOQjH9kxG1CIN/4chw4d\nmjVr1mxy3ZFHHpkrrrgiEydOzB//+Mds2LAh++yzT771rW9l//33z4oVK7b6eLD9vvCFL6RHjx45\n99xz88orr2TdunU5+OCD853vfCeDBg3K/fffXx3b1NSUH/zgB37PdxK/92+vbXl+SpJx48alR48e\nOfvss7Nhw4Z06NAhQ4YMycSJE6tjHnrooYwYMSKtra1Zt25dhgwZkn/8x39Mhw7+Jrktzj333HTv\n3r16GtQrr7ySY445JtOnT0+3bt2qn8r2D//wD0leeyF35pln5uMf/3iSTfeVDh065Nxzz81VV12V\nESNGeHP8dqqpqak+JpVKJbW1tfna176WP/3TP61ez45x66235oUXXshf/dVfVZedeeaZufPOO/OD\nH/wgn//851NbW5uzzz67zffoTJs2LR07vpYEb3w8mpqa8v/+3/+rRunu+FjVVGQ0AFCQb3zjG3n5\n5ZfbhCTw7uPPRABAUZqamjJ37tz84Q9/2NVTAXYhoQMAFOXQQw/N5z73uYwcOdLHqcO7mFPXAACA\n4jiiAwAAFEfoAAAAxRE6AABAcYQOAABQHKEDAAAU5/8Dd3YRPURotjIAAAAASUVORK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3246c23850>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from itertools import chain\n",
    "\n",
    "pairs = [\n",
    "    symbols(['AAPL', 'MSFT']),\n",
    "    symbols(['GM', 'F']),\n",
    "    symbols(['MCD', 'QSR']),\n",
    "    symbols(['BP', 'XOM']),\n",
    "]\n",
    "\n",
    "# Flatten the list of pairs into a single list for use as an index.\n",
    "all_pair_stocks = list(chain.from_iterable(pairs))\n",
    "\n",
    "# Initially allocate half of our capital in the AAPL/MSFT pair and half in the GM/F pair.\n",
    "initial_pairs_portfolio = pd.Series({\n",
    "    pairs[0][0]:  0.25,  # AAPL\n",
    "    pairs[0][1]: -0.25,  # MSFT\n",
    "    pairs[1][0]:  0.25,  # GM\n",
    "    pairs[1][1]: -0.25,  # F\n",
    "}).reindex(\n",
    "    all_pair_stocks, \n",
    "    fill_value=0.0,\n",
    ")\n",
    "\n",
    "draw_asset_barplot(initial_pairs_portfolio, 'Initial Pairs Portfolio');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose that after some period of time, our algorithm decides that it wants to exit the `AAPL/MSFT` pair and enter the `MCD/QSR` and `BP/XOM` pairs.  It might calculate a new target portfolio that's equally-weighted between the three new pairs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA0AAAAHvCAYAAAB9tr9QAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzs3Xt8FOW9x/HvksvGlWgItKCYlUtfdFUEIQSCxbJcQi4I\ncjkqClgU++LA4UULgYpyNE2rXAqCQKwokZMSbA1VMQoxXCylRoKUoKQUrRRIUJAgiiaY3Vz3/MHL\nlSVXs0CaPJ/3X5lnnpn9TZKZ2e/OM7MWj8fjEQAAAAAYoE1zFwAAAAAAVwoBCAAAAIAxCEAAAAAA\njEEAAgAAAGAMAhAAAAAAYxCAAAAAABiDAAQAaHHee+899e7dWxUVFc1dyvcya9Ys9enTR3/+858b\n7Hv//fdr+fLlkqTHHntM8+fPv9zlAYARApu7AABA0z3++OPKzMyUxWJRVVWVKisrZbVa5fF4ZLFY\n9OKLL6pfv35XvK7t27fL4XAoIiKixrzjx49rxIgRCg4OlsVikSSFhoaqb9++mjdvXq3LXGzAgAE6\ncODAJak1NzdXDz74oKxWqyTJ4/EoPDxcAwcO1Ny5c9W+ffsmrbe6ulrr16/XlClTJEn//Oc/tW3b\nNm3evFk/+tGPvte6Fi5c2KQaAAA1cQUIAFqw3/72t8rPz9eBAweUkpIii8WiAwcOeNu+b/i5VN+N\nvWLFChUUFNQ532Kx6I033tCBAwd04MABvfnmm7JarXr44YdVWVnp12s3ZRssFov27dvn/d29/PLL\nKioq0uzZs5tcwz/+8Q+lpqZ624qLi2WxWGS325u0TgDApUEAAgADpKWlKTY2Vn369FFsbKxef/11\n77xnnnlG//3f/6158+bptttukyR9+eWXmjx5snr37q0xY8YoJydHDodDx44dkyR9/fXXmjt3ru64\n4w717dtX06ZN06lTpyRJcXFxOnr0qGbMmKEFCxbUWdOFQaVdu3aaP3++CgsLdfjwYUnSP/7xD02e\nPFlRUVG6/fbb9eijj8rtdks6f9XG4XCovLxcVVVVcjgc2rBhgwYPHqznnntOLpdLjzzyiG6//Xb1\n7dtX//Vf/6W9e/fW+zu6sJ5OnTrpl7/8pf7+97+ruLhYknT48GFNmTJF/fv314ABA/Too4/qm2++\n8dbTp08f/fGPf1S/fv2Ul5eniRMn6osvvlDv3r31t7/9TT//+c8lSVFRUcrIyFB1dbV+//vfa8SI\nEbrttts0evRo/eUvf6m1tnnz5ikxMdE7vWPHDo0ZM0Z9+vTR0KFD9fzzz9e7bQCA7xCAAKCVe++9\n97Rs2TItX75c77//vubNm6cFCxbok08+8fbJz89Xv379vMPK5s+fL4/Ho5ycHK1cuVLLly/3DleT\npF/96lcqLy9XVlaWcnJyFB4e7n2DvmXLFknSmjVr9NRTTzW6zm+v/AQGnh+d/Ytf/EK9evXS3r17\n9cYbb+j999/3uaJyYT2StG3bNm3atEkzZszQiy++qMOHD2vr1q3at2+fxowZ492m71tPQECAysvL\n9dBDD+nWW29VTk6OMjMz9dFHH/kMTausrNTRo0e1e/du9evXT0lJSWrfvr0OHDign/70p1q7dq0k\nad++fbr33nuVnp6ujRs3KiUlRXl5ebr//vs1a9Ysn79LbT788EP94he/0MyZM7Vv3z4tW7ZMqamp\nyszMbPS2AYDJCEAA0MoNGDBAubm5uuWWWyRJw4cPV1BQkA4dOuTt06ZNG917772SpKqqKu3evVsP\nPfSQQkNDdeONN+r+++/39v3888+1a9cuzZ49W6GhobLZbJo7d67y8vJ83rx/n7Bx5swZ/e53v9PN\nN9/svT9my5Yt+uUvfymLxaIOHTpo4MCBOnjwYJ3riI+PV3h4uCTp3LlzCgwMVHBwsNq0aaNJkybp\nL3/5S43QVJcTJ05o9erVcjqduvrqq7Vz506VlZVp1qxZCg4OVqdOnTR16lRlZ2d7l6msrNR9992n\n4ODgetf97e/llVde0aRJk9SjRw8FBARowoQJ6ty5s7Zv317v8q+++qpuv/12DR8+XAEBAerbt6/i\n4+P11ltvNWrbAMB0PAQBAFq5iooKrV69Wtu2bdPZs2fl8XhUUVGh8vJyb59OnTp5fz579qwqKyt1\n/fXXe9t69erl/fn48eOSpDFjxnjbPB6PgoKC9Nlnn/ksVxePx6O77rrLG0iuvfZaRUVF6bnnnvO2\nvfPOO1qzZo2OHTumqqoqVVdXq3///nWu88LXnThxonbu3Kmf/vSn+slPfqIhQ4YoISFBAQEBddYT\nFRXlnW7fvr0GDx6sOXPmSJI+/fRT3XDDDQoKCvL2sdvtKi0t1dmzZ2utoSGffvqpunfv7tN24403\n6sSJE/Uu98knn9R4iILdbtf777/f6NcGAJMRgACglVu1apW2bdum5557TjfddJMkqW/fvj59vh12\nJp1/epkknzf7bdp8N2AgJCREFotF77zzjq655poar1dVVdVgTd8+BKFLly61zv/3v/+tOXPm6JFH\nHtE999wjq9WqJ598UkePHq1znReGm4iICGVnZ2vPnj36y1/+osWLF+vll1/Whg0bar0K9O1DEC7c\n5gtdGBZrW7a2GhpS1zobukpVXy0AgIYxBA4AWrl//OMfGjZsmDf8HDt2TKWlpXX2b9eunSwWi8+V\niAsfOX3DDTfIYrHoo48+8rZVV1d7H4LQWPUNkfvnP/+p4OBgTZ482ft46vqGv13M5XKpoqJCAwcO\n1IIFC/Tyyy8rLy9PH3/8cZPqsdvt+vTTT32+d+jo0aO65pprFBYW1ui6LhQREaEjR474tB07dkw3\n3njj917u6NGjDS4HADiPAAQArVznzp314Ycfyu1268iRI1q2bJl+8IMfqKioqNb+QUFBioyMVFpa\nms6dO6fCwkKfL+689tprFR8fr6VLl+rUqVMqKyvTM888o5/97GeSzl8FCQwMVGFhoc6dO1frazR0\nf1Dnzp1VVlamDz/8UOfOndPq1atVXl6uzz//vFH3Fk2fPl2//vWvde7cOXk8Hr3//vuyWq267rrr\nGly2Nk6nU4GBgUpJSVF5ebk++eQTvfjiixo7dmydy4SEhOjcuXM6ffq0ysrKaswfN26cXnrpJf37\n3/9WRUWF0tLS9MUXXyguLq7eWsaOHavdu3dr586dqqqq0nvvvae33npL48aNa9K2AYBp/A5Aubm5\nGjdunOLi4jR16tRaT6hvv/22xowZo5EjR2rixIneR5xK0rJlyxQXF6eEhATvN14DAC6d6dOnq7q6\nWgMHDtS8efM0bdo03XvvvUpJSdGrr75a6zKLFy9WcXGxBg0apPnz52v69OmSvhsK98QTT6hLly66\n8847dccdd+jQoUM+j2KeMGGCfve73+mRRx6pdf0NDfPq16+f7rvvPk2ePFnx8fGyWq1auHChvvzy\nS2/Qqm99ixYt0ueffy6n06l+/fpp/fr1SklJqXXIXmNcffXVev7555WXl6dBgwZpypQpGjp0qObO\nnVvnMj/5yU90/fXXKyYmptbHW0+dOlUJCQmaNm2abr/9du3YsUPp6en6wQ9+4N2m2n5Pffr00ZNP\nPqnly5erf//+evLJJ5WcnKyhQ4c2adsAwDQWjx/feudyuTRs2DCtW7dODodD6enpevfdd7VmzRpv\n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\n9ekXFBSk5cuXq1u3bpKkyMhIHTlyRJK0detWjR07VoGBgQoKCtLo0aOVnZ3d1JIAAAAAoF5NDkAF\nBQWKiIjwTttsNoWFhen48eM+/cLDwzVo0CDv9K5du9S7d29J0rFjx2S3273z7Ha7jh492tSSAAAA\nAKBegU1d0OVyyWq1+rSFhITUuAJ0odzcXK1fv17r16+XJLndbgUHB/ss73K5mloSAAAAANSrwQC0\nfft2LV26VBaLRZLk8XhksVh03333qayszKev2+2WzWardT07duzQU089pRdeeME7HO6qq65SeXm5\nt4/L5apz+Qvl5eU12AcAAAAALtZgAIqJiVFMTEyN9l27dikrK8s7XVJSouLiYnXp0qVG3927d2vh\nwoVat26dunbt6m3v1q2bCgsLNXDgQElSYWGhunfvXm89kZGRDZUMAAAAALVq8j1A0dHROnnypPbv\n3y9JSktLk9PpVEhIiE8/t9utxx57TCkpKT7hR5Li4+O1ceNGuVwuffPNN8rIyNCdd97Z1JIAAAAA\noF5NvgfIarVqxYoVSk5Oltvtlt1u1+LFiyVJ+fn5WrVqlVJTU/X222/r7Nmzmjt3rqTvhtBt2LBB\nsbGxOnTokMaMGSOLxaJRo0bJ6XRekg0DAAAAgItZPB6Pp7mLAAAAAIAroclD4AAAAACgpSEAAQAA\nADAGAQgAAACAMZr8EAR8Z/z48SotLdVbb73V6HkOh0M33nijAgICVFVVpWuuuUZz5szxPhLc4XBo\n165d6tix4xXZhpbK4XAoNjZWK1eu9GlfsGCBXn31VX300UeSpH/+859aunSpTp8+raqqKrVr107z\n5s1TZGSkTpw4oWHDhnm/n+rbB3X06dNHkZGRWrt2rSwWi06fPq2goCCFhYXJYrHoiSeeUHR09BXf\n5pZo/fr1evXVV1VZWanKykp16dJFs2bN0i233KL58+dr8+bN2r17t6655hrvMvv27dOkSZO0ePFi\njRkzphmrb70uPA5J5//3O3furNTU1GaurOVr7LFJkv7v//5Pr732miorK1VVVaVBgwZpzpw5atu2\nrTZt2qTf/OY3uu6661RRUSGLxaKhQ4fqf/7nfxQaGnqlN6vFWr9+vf785z+rqqpK1dXVGjBggH75\ny1+qXbt2Onv2rJ566ikdPHhQkhQYGKif/exnuvvuuyVJQ4cOlXT+y9o9Ho+qq6vlcDj0xBNPqH37\n9s22TS3dhcef6upq2e12Pf7444qIiKgxv7b3SWi8jz/+WJMnT9brr7+u6667TpL0+eefa/To0Xrx\nxRd188036w9/+INeeeUVn33kF7/4hcLDwyVJkydP1rFjx/TOO+94vxtUkjIzM/XII48oPT1dUVFR\nzbJ9TeKBXz7++GPP+PHjPffee6/ngw8+aPQ8h8PhKSoq8k7n5eV5+vfv7/nyyy+980+dOnX5N6CF\n+/GPf+yJi4vzfPPNN962iooKz+jRoz0Oh8PbNmjQIM+uXbu809nZ2Z4BAwZ43G6359NPP/Xccsst\nDb7W/PnzPc8999yl3QADPP300557773Xc+bMGY/H4/FUV1d7Xn75Ze//+/z58z1DhgzxbNy40We5\n5ORkz5AhQzybNm1qjrKNcPFxCJdOY49Nv/vd7zz33HOP5/Tp0x6Px+NxuVyeBQsWeCZOnOjxeDye\n1157zfPggw96+5eUlHiSkpI8d911l6esrOwKbU3LtmLFCs/dd9/t/V+vqqryLF261DNq1ChPWVmZ\nZ/bs2Z5ly5Z5+x89etQzYMAA73l7yJAhnv3793vnV1dXe3772996EhMTr+yGtDIXH3+efvppz7Rp\n0+qcf/H7JHw/zz33nGfq1Kne6VmzZnmeeeYZj8dz/ndf2z4ycuRI73Fm0qRJniFDhnh2797ts95p\n06Z5hgwZ4tm7d+8V2pJLgyFwftq0aZNGjRqlu+66S5s2bWr0PI/HI88FD+Dr27ev7Ha7PvjgA+98\nNE7//v21bds273ROTo5uvfVW7/SXX36pM2fOqHfv3t622NhYvfnmm7JarVe0VtN8/fXXWr9+vZYu\nXer9pNRisejee+/Vzp071a5dO0nSHXfcoS1btniXq66uVk5Ojvr06dMsdZvi4uMQLq2Gjk1fffWV\nNmzYoCVLlugHP/iBpPNXGZ544gk9/PDDta6zbdu2+vWvf622bdsqMzPz8m5AK1BcXKw//OEPWrZs\nmX74wx9Kktq0aaO5c+cqODhYmZmZOnz4sHr16uVdpmvXrsrKyvI5Z1y4n1gsFjmdTv3rX/+6chvS\nCl18/ImOjtaJEyfqnH/x+yR8Pz//+c919uxZbdq0STt37tTRo0c1Y8YMffXVV1q/fn2t+4jVavU5\nztxxxx168803vdPFxcX65JNPdMMNN1zx7fEXAcgP1dXVys7O1l133aU777xTO3fuVGVlZYPz6lJZ\nWang4OArUXqrEh8f7/PmecuWLYqPj/dOh4eH69Zbb9XkyZP1yiuv6NNPP5Uk7xsOXD4ffPCBrr/+\neu+QhgvZbDbvz71799ann36qM2fOSJLee+893XrrrewPaNEaOjYdOHBAnTp1UpcuXXyWCw4ObvA7\n8ZxOp/bs2XMpy22VPvjgA1133XWy2+015jmdTu3du1c//elPlZSUpBdeeEEffvihPB6Pd9hPbdxu\nt1599VU+oLmEysvL9cYbb3iHG9aF90lNFxAQoEWLFunpp5/Wk08+qUWLFikoKEgHDhzQ9ddfX+s+\nMmTIEO3du9dnOicnRxUVFZKkrVu3avjw4VdsGy4lApAf3nnnHd16660KCwtTaGiooqKitHPnzgbn\n1WbXrl06c+aM+vbte6XKbxUsFosGDBigw4cP66uvvlJZWZk++OADRUdH+3xytG7dOo0YMULp6emK\niYnRqFGjtH37du/8yspKJSQkKCEhQfHx8UpISFBKSkpzbFKrUlxc7PNGoqSkxPv7HTx4sPdekzZt\n2ig2NlZZWVmSzr9RTEhIaJaaTfPAAw94//cTEhL0xBNPNHdJrUJjjk1ff/21OnTo0KT1t23bVufO\nnbuUJbdKFx+DLtShQweVlJRo3rx5mj17tnJycnTPPffojjvu0O9//3ufvnPnzlVCQoJiY2M1YMAA\ndezYUY899tiV2IRW7YEHHlB8fLwGDRqkgwcPaty4cXX25X2S/3r06KEbbrhBgYGBuvnmmyWdPw7V\nt498/fXX3umrr75affv21d/+9jdJUlZWluLj41vkSAIeguCHTZs26Z133lH//v3l8XhUVVWl0tJS\nxcTE6LXXXqtz3rceeOAB781/nTt31tq1a3XVVVc14xa1TBaLRTExMcrKylL79u11++23e2/q/lbb\ntm01c+ZMzZw5U19++aVeffVVzZkzR5mZmbJarQoMDPS++calEx4ertOnT3unQ0NDvQ8Eefzxx+V2\nu73zRo4cqV//+te6//77tWfPHiUlJWnHjh1XvGbTpKene4c94NJq6NjUrl07FRUVNWndJ06cqPcq\nBc7r2LGjzzHoQmfOnFGnTp0kSXfffbfuvvtuud1u/fWvf9Vvf/tbdejQQffcc48k6emnn1afPn1U\nUVGhuLg4DRkyRCEhIVdsO1qrC48/+/bt08SJE/X66697Pxi4+H1Samoq75P88MorrygkJEQ/+tGP\ntHbtWk2bNk3t2rWrdx+5+EEfI0eO1JtvvqnbbrtNZ86ckcPhuBKlX3IEoCYqLi7W3//+d/3973/3\nntCqqqo0ePBgffnll3XOO3v2rPe+B954XDoJCQlauXKlwsPDNWHCBEnyPqWkqKhIJ06c8H5qFB4e\nrp///Od666239O9//1u33HJLs9Xd2t1222364osv9NFHH9U4SF78idHNN9+s4uJivfbaa4qKilJQ\nUNCVLNVYLfGTu5akvmPTt/vHhx9+qJtuusm7TGVlpVavXq0ZM2bUus7q6mrt2LFDM2fOvPwb0MI5\nHA598cUX+te//qUf//jHPvP++te/avLkydq1a5cGDx4s6fw9WHFxcTpw4IA+/vhjb99v95OgoCDN\nnDlTS5Ys0WuvvXblNqSVuvD4069fP3Xu3Fl5eXmKjY2VxPukS+nUqVN65pln9Kc//UlBQUEaO3as\nYmNj1adPH3399dd17iMPPPCAT9vgwYOVnJyszZs3e/9OLRFD4Jpo8+bNio6O9vk0LyAgQHfccYc2\nb96sgQMH1pg3aNAgn/HgvPHw37e/wz59+qioqEiHDx9W//79feZ99tlnmjFjhvcRp5KUn5+vU6dO\neW9I5m9xeVx99dWaPn265s2bp+PHj0s6/7vesmWLsrOzdeONN/r0HzlypFJSUhj+hhavMcem0NBQ\nTZ06Vb/61a+8+4fL5dLjjz+ujz76yPuQlguPT6Wlpfrf//1fXXvttT73E6F2oaGh+tnPfqZf/epX\n3vs/q6qq9PTTT6u6ulrDhg3T/PnzfcLMmTNn9O6773r/Xhe76667VF5ertdff/2KbIMpjh07poKC\nAnXv3t3bxrn50lmwYIEeeughRUREqFOnTpoxY4YWLFigtm3batq0aXXuIxefj4ODgzVo0CCtW7eu\nRR+DuALURG+88UaNVCxJw4YN05o1a/TQQw/VmDd8+HCtWbNGkyZN8nmGem0sFouGDRsm6bvvpXnh\nhRd0++23X5oNaCUu/D3GxMSotLS0xrzbbrtNTz75pJKTk3Xu3DlVV1erQ4cOeuaZZ3TdddfpxIkT\nDf490HQPP/ywwsLCNGvWLJWXl6usrExdu3bV6tWrNXDgQO3evdvbd+TIkXrppZf4P79C+L+/fBpz\nbJKkmTNnKiwsTNOnT1d1dbXatGmjYcOGKTk52dvngw8+UEJCgqqqqlRWVqZhw4bpxRdfVJs2fIbZ\nGLNmzVJoaKh3OFV5ebn69++vP/zhD2rbtq33KXHPP/+8pPNv8CZNmqQRI0ZIqrmftGnTRrNmzdKi\nRYuUkJDATflNZLFYvH8Tj8cjq9Wq3/zmN/rRj37knY9LY+PGjTp79qymTJnibZs0aZLefPNNvfTS\nS3rooYdktVo1ffp0n+8BSktLU2Dg/7dzxzYMhTAABZ15GMUdC7APE/1JWIKaOikiRckEX5HvJkBy\n9QD5nQrf88jMWGt9YvUfZ/V4ymsAoIA5Z5xzfgITqMf1EQBQQmbGdV2x9777KMCNBBAAUEJrLcYY\n0Xu38h0K8wUOAAAowwsQAABQhgACAADKEEAAAEAZAggAAChDAAEAAGW8AKc9kPxntGG6AAAAAElF\nTkSuQmCC\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f3245538110>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "target_pairs_portfolio = pd.Series({\n",
    "    pairs[0][0]:  0.16666,\n",
    "    pairs[0][1]: -0.16666,\n",
    "    pairs[2][0]:  0.16666,\n",
    "    pairs[2][1]: -0.16666,\n",
    "    pairs[3][0]:  0.16666,\n",
    "    pairs[3][1]: -0.16666,\n",
    "}).reindex(\n",
    "    all_pair_stocks, \n",
    "    fill_value=0.0,\n",
    ")\n",
    "\n",
    "draw_asset_barplot(target_pairs_portfolio, 'Target Pairs Portfolio');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we naively run `calculate_target_weights` using an unconstrained `TargetWeights` objective, we'll get back our target.  But if we supply turnover and pairs constraints, we'll move our capital incrementally out of the current pairs and into the new ones:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Objective that minimizes the distance from an already-computed portfolio.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    weights : pd.Series[Asset -> float] or dict[Asset -> float]\n",
      "        Map from asset to target percentage of holdings.\n",
      "\n",
      "    Notes\n",
      "    -----\n",
      "    A target value of 1.0 indicates that 100% of the portfolio's current net\n",
      "    liquidation value should be held in a long position in the corresponding\n",
      "    asset.\n",
      "\n",
      "    A target value of -1.0 indicates that -100% of the portfolio's current net\n",
      "    liquidation value should be held in a short position in the corresponding\n",
      "    asset.\n",
      "\n",
      "    Assets with target values of exactly 0.0 are ignored unless an algorithm\n",
      "    has an existing position in the given asset.\n",
      "\n",
      "    If an algorithm has an existing position in an asset and no target weight\n",
      "    is provided, the target weight is assumed to be zero.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.TargetWeights.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/latex": [
       "\n",
       "\\begin{align*}\n",
       "&\\underset{\\boldsymbol{w}}{\\text{minimize}} && ||\\boldsymbol{w} - \\boldsymbol{t}||_2 \\\\\n",
       "&\\text{where} &&\\boldsymbol{t} = [0.167, -0.167, \\ldots, -0.167]\n",
       "\\end{align*}\n"
      ],
      "text/plain": [
       "<qexec.optimize.latex.LatexRepr at 0x7f3245078790>"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "opt.TargetWeights(target_pairs_portfolio).math"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    A constraint representing a pair of inverse-weighted stocks.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    long : Asset\n",
      "        The asset to long.\n",
      "    short : Asset\n",
      "        The asset to short.\n",
      "    hedge_ratio : float, optional\n",
      "        The ratio between the respective absolute values of the long and short\n",
      "        weights. Required to be greater than 0. Default is 1.0, signifying\n",
      "        equal weighting.\n",
      "    tolerance : float, optional\n",
      "        The amount by which the hedge ratio of the calculated weights is\n",
      "        allowed to differ from the given hedge ratio, in either direction.\n",
      "        Required to be greater than or equal to 0. Default is 0.0.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.Pair.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    A constraint enforcing a maximum turnover for the optimal portfolio.\n",
      "\n",
      "    Turnover is computed as the sum of the magnitude of the difference in\n",
      "    weights for each asset in the portfolio, i.e., as::\n",
      "\n",
      "        sum(abs(new_weights - old_weights))\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    max : float\n",
      "        The maximum allowable turnover across the whole portfolio.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print opt.MaxTurnover.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def migrate_pairs_constrain_turnover(current_pf, target_pf, max_turnover):\n",
    "    \"\"\"Calculate a new target portfolio while respecting turnover and pair constraints.\"\"\"\n",
    "    objective = opt.TargetWeights(target_pf)\n",
    "    \n",
    "    constraints = [opt.Pair(long, short) for long, short in pairs]\n",
    "    constraints.append(opt.MaxTurnover(max_turnover))\n",
    "    \n",
    "    return opt.calculate_optimal_portfolio(\n",
    "        objective=objective,\n",
    "        constraints=constraints,\n",
    "        current_portfolio=current_pf,\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Try changing with the `MAX_TURNOVER` parameter here to see how it affects\n",
    "# the resulting portfolio!\n",
    "MAX_TURNOVER = 0.75\n",
    "\n",
    "migrated_pairs_portfolio = migrate_pairs_constrain_turnover(\n",
    "    current_pf=initial_pairs_portfolio,\n",
    "    target_pf=target_pairs_portfolio,\n",
    "    max_turnover=MAX_TURNOVER,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAzoAAAHvCAYAAACc3aoBAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAIABJREFUeJzs3XtcVGXix/HviAKOYoiVdxQpJFMRUUEzM02l1LywZemm\nlbVpF7fE+qVlpqXSekvXthuZ4iW3TdO2vCxaq2uhAqZol0XxfkNNy+Eq4Pz+8MWsE4jIjI4+ft6v\n1762Oec5z3nOnHmc+fI85xyL3W63CwAAAAAMUsnTDQAAAAAAdyPoAAAAADAOQQcAAACAcQg6AAAA\nAIxD0AEAAABgHIIOAAAAAOMQdADgEr377rsaOHDgZan7kUce0V/+8pfLUnd5nThxQjExMQoPD9eu\nXbsuWj40NFTr1q2TJEVHR+vvf//75W4iAAAXRdABYLSff/5Zzz//vDp06KBWrVqpS5cumjBhgo4f\nP35J9cybN0+FhYWSpOHDh2vRokWXo7llmj17tm677TaFhYUpLCxMrVq1Uo8ePTR79mwVFBRUuN5D\nhw5p5cqVjtcrVqzQ8ePHtXHjRt1yyy2XVNeqVas0YMCACrelWEpKilq2bOk41rCwMLVs2VKhoaE6\ncuSINm/erNDQUKd1YWFhWrFihSRp69at6tGjh9q1a6e//vWvTnVnZWWpa9eu2r17d5ltCA0NVZcu\nXUpd98EHHyg0NFTLli1z+VjPt3z5csexFB9v8+bNHcvee+89t+4PAExW2dMNAIDLJSkpSU8//bSe\neuopvfbaawoICNCBAwc0a9YsxcTE6B//+Idq16590XpOnjypuLg4PfDAA6pc2bP/bN5+++367LPP\nHK9//PFHPfvssyoqKtKf//znS6rLbrfLYrFo9erV2rp1q+69915J0unTp3XzzTfLx8fHrW2/FG3a\ntFFaWprTsr///e9avny56tatqwMHDshisWjbtm2lbh8XF6eRI0eqQ4cOuv/++9WrVy8FBQVJkqZN\nm6Z+/fqpSZMmF23HmTNntHHjRkVFRTkt/+c//6kbb7yxgkd3YX369FGfPn0kSTk5OWrdurXmzp2r\nNm3auH1fnlD8mQOAK4ERHQBGstvteu211/Tggw9q2LBhCggIkCQ1bNhQU6ZMUZ06dRQXFydJ2rRp\nk2677TatW7dO3bt3V6tWrfTUU08pKytLmZmZ6tSpkySpffv2+uyzzzR79mzFxMRIkjZv3qzw8HB9\n88036tq1q8LDwxUXF6f09HT169dP4eHheuaZZxyjQWfOnNFrr72mO++8UxEREXrwwQe1devWCh9n\ns2bN9MgjjygxMdGx7Ouvv3bs++6779bf/vY3x7rZs2friSee0OjRo9WqVSu99957mjp1qtauXauw\nsDBNnz5d7777rn744QeFhYUpPT1dNptNo0ePVqdOnRQeHq7HHnvsglPaunTpooULFzrOwXvvvace\nPXqoVatW6t27t9asWeMoeylTAE+ePKmZM2dq3Lhx5Sr/448/qnPnzvLz81NYWJh++uknSdL333+v\n5ORkPfXUU+Wq56677tLSpUtL1J2Tk1MiKM2YMUNdunRReHi4evfurX//+9+SpF9++UWRkZH6+uuv\nHWVfffVVPf744+Vqg91ud3pdPJqVm5vrWDZ69GhH0P3888917733aubMmQoPD9eBAwc0evRovfHG\nG3rrrbcUGRmpDh06aN68eY7tf3+OH330UWVkZEiSHnzwQc2aNavEsT700EOSpKNHj+rpp59W+/bt\n1bZtW40cOVK//fabo60tW7bU3//+d7Vp00abNm0q1zEDgDsQdAAY6YcfftDBgwf1yCOPlLr+kUce\n0TfffKOCggJZLBbZ7XYtXbpUS5Ys0Zo1a3T06FFNnTpVtWvX1pw5cySdC0R/+MMfJMnpr9J5eXn6\n9ttvtWLFCk2ePFlz587VtGnT9NFHH2np0qVav369vvnmG0lSfHy8Nm3apOXLlys5OVnt2rW75JGY\n3yssLJSXl5ckKT09Xc8995yGDx+ulJQUzZgxQ/PmzXP6sf7jjz+qRYsW2rZtm4YNG6Y+ffronnvu\n0bZt2zRy5EgNHz5ct99+u7Zt26aQkBC98sorOnTokJYtW6akpCTVq1dPw4YNK/ED/PcWLVqkRYsW\naebMmUpNTdXgwYP1/PPPa+/evZIubQrgO++8oy5duqhp06aOZXa7XS+++KLuuOMOdezY0WlaV6VK\n//t6O3v2rCwWiwoLCzVu3DiNGDFCzz33nB544AG9//77Ze73vvvuU2JionJychzLli9f7hj9On/Z\n4sWLNW/ePH3//fd66KGH9MILLygrK0u1atXSyy+/rEmTJunMmTPavn27Vq5cqTfeeKNcx16ai42K\nnDx5UmfPnlVqaqoaNmwoSVq5cqWaNm2q7777Ts8++6ymTJniCCS/P8f169d3nON7773XKaBKUmJi\nonr16iVJGjZsmGrXrq1vvvlGiYmJys7O1oQJExxlz549q/T0dH377bclRsYA4HIi6AAw0v79+1Wl\nShU1aNCg1PW33HKL8vPzlZmZKencD8ehQ4fKz89PN954owYNGqS1a9c6bVPWD/uHH35YPj4+jms6\nunTpooCAAAUFBalx48aOH/fDhg3T0qVLFRAQoEqVKunee+/VsWPHdOLEiUs+xrNnz2r79u365JNP\n1Lt3b0nSkiVLFBkZqe7du8vLy0utWrXSfffd57h2pfg4yjuScvr0aSUmJuqFF15QQECAfH19FRsb\nq4MHD5aYWvZ7n332mQYNGqTQ0FB5eXnpgQceUKNGjfSvf/3rko4zMzNTS5cu1bBhwxzLqlevrtat\nW6t3795av369I1guXrxYktSiRQslJibql19+0datW9WiRQt99NFHCgsL06ZNm9SqVSstXrxYX375\npX7++edS92uxWBQUFKSmTZtq1apVkqSioiJ99dVX6tOnj9Pn4f7779fatWsdoaJnz57Kzc11jIr0\n69dPjRo10gcffKCJEydqxIgRql+//iW9D5fCZrPpySefdAp8derUUd++feXl5aXo6GgVFhZq3759\nFzzHBw4cUFpamqKjo7Vz504dOHBAkrRr1y7t27dP0dHRSktL086dOzVq1Cj5+vrK399fI0aM0KpV\nq5SXl+d4zwYMGODRqZAArk9cowPAWHa7/aLXBJy/rnHjxo7/rlevnk6ePHnRUYtiderUkSR5e3tL\nkm6++WbHOm9vb+Xn50uSjh8/rokTJyo5OVnZ2dmO+s+cOVOu/RRPKZPOjVrUq1dPAwcO1NChQyVJ\nBw4cUHBwsNM2jRo10saNG0u0tTwOHTokSU51BgQEqFq1ajp06JCjLaUprS2BgYGOOstrwYIF6tSp\nk1NobdasmdNoUGRkpAYMGKBly5bpoYce0ksvvaSXXnpJb775pp588knZ7XZ9+umnWrZsmYYMGaK4\nuDh5eXnpjjvuUGpqqkJDQ0vst/jc3H///Vq6dKn69++vDRs26Oabb9att97qVDY7O1uTJk3S+vXr\nZbPZHJ+788/rhAkT1KtXLzVp0kSDBw++pPfgUlWvXl3Vq1d3Wnb+++fr6ytJys/PL9c5DgsL09q1\na/Xoo48qMTFRbdu21Y033qjNmzerqKhIHTp0cGxbfOzHjh1zLKtXr95lOU4AKAtBB4CRmjRp4viL\n9fkBptju3btVtWpV1alTx/FDr6ioyLG++EdueS+cPv8v56W9LvbCCy+oSpUqWrZsmWrXrq2ff/5Z\n/fr1K9c+pJI3I/i9CwWm84+jeJpbeZQ3gFW0LeWxcuVKPf/88xctV79+fcfIVYsWLZzuJPf4448r\nNjZWfn5+stlsslqtkqSqVavKZrOVWW/Pnj311ltv6eDBg/riiy8cNws43/jx4/Xzzz9r4cKFatSo\nkbKyskrcQCAzM1NeXl46fvy4srOzSwQRV5z/2ZVKP8cXet/Lc46jo6O1Zs0aR9ApHhH08fGRr6/v\nBa8zO3r06AXbAwCXG1PXABgpNDRUQUFBThdcn2/hwoWKjo52+gFWPDVHOjeScdNNN7m9Xdu3b9eA\nAQMcd3vbsWOHW+sPDAwscdvk3bt3KzAwsEL1NWzYUHa73TEFSzr3gz07O7vUAPn7tpy/XXFbGjVq\nVO79//zzzzp06JDjhhDFVq1aVeLcZmRkOKaOnW/ZsmWqXLmy7rvvPknnRjtOnz4tSfr1119VrVq1\nMttwww036K677tIXX3yh9evXO6YJnm/79u3q3bu349i2b9/utL6goEBjx47VmDFj1Lp1a7311lsX\nOfILK54Cdv7NCPbv31/h+so6x8XHc++992rr1q3asWOHdu7cqe7du0s6N1qYn5/vtP+8vDydPHmy\nwu0BAHch6AAw1oQJE7Rs2TJNnjxZv/zyiyTp4MGDeu6555SZmalRo0Y5ytrtds2dO1c2m03Hjh3T\nJ598onvuuUfS/6b57N692+nHZUXUr19f27ZtU2FhoZKSkrR69WpJclwr5Kq+fftq06ZNWrNmjYqK\nipSSkqKvvvrKcZe40vj4+OjIkSOy2WwlRgYCAgJ01113aebMmTp16pSysrI0ZcoUNW3aVM2aNSuz\nLf369dOiRYuUnp6ugoICzZ8/X8eOHStxIX9ZfvzxR/n5+alGjRpOy6tUqaJp06Zp3bp1KioqUlJS\nkpYtW6Y//vGPTuVOnTqlWbNmafz48Y5lYWFhWr16tWw2mzZs2KDw8PCLtqNv376aN2+ewsPDHXfw\nO1/9+vW1Y8cOFRQU6IcfftCiRYvk7e3tOK/vvvuu/P391b9/f40ePVorV67U5s2by/0+nK9Bgwby\n8vLS6tWrHdcMuRJ0yjrHt99+uySpdu3aatGiheLi4nTHHXc4zsctt9yiNm3a6M0339TJkyeVlZWl\nCRMmuHyDDQBwB5eDTlJSkvr376/o6GgNHTq01C/r1atXq2/fvrrvvvs0aNAg7dy509XdAsBFtWnT\nRosXL9aRI0fUq1cvtWrVSkOGDFGdOnX02WefOf1gtVgs6t69u2JiYtStWzfVrVtXI0eOlCTddttt\nCg8P18MPP6wFCxZcdL+/nyJ0/utx48bp66+/Vrt27fTxxx87fjgOHTpU6enpLj9jpGXLlpo8ebJm\nzZqltm3bavz48Ro7dqy6det2wW169eqlAwcO6O6773ZMNTpfXFycatasqd69e6tHjx4qKChQfHx8\nqcd3/n8/9thj6tOnj55++ml16NBBK1euVEJCguMaofLcXvrEiROlPq+ma9euGjt2rCZPnqyIiAjH\naMnvj/Mvf/mLBg8erLp16zqWDR8+XJs2bVLXrl3Vu3dvNW/evNR9n38snTp1UuXKldW3b99S17/4\n4ovas2eP2rVrp4kTJyo2NlZ9+/bV2LFjtXDhQn388cd6/fXXJZ0LDc8++6zGjh170WljpX0eatWq\npVGjRmn27NmKiorS999/X+p0uos5v+7JkyeXeY6lc6M6qampjrutFZs6daoqV66srl276p577lFW\nVpamTZt2ye0BAHez2Mt7pW0pcnNz1bVrV82ZM0ehoaGaP3++vv32W6dbfB45ckQxMTFaunSp6tSp\no4SEBP3zn//UP/7xD7ccAAC4avPmzRoyZIi2bNmiqlWrero5AADADVwa0dm4caMCAwMdd6uJiYnR\nhg0bnJ43ULlyZU2bNs3xF7z27ds7brMKAAAAAJeDS0Fn7969Thd+Wq1W+fv7O80Vvummm9S+fXtJ\n5x5qt3TpUse8dwAAAAC4HFwKOrm5uSUeAObr6+s0olMsISFBd9xxh5KTk/XCCy+4slsAcKt27drp\np59+YtoaAAAGcek5Olar1fEQvGJ5eXmO5xOcb/DgwRo8eLC++uorPfTQQ1q1apXjwXqlSU1NdaVp\nAAAAAK4DERERpS53KegEBQU5Hs4mSTabTadPn3Z6tkJGRoZOnDihyMhISecevDZhwgTt3r271CdR\nl6fRAAAAAFDW4IhLU9eioqJ0+PBhbdmyRZI0d+5cde7c2fHMCencMwxGjRqlY8eOSZJSUlJUVFRU\n6kPdAAAAAMAdXBrR8fHx0YwZMzR+/Hjl5eUpMDBQcXFxSktL06xZsxQfH682bdpo+PDheuyxx2S3\n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\nHQAAAADGIegAAAAAMA5BBwAAAIBxCDoAAAAAjEPQAQAAAGAcgg4AAAAA4xB0AAAAABiHoAMAAADA\nOAQdAAAAAMYh6AAAAAAwDkEHAAAAgHEIOgAAAACMQ9ABAAAAYByCDgAAAADjEHQAAAAAGIegAwAA\nAMA4BB0AAAAAxiHoAAAAADAOQQcAAACAcQg6AAAAAIxD0AEAAABgHIIOAAAAAOMQdAAAAAAYp7Kn\nGwC4Ivu4zSPbAgAA4OpG0ME1q6rfTRp913MKCgqqcB3BwcFubBEAAACuFgQdXLMslSopKChIISEh\nnm4KAAAArjJcowMAAADAOAQdAAAAAMYh6AAAAAAwDkEHAAAAgHEIOgAAAACMw13X4FE5vx3zyLbA\n1Ya+AACAexF04DHBwcGaP3mgy3UA1zr6AgAA7kfQgcd4eXnxDBxA9AUAAC4HrtEBAAAAYByCDgAA\nAADjEHQAAAAAGIegAwAAAMA4BB0AAAAAxiHoAAAAADAOQQcAAACAcQg6AAAAAIxD0AEAAABgHIIO\nAAAAAOMQdAAAAAAYh6ADAAAAwDgEHQAAAADGIegAAAAAMA5BBwAAAIBxCDr4//buPSiqso8D+HeR\nWwoGiAleUMvJTYYUTS4KASIuLCmmg1oClpdhJIbygjGSIGZ5QSZNS/OWYFZjAiIXMZ1BksxAHXQs\nL5Q6Jim4goAil9193j8Yz8siAi8ivKzfz197zvOcs8+zZ59nn9/Z55xDRERERKR3GOgQEREREZHe\nYaBDRERERER6h4EOERERERHpHQY6RERERESkdxjoEBERERGR3mGgQ0REREREeoeBDhERERER6R0G\nOkREREREpHcY6BARERERkd5hoENERERERHqHgQ4REREREekdBjpERERERKR3GOgQEREREZHeYaBD\nRERERER656kCnd9++w3Tpk2Dr68v5s2bh5KSkmbzHTlyBFOnToVSqcTs2bNRVFT0NG9LRERERETU\nonYHOg8fPsSSJUvw+eefIzs7G56enoiNjX0s361btxAXF4dt27YhKysLCoUCy5cvf6pCExERERER\ntaTdgc6pU6dgZ2cHuVwOAJg+fTry8vJQXV2tk8/Q0BAJCQmwsbEBALi6uuL69evtLzEREREREVEr\n2h3oXL9+HYMGDZKWe/bsCQsLC9y4cUMnX9++feHq6goAUKvVSElJwcSJE9v7tkRERERERK16qqlr\n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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f326b069410>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "before_and_after_frame = pd.DataFrame(\n",
    "    {\n",
    "        'Initial Weight': initial_pairs_portfolio,\n",
    "        'Migrated Weight': migrated_pairs_portfolio,\n",
    "        'Target Weight': target_pairs_portfolio,\n",
    "    },\n",
    "    # Explicitly set a column order so that the plot below is\n",
    "    # created in the order we want.\n",
    "    columns=['Initial Weight', 'Migrated Weight', 'Target Weight']\n",
    ")\n",
    "\n",
    "ax = draw_asset_barplot(\n",
    "    before_and_after_frame,\n",
    "    # The fancy brace syntax here is a format specification.\n",
    "    # See https://docs.python.org/2/library/string.html#formatspec for more info.\n",
    "    'Optimal Portfolio: {0:.0f}% Max Turnover '.format(MAX_TURNOVER * 100),\n",
    ");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the optimizer can't reach its target portfolio without violating the `MaxTurnover` constraint, it attempts to equalize the size of the difference between each stock's output weight and it's target weight."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total Turnover: 0.750000\n",
      "\n",
      "Absolute Difference from Target Weight:\n",
      "\n",
      "Equity(24 [AAPL])      0.072915\n",
      "Equity(5061 [MSFT])    0.072915\n",
      "Equity(40430 [GM])     0.072915\n",
      "Equity(2673 [F])       0.072915\n",
      "Equity(4707 [MCD])     0.072915\n",
      "Equity(48215 [QSR])    0.072915\n",
      "Equity(19675 [BP])     0.072915\n",
      "Equity(8347 [XOM])     0.072915\n",
      "dtype: float64\n"
     ]
    }
   ],
   "source": [
    "print \"Total Turnover: %f\\n\" % (migrated_pairs_portfolio - initial_pairs_portfolio).abs().sum()\n",
    "print \"Absolute Difference from Target Weight:\\n\"\n",
    "print (migrated_pairs_portfolio - target_pairs_portfolio).abs()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Debugging and Diagnostics\n",
    "\n",
    "One issue users may encounter when using the Optimize API is that it’s possible to accidentally ask the optimizer to solve problems for which no solution exists. This can happen, for example, if we provide the optimizer with two mutually-exclusive constraints.\n",
    "\n",
    "If the optimizer determines that no portfolio can satisfy all the constraints we've provided, it raises an `InfeasibleConstraints` error. Debugging `InfeasibleConstraints` can be tricky: since different portfolios might violate different constraints, there isn't necessarily a single constraint we can point to as being the source of infeasibility.\n",
    "\n",
    "One observation that can help us when we encounter infeasible constraints is to note that there are certain \"special\" portfolios that we might have expected to pass our constraints. We can often figure out the problem with our optimization by examining the constraints that were violated by these special portfolios.\n",
    "\n",
    "When an `InfeasibleConstraints` error is raised, the optimizer examines a small number of these portfolios and produces an error message detailing the constraints that were violated by each tested portfolio. The portfolios current exampled by the optimizer for diagnostics are:\n",
    "\n",
    "1. The current portfolio.\n",
    "2. An empty portfolio.\n",
    "3. The target portfolio (only applies when using `TargetWeights`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example:\n",
    "\n",
    "Suppose we have a portfolio that currently has long and short positions worth 10% of our portfolio value in `AAPL` and `MSFT`, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "AAPL, MSFT = symbols(['AAPL', 'MSFT'])\n",
    "current_weights = pd.Series({AAPL: 0.1, MSFT: -0.1})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use `TargetWeights` as our objective to try to close the `MSFT` position."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "objective = opt.TargetWeights({AAPL: 0.1, MSFT: 0.0})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We also define three mutually-exclusive constraints:\n",
    "\n",
    "- Our portfolio must be dollar-neutral (i.e., it must have the same amount invested long and short). Our target portfolio violates this constraint.\n",
    "- Fixed weight in `AAPL`. This simulates what might happen if `AAPL` were subject to a trading halt during the day. An empty portfolio would violate this constraint.\n",
    "- Cannot short `MSFT`. The current portfolio violates this constraint."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "impossible_constraints = [\n",
    "    opt.DollarNeutral(tolerance=0.01), \n",
    "    opt.FixedWeight(AAPL, 0.1),\n",
    "    opt.LongOnly(MSFT),\n",
    "]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "ename": "InfeasibleConstraints",
     "evalue": "The attempted optimization failed because no portfolio could be found that\nsatisfied all required constraints.\n\nThe following special portfolios were spot checked and found to be in violation\nof at least one constraint:\n\nTarget Portfolio (as provided to TargetWeights):\n\n   Would violate DollarNeutral() because:\n      Net exposure (0.1) would be greater than max net exposure (0.01).\n\nCurrent Portfolio (at the time of the optimization):\n\n   Would violate FixedWeight(Equity(24 [AAPL])) because:\n      New weight (0.0) would not equal required weight (0.1).\n\nEmpty Portfolio (no positions):\n\n   Would violate FixedWeight(Equity(24 [AAPL])) because:\n      New weight (0.0) would not equal required weight (0.1).",
     "output_type": "error",
     "traceback": [
      "InfeasibleConstraints:",
      "",
      "The attempted optimization failed because no portfolio could be found that\nsatisfied all required constraints.\n\nThe following special portfolios were spot checked and found to be in violation\nof at least one constraint:\n\nTarget Portfolio (as provided to TargetWeights):\n\n   Would violate DollarNeutral() because:\n      Net exposure (0.1) would be greater than max net exposure (0.01).\n\nCurrent Portfolio (at the time of the optimization):\n\n   Would violate FixedWeight(Equity(24 [AAPL])) because:\n      New weight (0.0) would not equal required weight (0.1).\n\nEmpty Portfolio (no positions):\n\n   Would violate FixedWeight(Equity(24 [AAPL])) because:\n      New weight (0.0) would not equal required weight (0.1)."
     ]
    }
   ],
   "source": [
    "opt.calculate_optimal_portfolio(objective, impossible_constraints)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Occasionally it can useful to interrogate the results of an optimize error programatically.  The `run_optimization` entrypoint makes this possible.\n",
    "\n",
    "`run_optimization` performs the same calculation as `calculate_optimal_portfolio`, but it returns an `OptimizationResult` which contains additional information besides the computed portfolio."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success: OptimizationResult(success=True, status='optimal')\n",
      "Failure: OptimizationResult(success=False, status='infeasible')\n"
     ]
    }
   ],
   "source": [
    "# Run an optimization with no constraints to get a successful result.\n",
    "success_result = opt.run_optimization(objective, [])\n",
    "print \"Success:\", success_result\n",
    "\n",
    "# Re-run the impossible optimization to see a failed result.\n",
    "fail_result = opt.run_optimization(objective, impossible_constraints)\n",
    "print \"Failure:\", fail_result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When an optimization succeeds, the result's `success` attribute is set to `True`, and the new optimal portfolio is stored as `result.new_weights`.  If the result failed, `success` is `False`, and `result.new_weights` is `None`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success: True\n",
      "New Portfolio: Equity(24 [AAPL])    0.1\n",
      "dtype: float64\n"
     ]
    }
   ],
   "source": [
    "print \"Success:\", success_result.success\n",
    "print \"New Portfolio:\", success_result.new_weights"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success: False\n",
      "New Portfolio: None\n"
     ]
    }
   ],
   "source": [
    "print \"Success:\", fail_result.success\n",
    "print \"New Portfolio:\", fail_result.new_weights"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result object also has a `print_diagnostics` method, which can be used to print the same debugging information displayed by `InfeasibleConstraints`. This can be useful for debugging cases where an optimization is **succeeding**, but not producing the results expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Target Portfolio (as provided to TargetWeights):\n",
      "  All Constraints Satisfied\n"
     ]
    }
   ],
   "source": [
    "success_result.print_diagnostics()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Target Portfolio (as provided to TargetWeights):\n",
      "\n",
      "   Would violate DollarNeutral() because:\n",
      "      Net exposure (0.1) would be greater than max net exposure (0.01).\n",
      "\n",
      "Current Portfolio (at the time of the optimization):\n",
      "\n",
      "   Would violate FixedWeight(Equity(24 [AAPL])) because:\n",
      "      New weight (0.0) would not equal required weight (0.1).\n",
      "\n",
      "Empty Portfolio (no positions):\n",
      "\n",
      "   Would violate FixedWeight(Equity(24 [AAPL])) because:\n",
      "      New weight (0.0) would not equal required weight (0.1).\n"
     ]
    }
   ],
   "source": [
    "fail_result.print_diagnostics()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Review"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- The **Optimize API** is a suite of tools for solving portfolio optimization problems on Quantopian. It provides a high-level, declarative, finance-oriented interface to Python's excellent ecosystem of numerical optimization libraries.\n",
    "\n",
    "- Users interact with the Optimize API by passing an `Objective` and a list of `Constraint`s to one of three optimize entrypoints:\n",
    "  - The primary entrypoint in research is `calculate_optimal_portfolio`. \n",
    "  - The primary entrypoint in algorithms is `order_optimal_portfolio`.\n",
    "  - `run_optimization` is a lower-level entrypoint primarily useful for debugging.\n",
    "  \n",
    "- When an optimization fails because of `InfeasibleConstraints`, the optimizer provides information about the failed optimization by testing interesting portfolios for constraint information."
   ]
  }
 ],
 "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}