add tutorial on renewables part 1/3: firm capacity

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

@@ -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`)?"
    ]