Merge pull request #219 from FourierFlows/ncc/add-scalability-remarks

Add scalability remarks

Project.toml

@@ -2,7 +2,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>"]
-version = "0.11.5"
+version = "0.11.6"
 
 [deps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"

README.md

@@ -36,6 +36,7 @@
 This package leverages the [FourierFlows.jl] framework to provide modules for solving problems in
 Geophysical Fluid Dynamics on periodic domains using Fourier-based pseudospectral methods.
 
+
 ## Installation
 
 To install, do
@@ -59,6 +60,28 @@ the package's [documentation].
 Some animations created with GeophysicalFlows.jl are [online @ youtube].
 
 
+## Scalability
+
+For now, GeophysicalFlows.jl is restricted to run on either a single CPU or single GPU. These
+restrictions come from FourierFlows.jl. Multi-threading can enhance performance for the Fourier
+transforms. By default, FourierFlows.jl will use the maximum number of threads available on 
+your machine. You can set the number of threads used by FourierFlows.jl by setting the 
+environment variable, e.g.,
+
+```
+$ export JULIA_NUM_THREADS=4
+```
+
+For more information on multi-threading users are directed to the [Julia Documentation](https://docs.julialang.org/en/v1/manual/multi-threading/).
+
+If your machine has more than one GPU available, then functionality within CUDA.jl package 
+enables the user to choose the GPU device that FourierFlows.jl should use. The user is referred
+to the [CUDA.jl Documentation](https://juliagpu.github.io/CUDA.jl/stable/lib/driver/#Device-Management);
+in particular, [`CUDA.devices`](https://juliagpu.github.io/CUDA.jl/stable/lib/driver/#CUDA.devices) 
+and [`CUDA.CuDevice`](https://juliagpu.github.io/CUDA.jl/stable/lib/driver/#CUDA.CuDevice). 
+The user is also referred to the [GPU section](https://fourierflows.github.io/FourierFlowsDocumentation/stable/gpu/) in the FourierFlows.jl documentation.
+
+
 ## Modules
 
 * `TwoDNavierStokes`: the two-dimensional vorticity equation.
@@ -98,7 +121,7 @@ For more information, check out our [contributor's guide](https://github.com/Fou
 
 The code is citable via [zenodo](https://zenodo.org). Please cite as:
 
-> Navid C. Constantinou, Gregory L. Wagner, and co-contributors. (2021). FourierFlows/GeophysicalFlows.jl: GeophysicalFlows v0.11.5 (Version v0.11.5). Zenodo.  [http://doi.org/10.5281/zenodo.1463809](http://doi.org/10.5281/zenodo.1463809)
+> Navid C. Constantinou, Gregory L. Wagner, and co-contributors. (2021). FourierFlows/GeophysicalFlows.jl: GeophysicalFlows v0.11.6 (Version v0.11.6). Zenodo.  [http://doi.org/10.5281/zenodo.1463809](http://doi.org/10.5281/zenodo.1463809)
 
 
 [FourierFlows.jl]: https://github.com/FourierFlows/FourierFlows.jl

docs/make.jl

@@ -65,6 +65,7 @@ sitename = "GeophysicalFlows.jl",
    pages = Any[
             "Home"    => "index.md",
             "Installation instructions" => "installation_instructions.md",
+            "GPU" => "gpu.md",
             "Examples" => [
               "TwoDNavierStokes" => Any[
                 "generated/twodnavierstokes_decaying.md",

docs/src/gpu.md

@@ -0,0 +1,25 @@
+# GPU
+
+GPU-functionality is enabled via `FourierFlows.jl`. For more information on how `FourierFlows.jl`
+handled with GPUs we urge you to the corresponding [`FourierFlows.jl` documentation section ](https://fourierflows.github.io/FourierFlowsDocumentation/stable/gpu/)
+
+All `GeophysicalFlows.jl` modules can be run on GPU by providing `GPU()` as the device (`dev`) 
+argument in the problem constructors. For example,
+
+```julia
+julia> GeophysicalFlows.TwoDNavierStokes.Problem(GPU())
+Problem
+  ├─────────── grid: grid (on GPU)
+  ├───── parameters: params
+  ├────── variables: vars
+  ├─── state vector: sol
+  ├─────── equation: eqn
+  ├────────── clock: clock
+  └──── timestepper: RK4TimeStepper
+```
+
+## Selecting GPU device
+
+`FourierFlows.jl` can only utilize a single GPU. If your machine has more than one GPU available, 
+then functionality within `CUDA.jl` package enables the user to choose the GPU device that 
+`FourierFlows.jl` should use. The user is referred to the [`CUDA.jl` Documentation](https://juliagpu.github.io/CUDA.jl/stable/lib/driver/#Device-Management); in particular, [`CUDA.devices`](https://juliagpu.github.io/CUDA.jl/stable/lib/driver/#CUDA.devices) and [`CUDA.CuDevice`](https://juliagpu.github.io/CUDA.jl/stable/lib/driver/#CUDA.CuDevice).