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:)

[navidcy]

Latest version @ http://res.cloudinary.com/hju22ue2k/image/upload/v1611880691/mlfipst5ecujyiux50ig.pdf

Please scrutinize! I'll submit as soon as I hear "OK" from all of you...

[navidcy]

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

[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