A tutorial for creating Westeros multi-node and modeling different trade possibilities

[behnam-zakeri]

This PR adds a new tutorial to demonstrate how a multi-node energy system can be built using the MESSAGEix framework. It shows:

• how new nodes can be added to a model and how data can be populated for those new nodes
• how a trade hub can be represented
• how bilateral trade can be modeled
• role of the message_ix index set "mode" in representing trade links

How to review

• Check out this branch and run the tutorial, and make sure it works without a flaw (error or infeasibility).
• Check the results shown in the tutorial and make sure it makes sense and the text describing the results are correct.

PR checklist

• Continuous integration checks all ✅
• Add or expand tests; coverage checks both ✅ (added this tutorial to those being tested in test_tutorials.py)
• Add, expand, or update documentation.
• Update release notes.

[codecov]

Codecov Report

Merging #683 (a94afc3) into main (ebf17ee) will not change coverage.
The diff coverage is n/a.

❗ Current head a94afc3 differs from pull request most recent head 7918bfd. Consider uploading reports for the commit 7918bfd to get more accurate results

@@          Coverage Diff          @@
##            main    #683   +/-   ##
=====================================
  Coverage   94.9%   94.9%           
=====================================
  Files         42      42           
  Lines       3400    3400           
=====================================
  Hits        3229    3229           
  Misses       171     171           

see 1 file with indirect coverage changes

[glatterf42]

All checks were successful, but the branch was out of date. I rebased the branch so that we can merge it soon, but now the tests might fail due to the removal of codecov from PyPi, which will be fixed by

• Miscellaneous updates for 2023-W15 ixmp#476

[glatterf42]

Great tutorial! It showcases a lot of features and possibilities, which brings it to the more complex tutorials, but all the examples and exercises will enable people to understand it completely. On that note, I would really like to see solutions to the exercises, maybe at the end of the tutorial. That way, even people working through them without guidance at a workshop will be able to tell if they understood things correctly. Some notes:

• The final image, external.JPG, has some text in the top right corner, which seems to be too close to the border as the t from market is hardly in the image anymore.
• In 2.4, Westeros and Essos have the exact same lvl of PRICE_COMMODITY, while Stepstones has a different one. Is that intentional? Essos does import more than Westeros.

Apart from that, this PR looks fine to me and is good to be merged :)

[behnam-zakeri]

Thanks, @glatterf42 for reviewing this and for the useful suggestions. I agree that adding solutions at the end here or somewhere else as key to exercises, in general, will be useful. For this tutorial, the given exercise involves developing a scenario, with the intention to encourage users to do hands-on work. I'm afraid adding that solution here may not encourage users to start coding this.
On your questions:

1. I corrected and re-added the figure, thanks for spotting that issue.
2. Yes, that is correct. The price is determined by the most expensive generator of that commodity, which in this case is the same between the two regions, as the commodity is supplied from one generator to two regions via trade.

[glatterf42]

Maybe you could add a statement like 'Self-supervised learners who would like to see a solution for these exercises: please contact the author.'

[glatterf42]

This might then be ready for merging.

[behnam-zakeri]

Thanks @glatterf42 for reviewing and adding the hint for the exercise. I agree, this can be merged. @OFR-IIASA is that okay?

[glatterf42]

For future reference: @OFR-IIASA confirmed privately that the merge is okay.