Jupyter notebooks

[ta440]

Added a directory with four example notebooks to demonstrate the functionality of Gusto.

[JDBetteridge]

Hopefully changes in #297 fix the above issues

[tommbendall]

I think this looks really nice and I'm really excited for us to have these in Gusto. Thanks so much for doing all of this.

I have a few pernickety comments about style of some particular comments and things we can probably omit -- if you disagree with anything please feel free to ignore it. The main thing that I think would be nice is to add lint checking, which I suspect may highlight some more issues.

I've only looked at the first notebook -- I thought I'd come back to that in case you want to make any changes having used the lint checker.

I was also wondering whether we want to include the mountain notebook? Some of the routines in there aren't that obvious so it might be quite challenging as an introduction. Maybe there's something important in that case that I'm missing though that is helpful!

My final suggestion is about the names of the notebooks. I think the first one is great, the second one could do with some capitalisation to make it look consistent (i.e. Book_2_Gravity_Wave_Vertical_Slice) and finally I think the final one might be best as Book_3_Lowest_Order_Rising_Bubble (or book 4 if you keep the mountain!)

[tommbendall]

I think it would be nice to add the notebooks to the lint checker here, I think just by adding:

@echo "     Linting gusto jupyter notebooks"
@python3 -m flake8 jupyter_notebooks

I expect when you run make lint it will then throw up a bunch of things to change in the notebooks though! But that will help make sure the code is consistent everywhere. One of the main things will be to make sure that we leave a space between the # at the start of a comment and the text after it.

[tommbendall]

I think it would be OK to give the reference in a shorter form since we are giving the link to it, i.e.:
"This is the second test from Williamson et al (1992), "

[tommbendall]

There is a rogue backslash somewhere around here

[tommbendall]

I have a very petty suggestion for how we write the shallow-water equations. I prefer to see the transport term (u.grad)u immediately after the time derivative in the momentum equation (so that you can easily see that together these are the material derivative). For the continuity equation, can we just write
\\eta_t + \\nabla \\cdot [(\\eta - b) \\textbf{u}] = 0?

Please feel free to ignore if you disagree!

[jshipton]

Yes, I agree with grouping the terms in that way and I also think we should try to be consistent with the names in the code - i.e. we use D for the prognostic variable, where D=H+\eta-b.

[tommbendall]

Maybe we could rewrite this as "The second Williamson test case models zonal geostrophic flow. This is a steady-state solution of the shallow-water equations, so the true solution does not change with time."

[tommbendall]

I wonder if we could actually just import pi from firedrake? I think we also might not need to do import sys

[jshipton]

yes, this is probably highlighting that the examples need a bit more tidying...

[tommbendall]

We actually can probably give a clearer directory name -- maybe just:

dirname="williamson_2_intro"

[tommbendall]

I think you don't need this detail -- we've explained the initial condition at the top so I think it's OK to leave this out

[tommbendall]

I think we are embedded in a 3D space so we are specifying all three of the Cartesian components of the velocity. I don't think we need the R/R^2 so maybe you can cancel one out! Presumably the was originally done to make it clear that the final part is sin^2(lat)?

[tommbendall]

Yes it's semi-implicit!

[jshipton]

I suggested the mountain as it demonstrates how to deform the mesh - so maybe not an introductory notebook but a more advanced one!

[jshipton]

Thanks Tim, these are a great start to our notebook resources!

[tommbendall]

I suggested the mountain as it demonstrates how to deform the mesh - so maybe not an introductory notebook but a more advanced one!

Ah OK! Maybe that can be the fourth then? And maybe it should be called Book_4_Flow_Over_A_Mountain

[ta440]

Hi Tom and Jemma, thanks for the feedback! I've made the changes you've mentioned and have added the notebooks to the lint checker, so will see what that comes back with.
Let me know when you change the name of the time-stepper from 'Crank-Nicolson', as I'll need to update the notebooks to compensate.

[tommbendall]

Does this file need deleting?

[JDBetteridge]

Suggested change

	--nbval-lax \
	--nbval \

When you're happy with the state of the notebooks, you can drop the lax and the test will check that the output doesn't change. Use # NBVAL_IGNORE_OUTPUT for specific cells where this is undesirable, see these docs.

[atb1995]

Just a few suggested changes! Open to discussion on them :)

[atb1995]

Overall a description of how the transport terms are treated has been given, but it may be useful to say that implicit terms are treated with an centred or off-centred implicit method, and that the nonlinear solve is a Newton solve with a fixed number of iterations (in a staggered 2x2 loop normally)

[atb1995]

It would be good to have some description of what we are seeing in the plots - and perhaps a comment on the oscillations in the depth perturbation

[jshipton]

Yes, I agree - and I will change the reference plots to be closer to what we're using here...