Merge branch 'mg/lta-ndim-1' of https://github.com/SpeedyWeather/Spee…

…dyWeather.jl into mg/lta-ndim-1

.github/workflows/draft-pdf.yml

@@ -0,0 +1,29 @@
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: docs/joss/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v1
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: docs/joss/paper.pdf
+        # These lines have been added following
+        # https://github.com/openjournals/openjournals-draft-action/issues/15
+      - name: save pdf to repo
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: Saved new PDF of paper

.gitignore

@@ -37,5 +37,9 @@ run_*/
 # no video outputs
 *.mp4
 
+# JOSS paper
+docs/joss/media
+docs/joss/paper.jats
+
 # not sure where they are from
-default.profraw
+default.profraw

CITATION.cff

@@ -0,0 +1,43 @@
+cff-version: 1.2.0
+preferred-citation:
+  type: article
+  authors:
+  - family-names: "Klöwer"
+    given-names: "Milan"
+    orcid: "https://orcid.org/0000-0002-3920-4356"
+  - family-names: "Gelbrecht"
+    given-names: "Maximilian"
+    orcid: "https://orcid.org/0000-0002-0729-6671"
+  - family-names: "Hotta"
+    given-names: "Daisuke"
+    orcid: "https://orcid.org/0000-0003-2287-0608"
+  - family-names: "Willmert"
+    given-names: "Justin"
+    orcid: "https://orcid.org/0000-0002-6452-4693"
+  - family-names: "Silvestri"
+    given-names: "Simone"
+    orcid: "https://orcid.org/0000-0002-7156-946X"
+  - family-names: "Wagner"
+    given-names: "Gregory L"
+    orcid: "https://orcid.org/0000-0003-3377-6852"
+  - family-names: "White"
+    given-names: "Alistair"
+    orcid: "https://orcid.org/0000-0001-7235-6450"
+  - family-names: "Hatfield"
+    given-names: "Sam"
+    orcid: "https://orcid.org/0000-0002-6542-6032"
+  - family-names: "Kimpson"
+    given-names: "Tom"
+    orcid: "https://orcid.org/0000-0002-8149-4094"
+  - family-names: "Constantinou"
+    given-names: "Navid C"
+    orcid: "https://orcid.org/0000-0001-5317-2445"
+  - family-names: "Hill"
+    given-names: "Chris"
+  title: "SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility"
+  journal: "Journal of Open Source Software"
+  doi: "10.21105/joss.06323"
+  volume: 9
+  issue: 98
+  start: 6323
+  year: 2024

Project.toml

@@ -1,7 +1,7 @@
 name = "SpeedyWeather"
 uuid = "9e226e20-d153-4fed-8a5b-493def4f21a9"
 authors = ["Milan Klöwer and SpeedyWeather contributors"]
-version = "0.9.0"
+version = "0.10.0"
 
 [deps]
 AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"

README.md

@@ -196,6 +196,30 @@ SpeedyWeather.jl at about 500 simulated years per day, i.e. one year takes about
 For an overview of typical simulation speeds a user can expect under different model setups see
 [Benchmarks](https://github.com/SpeedyWeather/SpeedyWeather.jl/blob/main/benchmark).
 
+## Citing
+
+If you use SpeedyWeather.jl in research, teaching, or other activities, we would be grateful 
+if you could mention SpeedyWeather.jl and cite our paper in JOSS:
+
+> Klöwer et al., (2024). SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility. Journal of Open Source Software, 9(98), 6323, doi:[10.21105/joss.06323](https://doi.org/10.21105/joss.06323).
+
+The bibtex entry for the paper is:
+
+```bibtex
+@article{SpeedyWeatherJOSS,
+    doi = {10.21105/joss.06323},
+    url = {https://doi.org/10.21105/joss.06323},
+    year = {2024},
+    publisher = {The Open Journal},
+    volume = {9},
+    number = {98},
+    pages = {6323},
+    author = {Milan Klöwer and Maximilian Gelbrecht and Daisuke Hotta and Justin Willmert and Simone Silvestri and Gregory L. Wagner and Alistair White and Sam Hatfield and Tom Kimpson and Navid C. Constantinou and Chris Hill},
+    title = {{SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility}},
+    journal = {Journal of Open Source Software}
+}
+```
+
 ## Copyright and license
 
 Copyright (c) 2020 Milan Klöwer for SpeedyWeather.jl  

docs/joss/paper.md

@@ -0,0 +1,237 @@
+---
+title: 'SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility'
+
+tags:
+  - Julia
+  - weather
+  - climate
+  - general circulation model
+  - spectral
+  - spherical harmonic transform
+
+authors:
+  - name: Milan Klöwer
+    orcid: 0000-0002-3920-4356
+    email: [email protected]
+    corresponding: true # (This is how to denote the corresponding author)
+    affiliation: "1, 2" # (Multiple affiliations must be quoted)
+
+  - name: Maximilian Gelbrecht
+    orcid: 0000-0002-0729-6671
+    affiliation: "3,4"
+
+  - name: Daisuke Hotta
+    orcid: 0000-0003-2287-0608
+    affiliation: "5,6"
+
+  - name: Justin Willmert
+    orcid: 0000-0002-6452-4693
+    affiliation: 7
+
+  - name: Simone Silvestri
+    orcid: 0000-0002-7156-946X
+    affiliation: 1
+
+  - name: Gregory L Wagner
+    orcid: 0000-0001-5317-2445
+    affiliation: 1
+
+  - name: Alistair White
+    orcid: 0000-0003-3377-6852
+    affiliation: "3,4"
+
+  - name: Sam Hatfield
+    orcid: 0000-0001-7235-6450
+    affiliation: 6
+
+  - name: Tom Kimpson
+    orcid: 0000-0002-6542-6032
+    affiliation: "2,8"
+
+  - name: Navid C Constantinou
+    orcid: 0000-0002-8149-4094
+    affiliation: "8, 9"
+
+  - name: Chris Hill
+    affiliation: 1
+
+affiliations:
+ - name: Massachusetts Institute of Technology, Cambridge, MA, USA
+   index: 1
+ - name: University of Oxford, UK
+   index: 2
+ - name: Technical University of Munich, Germany
+   index: 3
+ - name: Potsdam Institute for Climate Impact Research, Germany
+   index: 4
+ - name: Japan Meteorological Agency, Tsukuba, Japan
+   index: 5
+ - name: European Centre for Medium-Range Weather Forecasts, Reading, UK
+   index: 6
+ - name: University of Minnesota, Minneapolis, MN, USA
+   index: 7
+ - name: University of Melbourne, Parkville, VIC, Australia
+   index: 8
+ - name: ARC Centre of Excellence for the Weather of the 21st Century, University of Melbourne, Parkville, VIC, Australia
+   index: 9
+
+date: 7 June 2024
+bibliography: paper.bib
+
+---
+
+
+# Summary
+
+SpeedyWeather.jl is a library to simulate and analyze the global atmospheric
+circulation on the sphere. It implements several 2D and 3D
+models which solve different sets of equations:
+
+- the primitive equations with and without humidity (\autoref{fig:primitive}),
+- the shallow water equations (\autoref{fig:swm}), and
+- the barotropic vorticity equation (\autoref{fig:particles}).
+
+The primitive equation model in SpeedyWeather.jl is an
+atmospheric general circulation model [@Kucharski2013] with simple parameterizations
+for unresolved physical processes including precipitation or boundary layer mixing.
+It can be thought of as a conceptual reinvention of the Fortran SPEEDY model [@Molteni2003]
+in the Julia programming language [@Bezanson2017]. However, all models here are written in a modular
+way to make its components easily extensible. For example, a new parameterization can
+be externally defined and passed as an argument to the model constructor.
+Operators used inside SpeedyWeather.jl are exposed to the user,
+facilitating analysis of the simulation data.
+SpeedyWeather.jl is therefore, beyond its main purpose of simulating 
+atmospheric motion, also a library for the analysis of gridded data on the sphere.
+Running and analyzing simulations can be interactively combined, enhancing user
+experience and productivity.
+
+The user interface of SpeedyWeather.jl is heavily influenced by
+the Julia ocean model Oceananigans.jl [@Ramadhan2020].
+A monolithic interface [@Mazlami2017], controlling most of the model's functionality
+through arguments of a single function or through parameter files (often called namelists in Fortran),
+is avoided in favor of a library-style interface.
+A model is constructed bottom-up by first defining the discretization
+and any non-default model components with their respective parameters.
+All components are then collected into a single model object which, once
+initialized, returns a simulation object. A simulation contains everything,
+the model with all parameters as constructed before but also all prognostic and diagnostic variables.
+Such a simulation can then be run, but also accessed before and after to analyze or
+visualize the current variables, or individual terms of the equations.
+One can also adjust some parameters before resuming the simulation.
+While these steps can be written into a script for reproducibility,
+the same steps can be executed and interacted with one-by-one in
+Julia's read-evaluate-print loop (REPL) or in a Jupyter or Pluto notebook.
+We thereby achieve an interactivity of a simulation and its various model components
+far beyond the options provided in a monolithic interface.
+At the same time, defaults, set to well-established test cases, 
+enable even inexperienced users to run simulations in just a few lines of code. 
+
+![Surface humidity, air temperature, wind speed and precipitation simulated
+with the primitive equation model in SpeedyWeather.jl. Spectral resolution is
+T340 (about 40km) on an octahedral Gaussian grid [@Malardel2016] with simple
+physics to represent unresolved processes such as surface fluxes including
+evaporation, and precipitation due to large-scale condensation and convection.
+\label{fig:primitive}](primitive.jpg)
+
+SpeedyWeather.jl relies on Julia's multiple dispatch programming paradigm [@Bezanson2017]
+to be extensible with new components including parameterizations, forcing, drag,
+or even the grid.
+All such supported model components define an abstract type that can be
+subtyped to introduce, for example, a new parameterization.
+To define a new parameterization for convection in a given vertical column of the atmosphere,
+one would define `MyConvection` as a new subtype of `AbstractConvection`.
+One then only needs to extend the `initialize!` (executed once during model initialization)
+and `convection!` (executed on every time step)
+functions for this new type. Passing on `convection = MyConvection()`
+to the model constructor then implements this new model component without
+the need to branch off or overwrite existing model components.
+Conceptually similar scientific modelling paradigms have been very successful
+in the Python-based generic partial differential equation solver Dedalus [@Burns2020],
+the process-oriented climate model CLIMLAB [@Rose2018],
+and the Julia ocean model Oceananigans.jl [@Ramadhan2020].
+
+The dynamical core of SpeedyWeather.jl uses established numerics
+[@Bourke1972; @Hoskins1975; @Simmons1978; @Simmons1981],
+widely adopted in numerical weather prediction. It is based on the spherical
+harmonic transform [@reinecke2013; @stompor2011] with a leapfrog-based semi-implicit
+time integration [@Hoskins1975] and a Robert-Asselin-Williams filter [@Williams2011; @Amezcua2011].
+The spherical harmonic transform is grid-flexible [@Willmert2020]. Any iso-latitude ring-based
+grid can be used and new grids can be externally defined and passed in
+as an argument. Many grids are already implemented: the conventional
+Gaussian grid, a regular longitude-latitude grid, 
+the octahedral Gaussian grid [@Malardel2016], the octahedral
+Clenshaw-Curtis grid [@Hotta2018], and the HEALPix grid [@Gorski2005].
+Both SpeedyWeather.jl and its spherical harmonic transform are also
+number format-flexible. Single-precision floating-point numbers
+(Float32) are the default as adopted by other modelling efforts [@Vana2017; @Nakano2018],
+but Float64 and other custom number formats can be used with a single
+code basis [@Klower2022; @Klower2020].
+Julia will compile to the choice of number format, the grid,
+and and other model components just-in-time. A simple parallelization
+(across vertical layers for the dynamical core, across horizontal grid points
+for the parameterizations) is supported by Julia's multithreading.
+No distributed-memory parallelization is currently supported,
+GPU support is planned.
+
+SpeedyWeather.jl internally uses three sub-modules `RingGrids`,
+`LowerTriangularMatrices`, and `SpeedyTransforms`. `RingGrids` is a module that discretizes
+the sphere on iso-latitude rings and implements interpolations between various such grids.
+`LowerTriangularMatrices` facilitates the implementation of the spherical harmonics by organizing
+their coefficients in a lower triangular matrix representation.
+`SpeedyTransforms` implements the spectral transform between
+the grid-point space as defined by `RingGrids` and the spectral space defined in
+`LowerTriangularMatrices`. These three modules are independently usable
+and therefore support SpeedyWeather's library-like user interface.
+Output is stored as NetCDF files using NCDatasets.jl [@NCDatasets].
+
+![Relative vorticity simulated with the shallow water model in SpeedyWeather.jl.
+The simulation used a spectral resolution of T1023 (about 20 km) and Float32
+arithmetic on an octahedral Clenshaw-Curtis grid [@Hotta2018]. Relative vorticity
+is visualized with Matplotlib [@Hunter2007] and Cartopy [@Cartopy] using a
+transparent-to-white colormap to mimic the appearance of clouds. Underlaid is
+NASA's blue marble from June 2004. \label{fig:swm}](swm.png)
+
+# Statement of need
+
+SpeedyWeather.jl is a fresh approach to atmospheric models that have been
+very influential in many areas of scientific  and high-performance computing
+as well as climate change mitigation and adaptation.
+Most weather, ocean and climate models are written in Fortran
+(e.g. ICON [@ICON], CESM [@CESM], MITgcm [@MITgcm], NEMO [@NEMO]) and have been
+developed over decades. From this tradition follows a specific programming
+style and associated user interface.
+SpeedyWeather.jl aims to overcome the constraints of traditional Fortran-based models.
+The modern trend sees simulations in Fortran and data analysis in Python
+(e.g. NumPy [@Numpy], Xarray [@Xarray], Dask [@Dask], Matplotlib [@Hunter2007]),
+making it virtually impossible to interact with various model components directly.
+In SpeedyWeather.jl, interfaces to the model components are exposed to the user.
+Furthermore, data-driven climate modelling [@Rasp2018; @Schneider2023],
+which replaces existing model components with machine learning,
+is more difficult in Fortran due to the lack of established machine learning
+frameworks [@Meyer2022a]. 
+In Julia, Flux.jl [@Innes2019] is available for machine learning as well as automatic
+differentiation with Enzyme [@Moses2020] for gradients-based optimization.
+
+With SpeedyWeather.jl we hope to provide a platform for data-driven
+atmospheric modelling and in general an interactive model that makes difficult
+problems easy to simulate. Climate models that are user-friendly, trainable,
+but also easily extensible will suddenly make many complex
+research ideas possible.
+
+![Particle trajectories advected in the barotropic vorticity model. The barotropic
+vorticity equations were stochastically stirred at wave numbers 8 to 40 for homogeneous
+turbulence on the sphere. The simulation was computed at T340 (about 40km global resolution).
+Visualized are 20,000 particles (white dots) with trajectories (colored randomly)
+for the previous 6 hours. \label{fig:particles}](particles.jpg)
+
+# Acknowledgements
+
+We acknowledge contributions from David Meyer, Mosè Giordano, Valentin Churavy, and Pietro Monticone
+who have also committed to the SpeedyWeather.jl repository, and the wider Julia community
+for help and support.
+MK acknowledges funding from the National Science Foundation.
+MK and TK acknowledge funding from the European Research Council
+under the European Union's Horizon 2020 research and innovation programme for the ITHACA grant (no. 741112).
+NCC acknowledges support by the Australian Research Council under DECRA Fellowship DE210100749 and the Center of Excellence for the Weather of the 21st Century CE230100012.
+
+# References

docs/src/index.md

@@ -60,8 +60,32 @@ We are more than happy to guide you, especially when you don't know where to sta
 We can point you to the respective code, highlight how everything is connected and tell you
 about dos and don'ts. Just express your interest to contribute and we'll be happy to have you.
 
+## Citing
+
+If you use SpeedyWeather.jl in research, teaching, or other activities, we would be grateful 
+if you could mention SpeedyWeather.jl and cite our paper in JOSS:
+
+Klöwer et al., (2024). SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility. _Journal of Open Source Software_, **9(98)**, 6323, doi:[10.21105/joss.06323](https://doi.org/10.21105/joss.06323).
+
+The bibtex entry for the paper is:
+
+```bibtex
+@article{SpeedyWeatherJOSS,
+    doi = {10.21105/joss.06323},
+    url = {https://doi.org/10.21105/joss.06323},
+    year = {2024},
+    publisher = {The Open Journal},
+    volume = {9},
+    number = {98},
+    pages = {6323},
+    author = {Milan Klöwer and Maximilian Gelbrecht and Daisuke Hotta and Justin Willmert and Simone Silvestri and Gregory L. Wagner and Alistair White and Sam Hatfield and Tom Kimpson and Navid C. Constantinou and Chris Hill},
+    title = {{SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility}},
+    journal = {Journal of Open Source Software}
+}
+```
+
 ## Funding
 
 MK received funding by the European Research Council under Horizon 2020 within the ITHACA project,
 grant agreement number 741112 from 2021-2022. Since 2023 this project is also funded by the
-National Science Foundation NSF.
+National Science Foundation NSF.