[PRE REVIEW]: QGDipoles.jl: A Julia package for calculating dipolar vortex solutions to the Quasi-Geostrophic equations

[editorialbot]

Submitting author: @mncrowe (Matthew Crowe)
Repository: https://github.com/mncrowe/QGDipoles.jl/
Branch with paper.md (empty if default branch): joss_draft
Version: v1.0.0
Editor: Pending
Reviewers: Pending
Managing EiC: Kristen Thyng

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/c7116a767b1b555b975072e9e2d04aaf"><img src="https://joss.theoj.org/papers/c7116a767b1b555b975072e9e2d04aaf/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/c7116a767b1b555b975072e9e2d04aaf/status.svg)](https://joss.theoj.org/papers/c7116a767b1b555b975072e9e2d04aaf)

Author instructions

Thanks for submitting your paper to JOSS @mncrowe. Currently, there isn't a JOSS editor assigned to your paper.

@mncrowe if you have any suggestions for potential reviewers then please mention them here in this thread (without tagging them with an @). You can search the list of people that have already agreed to review and may be suitable for this submission.

Editor instructions

The JOSS submission bot @editorialbot is here to help you find and assign reviewers and start the main review. To find out what @editorialbot can do for you type:

@editorialbot commands

[editorialbot]

Hello human, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.1137/141000671 is OK
- 10.5281/zenodo.4686348 is OK
- 10.21105/joss.02018 is OK
- 10.1103/PhysRevResearch.2.023068 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: QGDipoles.m
- No DOI given, and none found for title: Symmetry breaking of two-layer eastward propagatin...

❌ MISSING DOIs

- 10.1017/jfm.2023.607 may be a valid DOI for title: The evolution of surface quasi-geostrophic modons ...
- 10.1017/jfm.2024.619 may be a valid DOI for title: Modon solutions in an N-layer quasi-geostrophic mo...
- 10.1017/jfm.2023.87 may be a valid DOI for title: Oceanic dipoles in a surface quasi-geostrophic mod...
- 10.1029/2020jc016479 may be a valid DOI for title: Widespread Mesoscale Dipoles in the Global Ocean
- 10.1063/1.859425 may be a valid DOI for title: Motion of dipole vortices in a weakly inhomogeneou...
- 10.1063/5.0171909 may be a valid DOI for title: Deformation and destruction of north-eastward drif...
- 10.1016/0377-0265(80)90010-x may be a valid DOI for title: An application of equivalent modons to atmospheric...
- 10.1080/03091929.2020.1805448 may be a valid DOI for title: Eastward-moving equatorial modons in moist-convect...

❌ INVALID DOIs

- https://doi.org/10.21105/joss.03053 is INVALID because of 'https://doi.org/' prefix

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.90  T=0.09 s (365.8 files/s, 43981.6 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Markdown                         8            459              0           1061
Julia                           14            731            539            670
YAML                             6              3              8            165
TeX                              1             14              0            163
TOML                             2              5              0             29
SVG                              1              0              0              1
-------------------------------------------------------------------------------
SUM:                            32           1212            547           2089
-------------------------------------------------------------------------------

Commit count by author:

    49	mncrowe
    45	Matthew Crowe
     6	Navid C. Constantinou

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 1111

✅ The paper includes a Statement of need section

[editorialbot]

License info:

✅ License found: MIT License (Valid open source OSI approved license)

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[editorialbot]

Five most similar historical JOSS papers:

qgs: A flexible Python framework of reduced-order multiscale climate models
Submitting author: @jodemaey
Handling editor: @harpolea (Retired)
Reviewers: @eviatarbach, @sadielbartholomew
Similarity score: 0.7477

SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility
Submitting author: @milankl
Handling editor: @kthyng (Active)
Reviewers: @vavrines, @natgeo-wong, @slayoo
Similarity score: 0.7465

xinvert: A Python package for inversion problems in geophysical fluid dynamics
Submitting author: @miniufo
Handling editor: @jbytecode (Active)
Reviewers: @DamienIrving, @NoraLoose
Similarity score: 0.7312

PyMPDATA v1: Numba-accelerated implementation of MPDATA with examples in Python, Julia and Matlab
Submitting author: @slayoo
Handling editor: @arfon (Active)
Reviewers: @Chiil, @wdeconinck
Similarity score: 0.7308

SyntheticEddyMethod.jl: A Julia package for the creation of inlet flow conditions for LES
Submitting author: @carlodev
Handling editor: @philipcardiff (Active)
Reviewers: @atzberg, @akshaysridhar
Similarity score: 0.7283

⚠️ Note to editors: If these papers look like they might be a good match, click through to the review issue for that paper and invite one or more of the authors before considering asking the reviewers of these papers to review again for JOSS.

[kthyng]

Hi @mncrowe and thanks for your submission! I am looking for some specific items to make sure your submission fits our requirements at a high level (not at the more detailed review level) before moving on to finding an editor or putting this on our waitlist if no relevant editors are available. I'll comment over time as I have a chance to go through them:

• OSI-approved license
• Installation instructions
• Documentation exists at all
• Tests of some sort
• Check paper (make sure compiles, read through, check for length 250-1000 words)
• Substantial scholarly effort
• Clear research application

In the meantime, please take a look at the comments above ⬆️ from the editorialbot to address any DOI, license, or paper issues if you're able (there may not be any), or suggest reviewers. For reviewers, please suggest 5 reviewers from the database listed above or your own (non-conflicted) extended network. Their github handles are most useful to receive but please don't use "@" to reference them since it will prematurely ping them.

[kthyng]

@mncrowe
I am going to ping our editorial board to see if this submission passes our criteria for substantial scholarly effort. This process will take a few weeks; thanks for your patience.

[kthyng]

@editorialbot query scope

[editorialbot]

Submission flagged for editorial review.

[mncrowe]

@mncrowe I am going to ping our editorial board to see if this submission passes our criteria for substantial scholarly effort. This process will take a few weeks; thanks for your patience.

Thank you for your consideration. It appears that the query-scope label almost always leads to rejection, but if it does help my case, I'd like to point out that much of the commit history was lost due to a force push on 04/11/2024. The commit count above only seems to include the commits after this point whereas the full activity goes back to 28/06/2024.

[mncrowe]

❌ MISSING DOIs

- 10.1017/jfm.2023.607 may be a valid DOI for title: The evolution of surface quasi-geostrophic modons ...
- 10.1017/jfm.2024.619 may be a valid DOI for title: Modon solutions in an N-layer quasi-geostrophic mo...
- 10.1017/jfm.2023.87 may be a valid DOI for title: Oceanic dipoles in a surface quasi-geostrophic mod...
- 10.1029/2020jc016479 may be a valid DOI for title: Widespread Mesoscale Dipoles in the Global Ocean
- 10.1063/1.859425 may be a valid DOI for title: Motion of dipole vortices in a weakly inhomogeneou...
- 10.1063/5.0171909 may be a valid DOI for title: Deformation and destruction of north-eastward drif...
- 10.1016/0377-0265(80)90010-x may be a valid DOI for title: An application of equivalent modons to atmospheric...
- 10.1080/03091929.2020.1805448 may be a valid DOI for title: Eastward-moving equatorial modons in moist-convect...

❌ INVALID DOIs

- https://doi.org/10.21105/joss.03053 is INVALID because of 'https://doi.org/' prefix

I've fixed the missing and invalid DOIs.

[mncrowe]

@editorialbot generate pdf

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[editorialbot]

Five most similar historical JOSS papers:

qgs: A flexible Python framework of reduced-order multiscale climate models
Submitting author: @jodemaey
Handling editor: @harpolea (Retired)
Reviewers: @eviatarbach, @sadielbartholomew
Similarity score: 0.7479

SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility
Submitting author: @milankl
Handling editor: @kthyng (Active)
Reviewers: @vavrines, @natgeo-wong, @slayoo
Similarity score: 0.7465

xinvert: A Python package for inversion problems in geophysical fluid dynamics
Submitting author: @miniufo
Handling editor: @jbytecode (Active)
Reviewers: @DamienIrving, @NoraLoose
Similarity score: 0.7311

PyMPDATA v1: Numba-accelerated implementation of MPDATA with examples in Python, Julia and Matlab
Submitting author: @slayoo
Handling editor: @arfon (Active)
Reviewers: @Chiil, @wdeconinck
Similarity score: 0.7308

SyntheticEddyMethod.jl: A Julia package for the creation of inlet flow conditions for LES
Submitting author: @carlodev
Handling editor: @philipcardiff (Active)
Reviewers: @atzberg, @akshaysridhar
Similarity score: 0.7289

⚠️ Note to editors: If these papers look like they might be a good match, click through to the review issue for that paper and invite one or more of the authors before considering asking the reviewers of these papers to review again for JOSS.

[mncrowe]

@editorialbot commands

[editorialbot]

Hello @mncrowe, here are the things you can ask me to do:

# List all available commands
@editorialbot commands

# Get a list of all editors's GitHub handles
@editorialbot list editors

# Adds a checklist for the reviewer using this command
@editorialbot generate my checklist

# Set a value for branch
@editorialbot set joss-paper as branch

# Run checks and provide information on the repository and the paper file
@editorialbot check repository

# Check the references of the paper for missing DOIs
@editorialbot check references

# Generates the pdf paper
@editorialbot generate pdf

# Generates a LaTeX preprint file
@editorialbot generate preprint

# Get a link to the complete list of reviewers
@editorialbot list reviewers

[mncrowe]

@editorialbot check repository

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.90  T=0.09 s (394.6 files/s, 51505.2 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Julia                           18           1035            761           1090
Markdown                         8            462              0           1084
TeX                              1             14              0            171
YAML                             6              3              8            166
TOML                             2              5              0             29
SVG                              2              0              0              2
-------------------------------------------------------------------------------
SUM:                            37           1519            769           2542
-------------------------------------------------------------------------------

Commit count by author:

    65	Matthew Crowe
    52	mncrowe
     6	Navid C. Constantinou

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 1111

✅ The paper includes a Statement of need section

[editorialbot]

License info:

✅ License found: MIT License (Valid open source OSI approved license)

[mncrowe]

@editorialbot check references

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.1137/141000671 is OK
- 10.5281/zenodo.4686348 is OK
- 10.21105/joss.02018 is OK
- 10.21105/joss.03053 is OK
- 10.1017/jfm.2023.607 is OK
- 10.1017/jfm.2024.619 is OK
- 10.1017/jfm.2023.87 is OK
- 10.1029/2020jc016479 is OK
- 10.1063/1.859425 is OK
- 10.1063/5.0171909 is OK
- 10.1016/0377-0265(80)90010-x is OK
- 10.1080/03091929.2020.1805448 is OK
- 10.1103/PhysRevResearch.2.023068 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: QGDipoles.m
- No DOI given, and none found for title: Symmetry breaking of two-layer eastward propagatin...

❌ MISSING DOIs

- None

❌ INVALID DOIs

- None

[kthyng]

@mncrowe Thanks for your note — I'll point that out.

[mncrowe]

@editorialbot check repository

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.90  T=0.10 s (418.8 files/s, 52380.7 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Julia                           23           1194            874           1227
Markdown                         8            463              0           1097
TeX                              1             14              0            171
YAML                             6              3              8            166
TOML                             2              5              0             29
SVG                              2              0              0              2
-------------------------------------------------------------------------------
SUM:                            42           1679            882           2692
-------------------------------------------------------------------------------

Commit count by author:

    68	Matthew Crowe
    52	mncrowe
     6	Navid C. Constantinou

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 1111

✅ The paper includes a Statement of need section

[editorialbot]

License info:

✅ License found: MIT License (Valid open source OSI approved license)

[mncrowe]

@kthyng, any update on this?

[kthyng]

@mncrowe Can you comment on the size changes of the repository? What has changed in the repository?

Several editors have the question of whether this should be a stand alone package or whether we should be encouraging you to make this package a contribution to another more general package (ex. GeophysicalFlows.jl). Why are you creating a separate package for this work? How could it be expanded if it is going to stand alone?

[mncrowe]

Regarding the changes to the repository; this was to implement some additional features:

• Custom types for parameter sets and vortex solutions
• Energy, Enstrophy and vorticity diagnostic functions so these quantities do not have to be evaluated manually (or by using another package)
• Some lines that were used multiple times (e.g. defining polar coordinates) have been move to their own functions
• Added some monopolar vortex solutions
• Documentation updates

I had three weeks off due to illness so used the time to implement features on my to-do list. Apologies if this has interfered with your reviewing.

My reason for keeping QGDipoles as a separate package is that merging it with another package would reduce it's reach and applicability and restrict development:

• QGDipoles can be used to set up initial conditions for various packages and I don't want to tie it to any one. It was made to be compatible with GeophysicalFlows as that was the package I was using most at the time, however it will also work with other packages too (potentially with some reshaping of arrays). Tying it to just one package would likely prevent it's use by users of other packages.
• QGDipoles currently contains functionality that these general PDE solver packages do not. For example, my SQG solutions allow for finite depth whereas the SQG model in GeophysicalFlows only allows for an infinite depth. As such, there would be various consistency issues when merging this package with others. These issues may force me to reduce or limit the functionality I'm offering and restrict future development.
• The solutions calculated by this package aren't intended solely to be used as initial conditions for a initial value problem (IVP) so packaging QGDipoles with an IVP solver restricts it's use. For example, there are people working on theoretical vortex dynamics who would not want to run time-dependent simulations, and only care about the form of these solutions. They would not necessarily know that an IVP solver contained the functions they were looking for and would not make use of most of the functionality offered by a combined package.
• Users of general packages are working on a wide range of problems and in many cases will not need the functionality of QGDipoles. Therefore it seems like adding QGDipoles to any of them would add unnecessary bloat that many users would not benefit from.

There are various directions for expansion, some of which I'm currently working on:

• Additional functions for calculating monopolar vortices (in progress)
• Functions for higher order poles (quadrupoles etc.)
• A 3D quasi-geostrophic model with corresponding types (in progress)
• Dipolar solutions to the shallow water equations (SWE) and magnetohydrodynamical equations (MHD)
• Functions to enable compatibility with other packages (e.g. Oceananigans, eigenvalue solver for stability problems)
• Theoretical energy predictions (in progress)
• Additional diagnostics (e.g. momentum/impulse)

These additions would cause QGDipoles to further diverge from GeophysicalFlows and many could not be added to a more general package if it did not support the underlying model (GeophysicalFlows does not support the 3D QG model, SWE or MHD and likely never will).

[kthyng]

@mncrowe Thanks for your thorough response, this is helpful. It does bring up an additional question then: given your active development, would it be better to wait until some of your in progress work is finished to undergo JOSS review, so those features can be included in the review?

[mncrowe]

@kthyng That is a good question, currently the three areas I'm working on (the ones listed as in progress above) are limited by the theoretical side rather than the coding side so it's difficult to put a timeframe on finishing their implementation as I'm not sure how easily the maths will work out. Once I've got the theory working, these additions will follow the existing format. For example, 3D QG will use similar types and functions to SQG and LQG, just with different calculations under the hood.

As such, I'd rather a thorough review of the codebase sooner rather than later though it is of course up to you and the editors. Any improvements suggested by the reviewers would also benefit these later implementations.