Data - Querying

[CasperWA]

The two commits represent the following:

1. Syntax change: One sentence per line.
2. Minor content changes:
   • Use query instead of qb.
   • Update perspective/tense according to 👌 IMPROVE: Use consistent tense/perspective throughout tutorial #360.

I have a few open questions still:

• In this section AiiDA was always written encapsulated in back ticks (`), I've changed this, but maybe it should be in bold or?
• This seems to be directly taken from a notebook - will it be rendered as a notebook? This is all very confusing!
• How/When do/should I use {ref}'something<some:reference>' versus something?
• How about appendix references? There is one appendix reference here that leads to the 2020 tutorial?
• For the last section it mentions "virtual machine script"? What does that mean? There doesn't seem to be anything wrong with following the note, downloading and importing the data and then continuing on with the exercise?
• How does one actually put in internal and external references? Do we have a "cheat sheet" for the new type of syntax?
• At some point $-TS$ is mentioned (in the last section), what is that? Is that a mistake?

[chrisjsewell]

Heya, so the actual commit changes you made look good cheers 👍

But to quickly answer some questions (and I will look into the others):

This seems to be directly taken from a notebook - will it be rendered as a notebook? This is all very confusing!

So yes myst-nb converts it to a notebook (as explained here: https://myst-nb.readthedocs.io/en/latest/use/markdown.html), and you can also do this manually using jupytext, basically install it then: jupytext --to notebook querying.md.

BUT, at present because executions is turned off, you don't get any outputs 😬:

aiida-tutorials/docs/conf.py

Line 398 in 51b065d

jupyter_execute_notebooks = "off"

It was using this script before: https://github.com/aiidateam/aiida-tutorials/blob/tutorial-2021-intro-week/docs/scripts/make_notebook.py, together with the makefile:

aiida-tutorials/docs/Makefile

Line 19 in 51b065d

IPYNB_TEMPLATE_PATTERNS = \

, but I guess some of the change @mbercx has made, has stopped this from "activating".
I will look into that.

How/When do/should I use {ref}'somethingsome:reference' versus something?

I would generally always use the latter

How does one actually put in internal and external references? Do we have a "cheat sheet" for the new type of syntax?

Most of this is noted in https://github.com/aiidateam/aiida-tutorials/wiki/Moving-to-using-MyST-Markdown; with https://jupyterbook.org/reference/cheatsheet.html and https://github.com/executablebooks/rst-to-myst being two resources for conversion

[mbercx]

• In this section AiiDA was always written encapsulated in back ticks (`), I've changed this, but maybe it should be in bold or?

No, removing the backticks is consistent with the rest of the tutorial 👍

• This seems to be directly taken from a notebook - will it be rendered as a notebook? This is all very confusing!

@chrisjsewell is on that. 😁

• How/When do/should I use {ref}'something<some:reference>' versus something?

I'd use {ref} as much as possible, since they use the internal targets that we specify using e.g. (workflows-workchain)= (see the MyST docs for more details). For external links, I've written down my preferences in the wiki. @chrisjsewell why would you prefer the Markdown syntax for internal (or intersphinx) references?

• How about appendix references? There is one appendix reference here that leads to the 2020 tutorial?

This appendix has not been added yet. I'll look into reinstating the appendices (#379), but you can remove that line for now.

• For the last section it mentions "virtual machine script"? What does that mean? There doesn't seem to be anything wrong with following the note, downloading and importing the data and then continuing on with the exercise?

You mean the note that imports the data? This one is only necessary in case they haven't imported the archive in the "Organising your data" section yet. I'd rephrase this as follows:

:::{important}
This section relies on a specific dataset of previously run calculations.
If you have already imported the data set from the "Organising your data" module, you should be good to go!
If not, you can use the following command to import the required calculations:

```{code-block} console
$ verdi archive import https://object.cscs.ch/v1/AUTH_b1d80408b3d340db9f03d373bbde5c1e/marvel-vms/tutorials/aiida_tutorial_2020_07_perovskites_v0.9.aiida
```

:::

So, put this at the start of the section, and then just continue with "In this part..."

• At some point $-TS$ is mentioned (in the last section), what is that? Is that a mistake?

Since he wrote the content, @chrisjsewell would know for sure, but that looks like the entropy contribution? The $ notation looks weird though. 😅

@chrisjsewell: would be good if we can still fix the notebook execution issue by tomorrow. If you do not have the time, I'll try and fix it on Sunday.

[CasperWA]

I've implemented some of the obvious corrections here, but maybe some are missing? (See the last commit.)
Out of time now - sorry :/

[mbercx]

I've implemented some of the obvious corrections here, but maybe some are missing? (See the last commit.)
Out of time now - sorry :/

[mbercx]

These all LGTM! 🚀 Thanks @CasperWA, I'll test the section anyways, so will give it a pass then.