{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1abd08bf",
   "metadata": {},
   "source": [
    "# Sector Allocation\n",
    "\n",
    "The *standard mean-variance (Markowitz) portfolio selection model* determines an optimal investment portfolio that balances risk and expected return. In this notebook, we minimize the variance (risk) of the portfolio given that the prescribed level of expected return is attained. Please refer to the [annotated list of references](../literature.rst#portfolio-optimization) for more background information on portfolio optimization.\n",
    "\n",
    "The stock market comprises different sectors (Technology, Financial Services, Healthcare, etc.), industry groups, industries, and sub-industries and one often wants to limit exposure to each of them. In order to diversify investment risks across different industries, or to comply with regulatory requirements, one often needs to add *sector allocation constraints* to the basic model to limit\n",
    "\n",
    "* the number of open positions and\n",
    "* the total investment\n",
    "\n",
    "in each sector."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "4648f64f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:15.258228Z",
     "iopub.status.busy": "2025-01-31T10:06:15.257822Z",
     "iopub.status.idle": "2025-01-31T10:06:16.051908Z",
     "shell.execute_reply": "2025-01-31T10:06:16.051200Z"
    },
    "nbsphinx": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: numpy in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (2.2.2)\r\n",
      "Requirement already satisfied: scipy in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (1.15.1)\r\n",
      "Requirement already satisfied: gurobipy in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (11.0.3)\r\n",
      "Requirement already satisfied: pandas in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (2.2.3)\r\n",
      "Requirement already satisfied: gurobipy_pandas in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (1.2.0)\r\n",
      "Requirement already satisfied: matplotlib in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (3.10.0)\r\n",
      "Requirement already satisfied: python-dateutil>=2.8.2 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from pandas) (2.9.0.post0)\r\n",
      "Requirement already satisfied: pytz>=2020.1 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from pandas) (2025.1)\r\n",
      "Requirement already satisfied: tzdata>=2022.7 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from pandas) (2025.1)\r\n",
      "Requirement already satisfied: contourpy>=1.0.1 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (1.3.1)\r\n",
      "Requirement already satisfied: cycler>=0.10 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (0.12.1)\r\n",
      "Requirement already satisfied: fonttools>=4.22.0 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (4.55.8)\r\n",
      "Requirement already satisfied: kiwisolver>=1.3.1 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (1.4.8)\r\n",
      "Requirement already satisfied: packaging>=20.0 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (24.2)\r\n",
      "Requirement already satisfied: pillow>=8 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (11.1.0)\r\n",
      "Requirement already satisfied: pyparsing>=2.3.1 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from matplotlib) (3.2.1)\r\n",
      "Requirement already satisfied: six>=1.5 in /opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages (from python-dateutil>=2.8.2->pandas) (1.17.0)\r\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "# Install dependencies\n",
    "%pip install numpy scipy gurobipy pandas gurobipy_pandas matplotlib"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "b0bfb077",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.054230Z",
     "iopub.status.busy": "2025-01-31T10:06:16.053785Z",
     "iopub.status.idle": "2025-01-31T10:06:16.668153Z",
     "shell.execute_reply": "2025-01-31T10:06:16.667490Z"
    }
   },
   "outputs": [],
   "source": [
    "import gurobipy as gp\n",
    "import gurobipy_pandas as gppd\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "218cc278",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.670284Z",
     "iopub.status.busy": "2025-01-31T10:06:16.670004Z",
     "iopub.status.idle": "2025-01-31T10:06:16.678245Z",
     "shell.execute_reply": "2025-01-31T10:06:16.677661Z"
    },
    "nbsphinx": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Set parameter WLSAccessID\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Set parameter WLSSecret\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Set parameter LicenseID to value 2443533\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "WLS license 2443533 - registered to Gurobi GmbH\n"
     ]
    }
   ],
   "source": [
    "# Hidden cell to avoid licensing messages\n",
    "# when docs are generated.\n",
    "with gp.Model():\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87cfcc5b",
   "metadata": {},
   "source": [
    "## Input Data\n",
    "\n",
    "The following input data is used within the model:\n",
    "\n",
    "- $S$: set of stocks\n",
    "- $\\mu$: vector of expected returns\n",
    "- $\\Sigma$: PSD variance-covariance matrix\n",
    "    - $\\sigma_{ij}$ covariance between returns of assets $i$ and $j$\n",
    "    - $\\sigma_{ii}$ variance of return of asset $i$\n",
    "- $M$: set of sectors. We use the 11 sectors in the [Global Industry Classification Standard (GICS)](https://en.wikipedia.org/wiki/Global_Industry_Classification_Standard) classification."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "909aec59",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.680005Z",
     "iopub.status.busy": "2025-01-31T10:06:16.679828Z",
     "iopub.status.idle": "2025-01-31T10:06:16.684532Z",
     "shell.execute_reply": "2025-01-31T10:06:16.684142Z"
    }
   },
   "outputs": [],
   "source": [
    "# Import some example data set\n",
    "Sigma = pd.read_pickle(\"sigma.pkl\")\n",
    "mu = pd.read_pickle(\"mu.pkl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "721e7e42",
   "metadata": {},
   "source": [
    "We also import some data that contains the market capitalization and sector according to the GICS hierarchy for each of the stocks. We will need the total market capitalization and relative weight of each sector in the index."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "b5e19f87",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.686394Z",
     "iopub.status.busy": "2025-01-31T10:06:16.686038Z",
     "iopub.status.idle": "2025-01-31T10:06:16.702029Z",
     "shell.execute_reply": "2025-01-31T10:06:16.701394Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>MarketCap</th>\n",
       "      <th>Number</th>\n",
       "      <th>Weight</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Sector</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Technology</th>\n",
       "      <td>12715607901184</td>\n",
       "      <td>65</td>\n",
       "      <td>0.286058</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Communication Services</th>\n",
       "      <td>6054451107840</td>\n",
       "      <td>18</td>\n",
       "      <td>0.136205</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Financial Services</th>\n",
       "      <td>5588576733184</td>\n",
       "      <td>64</td>\n",
       "      <td>0.125724</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Healthcare</th>\n",
       "      <td>5272300330496</td>\n",
       "      <td>60</td>\n",
       "      <td>0.118609</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Consumer Cyclical</th>\n",
       "      <td>4588151685632</td>\n",
       "      <td>53</td>\n",
       "      <td>0.103218</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Industrials</th>\n",
       "      <td>3305283061760</td>\n",
       "      <td>67</td>\n",
       "      <td>0.074358</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Consumer Defensive</th>\n",
       "      <td>2780607703040</td>\n",
       "      <td>34</td>\n",
       "      <td>0.062554</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Energy</th>\n",
       "      <td>1569043430400</td>\n",
       "      <td>23</td>\n",
       "      <td>0.035298</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Real Estate</th>\n",
       "      <td>931872515072</td>\n",
       "      <td>29</td>\n",
       "      <td>0.020964</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Utilities</th>\n",
       "      <td>868188347904</td>\n",
       "      <td>29</td>\n",
       "      <td>0.019531</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Basic Materials</th>\n",
       "      <td>777054908928</td>\n",
       "      <td>20</td>\n",
       "      <td>0.017481</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                             MarketCap  Number    Weight\n",
       "Sector                                                  \n",
       "Technology              12715607901184      65  0.286058\n",
       "Communication Services   6054451107840      18  0.136205\n",
       "Financial Services       5588576733184      64  0.125724\n",
       "Healthcare               5272300330496      60  0.118609\n",
       "Consumer Cyclical        4588151685632      53  0.103218\n",
       "Industrials              3305283061760      67  0.074358\n",
       "Consumer Defensive       2780607703040      34  0.062554\n",
       "Energy                   1569043430400      23  0.035298\n",
       "Real Estate               931872515072      29  0.020964\n",
       "Utilities                 868188347904      29  0.019531\n",
       "Basic Materials           777054908928      20  0.017481"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Import stock data\n",
    "data = pd.read_pickle(\"stock_data.pkl\")\n",
    "\n",
    "# Display sector data\n",
    "sectors = (\n",
    "    data[[\"Sector\", \"MarketCap\"]].groupby(by=[\"Sector\"]).aggregate([\"sum\", \"count\"])\n",
    ")\n",
    "sectors.columns = [\"MarketCap\", \"Number\"]\n",
    "sectors[\"Weight\"] = sectors[\"MarketCap\"] / sectors[\"MarketCap\"].sum()\n",
    "sectors.sort_values(\"MarketCap\", ascending=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06745e9b",
   "metadata": {},
   "source": [
    "For example, 65 stocks from our set belong to the Technology sector, which accounts for 28.6% of the total market capitalization.\n",
    "\n",
    "For reference, we will compute the _market portfolio_ as the portfolio that allocates into all stocks relative to the stocks' market capitalization."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "a0bf128d",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.703950Z",
     "iopub.status.busy": "2025-01-31T10:06:16.703755Z",
     "iopub.status.idle": "2025-01-31T10:06:16.710823Z",
     "shell.execute_reply": "2025-01-31T10:06:16.710222Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'Variance': np.float64(4.673079099420153), 'Expected return': np.float64(0.28157962440870105)}\n"
     ]
    }
   ],
   "source": [
    "x_market = data[\"MarketCap\"] / data[\"MarketCap\"].sum()\n",
    "data_market = {\n",
    "    \"Variance\": x_market @ Sigma @ x_market,\n",
    "    \"Expected return\": x_market @ mu,\n",
    "}\n",
    "print(data_market)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24bdf74b",
   "metadata": {},
   "source": [
    "## Formulation\n",
    "The model minimizes the variance of the portfolio subject to\n",
    "\n",
    "* the portfolio matches the expected return of the market portfolio,\n",
    "* the size of each position does not fall below a certain level,\n",
    "* the total investment in each sector lies between specified lower and upper bounds,\n",
    "* the number of positions in each sector does not exceed a specified number.\n",
    "\n",
    "Mathematically, this results in a convex quadratic mixed-integer optimization problem.\n",
    "\n",
    "### Model Parameters\n",
    "\n",
    "We use the following parameters:\n",
    "\n",
    "- $\\bar\\mu$: required expected portfolio return\n",
    "- $\\ell>0$: lower bound on position size\n",
    "- $K_m$: maximal number of stocks in the portfolio from sector $m$.\n",
    "- $\\ell_m, u_m$: lower and upper bounds on the weight of sector $m$ in the portfolio. In this notebook, we will choose those bounds as a +/- 10% envelope around the sector weight in the S&P 500: That is, we choose $\\ell_m = (1-\\delta)w_m, u_m = (1+\\delta)w_m$, where $w_m$ is the weight of sector $m$ in the index."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "26a11f80",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.712598Z",
     "iopub.status.busy": "2025-01-31T10:06:16.712426Z",
     "iopub.status.idle": "2025-01-31T10:06:16.715500Z",
     "shell.execute_reply": "2025-01-31T10:06:16.714884Z"
    }
   },
   "outputs": [],
   "source": [
    "# Values for the model parameters:\n",
    "r = data_market[\"Expected return\"]  # Required return\n",
    "l = 0.00001  # Minimal position size\n",
    "K = 3  # Maximal number of stocks per sector\n",
    "delta = 0.1  #  bound on the relative deviation from sector weight"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3c6f4fa",
   "metadata": {},
   "source": [
    "### Decision Variables\n",
    "We need two sets of decision variables:\n",
    "\n",
    "1. The proportions of capital invested among the considered stocks. The corresponding vector of positions is denoted by $x$ with its component $x_i$ denoting the proportion of capital invested in stock $i$.\n",
    "\n",
    "2. Binary variables $b_i$ indicating whether or not asset $i$ is held. If $b_i$ is 0, the holding $x_i$ is also 0; otherwise if $b_i$ is 1, the investor holds asset $i$ (that is, $x_i \\geq \\ell$).\n",
    "\n",
    "### Variable Bounds\n",
    "\n",
    "Each position must be between 0 and 1; this prevents leverage and short-selling:\n",
    "\n",
    "\\begin{equation*}\n",
    "0\\leq x_i\\leq 1 \\; , \\;  i \\in S\n",
    "\\end{equation*}\n",
    "\n",
    "\n",
    "The $b_i$ must be binary:\n",
    "\n",
    "\\begin{equation*}\n",
    "b_i \\in \\{0,1\\} \\; , \\; i \\in S\n",
    "\\end{equation*}\n",
    "\n",
    "We will model this using the [gurobipy-pandas](https://gurobipy-pandas.readthedocs.io/en/stable/) package. Using this, we create a  DataFrame containing the decision variables as columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "270e9862",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.717271Z",
     "iopub.status.busy": "2025-01-31T10:06:16.717075Z",
     "iopub.status.idle": "2025-01-31T10:06:16.737831Z",
     "shell.execute_reply": "2025-01-31T10:06:16.737442Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>MarketCap</th>\n",
       "      <th>Sector</th>\n",
       "      <th>Name</th>\n",
       "      <th>x</th>\n",
       "      <th>b</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>MSFT</th>\n",
       "      <td>3004349808640</td>\n",
       "      <td>Technology</td>\n",
       "      <td>Microsoft Corporation</td>\n",
       "      <td>&lt;gurobi.Var x[MSFT]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[MSFT]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>AAPL</th>\n",
       "      <td>2893580337152</td>\n",
       "      <td>Technology</td>\n",
       "      <td>Apple Inc.</td>\n",
       "      <td>&lt;gurobi.Var x[AAPL]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[AAPL]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>AMZN</th>\n",
       "      <td>1750173089792</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>Amazon.com, Inc.</td>\n",
       "      <td>&lt;gurobi.Var x[AMZN]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[AMZN]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>NVDA</th>\n",
       "      <td>1684540096512</td>\n",
       "      <td>Technology</td>\n",
       "      <td>NVIDIA Corporation</td>\n",
       "      <td>&lt;gurobi.Var x[NVDA]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[NVDA]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>GOOGL</th>\n",
       "      <td>1789200171008</td>\n",
       "      <td>Communication Services</td>\n",
       "      <td>Alphabet Inc.</td>\n",
       "      <td>&lt;gurobi.Var x[GOOGL]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[GOOGL]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>RL</th>\n",
       "      <td>9448713216</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>Ralph Lauren Corporation</td>\n",
       "      <td>&lt;gurobi.Var x[RL]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[RL]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>SEE</th>\n",
       "      <td>4919490560</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>Sealed Air Corporation</td>\n",
       "      <td>&lt;gurobi.Var x[SEE]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[SEE]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DVA</th>\n",
       "      <td>10014481408</td>\n",
       "      <td>Healthcare</td>\n",
       "      <td>DaVita Inc.</td>\n",
       "      <td>&lt;gurobi.Var x[DVA]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[DVA]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>ALK</th>\n",
       "      <td>4465086464</td>\n",
       "      <td>Industrials</td>\n",
       "      <td>Alaska Air Group, Inc.</td>\n",
       "      <td>&lt;gurobi.Var x[ALK]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[ALK]&gt;</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>MHK</th>\n",
       "      <td>6813997568</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>Mohawk Industries, Inc.</td>\n",
       "      <td>&lt;gurobi.Var x[MHK]&gt;</td>\n",
       "      <td>&lt;gurobi.Var b[MHK]&gt;</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>462 rows × 5 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "           MarketCap                  Sector                      Name  \\\n",
       "MSFT   3004349808640              Technology     Microsoft Corporation   \n",
       "AAPL   2893580337152              Technology                Apple Inc.   \n",
       "AMZN   1750173089792       Consumer Cyclical          Amazon.com, Inc.   \n",
       "NVDA   1684540096512              Technology        NVIDIA Corporation   \n",
       "GOOGL  1789200171008  Communication Services             Alphabet Inc.   \n",
       "...              ...                     ...                       ...   \n",
       "RL        9448713216       Consumer Cyclical  Ralph Lauren Corporation   \n",
       "SEE       4919490560       Consumer Cyclical    Sealed Air Corporation   \n",
       "DVA      10014481408              Healthcare               DaVita Inc.   \n",
       "ALK       4465086464             Industrials    Alaska Air Group, Inc.   \n",
       "MHK       6813997568       Consumer Cyclical   Mohawk Industries, Inc.   \n",
       "\n",
       "                           x                      b  \n",
       "MSFT    <gurobi.Var x[MSFT]>   <gurobi.Var b[MSFT]>  \n",
       "AAPL    <gurobi.Var x[AAPL]>   <gurobi.Var b[AAPL]>  \n",
       "AMZN    <gurobi.Var x[AMZN]>   <gurobi.Var b[AMZN]>  \n",
       "NVDA    <gurobi.Var x[NVDA]>   <gurobi.Var b[NVDA]>  \n",
       "GOOGL  <gurobi.Var x[GOOGL]>  <gurobi.Var b[GOOGL]>  \n",
       "...                      ...                    ...  \n",
       "RL        <gurobi.Var x[RL]>     <gurobi.Var b[RL]>  \n",
       "SEE      <gurobi.Var x[SEE]>    <gurobi.Var b[SEE]>  \n",
       "DVA      <gurobi.Var x[DVA]>    <gurobi.Var b[DVA]>  \n",
       "ALK      <gurobi.Var x[ALK]>    <gurobi.Var b[ALK]>  \n",
       "MHK      <gurobi.Var x[MHK]>    <gurobi.Var b[MHK]>  \n",
       "\n",
       "[462 rows x 5 columns]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create an empty optimization model\n",
    "m = gp.Model()\n",
    "\n",
    "# Add variables to model, align with data\n",
    "df_model = (\n",
    "    # x[i] denotes the proportion invested in stock i\n",
    "    data.gppd.add_vars(m, name=\"x\", ub=1)\n",
    "    # b[i]=1 if stock i is held, and b[i]=0 otherwise\n",
    "    .gppd.add_vars(m, name=\"b\", vtype=gp.GRB.BINARY).drop(\n",
    "        \"Risk\", axis=1\n",
    "    )  # Not needed here\n",
    ")\n",
    "\n",
    "# A quick look at this DataFrame:\n",
    "m.update()\n",
    "df_model"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bddf5d9",
   "metadata": {},
   "source": [
    "###  Constraints\n",
    "The budget constraint ensures that all capital is invested:\n",
    "\n",
    "\\begin{equation*}\n",
    "\\sum_{i \\in S} x_i =1\n",
    "\\end{equation*}\n",
    "\n",
    "The expected return of the portfolio must be at least $\\bar\\mu$:\n",
    "\n",
    "\\begin{equation*}\n",
    "\\mu^\\top x \\geq \\bar\\mu\n",
    "\\end{equation*}\n",
    "\n",
    "We use functionality from pandas to create those constraints.  Note that this ensures that the indices of `df_model` and `mu` are aligned."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "e03e88c6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.739765Z",
     "iopub.status.busy": "2025-01-31T10:06:16.739587Z",
     "iopub.status.idle": "2025-01-31T10:06:16.747594Z",
     "shell.execute_reply": "2025-01-31T10:06:16.746972Z"
    }
   },
   "outputs": [],
   "source": [
    "%%capture\n",
    "# Budget constraint: all investments sum up to 1\n",
    "m.addConstr(df_model[\"x\"].sum() == 1, name=\"Budget_Constraint\")\n",
    "\n",
    "# Lower bound on expected return\n",
    "m.addConstr(mu @ df_model[\"x\"] >= r, \"Required_Return\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b238aadb",
   "metadata": {},
   "source": [
    "From the bounds alone, $x$ can take any value between $0$ and $1$. To enforce the minimal position size, we need the binary variables $b$ and the following sets of discrete constraints:\n",
    "\n",
    "Ensure that $x_i = 0$ if $b_i = 0$:\n",
    "\n",
    "\\begin{equation*}\n",
    "x_i \\leq b_i \\; , \\; i \\in S\\tag{1}\n",
    "\\end{equation*}\n",
    "\n",
    "Note that since $x_i$ has an upper bound of 1, the above constraint is non-restrictive if $b_i = 1$.\n",
    "\n",
    "Ensure a minimal position size of $\\ell$ if asset $i$ is traded:\n",
    "\n",
    "\\begin{equation*}\n",
    "x_i \\geq \\ell b_i \\; , \\; i \\in S\\tag{2}\n",
    "\\end{equation*}\n",
    "\n",
    "Hence $b_i = 1$ implies $x_i \\geq \\ell$. Additionally, if $b_i = 0$, the above constraint is non-restrictive since $x_i$ has a lower bound of 0.\n",
    "\n",
    "To add these constraints to the model, we use [gurobipy-pandas functionality](https://gurobipy-pandas.readthedocs.io/en/stable/usage.html#adding-constraints)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "c1cb4d2e",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.749540Z",
     "iopub.status.busy": "2025-01-31T10:06:16.749187Z",
     "iopub.status.idle": "2025-01-31T10:06:16.767961Z",
     "shell.execute_reply": "2025-01-31T10:06:16.767352Z"
    }
   },
   "outputs": [],
   "source": [
    "%%capture\n",
    "# Force x to 0 if not traded; see formula (1) above\n",
    "# We use a gurobipy-pandas DataFrame accessor that takes the constraint as a string with column labels\n",
    "df_model.gppd.add_constrs(m, \"x <= b\", name=\"Indicator\")\n",
    "\n",
    "# Minimal position; see formula (2) above\n",
    "# We use a gurobipy-pandas function that takes the model, the left-hand side, sense, and right-hand side\n",
    "gppd.add_constrs(\n",
    "    m,\n",
    "    df_model[\"x\"],\n",
    "    \">\",\n",
    "    l * df_model[\"b\"],\n",
    "    name=\"Minimal_Position\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4ddd941",
   "metadata": {},
   "source": [
    "#### Allocation constraints by sector\n",
    "\n",
    "The weight of all stocks in sector $m$ must be within the prescribed bounds:\n",
    "\n",
    "\\begin{equation*}\n",
    "\\ell_m \\leq \\sum_{i\\in m} x_i \\leq u_m \\; , \\; m \\in M\\; , \\tag{3}\n",
    "\\end{equation*}\n",
    "\n",
    "where $\\ell_m = (1-\\delta)w_m$ and $u_m = (1+\\delta)w_m$.\n",
    "\n",
    "Likewise, the number of stocks in sector $m$ must not exceed $K_m$. We use the binary variables $b_i$ to count positions.\n",
    "\n",
    "\\begin{equation*}\n",
    "\\sum_{i\\in m} b_i \\leq K_m \\; , \\; m \\in M \\tag{4}\n",
    "\\end{equation*}\n",
    "\n",
    "The DataFrame's `groupby` method can be used to conveniently create sums over all stocks within the same sector:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "41ca838b",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.769848Z",
     "iopub.status.busy": "2025-01-31T10:06:16.769670Z",
     "iopub.status.idle": "2025-01-31T10:06:16.782108Z",
     "shell.execute_reply": "2025-01-31T10:06:16.781511Z"
    }
   },
   "outputs": [],
   "source": [
    "# Lower and upper bounds on position size per sector; see formula (3) above\n",
    "sector_weight_ub = gppd.add_constrs(\n",
    "    m,\n",
    "    df_model.groupby(\"Sector\")[\"x\"].sum(),\n",
    "    \"<\",\n",
    "    sectors[\"Weight\"] * (1 + delta),\n",
    "    name=\"Sector_Weight_UB\",\n",
    ")\n",
    "sector_weight_lb = gppd.add_constrs(\n",
    "    m,\n",
    "    df_model.groupby(\"Sector\")[\"x\"].sum(),\n",
    "    \">\",\n",
    "    sectors[\"Weight\"] * (1 - delta),\n",
    "    name=\"Sector_Weight_LB\",\n",
    ")\n",
    "\n",
    "# Upper bound on the number of positions per sector; see formula (4) above\n",
    "sector_cardinality = gppd.add_constrs(\n",
    "    m,\n",
    "    df_model.groupby(\"Sector\")[\"b\"].sum(),\n",
    "    \"<\",\n",
    "    K,\n",
    "    name=\"Sector_Cardinality\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1de07ab8",
   "metadata": {},
   "source": [
    "###  Objective Function\n",
    "The objective is to minimize the risk of the portfolio, which is measured by its variance:\n",
    "\n",
    "\\begin{equation*}\n",
    "\\min_x x^\\top \\Sigma x\n",
    "\\end{equation*}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "63cbd73f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:16.783942Z",
     "iopub.status.busy": "2025-01-31T10:06:16.783760Z",
     "iopub.status.idle": "2025-01-31T10:06:17.489918Z",
     "shell.execute_reply": "2025-01-31T10:06:17.489278Z"
    }
   },
   "outputs": [],
   "source": [
    "# Define objective function: Minimize risk\n",
    "m.setObjective(df_model[\"x\"] @ Sigma @ df_model[\"x\"], gp.GRB.MINIMIZE)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58880728",
   "metadata": {},
   "source": [
    "We now solve the optimization problem:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "8ff170e8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:17.492037Z",
     "iopub.status.busy": "2025-01-31T10:06:17.491858Z",
     "iopub.status.idle": "2025-01-31T10:06:17.956548Z",
     "shell.execute_reply": "2025-01-31T10:06:17.955802Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Gurobi Optimizer version 11.0.3 build v11.0.3rc0 (linux64 - \"Ubuntu 24.04.1 LTS\")\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU model: AMD EPYC 7763 64-Core Processor, instruction set [SSE2|AVX|AVX2]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Thread count: 1 physical cores, 2 logical processors, using up to 2 threads\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "WLS license 2443533 - registered to Gurobi GmbH\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Optimize a model with 959 rows, 924 columns and 4158 nonzeros\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model fingerprint: 0xd130e4c6\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model has 106953 quadratic objective terms\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Variable types: 462 continuous, 462 integer (462 binary)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Coefficient statistics:\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Matrix range     [1e-05, 1e+00]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Objective range  [0e+00, 0e+00]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  QObjective range [6e-03, 2e+02]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Bounds range     [1e+00, 1e+00]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  RHS range        [2e-02, 3e+00]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Presolve time: 0.05s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Presolved: 959 rows, 924 columns, 4157 nonzeros\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Presolved model has 106953 quadratic objective terms\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Variable types: 462 continuous, 462 integer (462 binary)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found heuristic solution: objective 4.2808136\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Root relaxation: objective 2.599011e+00, 210 iterations, 0.01 seconds (0.01 work units)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "    Nodes    |    Current Node    |     Objective Bounds      |     Work\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   36    4.28081    2.59901  39.3%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H    0     0                       2.6251831    2.59901  1.00%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   34    2.62518    2.59901  1.00%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   33    2.62518    2.59901  1.00%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H    0     0                       2.6225600    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   32    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     2    2.59901    0   30    2.62256    2.59901  0.90%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H   40    11                       2.6225597    2.62091  0.06%   8.1    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cutting planes:\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Gomory: 1\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Cover: 3\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  MIR: 2\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Flow cover: 8\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Explored 53 nodes (627 simplex iterations) in 0.45 seconds (0.25 work units)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Thread count was 2 (of 2 available processors)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Solution count 4: 2.62256 2.62256 2.62518 4.28081 \n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Optimal solution found (tolerance 1.00e-04)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Best objective 2.622559688764e+00, best bound 2.622379368808e+00, gap 0.0069%\n"
     ]
    }
   ],
   "source": [
    "m.optimize()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5abe6094",
   "metadata": {},
   "source": [
    "Display basic solution data based on the individual assets and sectors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "db302b36",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:17.958480Z",
     "iopub.status.busy": "2025-01-31T10:06:17.958306Z",
     "iopub.status.idle": "2025-01-31T10:06:17.971961Z",
     "shell.execute_reply": "2025-01-31T10:06:17.971354Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Variance:         2.622560\n",
      "Expected return:  0.281580\n",
      "Solution time:    0.46 seconds\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>MarketCap</th>\n",
       "      <th>Sector</th>\n",
       "      <th>Position</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>MSFT</th>\n",
       "      <td>3004349808640</td>\n",
       "      <td>Technology</td>\n",
       "      <td>0.129882</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>LLY</th>\n",
       "      <td>667918204928</td>\n",
       "      <td>Healthcare</td>\n",
       "      <td>0.119143</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>PGR</th>\n",
       "      <td>106073907200</td>\n",
       "      <td>Financial Services</td>\n",
       "      <td>0.096290</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>BR</th>\n",
       "      <td>23238772736</td>\n",
       "      <td>Technology</td>\n",
       "      <td>0.082739</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>TMUS</th>\n",
       "      <td>193721221120</td>\n",
       "      <td>Communication Services</td>\n",
       "      <td>0.063901</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DPZ</th>\n",
       "      <td>14603976704</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>0.054687</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>WM</th>\n",
       "      <td>75618992128</td>\n",
       "      <td>Industrials</td>\n",
       "      <td>0.049627</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>TYL</th>\n",
       "      <td>17882144768</td>\n",
       "      <td>Technology</td>\n",
       "      <td>0.044831</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>AZO</th>\n",
       "      <td>48049000448</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>0.037813</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>TTWO</th>\n",
       "      <td>27903057920</td>\n",
       "      <td>Communication Services</td>\n",
       "      <td>0.035356</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>NOC</th>\n",
       "      <td>66327912448</td>\n",
       "      <td>Industrials</td>\n",
       "      <td>0.031669</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>KR</th>\n",
       "      <td>33348851712</td>\n",
       "      <td>Consumer Defensive</td>\n",
       "      <td>0.030470</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CME</th>\n",
       "      <td>73643769856</td>\n",
       "      <td>Financial Services</td>\n",
       "      <td>0.029367</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>KDP</th>\n",
       "      <td>43670155264</td>\n",
       "      <td>Consumer Defensive</td>\n",
       "      <td>0.024210</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CTRA</th>\n",
       "      <td>18142871552</td>\n",
       "      <td>Energy</td>\n",
       "      <td>0.023883</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>VZ</th>\n",
       "      <td>174259945472</td>\n",
       "      <td>Communication Services</td>\n",
       "      <td>0.023327</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>ED</th>\n",
       "      <td>31142295552</td>\n",
       "      <td>Utilities</td>\n",
       "      <td>0.021474</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>MCD</th>\n",
       "      <td>207836446720</td>\n",
       "      <td>Consumer Cyclical</td>\n",
       "      <td>0.020241</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DLR</th>\n",
       "      <td>44423024640</td>\n",
       "      <td>Real Estate</td>\n",
       "      <td>0.018868</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>HRL</th>\n",
       "      <td>16470820864</td>\n",
       "      <td>Consumer Defensive</td>\n",
       "      <td>0.014130</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>MKTX</th>\n",
       "      <td>8191925760</td>\n",
       "      <td>Financial Services</td>\n",
       "      <td>0.012639</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>APD</th>\n",
       "      <td>49082589184</td>\n",
       "      <td>Basic Materials</td>\n",
       "      <td>0.008529</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>XOM</th>\n",
       "      <td>402421940224</td>\n",
       "      <td>Energy</td>\n",
       "      <td>0.007886</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>NEM</th>\n",
       "      <td>38533505024</td>\n",
       "      <td>Basic Materials</td>\n",
       "      <td>0.007204</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>GILD</th>\n",
       "      <td>95658491904</td>\n",
       "      <td>Healthcare</td>\n",
       "      <td>0.006410</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>MRK</th>\n",
       "      <td>318729060352</td>\n",
       "      <td>Healthcare</td>\n",
       "      <td>0.004917</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>RSG</th>\n",
       "      <td>54473105408</td>\n",
       "      <td>Industrials</td>\n",
       "      <td>0.000497</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "          MarketCap                  Sector  Position\n",
       "MSFT  3004349808640              Technology  0.129882\n",
       "LLY    667918204928              Healthcare  0.119143\n",
       "PGR    106073907200      Financial Services  0.096290\n",
       "BR      23238772736              Technology  0.082739\n",
       "TMUS   193721221120  Communication Services  0.063901\n",
       "DPZ     14603976704       Consumer Cyclical  0.054687\n",
       "WM      75618992128             Industrials  0.049627\n",
       "TYL     17882144768              Technology  0.044831\n",
       "AZO     48049000448       Consumer Cyclical  0.037813\n",
       "TTWO    27903057920  Communication Services  0.035356\n",
       "NOC     66327912448             Industrials  0.031669\n",
       "KR      33348851712      Consumer Defensive  0.030470\n",
       "CME     73643769856      Financial Services  0.029367\n",
       "KDP     43670155264      Consumer Defensive  0.024210\n",
       "CTRA    18142871552                  Energy  0.023883\n",
       "VZ     174259945472  Communication Services  0.023327\n",
       "ED      31142295552               Utilities  0.021474\n",
       "MCD    207836446720       Consumer Cyclical  0.020241\n",
       "DLR     44423024640             Real Estate  0.018868\n",
       "HRL     16470820864      Consumer Defensive  0.014130\n",
       "MKTX     8191925760      Financial Services  0.012639\n",
       "APD     49082589184         Basic Materials  0.008529\n",
       "XOM    402421940224                  Energy  0.007886\n",
       "NEM     38533505024         Basic Materials  0.007204\n",
       "GILD    95658491904              Healthcare  0.006410\n",
       "MRK    318729060352              Healthcare  0.004917\n",
       "RSG     54473105408             Industrials  0.000497"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data_model1 = {\n",
    "    \"Variance\": m.ObjVal,\n",
    "    \"Expected return\": mu @ df_model[\"x\"].gppd.X,\n",
    "}\n",
    "\n",
    "print(f\"Variance:         {m.ObjVal:.6f}\")\n",
    "print(f\"Expected return:  {mu @ df_model['x'].gppd.X:.6f}\")\n",
    "print(f\"Solution time:    {m.Runtime:.2f} seconds\\n\")\n",
    "\n",
    "# Print investments (with non-negligible value, i.e. >1e-5)\n",
    "data[\"Position\"] = df_model[\"x\"].gppd.X\n",
    "data[data[\"Position\"] > 1e-5][[\"MarketCap\", \"Sector\", \"Position\"]].sort_values(\n",
    "    \"Position\", ascending=False\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "89d6ff0a",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:17.973677Z",
     "iopub.status.busy": "2025-01-31T10:06:17.973509Z",
     "iopub.status.idle": "2025-01-31T10:06:17.981621Z",
     "shell.execute_reply": "2025-01-31T10:06:17.981018Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Weight</th>\n",
       "      <th>Number</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Sector</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Technology</th>\n",
       "      <td>0.257452</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Financial Services</th>\n",
       "      <td>0.138296</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Healthcare</th>\n",
       "      <td>0.130470</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Communication Services</th>\n",
       "      <td>0.122584</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Consumer Cyclical</th>\n",
       "      <td>0.112741</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Industrials</th>\n",
       "      <td>0.081793</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Consumer Defensive</th>\n",
       "      <td>0.068810</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Energy</th>\n",
       "      <td>0.031768</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Utilities</th>\n",
       "      <td>0.021474</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Real Estate</th>\n",
       "      <td>0.018868</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Basic Materials</th>\n",
       "      <td>0.015733</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                          Weight  Number\n",
       "Sector                                  \n",
       "Technology              0.257452       3\n",
       "Financial Services      0.138296       3\n",
       "Healthcare              0.130470       3\n",
       "Communication Services  0.122584       3\n",
       "Consumer Cyclical       0.112741       3\n",
       "Industrials             0.081793       3\n",
       "Consumer Defensive      0.068810       3\n",
       "Energy                  0.031768       2\n",
       "Utilities               0.021474       1\n",
       "Real Estate             0.018868       1\n",
       "Basic Materials         0.015733       2"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Display sector data\n",
    "data_sectors = (\n",
    "    data[data[\"Position\"] > 1e-5].groupby(\"Sector\")[\"Position\"].agg([\"sum\", \"count\"])\n",
    ")\n",
    "data_sectors.columns = [\"Weight\", \"Number\"]\n",
    "data_sectors.sort_values(\"Weight\", ascending=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d5d3b8a",
   "metadata": {},
   "source": [
    "## Comparison with the unconstrained portfolio\n",
    "\n",
    "For comparison purposes, we will also compute the portfolio without the sector allocation constraints:\n",
    "\n",
    "* upper and lower bounds on the weight of each sector in the portfolio,\n",
    "* upper bound on the number of bought stocks in each sector.\n",
    "\n",
    "\n",
    "To compute this, we relax the right-hand sides of those constraints enough to make them non-binding.  In addition, we show the risk and return of the market porfolio that results from weighing all the of S&P500 stocks according to their market capitalization."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "2bbfca04",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:17.983386Z",
     "iopub.status.busy": "2025-01-31T10:06:17.983218Z",
     "iopub.status.idle": "2025-01-31T10:06:18.074432Z",
     "shell.execute_reply": "2025-01-31T10:06:18.073737Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Variance</th>\n",
       "      <th>Expected return</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>with allocation constraints</th>\n",
       "      <td>2.622560</td>\n",
       "      <td>0.28158</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>unconstrained</th>\n",
       "      <td>2.344234</td>\n",
       "      <td>0.28158</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>market</th>\n",
       "      <td>4.673079</td>\n",
       "      <td>0.28158</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                             Variance  Expected return\n",
       "with allocation constraints  2.622560          0.28158\n",
       "unconstrained                2.344234          0.28158\n",
       "market                       4.673079          0.28158"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# remove sector allocation constraints by relaxing the RHSs\n",
    "sector_weight_ub.gppd.set_attr(\"RHS\", 1)\n",
    "sector_weight_lb.gppd.set_attr(\"RHS\", 0)\n",
    "sector_cardinality.gppd.set_attr(\"RHS\", 100)\n",
    "\n",
    "m.params.OutputFlag = 0\n",
    "m.optimize()\n",
    "\n",
    "data_model2 = {\n",
    "    \"Variance\": m.ObjVal,\n",
    "    \"Expected return\": mu @ df_model[\"x\"].gppd.X,\n",
    "}\n",
    "\n",
    "df_results = pd.DataFrame(\n",
    "    index=[\"with allocation constraints\", \"unconstrained\", \"market\"],\n",
    "    data=[data_model1, data_model2, data_market],\n",
    ")\n",
    "display(df_results)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2cb820b0",
   "metadata": {},
   "source": [
    "From this comparison we see the effect of enforcing our sector allocation constraints:\n",
    "\n",
    "- In comparison with the unconstrained portfolio, the variance increases by about 15% by enforcing all sector allocation constraints.  This is the \"price\" we have to pay for these portfolio features.\n",
    "- The optimized portfolios have greatly reduced variance in comparison with the market portfolio.\n",
    "\n",
    "Finally we visualize the allocated investment sum for each stock being bought by either of the two optimized portfolios."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "5b63415c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:18.076410Z",
     "iopub.status.busy": "2025-01-31T10:06:18.076237Z",
     "iopub.status.idle": "2025-01-31T10:06:18.360171Z",
     "shell.execute_reply": "2025-01-31T10:06:18.359440Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# retrieve solution data and store in data\n",
    "data[\"Position unconstr\"] = df_model[\"x\"].gppd.X\n",
    "\n",
    "mask = (data[\"Position\"] > 1e-5) | (data[\"Position unconstr\"] > 1e-5)\n",
    "df_positions = pd.DataFrame(\n",
    "    index=data[mask].index,\n",
    "    data={\n",
    "        \"sector allocation\": data[\"Position\"],\n",
    "        \"unconstrained\": data[\"Position unconstr\"],\n",
    "    },\n",
    ").sort_values(by=[\"sector allocation\", \"unconstrained\"], ascending=True)\n",
    "\n",
    "# plot data\n",
    "axs = df_positions.plot.barh(color=[\"#0b1a3c\", \"#dd2113\"])\n",
    "axs.set_xlabel(\"Fraction of investment sum (per asset)\")\n",
    "plt.title(\"Portfolios with and without sector allocation constraints\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8108e842",
   "metadata": {},
   "source": [
    "We can also compare the resulting sector allocation with the unconstrained portfolio and the market capitalization in the S&P 500 index:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "608b15bb",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:06:18.362283Z",
     "iopub.status.busy": "2025-01-31T10:06:18.362054Z",
     "iopub.status.idle": "2025-01-31T10:06:18.501989Z",
     "shell.execute_reply": "2025-01-31T10:06:18.501291Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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/caECROIjo7m8uXLphHn+Ph4KleunKt4/P39TT8bDAY8PDxM01OioqKoXr16tsl2cnIyEyZM4LvvviMhIYHbt29z48aNTCPctWrVMnudk2vMiq2tLba2trm6PhEREXn6KOF+yjk6OlKuXDmzfX/++afp5+TkZPr27cvAgQMznVuqVCmuXbtGYGAggYGBfPPNNxQtWpT4+HgCAwPv64bEggULmr02GAymBN7e3v6u5w4bNozNmzczffp0ypUrh729Pa+++mqmOBwdHc1e3+sac8unRy0MVvrVkqddwzytLfnMtjytT0TkYVJWIHdVo0YNDh06lCkpz3Dw4EEuXrzI1KlTTXOY9+7de9c6bWxsSEtLy3Us/v7+zJs3j0uXLmU5yh0ZGUlISAivvPIKcCeRPnny5D3rvdc1ioiIiDwI3TQpdzVixAh27NjBgAEDiIqK4tixY6xbt840J7pUqVLY2Njw8ccfc+LECdavX8+kSZPuWqe3tzfJycmEh4dz4cIFrl+/nqNYOnfujIeHB23atCEyMpITJ06wevVqdu7cCYCvry9r1qwhKiqK6OhoXnvtNdPo+INco4iIiMiDUMItd+Xv78+WLVs4evQoDRs2pHr16owbN44SJUoAULRoUcLCwli5ciWVK1dm6tSpTJ8+/a511q9fnzfeeIOOHTtStGhRpk2blqNYbGxs+PHHHylWrBgtWrTAz8+PqVOnYm1tDcCHH35IoUKFqF+/Pq1atSIwMJAaNWo88DWKiIiIPAitUiKSRzLucnbweE5zuEXymOZwi4ilPIxVSjTCLSIiIiJiQRqGE8ljCUc2WewbsoiIiDx+NMItIiIiImJBSrhFRERERCxICbeIiIiIiAUp4RYRERERsSAl3CIiIiIiFqSEW0RERETEgpRwi4iIiIhYkBJuERERERELUsItIiIiImJBSrhFRERERCxICbeIiIiIiAUp4RYRERERsSAl3CIiIiIiFqSEW0RERETEgpRwi4iIiIhYUIH8DkDkSRPn742zlb7LyuPD58SF/A5BROSJpqxARERERMSClHCLiIiIiFiQEm4REREREQtSwp1PDAYDa9eutWgbYWFhuLm5WbSN/BYSEkKbNm3yOwwRERGRbOV7wn327FneeustfHx8sLW1xcvLi1atWhEeHp7foVlUQkICzZs3z7P6vL29+eijj8z2dezY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75g8eTJRUVHY29ubVrQICAjI6xhFHgtJSUm4urri4PGcppRIJppSIiLyaMr4+52YmGix+7HuOyt46aWXeOmll/IyFhERERGRJ859J9xXrlxh1apVnDhxgmHDhuHu7s6+ffsoXrw4zzzzTF7GKPJYSTiySSuWiIiIiMl9JdwHDhygadOmuLq6cvLkSXr16oW7uztr1qwhPj6eRYsW5XWcIiIiIiKPpftapWTIkCGEhIRw7Ngx7OzsTPtbtGihdbhFRERERP7hvhLuPXv2ZLl6wzPPPMPZs2cfOCgRERERkSfFfSXctra2WT7g5ujRo6aHnYiIiIiIyH0m3C+//DITJ040PabbYDAQHx/PiBEjaNeuXZ4GKCIiIiLyOLuvhHvGjBkkJydTrFgxbty4QUBAAGXLlsXJyYn33nsvr2MUEREREXls3dcqJa6urmzevJnt27dz4MABkpOTqVmzJi+++GJexyciIiIi8ljL1Qj3zp072bBhg+n1888/j6OjI59++imdO3emT58+pKSk5HmQIiIiIiKPq1wl3BMnTuSPP/4wvT548CC9e/emWbNmjBw5kv/9739MmTIlz4MUEREREXlc5SrhjoqKMps2smzZMurUqcOXX37JkCFDmD17NitWrMjzIEVEREREHle5SrgvX75M8eLFTa+3bNlC8+bNTa9r167N6dOn8y46EREREZHHXK4S7uLFixMXFwdAamoq+/bt47nnnjMdv3r1KgULFszbCEVEREREHmO5SrhbtGjByJEj2bZtG6NGjcLBwYGGDRuajh84cICyZcvmeZAiIiIiIo+rXC0LOGnSJNq2bUtAQABOTk4sXLgQGxsb0/H58+fzn//8J8+DFBERERF5XBmMRqMxtyclJibi5OSEtbW12f5Lly7h5ORkloSLPC2SkpJwdXUlMTERFxeX/A5HREREcuBh/P2+7wffZMXd3f2BghERERERedLcV8ItItmL8/fG2SpXt0eIiIg8MnxOXMjvEJ44ygpERERERCxICbeIiIiIiAUp4RYRERERsSAl3PJQfPHFF3h5eWFlZcVHH31k8fZOnjyJwWAgKirK4m2JiIiI3M1Tl3CfPXuWt956Cx8fH2xtbfHy8qJVq1aEh4fnd2iPlJCQEAwGAwaDgYIFC1K8eHGaNWvG/PnzSU9Pz1VdSUlJDBgwgBEjRnDmzBn69Olj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IFObWc2n/mesR44cyTJWK6ucvy2LFi1Kt27d+Prrr/noo4/44osvsi372muv8fvvv/Pbb7+xatUq03SSB7kOERERkXt5ahJugDlz5pCWlkadOnVYvXo1x44dIyYmhtmzZ1OvXj0AmjZtip+fH8HBwezbt4/du3fTtWtXAgICcjwVY9euXUyePJm9e/cSHx/PmjVrOH/+PJUqVQLuzKH+7rvv+O677zh8+DBvvvmmKeF/ECNGjGDHjh0MGDCAqKgojh07xrp16zLdNJlTKSkpnD17ljNnzrBv3z4mT55M69atadmyJV27dgXu9Fe9evVo06YNP/74IydPnmTHjh2MHj060woq/zRu3DgWLVpEaGgof/zxBzExMSxbtowxY8bkOL5x48axbt06jh8/zh9//MGGDRtMfZwVb29v6tevT8+ePUlLS+Pll182Hbvf6xARERG5l6cq4fbx8WHfvn00adKEoUOH8uyzz9KsWTPCw8NNS8YZDAbWrVtHoUKFaNSoEU2bNsXHx4fly5fnuB0XFxe2bt1KixYtKF++PGPGjGHGjBk0b94cgB49etCtWzdTIu/j40OTJk0e+Pr8/f3ZsmULR48epWHDhlSvXp1x48ZRokSJ+6pv48aNeHp64u3tTVBQEL/88guzZ89m3bp1WFtbA3f66/vvv6dRo0Z0796d8uXL06lTJ06dOmWaY56VwMBANmzYwI8//kjt2rV57rnnmDlzpmnFkJywsbFh1KhR+Pv706hRI6ytrVm2bNldzwkODiY6OppXXnkFe3t70/77vQ4RERGRezEYc7tWnYhkKSkpCVdXVxw8ntMc7seY5nCLiDxdMv5+JyYm4uLiYpE2nqoRbhERERGRh03DcCJ5LOHIJot9QxYREZHHj0a4RUREREQsSAm3iIiIiIgFKeEWEREREbEgJdwiIiIiIhakhFtERERExIKUcIuIiIiIWJASbhERERERC1LCLSIiIiJiQUq4RUREREQsSAm3iIiIiIgFKeEWEREREbEgJdwiIiIiIhakhFtERERExIKUcIuIiIiIWJASbhERERERC1LCLSIiIiJiQUq4RUREREQsSAm3iIiIiIgFKeEWEREREbEgJdwiIiIiIhakhFsempCQEAwGQ6YtKCgov0MTERERsZgC+R2APF2CgoJYsGCB2T5bW1uLtZeamoqNjY3F6s/KjcjC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9NNPTJkyhcOHD5OUlMTt27e5efMm169fx8HBIctzDh48SFpaGuXLlzfbn5KSYnrgQFZsbW2xtbXN6aWKiIjIU0oJ91PI0dGRcuXKATB//nyqVq3KV199Rc+ePU3znb/77jueeeYZs/Mykstly5YxbNgwZsyYQb169XB2duaDDz5g165duY6lTJky2a4asmDBAgYOHMjGjRtZvnw5Y8aMYfPmzTz33HNZlj958iQtW7bkzTff5L333sPd3Z3t27fTs2dPUlNTs024k5OTsba25rfffsPa2trsWMaUk9zw6VELg9XD/9V6HJ4WJyIi8jRSwv2Us7Ky4p133mHIkCG89tprVK5cGVtbW+Lj4wkICMjynMjISOrXr0+/fv1M+2JjYy0SX/Xq1alevTqjRo2iXr16LFmyhOeeew4bGxvS0tLMyv7222+kp6czY8YM042XK1asMCuT1XnVq1cnLS2Nc+fO0bBhQ4tch4iIyKPOYDDw7bff6jkaFqBVSoT27dtjbW3NnDlzcHZ2ZtiwYQwePJiFCxcSGxvLvn37+Pjjj1m4cCEAvr6+7N27l02bNnH06FHGjh3Lnj177qvtc+fOcfbsWbPt1q1bxMXFMWrUKHbu3MmpU6f48ccfOXbsmGket7e3N3FxcURFRXHhwgVSUlIoV64ct27d4uOPP+bEiRMsXryYzz77zKw9b29vkpOTCQ8P58KFC1y/fp3y5csTHBxM165dWbNmDXFxcezevZspU6bw3XffPVjniog84m5stXmoW26dP3+eN998k1KlSplW2QoMDCQyMtKs3Ndff03FihWxs7PD29ubSZMmZarr5MmTZs99KFy4MP/5z3/Yv39/tu1n99yIfz8zYs6cOXh7e2NnZ0fdunXZvXu32fGbN2/Sv39/ChcujJOTE+3atePvv//OdX88yry9vfnoo4/yO4xHkhJuoUCBAgwYMIBp06Zx7do1Jk2axNixY5kyZQqVKlUiKCiI7777jjJlygDQt29f2rZtS8eOHalbty4XL140G+3OjQoVKuDp6Wm2/fbbbzg4OHD48GHatWtH+fLl6dOnD/3796dv374AtGvXjqCgIJo0aULRokVZunQpVatW5cMPP+T999/n2Wef5ZtvvmHKlClm7dWvX5833niDjh07UrRoUaZNmwbcmb7StWtXhg4dSoUKFWjTpg179uyhVKlS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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "df_sectors = pd.DataFrame(\n",
    "    index=data_sectors.index,\n",
    "    data={\n",
    "        \"with constraints\": data_sectors[\"Weight\"],\n",
    "        \"S&P 500 market cap\": sectors[\"Weight\"],\n",
    "        \"unconstrained\": data.groupby(\"Sector\").sum()[\"Position unconstr\"],\n",
    "    },\n",
    ").sort_values(by=[\"with constraints\"], ascending=True)\n",
    "\n",
    "axs = df_sectors.plot.barh(color=[\"#0b1a3c\", \"#f6c105\", \"#dd2113\"])\n",
    "axs.set_xlabel(\"Fraction of investment sum (per sector)\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f35c236",
   "metadata": {},
   "source": [
    "One can see that without the allocation constraints, the resulting portfolio can be quite far from the distribution in the index. For example, in the S&P 500, the Technology sector has a weight of almost 29%, but the unconstrained portfolio almost completely avoids it due to its high variance.  With the sector allocation constraints, we maintain the diversification from the index.\n",
    "\n",
    "## Takeaways\n",
    "* Constraints on the number of assets and total investment in each sector can be incorporated into the model.\n",
    "* Data from pandas DataFrames can easily be used to build an optimization model via the [gurobipy-pandas](https://github.com/Gurobi/gurobipy-pandas) package.\n",
    "* Sums over subsets of the variables can be defined using the DataFrame's `groupby` method."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}