Define to_device and to_cpu

Update src/to_device.jl

Co-authored-by: Gabriele Bozzola <gbozzola@caltech.edu>

More docs

NEWS.md

@@ -4,6 +4,11 @@ ClimaCore.jl Release Notes
 main
 -------
 
+ - A new `Adapt` wrapper was added, `to_device`, which allows users to adapt datalayouts, spaces, fields, and fieldvectors between the cpu and gpu. PR [2159](https://github.com/CliMA/ClimaCore.jl/pull/2159).
+ - Remap interpolation cuda threading was improved. PR [2159](https://github.com/CliMA/ClimaCore.jl/pull/2159).
+ - `center_space` and `face_space` are now exported from `CommonSpaces`. PR [2157](https://github.com/CliMA/ClimaCore.jl/pull/2157).
+ - Limiter debug printing can now be suppressed, and printed at the end of a simulation, using `Limiters.print_convergence_stats(limiter)`. PR [2152](https://github.com/CliMA/ClimaCore.jl/pull/2152).
+ - Fixed getidx for `GradientC2F` with `SetValue` bcs. PR [2148](https://github.com/CliMA/ClimaCore.jl/pull/2148).
  - Added support `data2array` for `DataF` (i.e., `PointField`s). PR [2143](https://github.com/CliMA/ClimaCore.jl/pull/2143).
  - `HDF5Reader` / `HDF5Writer` now support `do`-syntax. PR [2147](https://github.com/CliMA/ClimaCore.jl/pull/2147).
 

docs/make.jl

@@ -96,6 +96,7 @@ withenv("GKSwstype" => "nul") do
             ],
             "Contributing guide" => "Contributing.md",
             "Code of Conduct" => "code_of_conduct.md",
+            "Frequently asked questions" => "faq.md",
             "references.md",
         ],
     )

docs/src/api.md

@@ -402,6 +402,13 @@ Remapping.interpolate_array
 Remapping.interpolate
 ```
 
+## Converting between devices
+
+```@docs
+to_device
+to_cpu
+```
+
 ## DebugOnly
 
 ```@docs

docs/src/faq.md

@@ -0,0 +1,27 @@
+# Frequently asked questions
+
+## Moving objects between the CPU and GPU.
+
+Occasionally, it's helpful to move data between the CPU and GPU. ClimaCore
+supports this through a method, [`to_device`](@ref ClimaCore.to_device). We also
+have a specialized version for converting only to the CPU: [`to_cpu`](@ref ClimaCore.to_cpu).
+
+For example, to create a CUDA column space from a CPU space, you can use:
+
+```julia
+using ClimaComms
+using ClimaCore
+using ClimaCore.CommonSpaces
+cpu_space = ColumnSpace(;
+    z_elem = 10,
+    z_min = 0,
+    z_max = 10,
+    staggering = CellCenter()
+)
+cuda_space = ClimaCore.to_device(ClimaComms.CUDADevice(), cpu_space)
+```
+
+Similarly, we can convert back with `to_cpu`:
+```julia
+new_cpu_space = ClimaCore.to_cpu(cuda_space)
+```

src/ClimaCore.jl

@@ -28,5 +28,6 @@ include("CommonGrids/CommonGrids.jl")
 include("CommonSpaces/CommonSpaces.jl")
 
 include("deprecated.jl")
+include("to_device.jl")
 
 end # module

src/to_device.jl

@@ -0,0 +1,60 @@
+import Adapt
+import ClimaComms
+
+"""
+    out = to_device(device, x::Union{
+        DataLayouts.AbstractData,
+        Spaces.AbstractSpace,
+        Fields.Field,
+        Fields.FieldVector,
+    })
+
+Move `x` to the given `device`.
+
+This is particularly useful to move different types of `Space.AbstractSpace`s,
+`Fields.Field`s, and `Fields.FieldVector`s from CPUs to GPUs and viceversa.
+
+If the input is already defined on the target device, returns a copy.
+
+This means that `out === x` will not in general be satisfied.
+"""
+function to_device(
+    device::ClimaComms.AbstractDevice,
+    x::Union{
+        DataLayouts.AbstractData,
+        Spaces.AbstractSpace,
+        Fields.Field,
+        Fields.FieldVector,
+    },
+)
+    return Adapt.adapt(ClimaComms.array_type(device), x)
+end
+
+to_device(::ClimaComms.CPUMultiThreaded, _) = error("Not supported")
+
+
+"""
+    out = to_cpu(x::Union{
+        DataLayouts.AbstractData,
+        Spaces.AbstractSpace,
+        Fields.Field,
+        Fields.FieldVector,
+    })
+
+Move `x` backing data to the CPU.
+
+This is particularly useful for `Space.AbstractSpace`s,
+`Fields.Field`s, and `Fields.FieldVector`s.
+
+Returns a copy.
+
+This means that `out === x` will not in general be satisfied.
+"""
+to_cpu(
+    x::Union{
+        DataLayouts.AbstractData,
+        Spaces.AbstractSpace,
+        Fields.Field,
+        Fields.FieldVector,
+    },
+) = to_device(ClimaComms.CPUSingleThreaded(), x)