updates after Paul's comments

tutorial/README.rst

@@ -67,6 +67,7 @@ uses it to illustrate a range of framework features.
 3. `Limit emissions using a tax <https://github.com/iiasa/message_ix/blob/master/tutorial/westeros/westeros_emissions_taxes.ipynb>`_ instead of a bound.
 4. `Represent both coal and wind electricity <https://github.com/iiasa/message_ix/blob/master/tutorial/westeros/westeros_firm_capacity.ipynb>`_, using a “firm capacity” formulation: each generation technology can supply some firm capacity, but the variable, renewable technology (wind) supplies less than coal.
 5. Represent coal and wind electricity using a different, `“flexibility requirement” formulation <https://github.com/iiasa/message_ix/blob/master/tutorial/westeros/westeros_flexible_generation.ipynb>`_, wherein wind *requires* and coal *supplies* flexibility.
+6. `Variablity in energy supply and demand <https://github.com/iiasa/message_ix/blob/master/tutorial/westeros/westeros_seasonality.ipynb>`_, by adding two sub-annual time steps (winter and summer).
 
 Austrian energy system
 ----------------------

tutorial/westeros/westeros_baseline.ipynb

@@ -47,7 +47,7 @@
    "source": [
     "## Online documentation\n",
     "\n",
-    "The full framework documentation is available at [https://messageix.iiasa.ac.at](https://messageix.iiasa.ac.at)\n",
+    "The full framework documentation is available at [https://message.iiasa.ac.at](https://message.iiasa.ac.at)\n",
     "    \n",
     "<img src='_static/doc_page.png'>"
    ]
@@ -77,7 +77,7 @@
    "source": [
     "## MESSAGEix: the mathematical paradigm\n",
     "\n",
-    "At its core, *MESSAGEix* is an optimization model:\n",
+    "At its core, *MESSAGEix* is an optimization problem:\n",
     "\n",
     "> $\\min \\quad ~c^T \\cdot x$  \n",
     "> $~s.t. \\quad A \\cdot x \\leq b$\n",
@@ -347,6 +347,8 @@
    },
    "source": [
     "The `COMMODITY_BALANCE_GT` and `COMMODITY_BALANCE_LT` equations ensure that `demand` for each `commodity` is met at each `level` in the energy system.\n",
+    "The equation is copied below in this tutorial notebook, but every model equation is available for reference in\n",
+    "the [Mathematical formulation](https://message.iiasa.ac.at/en/stable/model/MESSAGE/model_core.html#) section of the MESSAGEix documentation.\n",
     "\n",
     "$\\sum_{\\substack{n^L,t,m \\\\ y^V \\leq y}} \\text{output}_{n^L,t,y^V,y,m,n,c,l} \\cdot \\text{ACT}_{n^L,t,y^V,y,m}$\n",
     "$- \\sum_{\\substack{n^L,t,m, \\\\ y^V \\leq y}} \\text{input}_{n^L,t,y^V,y,m,n,c,l} \\cdot \\text{ACT}_{n^L,t,m,y}$  \n",
@@ -501,7 +503,9 @@
     "- receives *input* in the form of the \"electricity\" *commodity* at the \"final [energy]\" *level*, and\n",
     "- *outputs* the commodity \"light\" at the \"useful [energy]\" level.\n",
     "\n",
-    "The `value` in the input and output parameter is used to represent the effiecieny of a technology (efficiency = output/input). For example, input of 1.0 and output of 1.0 for a technology shows that the efficiency of that technology is 100% in converting input commodity to output commodity."
+    "The `value` in the input and output parameter is used to represent the effiecieny of a technology (efficiency = output/input).\n",
+    "For example, input of 1.0 and output of 1.0 for a technology shows that the efficiency of that technology is 100% in converting\n",
+    "the input commodity to the output commodity."
    ]
   },
   {
@@ -1325,7 +1329,9 @@
    "source": [
     "### Electricity Price\n",
     "\n",
-    "And how much does the electricity cost? These prices are in fact **shadow prices** taken from the **dual variables** of the model solution. They reflect the marginal cost of electricity generation (i.e., the additional cost of the system for supplying one more unit of electricity), which is in fact the marginal cost of the most expensive generator.  \n",
+    "And how much does the electricity cost? These prices are in fact **shadow prices** taken from the **dual variables** of the model solution.\n",
+    "They reflect the marginal cost of electricity generation (i.e., the additional cost of the system for supplying one more unit of\n",
+    "electricity), which is in fact the marginal cost of the most expensive operating generator.  \n",
     "\n",
     "Note the price drop when the most expensive technology is no longer in the system."
    ]

tutorial/westeros/westeros_emissions_taxes.ipynb

@@ -85,7 +85,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "When setting a cumlulative bound, the undiscounted price of emission is the same in different model years (see the marginals of equation `EMISSION_CONSTRAINT`). However, considering the year-to-year discount factor, we observe an ascending trend in emission prices shown in `PRICE_EMISSION` above. This means the emission price in later years is higher as the value of money in the future is lower compared to today. "
+    "When setting a cumlulative bound, the undiscounted price of emission is the same in different model years (see the marginals of\n",
+    "equation `EMISSION_CONSTRAINT`). However, considering the year-to-year discount factor, we observe an ascending trend in\n",
+    "emission prices shown in `PRICE_EMISSION` above. This means the emission price in later years is higher as the value of money in\n",
+    "the future is lower compared to today. "
    ]
   },
   {
@@ -94,9 +97,11 @@
    "source": [
     "## Make a new scenario with emission bounds by year\n",
     "\n",
-    "In the previous example, we imposed a bound on emissions over the entire model horizon by using the `type_year` as 'cumulative' in the parameter `bound_emission`. Now, we will create a similar scenario, but the emission constraint will be defined per year.\n",
+    "In the previous example, we imposed a bound on emissions over the entire model horizon by using the `type_year` as 'cumulative'\n",
+    "in the parameter `bound_emission`. Now, we will create a similar scenario, but the emission constraint will be defined per year.\n",
     "\n",
-    "For the sake of comparison, the per-year emission values will be chosen exactly in line with the optimal emission trajectory obtained from the solution of the previous scenario."
+    "For the sake of comparison, the per-year emission values will be chosen exactly in line with the optimal emission trajectory\n",
+    "obtained from the solution of the previous scenario."
    ]
   },
   {
@@ -174,7 +179,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Comparing the emission prices between the two scenarios at this stage, we see that the values are not identical. The reason is that when we introduce emission bounds per year, the price of emission in each year reflects the cost occuring when reducing one more unit of emission in that year. However, in the scenario with a cumulative bound over the entire model horizon, the price of emission reflects the cost of the system in reducing one more unit of emission over the entire model horizon."
+    "Comparing the emission prices between the two scenarios at this stage, we see that the values are not identical.\n",
+    "The reason is that when we introduce emission bounds per year, the price of emission in each year reflects the cost occuring\n",
+    "when reducing one more unit of emission in that year.\n",
+    "However, in the scenario with a cumulative bound over the entire model horizon, the price of emission reflects the cost of the\n",
+    "system in reducing one more unit of emission over the entire model horizon."
    ]
   },
   {
@@ -234,10 +243,8 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
-   "metadata": {
-    "collapsed": true
-   },
+   "execution_count": null,
+   "metadata": {},
    "outputs": [],
    "source": [
     "scen_tax.commit(comment='setting taxes on emissions')"
@@ -265,7 +272,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Question\n",
+    "# Exercises\n",
     "- How does these prices compare to the scenario with a cumulative emission bound (`scen_bd`)?\n",
     "- Try setting the emission tax again by using emission prices obtained from the scenario with yearly bounds on emissions (`scen_bd_by_year`). What is the difference in emissions (i.e., variable `EMISS`)?"
    ]

tutorial/westeros/westeros_firm_capacity.ipynb

@@ -67,7 +67,13 @@
    "source": [
     "## Improving the Representation of Electricity Sector\n",
     "### Peak load factor\n",
-    "The input demand for electricity (notice: not the demand for useful light but for electricity) in the model shows the average electricity demand in the given time (which in our example is a year). However, power systems need enough installed capacity not only to cover the average electricity demand but also to meet the peak demand, i.e., maximum load throughout that time. This feature can be specified in the model using parameter `peak_load_factor`. For example, if annual average load is 5 GWa peak load amy be 10GW, hence, the peak load factor is equal to 2."
+    "The input demand for electricity (notice: not the demand for useful light but for electricity) in the model shows the average\n",
+    "electricity demand in the given time (which in our example is a year).\n",
+    "However, power systems need enough installed capacity not only to cover the average electricity demand but also to meet the peak\n",
+    "demand, i.e., maximum load throughout that time.\n",
+    "This feature can be specified in the model using parameter `peak_load_factor`.\n",
+    "For example, if annual average load is 5 GW, the peak load may be twice as high, at 10 GW; hence, the peak load factor is equal\n",
+    "to 2."
    ]
   },
   {
@@ -94,7 +100,12 @@
    "metadata": {},
    "source": [
     "## Reliability of Power System\n",
-    "In roder to meet demand reliably, the power system needs to maintain dispatchable or so called firm capacity at any time. Some technologies like coal power plants can fully contribute to the required firm capacity, i.e., 1 MW installed capacity of these technologies provide 1 MW firm capacity. However, some other technologies such as variable renewables such as wind are not fully reliable when the power system needs them. As such, the capacity value of wind power plant is considered to be lower than 1. In this example, we assume that 10% of electricity supply by wind is 80% reliable, while he remaining 90% installed capacity can only contribute by 5% to the required firm capcity. As such, we divide wind power into two parts with two different ratings (r1 and r2) and we define this through parameter `rating_bin`.\n"
+    "In order to meet demand reliably, the power system needs to maintain dispatchable or so-called firm capacity at any time.\n",
+    "Some technologies like coal power plants can fully contribute to the required firm capacity, i.e.,\n",
+    "1 MW installed capacity of these technologies provide 1 MW firm capacity.\n",
+    "However, some other technologies such as variable renewables like wind are not fully reliable when the power system needs them.\n",
+    "As such, the capacity value of wind power plant is considered to be lower than 1.\n",
+    "In this example, we assume that 10% of electricity supply by wind is 80% reliable, while the remaining 90% installed capacity can only contribute by 5% to the required firm capacity. As such, we divide wind power into two parts with two different ratings (r1 and r2) and we define this through parameter `rating_bin`.\n"
    ]
   },
   {

tutorial/westeros/westeros_flexible_generation.ipynb

@@ -70,7 +70,7 @@
    "source": [
     "## Add a carbon tax\n",
     "\n",
-    "Then, we add a carbon tax to motivate the use of low-carbon technologies in the system. We do this similar to the process explained in the [tutorial for adding emission tax](https://github.com/iiasa/message_ix/blob/master/tutorial/westeros/westeros_emissions_taxes.ipynb)"
+    "Then, we add a carbon tax to motivate the use of low-carbon technologies in the system. We do this similar to the process explained in the tutorial for adding emissions taxes (`westeros_emission_taxes.ipynb`)."
    ]
   },
   {
@@ -101,7 +101,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
    "metadata": {
     "collapsed": true
    },

tutorial/westeros/westeros_seasonality.ipynb

@@ -5,14 +5,19 @@
    "metadata": {},
    "source": [
     "# \"*Winter is coming!*\": Modeling of variability in energy supply and demand\n",
-    "Time-dependent variations in demand and supply are common characteristics of an electricity system, and Westeros is not an exception. This tutorial helps to learn how to add sub-annual time steps to a MESSAGEix model and investigate the impact of the variability in supply and demand. This tutorial is structured as follows:\n",
+    "Time-dependent variations in demand and supply are common characteristics of an electricity system, and Westeros is not an\n",
+    "exception. This tutorial helps to learn how to add sub-annual time steps to a MESSAGEix model and investigate the impact of the\n",
+    "variability in supply and demand. It is structured as follows:\n",
     "1. A short note on seasonality\n",
     "2. Adding sub-annual time steps\n",
     "3. Analyzing the results\n",
     "\n",
     "### Requirements for running this tutorial\n",
     "- You have MESSAGEix framework installed and working\n",
-    "- You have run Westeros baseline scenario and solved it successfully"
+    "- You have run Westeros baseline scenario and solved it successfully\n",
+    "\n",
+    "This tutorial was developed by Behnam Zakeri ([@behnam-zakeri](https://github.com/behnam-zakeri)) for the course Energy\n",
+    "Economics and Modeling held at the International Summer School in Energy Technology, St. Petersburg Polytechnique University in August 2018."
    ]
   },
   {
@@ -189,7 +194,8 @@
     "|-----------|----------| -----------|\n",
     "| duration_time\t| time\t|duration of sub-annual time slices (relative to 1)| \n",
     "\n",
-    "In our example, winter and summer are each half of the year."
+    "In our example, winter and summer are defined as each half of the year. However, the duration of time steps can be\n",
+    "different in a MESSAGEix model, e.g., winter 0.4 and summer 0.6. But the sum of the duration times must be equal to 1."
    ]
   },
   {
@@ -213,7 +219,10 @@
     "In this stage, we introduce a function that helps us to modify the parameters after adding new time steps. This function called \"yearly_to_season\" does the following:\n",
     "- removing old values, where the \"time\" index was \"year\"\n",
     "- populating data for new \"time\" indexes\n",
-    "- using the ratios defined by the user to convert yearly values to seasonal ones"
+    "- using the ratios defined by the user to convert yearly values to seasonal ones\n",
+    "\n",
+    "This is a common code pattern when modelling using MESSAGEix:\n",
+    "writing re-usable code that helps modify existing parameter data to reflect some desired change in the reference energy system."
    ]
   },
   {
@@ -279,7 +288,7 @@
    "metadata": {},
    "source": [
     "### Modifying \"input\" and \"output\"\n",
-    "However, not all parameters that have subannual time steps need to divide their values for each time step. For example, \"output\" parameter shows the output efficiency, commodities and level of a technology. Hence, as far as the efficiency of a technology remains unchanged in different seasons, the value of \"output\" remains fixed. As such, we only need to add the sub-annual time steps but with the same value as for the yearly one."
+    "However, not all parameters that have subannual time steps need to divide their annual values for each time step. For example, \"output\" parameter shows the output efficiency, commodities and the level of a technology. Hence, as far as the efficiency of a technology remains unchanged in different seasons, the value of \"output\" will be the same. As such, we only need to add the sub-annual time steps but with the same value as for the yearly one."
    ]
   },
   {
@@ -324,7 +333,7 @@
    "metadata": {},
    "source": [
     "### Modifying capacity factor\n",
-    "We discussed about the variation in the capacity factor of wind power in each month. By averaging the values for the respective months, we reach a capacity factor of 0.46 for winter and 0.25 for summer in Westeros. For simplicity, the capacity factor of wind was 1 in the baseline scenario.\n"
+    "We discussed about the variation in the capacity factor of wind power in each month. By averaging the values for the respective months, we reach a capacity factor of 0.46 for winter and 0.25 for summer in Westeros.\n"
    ]
   },
   {
@@ -334,11 +343,11 @@
    "outputs": [],
    "source": [
     "# Modifying capacity factor\n",
-    "# Retrieving average yearly capacity factor of wind in the model\n",
-    "cf_wind = scen.par('capacity_factor', {'technology': 'wind_ppl'})['value'].mean()\n",
+    "# Let's check the yearly capacity factor of wind in the baseline scenario\n",
+    "scen.par('capacity_factor', {'technology': 'wind_ppl'})['value'].mean()\n",
     "\n",
-    "# Passing seasonal capacity factors as shares of the yearly value\n",
-    "cf_data = {'winter': 0.46/cf_wind, 'summer': 0.25/cf_wind} \n",
+    "# Passing seasonal capacity factors\n",
+    "cf_data = {'winter': 0.46, 'summer': 0.25} \n",
     "cf_filters = {'technology': 'wind_ppl'}\n",
     "yearly_to_season(scen, 'capacity_factor', cf_data, cf_filters)\n",
     "\n",