Finish BuildME tutorial in jupyter notebook

[kamilakrych]

As requested by Niko, I have created a simple tutorial walking (available in my branch here) through the main steps of BuildME. Could you please have a look at it and give some feedback? E.g. does the code work for you, are the explanations clear? There is one part missing at the very end, it's either to be deleted altogether or to be extended by some comments explaining the points I mention there.

• [x] @nheeren: decide what to do with the last part of the tutorial
• [x] @nheeren review the tutorial
• [x] @shnkn review the tutorial
• [ ] @anistad review the tutorial

Charles, if you want to have a look at it, your feedback is also more than welcome! I cannot mention/tag you though :)

[CBreton026]

Hi @kamilitsa!

I haven't tried to run the tutorial yet, however it seems very interesting; I especially liked the part on apply_obj_name_change(). As far as I know, the use of the 'replaceme' strings wasn't explained anywhere (yet).

I'll try to run it when I have some time!

[kamilakrych]

Thanks for the quick reply :) Just one more thing, I have slightly improved the calculate_materials() function. The tutorial won't work unless you update it as well - see this commit

[nheeren]

Thank you so much @kamilitsa. A lot of students will love you for this ;) @CBreton026, you were mentioning at some point that you were making some notes on using BuiildME, so maybe we should discuss if your notes should integrate with tutorial notebooks.

[CBreton026]

Good idea! I'll keep it in mind.

[CBreton026]

Hi @kamilitsa, I just thought of a potential issue - what climate files / paths are used for the tutorial? Since the Meteonorm files were removed from the repo, anyone new to BuildME may have trouble running the tutorial "out of the box". It's a problem I also encountered when starting, as well as when running tests.

My suggestion would be that we add the EnergyPlus TMY3 climate files to the repo (or at least one of them) so that it's easy for anyone to start the tutorial.

[nheeren]

The notebook is great ! Thank you!

Here are a few improvements I would suggest:

• [x] Move notebook to ./docs/notebook and fix paths
• [x] Mention in the beginning that this is basically walking the user through main.py
• [x] SectionSelection of archetypes: Explain the files that need to be present (1A.epw, SFH.idf, etc.) and that they come with BuildME or need to be downloaded in case of the climate files. We can refer to https://github.com/nheeren/BuildME/blob/master/docs/setup.md
• [x] define debug_combinations in a way that a few combinations are created. The current variable will yield only one single combination.
• [x] Explain a bit the result the user receives in the last two steps

Concerning the open questions:

• I would stick to MJ, because e+ uses that. Why is kWh more natural? It depends a bit on the region.
• I would not add much more than that. This tutorial is meant to help people get started. Everything else I would consider 'advanced use' and they need to start looking into the code.

Will you do the next iteration, @kamilitsa ?

[shnkn]

I agree, it works perfectly.

Honestly, I still do not know what the divide_by_area, disaggregate_scenario_str, and weighing_climate_region do detailly, so I agree with Niko that these might be a bit too complex for beginners.

So maybe for the material intensity calculations, giving more information about the included building components would be good (i.e., window frame, external wall, internal partitions, roof, floor, door, shading device? etc. ).

Apart from that I do not have any other suggestions :)

[kamilakrych]

Thank you for all the insightful suggestions! I have implemented all of them, you can have a look in my branch.

Just one follow-up comment: I have added a 'dummy' weather file, as suggested by Charles. This way the user can perform the simulations even if no weather files are created. However, to use the full functionality of the framework, the user would need to add the weather files. Maybe it should be mentioned in the setup file?

[kamilakrych]

tutorial finished, added mention of weather files in the setup file