Add clarification in Docs

[navidcy]

[moved here from https://github.com/FourierFlows/GeophysicalFlows.jl/issues/132; thanks @francispoulin]

Some thoughts on the docs. Please ignore whatever you like, since you are the experts of ourse.

• Home: In the overview you could menton that you have a lot of geophysical exams written to date but it's easy to generalize this to other PDEs.

• Installations instructions: Maybe add that yo press backspace or control-C to leave this environment afterwards? I had to look that up being a newbie.

• Code Basics: In first sentence after first equation maybe say that sometimes it is better to put linear terms in the nonlinear part depending on the efficiency of the solvers (or something else?). I'm thinking about the linera SW problem where you do this because presumably the solver is faster. Maybe mention that in most systems L is a 1D array, so a vector? Typo? Suggest: For example, if u has only **l depends only in one spatial dimension, In the range of k maybe put a cap fo n_x/2 -1 or something? Since it's necessarily finite.

• Grids: I did run this by mostly copying and pasting. Sadly, I couldn't figure out how to get \partial_x. I got the partial but the subscript eluded me. I admit that I find the ldiv! confusing, not knowing Julia, yet. Interesting, and suprising to me, that you recover \partial_x u by using a system solve but great that you can do this!

• Problem: I would just add the using in the same block before "nx, Lx ..." and mention that because Julia wants to be efficient, you need to load in functions when you need them. Or something to that affect. It's great that Julia gives you the output after grid = OneDGrid(nx, Lx). What is this called?
  Can you say a sentence as to why you use struct? In Python I presume you would use classes, but I could be wrong. I think it's great how you have it so nearly structured by the way! I was wondering about the definition of struct and found this "It is possible but tedious to define two structs, where one extends the other by extra fields. The relationship between the two is then made clear with an abstract and <: declaration." Maybe paraphrase this or something to explain a bit of what you are doing? Maybe mention what time steppers are currently avaible or mention a couple? I like the clock feature! I presume three is a way to list the variables in prob.vars. Can you state that? This case there is only u and uh, but in SW there would be several. You direct the reader to Diffusion in src but I don't see it there. Should it be?

• GPU: Here you have "using" which is great!

• Examples Type "For this problem Vars includes the representations" Are Aphys and Atrans place holders or do they mean something in particular? You have all the equal signs lined up except for in the block after "Construct the structs and you are ready to go!". Do you want to align those?

[navidcy]

hey @francispoulin, sorry for slacking on this.

Regarding,

In the range of k maybe put a cap fo n_x/2 -1 or something? Since it's necessarily finite.

I disagree that k is finite at that point. If x ∈ [0, L] then the allowed wavenumber are k = (2π/L){0, ±1, ±2, ...}. It's only when x becomes discrete, i.e., x = (j-1)2π/L, j=1,...,n that only n of the above wavenumber are independent and thus the sum should be capped.

[navidcy]

PR #221 dealt with some of the issues regarding Grids section

[navidcy]

Maybe mention that in most systems L is a 1D array, so a vector?

L has the same dimensions as prob.sol it's not really 1D most of the times.

[navidcy]

It's great that Julia gives you the output after grid = OneDGrid(nx, Lx). What is this called?

Actually this is custom made way to show the Grid struct. See

https://github.com/FourierFlows/FourierFlows.jl/blob/d664b6a05dbcaf89a1dac3cf9e5c63bc8657dcda/src/domains.jl#L398-L426

[navidcy]

You direct the reader to Diffusion in src but I don't see it there. Should it be?

It's there: https://github.com/FourierFlows/FourierFlows.jl/blob/d664b6a05dbcaf89a1dac3cf9e5c63bc8657dcda/src/diffusion.jl#L1

[navidcy]

I presume three is a way to list the variables in prob.vars. Can you state that? This case there is only u and uh, but in SW there would be several.

I don't understand exactly what you mean. Even in this example there are already 2 variables in vars: u and uh. Do you think a clarification is needed?

[navidcy]

Are Aphys and Atrans place holders or do they mean something in particular?

This are parametric types so that, e.g., u can be of type Array{Float64, 2} or Array{Float32, 2} or even CuArray{Float32, 2}... Some explanation is needed. But perhaps it'll come a bit too much at this stage? @glwagner what do you think?

[francispoulin]

hey @francispoulin, sorry for slacking on this.

Regarding,

In the range of k maybe put a cap fo n_x/2 -1 or something? Since it's necessarily finite.

I disagree that k is finite at that point. If x ∈ [0, L] then the allowed wavenumber are k = (2π/L){0, ±1, ±2, ...}. It's only when x becomes discrete, i.e., x = (j-1)2π/L, j=1,...,n that only n of the above wavenumber are independent and thus the sum should be capped.

True for this early stage. Maybe you could add a sentence pointing that out? I think it could help the reader when moving from the continuous to the discrete versions of the equations, which you guide them through in the docs.

[francispoulin]

I presume three is a way to list the variables in prob.vars. Can you state that? This case there is only u and uh, but in SW there would be several.

I don't understand exactly what you mean. Even in this example there are already 2 variables in vars: u and uh. Do you think a clarification is needed?

Sorry I was unclear. I guess I was thinking far into the future, maybe too far, and thought given a model the reader might want to know what fields are contained in the models. Yesterday, I learend that you can do something like keys(fields(model)) and that gives you a list of all the fields in model. This is something that I wanted to know back whwen I read it first, but I am not convinced this is a general concern.

[francispoulin]

Are Aphys and Atrans place holders or do they mean something in particular?

This are parametric types so that, e.g., u can be of type Array{Float64, 2} or Array{Float32, 2} or even CuArray{Float32, 2}... Some explanation is needed. But perhaps it'll come a bit too much at this stage? @glwagner what do you think?

I agree that you don't want to burdern the reader with all of the information. I don't think you need to change anything here.

[francispoulin]

Thanks @navid for the thoughtful reply, it is appreciated. I do look forward to getting back to FourierFlows after I have some shallow water stuff running on Oceananigans. I'd like to get a Shallow Water version in both, but we will see how that goes.

I am happy for you to close this issue whenever you like. It has been very helpful for me and do appreciate it.

[navidcy]

hey @francispoulin, sorry for slacking on this. Regarding,

In the range of k maybe put a cap fo n_x/2 -1 or something? Since it's necessarily finite.

I disagree that k is finite at that point. If x ∈ [0, L] then the allowed wavenumber are k = (2π/L){0, ±1, ±2, ...}. It's only when x becomes discrete, i.e., x = (j-1)2π/L, j=1,...,n that only n of the above wavenumber are independent and thus the sum should be capped.

True for this early stage. Maybe you could add a sentence pointing that out? I think it could help the reader when moving from the continuous to the discrete versions of the equations, which you guide them through in the docs.

Done.