Improve the tutorials

[tsmbland]

Description

This makes a number of improvements to the example models and tutorials, which I would summarise as follows:

• Modify the tutorials so they can be attempted in any order. Previously the tutorials built on each other sequentially, which led to some interesting scenarios, but also complicated things and made them less accessible. This way, if a user has problems with one tutorial (or just wants to skip it), they can still attempt later tutorials.

• Re-order the tutorials. In line with my plans for the open university course

• Tidy up the text in the tutorials. Removing inconsistencies, cleaning up convoluted language, etc.

• Relax growth constraints in the example models. I think it's better to have looser growth constraints in the default models, as users are less likely to run into GrowthTooConstrained errors as they build on the default models, and it also means that the behaviors observed are more likely to do with the different costs of technologies rather than capacity limits, which I think is a bit more interesting and realistic.

• Remove unnecessary output files. I think for most users the MCACapacity and MCAPrices files are enough to get started, so any other outputs have now been removed from most of the example models. This tidies up the repo, and gives users a cleaner starting point from which to customise their models, rather than giving them a load of unnecessary files by default. I give an example of how to add an extra output in the min-max-timeslice-constraint example. Also, some of the models used outputs that we are encouraging users not to use (MCAMetric_Supply, etc.), so I've gotten rid of these.

Existing issues/to do:

• For the open university course, we will need to create a pdf for each tutorial. Not sure the best way to do this. Probably worth having a fuller discussion about this, and implications for structuring the OU course repo (e.g. do we include the notebooks in that repo too? how to deal with relative links in the notebooks?). Or can we just provide links to the documentation in the course?

• Some of the tables are too wide. In the HTML documentation, they just end up spilling off to the side, which is ok but looks a bit ugly. In the PDF, things end up getting pushed over to multiple lines or chopped off, which isn't any better. Need to figure out how to reduce the font size in the tables or get rid of white space.

• Strange behavior in the multi-region model in tutorial 3. The residential sectors are very different between the two regions, but the gas and power sectors are identical, despite a different gas/electricity mix required in the residential sector. I need to characterise this a bit more, but it looks like there's a bug here.

• The timeslice model has dispatch_production = "costed" for the power sector. It's not explained in the tutorial why this is done and what this means (and there's not much about this anywhere in the documentation).

There's a lot going on in the diffs, so in terms of reviewing, just confirm that you're ok with the changes described above, and if you'd like to take a glance at the new tutorials, you can do so here

Fixes #264

Type of change

Please add a line in the relevant section of
CHANGELOG.md to
document the change (include PR #) - note reverse order of PR #s.

• New feature (non-breaking change which adds functionality)
• Optimization (non-breaking, back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (whatever its nature)

Key checklist

• All tests pass: $ python -m pytest
• The documentation builds and looks OK: $ python -m sphinx -b html docs docs/build

Further checks

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[dalonsoa]

Looks good to me. A lot of simplification for new users, which is good to help them getting started.

About the pending issues, what are your plans about those? Are there issues open?

For the tables in Sphinx, I've found the following. Not sure if it will solve your issue, but might help or point you in the right direction. Not sure if it will affect the PDF output, as that's handled with Latex. https://kallimachos.github.io/docs/sphinx/rtd-tables.html

[tsmbland]

About the pending issues, what are your plans about those? Are there issues open?

I've added #473, #474 and #475

For the OU course, I think it would be worth having a chat at some point as as I'm a bit unsure about the best approach. We basically need a PDF for each of the exercises in the course, all of which can directly (or with very small changes) use pages that already exist in the MUSE documentation.

Probably the easiest thing to do would be to create these PDFs from with in the MUSE_OS repo, and manually add them to the muse_teaching_kit repo. However, I imagine there could be better approaches, possibly involving git submodules, where we could pull the appropriate files into the muse_teaching_kit repo and build the PDFs there.

There are also subtleties like making sure links work

[dalonsoa]

Why do you need PDFs for, anyway? For what I can see in the teaching kit, everything is HTML, so why not using the examples and tutorials as they are? We can discuss exactly how to best do that and avoid duplication, but my point is that PDFs seem an unnecessary complication.

[tsmbland]

Why do you need PDFs for, anyway? For what I can see in the teaching kit, everything is HTML, so why not using the examples and tutorials as they are? We can discuss exactly how to best do that and avoid duplication, but my point is that PDFs seem an unnecessary complication.

Good point. The exercises in the course are currently written in markdown, and then converted to both HTML and PDF. Currently the PDFs are what appears in the course online, although I imagine HTML could be used as well. So yeah, I agree that would be better