Feature/tutorial rayleigh benard

[adperezm]

Hi,

I add this "tutorial" of RBC. The idea here was to start from zero and create a mesh and case file from scratch. Compile the user module, run, and then use the data to create an animation.

I guess the question is if something like this is needed in the repository or not. At some point we discussed this sort of tutorials in the user meetings but we also sort of said to do it in markdown. This is a notebook, so not exactly as discussed.

I guess this is opened to create a discussion on whether this type of extra step by step documentation on a case is useful. Let me know.

[adperezm]

I also guess this is not a "feature", so sorry for the name of the branch.

[vbaconnet]

I have to say the notebook format is really nice. I don't think this goes against what we discussed in the user meetings, rather the opposite I would say this is maybe even better than a markdown tutorial.

Perhaps the markdown tutorial version could just be the "non-interactive" version of the jupyter notebook, but I still think we should have both so anyone could still access the tutorials easily through the website, unless there's a nice way to render notebooks with Doxygen?

[timfelle]

I have to say the notebook format is really nice. I don't think this goes against what we discussed in the user meetings, rather the opposite I would say this is maybe even better than a markdown tutorial.

Perhaps the markdown tutorial version could just be the "non-interactive" version of the jupyter notebook, but I still think we should have both so anyone could still access the tutorials easily through the website, unless there's a nice way to render notebooks with Doxygen?

Yes one can indeed get the system to be linked to our documentation. It requires some CI magic to, render the notebook as either a markdown file or a html page, and then link to it from the existing markdown stuff. (nbconvert can do that kind of stuff.)

[adperezm]

Okay that's good to know! I think that if this sort of example is deemed useful, then one thing to discuss is where to keep them. If we start adding more tutorials with plots and the sort, the file sizes start to grow. I don't think we want the Neko clone to be too heavy or am I mistaken?

This particular file is 20Mb, but that's because there is an animation that can't even be seen on GitHub 😅. That can be changed.

[timfelle]

Okay that's good to know! I think that if this sort of example is deemed useful, then one thing to discuss is where to keep them. If we start adding more tutorials with plots and the sort, the file sizes start to grow. I don't think we want the Neko clone to be too heavy or am I mistaken?

This particular file is 20Mb, but that's because there is an animation that can't even be seen on GitHub 😅. That can be changed.

Well one way arround that is to upload a cleaned notebook. Aka, one that is not saved with all the plots constructed. And then let users run it themselves.

Alternatively, we could create a new git repository ExtremeFLOW/tutorials, and then use it when generating our documentation, but it will not be included when someone clones Neko. Adding it as a git submodule would allow users to clone it if they do --recursive clones, but otherwise it will not be there.

[adperezm]

Well one way arround that is to upload a cleaned notebook. Aka, one that is not saved with all the plots constructed. And then let users run it themselves.

That is true! Perhaps the better solution. I was stuck thinking that to render it in the website we need it executed, but this is perhaps not needed.

The other option I like as well. One could potentially just use git submodules and let the user decide if they want extra stuff, like tutorials, pynektools, neko-top, etc.

[timfelle]

Well one way arround that is to upload a cleaned notebook. Aka, one that is not saved with all the plots constructed. And then let users run it themselves.

That is true! Perhaps the better solution. I was stuck thinking that to render it in the website we need it executed, but this is perhaps not needed.

The other option I like as well. One could potentially just use git submodules and let the user decide if they want extra stuff, like tutorials, pynektools, neko-top, etc.

Yes, we need to execute it, just like we do with doxygen. We just dont need to save it to the git repository to do so.

But yea i think that would in general be the better solution, we just need to link to them in some way. Atleast in the documentation.

[timofeymukha]

Very nice work Adalberto! I am wondering if there is some distinction between examples and tutorials? Could this not simply replace the RB examples we have now?

[timofeymukha]

Branching out the examples / tutorials to a separate repo that would allows some heavier files could be something to consider.

[adperezm]

Very nice work Adalberto! I am wondering if there is some distinction between examples and tutorials? Could this not simply replace the RB examples we have now?

Thanks!, They are very similar and I think the example could be replaced as I cleaned this one a bit. The difference of this tutorial is of course that it is cluttered with text that might not be needed and that it being in a notebook makes it harder to run for someone that has not set up python (Which I think might be many people).

If some one already knows how to run neko but just wants an RBC case file to modify and run, then needing to run this script to generate it might be annoying. But I guess that can be a compromise.

[timofeymukha]

I think as long as there is a rendered version of the notebook available, the issue with python is removed, I think. It would be great if our example would all be at this level of detail!

[pschlatt1]

This is great, and I think could be one of the excellent features of neko in terms of usability. Having a good python driver to put together meshes, parameter files and the like is very good, and certainly helpful for the beginners. There will clearly be a challenge to keep all the things updated and in sync (parameters etc.) but at least for some base features this is really helpful.

A few comments:

• I would perhaps also have it in a separate repo, just because of the (potential) size of the tutorials. Ideally, we can include also figures that show how the results should look like. In Nek5000 there is also a separate example repo which we could then have as tutorial repo.
• Jupyter I think is a kinda requirement these days, so I would not worry about people not having access to it. I have used this format as well for tutorials and it really works nicely.
• I really like the way how to create input files using jupyter.
• at the same time, we should be careful to not overengineer these Jupyter scripts. It is a tutorial, and we do not want to require a tutorial for running the tutorials.

[adperezm]

Okay! then I will do as you suggest.

It would be great if our example would all be at this level of detail!

The idea we had in the user meetings was to indeed have several examples like this, although I think not all of them (I remember we discussed 3), but certainly a couple of very detailed ones that showcase core functionalities.

• Ideally, we can include also figures that show how the results should look like.

Indeed in our idea is to have a case such as a channel flow where we can go from 0 to TKE budgets for example. I think this is in our plan. Martin is the project manager on that but this was talked before summer.

• at the same time, we should be careful to not overengineer these Jupyter scripts. It is a tutorial, and we do not want to require a tutorial for running the tutorials.

And I agree. In fact here I was already considering that the pyNekTools stuff was too much. I will probably keep it simple and generate a picture by other, simpler, means.

So I think we all kind of agree on how to proceed:

• I will create another repository that will be public where tutorials will reside. Whether we put a folder with sub-modules in the main Neko repo can be discussed later.
• I will keep using Jupyter notebooks. I guess we will discuss internally if people that might contribute to other tutorials is comfortable with that.
• I will close this PR when I create the other repo. So it will remain open as a draft temporally in case anyone has some comment or wishes to object.

Thank you for the feedback, everyone.

[pschlatt1]

excellent, thank you @adperezm !