✨ NEW: Module on troubleshooting calculations

[ramirezfranciscof]

I took the content of the former running computations section that was
specific for troubleshooting errors and created a new module for it.

It includes:

1. An introduction with a warning of the previous knowledge required,
   together with a link to the section where to get it.

2. A setup subsection where they prepare the calculation; I propose to
   use the builder of pw and give them the faulty input parameters, but
   setting up the structure, kpoints and pseudo is left as exercise.

3. Dry run to simulate the submission.

4. Troubleshooting an error: check the process status, the logs, the
   output, and the inputs.

5. Restarting the calculation using get_builder_restart.

Closes #354

[ramirezfranciscof]

@mbercx : In the end you didn't create any issues for the running calculation sections, right? Not necessary since we met and discussed, just making sure I was not ignoring some important indications that I missed.

@CasperWA hey you are my session buddy, take a look, I meid dis.

[ramirezfranciscof]

Comments on the general structure, content, or specifics apart: I think we can probably all agree that it is ok to have here the dry run, the verdi process report and the get_builder_restart, but I would like to know if you agree that this is also the place for the outputcat and inputcat/inputls (in which case I will also later remove them from the calculations/basic section). I think this is ok since the reason why one would like to take a look at the input and output files is typically related to troubleshooting.

[mbercx]

Thanks, @ramirezfranciscof! I just had a quick look, and it already looks great! Will leave a detailed review to @CasperWA, but to answer your questions:

In the end you didn't create any issues for the running calculation sections, right? Not necessary since we met and discussed, just making sure I was not ignoring some important indications that I missed.

No, you're right! I wouldn't want to deprive you of the satisfaction of closing an issue, so I opened #354. 😁

[...], but I would like to know if you agree that this is also the place for the outputcat and inputcat/inputls (in which case I will also later remove them from the calculations/basic section). I think this is ok since the reason why one would like to take a look at the input and output files is typically related to troubleshooting.

I think it's indeed a good idea to show them the error in the QE stdout using outputls/outputcat. However, I'm not sure if it's needed to remove the parts where they are used in the calculation/basic section. There the purpose was to get more details on a successful run (which I think is also a valid use case), here it's to debug. I think it's fine to show the two use cases, it's not really repetitive, but rather reminds them of this command.

[ramirezfranciscof]

I think it's indeed a good idea to show them the error in the QE stdout using outputls/outputcat. However, I'm not sure if it's needed to remove the parts where they are used in the calculation/basic section. There the purpose was to get more details on a successful run (which I think is also a valid use case), here it's to debug. I think it's fine to show the two use cases, it's not really repetitive, but rather reminds them of this command.

Mmm yeah I see what you mean. It is true you may want to check some stuff directly from the output, but I still have the feeling that 99% of those checks are "debug related" checks. For general status you just check the verdi process list (and only check the output if there is a problem there), and all the useful data from a successful run is supposed to be on the output nodes (I would argue that if there is something you need to be checking on the output file after a successful run, you probably have a good case for requesting the plugin developer the option to include that in an output node).

There is also the matter of "flow" of the tutorial: I agree using repetition strategically can be good, but also we need to be careful because too much also confuses people (I think we had some complaints in this direction last tutorial, no?). I would perhaps save that for more critical concepts; let me see how the section looks like when I remove that, if you still don't like it I can always put it back.

[mbercx]

Mmm yeah I see what you mean. It is true you may want to check some stuff directly from the output, but I still have the feeling that 99% of those checks are "debug related" checks. For general status you just check the verdi process list (and only check the output if there is a problem there), and all the useful data from a successful run is supposed to be on the output nodes (I would argue that if there is something you need to be checking on the output file after a successful run, you probably have a good case for requesting the plugin developer the option to include that in an output node).

I agree that typically you wouldn't get your results using these commands, but again: a tutorial isn't meant to always show you the 'correct' way to do things. I think it's still good for them to also have a look at the (probably familiar) QE stdout.

There is also the matter of "flow" of the tutorial: I agree using repetition strategically can be good, but also we need to be careful because too much also confuses people (I think we had some complaints in this direction last tutorial, no?).

Actually, based on the feedback, the vast majority of participants of last year did not thing there was too much repetition in the tutorial material, so I wouldn't worry too much about it.

[ramirezfranciscof]

@CasperWA 😬

[CasperWA]

@CasperWA grimacing

Chill, dude.

[CasperWA]

Looks good.

There are some issues with "you" versus "we" though. I think the "we" perspective is from the original text and you've used "you". Choose one. Indeed, one of these perspectives should be chosen for the whole tutorial. I personally would go for "you", since it feels less disrespectful when reading it...

There also something about Node versus node. I'm not completely sure about this, though?

[mbercx]

There are some issues with "you" versus "we" though. I think the "we" perspective is from the original text and you've used "you". Choose one. Indeed, one of these perspectives should be chosen for the whole tutorial. I personally would go for "you", since it feels less disrespectful when reading it...

Good point, probably best to give this some thought and then try to be consistent throughout the tutorial! I've opened #360 for this.

[mbercx]

Sorry, accidentally touched my touch pad with the palm of my hand as I was hovering over the "Close" button 😅

[CasperWA]

Also, going through my sections I see that we now more commonly use node and not Node. This should then be done for all pages, only using the capitalized version if one is discussing/mentioning the actual Python class name.
Mentioning @mbercx and @chrisjsewell as well for this point.

[mbercx]

Also, going through my sections I see that we now more commonly use node and not Node. This should then be done for all pages, only using the capitalized version if one is discussing/mentioning the actual Python class name.

Fair point! Have opened #361 for this so I keep it in mind as I'm giving a pass to all sections.

[ramirezfranciscof]

@CasperWA thanks for the thorough first pass! I think I have now addressed all points (+rebased the branch) and it is ready for a second go.

[CasperWA]

Ready to be re-reviewed or?

[ramirezfranciscof]

Ready to be re-reviewed or?

Ah sure. Since I just accepted all the modifications I assumed that would be it but if you have more comments let them come. The only thing remaining is the PK correction which I'm only waiting for @mbercx to confirm if I open a new issue or use the existing one.

[CasperWA]

Ready to be re-reviewed or?

Ah sure. Since I just accepted all the modifications I assumed that would be it but if you have more comments let them come. The only thing remaining is the PK correction which I'm only waiting for @mbercx to confirm if I open a new issue or use the existing one.

Just make a new one.

[ramirezfranciscof]

Ba-dam done, feel free to re-re-review @CasperWA .

[CasperWA]

I think this is fine when the final correction here has been implemented.

[mbercx]

The only thing remaining is the PK correction which I'm only waiting for @mbercx to confirm if I open a new issue or use the existing one.

Sorry, I hadn't noticed the "new" mention. 😅 But yeah, opening a new issue is good 👍