Add Vertical Advection design document

[brian-oneill]

This PR adds the design document for the vertical advection module. Compiled here.

Checklist

• Documentation:
  • Design document has been generated and added to the docs
  • Documentation has been built locally and changes look as expected

[cbegeman]

Can you clarify somewhere the relationship between your "Core data arrays" and the variables in the Algorithm section? I think I understand VerticalTransport to correspond to $\tilde{W}_{tr}$ but I don't understand why that is a 2-d array. Is VerticalFlux intended to hold either $U \tilde{W}_{tr}$ or $\phi \tilde{W}_{tr}$?

[cbegeman]

The description of VertAdv::computeVerticalTransport sounds to me like it's computing $\tilde{w}$, but I think we've been using the word "Transport" to denote $\tilde{W}_{tr}$. Can you clarify where we're computing each and whether both will be available for output?

[brian-oneill]

@cbegeman Looking again at the V1 equations document, there is a table where VerticalTransport is used for mass flux, and VerticalVelocity is the velocity, so I'll rename the array here to VerticalVelocity (for $\tilde{w}$). VerticalFlux is just intended for tracer fluxes (specifically the high-order fluxes in FCT, and in the standard vertical advection algorithm there is only one flux array needed).

My initial thoughts were to just modify VerticalVelocity in place to include the corrections (for moving coordinate, projection of normal velocity, etc). If we want to store $\tilde{w}$ and $\tilde{W}_{tr}$ separately to allow for output of both quantities I can add a TotalVerticalVelocity member array. As for the actual computation of these corrections, I haven't worked out that implementation yet. For the initial PR, I was planning to assume $\tilde{W}_{tr} = \tilde{w}$.

[cbegeman]

@brian-oneill Thanks for clarifying. I think it would be helpful to be explicit in the document with math notation where you are solving for each. The assumption of no vertical coordinate motion seems fine, but it would probably be helpful to specify that in a few places in the document as well. I haven't given this a lot of thought to say whether modifications in place is the best way forward, but it does seem like adding the projection of the normal velocity to VerticalVelocity could lead to confusion.

[sbrus89]

This looks good @brian-oneill, I just have a couple comments.

[sbrus89]

@brian-oneill, do you want to make any changes to this based on any outstanding review comments? Let me know and we can get it merged soon.

[sbrus89]

I just realized you're the assignee on this one.

[xylar]

@sbrus89, unless something changed, @brian-oneill doesn't have merge permission. Someone should fix that (I don't have that level of permission) but for now maybe you can merge.

[cbegeman]

@brian-oneill Thanks for providing those clarifications in the text!

[sbrus89]

This looks good to me. Thanks @brian-oneill!

[sbrus89]

@vanroekel and @mark-petersen this is ready to go if you both approve.