JOSS paper

[navidcy]

Hey co-contributors,

I have a first draft of the JOSS paper in JOSS-paper branch. The compiled pdf can be downloaded from:

http://res.cloudinary.com/hju22ue2k/image/upload/v1611563203/emcv5133bs7h8hiw5yzs.pdf

Have a look -- any suggestions welcome! I'm not saying it's ready to go but it's perhaps a good time to hear what everybody thinks? Feel free to edit and submit a PR. Check your affiliations... If you edit and you wanna see the compiled version of the changes you made then you can do so here: https://whedon.theoj.org

cc @glwagner, @liasiegelman, @BrodiePearson, @apaloczy

(P.S.: @apaloczy I don't recall hearing back from you. I'm very excited to include you in the co-authors list, but if I don't hear anything back from you the time of submission I'll assume you don't wanna be part of it.)

[apaloczy]

Hi everyone,

Thank you very much for including me in the discussion, I've just read the
JOSS draft and would be very excited to be part of it if you think I can
contribute. Just to clarify, the idea is to have this JOSS paper be a short
note on the capabilities of GeophysicalFlows.jl, correct? Would we want to
include just this one example of the Eady problem or do we have room for
maybe two or three examples?

[navidcy]

JOSS papers are usually very short (1-2 pages); e.g. https://joss.theoj.org/papers/10.21105/joss.02018 or https://joss.theoj.org/papers/10.21105/joss.01043). Some have some more examples. But note that as part of the review process the reviewers look at the package's documentation. There are lots more of examples there!

[BrodiePearson]

Thanks for pulling this together Navid! I made some suggestions and submitted a PR #189 with the pdf here.

I haven't submitted to JOSS before, so I hope I didn't add too much...

[navidcy]

Thanks all.

Some questions for you to ponder on:

• Should we add anything regarding performance? Perhaps point to the (bit outdated) https://github.com/FourierFlows/BenchFourierFlows.jl? Personally I'd rather refrain from doing that because we enter into the loop hole of how do you compare two codes on equal basis, some are MPI-parallelized, some are multi-threaded, GPU-enabled, etc...

• Does the last paragraph reads a bit out of place? I added it because JOSS mentions that the paper should include "A list of key references, including to other software addressing related needs." Could we smooth it a bit you reckon?

• I'm not sure about the last paragraph regarding "ongoing research etc". There are a few other ongoing research efforts using GeophysicalFlows.jl... Should we add all them? Or drop everything whatsoever and perhaps we should just mention everythng to the editor upon submission?

[BrodiePearson]

• You're right that boiling down performance benchmarks is hard. I don't mind if we leave it out
• For the second-to-last paragraph, perhaps rephrasing the first sentence will help make it feel more connected:

GeophysicalFlows.jl is a unique Julia package, and it has similar functionality to the Python package pyqg (Abernathey et al., 2019).

• For the final paragraph, I think that mentioning the breadth of active research projects is important to demonstrate the utility of the package for research (I anticipated everyone would expand to include their relevant projects). Should we add a sentence about its utility for teaching as well?

GeophysicalFlows.jl can be used to investigate a variety of scientific research questions thanks to its various modules and high customizability, and its ease-of-use makes it an ideal teaching tool for fluids courses.

[navidcy]

Yes, I feel that a mention to teaching, perhaps pointing, e.g., to this notebook (?), is very good point to be made.

[liasiegelman]

Thanks for including me here.

I agree with @BrodiePearson . In the last paragraph, you write "Dedalus (Burns et al., 2020) is Python software with an intuitive script-based interface that uses spectral methods to solve general partial differential equations, including the ones withing GeophysicalFlows.jl. " I assume you mean that Dedalus solves the same equations as GeophysicalFlows.jl and not that GeophysicalFlows.jl calls Dedalus. If I am correct, you may write something more compact like "GeophysicalFlows.jl is a unique Julia package, and it has similar functionality to the Python package pyqg (Abernathey et al., 2019) and the Python spectral solver Dedalus (Burns et al., 2020). "

Otherwise, happy to add a line or two to describe the SingleLayerQG if needed although it's already clearly described in the docs.

[navidcy]

@liasiegelman thanks! I'll rephrase.

I think we shouldn't include module-specific descriptions in the paper for brevity; the docs describe what each module does very nicely I feel.

[navidcy]

@liasiegelman, perhaps you could add a line on what you're up to with SingleLayerQG and Jupiter in the "ongoing research" paragraphs? You can leave it as vague as you wish...

[liasiegelman]

@navidcy ok, will do

[navidcy]

I added what was discussed above. See latest version here.

What about mentioning something like "GeophysicalFlows.jl is continuously tested..."?

[BrodiePearson]

Do you mean there should be a new paragraph about testing?

Also, could you add in the acknowledgements:

BCP was supported by the National Science Foundation under Grant No. 2023721

[navidcy]

Was mostly thinking a sentence about testing... or half a sentence.

I'm adding the acknowledgment now.

[navidcy]

@liasiegelman, regarding your remark:

In the last paragraph, you write "Dedalus (Burns et al., 2020) is Python software with an intuitive script-based interface that uses spectral methods to solve general partial differential equations, including the ones withing GeophysicalFlows.jl. " I assume you mean that Dedalus solves the same equations as GeophysicalFlows.jl and not that GeophysicalFlows.jl calls Dedalus. If I am correct, you may write something more compact like "GeophysicalFlows.jl is a unique Julia package, and it has similar functionality to the Python package pyqg (Abernathey et al., 2019) and the Python spectral solver Dedalus (Burns et al., 2020)."

I rephrased here:
2f5f234

Clearer?

[liasiegelman]

@navidcy yep:)

[liasiegelman]

@navidcy could you add this line at the end of the last paragraph of the paper :
"(iv) to study the genesis and persistence of the polygons of vortices present at Jovian high latitudes (Siegelman, Young and Ingersoll, in prep)." ?
My complete affiliation is Scripps Institution of Oceanography, University of California San Diego.
Otherwise, looks good to me :)

[navidcy]

thanks @liasiegelman; done.

I kept only the institutions in the affiliations as I understood that this is JOSS style. I'll investigate this and if so I'll add Scripps, and EAPS (for Greg) and everybody's departments, etc.

[apaloczy]

@navidcy, regarding

"Is it "on periodic domains" or "in periodic domains"? At the moment both of these appear in the manuscript..."

perhaps "in periodic domains" because 1D, 2D and 3D grids are supported?

Also, what does everyone think about rephrasing the title from

GeophysicalFlows.jl: geophysical fluid dynamics-problems solvers in periodic domains on CPUs and GPUs

to

GeophysicalFlows.jl: Solvers for geophysical fluid dynamics problems in periodic domains on CPUs and GPUs

[navidcy]

thanks @apaloczy. Your title suggestion reads better; the only problem it doesn't fit in two lines and not so pleasing for the eye so I changed "CPUs and GPUs" to "CPUs & GPUs" :)

[navidcy]

http://res.cloudinary.com/hju22ue2k/image/upload/v1611953748/y9zip8e6j4xcgqz594fc.pdf

[navidcy]

@BrodiePearson OK to submit?

[BrodiePearson]

@navidcy Could you re-add my funding acknowledgement in? For the last paragraph, should point (iii) be Kolmogorov?

Other than that, the new title sounds good and I'm on board for submitting!

[navidcy]

Damn! The grant acknowledgment went out by accident --- back in now.

"Kolmogorov flow" is sort of standard nomenclature in maths community about 2D Navier-Stokes with constant sinusoidal forcing; see e.g., https://aip.scitation.org/doi/10.1063/5.0002751

[BrodiePearson]

Thanks! I meant the PDF I saw says Kologorov instead of Kolmogorov...maybe it got updated after

[navidcy]

Thanks all. I clicked the "submit" button. Will let you know what happens..

[navidcy]

The submission's pre-review process is at openjournals/joss-reviews#2996
Review is done at openjournals/joss-reviews#3053

[navidcy]

Hey all,

I made an attempt to restructure the paper to address the JOSS review remarks. I pushed the paper in the JOSS-paper branch; a preview of its current form is here. I'm sure it can be improved....

Could you all please have a read. Let me know of any suggestions you may have. In particular, I'd appreciate

• Feedback on the remarks on MAOOAM, qgs, Oceananigans.jl that I've included,
• Making sure I've addressed all comments by the reviewers. (At least those comments that required something to be added in the paper!) For reviewer 1 have a look at this post and also this one; for reviewer 2 have a look here

There is still the remark about GPU and scalability; we should add a remark on that in the README and in the Docs. Will do that soon...

cc: @apaloczy @BrodiePearson @glwagner @liasiegelman

[BrodiePearson]

@navidcy Thank you for addressing virtually all of these comments already! The restructuring and elaboration works well. I have a few suggestions for the revised manuscript, I hope they help:

• Line 15: ...understanding geophysical and astrophysical systems, particularly the atmospheres and oceans of Earth and other planets.
• Line 18: ...the same partial differential equations for research or classwork. The GeophysicalFlows.jl package is designed to be easily utilized and adaptable for a wide variety of research and pedagogical purposes.
• Line 47: is a (missing a)
• Line 50: [hopefully @glwagner has a more accurate and precise comparison, but this is a rough attempt]Oceananigans.jl is an incompressible fluid solver that can be run in 1-D, 2-D, and 3-D domains. Both Oceananigans.jl and GeophysicalFlows.jl contain modules for two-dimensional flow, but the other examples provided with Oceananigans focus on three-dimensional flows which are generally present at smaller scales than the dynamics of GeophysicalFlows.jl's other modules.
• Line 54: The MOAAM (De Cruz et al., 2016) package, and its expanded Python implementation qgs (Demaeyer et al., 2020), simulate two atmospheric layers with QG dynamics, above either land or an oceanic layer with reduced-gravity QG dynamics. The dynamics of individual layers have overlap with the MultiLayerQG and SingleLayerQG modules, however the layer configuration of MOAAM and qgs is specifically designed to study the dynamics of Earth's mid-latitude atmosphere.
• State of the Field section: It might be nice to bullet each model that is discussed here, similar to the same section in the qgs paper.
• Line 68 - The Pearson et al paper is now in press, so it can be changed to Pearson et al., 2021

[navidcy]

@BrodiePearson can you update the bib file for your paper?

[navidcy]

Thanks @BrodiePearson!
I've pushed a commit with most of your suggestions (except the one of doing bullet points for each model we compare... It's not that I don't agree with that, I just thought I sleep over it and see what others feel also before doing it.)

[BrodiePearson]

@navidcy Great, thanks for taking those on board!

[navidcy]

Latest version of the paper can be viewed here.

[liasiegelman]

Hi all, Thanks @navidcy Navid for addressing all the comments. The latest version looks good to me ! I like @BrodiePearson's suggestion of doing bullet points for each model, it would enhance readability. Otherwise, do you want to add a sentence in the paper stating that FourierFlows.jl is restricted to either a single GPU or a single CPU node atm ?

[apaloczy]

Thanks @navidcy and everyone for addressing the comments. I also feel like the bullet point layout in the comparisons to the other models could enhance readability.

This looks like a minor typo:

• Line 71: Study the bifurcation properties of Kolmogorov flows.

Also, perhaps it is worth adding to the Figure caption or to each panel's title what is the variable being plotted (PV in each layer?).

Otherwise looks good to me!

[glwagner]

I love it! My only minor comment is that "stepping stone" appears for the second time on line 35. Perhaps "starting point" could replace this second appearance of the phrase.

[navidcy]

Thanks all! 🙏 I’ll address everything and resubmit. I think I won’t mention about multiple gpus/cpus in the paper (since this is a FourierFlows.jl-related restrictions). I’ll add a remark in both FourierFlows and GeophysicalFlows docs+Readme though.

[navidcy]

Thanks all. I pushed the revised version to JOSS review issue.

[navidcy]

Paper is published: https://doi.org/10.21105/joss.03053