JOSS paper folder + update citations

Project.toml

@@ -1,7 +1,7 @@
 name = "GeophysicalFlows"
 uuid = "44ee3b1c-bc02-53fa-8355-8e347616e15e"
 license = "MIT"
-authors = ["Navid C. Constantinou <navidcy@gmail.com>", "Gregory L. Wagner <wagner.greg@gmail.com>"]
+authors = ["Navid C. Constantinou <navidcy@gmail.com>", "Gregory L. Wagner <wagner.greg@gmail.com>", "and co-contributors"]
 version = "0.12.1"
 
 [deps]

README.md

@@ -28,8 +28,8 @@
     <a href="https://github.com/SciML/ColPrac">
       <img alt="ColPrac: Contributor's Guide on Collaborative Practices for Community Packages" src="https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet">
     </a>
-    <a href="https://joss.theoj.org/papers/a8cdf26beae8bcecc751ab4ded53b308">
-        <img src="https://joss.theoj.org/papers/a8cdf26beae8bcecc751ab4ded53b308/status.svg">
+    <a href="https://doi.org/10.21105/joss.03053">
+      <img src="https://joss.theoj.org/papers/10.21105/joss.03053/status.svg" alt="DOI badge" >
     </a>
 </p>
 
@@ -119,12 +119,29 @@ than happy to help along the way.
 For more information, check out our [contributor's guide](https://github.com/FourierFlows/GeophysicalFlows.jl/blob/master/CONTRIBUTING.md).
 
 
-## Cite
+## Citing
 
-The code is citable via [zenodo](https://zenodo.org). Please cite as:
+If you use GeophysicalFlows.jl in research, teaching, or other activities, we would be grateful 
+if you could mention GeophysicalFlows.jl and cite our paper in JOSS:
 
-> Navid C. Constantinou, Gregory L. Wagner, and co-contributors. (2021). FourierFlows/GeophysicalFlows.jl: GeophysicalFlows v0.12.1 (Version v0.12.1). Zenodo.  [http://doi.org/10.5281/zenodo.1463809](http://doi.org/10.5281/zenodo.1463809)
+> Constantinou et al., (2021). GeophysicalFlows.jl: Solvers for geophysical fluid dynamics problems in periodic domains on CPUs & GPUs. Journal of Open Source Software, 6(60), 3053, doi:[10.21105/joss.03053](https://doi.org/10.21105/joss.03053)
 
+The bibtex entry for the paper is:
+
+```bibtex
+@article{Constantinou2021,
+  doi = {10.21105/joss.03053},
+  url = {https://doi.org/10.21105/joss.03053},
+  year = {2021},
+  publisher = {The Open Journal},
+  volume = {6},
+  number = {60},
+  pages = {3053},
+  author = {Navid C. Constantinou and Gregory LeClaire Wagner and Lia Siegelman and Brodie C. Pearson and André Palóczy},
+  title = {GeophysicalFlows.jl: Solvers for geophysical fluid dynamics problems in periodic domains on CPUs &amp; GPUs},
+  journal = {Journal of Open Source Software}
+}
+```
 
 [FourierFlows.jl]: https://github.com/FourierFlows/FourierFlows.jl
 [documentation]: https://fourierflows.github.io/GeophysicalFlowsDocumentation/dev/

docs/Project.toml

@@ -3,6 +3,7 @@ CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 FourierFlows = "2aec4490-903f-5c70-9b11-9bed06a700e1"
+GeophysicalFlows = "44ee3b1c-bc02-53fa-8355-8e347616e15e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"

docs/src/index.md

@@ -55,6 +55,26 @@ course of time various people have contributed to GeophysicalFlows.jl, including
 [Lia Siegelman](https://scholar.google.com/citations?user=BQJtj6sAAAAJ), [Brodie Pearson](https://brodiepearson.github.io), and [André Palóczy](https://scholar.google.com/citations?user=o4tYEH8AAAAJ) (see the [example in FourierFlows.jl](https://fourierflows.github.io/FourierFlowsDocumentation/stable/generated/OneDShallowWaterGeostrophicAdjustment/)).
 
 
-## Cite
+## Citing
 
-The code is citable via [zenodo](https://doi.org/10.5281/zenodo.1463809).
+If you use GeophysicalFlows.jl in research, teaching, or other activities, we would be grateful 
+if you could mention GeophysicalFlows.jl and cite our paper in JOSS:
+
+Constantinou et al., (2021). GeophysicalFlows.jl: Solvers for geophysical fluid dynamics problems in periodic domains on CPUs & GPUs. _Journal of Open Source Software_, **6(60)**, 3053, doi:[10.21105/joss.03053](https://doi.org/10.21105/joss.03053)
+
+The bibtex entry for the paper is:
+
+```bibtex
+@article{Constantinou2021,
+  doi = {10.21105/joss.03053},
+  url = {https://doi.org/10.21105/joss.03053},
+  year = {2021},
+  publisher = {The Open Journal},
+  volume = {6},
+  number = {60},
+  pages = {3053},
+  author = {Navid C. Constantinou and Gregory LeClaire Wagner and Lia Siegelman and Brodie C. Pearson and André Palóczy},
+  title = {GeophysicalFlows.jl: Solvers for geophysical fluid dynamics problems in periodic domains on CPUs & GPUs},
+  journal = {Journal of Open Source Software}
+}
+```

paper/paper.bib

@@ -0,0 +1,153 @@
+@article{Bezanson2017,
+  title   = {Julia: {A} fresh approach to numerical computing},
+  author  = {Bezanson, Jeff and Edelman, Alan and Karpinski, Stefan and Shah, Viral B.},
+  journal = {SIAM Review},
+  volume  = {59},
+  number  = {1},
+  pages   = {65--98},
+  year    = {2017},
+  doi     = {10.1137/141000671}
+}
+
+@article{Oceananigans,
+  title={Oceananigans.jl: {Fast} and friendly geophysical fluid dynamics on {GPUs}},
+  author={Ramadhan, Ali and Wagner, Gregory LeClaire and Hill, Chris and Campin, Jean-Michel and Churavy, Valentin and Besard, Tim and Souza, Andre and Edelman, Alan and Ferrari, Raffaele and Marshall, John},
+  journal={Journal of Open Source Software},
+  volume={5},
+  number={53},
+  pages={2018},
+  year={2020},
+	doi={10.21105/joss.02018}
+}
+
+@article{MAOOAM,
+	author = {De Cruz, L. and Demaeyer, J. and Vannitsem, S.},
+	doi = {10.5194/gmd-9-2793-2016},
+	journal = {Geoscientific Model Development},
+	volume = {9},
+	number = {8},
+	pages = {2793--2808},
+	title = {The modular arbitrary-order ocean-atmosphere model: \textsc{maooam}~v1.0},
+	year = {2016}}
+
+@article{qgs,
+	author = {Demaeyer, J. and De Cruz, L. and Vannitsem, S.},
+	doi = {10.21105/joss.02597},
+	journal = {Journal of Open Source Software},
+	volume = {5},
+	number = {56},
+	pages = {2597},
+	title = {{qgs}: {A} flexible {Python} framework of reduced-order multiscale climate models},
+	year = {2020}}
+
+@software{FourierFlows,
+  author       = {Constantinou, N. C. and
+                  Wagner, L. C. and
+                  Palóczy, A.},
+  title        = {FourierFlows/FourierFlows.jl: v0.6.17},
+  year         = {2021},
+  publisher    = {Zenodo},
+  version      = {v0.6.17},
+  doi          = {10.5281/zenodo.4686348},
+  url          = {https://doi.org/10.5281/zenodo.4686348}
+}
+
+@article{Thyng2016,
+  title   = {True colors of oceanography: {Guidelines} for effective and accurate colormap selection},
+  author  = {Thyng, K. M. and Greene, C. A. and Hetland, R. D. and Zimmerle, H. M. and DiMarco, S. F.},
+  journal = {Oceanography},
+  volume  = {29},
+  number  = {3},
+  pages   = {9--13},
+  year    = {2016},
+  doi     = {10.5670/oceanog.2016.66}
+}
+
+@article{Burns2020,
+  title = {Dedalus: {A} flexible framework for numerical simulations with spectral methods},
+  author = {Burns, K. J. and Vasil, G. M. and Oishi, J. S. and Lecoanet, D. and Brown, B. P.},
+  journal = {Physical Review Research},
+  volume = {2},
+  issue = {2},
+  pages = {023068},
+  numpages = {39},
+  year = {2020},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevResearch.2.023068}
+}
+
+@software{pyqg,
+  author       = {Abernathey, R. and
+                  Rocha, C. B. and
+                  Jansen, M. and
+                  Poulin, F. J. and
+                  Constantinou, N. C. and
+                  Balwada, D. and
+                  Sinha, A. and
+                  Bueti, M. and
+                  Penn, J. and
+                  Wolfe, C. L. P. and
+                  Boas, B. V.},
+  title        = {{pyqg/pyqg}: v0.3.0},
+  year         = {2019},
+  publisher    = {Zenodo},
+  version      = {v0.3.0},
+  doi          = {10.5281/zenodo.3551326},
+  url          = {https://doi.org/10.5281/zenodo.3551326}
+}
+
+@article{Pearson2021,
+  title = {Advective structure functions in anisotropic two-dimensional turbulence	},
+  author = {Pearson, B. C. and Pearson, J. L. and Fox-Kemper, B.},
+  journal = {Journal of Fluid Mechanics},
+  year = {2021},
+	volume = {916},
+	pages = {A49},
+	doi = {10.1017/jfm.2021.247}
+}
+
+@article{Karrasch2020,
+  title = {Fast and robust computation of coherent {Lagrangian} vortices on very large two-dimensional domains},
+  author = {Karrasch, D. and Schilling, N.},
+  journal = {SMAI Journal of Computational Mathematics},
+  volume = {6},
+  pages = {101--124},
+  year = {2020},
+  doi = {10.5802/smai-jcm.63}
+}
+
+@misc{KolmogorovFlow,
+  author = {Constantinou, N. C. and Drivas, T. D.},
+  title = {KolmogorovFlow},
+  year = {2020},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/navidcy/KolmogorovFlow}
+}
+
+@misc{QG_tracer_advection,
+  author = {Bisits, J. and Constantinou, N. C.},
+  title = {QG_tracer_advection},
+  year = {2021},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/jbisits/QG_tracer_advection}
+}
+
+@misc{GeophysicalFlows-Examples,
+  author = {Constantinou, N. C. and Wagner, G. L.},
+  title = {GeophysicalFlows-Examples},
+  year = {2020},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/FourierFlows/GeophysicalFlows-Examples}
+}
+
+@misc{CLExWinterSchool2020,
+  author = {Constantinou, N. C.},
+  title = {CLExWinterSchool2020},
+  year = {2020},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/navidcy/CLExWinterSchool2020}
+}

paper/paper.md

@@ -0,0 +1,138 @@
+---
+title: 'GeophysicalFlows.jl: Solvers for geophysical fluid dynamics problems in periodic domains on CPUs & GPUs'
+tags:
+  - geophysical fluid dynamics
+  - computational fluid dynamics
+  - Fourier methods
+  - pseudospectral
+  - Julia
+  - gpu
+authors:
+  - name: Navid C. Constantinou
+    orcid: 0000-0002-8149-4094
+    affiliation: "1, 2"
+  - name: Gregory LeClaire Wagner
+    orcid: 0000-0001-5317-2445
+    affiliation: 3
+  - name: Lia Siegelman
+    orcid: 0000-0003-3330-082X
+    affiliation: 4
+  - name: Brodie C. Pearson
+    orcid: 0000-0002-0202-0481
+    affiliation: 5
+  - name: André Palóczy
+    orcid: 0000-0001-8231-8298
+    affiliation: 6
+affiliations:
+ - name: Australian National University
+   index: 1
+ - name: ARC Centre of Excellence for Climate Extremes
+   index: 2
+ - name: Massachussetts Institute of Technology
+   index: 3
+ - name: University of California San Diego
+   index: 4
+ - name: Oregon State University
+   index: 5
+ - name: University of Oslo
+   index: 6
+date: 7 April 2021
+bibliography: paper.bib
+---
+
+
+# Summary
+
+`GeophysicalFlows.jl` is a Julia [@Bezanson2017] package that contains partial differential 
+equations solvers for a collection of geophysical fluid systems in periodic domains. All 
+modules use Fourier-based pseudospectral numerical methods and leverage the framework provided 
+by the `FourierFlows.jl` [@FourierFlows] Julia package for time-stepping, custom diagnostics, 
+and saving output.
+
+
+# Statement of need
+
+Conceptual models in simple domains often provide stepping stones for better understanding geophysical and astrophysical systems, particularly the atmospheres and oceans of Earth and other planets. These conceptual models are used in research but also are of great value for helping students in class to grasp new concepts and phenomena. Oftentimes people end up coding their own versions of solvers for the same partial differential equations for research or classwork. `GeophysicalFlows.jl` package is designed to be easily utilized and adaptable for a wide variety of both research and pedagogical purposes.
+
+On top of the above-mentioned needs, the recent explosion of machine-learning applications in atmospheric and oceanic sciences advocates for the need that solvers for partial differential equations can be run on GPUs. 
+
+`GeophysicalFlows.jl` provides a collection of modules for solving sets of partial differential equations often used as conceptual models. These modules are continuously tested (unit tests and tests for the physics involved) and are well-documented. `GeophysicalFlows.jl` utilizes Julia's functionality and abstraction to enable all modules to run on CPUs or GPUs, and to provide a high level of customizability within modules. The abstractions allow simulations to be tailored for specific research questions, via the choice of parameters, domain properties, and schemes for damping, forcing, time-stepping etc. Simulations can easily be carried out on different computing architectures. Selection of the architecture on which equations are solved is done by providing the argument `CPU()` or `GPU()` during the construction of a particular problem.
+
+Documented examples for each geophysical system (module) appear in the package's documentation, 
+providing a starting point for new users and for the development of new or customized modules. 
+Current modules include two-dimensional flow and a variety of quasi-geostrophic (QG) dynamical 
+systems, which provide analogues to the large-scale dynamics of atmospheres and oceans. The QG 
+systems currently in `GeophysicalFlows.jl` extend two-dimensional dynamics to include the leading
+order effects of a third dimension through planetary rotation, topography, surface boundary 
+conditions, stratification and quasi-two-dimensional layering. A community-based collection 
+of diagnostics throughout the modules are used to compute quantities like energy, enstrophy, 
+dissipation, etc.
+
+![Potential vorticity snapshots from a nonlinearly equilibrated simulation of the Eady instability 
+over a meridional ridge. Simulation used `MultiLayerQG` module of `GeophysicalFlows.jl`. The Eady 
+problem was approximated here using 5 fluid layers stacked up in the vertical. Each layer was
+simulated with 512² grid-points. Plots were made with the `Plots.jl` Julia package, which 
+utilizes the `cmocean` colormaps collection [@Thyng2016]. Scripts to reproduce the simulation 
+reside in the repository `github.com/FourierFlows/MultilayerQG-example`.
+\label{fig1}](PV_eady_nlayers5.png)
+
+
+# State of the field
+
+`GeophysicalFlows.jl` is a unique Julia package that shares some features and similarities with 
+other packages. In particular:
+
+- `pyqg` [@pyqg] (Python)
+
+  Beyond their base language, the major differences between `GeophysicalFlows.jl` and `pyqg` 
+  is that `GeophysicalFlows.jl` can be run on GPUs or CPUs and leverages a separate package (`FourierFlows.jl`; which is continuously developed) to solve differential equations and compute diagnostics, while `pyqg` can only be run on CPUs and uses a self-contained kernel. 
+
+- Dedalus [@Burns2020] (Python)
+
+  Dedalus is a Python package with an intuitive script-based interface that uses spectral methods 
+  to solve general partial differential equations, such as the ones within `GeophysicalFlows.jl`.
+  Dedalus allows for more general boundary conditions in one of the dimensions. It only runs on 
+  CPUs (not on GPUs) but can be MPI-parallelized.
+
+- `Oceananigans.jl` [@Oceananigans] (Julia)
+
+  `Oceananigans.jl` is a fluid solver focussed on the Navier-Stokes equations under the Boussinesq
+  approximation. `Oceananigans.jl` also runs on GPUs, and it allows for more variety of boundary
+  conditions but it does not have spectral accuracy as it uses finite-volume discretization methods.
+
+- `MAOOAM` [@MAOOAM] (Fortran, Python, and Lua) and its expanded Python implementation `qgs` [@qgs]
+
+  `MAOOAM` and `qgs` simulate two atmospheric layers with QG dynamics, above either land or 
+  an oceanic fluid 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. Neither `MAOOAM` nor `qgs` can run on GPUs.
+
+- Isolated codes/scripts 
+
+  Several codes/scripts exist in personal websites and in open-source public repositories with
+  similar functionality as some `GeophysicalFlows.jl` modules (e.g., `TwoDNavierStokes` or 
+  `SingleLayerQG`). Usually, though, these codes come without any or poor documentation and 
+  typically they are not continuously tested.
+
+`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 [@GeophysicalFlows-Examples; @CLExWinterSchool2020]. 
+`GeophysicalFlows.jl` has been used in developing Lagrangian vortices identification algorithms 
+[@Karrasch2020] and to test new theories for diagnosing turbulent energy transfers in geophysical 
+flows [@Pearson2021]. Currently, `GeophysicalFlows.jl` is being used, e.g., (i) to compare 
+different observational sampling techniques in these flows, (ii) to study the bifurcation properties 
+of Kolmogorov flows [@KolmogorovFlow], (iii) to study the genesis and persistence of the polygons 
+of vortices present at Jovian high latitudes (Siegelman, Young, and Ingersoll; in prep), and 
+(iv) to study how mesoscale macroturbulence affects mixing of tracers [@QG_tracer_advection].
+
+
+# Acknowledgements
+
+We acknowledge discussions with Keaton Burns, Valentin Churavy, Theodore Drivas, Cesar Rocha, 
+and William Young. B. C. P. was supported by the National Science Foundation under Grant 
+No. 2023721. We would also like to take a moment to remember our friend and colleague 
+Sean R. Haney (February 1987 - January 2021) who left us a bit too early.
+
+
+# References