Writing tutorial for high level overview of atomate2 concepts.

[QuantumChemist]

Summary

This PR will add a tutorial for atomate2, giving a detailed overview of its key concepts.

• Job and flow makers
• Input sets
• task docs
• builders

TODO Checklist

The following sections have to be added

• [x] Job makers
• [x] Flow makers
• [x] Input sets
• [x] Task docs
• [x] Builders
• [x] checking typos
• [x] revise the text

[QuantumChemist]

For now, I have simply drafted a markdown file.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 76.91%. Comparing base (29a5731) to head (6debd10). Report is 15 commits behind head on main.

:exclamation: Current head 6debd10 differs from pull request most recent head 2de908e

Please upload reports for the commit 2de908e to get more accurate results.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #757      +/-   ##
==========================================
+ Coverage   74.94%   76.91%   +1.96%     
==========================================
  Files         136      122      -14     
  Lines       10513     9108    -1405     
  Branches     1643     1429     -214     
==========================================
- Hits         7879     7005     -874     
+ Misses       2143     1675     -468     
+ Partials      491      428      -63     

see 30 files with indirect coverage changes

[QuantumChemist]

Hey Alex @utf If you can spare some time and don't mind, could you have a look at the first section I added, if this is what you expect the tutorial to be? Does it have to be more detailed or shorter? Are the examples ok like that? Thank you a lot!

[utf]

Hi @QuantumChemist, thanks for making a start on this.

If possible, I would aim to make the tutorial more pedagogical with more emphasis on what the concepts are for rather than delving too much into the code specifics. In general, I imagine that this tutorial will be the first time users are exposed to these concepts, so the main aim is for users to understand why they need to work with these objects and what they achieve, rather than how exactly they work (although this could be included later on in the tutorial).

For example, it could be helpful to have a high level overview at the beginning of the document summarising verbally or graphically how these components interact and form a workflow. You can then give delve into each topic. I would start by giving examples from the atomate2 code and state what is happening in each case. And then if necessary you can give detailed insights into the jobflow source. Although I think this should be minimised as much as possible.

In terms of the writing style and level of detail, I would use the documentation of QuAcc as an example.

[QuantumChemist]

Hi @QuantumChemist, thanks for making a start on this.

If possible, I would aim to make the tutorial more pedagogical with more emphasis on what the concepts are for rather than delving too much into the code specifics. In general, I imagine that this tutorial will be the first time users are exposed to these concepts, so the main aim is for users to understand why they need to work with these objects and what they achieve, rather than how exactly they work (although this could be included later on in the tutorial).

For example, it could be helpful to have a high level overview at the beginning of the document summarising verbally or graphically how these components interact and form a workflow. You can then give delve into each topic. I would start by giving examples from the atomate2 code and state what is happening in each case. And then if necessary you can give detailed insights into the jobflow source. Although I think this should be minimised as much as possible.

In terms of the writing style and level of detail, I would use the documentation of QuAcc as an example.

Ok, thank you so much for the feedback! :)

[QuantumChemist]

Hi @utf ,

I have now adjusted the tutorial text and tried to make it more pedagogical. And I'm very sorry, I was misunderstanding the "high-level overview" part a little bit, and upon looking up the definition, it became clearer to me how the tutorial is supposed to be. I also included a (draft) figure for checking out how that would look like in the tutorial and kept some technical details, as having those helped me a lot in the beginning when I started to work with atomate2. If the current style is ok like that, then I would go on and write the other sections in a similar way and also make proper figures (the one figure is there for demonstration and drafting purposes). If this is not ok, I'd be very happy about more feedback on my text!

[utf]

Hi @QuantumChemist, this looks perfect. Thank you.

[QuantumChemist]

Hi @QuantumChemist, this looks perfect. Thank you.

Great! Then I will continue the rest of the tutorial like that! Thx!

[QuantumChemist]

Hey @utf :) I would say I'm finished with writing the tutorial. Could you give me some feedback? Also, I hope it's okay that I added the tutorial text to docs/user as one single file!

[utf]

This is fantastic. Thank you @QuantumChemist and @JaGeo.

[QuantumChemist]

@utf Thank you as well! 😃

[QuantumChemist]

Hey @utf , I realized I forgot to link this tutorial somewhere, so so far it's only accessible if one knows the full link https://materialsproject.github.io/atomate2/user/key_concepts_overview.html

So I wonder: Shall I fix this in another PR? If yes, shall I link it to the User Guide, also in a way that it shows up on the User Guide sidebar on the left or shall I link it to the welcome page? What do you think would be best?