Merge branch 'MultiLayerQG_GPU' of https://github.com/mpudig/Geophysi…

…calFlows.jl into MultiLayerQG_GPU

.buildkite/pipeline.yml

@@ -3,24 +3,24 @@ env:
   SECRET_CODECOV_TOKEN: "Ak2mVTxXnhkPNc096ImDdp7bOc4zGNTqFEEDaGMwAgYPr28g5dyMbslh8B/ad4NQHXVL1MXQ3zrUfGgMBRq+mmqRaAe13FI4Go9uCas6bzdZXE23ExiLzBmqVRNRf8GqEcpGL7BBreohC0cnfI0SVMiIJDCJXX9YsXJtlcpk1glQFMEFI5V6cpFe9K2l5xoUNQ4179ZYoJUMAy/aylQx/UdQuw527FjHQUsi5/dFtWzMqeys0secNa9alLvJCQdIX9OqPjmBYvuIIVXCR7vlZoH8PgXwEj7wbdp8/V31+wlLQI9WePcsJxoOybtLTOlwwfw4jWLAttDZYqnqiLVp3Q==;U2FsdGVkX18sNLCManU1B/jI5kh4LhSi69MFXljHSp9yWrN7u5d196K/XrELwb8ksbamyKeHjIvDIopwD55dbw=="
 
 steps:
-  - label: "🥝 Julia 1.6"
+  - label: "🥑 Julia 1.10"
     plugins:
       - JuliaCI/julia#v1:
-          version: '1.6'
+          version: '1.10'
       - JuliaCI/julia-test#v1: ~
-      - JuliaCI/julia-coverage#v1:
-          codecov: true
     agents:
       queue: "juliagpu"
       cuda: "*"
     if: build.message !~ /\[skip tests\]/
     timeout_in_minutes: 60
 
-  - label: "🥑 Julia 1.10"
+  - label: "🥝 Julia 1.11"
     plugins:
       - JuliaCI/julia#v1:
-          version: '1.10'
+          version: '1.11'
       - JuliaCI/julia-test#v1: ~
+      - JuliaCI/julia-coverage#v1:
+          codecov: true
     agents:
       queue: "juliagpu"
       cuda: "*"

.github/workflows/CI.yml

@@ -0,0 +1,54 @@
+name: CI
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - "1.10" # LTS
+          - "1.11"
+        os:
+          - macOS-latest
+          - windows-latest
+        arch:
+          - x64
+          - aarch64
+          - arm64
+        exclude:
+          # Test 32-bit only on Linux
+          - os: macOS-latest
+            arch: x64
+          - os: windows-latest
+            arch: aarch64
+          - os: windows-latest
+            arch: arm64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1.11'
+      - uses: julia-actions/julia-buildpkg@latest
+      - uses: julia-actions/julia-docdeploy@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          JULIA_DEBUG: Documenter

.github/workflows/CompatHelper.yml

@@ -1,19 +1,45 @@
 name: CompatHelper
-
 on:
   schedule:
-    - cron: '00 00 * * *'
-
+    - cron: 0 0 * * *
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
 jobs:
   CompatHelper:
     runs-on: ubuntu-latest
     steps:
-      - uses: julia-actions/setup-julia@latest
+      - name: Check if Julia is already available in the PATH
+        id: julia_in_path
+        run: which julia
+        continue-on-error: true
+      - name: Install Julia, but only if it is not already available in the PATH
+        uses: julia-actions/setup-julia@v2
         with:
-          version: '1.10'
-      - name: Pkg.add("CompatHelper")
-        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
-      - name: CompatHelper.main()
+          version: '1'
+          # arch: ${{ runner.arch }}
+        if: steps.julia_in_path.outcome != 'success'
+      - name: "Add the General registry via Git"
+        run: |
+          import Pkg
+          ENV["JULIA_PKG_SERVER"] = ""
+          Pkg.Registry.add("General")
+        shell: julia --color=yes {0}
+      - name: "Install CompatHelper"
+        run: |
+          import Pkg
+          name = "CompatHelper"
+          uuid = "aa819f21-2bde-4658-8897-bab36330d9b7"
+          version = "3"
+          Pkg.add(; name, uuid, version)
+        shell: julia --color=yes {0}
+      - name: "Run CompatHelper"
+        run: |
+          import CompatHelper
+          CompatHelper.main()
+        shell: julia --color=yes {0}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: julia -e 'using CompatHelper; CompatHelper.main()'
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+          # COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }}

Project.toml

@@ -2,7 +2,7 @@ name = "GeophysicalFlows"
 uuid = "44ee3b1c-bc02-53fa-8355-8e347616e15e"
 license = "MIT"
 authors = ["Navid C. Constantinou <[email protected]>", "Gregory L. Wagner <[email protected]>", "and contributors"]
-version = "0.16.1"
+version = "0.16.2"
 
 [deps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"

README.md

@@ -10,8 +10,8 @@
     <a href="https://buildkite.com/julialang/geophysicalflows-dot-jl">
         <img alt="Buildkite CPU+GPU build status" src="https://img.shields.io/buildkite/4d921fc17b95341ea5477fb62df0e6d9364b61b154e050a123/main?logo=buildkite&label=Buildkite%20CPU%2BGPU">
     </a>
-    <a href="https://ci.appveyor.com/project/navidcy/geophysicalflows-jl">
-        <img alt="Build Status for Window" src="https://img.shields.io/appveyor/ci/navidcy/geophysicalflows-jl/main?label=Window&logo=appveyor&logoColor=white">
+    <a href="https://github.com/FourierFlows/GeophysicalFlows.jl/actions/workflows/CI.yml">
+        <img alt="CI Status" src="https://github.com/FourierFlows/GeophysicalFlows.jl/actions/workflows/CI.yml/badge.svg">
     </a>
     <a href="https://FourierFlows.github.io/GeophysicalFlowsDocumentation/stable">
         <img alt="stable docs" src="https://img.shields.io/badge/documentation-stable%20release-blue">
@@ -43,14 +43,12 @@ To install, use Julia's  built-in package manager (accessed by pressing `]` in t
 
 ```julia
 julia> ]
-(v1.6) pkg> add GeophysicalFlows
-(v1.6) pkg> instantiate
+(v1.10) pkg> add GeophysicalFlows
+(v1.10) pkg> instantiate
 ```
 
-The most recent version of GeophysicalFlows.jl requires Julia v1.6  (the current long-term-release) or later. _We strongly urge you to use this version._
-
-The latest version that is compatible with Julia v1.5 is GeophysicalFlows.jl v0.13.1.
-
+GeophysicalFlows.jl requires Julia v1.6 or later. However, the package has continuous integration testing on
+Julia v1.10 (the current long-term release) and v1.11. _We strongly urge you to use one of these Julia versions._
 
 ## Examples
 

docs/src/index.md

@@ -84,13 +84,17 @@ The bibtex entry for the paper is:
 
 ## Papers using `GeophysicalFlows.jl`
 
+1. Crowe, M. N. and Sutyrin, G. G. (2024) Symmetry breaking of two-layer eastward propagating dipoles. arXiv preprint arXiv.2410.14402, doi:[10.48550/arXiv.2410.14402](https://doi.org/10.48550/arXiv.2410.14402).
+
+1. Lobo, M., Griffies, S. M., and Zhang, W. (2024) Vertical structure of baroclinic instability in a three-layer quasi-geostrophic model over a sloping bottom. _ESS Open Archive_, doi:[10.22541/essoar.172166435.57577370/v1](https://doi.org/10.22541/essoar.172166435.57577370/v1).
+
 1. Pudig, M. and Smith, K. S. (2024) Baroclinic turbulence above rough topography: The vortex gas and topographic turbulence regimes. _ESS Open Archive_, doi:[10.22541/essoar.171995116.60993353/v1](https://doi.org/10.22541/essoar.171995116.60993353/v1).
 
 1. Shokar, I. J. S., Haynes, P. H. and Kerswell, R. R. (2024) Extending deep learning emulation across parameter regimes to assess stochastically driven spontaneous transition events. In ICLR 2024 Workshop on AI4DifferentialEquations in Science. url: [https://openreview.net/forum?id=7a5gUX4e5q](https://openreview.net/forum?id=7a5gUX4e5q).
 
 1. He, J. and Wang, Y. (2024) Multiple states of two-dimensional turbulence above topography. arXiv preprint arXiv:2405.10826, doi:[10.48550/arXiv.2405.10826](https://doi.org/10.48550/arXiv.2405.10826).
 
-1. Parfenyev, V., Blumenau, M., and Nikitin, I. (2024) Enhancing capabilities of particle image/tracking velocimetry with physics-informed neural networks. arXiv preprint arXiv:2404.01193, doi:[10.48550/arXiv.2404.01193](https://doi.org/10.48550/arXiv.2404.01193).
+1. Parfenyev, V., Blumenau, M., and Nikitin, I. (2024) Inferring parameters and reconstruction of two-dimensional turbulent flows with physics-informed neural networks. _Jetp Lett._, doi:[10.1134/S0021364024602203](https://doi.org/10.1134/S0021364024602203).
 
 1. Shokar, I. J. S., Kerswell, R. R., and Haynes, P. H. (2024) Stochastic latent transformer: Efficient modeling of stochastically forced zonal jets. _Journal of Advances in Modeling Earth Systems_, **16**, e2023MS004177, doi:[10.1029/2023MS004177](https://doi.org/10.1029/2023MS004177).
 

docs/src/installation_instructions.md

@@ -6,27 +6,27 @@ instantiate/build all the required dependencies
 
 ```julia
 julia> ]
-(v1.6) pkg> add GeophysicalFlows
-(v1.6) pkg> instantiate
+(v1.10) pkg> add GeophysicalFlows
+(v1.10) pkg> instantiate
 ```
 
 We recommend installing GeophysicalFlows.jl with the built-in Julia package manager, because 
 this installs a stable, tagged release. Later on, you can update GeophysicalFlows.jl to the 
 latest tagged release again via the package manager by typing
 
 ```julia
-(v1.6) pkg> update GeophysicalFlows
+(v1.10) pkg> update GeophysicalFlows
 ```
 
 Note that some releases might induce breaking changes to certain modules. If after anything 
 happens or your code stops working, please open an [issue](https://github.com/FourierFlows/GeophysicalFlows.jl/issues) 
 or start a [discussion](https://github.com/FourierFlows/GeophysicalFlows.jl/discussions). We're 
 more than happy to help with getting your simulations up and running.
 
-!!! warn "Use Julia 1.6 or newer"
+!!! warn "Julia 1.6 or newer required; Julia 1.10 or newer strongly encouraged"
     The latest GeophysicalFlows.jl requires at least Julia v1.6 to run.
     Installing GeophysicalFlows with an older version of Julia will install an older version 
     of GeophysicalFlows.jl (the latest version compatible with your version of Julia).
-
-    Last version compatible with Julia v1.5: GeophysicalFlows.jl v0.13.1
 
+    GeophysicalFlows.jl is continuously tested on Julia v1.10 (the current long-term release) and v1.11.
+    _We strongly urge you to use one of these Julia versions._

docs/src/modules/multilayerqg.md

@@ -71,10 +71,14 @@ with
 ```math
 \begin{aligned}
 \partial_y Q_j &\equiv \beta - \partial_y^2 U_j - (1-\delta_{j,1}) F_{j-1/2, j} (U_{j-1} - U_j) - (1 - \delta_{j,n}) F_{j+1/2, j} (U_{j+1} - U_j) + \delta_{j,n} \partial_y \eta , \\
-\partial_x Q_j &\equiv \delta_{j, n} \partial_x \eta .
+\partial_x Q_j & \equiv \delta_{j, n} \partial_x \eta ,
 \end{aligned}
 ```
 
+the background PV gradient components in each layer and with
+``\mathsf{J}(a, b) = (\partial_x a)(\partial_y b)-(\partial_y a)(\partial_x b)`` is the 
+two-dimensional Jacobian. On the right hand side, ``\mu`` is linear bottom drag, and ``\nu`` is
+hyperviscosity of order ``n_\nu``. Plain old viscosity corresponds to ``n_\nu = 1``.
 
 ### Implementation
 

docs/src/modules/singlelayerqg.md

@@ -20,33 +20,50 @@ radius follows is said to obey equivalent-barotropic dynamics. We denote the sum
 vorticity and the vortex stretching contributions to the QGPV with ``q \equiv \nabla^2 \psi - \psi / \ell^2``.
 Also, we denote the topographic PV with ``\eta \equiv f_0 h / H``.
 
-The dynamical variable is ``q``.  Thus, the equation solved by the module is:
+The dynamical variable is ``q``. Including an imposed zonal flow ``U(y)``, the equation of motion is:
 
 ```math
-\partial_t q + \mathsf{J}(\psi, q + \eta) + \beta \partial_x \psi = 
-\underbrace{-\left[\mu + \nu(-1)^{n_\nu} \nabla^{2n_\nu} \right] q}_{\textrm{dissipation}} + F .
+\partial_t q + \mathsf{J}(\psi, q) + (U - \partial_y\psi) \partial_x Q +  U \partial_x q + (\partial_y Q)(\partial_x \psi) = \underbrace{-\left[\mu + \nu(-1)^{n_\nu} \nabla^{2n_\nu} \right] q}_{\textrm{dissipation}} + F ,
 ```
 
-where ``\mathsf{J}(a, b) = (\partial_x a)(\partial_y b)-(\partial_y a)(\partial_x b)`` is the 
-two-dimensional Jacobian. On the right hand side, ``F(x, y, t)`` is forcing, ``\mu`` is 
+with
+
+```math
+\begin{aligned}
+\partial_y Q &\equiv \beta - \partial_y^2 U + \partial_y \eta , \\
+\partial_x Q &\equiv \partial_x \eta ,
+\end{aligned}
+```
+
+the background PV gradient components, and with
+``\mathsf{J}(a, b) = (\partial_x a)(\partial_y b) - (\partial_y a)(\partial_x b)``
+the two-dimensional Jacobian. On the right hand side, ``F(x, y, t)`` is forcing, ``\mu`` is 
 linear drag, and ``\nu`` is hyperviscosity of order ``n_\nu``. Plain old viscosity corresponds 
 to ``n_\nu = 1``.
 
+In the case that the imposed background zonal flow is just a constant, the above simplifies to:
+
+```math
+\partial_t q + \mathsf{J}(\psi, q + \eta) + U \partial_x (q + \eta) + β \partial_x \psi = \underbrace{-\left[\mu + \nu(-1)^{n_\nu} \nabla^{2n_\nu} \right] q}_{\textrm{dissipation}} + F ,
+```
+
+and thus the advection of ``q`` can be incorporated in the linear term ``L``.
 
 ### Implementation
 
 The equation is time-stepped forward in Fourier space:
 
 ```math
-\partial_t \widehat{q} = - \widehat{\mathsf{J}(\psi, q + \eta)} + \beta \frac{i k_x}{|𝐤|^2 + 1/\ell^2} \widehat{q} - \left(\mu + \nu |𝐤|^{2n_\nu} \right) \widehat{q} + \widehat{F} .
+\partial_t \widehat{q} = - \widehat{\mathsf{J}(\psi, q)} - \widehat{U \partial_x Q} - \widehat{U \partial_x q}
++ \widehat{(\partial_y \psi) (\partial_x Q)}  - \widehat{(\partial_x \psi)(\partial_y Q)} - \left(\mu + \nu |𝐤|^{2n_\nu} \right) \widehat{q} + \widehat{F} .
 ```
 
+In doing so the Jacobian is computed in the conservative form: ``\mathsf{J}(f,g) =
+\partial_y [ (\partial_x f) g] - \partial_x[ (\partial_y f) g]``.
+
 The state variable `sol` is the Fourier transform of the sum of relative vorticity and vortex 
 stretching (when the latter is applicable), [`qh`](@ref GeophysicalFlows.SingleLayerQG.Vars).
 
-The Jacobian is computed in the conservative form: ``\mathsf{J}(f, g) =
-\partial_y [ (\partial_x f) g] - \partial_x[ (\partial_y f) g]``.
-
 The linear operator is constructed in `Equation`
 
 ```@docs
@@ -122,4 +139,4 @@ Other diagnostic include: [`energy_dissipation`](@ref GeophysicalFlows.SingleLay
   (barotropic quasi-geostrophic flow with ``\beta=0``) above topography.
 
 - [`examples/singlelayerqg_decaying_barotropic_equivalentbarotropic.jl`](@ref singlelayerqg_decaying_barotropic_equivalentbarotropic_example):
-  Simulate two dimensional turbulence (``\beta=0``) with both infinite and finite Rossby radius of deformation and compares the evolution of the two.
+  Simulate two dimensional turbulence (``\beta=0``) with both infinite and finite Rossby radius of deformation and compares the evolution of the two.