Small fixes to text

Author: tsmbland

docs/user-guide/add-agent.ipynb

@@ -186,6 +186,8 @@
    "source": [
     "In this scenario we can see that agent `A2` has an intermediate behaviour compared to the two agents in the first simulation, investing in both gas boilers and heat pumps.\n",
     "\n",
+    "## Summary\n",
+    "\n",
     "From this small scenario, the difference between investment strategies between agents is evident. This is one of the key benefits of agent-based models when compared to optimisation-based models.\n",
     "\n",
     "Have a play around with the files to see if you can come up with different scenarios!"

docs/user-guide/add-gdp-correlation-demand.ipynb

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the previous section we added an exogenous service demand. That is, we explicitly specified what the demand would be per year. \n",
+    "In the previous tutorial we added an exogenous service demand. That is, we explicitly specified what the demand would be per year. \n",
     "However, we may not know what the electricity demand may be per year. Instead, we may conclude that our electricity demand is a function of the GDP and population of a particular region. \n",
     "To accommodate such a scenario, MUSE enables us to choose a regression function that estimates service demands from GDP and population, which may be more certain in your case.\n",
     "In this section we will show how this can be done.\n",
@@ -36,11 +36,11 @@
    "source": [
     "Similarly to before, we must amend the `technodata/preset` folder. As we are no longer explicitly specifying demand, we can delete the `Residential2020Consumption.csv` and `Residential2050Consumption.csv` files. Instead, we must replace these files with the following:\n",
     "\n",
-    "- A macrodrivers file. This contains the drivers of the service demand that we want to model. For this example, these will include GDP based on purchasing power parity (GDP PPP) and the population that we expect from 2010 to 2110.\n",
+    "- __A macrodrivers file__: This contains the drivers of the service demand that we want to model. For this example, these will include GDP based on purchasing power parity (GDP PPP) and the population that we expect from 2010 to 2110.\n",
     "\n",
-    "- A regression parameters file. This file will set the function type we would like to use to predict the service demand and the respective parameters of this regression file per region.\n",
+    "- __A regression parameters file__: This file will set the function type we would like to use to predict the service demand and the respective parameters of this regression file per region.\n",
     "\n",
-    "- A timeslice share file. This file sets how the demand is shared between timeslice.\n",
+    "- __A timeslice share file__: This file sets how the demand is shared between timeslice.\n",
     "\n",
     "The example files for each of those just mentioned can be found below, respectively:\n",
     "\n",

docs/user-guide/add-region.ipynb

@@ -21,6 +21,8 @@
     "\n",
     "We will add a region called `R2` (however, this could equally be called `USA` or `India`). This requires us to undertake a similar process as before of modifying the input simulation data.\n",
     "\n",
+    "## Input files\n",
+    "\n",
     "We begin by modifying the `settings.toml` file. We just have to add our new region to the `regions` variable, in the 4th line of the file, like so:\n",
     "\n",
     "```toml\n",
@@ -79,6 +81,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "## Results\n",
+    "\n",
     "Again, we will run the results using the ```python -m pip muse settings.toml``` in the command line, and visualize the data as follows:"
    ]
   },
@@ -128,12 +132,21 @@
    "source": [
     "We can see that `R2` quickly reaches its capacity limit for `heatpump`, and additional investment in `gasboiler` needed to meet the residential heating demand.\n",
     "\n",
+    "## Summary\n",
+    "\n",
+    "In this tutorial we have shown how to add a new region to the model, and shown how the `TotalCapacityLimit` parameter can be used to put an upper limit on capacity in a region.\n",
+    "\n",
     "Have a play around with the various costs data in the technodata files for each of the sectors and technologies to see if different scenarios emerge. Although be careful. In some cases, the constraints on certain technologies will make it impossible for the demand to be met and it will give you an error such as the following:\n",
     "\n",
     "    message: 'The algorithm terminated successfully and determined that the problem is infeasible.'\n",
     "\n",
     "To avoid this error message you may have to relax the constraints in the technodata files (`MaxCapacityGrowth`, `MaxCapacityAddition` and `TotalCapacityLimit`)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
   }
  ],
  "metadata": {

docs/user-guide/add-solar.ipynb

@@ -4,7 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Adding a new technology"
+    "# Adding a new technology\n",
+    "\n",
+    "In this tutorial we will begin by giving an overview of the input files that MUSE requires to run. We will then show how to modify these files to add a new technology to the model."
    ]
   },
   {
@@ -30,7 +32,7 @@
     "\n",
     "To create a customised case study it is necessary to edit both of these file types.\n",
     "\n",
-    "Simulation settings are specified in a TOML file. [TOML](https://github.com/toml-lang/toml) is a simple, extensible and intuitive file format well suited  for specifying small sets of complex data.\n",
+    "Simulation settings are specified in a TOML file. [TOML](../inputs/toml_primer.rst) is a simple, extensible and intuitive file format well suited for specifying small sets of complex data.\n",
     "\n",
     "Simulation data is specified in [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) files. This is a common format used for larger datasets, and is made up of columns and rows, with a comma used to differentiate between entries. \n",
     "\n",
@@ -124,8 +126,7 @@
     "|windturbine|R1|2020|1|0|0|0|0|**0**|\n",
     "|**solarPV**|**R1**|**2020**|**1**|**0**|**0**|**0**|**0**|**0**|\n",
     "\n",
-    "Similar to the the ```CommIn.csv```, we create a new row, and add in the solar commodity. We must ensure that we call our new commodity and technologies the same as the previous file for MUSE to successfully run. ie `solar` and `solarPV`.\n",
-    "\n",
+    "Similar to the the ```CommIn.csv```, we create a new row, and add in the solar commodity. We must ensure that we call our new commodity and technologies the same as the previous file for MUSE to successfully run. ie `solar` and `solarPV`. \n",
     "Please note that we use flat forward extension of the values when only one value is defined. For example, in the `CommOut.csv` we only provide data for the year 2020. Therefore for the benchmark years, 2025, 2030, 2035... we assume the data remains unchanged from 2020."
    ]
   },
@@ -147,15 +148,14 @@
    "metadata": {},
    "source": [
     "Finally, the `Technodata.csv` file contains parametrisation data for the technology, such as the cost, growth constraints, lifetime of the power plant and fuel used. \n",
-    "\n",
     "We will only display the some of the parameters, as the table is too large to display in full. The remaining parameters will be copied from the `windturbine` technology. You can see the full file [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/blob/main/docs/tutorial-code/1-add-new-technology/1-introduction/technodata/power/Technodata.csv), and details about each parameter [here](../inputs/technodata.rst).\n",
     "\n",
-    "|ProcessName|RegionName|Time|Level|cap_par|cap_exp|…|Fuel|EndUse|Agent1|\n",
-    "|-|-|-|-|-|-|-|-|-|-|\n",
-    "|Unit|-|Year|-|MUS$2010/PJ_a|-|…|-|-|New|\n",
-    "|gasCCGT|R1|2020|fixed|23.78234399|1|…|gas|electricity|1|\n",
-    "|windturbine|R1|2020|fixed|36.30771182|1|…|wind|electricity|1|\n",
-    "|**solarPV**|**R1**|**2020**|**fixed**|**30**|**1**|...|**solar**|**electricity**|**1**|\n",
+    "|ProcessName|RegionName|Time|cap_par|cap_exp|…|Fuel|EndUse|Agent1|\n",
+    "|-|-|-|-|-|-|-|-|-|\n",
+    "|Unit|-|Year|MUS$2010/PJ_a|-|…|-|-|New|\n",
+    "|gasCCGT|R1|2020|23.78234399|1|…|gas|electricity|1|\n",
+    "|windturbine|R1|2020|36.30771182|1|…|wind|electricity|1|\n",
+    "|**solarPV**|**R1**|**2020**|**30**|**1**|...|**solar**|**electricity**|**1**|\n",
     "\n",
     "Again, flat forward extension is used. Therefore, as we only provide data for the benchmark year 2020, 2025 and the following benchmark years will keep the same characteristics."
    ]
@@ -172,7 +172,6 @@
    "metadata": {},
    "source": [
     "Next, navigate to the `input` folder.\n",
-    "\n",
     "We must now edit each of the files found here to add the new `solar` commodity. Due to space constraints we will not display all of the entries contained in every input. You can be view the edited files in full [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/tree/main/docs/tutorial-code/1-add-new-technology/1-introduction)."
    ]
   },
@@ -197,7 +196,6 @@
    "metadata": {},
    "source": [
     "The `Projections.csv` file details the initial market prices for the commodities. The market clearing algorithm will update these throughout the simulation, however an initial estimate is required to start the simulation. As solar energy is free, we will indicate this by adding a final column.\n",
-    "\n",
     "Please note that the unit row is not read by MUSE, but used as a reference for the user. The units should be consistent across all input files for MUSE; MUSE does not carry out any unit conversion.\n",
     "\n",
     "|RegionName|Attribute|Time|electricity|gas|heat|CO2f|wind|**solar**|\n",
@@ -423,6 +421,15 @@
     "For the full example with the completed input files see [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/tree/main/docs/tutorial-code/1-add-new-technology/2-scenario)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "In this tutorial we have shown how to add a new technology to the model, and how to modify the parameters of this technology. Have a go at modifying some of the other parameters to see how this affects investment decisions. "
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/user-guide/additional-service-demand.ipynb

@@ -114,12 +114,11 @@
     "|ProcessName|RegionName|Time|cap_par|…|Fuel|EndUse|Agent1|\n",
     "|-|-|-|-|-|-|-|-|\n",
     "|Unit|-|Year|MUS$2010/PJ_a|…|-|-|New|\n",
-    "|gasboiler|R1|2020|3.8|…|gas|heat|1|\n",
     "|...|...|...|...|...|...|...|...|\n",
     "|**electric_stove**|**R1**|**2020**|**8.8667**|**…**|**electricity**|**cook**|**1**|\n",
     "|**gas_stove**|**R1**|**2020**|**3.8**|**…**|**gas**|**cook**|**1**|\n",
     "\n",
-    "As can be seen, we have added two technologies with different `cap_par` costs. We specified their respective fuels, and the enduse for both is `cook`. For the full file please see [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/blob/main/docs/tutorial-code/5-add-service-demand/1-exogenous-demand/technodata/power/Technodata.csv)."
+    "As can be seen, we have added two technologies with different `cap_par` costs. We specified their respective fuels, and the enduse for both is `cook`. For the full file please see [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/blob/main/docs/tutorial-code/5-add-service-demand/1-exogenous-demand/technodata/residential/Technodata.csv)."
    ]
   },
   {
@@ -131,9 +130,9 @@
     "- `CommOut.csv`\n",
     "- `ExistingCapacity.csv`\n",
     "\n",
-    "This is largely a similar process to the tutorial shown in [\"adding a new technology\"](add-solar.ipynb). We must add the input to each of the technologies (gas and electricity for `gas_stove` and `electric_stove` respectively), outputs of `cook` for both and the existing capacity for each technology in each region.\n",
+    "This is largely a similar process to the previous tutorial. We must add the input to each of the technologies (gas and electricity for `gas_stove` and `electric_stove` respectively), outputs of `cook` for both and the existing capacity for each technology in each region.\n",
     "\n",
-    "To prevent repetition of the [\"adding a new technology\"](add-solar.ipynb) section, we will leave the full files [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/tree/main/docs/tutorial-code/5-add-service-demand/1-exogenous-demand). "
+    "To prevent repetition of the previous tutorial, we will leave the full files [here](https://github.com/EnergySystemsModellingLab/MUSE_OS/tree/main/docs/tutorial-code/5-add-service-demand/1-exogenous-demand). "
    ]
   },
   {
@@ -196,8 +195,17 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can see that `electric_stove` is heavily used in the residential sector, and `gas_stove` is barely used at all. Therefore, compared to the default model, there is a larger increase in capacity in the `power` sector to accommodate this increase in demand for electricity, which is largely driven by `windturbine`."
+    "We can see that `electric_stove` is heavily used in the residential sector, and `gas_stove` is barely used at all. Therefore, compared to the default model, there is a larger increase in capacity in the `power` sector to accommodate this increase in demand for electricity, which is largely driven by `windturbine`.\n",
+    "\n",
+    "## Summary\n",
+    "\n",
+    "In this tutorial we have shown how to add a service demand to MUSE, and how to add technologies to meet this demand. Try changing the demand profile for `cook` to see how this influences investment decisions."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
   }
  ],
  "metadata": {

docs/user-guide/min-max-timeslice-constraints.ipynb

@@ -94,11 +94,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Once this has been completed, we can run MUSE as before, with the following command:\n",
+    "Once you've had a look at these files, run MUSE with the usual command:\n",
     "\n",
     "    python -m muse settings.toml\n",
     "\n",
-    "Next, we will visualise the output of the technologies in each timeslice:"
+    "We will then visualise the output of the technologies in each timeslice:"
    ]
   },
   {
@@ -219,8 +219,17 @@
    "source": [
     "As expected, we can see an enforced reduction in `windturbine` output in the 2nd (1) and 3rd (2) timeslices.\n",
     "\n",
-    "From the `MCACapacity.csv` file, we can see that the capacity of `windturbine` in this year is 1. Therefore, the results show that `windturbine` is operating at its maximum permitted level in all timeslices apart from the first, where it's operating below this level."
+    "From the `MCACapacity.csv` file, we can see that the capacity of `windturbine` in this year is 1. Therefore, the results show that `windturbine` is operating at its maximum permitted level in all timeslices apart from the first, where it's operating below this level.\n",
+    "\n",
+    "## Summary\n",
+    "\n",
+    "In this tutorial we've shown had to impose minimum and maximum constraints on the activity of technologies on a timeslice-basis. Not only will this impact the supply of comodities, but it may also influence investment decisions. You are encouraged to explore the implications of this on your own."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
   }
  ],
  "metadata": {

docs/user-guide/modify-timing-data.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Modification of time"
+    "# Modifying the time framework"
    ]
   },
   {
@@ -41,19 +41,19 @@
     "\n",
     "```toml\n",
     "[timeslices.all-year.all-week]\n",
-    "all-year.all-week.night = 1095\n",
-    "all-year.all-week.morning = 1095\n",
-    "all-year.all-week.mid-afternoon = 1095\n",
-    "all-year.all-week.early-peak = 1095\n",
-    "all-year.all-week.late-peak = 1095\n",
-    "all-year.all-week.evening = 1095\n",
-    "all-year.all-week.early-morning = 1095\n",
-    "all-year.all-week.late-afternoon = 1095\n",
+    "night = 1095\n",
+    "morning = 1095\n",
+    "mid-afternoon = 1095\n",
+    "early-peak = 1095\n",
+    "late-peak = 1095\n",
+    "evening = 1095\n",
+    "early-morning = 1095\n",
+    "late-afternoon = 1095\n",
     "```\n",
     "    \n",
     "The total length of the timeslices should add up to 8760; the number of hours in a benchmark year. Whilst this is required, MUSE does not check and enforce this.\n",
     "    \n",
-    "Next, we modify both Residential Consumption files. Again, we put the text in bold for the modified entries. We must add the demand for the two additional timelsices, which we call timeslice 7 and 8. We will also change the demand for `heat` in the existing timeslices.\n",
+    "Next, we modify both Residential Consumption files. Again, we put the text in bold for the modified entries. We must add the demand for the two additional timeslices, which are numbers 7 and 8. We will also change the demand for `heat` in the existing timeslices.\n",
     "\n",
     "Below is the modified ```Residential2020Consumption.csv``` file:\n",
     " \n",
@@ -205,6 +205,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "## Summary\n",
+    "\n",
     "As we add more timeslices or years, the model takes longer to run, but slightly different scenarios emerge. This highlights the trade-off between time granularity and speed of computation. It is up to you to decide what level of granularity is required for your use case."
    ]
   },