Add double buffering related features

Project.toml

@@ -28,8 +28,8 @@ ParallelStencil_OneAPIExt = "oneAPI"
 
 [compat]
 AMDGPU = "1, 2"
-CUDA = "3.12, 4, 5"
-CellArrays = "0.3.2"
+CUDA = "3.12, 4, 5, 6"
+CellArrays = "0.3.4"
 Enzyme = "0.12, 0.13"
 KernelAbstractions = "0.9"
 MacroTools = "0.5"

README.md

@@ -24,6 +24,7 @@ Beyond traditional high-performance computing, ParallelStencil supports automati
 - [Seamless interoperability with communication packages and hiding communication](#seamless-interoperability-with-communication-packages-and-hiding-communication)
 - [Support for architecture-agnostic low level kernel programming](#support-for-architecture-agnostic-low-level-kernel-programming)
 - [Support for logical arrays of small arrays / structs](#support-for-logical-arrays-of-small-arrays--structs)
+- [Support for scientific field types](#support-for-scientific-field-types)
 - [Support for automatic differentiation of architecture-agnostic parallel kernels](#support-for-automatic-differentiation-of-architecture-agnostic-parallel-kernels)
 - [Module documentation callable from the Julia REPL / IJulia](#module-documentation-callable-from-the-julia-repl--ijulia)
 - [Concise single/multi-xPU miniapps](#concise-singlemulti-xpu-miniapps)
@@ -336,6 +337,25 @@ A = @zeros(nx, ny, nz, celltype=SymmetricTensor3D)
 ```
 Details are found in the [Module documentation callable from the Julia REPL / IJulia](#module-documentation-callable-from-the-julia-repl--ijulia).
 
+## Support for scientific field types
+Building on the architecture-agnostic allocation macros earlier introduced (see [Parallelization and optimization with one macro call](#parallelization-and-optimization-with-one-macro-call)), ParallelStencil provides dedicated field allocation macros that allocate fields whose number of components and per-component array dimensionality follow the length of the passed `gridsize`; padding, when enabled at package initialization, applies uniformly to all of them. The scalar field macro `@Field` allocates a single array; the component field macros `@XField`/`@YField`/`@ZField`, `@BXField`/`@BYField`/`@BZField`, and `@XXField`/`@YYField`/`@ZZField`/`@XYField`/`@XZField`/`@YZField` allocate the individual components of a vector, vector with boundaries, or tensor field, respectively; `@VectorField` and `@BVectorField` allocate a whole vector field (optionally with boundaries) as a tuple of component arrays; `@TensorField` allocates a whole tensor field as a tuple of component arrays; and `@allocate` allocates multiple kinds of fields at once on a shared `gridsize` (and initializes them).
+```julia
+# Allocate one scalar field on a 2-D grid
+T = @Field((nx, ny))
+
+# Allocate component fields of a vector and a tensor field
+Vx, Vy = @XField((nx, ny)), @YField((nx, ny))
+Txx, Tyy, Tzz, Txy, Txz, Tyz = @XXField((nx, ny)), @YYField((nx, ny)), @ZZField((nx, ny)),
+                               @XYField((nx, ny)), @XZField((nx, ny)), @YZField((nx, ny))
+
+# Allocate a whole vector field (with boundaries) and a tensor field at once
+V, T = @BVectorField((nx, ny)), @TensorField((nx, ny))
+
+# Allocate multiple kinds of fields on a shared gridsize in one call
+A, B = @allocate((nx, ny), A=@VectorField, B=@XField)
+```
+The aggregate field type aliases exposed by the generated `Data.Fields`/`TData.Fields` submodules reflect the component structure: `VectorField`/`BVectorField` keep a single shared parameter between the number of components and the per-component array dimensionality (for a `gridsize` of length `N`, the number of components always equals `N`), while `TensorField` takes a separate parameter for the number of components in addition to the per-component array dimensionality (its number of components `N*(N+1)/2` is always distinct from `N`). See `?@Field`, `?@VectorField`, `?@BVectorField`, `?@TensorField`, `?@allocate` and the generated `Data.Fields` module for the full reference.
+
 ## Support for automatic differentiation of architecture-agnostic parallel kernels
 [Enzyme.jl]-powered automatic differentiation of architecture-agnostic parallel kernels is fully integrated into ParallelStencil's API and exposed both with high-level and generic syntax. The keyword argument `∇` is enough to trigger a parallel call to the gradient kernel instead of the kernel itself, e.g:
 ```julia

src/FieldAllocators.jl

@@ -24,6 +24,9 @@ Provides macros for the allocation of different kind of fields on a grid of size
 ###### Tensor fields
 - [`@TensorField`](@ref)
 
+###### Double-buffered fields (2B suffix)
+For every field allocator macro there is a corresponding double-buffered version with a `2B` suffix (e.g. [`@Field2B`](@ref), [`@VectorField2B`](@ref), [`@TensorField2B`](@ref)). A `2B` macro allocates a `NamedTuple{(:in, :out)}` of two single-buffer fields and is intended to enable ParallelStencil's automatic double-buffering optimization.
+
 To see a description of a macro type `?<macroname>` (including the `@`).
 """
 module FieldAllocators
@@ -61,5 +64,22 @@ module FieldAllocators
     macro XYYZZField(args...)    check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@XYYZZField($(args...)))); end
     macro XXYZZField(args...)    check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@XXYZZField($(args...)))); end
 
-    export @allocate, @Field, @VectorField, @BVectorField, @TensorField, @XField, @BXField, @YField, @BYField, @ZField, @BZField, @XXField, @YYField, @ZZField, @XYField, @XZField, @YZField
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_DOC,        "@init_parallel_kernel" => "@init_parallel_stencil") macro Field2B(args...)        check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@Field2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.VECTORFIELD2B_DOC,  "@init_parallel_kernel" => "@init_parallel_stencil") macro VectorField2B(args...)  check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@VectorField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.BVECTORFIELD2B_DOC, "@init_parallel_kernel" => "@init_parallel_stencil") macro BVectorField2B(args...) check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@BVectorField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.TENSORFIELD2B_DOC,  "@init_parallel_kernel" => "@init_parallel_stencil") macro TensorField2B(args...)  check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@TensorField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro XField2B(args...)       check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@XField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro BXField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@BXField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro YField2B(args...)       check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@YField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro BYField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@BYField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro ZField2B(args...)       check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@ZField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro BZField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@BZField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro XXField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@XXField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro YYField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@YYField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro ZZField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@ZZField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro XYField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@XYField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro XZField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@XZField2B($(args...)))); end
+    @doc replace(ParallelKernel.FieldAllocators.FIELD2B_COMP_DOC,   "@init_parallel_kernel" => "@init_parallel_stencil") macro YZField2B(args...)      check_initialized(__module__); esc(:(ParallelStencil.ParallelKernel.FieldAllocators.@YZField2B($(args...)))); end
+
+    export @allocate, @Field, @VectorField, @BVectorField, @TensorField, @XField, @BXField, @YField, @BYField, @ZField, @BZField, @XXField, @YYField, @ZZField, @XYField, @XZField, @YZField, @Field2B, @VectorField2B, @BVectorField2B, @TensorField2B, @XField2B, @BXField2B, @YField2B, @BYField2B, @ZField2B, @BZField2B, @XXField2B, @YYField2B, @ZZField2B, @XYField2B, @XZField2B, @YZField2B
 end