tutorial/transport/py_transport_scenario.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 2 for Python\n",
    "\n",
    "## Make a scenario of Dantzig's Transport Problem using the *ix modeling platform* (ixmp)\n",
    "\n",
    "<img style=\"float: right; height: 80px;\" src=\"_static/python.png\">\n",
    "\n",
    "### Aim and scope of the tutorial\n",
    "\n",
    "This tutorial uses teh transport problem scenario developed in the first tutorial and illustrates how the ixmp framework can be applied for scenario analysis in the sense often used in economic or environmental modeling: develop a baseline, create a clone from the baseline with altered parameters or assumptions, and solve the new model. Then, compare the results from the original and altered scenario versions.\n",
    "\n",
    "In particular, this tutorial will take you through the following steps:\n",
    "0. Launch an ixmp.Platform instance and retrieve the ixmp.Scenario instance of Dantzig's transport problem\n",
    "0. Retrieve some data from the scenario for illustration of filters\n",
    "0. Make a clone of the baseline scenario, then check out the clone and make changes:  \n",
    "   in this case, add a new demand location and transport costs to that city\n",
    "0. Solve the new scenario\n",
    "0. Display the solution of both the baseline and the new scenario"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Launching the platform and loading a scenario from the ixmp database instance\n",
    "\n",
    "We launch a platform instance and display all models/scenarios currently stored in the connected database instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load required packages\n",
    "import pandas as pd\n",
    "import ixmp"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# launch the ix modeling platform using the default local database\n",
    "mp = ixmp.Platform()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Model and scenario name for Dantzig's transport problem\n",
    "model = 'canning problem'\n",
    "scenario = 'standard'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# List all Scenarios in the database\n",
    "mp.scenario_list()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have just run the first, ``py_transport`` tutorial, the existing scenario should appear, and we can load it.\n",
    "Uncomment and run the following line."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# # Load the default version of the scenario created in the first tutorial\n",
    "# scen = ixmp.Scenario(mp, model, scenario)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If not (e.g. starting with this tutorial), we can use a function that creates the scenario from scratch in one step:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ixmp.testing import make_dantzig\n",
    "scen = make_dantzig(mp, solve='.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retrieve some data from the scenario for illustration of filters\n",
    "\n",
    "Before cloning a scenario and editing data, this section illustrates two-and-a-half methods to retrieve data for a parameter from a scenario."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load the distance parameter\n",
    "d = scen.par(\"d\")\n",
    "d"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# show only the distances for connections from Seattle by filtering the pandas.DataFrame returned above\n",
    "d[d['i'] == \"seattle\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# for faster access or more complex filtering,\n",
    "# it may be easier to only load specific parameter elements using a dictionary\n",
    "ele_filter = {}\n",
    "ele_filter['i'] = ['seattle']\n",
    "ele_filter['j'] = ['chicago', 'topeka']\n",
    "\n",
    "d_filtered = scen.par(\"d\", ele_filter)\n",
    "d_filtered"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Make a clone of the baseline scenario, then check out the clone and edit the scenario\n",
    "\n",
    "For illustration of a scenario analysis workflow, we add a new demand location ``detroit`` and add a demand level and transport costs to that city.\n",
    "Because the production capacity does not allow much slack for increased production, we also reduce the demand level in ``chicago``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create a new scenario by cloning the scenario (without keeping the solution)\n",
    "scen_detroit = scen.clone(model=model, scenario='detroit', annotation='extend the Transport problem by a new city', keep_solution=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check out the scenario to make changes\n",
    "scen_detroit.check_out()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# reduce demand in chicago\n",
    "scen_detroit.add_par('b', 'chicago', 200, 'cases')\n",
    "\n",
    "# add a new city with demand and distances\n",
    "scen_detroit.add_set('j', 'detroit')\n",
    "scen_detroit.add_par('b', 'detroit', 150, 'cases')\n",
    "scen_detroit.add_par('d', ['seattle', 'detroit'], 1.7, 'cases')\n",
    "scen_detroit.add_par('d', ['san-diego', 'detroit'], 1.9, 'cases')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# commit changes to the ixmp database instance\n",
    "comment = \"add new city 'detroit' with demand, reduce demand in 'chicago'\"\n",
    "scen_detroit.commit(comment)\n",
    "scen_detroit.set_as_default()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solve the new scenario"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scen_detroit.solve(model='dantzig')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Display and analyze the results\n",
    "\n",
    "For comparison between the baseline scenario, i.e., the original transport problem, and the \"detroit\" scenario, we show the solution for both cases."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "name": "scen-z"
    }
   },
   "outputs": [],
   "source": [
    "# display the objective value of the solution in the baseline scenario\n",
    "scen.var('z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
     "jupyter": {
      "name": "scen-detroit-z"
     }
   },
   "outputs": [],
   "source": [
    "# display the objective value of the solution in the \"detroit\" scenario\n",
    "scen_detroit.var('z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# display the quantities transported from canning plants to demand locations in the baseline scenario\n",
    "scen.var('x')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# display the quantities transported from canning plants to demand locations in the \"detroit\" scenario\n",
    "scen_detroit.var('x')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# display the quantities and marginals (=shadow prices) of the demand balance constraints in the baseline scenario\n",
    "scen.equ(\"demand\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# display the quantities and marginals (=shadow prices) of the demand balance constraints in the \"detroit\" scenario\n",
    "scen_detroit.equ(\"demand\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Close the database connection of the ix modeling platform"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# close the connection of the platform instance to the local ixmp database files\n",
    "mp.close_db()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "The cake is a lie!"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}