Merge basic tutorial from docs into basic hands on

[mbercx]

Fixes #238
Fixes #242

This PR is a rather large revamp of the AiiDA basics section of the tutorial, which now starts from the "basic tutorial" from the new AiiDA documentation. In order to still introduce the data types required for the rest of the tutorial, the tutorial continues along the lines of the previous version, but the sections have been restructured significantly, as splitting them up in verdi CLI and verdi shell did not make any sense after we already combine the two in the first part of the section.

My idea was to sort the content by data type and then discuss the the PwCalculation process, its inputs and then outputs in that order. I've tried my best to avoid too much repetition, or added words like "remember that..." to indicate that they've seen this previously. I'm still going to have another pass at this tomorrow with a clearer head, but feel free to already have a look and give suggestions.

Some notes:

• I removed the provenance graph with the inputs only. I didn’t really understand the reason of showing both here, especially straight after each other.
• I moved the groups section to the appendix. This might be more at home in the managing data and querying hands on.
• I've also moved some sections that explore the provenance to the appendix to keep the hands on from getting too big.

Some open issues/questions:

• The basic tutorial from the documentation introduces the computer with label tutor . In the "running computations" hands on, a computer with label localhost is configured. Should we only configure one computer, or is it fine to keep both so they see multiple computers when they execute verdi computer list?
• Currently the hands on is not entirely consistent on the use of e.g. <IDENTIFIER> versus actually providing the PK/UUID in the CLI command/code snippet.
• It might be better to move the outputs section to the "running computations" hands-on, where they can explore the outputs of the calculations they just ran.

[chrisjsewell]

thanks @mbercx, I've also linked a number of issues that I think this should close, but maybe have a check if this is the case

[mbercx]

Thanks @chrisjsewell for the review! I've applied all of your suggestions, save for some unresolved conversations.

@ltalirz or @giovannipizzi: Considering the large number of changes, it would be great if you could have a look at the whole section and see if you agree with the content and structure.

[chrisjsewell]

I've applied all of your suggestions

You still haven't figured out how to run pre-commit though have you 😜

[ltalirz]

@mbercx Thanks a lot for all this work!

I will first need to go through the plugins/code setup howtos before going through this section in-depth, but let me give some initial feedback already now:

• I think the structure you chose it not a bad one, but logically I would prefer to keep the "AiiDA basics" section to just the basic tutorial, name the second section "Quantum ESPRESSO example", and have it contain both the data analysis and calc execution aspects.

  You may worry a bit about the relative length of both sections in this case. I would argue that this is not an issue.
  The first section is the most important one, and people will spend a lot of time getting stuck at seemingly simple, minor issues.
  Plus, people who finish quickly can just go ahead with the second one.

Note: You might want to add a comment in the "AiiDA basics" section to mention that it is taken from the basic aiida tutorial (even if just for us to remember in the future)

• In the QE example, don't be shy to remove things that you consider duplication.
  E.g. explanations on graph generation, explanation of identifiers etc.

I moved the groups section to the appendix. This might be more at home in the managing data and querying hands on.

I agree that this information can be moved to data/querying, but in that case please move it there.
Groups are an important tool and deserve to be mentioned outside appendices.

I've also moved some sections that explore the provenance to the appendix to keep the hands on from getting too big.

One thing I am missing is the interactive provenance exploration using the Materials Cloud provenance explorer.
I think this should be reinstated (wherever it makes sense).

The basic tutorial from the documentation introduces the computer with label tutor . In the "running computations" hands on, a computer with label localhost is configured. Should we only configure one computer, or is it fine to keep both so they see multiple computers when they execute verdi computer list?

Ideally it would be the same computer (unless we can think of an educational reason to create a second one. It might confuse participants ("do I need to create a new computer for every code?")). If we don't manage to change it, it's ok to leave it.

Currently the hands on is not entirely consistent on the use of e.g. versus actually providing the PK/UUID in the CLI command/code snippet.

I don't consider it mandatory to be 100% consistent on this.
I'll keep an eye on it when I go through the tutorial.

It might be better to move the outputs section to the "running computations" hands-on, where they can explore the outputs of the calculations they just ran.

If you know where to place them, please do. I fully agree.

[ltalirz]

P.S. Just to provide some context as to the previous structure of the QE example:
The reason we didn't start with running calculations but with the analysis of existing data (not very sexy) was that running an external code was considered more difficult to get started with -- originally there was no --config option, and computer setup + code setup was error-prone (we let users go through the interactive prompts); plus there was the whole provenance concept to grasp etc.

Since the basic tutorial from the aiida-core docs now manages to introduce all these concepts in a straightforward manner, there is really no compelling reason anymore to keep this order, and so for the "QE example" I am all for integrating the 'data analysis' into the 'running computations' part wherever possible.

[ltalirz]

List of things to check:

• Add a comment in the "AiiDA basics" section to mention that it is taken from the basic aiida tutorial (even if just for us to remember in the future)
• search for "this tutorial" in the section copied from the docs and replace with the appropriate section name
• replace link to (missing) appendix for computer setup with a link to the aiida-core docs after DOCS: Add computer and code setup how-tos aiida-core#4216 is merged
• I added some minor fixes in https://github.com/ltalirz/aiida-tutorials/tree/basics-revamp
• try to find a place where to mention groups done in Improve "Working with data" section #231
• try to find a place where to show the MC provenance explorer

[ltalirz]

as discussed with @mbercx I think this is good to go - remaining items on the checklist can be handled in a separate PR

[mbercx]

I opened #248 to keep track of the remaining items for the basics section.