{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8452d272",
   "metadata": {},
   "source": [
    "# Cardinality Constraints\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, constraining the expected return to meet a prescribed minimum level. Please refer to the [annotated list of references](../literature.rst#portfolio-optimization) for more background information on portfolio optimization.\n",
    "\n",
    "To this basic model, we add *cardinality constraints* to\n",
    "\n",
    "* limit the number of open positions and\n",
    "* limit the minimum size of each position.\n",
    "\n",
    "These limits are often used to reduce transaction costs and simplify the rebalancing and management of the portfolio."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "9688aaeb",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:39.564265Z",
     "iopub.status.busy": "2025-01-31T10:03:39.564014Z",
     "iopub.status.idle": "2025-01-31T10:03:40.359724Z",
     "shell.execute_reply": "2025-01-31T10:03:40.359002Z"
    },
    "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: 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"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "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 matplotlib"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "ce2b93bb",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:40.361838Z",
     "iopub.status.busy": "2025-01-31T10:03:40.361632Z",
     "iopub.status.idle": "2025-01-31T10:03:40.974655Z",
     "shell.execute_reply": "2025-01-31T10:03:40.973982Z"
    }
   },
   "outputs": [],
   "source": [
    "import gurobipy as gp\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "8e28de71",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:40.976839Z",
     "iopub.status.busy": "2025-01-31T10:03:40.976587Z",
     "iopub.status.idle": "2025-01-31T10:03:40.984669Z",
     "shell.execute_reply": "2025-01-31T10:03:40.984093Z"
    },
    "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": "ef07e319",
   "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$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "e29d2fd6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:40.986453Z",
     "iopub.status.busy": "2025-01-31T10:03:40.986266Z",
     "iopub.status.idle": "2025-01-31T10:03:40.991898Z",
     "shell.execute_reply": "2025-01-31T10:03:40.991334Z"
    }
   },
   "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": "4ad8eb55",
   "metadata": {},
   "source": [
    "## Formulation\n",
    "The model minimizes the variance of the portfolio given that the minimum level of expected return is attained, that the number of positions held does not exceed a specified number, and that the size of each position does not fall below a certain level.\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",
    "- $K$: maximal number of stocks in the portfolio\n",
    "- $\\ell>0$: lower bound on position size"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "f2c88d6b",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:40.993662Z",
     "iopub.status.busy": "2025-01-31T10:03:40.993478Z",
     "iopub.status.idle": "2025-01-31T10:03:40.996203Z",
     "shell.execute_reply": "2025-01-31T10:03:40.995815Z"
    }
   },
   "outputs": [],
   "source": [
    "# Values for the model parameters:\n",
    "r = 0.25  # Required return\n",
    "K = 15  # Maximal number of stocks\n",
    "l = 0.00001  # Minimal position size"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e7725f1",
   "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",
    "$$0\\leq x_i\\leq 1 \\; , \\;  i \\in S$$\n",
    "\n",
    "The $b_i$ must be binary:\n",
    "\n",
    "$$b_i \\in \\{0,1\\} \\; , \\; i \\in S$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "6cf12ccc",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:40.997959Z",
     "iopub.status.busy": "2025-01-31T10:03:40.997769Z",
     "iopub.status.idle": "2025-01-31T10:03:41.002925Z",
     "shell.execute_reply": "2025-01-31T10:03:41.002528Z"
    }
   },
   "outputs": [],
   "source": [
    "%%capture\n",
    "# Create an empty optimization model\n",
    "m = gp.Model()\n",
    "\n",
    "# Add variables: x[i] denotes the proportion invested in stock i\n",
    "x = m.addMVar(len(mu), lb=0, ub=1, name=\"x\")\n",
    "\n",
    "# Add variables: b[i]=1 if stock i is held, and b[i]=0 otherwise\n",
    "b = m.addMVar(len(mu), vtype=gp.GRB.BINARY, name=\"b\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93e6fe92",
   "metadata": {},
   "source": [
    "###  Constraints\n",
    "The budget constraint ensures that all capital is invested:\n",
    "\n",
    "$$\\sum_{i \\in S} x_i =1 $$\n",
    "\n",
    "The expected return of the portfolio must be at least $\\bar\\mu$:\n",
    "\n",
    "$$\\mu^\\top x \\geq \\bar\\mu$$\n",
    "\n",
    "\n",
    "The variable bounds only enforce that each $x_i$ is between $0$ and $1$. To enforce the minimal position size, we use 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 $x_i$ has an upper bound of 1. Thus, if $b_i = 1$, the above constraint is non-restrictive.\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$. If $b_i = 0$, this constraint is non-restrictive since $x_i$ has a lower bound of 0.\n",
    "\n",
    "\n",
    "Finally, there must be at most $K$ positions in the portfolio:\n",
    "\n",
    "\\begin{equation*}\n",
    "\\sum_{i \\in S} b_i \\leq K\n",
    "\\end{equation*}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "544762d0",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:41.004602Z",
     "iopub.status.busy": "2025-01-31T10:03:41.004424Z",
     "iopub.status.idle": "2025-01-31T10:03:41.108941Z",
     "shell.execute_reply": "2025-01-31T10:03:41.108421Z"
    }
   },
   "outputs": [],
   "source": [
    "# Budget constraint: all investments sum up to 1\n",
    "m.addConstr(x.sum() == 1, \"Budget_Constraint\")\n",
    "\n",
    "# Lower bound on expected return\n",
    "m.addConstr(mu.to_numpy() @ x >= r, \"Minimal_Return\")\n",
    "\n",
    "# Force x to 0 if not traded; see formula (1) above\n",
    "m.addConstr(x <= b, name=\"Indicator\")\n",
    "\n",
    "# Minimal position; see formula (2) above\n",
    "m.addConstr(x >= l * b, name=\"Minimal_Position\")\n",
    "\n",
    "# Cardinality constraint: at most K positions\n",
    "cardinality_constr = m.addConstr(b.sum() <= K, \"Cardinality\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24bc3992",
   "metadata": {},
   "source": [
    "###  Objective Function\n",
    "The objective is to minimize the risk of the portfolio, which is measured by its variance:\n",
    "\n",
    "$$\\min_x x^\\top \\Sigma x$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "ca471842",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:41.111554Z",
     "iopub.status.busy": "2025-01-31T10:03:41.111278Z",
     "iopub.status.idle": "2025-01-31T10:03:41.130445Z",
     "shell.execute_reply": "2025-01-31T10:03:41.129875Z"
    }
   },
   "outputs": [],
   "source": [
    "# Define objective function: Minimize risk\n",
    "m.setObjective(x @ Sigma.to_numpy() @ x, gp.GRB.MINIMIZE)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34d73edc",
   "metadata": {},
   "source": [
    "We now solve the optimization problem:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "5385a123",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:41.133015Z",
     "iopub.status.busy": "2025-01-31T10:03:41.132683Z",
     "iopub.status.idle": "2025-01-31T10:03:58.601505Z",
     "shell.execute_reply": "2025-01-31T10:03:58.600902Z"
    }
   },
   "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 927 rows, 924 columns and 3234 nonzeros\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model fingerprint: 0x73f3de97\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-01, 2e+01]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found heuristic solution: objective 21.1318982\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Presolve time: 0.05s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Presolved: 927 rows, 924 columns, 3233 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": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Root relaxation: objective 2.026597e+00, 154 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.02660    0   37   21.13190    2.02660  90.4%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H    0     0                       2.5684442    2.02660  21.1%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.02660    0   37    2.56844    2.02660  21.1%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H    0     0                       2.0761887    2.02660  2.39%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.02660    0   37    2.07619    2.02660  2.39%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.02660    0   37    2.07619    2.02660  2.39%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.02660    0   37    2.07619    2.02660  2.39%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     0    2.02660    0   36    2.07619    2.02660  2.39%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H    0     0                       2.0717477    2.02660  2.18%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0     2    2.02660    0   36    2.07175    2.02660  2.18%     -    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "*  130    51              18       2.0661170    2.03162  1.67%   5.8    0s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  4471   882    2.04410   27   19    2.06612    2.04410  1.07%   5.1    5s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " 10202  1225     cutoff   29         2.06612    2.05415  0.58%   4.8   10s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " 16347   816    2.06422   32   18    2.06612    2.06032  0.28%   5.1   15s\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cutting planes:\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Implied bound: 5\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  MIR: 12\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Flow cover: 2\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Explored 19703 nodes (99888 simplex iterations) in 17.45 seconds (26.63 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 5: 2.06612 2.07175 2.07619 ... 21.1319\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.066116973868e+00, best bound 2.065910672679e+00, gap 0.0100%\n"
     ]
    }
   ],
   "source": [
    "m.optimize()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c30c2994",
   "metadata": {},
   "source": [
    "Display basic solution data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "57b61a72",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:58.603517Z",
     "iopub.status.busy": "2025-01-31T10:03:58.603200Z",
     "iopub.status.idle": "2025-01-31T10:03:58.609370Z",
     "shell.execute_reply": "2025-01-31T10:03:58.608758Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Minimum Risk:     2.066117\n",
      "Expected return:  0.250000\n",
      "Solution time:    17.46 seconds\n",
      "\n",
      "Number of trades: 15.0\n",
      "\n",
      "KR      0.040359\n",
      "PGR     0.051136\n",
      "CME     0.049374\n",
      "ODFL    0.044432\n",
      "KDP     0.087797\n",
      "CLX     0.073365\n",
      "SJM     0.060471\n",
      "LLY     0.104751\n",
      "DPZ     0.058761\n",
      "MRK     0.073922\n",
      "ED      0.110132\n",
      "TMUS    0.047234\n",
      "WM      0.073017\n",
      "TTWO    0.047324\n",
      "WMT     0.077925\n",
      "Name: Position, dtype: float64\n"
     ]
    }
   ],
   "source": [
    "print(f\"Minimum Risk:     {m.ObjVal:.6f}\")\n",
    "print(f\"Expected return:  {mu @ x.X:.6f}\")\n",
    "print(f\"Solution time:    {m.Runtime:.2f} seconds\\n\")\n",
    "print(f\"Number of trades: {sum(b.X)}\\n\")\n",
    "\n",
    "# Print investments (with non-negligible value, i.e. >1e-5)\n",
    "positions = pd.Series(name=\"Position\", data=x.X, index=mu.index)\n",
    "print(positions[positions > 1e-5])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d4dd0cf",
   "metadata": {},
   "source": [
    "## Comparison with the unconstrained portfolio\n",
    "\n",
    "We can also compute the portfolio without the cardinality constraint and compare the resulting portfolios."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "03efa769",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-01-31T10:03:58.611154Z",
     "iopub.status.busy": "2025-01-31T10:03:58.610945Z",
     "iopub.status.idle": "2025-01-31T10:03:58.968350Z",
     "shell.execute_reply": "2025-01-31T10:03:58.967658Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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qtd81nVy8uRJ2rZti7m5OU5OTnz++edkZmZmK+PpOVqFuX/t2bOH7t27U7VqVbRaLc7OzowcOVL9YzUvT95fIyIi6N69OwA+Pj56946AgAAqVKhAWlpatjL+97//4enpme++CnKPLcy9ryC/f7dt20bLli2xsbHBysoKT09PPvzwQ+DxOX7llVcACAoKUo8363pv06YNderU4ejRo7Ru3RoLCwt12/Xr19OxY0cqV66MVqulevXqfPbZZ2RkZOjt/+lruKDf+YJ+13JT4n9Ourq60qxZM3766SdeffVVAH777TcSEhLo2bNnoeYWvf3227i5uTFlyhSOHTvG4sWLqVixItOmTct322HDhuHg4MCnn37KwYMH+e6777CxsWH//v1UrVqVyZMn8+uvvzJ9+nTq1KlDv379nul4MzIyePXVV2ndujVffvklP/74I0OHDsXS0pKPPvoIf39/3nzzTRYuXEi/fv1o1qwZbm5uuZbXunVrnJycWLZsmd4vNnjcK2hhYUGXLl0AWLBgAV5eXrz++uuYmJiwceNGhgwZQmZmJiEhIXrbnj17ll69ejFo0CAGDhyY6xf30qVLrFu3ju7du+Pm5sbff//Nt99+i7e3N6dOnaJy5cp6+adOnYqRkRHvv/8+CQkJfPnll/j7+xMTE6Pm2bZtG506dcLR0ZH33nsPBwcHTp8+zaZNm3jvvfeAxzfMFi1aUKVKFcaNG4elpSU///wzXbp0YfXq1XTt2jXfn8X333/PgwcPCAkJISUlha+//pq2bdty4sQJKlWqBMD27dt59dVXqVatGhMnTiQ5OZm5c+fSokULjh07lu0XT/fu3alRowaTJ09GURQaNGjAjRs32LZtGz/88IOar1atWvzwww+MHDkSJycnRo8eDYC9vT3Jycm0adOGCxcuMHToUNzc3Fi5ciWBgYHcv39fPQcFNXHiRD799FPat2/P4MGDOXv2LAsWLODw4cPs27ePMmXKkJqaiq+vLzqdTv0u/PXXX2zatIn79+9jbW2dY9mtWrUiMzOTvXv3qnMp9+zZg5GREXv27FHz/f777yQlJdG6descy3nzzTc5d+4cP/30E7NmzaJChQrq+ciyd+9e1qxZw5AhQyhbtixz5syhW7duXL16FTs7u1yPPzExkcWLF9OrVy8GDhzIgwcPCAsLw9fXl0OHDlG/fn29/MuW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9uyhcuXKZGZmltg5y0lh73VFac+ePbz++uu0bt2a+fPn4+joSJkyZQgPD8/xoaHi+h7mdz4zMjLo0KEDd+/eZezYsdSsWRNLS0v++usvAgMDn7knJye1a9emUaNGLF26lH79+rF06VJMTU31RkYMKb9zY25uzu7du4mKiuKXX35h8+bNrFixgrZt27J169YCPU2b08/1/v37eHt7U65cOSZNmkT16tUxMzPj2LFjjB07tkDnvLi/86WmodW1a1cGDRrEwYMHWbFiRUlXp8CyWr5PP8FVmF6HotCrVy/Gjx/PsmXLcHFxISMjQ69LfOPGjeh0OjZs2KDXen/6yavCWrVqFT4+PoSFheml379/X53QXBhZQ0N//vkn7du3zzFPtWrVgMfDabnlKYisIZonnTt3Tp3k6eLiAjz+S/FpZ86coUKFClhaWua7n8IO/bi4uHD8+HEyMzP1erWyusCz6lXQsuDxMWSdN3j8JN7ly5eznb+6detSt25dPv74Y/bv30+LFi1YuHAhn3/+ea77aNy4MaampuzZs4c9e/aoTw+2bt2aRYsWsWPHDvVzXoorJMWqVauoVq2aGuA3S34ThnOTdU5zun5yulZyktWA2rZtG4cPH2bcuHHA43O0YMECKleujKWlJY0aNcqznOc9Z4W5xm1tbXMMJpvTva4w9apevToxMTGkpaXlGtpg9erVmJmZsWXLFr3H88PDwwu8HxcXl+f6mRXEiRMnOHfuHJGRkXoPTD35VH1h5Hce+/Xrx6hRo7h58ybLli2jY8eOekNgOSnIPbao7n1PMzIyol27drRr146vvvqKyZMn89FHHxEVFUX79u2f6XqOjo7mzp07rFmzRu8ec/ny5UKXlZfn+a6ViqFDACsrKxYsWMDEiRPp3LlzSVenwFxcXDA2NlbnW2SZP3++QetRtWpVWrVqxYoVK1i6dClubm56T2tktdifbKEnJCQU6kaVE2Nj42yt/pUrVxZojlROGjZsiJubG7Nnz852U8/aT8WKFWnTpg3ffvstN2/ezFbGP//8U6B9rVu3Tq+ehw4dIiYmRn361dHRkfr16xMZGalXlz///JOtW7fy2muvFWg/WTekgkY8f+2114iPj9f7gyM9PZ25c+diZWWlDkMURPv27TE1NWXOnDl6P6ewsDASEhLUp7USExOzxbKrW7cuRkZG6HS6PPdh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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# remove cardinality constraint\n",
    "m.remove(cardinality_constr)\n",
    "m.params.OutputFlag = 0\n",
    "m.optimize()\n",
    "\n",
    "# retrieve and display solution data\n",
    "positions_unconstr = pd.Series(name=\"Position\", data=x.X, index=mu.index)\n",
    "mask = (positions > 1e-5) | (positions_unconstr > 1e-5)\n",
    "df = pd.DataFrame(\n",
    "    index=positions[mask].index,\n",
    "    data={\n",
    "        \"at most 15 assets\": positions,\n",
    "        \"unconstrained\": positions_unconstr,\n",
    "    },\n",
    ").sort_values(by=[\"at most 15 assets\", \"unconstrained\"], ascending=True)\n",
    "\n",
    "axs = df.plot.barh(color=[\"#0b1a3c\", \"#dd2113\"])\n",
    "axs.set_xlabel(\"Fraction of investment sum\")\n",
    "plt.title(\"Minimum Variance portfolios with and without cardinality constraint\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7832aff7",
   "metadata": {},
   "source": [
    "## Takeaways\n",
    "* Cardinality constraints can be modeled using binary decision variables.\n",
    "* This already leads to non-trivial combinatorial optimization problems, which can be solved using Gurobi."
   ]
  }
 ],
 "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
}