diff --git a/docs/notebooks/Optimization.ipynb b/docs/notebooks/Optimization.ipynb new file mode 100644 index 00000000..75960782 --- /dev/null +++ b/docs/notebooks/Optimization.ipynb @@ -0,0 +1,392 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Introduction to Optimization in GerryChain\n", + "\n", + "This notebook walks through how to use the SingleMetricOptimizer class (as well as its Gingleator subclass) in order to perfrom heuristic optimization runs in GerryChain.\n", + "\n", + "There are 3 heuristic optimization methods whose use is shown in this notebook:\n", + "* **Short Bursts**: chaining together small neutral explorers ([More reading about short bursts here](https://arxiv.org/abs/2011.02288))\n", + "* **Simulated Annealing**: vary the probability of accepting worse plans over time wrt a temperature parameter $\\beta$.\n", + "* **Tilted runs**: accept worse plans with a fixed probability $p$\n", + "\n", + "## When do we want to use Heuristic Optimization?\n", + "\n", + "While sampling naively with GerryChain can give us an understanding of the neutral baseline for a state, there are often cases where we want to find plans with properties that are rare to encounter in a neutral run. Many states have laws/guidelines that state that plans should be as compact as feasibly possible, maximize preservation of political boundaries and/or communities of interest, some even look to minimize double bunking of incumbents or seek proportionality/competitiveness in contests. Heuristic optimization methods can be used to find example plans with these properties and to explore the trade-offs between them." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "from gerrychain import (GeographicPartition, Partition, Graph, MarkovChain,\n", + " proposals, updaters, constraints, accept, Election)\n", + "# from gerrychain.proposals import ReCom\n", + "from gerrychain.optimization import SingleMetricOptimizer, Gingleator\n", + "from gerrychain.tree import recursive_seed_part\n", + "# from gerrychain.updaters import Tally\n", + "from functools import partial\n", + "import pandas as pd\n", + "import json\n", + "import requests\n", + "from networkx.readwrite import json_graph\n", + "import matplotlib.pyplot as plt\n", + "from tqdm import tqdm\n", + "import numpy as np" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "response = json.loads(requests.get(\"https://people.csail.mit.edu/ddeford/BG/BG_05.json\").text)\n", + "graph = Graph(json_graph.adjacency_graph(response))" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "POPCOL = \"TOTPOP\"\n", + "SEN_DISTS = 35\n", + "EPS = 0.02\n", + "TOTPOP = sum(graph.nodes()[n][POPCOL] for n in graph.nodes())" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "sddict = recursive_seed_part(graph, range(SEN_DISTS), TOTPOP/SEN_DISTS, POPCOL, EPS)" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [], + "source": [ + "chain_updaters = {\n", + " \"population\": updaters.Tally(POPCOL, alias=\"population\"),\n", + " \"VAP\": updaters.Tally(\"VAP\"),\n", + " \"BVAP\": updaters.Tally(\"BVAP\")\n", + " }\n", + "part = Partition(graph, sddict, chain_updaters)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "proposal = partial(proposals.recom,\n", + " pop_col=POPCOL,\n", + " pop_target=TOTPOP/SEN_DISTS,\n", + " epsilon=EPS,\n", + " node_repeats=1)\n", + "cons = constraints.within_percent_of_ideal_population(part, EPS)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Optimizing for Gingles Districts\n", + "\n", + "Named for the Supreme Court case _Thornburg v. Gingles_, which created their precedent as one of the litmus tests in bringing forth a VRA court case, *Gingles' Districts* are districts that are 50% + 1 of a minority population subgroup (more colloquially called majority-minority districts). It is common to seek plans with greater/maximal numbers of gingles districts to understand the landscape of the state space." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "gingles = Gingleator(proposal, cons, part, \n", + " minority_pop_col=\"BVAP\", total_pop_col=\"VAP\",\n", + " score_function=Gingleator.reward_partial_dist)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "total_steps = 10000" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|█████████████████████████████████████| 10000/10000 [06:16<00:00, 26.56it/s]\n" + ] + } + ], + "source": [ + "max_scores_sb = np.zeros(total_steps)\n", + "scores_sb = np.zeros(total_steps)\n", + "for i, part in enumerate(gingles.short_bursts(10, 1000, with_progress_bar=True)):\n", + " max_scores_sb[i] = gingles.best_score\n", + " scores_sb[i] = gingles.score(part)" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|█████████████████████████████████████| 10000/10000 [07:48<00:00, 21.33it/s]\n" + ] + } + ], + "source": [ + "max_scores_anneal = np.zeros(total_steps)\n", + "scores_anneal = np.zeros(total_steps)\n", + "for i, part in enumerate(gingles.simulated_annealing(total_steps, gingles.jumpcycle_beta_function(1000, 4000),\n", + " beta_magnitude=500, with_progress_bar=True)):\n", + " max_scores_anneal[i] = gingles.best_score\n", + " scores_anneal[i] = gingles.score(part)" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|█████████████████████████████████████| 10000/10000 [07:41<00:00, 21.65it/s]\n" + ] + } + ], + "source": [ + "max_scores_tilt = np.zeros(total_steps)\n", + "scores_tilt = np.zeros(total_steps)\n", + "for i, part in enumerate(gingles.tilted_run(total_steps, 0.125, with_progress_bar=True)):\n", + " max_scores_tilt[i] = gingles.best_score\n", + " scores_tilt[i] = gingles.score(part)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAtkAAAF8CAYAAAAadKdeAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/YYfK9AAAACXBIWXMAAAsTAAALEwEAmpwYAABL0ElEQVR4nO3deXxU9fX/8dchCfsqoCCLYN0QwSBRUFxwR0W0QovWVmm1dlPbftva2lq1tm6tXbRq/VK1oOXrhmv9udQNFatQAlERUVFRNlllky0h5/fHvQmTMFluuJPZ3s/HI4+Zufcz955hGDg5c+7nY+6OiIiIiIjEp0W6AxARERERyTVKskVEREREYqYkW0REREQkZkqyRURERERipiRbRERERCRmSrJFRERERGJWmO4AUqFbt27er1+/dIchIiIiIjmutLR0lbt3r709J5Psfv36MWvWrHSHISIiIiI5zsw+SbY9I9pFzKzAzOaY2ZNJ9k0ws5VmVhb+XJiOGEVEREREGitTKtk/BN4FOtax/wF3v7gZ4xERERERabK0V7LNrDdwGnBnumMREREREYlDJlSy/wJcBnSoZ8xYMzsaeB/4sbsvqj3AzC4CLgLo27fvTgcoLy9n8eLFbNmyJY6YJYe1bt2a3r17U1RUlO5QREREJEulNck2s9HACncvNbORdQz7F3Cfu281s+8Ak4Hjag9y94nARICSkhKvvX/x4sV06NCBfv36YWZxvQTJMe7O6tWrWbx4Mf379093OCIiIpKl0t0uMgIYY2YLgfuB48zsn4kD3H21u28NH94JDG3KibZs2ULXrl2VYEu9zIyuXbvqGw8RERHZJWlNst39cnfv7e79gLOBF93964ljzKxnwsMxBBdINokSbGkM/T0RERGRXZXuSnZSZnaNmY0JH15qZu+Y2ZvApcCE9EW2a6699loGDhzI4MGDKS4uZsaMGUAwr/eqVauafNyysjKeeuqppPumTZtGp06dKC4uZvDgwZxwwgmsWLGiyedKNGnSJJYuXRrLsURERERyScYk2e4+zd1Hh/evdPcnwvuXu/tAdz/Y3Y919/npjbRpXn/9dZ588klmz57NW2+9xfPPP0+fPn12+bgVFRX1JtkARx11FGVlZbz11lsceuih3HbbbY0+vrtTWVmZdJ+SbBEREZHkMibJznXLli2jW7dutGrVCoBu3bqx5557Vu//61//yiGHHMKgQYOYPz/4PWLNmjWceeaZDB48mOHDh/PWW28BcPXVV/ONb3yDESNG8I1vfIMrr7ySBx54gOLiYh544IE6Y3B3NmzYQJcuXaqPc9NNN1XvP+igg1i4cCELFy5k//3357zzzuOggw5i0aJFTJgwgYMOOohBgwbx5z//malTpzJr1izOPfdciouL2bx5M7/4xS848MADGTx4MD/96U9j/zMUERERyRaZMIVfs/vNv95h3tL1sR7zwD07ctXpA+vcf9JJJ3HNNdew3377ccIJJzB+/HiOOeaY6v3dunVj9uzZ3H777dx0003ceeedXHXVVQwZMoTHHnuMF198kfPOO4+ysjIA5s2bx/Tp02nTpg2TJk1i1qxZ3HrrrUnP/eqrr1JcXMzq1atp164d1113XYOv54MPPmDy5MkMHz6c0tJSlixZwty5cwFYu3YtnTt35tZbb+Wmm26ipKSE1atX8+ijjzJ//nzMjLVr1zb+D09EREQkx+Rlkp0O7du3p7S0lFdffZWXXnqJ8ePHc8MNNzBhwgQAzjrrLACGDh3KI488AsD06dN5+OGHATjuuONYvXo169cHvxyMGTOGNm3aNOrcRx11FE8+GaxYf+ONN3LZZZdxxx131Pucvfbai+HDhwOw995789FHH3HJJZdw2mmncdJJJ+00vlOnTrRu3ZoLLriA0aNHM3r06EbFJiIiUtumbRVsr9xpNt4Gba90VmzYitfx1IrKSlZt3EZlXQMyhFWWN/m5LTevomD7phijyR4HDxpC69at0x1GtbxMsuurOKdSQUEBI0eOZOTIkQwaNIjJkydXJ9lVbSQFBQVUVFQ0eKx27do1KYYxY8YwduxYAAoLC2v0WydOW5d4/C5duvDmm2/y7LPPcscdd/Dggw9y99131zhuYWEhM2fO5IUXXmDq1KnceuutvPjii02KUURE4udhYpmYX3qtfYnbEsd6wtZk+WnNY9Z9nmfnfsajc5ZQ6Y57MDa43TFo6brNLP58c6NfVzZoxTYmFv2J3W0tVS/UAMPDnx33O9jmcJxE9VmPUnr02SfdYVTLyyQ7Hd577z1atGjBvvvuCwQzguy11171Pueoo45iypQp/PrXv2batGl069aNjh077jSuQ4cObNiwoVFxTJ8+nS996UtAMKtJVYV79uzZfPzxx0mfs2rVKlq2bMnYsWPZf//9+frXv77TeTdu3MimTZs49dRTGTFiBHvvvXej4hGRXVS5HT5fGGY0XuuWJNsSbiHJPurZ5+CVUF6zSrZpWwVrvthWY1vtPMwqttBl7iSwFnWO2WlLE4qNTa5PNnDqtZu28cW27U09esptLd/Oxm1hgSaDi7R7AN8FOrapuaJu7YlTrRN0aduySecoLGhBQT1TsRYWWL37U8G2b6b9irf4ovsQytt0BwvT6uo4gsfBH4Sxok03Klp3a9K5vKAl5W33SDh2/tiz2x7pDqEGJdnNZOPGjVxyySWsXbuWwsJC9tlnHyZOnFjvc66++mq+9a1vMXjwYNq2bcvkyZOTjjv22GO54YYbKC4u5vLLL2f8+PE19lf1ZLs7nTp14s477wRg7Nix3HPPPQwcOJBhw4ax3377JT3+kiVL+OY3v1ld9b7++usBmDBhAt/97ndp06YNTz/9NGeccQZbtmzB3fnTn/4U6c9HJE6bt23n5fdXsLWiksfmLKl3bEP5SEPfKte32xv5lXQL386e5Z9i4dFO33A/vbd9RHlFJe6VCVWuHdUuwvt9LJ4pOXdF2/CnMZb5biz2piUPmaBNUUG6Q0iqEOhSBJ0bSkytxk2TWZJ7yQ6a7DwdWhfSrmWq0496P5kpPncShS3hS8fR7sw7oENmJYK1bdu+jUpPPqtYpisqaNovZqlijf1PIJuUlJT4rFmzamx79913GTBgQJoikmyjvy/Z7b6Zn3L5I29XP+7ariW9utR9DUN9CUeBV1Bg9VcwE5/fwis5fuvztAwXqm0omWlBJadtfoIulZ/vtG9Gm6No36qouuqFJabXVZUw2FLQgaXtBu7YV1UlS4jQq58fROTsqKBVVbwS03iqt1W9iqrtsK1F24TnQ0EB9OzUhnataiZOtV97ZWFrNnbav9bWmqPMgl9OVm9dyoINZWwsX7vTn0tDBbqku632w+hp5h4dW9E25cmhSHqULi9lwdoFrNy8Mt2hNNlz456jR7sezX5eMyt195La2/WvhYjknC3lQVL8yPePoFu7VvTZrU3TVvLc9gX8eSBs3jkBjpdBz4PhqHDqSzPodyTD2nRJ8Xkz09MfP80NpZelOwyRvNOhZQfG7z+enu16Njw4A7Uvap/uEGpQki0iOafqC7ovdWtPp7ZF9Q+uz5Z1QYI94HTotVORom4t20Hx12r0H9erRSEU7EKcOWb5F8sB+Muxf+Ho3kc3qeosItEVWEHTChKSlJJsEZG6VGXr+5wIQ89Pbyx5ZMnGoI9+ZO+RFLTIzB5oEZGGaMVHEck51b3IKshkpU0VwewlSrBFJJspyRYRqVOYruvr02bVsqAlnVt1TncYIiK7REm2iOScqlmTlBtnJ3ensIW6GUUkuynJbkbXXnstAwcOZPDgwRQXFzNjxgwALrzwQubNmxfLOfr168eqVavqHXPddddFPu6kSZO4+OKL69x/5plnVi/D3pyuvvpqbrrpJgCuvPJKnn/++WaPQfKBsvXmposdRSTbqVTQTF5//XWefPJJZs+eTatWrVi1ahXbtgUrpFUtDtNcrrvuOn75y1/Gdry1a9dSWlpK+/bt+eijj9K22uM111yTlvNK5trlNC0H1xEQEZHmoUp2M1m2bBndunWjVatWAHTr1o0999wTgJEjR1K1eE779u352c9+xsCBAznhhBOYOXMmI0eOZO+99+aJJ54Adq4qjx49mmnTpu10zjPPPJOhQ4cycODA6tUlf/GLX7B582aKi4s599xzAfjnP//JYYcdRnFxMd/5znfYvj2YY/gf//gH++23H4cddhivvfZana/tkUce4fTTT+fss8/m/vvvr94+YcIELr30Uo444gj23ntvpk6dCsC0adMYOXIk48aN44ADDuDcc8+t/nq/tLSUY445hqFDh3LyySezbNkyAP7+979z6KGHcvDBBzN27Fg2bdq0UxwTJkyoPke/fv246qqrOOSQQxg0aBDz588HYOXKlZx44okMHDiQCy+8kL322qvByr+I+k6anyrZIpLt8rOS/fQv4LO3Gx4XRY9BcMoNde4+6aSTuOaaa9hvv/044YQTGD9+PMccc8xO47744guOO+44/vCHP/DlL3+ZK664gueee4558+Zx/vnnM2bMmEaHdPfdd7PbbruxefNmDj30UMaOHcsNN9zArbfeSllZGRCsbPjAAw/w2muvUVRUxPe//32mTJnCiSeeyFVXXUVpaSmdOnXi2GOPZciQIUnPc99993HllVeyxx57MHbs2BpV8mXLljF9+nTmz5/PmDFjGDduHABz5szhnXfeYc8992TEiBG89tprDBs2jEsuuYTHH3+c7t2788ADD/CrX/2Ku+++m7POOotvf/vbAFxxxRXcddddXHLJJfW+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\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "fig, ax = plt.subplots(figsize=(12,6))\n", + "plt.plot(max_scores_sb, label=\"Short Bursts\")\n", + "plt.plot(max_scores_anneal, label=\"Simulated Annealing\")\n", + "plt.plot(max_scores_tilt, label=\"Tilted Run\")\n", + "plt.xlabel(\"Steps\", fontsize=20)\n", + "plt.ylabel(\"Max Score Observered\", fontsize=20)\n", + "plt.legend()\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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Knr06AHA9OnTCR+eU1JSwi9+8QtGjhzJoYceyqeffsr06dMZMGAAL7zwApCoVZ41axbz5s1LSPP4449nwoQJjBw5MnK65FVXXUVDQwM1NTWcfvrpAPz73/9mv/32o6amhvPPP59AQPGK8I9//IMhQ4aw33778eGHH2q+2zPPPMOxxx7LKaecwn//+9/I9blz53LppZdywAEHMGDAAJ566ikA5s2bx/Tp0zn55JMZNmwYp59+OuFDkRYuXMjBBx/MhAkTOOKII9i0aRMAf//735k0aRJjx47lpJNOor6+PiEfc+fOjaTRr18/rr/+esaPH8/o0aNZvlxx+7Rt2zYOO+wwRo4cybnnnkvfvn1Tav4dHDr60GOHiCQRKTaD5ZJgZn1ejG9KsyDNLBWpVYfeZdsmO5ps9wnqNtkWRCxzqd3lPx1Tk/3KVbD5S2vj7DYajrpd8/bhhx/OTTfdxJAhQzj00EOZM2cOBx98cEK4ffv2MXPmTH73u99xwgkncO211/LGG2/w1VdfcdZZZzF79mzdWXrooYfo3LkzDQ0NTJo0iZNOOonbb7+de+65h8WLFwPKyYaPP/44H374IV6vl4suuohHH32Uww47jOuvv56FCxdSVlbGjBkzGDdunGo6jz32GNdddx1du3blpJNOitGSb9q0iQ8++IDly5cze/ZsTj75ZAA+//xzli1bRo8ePZg6dSoffvghkydP5pJLLuH555+nurqaxx9/nF/96lc89NBDnHjiifzkJz8B4Nprr+XBBx/kkksuSfr+VVVVLFq0iL/85S/ceeedPPDAA9x4443MnDmTq6++mldffZUHH3xQd3k6dDys9gjg4NCRCAt97UWTnc5btG2itgidZk4O2aVjCtlZoKSkhIULF/L+++/zzjvvMGfOHG6//Xbmzp0bE87n83HkkUcCMHr0aPx+P16vl9GjR7NmzRpDad511108++yzAKxbt44VK1ZQWRl7sMNbb73FwoULmTRpEgANDQ106dKFTz75hOnTp1NdXQ3AnDlz+PbbxEMftmzZwooVKzjwwAMRQuD1elm6dCmjRo0CFG26y+VixIgRbNnSdmDGfvvtR69evQCoqalhzZo1lJeXs3TpUg47TDmlLhAI0L27cgTz0qVLufbaa9m9ezd1dXUcccQRKd//xBNPBGDChAk888wzAHzwwQeRMjnyyCOp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\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "fig, ax = plt.subplots(figsize=(12,6))\n", + "plt.plot(scores_sb, label=\"Short Bursts\")\n", + "plt.plot(scores_anneal, label=\"Simulated Annealing\")\n", + "plt.plot(scores_tilt, label=\"Tilted Run\")\n", + "plt.xlabel(\"Steps\", fontsize=20)\n", + "plt.ylabel(\"Score Observered\", fontsize=20)\n", + "plt.legend()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Optimizing for Compactness\n", + "\n", + "Another metric we may seek to optimize over is compactness. Below we look at minimizing the number of cut edges in a plan." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [], + "source": [ + "num_cut_edges = lambda p: len(p[\"cut_edges\"])\n", + "optimizer = SingleMetricOptimizer(proposal, cons, part, num_cut_edges, maximize=False)" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|█████████████████████████████████████| 10000/10000 [05:20<00:00, 31.20it/s]\n" + ] + } + ], + "source": [ + "total_steps = 10000\n", + "min_scores_sb = np.zeros(total_steps)\n", + "for i, part in enumerate(optimizer.short_bursts(5, 2000, with_progress_bar=True)):\n", + " min_scores_sb[i] = optimizer.best_score" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|█████████████████████████████████████| 10000/10000 [06:31<00:00, 25.57it/s]\n" + ] + } + ], + "source": [ + "min_scores_anneal = np.zeros(total_steps)\n", + "for i, part in enumerate(optimizer.simulated_annealing(total_steps, optimizer.jumpcycle_beta_function(200, 800),\n", + " beta_magnitude=1, with_progress_bar=True)):\n", + " min_scores_anneal[i] = optimizer.best_score" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|█████████████████████████████████████| 10000/10000 [06:05<00:00, 27.34it/s]\n" + ] + } + ], + "source": [ + "min_scores_tilt = np.zeros(total_steps)\n", + "for i, part in enumerate(optimizer.tilted_run(total_steps, p=0.125, with_progress_bar=True)):\n", + " min_scores_tilt[i] = optimizer.best_score" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAtwAAAF8CAYAAAD8XWwaAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/YYfK9AAAACXBIWXMAAAsTAAALEwEAmpwYAABmNElEQVR4nO3dd5xU1fnH8c8zswWW3jsCgkhfYAEVDdhL7BrLz4bRmGhsMZqoMbZEYxJNolFjjD12sffYUEFFARdEmggoIL3Xrc/vj3sXFtgyszuzs7t836/Xvu7Mueee+yzD6sPZ555j7o6IiIiIiCRHJNUBiIiIiIjUZ0q4RURERESSSAm3iIiIiEgSKeEWEREREUkiJdwiIiIiIkmkhFtEREREJInSUh1AsrVu3dq7deuW6jBEREREpJ6bPHnySndvs3N7vU+4u3XrxqRJk1IdhoiIiIjUc2b2XVntKikREREREUkiJdwiIiIiIkmkhFtEREREJInqfQ23iIiISCwKCgpYtGgRW7duTXUoUss1aNCAzp07k56eHlN/JdwiIiIiwKJFi2jSpAndunXDzFIdjtRS7s6qVatYtGgR3bt3j+malJeUmNllZjbdzL42s8vDthvNbLGZ5YZfR5Xqf42ZzTWz2WZ2eMoCFxERkXpl69attGrVSsm2VMjMaNWqVVy/CUnpDLeZ9Qd+BgwH8oG3zOy18PTf3f32nfr3BU4D+gEdgXfNbC93L6rBsEVERKSeUrItsYj370mqZ7j7ABPdfbO7FwIfAidW0P844Gl3z3P3+cBcgmRdREREpM675ZZb6NevHwMHDiQ7O5uJEycCwb4iK1eurPK4ubm5vPHGG2WeGzduHM2aNSM7O5uBAwdyyCGHsHz58irfq7RHHnmEH374ISFj1WWpTrinAweYWSszywKOArqE5y42s2lm9pCZtQjbOgELS12/KGwTERERqdM+/fRTXnvtNaZMmcK0adN499136dKlS+UXVqKwsLDChBvggAMOIDc3l2nTpjFs2DDuueeemMd3d4qLi8s8p4Q7kNKE291nAn8G/ge8BeQCRcC/gD2BbGAJcEc845rZBWY2ycwmrVixIpEhi4iIiCTFkiVLaN26NZmZmQC0bt2ajh07bjv/z3/+kyFDhjBgwABmzZoFwOrVqzn++OMZOHAg++yzD9OmTQPgxhtv5KyzzmLkyJGcddZZXH/99TzzzDNkZ2fzzDPPlBuDu7NhwwZatGixbZzbb99e4du/f38WLFjAggUL6N27N2effTb9+/dn4cKFjBkzhv79+zNgwAD+/ve/M3bsWCZNmsQZZ5xBdnY2W7Zs4eqrr6Zv374MHDiQK6+8MuF/hrVVylcpcfcHgQcBzOxWYJG7Lys5b2b/AUrquhezfQYcoHPYtvOY9wP3A+Tk5HhyIhcREZH66qZXv2bGD+sTOmbfjk254Zh+5Z4/7LDDuPnmm9lrr7045JBDOPXUUxk1atS2861bt2bKlCnce++93H777TzwwAPccMMNDB48mJdeeon333+fs88+m9zcXABmzJjB+PHjadiwIY888giTJk3i7rvvLvPeH3/8MdnZ2axatYpGjRpx6623Vvr9fPPNNzz66KPss88+TJ48mcWLFzN9+nQA1q5dS/Pmzbn77ru5/fbbycnJYdWqVbz44ovMmjULM2Pt2rWx/+HVcakuKcHM2obHrgT120+aWYdSXU4gKD0BeAU4zcwyzaw70Av4vCbjjcXaDSv575t/ZZFm10VERCRGjRs3ZvLkydx///20adOGU089lUceeWTb+RNPDB5zGzp0KAsWLABg/PjxnHXWWQAcdNBBrFq1ivXrg38oHHvssTRs2DCme5eUlCxcuJBzzz2X3/zmN5Ves8cee7DPPvsA0KNHD+bNm8cll1zCW2+9RdOmTXfp36xZMxo0aMB5553HCy+8QFZWVkyx1Qcpn+EGnjezVkAB8Et3X2tm/zSzbMCBBcDPAdz9azN7FpgBFIb9a90KJfMXfcVflj/GlLFT+fuFj6c6HBEREYlTRTPRyRSNRhk9ejSjR49mwIABPProo4wZMwZgW6lJNBqlsLCw0rEaNWpUpRiOPfZYTjrpJADS0tJ2qM8uvRRe6fFbtGjB1KlTefvtt7nvvvt49tlneeihh3YYNy0tjc8//5z33nuPsWPHcvfdd/P+++9XKca6JuUJt7sfUEbbWRX0vwW4JalBVVPXjr0ByCtcl+JIREREpK6YPXs2kUiEXr16AcHKInvssUeF1xxwwAE88cQT/P73v2fcuHG0bt26zNnlJk2asGHDhpjiGD9+PHvuuScQrI7y2mtBZe+UKVOYP39+mdesXLmSjIwMTjrpJHr37s2ZZ565y303btzI5s2bOeqooxg5ciQ9evSIKZ76IOUJd33UvEm78FXl//oUERERgSAhveSSS1i7di1paWn07NmT+++/v8JrbrzxRn76058ycOBAsrKyePTRR8vsd+CBB3LbbbeRnZ3NNddcw6mnnrrD+ZIabnenWbNmPPDAAwCcdNJJPPbYY/Tr148RI0aw1157lTn+4sWLOffcc7fNhv/pT38CYMyYMfziF7+gYcOGvPnmmxx33HFs3boVd+dvf/tbXH8+dZm51+9nCnNycnzSpEk1ft+Bj/Rn/w3tuPeS92r83iIiIhK/mTNn0qdPn1SHIXVEWX9fzGyyu+fs3DflD03WV+lAsMKhiIiIiOzOlHAnSdRBJSUiIiIiooQ7SdIwOvsiyIvtAQURERERqZ+UcCdJhAgFBiz6ItWhiIiIiEgKKeFOksJIYwrMKF6cm+pQRERERCSFlHAniVsGxRhb87ZW3llERERE6i0l3EmSmZ5OEVCQn5fqUERERKSOuOWWW+jXrx8DBw4kOzubiRMnAnD++eczY8aMhNyjW7durFy5ssI+t956a9zjPvLII1x88cXlnj/++OO3bQVfk2688UZuv/12AK6//nrefffdGo9BG98kSdSiFFiEwoL8VIciIiIidcCnn37Ka6+9xpQpU8jMzGTlypXk5wd5RMlGNDXl1ltv5dprr03YeGvXrmXy5Mk0btyYefPmpWyXyZtvvjkl99UMd5KkRaIUY7wwaQHfrtiY6nBERESklluyZAmtW7cmMzMTgNatW9OxY0cARo8eTclGfo0bN+aqq66iX79+HHLIIXz++eeMHj2aHj168MorrwC7zjYfffTRjBs3bpd7Hn/88QwdOpR+/fpt29Xy6quvZsuWLWRnZ3PGGWcA8PjjjzN8+HCys7P5+c9/TlFRsNfIww8/zF577cXw4cOZMGFCud/bCy+8wDHHHMNpp53G008/va19zJgxXHrppey333706NGDsWPHAjBu3DhGjx7NySefzN57780ZZ5xByWaNkydPZtSoUQwdOpTDDz+cJUuWAPCf//yHYcOGMWjQIE466SQ2b968SxxjxozZdo9u3bpxww03MGTIEAYMGMCsWbMAWLFiBYceeij9+vXj/PPPZ4899qj0NwKVKXeG28wequKY7u7nVfHaeiMrI40ii5BGEQtWbmLPNo1THZKIiIjE6s2rYelXiR2z/QA48rZyTx922GHcfPPN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\n", + "text/plain": [ + "
" + ] + }, + "metadata": { + "needs_background": "light" + }, + "output_type": "display_data" + } + ], + "source": [ + "fig, ax = plt.subplots(figsize=(12,6))\n", + "plt.plot(min_scores_sb, label=\"Short Bursts\")\n", + "plt.plot(min_scores_anneal, label=\"Simulated Annealing\")\n", + "plt.plot(min_scores_tilt, label=\"Tilted Run\")\n", + "plt.xlabel(\"Steps\", fontsize=20)\n", + "plt.ylabel(\"Min #CutEdges Observered\", fontsize=20)\n", + "plt.legend()\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "interpreter": { + "hash": "de0b2e8f3822c864e297dc34a9420a5549c338b59d7a373e92a79db0315964f9" + }, + "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.9.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/gerrychain/optimization/__init__.py b/gerrychain/optimization/__init__.py new file mode 100644 index 00000000..831dd950 --- /dev/null +++ b/gerrychain/optimization/__init__.py @@ -0,0 +1,4 @@ +from .optimization import SingleMetricOptimizer +from .gingleator import Gingleator + +__all__ = ['SingleMetricOptimizer', 'Gingleator'] \ No newline at end of file diff --git a/gerrychain/optimization/gingleator.py b/gerrychain/optimization/gingleator.py new file mode 100755 index 00000000..6b461321 --- /dev/null +++ b/gerrychain/optimization/gingleator.py @@ -0,0 +1,168 @@ +from .optimization import SingleMetricOptimizer + +from functools import partial +import numpy as np +import warnings + + +class Gingleator(SingleMetricOptimizer): + """ + `Gingleator` is a child class of `SingleMetricOptimizer` which can be used to search for plans + with increased numbers of Gingles' districts. + + A gingles district (named for the Supreme Court case Thornburg v. Gingles) is a district that is + majority-minority. aka 50% + 1 of some population subgroup. Demonstrating additional Gingles + districts is one of the litmus tests used in bringing forth a VRA case. + """ + + def __init__(self, proposal, constraints, initial_state, + minority_perc_col=None, threshold=0.5, score_function=None, + minority_pop_col=None, total_pop_col="TOTPOP", + min_perc_column_name="_gingleator_auxiliary_helper_updater_min_perc_col"): + """ + :param `proposal`: Function proposing the next state from the current state. + :param `constraints`: A function with signature ``Partition -> bool`` determining whether + the proposed next state is valid (passes all binary constraints). Usually this is a + :class:`~gerrychain.constraints.Validator` class instance. + :param `initial_state`: Initial :class:`gerrychain.partition.Partition` class. + :param `minority_perc_col`: Which updater is a mapping of district ids to the fraction of + minority population within that district. + :param `threshold`: Beyond which fraction to consider something a "Gingles" + (or opportunity) district. + :param `score_function`: The function to using doing optimization. Should have the + signature ``Partition * str (minority_perc_col) * float (threshold) -> + 'a where 'a is Comparable``. This class implements a few potential choices as class + methods. + :param `minority_pop_col`: If minority_perc_col is defined, the minority population column + with which to compute percentage. + :param `total_pop_col`: If minority_perc_col is defined, the total population column with + which to compute percentage. + :param `min_perc_column_name`: If minority_perc_col is defined, the name to give the created + percentage updater. + """ + if minority_perc_col is None and minority_pop_col is None: + raise ValueError("`minority_perc_col` and `minority_pop_col` cannot both be `None`. \ + Unclear how to compute gingles district.") + elif minority_perc_col is not None and minority_pop_col is not None: + warnings.warn("`minority_perc_col` and `minority_pop_col` are both specified. By \ + default `minority_perc_col` will be used.") + score_function = self.num_opportunity_dists if score_function is None else score_function + + if minority_perc_col is None: + perc_up = {min_perc_column_name: + lambda part: {k: part[minority_pop_col][k] / part[total_pop_col][k] + for k in part.parts.keys()}} + initial_state.updaters.update(perc_up) + minority_perc_col = min_perc_column_name + + score = partial(score_function, minority_perc_col=minority_perc_col, threshold=threshold) + + super().__init__(proposal, constraints, initial_state, score, maximize=True) + + """ + Score Functions + """ + + @classmethod + def num_opportunity_dists(cls, part, minority_perc_col, threshold): + """ + Given a partition, returns the number of opportunity districts. + + :param `part`: Partition to score. + :param `minority_perc_col`: Which updater is a mapping of district ids to the fraction of + minority population within that district. + :param `threshold`: Beyond which fraction to consider something a "Gingles" + (or opportunity) district. + + :rtype int + """ + dist_percs = part[minority_perc_col].values() + return sum(list(map(lambda v: v >= threshold, dist_percs))) + + @classmethod + def reward_partial_dist(cls, part, minority_perc_col, threshold): + """ + Given a partition, returns the number of opportunity districts + the percentage of the next + highest district. + + :param `part`: Partition to score. + :param `minority_perc_col`: Which updater is a mapping of district ids to the fraction of + minority population within that district. + :param `threshold`: Beyond which fraction to consider something a "Gingles" + (or opportunity) district. + + :rtype float + """ + dist_percs = part[minority_perc_col].values() + num_opport_dists = sum(list(map(lambda v: v >= threshold, dist_percs))) + next_dist = max(i for i in dist_percs if i < threshold) + return num_opport_dists + next_dist + + @classmethod + def reward_next_highest_close(cls, part, minority_perc_col, threshold): + """ + Given a partition, returns the number of opportunity districts, if no additional district + is within 10% of reaching the threshold. If one is, the distance that district is from the + threshold is scaled between 0 and 1 and added to the count of opportunity districts. + + :param `part`: Partition to score. + :param `minority_perc_col`: Which updater is a mapping of district ids to the fraction of + minority population within that district. + :param `threshold`: Beyond which fraction to consider something a "Gingles" + (or opportunity) district. + + :rtype float + """ + dist_percs = part[minority_perc_col].values() + num_opport_dists = sum(list(map(lambda v: v >= threshold, dist_percs))) + next_dist = max(i for i in dist_percs if i < threshold) + + if next_dist < threshold - 0.1: + return num_opport_dists + else: + return num_opport_dists + (next_dist - threshold + 0.1) * 10 + + @classmethod + def penalize_maximum_over(cls, part, minority_perc_col, threshold): + """ + Given a partition, returns the number of opportunity districts + (1 - the maximum excess) + scaled to between 0 and 1. + + :param `part`: Partition to score. + :param `minority_perc_col`: Which updater is a mapping of district ids to the fraction of + minority population within that district. + :param `threshold`: Beyond which fraction to consider something a "Gingles" + (or opportunity) district. + + :rtype float + """ + dist_percs = part[minority_perc_col].values() + num_opportunity_dists = sum(list(map(lambda v: v >= threshold, dist_percs))) + if num_opportunity_dists == 0: + return 0 + else: + max_dist = max(dist_percs) + return num_opportunity_dists + (1 - max_dist) / (1 - threshold) + + @classmethod + def penalize_avg_over(cls, part, minority_perc_col, threshold): + """ + Given a partition, returns the number of opportunity districts + (1 - the average excess) + scaled to between 0 and 1. + + :param `part`: Partition to score. + :param `minority_perc_col`: Which updater is a mapping of district ids to the fraction of + minority population within that district. + :param `threshold`: Beyond which fraction to consider something a "Gingles" + (or opportunity) district. + + :rtype float + """ + dist_percs = part[minority_perc_col].values() + opport_dists = list(filter(lambda v: v >= threshold, dist_percs)) + if opport_dists == []: + return 0 + else: + num_opportunity_dists = len(opport_dists) + avg_opportunity_dist = np.mean(opport_dists) + return num_opportunity_dists + (1 - avg_opportunity_dist) / (1 - threshold) diff --git a/gerrychain/optimization/optimization.py b/gerrychain/optimization/optimization.py new file mode 100644 index 00000000..611d585c --- /dev/null +++ b/gerrychain/optimization/optimization.py @@ -0,0 +1,381 @@ +from ..chain import MarkovChain +from .. partition import Partition +from ..accept import always_accept +import random +from typing import Union, Callable, List, Any +from tqdm import tqdm +import math + + +class SingleMetricOptimizer: + """ + SingleMetricOptimizer represents the class of algorithms / chains that optimize plans with + respect to a single metric. An instance of this class encapsulates the following state + information: + * the dualgraph and updaters via the initial partition, + * the constraints new proposals are subject to, + * the metric over which to optimize, + * and whether or not to seek maximal or minimal values of the metric. + + The SingleMetricOptimizer class implements the following common methods of optimization: + * Short Bursts + * Simulated Annealing + * Tilted Runs + + Both during and after a optimization run, the class properties `best_part` and `best_score` + represent the optimal partition / corresponding score value observed. Note that these + properties do NOT persist across multiple optimization runs, as they are reset each time an + optimization run is invoked. + """ + + def __init__(self, proposal: Callable[[Partition], Partition], + constraints: Union[Callable[[Partition], bool], List[Callable[[Partition], bool]]], + initial_state: Partition, optimization_metric: Callable[[Partition], Any], + maximize: bool = True, step_indexer: str = "step"): + """ + Args: + proposal (Callable[[Partition], Partition]): Function proposing the next state from the + current state. + constraints (Union[Callable[[Partition], bool], List[Callable[[Partition], bool]]]): + A function, or lists of functions, determining whether the proposed next state is + valid (passes all binary constraints). Usually this is a + `~gerrychain.constraints.Validator` class instance. + initial_state (Partition): Initial state of the optimizer. + optimization_metric (Callable[[Partition], Any]): The score function with which to + optimize over. This should have the signature: + `Partition -> 'a where 'a is Comparable` + maximize (bool, optional): Whether to minimize or maximize the function? Defaults to + maximize. + step_indexer (str, optional): Name of the updater tracking the partitions step in the + chain. If not implemented on the partition the constructor creates and adds it. + Defaults to `"step"`. + + Returns: + A SingleMetricOptimizer object + """ + self._initial_part = initial_state + self._proposal = proposal + self._constraints = constraints + self._score = optimization_metric + self._maximize = maximize + self._best_part = None + self._best_score = None + self._step_indexer = step_indexer + + if self._step_indexer not in self._initial_part.updaters: + step_updater = lambda p: 0 if p.parent is None else p.parent[self._step_indexer] + 1 + self._initial_part.updaters[self._step_indexer] = step_updater + + @property + def best_part(self) -> Partition: + """ + Partition object corresponding to best scoring plan observed over the current (or most + recent) optimization run. + """ + return self._best_part + + @property + def best_score(self) -> Any: + """ + Value of score metric corresponding to best scoring plan observed over the current (or most + recent) optimization run. + """ + return self._best_score + + @property + def score(self) -> Callable[[Partition], Any]: + """ + The score function which is being optimized over. + """ + return self._score + + def _is_improvement(self, new_score, old_score) -> bool: + """ + Helper function defining improvement comparison between scores. Scores can be any + comparable type. + + Args: + new_score (Any): Score of proposed partition. + old_score (Any): Score of previous partition. + + Returns: + Whether the new score is an improvement over the old score. + + """ + if self._maximize: + return new_score >= old_score + else: + return new_score <= old_score + + def _tilted_acceptance_function(self, p: float) -> Callable[[Partition], bool]: + """ + Function factory that binds and returns a tilted acceptance function. + + Args: + p (float): The probability of accepting a worse score. + + Returns: + A acceptance function for tilted chains. + """ + def tilted_acceptance_function(part): + if part.parent is None: + return True + + part_score = self.score(part) + prev_score = self.score(part.parent) + + if self._is_improvement(part_score, prev_score): + return True + else: + return random.random() < p + + return tilted_acceptance_function + + def _simulated_annealing_acceptance_function(self, beta_function: Callable[[int], float], + beta_magnitude: float): + """ + Function factory that binds and returns a simulated annealing acceptance function. + + Args: + beta_functions (Callable[[int], float]): Function (f: t -> beta, where beta is in [0,1]) + defining temperature over time. f(t) = 0 the chain is hot and every proposal is + accepted. At f(t) = 1 the chain is cold and worse proposal have a low probability + of being accepted relative to the magnitude of change in score. + beta_magnitude (float): Scaling parameter for how much to weight changes in score. + + Returns: + A acceptance function for simulated annealing runs. + """ + def simulated_annealing_acceptance_function(part): + if part.parent is None: + return True + score_delta = self.score(part) - self.score(part.parent) + beta = beta_function(part[self._step_indexer]) + if self._maximize: + score_delta *= -1 + return random.random() < math.exp(-beta * beta_magnitude * score_delta) + + return simulated_annealing_acceptance_function + + @classmethod + def jumpcycle_beta_function(cls, duration_hot: int, + duration_cold: int) -> Callable[[int], float]: + """ + Class method that binds and return simple hot-cold cycle beta temperature function, where + the chain runs hot for some given duration and then cold for some duration, and repeats that + cycle. + + Args: + duration_hot: Number of steps to run chain hot. + duration_cold: Number of steps to run chain cold. + + Returns: + Beta function defining hot-cold cycle. + """ + cycle_length = duration_hot + duration_cold + + def beta_function(step: int): + time_in_cycle = step % cycle_length + return float(time_in_cycle >= duration_hot) + + return beta_function + + @classmethod + def linearcycle_beta_function(cls, duration_hot: int, duration_cooldown: int, + duration_cold: int) -> Callable[[int], float]: + cycle_length = duration_hot + duration_cooldown + duration_cold + + def beta_function(step: int): + pass + + return beta_function + + @classmethod + def logitcycle_beta_function(cls, duration_hot: int, duration_cooldown: int, + duration_cold: int) -> Callable[[int], float]: + cycle_length = duration_hot + duration_cooldown + duration_cold + + def beta_function(step: int): + pass + + return beta_function + + def short_bursts(self, burst_length: int, num_bursts: int, + accept: Callable[[Partition], bool] = always_accept, + with_progress_bar: bool = False): + """ + Performs a short burst run using the instance's score function. Each burst starts at the + best performing plan of the previous burst. If there's a tie, the later observed one is + selected. + + Args + burst_length (int): How many steps to run within each burst? + num_bursts (int): How many bursts to perform? + accept (Callable[[Partition], bool], optional): Function accepting or rejecting the + proposed state. In the most basic use case, this always returns True. + with_progress_bar (bool, optional): Whether or not to draw tqdm progress bar. Defaults + to False. + + Returns: + Partition generator. + """ + if with_progress_bar: + for part in tqdm(self.short_bursts(burst_length, num_bursts, accept, + with_progress_bar=False), + total=burst_length * num_bursts): + yield part + return + + self._best_part = self._initial_part + self._best_score = self.score(self._best_part) + + for _ in range(num_bursts): + chain = MarkovChain(self._proposal, self._constraints, accept, self._best_part, + burst_length) + + for part in chain: + yield part + part_score = self.score(part) + + if self._is_improvement(part_score, self._best_score): + self._best_part = part + self._best_score = part_score + + def simulated_annealing(self, num_steps: int, beta_function: Callable[[int], float], + beta_magnitude: float = 1, with_progress_bar: bool = False): + """ + Performs simulated annealing with respect to the class instance's score function. + + Args: + num_steps (int): How many steps to run for. + beta_function (Callable[[int], float]): Function (f: t -> beta, where beta is in [0,1]) + defining temperature over time. f(t) = 0 the chain is hot and every proposal is + accepted. At f(t) = 1 the chain is cold and worse proposal have a low probability + of being accepted relative to the magnitude of change in score. + beta_magnitude (float): Scaling parameter for how much to weight changes in score. + with_progress_bar (bool, optional): Whether or not to draw tqdm progress bar. Defaults + to False. + + Returns: + Partition generator. + """ + chain = MarkovChain(self._proposal, self._constraints, + self._simulated_annealing_acceptance_function(beta_function, + beta_magnitude), + self._initial_part, num_steps) + + self._best_part = self._initial_part + self._best_score = self.score(self._best_part) + + chain_generator = tqdm(chain) if with_progress_bar else chain + + for part in chain_generator: + yield part + part_score = self.score(part) + if self._is_improvement(part_score, self._best_score): + self._best_part = part + self._best_score = part_score + + def tilted_short_bursts(self, burst_length: int, num_bursts: int, p: float, + with_progress_bar: bool = False): + """ + Performs a short burst run using the instance's score function. Each burst starts at the + best performing plan of the previous burst. If there's a tie, the later observed one is + selected. Within each burst a tilted acceptance function is used where better scoring plans + are always accepted and worse scoring plans are accepted with probability `p`. + + Args + burst_length (int): How many steps to run within each burst? + num_bursts (int): How many bursts to perform? + p (float): The probability of accepting a plan with a worse score. + with_progress_bar (bool, optional): Whether or not to draw tqdm progress bar. Defaults + to False. + + Returns: + Partition generator. + """ + return self.short_bursts(burst_length, num_bursts, + accept=self._tilted_acceptance_function(p), + with_progress_bar=with_progress_bar) + + def variable_length_short_bursts(self, num_steps: int, stuck_buffer: int, + accept: Callable[[Partition], bool] = always_accept, + with_progress_bar: bool = False): + """ + Performs a short burst where the burst length is allowed to increase as it gets harder to + find high scoring plans. The initial burst length is set to 2, and it is doubled each time + there is no improvement over the passed number (`stuck_buffer`) of runs. + + Args: + num_steps (int): How many steps to run for. + stuck_buffer (int): How many bursts of a given length with no improvement to allow + before increasing the burst length. + accept (Callable[[Partition], bool], optional): Function accepting or rejecting the + proposed state. In the most basic use case, this always returns True. + with_progress_bar (bool, optional): Whether or not to draw tqdm progress bar. Defaults + to False. + + Returns: + Partition generator. + """ + if with_progress_bar: + for part in tqdm(self.variable_length_short_bursts(num_steps, stuck_buffer, accept, + with_progress_bar=False), total=num_steps): + yield part + return + + self._best_part = self._initial_part + self._best_score = self.score(self._best_part) + time_stuck = 0 + burst_length = 2 + i = 0 + + while(i < num_steps): + chain = MarkovChain(self._proposal, self._constraints, accept, self._best_part, + burst_length) + for part in chain: + yield part + part_score = self.score(part) + if self._is_improvement(part_score, self._best_score): + self._best_part = part + self._best_score = part_score + time_stuck = 0 + else: + time_stuck += 1 + + i += 1 + if i >= num_steps: + break + + if time_stuck >= stuck_buffer * burst_length: + burst_length *= 2 + + def tilted_run(self, num_steps: int, p: float, with_progress_bar: bool = False): + """ + Performs a tilted run. A chain where the acceptance function always accepts better plans + and accepts worse plans with some probability `p`. + + Args: + num_steps (int): How many steps to run for. + p (float): The probability of accepting a plan with a worse score. + with_progress_bar (bool, optional): Whether or not to draw tqdm progress bar. Defaults + to False. + + Returns: + Partition generator. + """ + chain = MarkovChain(self._proposal, self._constraints, self._tilted_acceptance_function(p), + self._initial_part, num_steps) + + self._best_part = self._initial_part + self._best_score = self.score(self._best_part) + + chain_generator = tqdm(chain) if with_progress_bar else chain + + for part in chain_generator: + yield part + part_score = self.score(part) + + if self._is_improvement(part_score, self._best_score): + self._best_part = part + self._best_score = part_score