ParallelStencil.jl

Appearance

API reference ​

This is the official API reference of ParallelStencil. Note that it can also be queried interactively from the Julia REPL using the help mode:

julia
julia> using ParallelStencil
julia>?
help?> ParallelStencil

Module ​

ParallelStencil.ParallelStencil Module

Module ParallelStencil

Enables domain scientists to write high-level code for parallel high-performance stencil computations that can be deployed on both GPUs and CPUs. Single-architecture backends (CUDA, AMDGPU, Metal, Threads, Polyester) remain fixed to their hardware, while abstraction-layer backends such as KernelAbstractions let you switch the runtime target through select_hardware and inspect it with current_hardware without reparsing code. Detailed workflow guidance is available in the interactive prototyping runtime selection section.

General overview and examples

https://omlins.github.io/ParallelStencil.jl/stable

Primary macros

Advanced

Runtime hardware selection

Macros available for @parallel_indices kernels

Advanced

Warp-level primitives

Warp-level primitives support

Warp-level primitives are only partially supported with the KernelAbstractions and Metal backends.

:::

Submodules

Modules generated in caller

Activation of GPU support

The support for GPU (CUDA, AMDGPU or Metal) is provided with extensions and requires therefore an explicit installation of the corresponding packages (CUDA.jl, AMDGPU.jl or Metal.jl). Note that it is not required to import explicitly the corresponding module (CUDA, AMDGPU or Metal); this is automatically done by @init_parallel_stencil.

To see a description of a macro or module type ?<macroname> (including the @) or ?<modulename>, respectively.

source

Initialization ​

ParallelStencil.@init_parallel_stencil Macro
julia
@init_parallel_stencil(package, numbertype, ndims)
@init_parallel_stencil(package, numbertype, ndims, inbounds=...)
@init_parallel_stencil(package=..., ndims=..., inbounds=...)

Initialize the package ParallelStencil, giving access to its main functionality. Creates a module Data in the module where @init_parallel_stencil is called from; the module Data contains the types Data.Number, Data.Array and Data.CellArray (type ?Data after calling @init_parallel_stencil to see the full description of the module). When the abstraction-layer backend KernelAbstractions is selected, the concrete runtime hardware is chosen later via select_hardware and inspected with current_hardware; consult the interactive prototyping runtime selection section for an end-to-end workflow.

Convenience modules

Data and TData modules with hardware-specific array aliases are generated only for single-architecture backends (CUDA, AMDGPU, Metal, Threads, Polyester). KernelAbstractions users trade off the additional convenience modules for runtime hardware selection instead.

Arguments

  • package::Module: the package used for parallelization (CUDA, AMDGPU, Metal, Threads, Polyester, or KernelAbstractions when deferring the hardware decision to runtime).

  • numbertype::DataType: the type of numbers used by @zeros, @ones, @rand and @fill and in all array types of module Data (e.g. Float32 or Float64). It is contained in Data.Number after @init_parallel_stencil. The numbertype can be omitted if the other arguments are given as keyword arguments (in that case, the numbertype will have to be given explicitly when using the types provided by the module Data).

  • ndims::Integer: the number of dimensions used for the stencil computations in the kernels: 1, 2 or 3 (overwritable in each kernel definition).

  • inbounds::Bool=false: whether to apply @inbounds to the kernels by default (overwritable in each kernel definition).

See also: Data, select_hardware, current_hardware

source

Parallel kernels ​

ParallelStencil.@parallel Macro
julia
@parallel kernel
@parallel inbounds=... memopt=... ndims=... kernel
@parallel inbounds=... memopt=true optvars=... loopdim=... loopsize=... optranges=... optimize_halo_read=... useshmemhalos=... kernel

Declare the kernel parallel and containing stencil computations be performed with one of the submodules ParallelStencil.FiniteDifferences{1D|2D|3D} (or with a compatible custom module or set of macros).

Optional keyword arguments

  • inbounds::Bool: whether to apply @inbounds to the kernel. The default is false or as set with the inbounds keyword argument of @init_parallel_stencil.

  • memopt::Bool=false: whether to perform advanced stencil-specific on-chip memory optimisations. Eligible memory-optimized declarations support two or three parallel indices.

Advanced optional keyword arguments

  • ndims::Integer|Tuple: the number of dimensions used for the stencil computations in the kernels: 1, 2 or 3 (or a tuple containing any of the previous in order to generate a method for each of the given values - this can only work correctly if the macros used and loaded work for any of the chosen values of ndims!). A default can be set with the ndims keyword argument of @init_parallel_stencil. The keyword argument N becomes mandatory when ndims is a tuple in order to dispatch on the number of dimensions (see below).

  • N::Integer|Tuple: the value(s) a type parameter N in the kernel method signatures must take. The values are typically computed based on ndims (set with the corresponding keyword argument of the @parallel macro or @init_parallel_stencil), which will be substituted in the expression before evaluating it. This enables dispatching on the number of dimensions in the kernel methods (e.g., @parallel ndims=(1,3) N=ndims function f(A::Data.Array{N}) ... end). The keyword argument N is mandatory if ndims is a tuple and must then furthermore be a tuple of the same length as ndims.

  • optvars::Symbol | Tuple{Vararg{Symbol}}: the read-only stencil input or inputs to optimize explicitly. By default, all eligible read-only multi-point stencil inputs are optimized.

  • loopdim::Integer: the optimization dimension used by memory-optimized declarations. Use 2 for 2-D declarations and 3 for 3-D declarations.

  • loopsize::Integer: the loop size used by the memory-optimized execution path.

  • optranges: per-optimized-array optimization ranges selecting the optimized x-y region and optimization-dimension region.

  • optimize_halo_read::Bool: whether halo reads are optimized together with the selected memory-optimization ranges.

  • useshmemhalos: per-optimized-array shared-memory halo usage for 3-D memory-optimized declarations.

Memory optimization

Two-dimensional memory-optimized declarations use register-only caching in the second dimension. Shared-memory caching belongs only to the 3-D memory-optimized declaration surface, where loopdim=3 and useshmemhalos may be used.

See also: @init_parallel_stencil

julia
@parallel kernelcall
@parallel ∇=... kernelcall

Advanced

@parallel ranges kernelcall
@parallel nblocks nthreads kernelcall
@parallel ranges nblocks nthreads kernelcall
@parallel (...) configcall=... backendkwargs... kernelcall
@parallel ∇=... ad_mode=... ad_annotations=... (...) backendkwargs... kernelcall

Declare the kernelcall parallel. The kernel will automatically be called as required by the package for parallelization selected with @init_parallel_stencil (however, see below the note on automatic computation of ranges). Synchronizes at the end of the call (if a stream is given via keyword arguments, then it synchronizes only this stream). If the called kernel was declared with memopt=true, this wrapper automatically uses the stored declaration metadata to select the memory-optimized launch-preparation path. The keyword argument ∇ triggers a parallel call to the gradient kernel instead of the kernel itself. The automatic differentiation is performed with the package Enzyme.jl (refer to the corresponding documentation for Enzyme-specific terms used below); Enzyme needs to be imported before ParallelStencil in order to have it load the corresponding extension.

Automatic computation of ranges

Automatic computation of ranges for @parallel <kernelcall> is only possible if the number of parallel indices used by the kernel is equal to the number of dimensions of the highest-dimensional input arrays. Otherwise, specify the ranges manually with @parallel ranges=... <kernelcall>.

Memory-optimized launches

Kernels declared with memopt=true activate memory-optimized launch preparation automatically; no repeated launch-time memopt keyword is needed. The launch preparation derives ranges, launch parameters, and shared-memory size from the stored declaration metadata when applicable.

Runtime hardware selection

When KernelAbstractions is chosen as the package for parallelization, this wrapper consults current_hardware to determine the runtime hardware target. The symbol defaults to :cpu and can be switched to select other targets via select_hardware.

Arguments

  • kernelcall: a call to a kernel that is declared parallel.

Advanced optional arguments

  • ranges::Tuple{UnitRange{},UnitRange{},UnitRange{}} | Tuple{UnitRange{},UnitRange{}} | Tuple{UnitRange{}} | UnitRange{}: the ranges of indices in each dimension for which computations must be performed.

  • nblocks::Tuple{Integer,Integer,Integer}: the number of blocks to be used if the package CUDA, AMDGPU, Metal or KernelAbstractions was selected with @init_parallel_stencil.

  • nthreads::Tuple{Integer,Integer,Integer}: the number of threads to be used if the package CUDA, AMDGPU, Metal or KernelAbstractions was selected with @init_parallel_stencil.

Keyword arguments

Advanced

  • ∇: the variable(s) with respect to which the kernel is to be differentiated automatically and a duplicate for each variable to store the result in, separated by ->, e.g., ∇=(A->Ā, B->B̄). Setting this keyword triggers a parallel call to the gradient kernel instead of the kernel itself. The duplicate variables are by default passed to Enzyme with the annotation DuplicatedNoNeed, e.g., DuplicatedNoNeed(A, Ā). Use the keyword argument ad_annotations to modify this behavior.

  • ad_mode=Enzyme.Reverse: the automatic differentiation mode (see the documentation of Enzyme.jl for more information).

  • ad_annotations=(): Enzyme variable annotations for automatic differentiation in the format (<keyword>=<variable(s)>, <keyword>=<variable(s)>, ...), where <variable(s)> can be a single variable or a tuple of variables (e.g., ad_annotations=(Duplicated=B, Active=(a,b))). Currently supported annotations are: (:Const, :Active, :Duplicated, :DuplicatedNoNeed).

  • configcall=kernelcall: a call to a kernel that is declared parallel, which is used for determining the kernel launch parameters. This keyword is useful, e.g., for generic automatic differentiation using the low-level submodule AD.

  • backendkwargs...: keyword arguments to be passed further to CUDA.jl, AMDGPU.jl, Metal.jl or KernelAbstractions.jl (ignored for Threads and Polyester).

Performance note

Kernel launch parameters are automatically defined with heuristics, where not defined with optional kernel arguments. For CUDA and AMDGPU, nthreads is typically set to (32,8,1) and nblocks accordingly to ensure that enough threads are launched.

See also: @init_parallel_stencil

source
ParallelStencil.@parallel_indices Macro
julia
@parallel_indices indices kernel
@parallel_indices indices inbounds=... memopt=... ndims=... kernel
@parallel_indices indices inbounds=... memopt=true optvars=... loopdim=... loopsize=... optranges=... optimize_halo_read=... useshmemhalos=... kernel

Declare the kernel parallel and generate the given parallel indices inside the kernel using the package for parallelization selected with @init_parallel_stencil.

Runtime hardware selection

When KernelAbstractions is initialized, this wrapper consults current_hardware to determine the runtime hardware target. The symbol defaults to :cpu and can be switched to select other targets via select_hardware.

Optional keyword arguments

  • inbounds::Bool: whether to apply @inbounds to the kernel. The default is false or as set with the inbounds keyword argument of @init_parallel_stencil.

  • memopt::Bool=false: whether to perform advanced stencil-specific on-chip memory optimisations. Eligible memory-optimized declarations support two or three generated parallel indices.

Advanced optional keyword arguments

  • ndims::Integer|Tuple: the number of indexing dimensions desired when using splat syntax for the indices: 1, 2, 3 (a default ndims value can be set with the corresponding keyword argument of @init_parallel_stencil) or a tuple containing any of the previous in order to generate a method for each of the given ndims values. Concretely, the splat syntax (e.g., @parallel_indices (I...) ndims=(2,3) ...) generates a tuple of parallel indices (I in this example) where the length is given by the ndims value (here 2 for the first method and 3 for the second). This makes it possible to write kernels that are agnostic to the number of dimensions (writing, e.g., A[I...] to access elements of the array A). The keyword argument N becomes mandatory when ndims is a tuple in order to dispatch on the number of dimensions (see below).

  • N::Integer|Tuple: the value(s) a type parameter N in the kernel method signatures must take. The values are typically computed based on ndims (set with the corresponding keyword argument of the @parallel_indices macro or @init_parallel_stencil), which will be substituted in the expression before evaluating it. This enables dispatching on the number of dimensions in the kernel methods (e.g., @parallel_indices (I...) ndims=(1,3) N=ndims function f(A::Data.Array{N}) ... end). The keyword argument N is mandatory if ndims is a tuple and must then furthermore be a tuple of the same length as ndims.

  • optvars::Symbol | Tuple{Vararg{Symbol}}: the read-only stencil input or inputs to optimize explicitly. By default, all eligible read-only multi-point stencil inputs are optimized.

  • loopdim::Integer: the optimization dimension used by memory-optimized declarations. Use 2 for 2-D declarations and 3 for 3-D declarations.

  • loopsize::Integer: the loop size used by the memory-optimized execution path.

  • optranges: per-optimized-array optimization ranges selecting the optimized x-y region and optimization-dimension region.

  • optimize_halo_read::Bool: whether halo reads are optimized together with the selected memory-optimization ranges.

  • useshmemhalos: per-optimized-array shared-memory halo usage for 3-D memory-optimized declarations.

Memory optimization

Two-index memory-optimized declarations use register-only caching in the second dimension. Shared-memory caching belongs only to the 3-D memory-optimized declaration surface, where loopdim=3 and useshmemhalos may be used.

See also: @init_parallel_stencil

source
ParallelStencil.@parallel_async Macro
julia
@parallel_async kernelcall
@parallel_async ∇=... kernelcall

Advanced

@parallel_async ranges kernelcall
@parallel_async nblocks nthreads kernelcall
@parallel_async ranges nblocks nthreads kernelcall
@parallel_async (...) configcall=... backendkwargs... kernelcall
@parallel_async ∇=... ad_mode=... ad_annotations=... (...) backendkwargs... kernelcall

Declare the kernelcall parallel as with @parallel (see @parallel for more information); deactivates however automatic synchronization at the end of the call. Use @synchronize for synchronizing.

Runtime hardware selection

When KernelAbstractions is initialized, this wrapper consults current_hardware to determine the runtime hardware target. The symbol defaults to :cpu and can be switched to select other targets via select_hardware.

Performance note

@parallel_async falls currently back to running synchronously if the package Threads or Polyester was selected with @init_parallel_stencil.

See also: @synchronize, @parallel

source
ParallelStencil.@synchronize Macro
julia
@synchronize()

Synchronize the GPU/CPU.

See also: @parallel_async

source

Allocation ​

ParallelStencil.@zeros Macro
julia
@zeros(args...)
@zeros(args..., <keyword arguments>)

Call zeros(eltype, args...), where eltype is by default the numbertype selected with @init_parallel_stencil and the function zeros is chosen to be compatible with the package for parallelization selected with @init_parallel_stencil (zeros for Threads or Polyester, CUDA.zeros for CUDA, AMDGPU.zeros for AMDGPU, Metal.zeros for Metal, and a runtime-dispatched allocator for KernelAbstractions that honours current_hardware — defaulting to :cpu and switchable to other targets via select_hardware).

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

  • celldims::Integer|NTuple{N,Integer}=1: the dimensions of each array cell. Each cell can contain a single value (default) or an N-dimensional array of the specified dimensions.

Advanced

  • celltype::DataType: the type of each array cell; it must be generated with the macro @CellType. The keyword argument celltype is incompatible with the other keyword arguments: if any of them is set, then the celltype is automatically defined. The celltype needs only to be specified to use named cell fields. Note that values can always be addressed with array indices, even when cell field names are defined.

  • blocklength::Integer: refers to the amount of values of a same Cell field that are stored contigously (blocklength=1 means array of struct like storage; blocklength=prod(dims) means array struct of array like storage; blocklength=0 is an alias for blocklength=prod(dims), enabling better peformance thanks to more specialized dispatch). By default, blocklength is automatically set to 0 if a GPU package was chosen with @init_parallel_stencil and to 1 if a CPU package was chosen. Furthermore, the argument blocklength is only of effect if either celldims or celltype is set, else it is ignored.

See also: @ones, @rand, @falses, @trues, @fill, @CellType

source
ParallelStencil.@ones Macro
julia
@ones(args...)
@ones(args..., <keyword arguments>)

Call ones(eltype, args...), where eltype is by default the numbertype selected with @init_parallel_stencil and the function ones is chosen to be compatible with the package for parallelization selected with @init_parallel_stencil (ones for Threads or Polyester, CUDA.ones for CUDA, AMDGPU.ones for AMDGPU, Metal.ones for Metal, and a runtime-dispatched allocator for KernelAbstractions that honours current_hardware — defaulting to :cpu and switchable to other targets via select_hardware).

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

  • celldims::Integer|NTuple{N,Integer}=1: the dimensions of each array cell. Each cell can contain a single value (default) or an N-dimensional array of the specified dimensions.

Advanced

  • celltype::DataType: the type of each array cell; it must be generated with the macro @CellType. The keyword argument celltype is incompatible with the other keyword arguments: if any of them is set, then the celltype is automatically defined. The celltype needs only to be specified to use named cell fields. Note that values can always be addressed with array indices, even when cell field names are defined.

  • blocklength::Integer: refers to the amount of values of a same Cell field that are stored contigously (blocklength=1 means array of struct like storage; blocklength=prod(dims) means array struct of array like storage; blocklength=0 is an alias for blocklength=prod(dims), enabling better peformance thanks to more specialized dispatch). By default, blocklength is automatically set to 0 if a GPU package was chosen with @init_parallel_stencil and to 1 if a CPU package was chosen. Furthermore, the argument blocklength is only of effect if either celldims or celltype is set, else it is ignored.

See also: @zeros, @rand, @falses, @trues, @fill, @CellType

source
ParallelStencil.@rand Macro
julia
@rand(args...)
@rand(args..., <keyword arguments>)

Call rand(eltype, args...), where eltype is by default the numbertype selected with @init_parallel_stencil and the function rand is chosen/implemented to be compatible with the package for parallelization selected with @init_parallel_stencil (dispatching via current_hardware when KernelAbstractions is active; default :cpu, switchable through select_hardware).

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Keyword arguments

  • eltype::DataType: the type of the elements, which can be numbers, indices, booleans or enums.

  • celldims::Integer|NTuple{N,Integer}=1: the dimensions of each array cell. Each cell can contain a single value (default) or an N-dimensional array of the specified dimensions.

Advanced

  • celltype::DataType: the type of each array cell; it must be generated with the macro @CellType. The keyword argument celltype is incompatible with the other keyword arguments: if any of them is set, then the celltype is automatically defined. The celltype needs only to be specified to use named cell fields. Note that values can always be addressed with array indices, even when cell field names are defined.

  • blocklength::Integer: refers to the amount of values of a same Cell field that are stored contigously (blocklength=1 means array of struct like storage; blocklength=prod(dims) means array struct of array like storage; blocklength=0 is an alias for blocklength=prod(dims), enabling better peformance thanks to more specialized dispatch). By default, blocklength is automatically set to 0 if a GPU package was chosen with @init_parallel_stencil and to 1 if a CPU package was chosen. Furthermore, the argument blocklength is only of effect if either celldims or celltype is set, else it is ignored.

See also: @zeros, @ones, @falses, @trues, @fill, @CellType

source
ParallelStencil.@falses Macro
julia
@falses(args...)
@falses(args..., <keyword arguments>)

Call falses(args...), where the function falses is chosen to be compatible with the package for parallelization selected with @init_parallel_stencil (dispatching via current_hardware when KernelAbstractions is active; default :cpu, switchable through select_hardware).

Keyword arguments

  • celldims::Integer|NTuple{N,Integer}=1: the dimensions of each array cell. Each cell can contain a single value (default) or an N-dimensional array of the specified dimensions.

Advanced

  • blocklength::Integer: refers to the amount of values of a same Cell field that are stored contigously (blocklength=1 means array of struct like storage; blocklength=prod(dims) means array struct of array like storage; blocklength=0 is an alias for blocklength=prod(dims), enabling better peformance thanks to more specialized dispatch). By default, blocklength is automatically set to 0 if a GPU package was chosen with @init_parallel_stencil and to 1 if a CPU package was chosen. Furthermore, the argument blocklength is only of effect if either celldims or celltype is set, else it is ignored.

See also: @zeros, @ones, @rand, @trues, @fill, @CellType

source
ParallelStencil.@trues Macro
julia
@trues(args...)
@trues(args..., <keyword arguments>)

Call trues(args...), where the function trues is chosen to be compatible with the package for parallelization selected with @init_parallel_stencil (dispatching via current_hardware when KernelAbstractions is active; default :cpu, switchable through select_hardware).

Keyword arguments

  • celldims::Integer|NTuple{N,Integer}=1: the dimensions of each array cell. Each cell can contain a single value (default) or an N-dimensional array of the specified dimensions.

Advanced

  • blocklength::Integer: refers to the amount of values of a same Cell field that are stored contigously (blocklength=1 means array of struct like storage; blocklength=prod(dims) means array struct of array like storage; blocklength=0 is an alias for blocklength=prod(dims), enabling better peformance thanks to more specialized dispatch). By default, blocklength is automatically set to 0 if a GPU package was chosen with @init_parallel_stencil and to 1 if a CPU package was chosen. Furthermore, the argument blocklength is only of effect if either celldims or celltype is set, else it is ignored.

See also: @zeros, @ones, @rand, @falses, @fill, @CellType

source
ParallelStencil.@fill Macro
julia
@fill(x, args...)
@fill(x, args..., <keyword arguments>)

Call fill(convert(eltype, x), args...), where eltype is by default the numbertype selected with @init_parallel_stencil and the function fill is chosen/implemented to be compatible with the package for parallelization selected with @init_parallel_stencil (dispatching via current_hardware when KernelAbstractions is active; default :cpu, switchable through select_hardware).

Advanced

The element type eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Keyword arguments

  • eltype::DataType: the type of the elements, which can be numbers, indices, booleans or enums.

  • celldims::Integer|NTuple{N,Integer}=1: the dimensions of each array cell. Each cell can contain a single value (default) or an N-dimensional array of the specified dimensions.

Advanced

  • celltype::DataType: the type of each array cell; it must be generated with the macro @CellType. The keyword argument celltype is incompatible with the other keyword arguments: if any of them is set, then the celltype is automatically defined. The celltype needs only to be specified to use named cell fields. Note that values can always be addressed with array indices, even when cell field names are defined.

  • blocklength::Integer: refers to the amount of values of a same Cell field that are stored contigously (blocklength=1 means array of struct like storage; blocklength=prod(dims) means array struct of array like storage; blocklength=0 is an alias for blocklength=prod(dims), enabling better peformance thanks to more specialized dispatch). By default, blocklength is automatically set to 0 if a GPU package was chosen with @init_parallel_stencil and to 1 if a CPU package was chosen. Furthermore, the argument blocklength is only of effect if either celldims or celltype is set, else it is ignored.

See also: @fill!, @zeros, @ones, @rand, @falses, @trues, @CellType

source
ParallelStencil.@fill! Macro
julia
@fill!(A, x)
@fill!(A, x)

Call fill!(A, x), where the function fill is chosen/implemented to be compatible with the package for parallelization selected with @init_parallel_stencil (dispatching via current_hardware when KernelAbstractions is active; default :cpu, switchable through select_hardware).

Arguments

  • A::Array|CellArray|TArray|TCellArray: the array to be filled with x.

  • x::Number|Data.Index|Enum|Collection{Number|Data.Index|Enum, celldims}: the content to fill A with. If A is an CellArray, then x can be either a single value or a collection of values (e.g. an array, tuple,...) of the size celldims of A.

See also: @fill

source
ParallelStencil.@CellType Macro
julia
@CellType(name, <keyword arguments>)

Create a cell type, which can then be passed to @zeros, @ones, @rand, @falses, @trues or @fill using the keyword argument celltype.

Advanced

The element type eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory, except if parametric=true is set. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • name: the name of the cell type.

Keyword arguments

  • eltype::DataType: the type of the elements, which can be numbers, indices, booleans or enums.

  • fieldnames::String|NTuple{N,String}: the names of the fields of the cell. Note that cell values can always be addressed with array indices, even when field names are defined.

  • dims::Integer|NTuple{N,Integer}=length(fieldnames): the dimensions of the cell. A cell can contain a single value or an N-dimensional array of the specified dimensions. A valid dims argument must fullfill prod(dims)==length(fieldnames). If dims is omitted, then it will be automatically set as dims=length(fieldnames), defining the cell to contain a 1-D array of appropriate length.

Advanced

  • parametric::Bool=false: whether the cell type has a fixed or parametrisable element type. If parametric=true is set, then the keyword argument eltype is invalid.

Examples

julia
@CellType SymmetricTensor2D fieldnames=(xx, zz, xz)
#(...)
A = @zeros(nx, ny, celltype=SymmetricTensor2D)

@CellType SymmetricTensor3D fieldnames=(xx, yy, zz, yz, xz, xy)
#(...)
A = @zeros(nx, ny, nz, celltype=SymmetricTensor3D)

@CellType Tensor2D fieldnames=(xxxx, yxxx, xyxx, yyxx, xxyx, yxyx, xyyx, yyyx, xxxy, yxxy, xyxy, yyxy, xxyy, yxyy, xyyy, yyyy) dims=(2,2,2,2)
#(...)
A = @zeros(nx, ny, celltype=Tensor2D)

@CellType SymmetricTensor2D fieldnames=(xx, zz, xz) parametric=true
#(...)
A = @zeros(nx, ny, celltype=SymmetricTensor2D{Float32})

@CellType SymmetricTensor2D fieldnames=(xx, zz, xz) eltype=Float32
#(...)
A = @zeros(nx, ny, celltype=SymmetricTensor2D)

See also: @zeros, @ones, @rand, @falses, @trues, @fill

source

Runtime hardware selection ​

ParallelStencil.@select_hardware Macro
julia
@select_hardware(hardware)

Select the runtime hardware architecture for the caller module. The macro captures the caller and backend at parse time and forwards to select_hardware.

Arguments

  • hardware::Symbol: the symbol representing the hardware architecture to select for runtime execution.

See also: select_hardware, @current_hardware

source
ParallelStencil.@current_hardware Macro
julia
@current_hardware()

Return the symbol representing the runtime hardware architecture selected for the caller module. The macro captures the caller and backend at parse time and forwards to current_hardware.

See also: current_hardware, @select_hardware

source
ParallelStencil.select_hardware Function
julia
select_hardware(caller, hardware; package=get_package(caller))

Set the runtime hardware architecture used by the backend of the caller module. When a backend that supports multiple architectures — such as KernelAbstractions — is active, the function records the chosen hardware symbol so kernel launch and allocation macros can dispatch to the matching device without reparsing code. Single-architecture backends remain fixed to their only target.

Preferred interface

Prefer @select_hardware so the caller module and backend are captured automatically.

Arguments

  • caller::Module: the module from which the hardware selection is made (easily provided using @__MODULE__).

  • hardware::Symbol: the symbol representing the hardware architecture to select for runtime execution. Supported hardware symbols by backend are: - KernelAbstractions: :cpu, :gpu_cuda, :gpu_amd, :gpu_metal, :gpu_oneapi (defaults to :cpu). - Threads: :cpu. - Polyester: :cpu. - CUDA: :gpu_cuda. - AMDGPU: :gpu_amd. - Metal: :gpu_metal.

Keyword arguments

  • package::Symbol: backend context used for validation (default: get_package(caller)).

For workflow guidance refer to the interactive prototyping runtime selection section.

See also: @select_hardware, current_hardware, @current_hardware

source
ParallelStencil.current_hardware Function
julia
current_hardware(caller; package=get_package(caller))

Return the symbol representing the hardware architecture currently selected for runtime execution. For multi-architecture backends, the symbol defaults to :cpu until changed; single-architecture backends report their fixed hardware symbol. Kernel launch and allocation macros inject this state query when constructing hardware-specific calls.

Preferred interface

Prefer @current_hardware so the caller module and backend are captured automatically.

Arguments

  • caller::Module: the module from which the hardware query is made (easily provided using @__MODULE__).

Keyword arguments

  • package::Symbol: backend context used for lookup (default: get_package(caller)).

For workflow guidance refer to the interactive prototyping runtime selection section.

See also: @current_hardware, select_hardware, @select_hardware

source

Hiding communication ​

ParallelStencil.@hide_communication Macro
julia
@hide_communication boundary_width block

Advanced

@hide_communication boundary_width block computation_calls=...
@hide_communication ranges_outer ranges_inner block
@hide_communication ranges_outer ranges_inner block computation_calls=...

Hide the communication behind the computation within the code block.

Arguments

  • boundary_width::Tuple{Integer,Integer,Integer} | Tuple{Integer,Integer} | Tuple{Integer}: width of the boundaries in each dimension. The boundaries must include (at least) all the data that is accessed in the communication performed.

  • block: code block wich starts with one @parallel call to perform computations (for exceptions, see keyword computation_calls), followed by code to set boundary conditions and to perform communication (as e.g. update_halo! from the package ImplicitGlobalGrid). The @parallel call to perform computations can normally not contain any positional arguments (ranges, nblocks or nthreads) nor the stream keyword argument (stream=...) (for exceptions, see keyword computation_calls). The code to set boundary conditions and to perform communication must only access the elements in the boundary ranges of the fields modified in the @parallel call; all elements can be acccessed from other fields. Moreover, this code must not include statements in array broadcasting notation, because they are always run on the default stream in CUDA (for CUDA.jl < v2.0), which makes CUDA stream overlapping impossible. Instead, boundary region elements can, e.g., be accessed with @parallel calls passing a ranges argument that ensures that no threads mapping to elements outside of the boundary regions are launched. Note that these @parallel ranges calls cannot contain any other positional arguments (nblocks or nthreads) nor the stream keyword argument (stream=...).

Advanced

  • ranges_outer::Tuple with one or multiple ranges as required by the corresponding argument of @parallel: the ranges must together span (at least) all the data that is accessed in the communication and boundary conditions performed.

  • ranges_inner::Tuple with one or multiple ranges as required by the corresponding argument of @parallel: the ranges must together span the data that is not included by ranges_outer.

Advanced keyword arguments

  • computation_calls=1::number of @parallel calls at the start of the code block that contain the computation to be hidden behind communication. Only set this argument if you are sure that it is safe to deviate from the standard behavior (computation_calls=1). Note that, in many scenarios (slightly) wrong results will be obtained when computation_calls in greater than 1; it is only safe, generally speaking, if no point in the boundary region computations depends on any inner point computation (finite difference derivatives can, for example, constitute such a dependency leading to wrong results).

Examples

julia
@hide_communication (16, 2, 2) begin
    @parallel diffusion3D_step!(Te2, Te, Ci, lam, dt, dx, dy, dz);
    update_halo!(Te2);
end

@hide_communication (16, 2) begin
    @parallel diffusion2D_step!(Te2, Te, Ci, lam, dt, dx, dy);
    update_halo!(Te2);
end

@hide_communication ranges_outer ranges_inner begin
    @parallel diffusion3D_step!(Te2, Te, Ci, lam, dt, dx, dy, dz);
    update_halo!(Te2);
end

@parallel_indices (iy,iz) function bc_x(A)
    A[  1, iy,  iz] = A[    2,   iy,   iz]
    A[end, iy,  iz] = A[end-1,   iy,   iz]
    return
end
@parallel_indices (ix,iz) function bc_y(A)
    A[ ix,  1,  iz] = A[   ix,    2,   iz]
    A[ ix,end,  iz] = A[   ix,end-1,   iz]
    return
end
@parallel_indices (ix,iy) function bc_z(A)
    A[ ix,  iy,  1] = A[   ix,   iy,    2]
    A[ ix,  iy,end] = A[   ix,   iy,end-1]
    return
end
@hide_communication (16, 2, 2) begin
    @parallel diffusion3D_step!(Te2, Te, Ci, lam, dt, dx, dy, dz);
    @parallel (1:size(Te,2), 1:size(Te,3)) bc_x(Te);
    @parallel (1:size(Te,1), 1:size(Te,3)) bc_y(Te);
    @parallel (1:size(Te,1), 1:size(Te,2)) bc_z(Te);
    update_halo!(Te2);
end

@hide_communication (16, 2, 2) begin
    @parallel (1:size(Te,1), 1:size(Te,2), 1:size(Te,3)) diffusion3D_step!(Te2, Te, Ci, lam, dt, dx, dy, dz);
    @parallel (1:size(Te,2), 1:size(Te,3)) bc_x(Te);
    @parallel (1:size(Te,1), 1:size(Te,3)) bc_y(Te);
    @parallel (1:size(Te,1), 1:size(Te,2)) bc_z(Te);
    update_halo!(Te2);
end

@hide_communication (16, 2, 2) computation_calls=2 begin
    @parallel computation1!(A2, A, B);
    @parallel computation2!(B, C);
    @parallel (1:size(A,2), 1:size(A,3)) bc_x(A);
    @parallel (1:size(A,1), 1:size(A,3)) bc_y(A);
    @parallel (1:size(A,1), 1:size(A,2)) bc_z(A);
    update_halo!(Te2);
end

Developers note

The communication should not perform any blocking operations to enable a maximal overlap of communication with computation.

See also: @parallel

source
ParallelStencil.@overlap Macro
julia
@overlap block

Overlap all @parallel calls in block by executing them asynchronously on separate streams and synchronizing them at the end of the block.

Arguments

  • block: code block containing multiple @parallel calls to be overlapped. Other code in the block, including @parallel_async or @synchronize calls, is not allowed (would lead to unclear semantics); any other code must be placed before or after the @overlap block. The @parallel calls cannot contain the stream keyword argument (stream=...); any other positional and keyword arguments are allowed.

Examples

julia
@overlap begin
    @parallel kernel1!(array1)
    @parallel kernel2!(array2)
    @parallel kernel3!(array3)
end

See also: @parallel, @parallel_async, @synchronize

source
ParallelStencil.@get_stream Macro
julia
@get_stream(id)

Get the default-priority stream with identifier id for the package selected with @init_parallel_stencil. Returns nothing for CPU backends.

If no stream with the given identifier exists yet, then a new stream is created for this identifier. All stream handles are stored package-internally and can be re-retrieved anytime at no cost.

Arguments

  • id::Integer: identifier of the stream (1-based, consecutive integer)

See also: @parallel_async, @synchronize

source
ParallelStencil.@get_priority_stream Macro
julia
@get_priority_stream(id)

Get the priority stream with identifier id for the package selected with @init_parallel_stencil. Returns nothing for CPU backends.

If no stream with the given identifier exists yet, then a new stream is created for this identifier. All stream handles are stored package-internally and can be re-retrieved anytime at no cost.

Arguments

  • id::Integer: identifier of the stream (1-based, consecutive integer)

See also: @parallel_async, @synchronize

source

Kernel language ​

The following macros are available in @parallel_indices kernels.

ParallelStencil.@ps_show Macro
julia
@ps_show(...)

Call a macro analogue to Base.@show, compatible with the package for parallelization selected with @init_parallel_stencil (Base.@show for Threads or Polyester and CUDA.@cushow for CUDA).

source
ParallelStencil.@ps_println Macro
julia
@ps_println(...)

Call a macro analogue to Base.@println, compatible with the package for parallelization selected with @init_parallel_stencil (Base.@println for Threads or Polyester and CUDA.@cuprintln for CUDA).

source
ParallelStencil.@∀ Macro
julia
@∀ x ∈ X statement
@∀ x in X statement
@∀ x = X statement

Expand the statement for all x in X.

Arguments

  • x: the name of the variable the statement is to be expanded with.

  • X: the set of names or range of values x is to be expanded over.

  • statement: the statement to be expanded.

Examples

julia
@∀ i ∈ (x,z) @all(C.i) = @all(A.i) + @all(B.i)                     # Equivalent to: @all(C.x) = @all(A.x) + @all(B.x)
                                                                   #                @all(C.z) = @all(A.z) + @all(B.z)

@∀ i ∈ (y,z) C.i[ix,iy,iz] = A.i[ix,iy,iz] + B.i[ix,iy,iz]         # Equivalent to: C.y[ix,iy,iz] = A.y[ix,iy,iz] + B.y[ix,iy,iz]
                                                                   #                C.z[ix,iy,iz] = A.z[ix,iy,iz] + B.z[ix,iy,iz]

@∀ (ij,i,j) ∈ ((xy,x,y), (xz,x,z), (yz,y,z)) @all(C.ij) = @all(A.i) + @all(B.j)  # Equivalent to: @all(C.xy) = @all(A.x) + @all(B.y)
                                                                                 #                @all(C.xz) = @all(A.x) + @all(B.z)
                                                                                 #                @all(C.yz) = @all(A.y) + @all(B.z)

@∀ i ∈ 1:N @all(C[i]) = @all(A[i]) + @all(B[i])                    # Equivalent to: @all(C[1]) = @all(A[1]) + @all(B[1])
                                                                   #                @all(C[2]) = @all(A[2]) + @all(B[2])
                                                                   #                ...
                                                                   #                @all(C[N]) = @all(A[N]) + @all(B[N])

@∀ i ∈ 1:N C[i][ix,iy,iz] = A[i][ix,iy,iz] + B[i][ix,iy,iz]        # Equivalent to: C[1][ix,iy,iz] = A[1][ix,iy,iz] + B[1][ix,iy,iz]
                                                                   #                C[2][ix,iy,iz] = A[2][ix,iy,iz] + B[2][ix,iy,iz]
                                                                   #                ...
                                                                   #                C[N][ix,iy,iz] = A[N][ix,iy,iz] + B[N][ix,iy,iz]

Performance note

Besides enabling a concise notation for certain sets of equations, the @∀ macro is also designed to replace for loops over a small range of values in compute kernels, leading often to better performance.

Symbol ∀

The symbol ∀ can be obtained, e.g., in the Julia REPL or VSCode, by typing orall and pressing TAB.

source
ParallelStencil.@gridDim Macro
julia
@gridDim()

Return the grid size (or "dimension") in x, y and z dimension. The grid size in a specific dimension is commonly retrieved directly as in this example in x dimension: @gridDim().x.

source
ParallelStencil.@blockIdx Macro
julia
@blockIdx()

Return the block ID in x, y and z dimension within the grid. The block ID in a specific dimension is commonly retrieved directly as in this example in x dimension: @blockIdx().x.

source
ParallelStencil.@blockDim Macro
julia
@blockDim()

Return the block size (or "dimension") in x, y and z dimension. The block size in a specific dimension is commonly retrieved directly as in this example in x dimension: @blockDim().x.

source
ParallelStencil.@threadIdx Macro
julia
@threadIdx()

Return the thread ID in x, y and z dimension within the block. The thread ID in a specific dimension is commonly retrieved directly as in this example in x dimension: @threadIdx().x.

source
ParallelStencil.@sync_threads Macro
julia
@sync_threads()

Synchronize the threads of the block: wait until all threads in the block have reached this point and all global and shared memory accesses made by these threads prior to the sync_threads() call are visible to all threads in the block.

source
ParallelStencil.@sharedMem Macro
julia
@sharedMem(T, dims, offset::Integer=0)

Create an array that is shared between the threads of a block (i.e. accessible only by the threads of a same block), with element type T and size specified by dims. When multiple shared memory arrays are created within a kernel, then all arrays except for the first one typically need to define the offset to the base shared memory pointer in bytes (note that the CPU and AMDGPU implementation do not require the offset and will simply ignore it when present).

Note

The amount of shared memory needs to be specified when launching the kernel (keyword argument shmem).

source

Warp-level primitives ​

ParallelStencil.@warpsize Macro
julia
@warpsize() -> Int

Return the logical warp / wavefront / SIMD-group width in threads for the active backend. CUDA returns 32. AMD GPUs return the hardware wavefront size (typically 64 or 32). Metal returns the device threadExecutionWidth. CPU backend returns 1. Guaranteed constant for the lifetime of the kernel invocation. Use this value (not a hard‑coded constant) for portable intra-warp algorithms.

source
ParallelStencil.@laneid Macro
julia
@laneid() -> Int

Return the 1-based logical lane index in the current warp (range: 1:warpsize()). For CUDA this is CUDA.laneid()+1 internally; for backends with 0-based hardware lane numbering the abstraction adds 1. CPU backend always returns 1.

source
ParallelStencil.@active_mask Macro
julia
@active_mask() -> Unsigned

Return a bit mask of currently active (non-exited, converged) lanes in the caller's warp. Bit (laneid()-1) corresponds to that logical lane. CUDA returns a 32-bit value; AMD returns a 64-bit value. Absent (throws) on Metal if not supported; CPU returns UInt64(0x1).

source
ParallelStencil.@shfl_sync Macro
julia
@shfl_sync(mask::Unsigned, val, lane::Integer)
@shfl_sync(mask::Unsigned, val, lane::Integer, width::Integer)

Return the value of val from the source lane lane (1-based) among lanes named in mask. Optional width (power of two, 1 <= width <= warpsize()) logically partitions the warp into independent contiguous sub-groups each behaving as a mini-warp with lanes numbered 1:width. The source lane index is resolved modulo width. All participating lanes must supply identical mask, lane, and (if present) width. val may be any isbits type; larger composite isbits values are shuffled by decomposition into supported word sizes. CPU backend returns val unchanged.

source
ParallelStencil.@shfl_up_sync Macro
julia
@shfl_up_sync(mask::Unsigned, val, delta::Integer)
@shfl_up_sync(mask::Unsigned, val, delta::Integer, width::Integer)

Shift val up by delta lanes within each logical partition (width semantics as in shfl_sync). Lanes with no valid upstream partner retain their original val. delta >= 0. CPU backend returns val unchanged.

source
ParallelStencil.@shfl_down_sync Macro
julia
@shfl_down_sync(mask::Unsigned, val, delta::Integer)
@shfl_down_sync(mask::Unsigned, val, delta::Integer, width::Integer)

Shift val down by delta lanes within each logical partition; lanes without a valid downstream partner retain their original val. delta >= 0. CPU backend returns val unchanged.

source
ParallelStencil.@shfl_xor_sync Macro
julia
@shfl_xor_sync(mask::Unsigned, val, lane_mask::Integer)
@shfl_xor_sync(mask::Unsigned, val, lane_mask::Integer, width::Integer)

Perform a butterfly (bitwise XOR) shuffle: each lane exchanges with the lane whose (laneid()-1) XOR lane_mask differs in the specified bits, constrained within each width partition if provided. If the computed partner is outside the partition the calling lane's own val is returned. CPU backend returns val unchanged.

source
ParallelStencil.@vote_any_sync Macro
julia
@vote_any_sync(mask::Unsigned, predicate::Bool) -> Bool

Evaluate predicate across all active lanes named in mask; return true if any lane's predicate is true. Does not imply a memory fence. CPU backend returns predicate.

source
ParallelStencil.@vote_all_sync Macro
julia
@vote_all_sync(mask::Unsigned, predicate::Bool) -> Bool

Evaluate predicate across all active lanes named in mask; return true only if every such lane's predicate is true. No memory ordering implied. CPU backend returns predicate.

source
ParallelStencil.@vote_ballot_sync Macro
julia
@vote_ballot_sync(mask::Unsigned, predicate::Bool) -> Unsigned

Return a bit mask aggregating predicate values for lanes named in mask: bit (laneid()-1) set iff that lane's predicate is true. Width of result equals hardware warp mask width (32 for CUDA, 64 for AMD, CPU uses 64 with only bit 0 meaningful). Caller may safely promote to UInt64 for uniform handling; upper bits beyond hardware width are zero. No memory ordering implied.

source

Module Data ​

The module Data is generated in the caller module by @init_parallel_stencil (if a numbertype is given; type ?Data after the call to see its description in the Julia REPL):

Module Data

The module Data is created in the module where @init_parallel_stencil is called from. It provides data types, some of which are organized in submodules.

It contains the following submodules:

Data.Fields

Advanced

Data.Device
Data.Fields.Device

For each datatype in Data and Data.Fields exist a corresponding datatype in Data.Device and Data.Fields.Device, respectively.

Warning

These Device datatypes are not intended for explicit manual usage. @parallel and @parallel_indices convert datatypes from Data and Data.Fields automatically to corresponding datatypes from Data.Device and Data.Fields.Device, respectively, in kernels when required.

:::

The module Data provides the following types at the top level:

Data.Number

The type of numbers used by @zeros, @ones, @rand and @fill and in all array types of module Data (selected with argument numbertype of @init_parallel_stencil).

Data.Index

The type of indices used in parallel kernels.

Data.Array{ndims}

Expands to Data.Array{numbertype, ndims}, where numbertype is the datatype selected with @init_parallel_stencil and the datatype Data.Array is chosen to be compatible with the package for parallelization selected with @init_parallel_stencil (Array for Threads or Polyester, CUDA.CuArray or CUDA.CuDeviceArray for CUDA, AMDGPU.ROCArray or AMDGPU.ROCDeviceArray for AMDGPU and Metal.MtlArray or Metal.MtlDeviceArray for Metal; @parallel and @parallel_indices convert CUDA.CuArray, AMDGPU.ROCArray and Metal.MtlArray automatically to CUDA.CuDeviceArray, AMDGPU.ROCDeviceArray and Metal.MtlDeviceArray in kernels when required).

Data.CellArray{ndims}

Expands to Data.CellArray{numbertype, ndims}, where numbertype is the datatype selected with @init_parallel_stencil and the datatype Data.CellArray is chosen to be compatible with the package for parallelization selected with @init_parallel_stencil (CPUCellArray for Threads or Polyester, CuCellArray or CuDeviceCellArray for CUDA, ROCCellArray or ROCDeviceCellArray for AMDGPU and MtlCellArray or MtlDeviceCellArray for Metal; @parallel and @parallel_indices convert CellArray automatically to DeviceCellArray when required).

Data.Cell{S}

Expands to Union{StaticArrays.SArray{S, numbertype}, StaticArrays.FieldArray{S, numbertype}}, where numbertype is the datatype selected with @init_parallel_stencil.

Data.NumberTuple{N_tuple} | Data.NamedNumberTuple{N_tuple, names} | Data.NumberCollection{N_tuple}

Expands to: NTuple{N_tuple, Data.Number} | NamedTuple{names, NTuple{N_tuple, Data.Number}} | Union{Data.NumberTuple{N_tuple}, Data.NamedNumberTuple{N_tuple}}

Data.IndexTuple{N_tuple} | Data.NamedIndexTuple{N_tuple, names} | Data.IndexCollection{N_tuple}

Expands to: NTuple{N_tuple, Data.Index} | NamedTuple{names, NTuple{N_tuple, Data.Index}} | Union{Data.IndexTuple{N_tuple}, Data.NamedIndexTuple{N_tuple}}

Data.ArrayTuple{N_tuple, N} | Data.NamedArrayTuple{N_tuple, N, names} | Data.ArrayCollection{N_tuple, N}

Expands to: NTuple{N_tuple, Data.Array{N}} | NamedTuple{names, NTuple{N_tuple, Data.Array{N}}} | Union{Data.ArrayTuple{N_tuple, N}, Data.NamedArrayTuple{N_tuple, N}}

Data.CellArrayTuple{N_tuple, N, B} | Data.NamedCellArrayTuple{N_tuple, N, B, names} | Data.CellArrayCollection{N_tuple, N, B}

Expands to: NTuple{N_tuple, Data.CellArray{N, B}} | NamedTuple{names, NTuple{N_tuple, Data.CellArray{N, B}}} | Union{Data.CellArrayTuple{N_tuple, N, B}, Data.NamedCellArrayTuple{N_tuple, N, B}}

Data.CellTuple{N_tuple, S} | Data.NamedCellTuple{N_tuple, S, names} | Data.CellCollection{N_tuple, S}

Expands to: NTuple{N_tuple, Data.Cell{S}} | NamedTuple{names, NTuple{N_tuple, Data.Cell{S}}} | Union{Data.CellTuple{N_tuple, S}, Data.NamedCellTuple{N_tuple, S}}

Submodule Data.Fields

The submodule Data.Fields provides the types for fields allocated with macros from ParallelStencil.FieldAllocators.

Usage

using .Data.Fields # Note the preceeding dot!

Data.Fields provides the following types:

Field

A scalar field, on a grid of size gridsize; allocated with @Fields.

{X|Y|Z}Field

A scalar field of the same size as the {X|Y|Z}-component of a VectorField, on a grid of size gridsize; allocated with @{X|Y|Z}Field.

B{X|Y|Z}Field

A scalar field of the same size as the {X|Y|Z}-component of a BVectorField (a vector field including boundaries), on a grid of size gridsize; allocated with @B{X|Y|Z}Field.

{XX|YY|ZZ|XY|XZ|YZ}Field

A scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize; allocated with @{XX|YY|ZZ|XY|XZ|YZ}Field.

VectorField

A vector field, on a grid of size gridsize; allocated with @VectorField.

BVectorField

A vector field including boundaries, on a grid of size gridsize; allocated with @BVectorField.

TensorField

A tensor field, on a grid of size gridsize; allocated with @TensorField.

Finite differences ​

1-D ​

ParallelStencil.FiniteDifferences1D Module

Module FiniteDifferences1D

Provides macros for 1-D finite differences computations. The dimensions x refers to the 1st and only array dimension. The module was designed to enable a math-close notation and, as a consequence, it does not allow for a nested invocation of the provided macros as, e.g., @d(@d(A)) (instead, one can simply write @d2(A)). Additional macros can be straightforwardly added in the caller module to cover eventual missing functionality. The module is intended for usage with the module ParallelStencil.

Usage

julia
using ParallelStencil.FiniteDifferences1D

Macros

Differences

Selection

Averages

Harmonic averages

Others

To see a description of a macro type ?<macroname> (including the @).

source
ParallelStencil.FiniteDifferences1D.@all Macro

@all(A): Select all elements of A. Corresponds to A[:].

source
ParallelStencil.FiniteDifferences1D.@av Macro

@av(A): Compute averages between adjacent elements of A.

source
ParallelStencil.FiniteDifferences1D.@d Macro

@d(A): Compute differences between adjacent elements of A.

source
ParallelStencil.FiniteDifferences1D.@d2 Macro

@d2(A): Compute the 2nd order differences between adjacent elements of A.

source
ParallelStencil.FiniteDifferences1D.@harm Macro

@harm(A): Compute harmonic averages between adjacent elements of A.

source
ParallelStencil.FiniteDifferences1D.@inn Macro

@inn(A): Select the inner elements of A. Corresponds to A[2:end-1]

source
ParallelStencil.FiniteDifferences1D.@maxloc Macro

@maxloc(A): Compute the maximum between 2nd order adjacent elements of A, using a moving window of size 3.

source
ParallelStencil.FiniteDifferences1D.@minloc Macro

@minloc(A): Compute the minimum between 2nd order adjacent elements of A, using a moving window of size 3.

source
ParallelStencil.FiniteDifferences1D.@within Macro
julia
@within(macroname::String, A)

Return an expression that evaluates to true if the indices generated by @parallel (module ParallelStencil) point to elements in bounds of the selection of A by macroname.

Warning

This macro is not intended for explicit manual usage. Calls to it are automatically added by @parallel where required.

source

2-D ​

ParallelStencil.FiniteDifferences2D Module

Module FiniteDifferences2D

Provides macros for 2-D finite differences computations. The dimensions x and y refer to the 1st and 2nd array dimensions, respectively. The module was designed to enable a math-close notation and, as a consequence, it does not allow for a nested invocation of the provided macros as, e.g., @inn_y(@d_xa(A)) (instead, one can simply write @d_xi(A)). Additional macros can be straightforwardly added in the caller module to cover eventual missing functionality. The module is intended for usage with the module ParallelStencil.

Usage

julia
using ParallelStencil.FiniteDifferences2D

Macros

Differences

Selection

Averages

Harmonic averages

Others

To see a description of a macro type ?<macroname> (including the @).

source
ParallelStencil.FiniteDifferences2D.@all Macro

@all(A): Select all elements of A. Corresponds to A[:,:].

source
ParallelStencil.FiniteDifferences2D.@av Macro

@av(A): Compute averages between adjacent elements of A along the dimensions x and y.

source
ParallelStencil.FiniteDifferences2D.@av_xa Macro

@av_xa(A): Compute averages between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences2D.@av_xi Macro

@av_xi(A): Compute averages between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimension. Corresponds to @inn_y(@av_xa(A)).

source
ParallelStencil.FiniteDifferences2D.@av_ya Macro

@av_ya(A): Compute averages between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences2D.@av_yi Macro

@av_yi(A): Compute averages between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimension. Corresponds to @inn_x(@av_ya(A)).

source
ParallelStencil.FiniteDifferences2D.@d2_xa Macro

@d2_xa(A): Compute the 2nd order differences between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences2D.@d2_xi Macro

@d2_xi(A): Compute the 2nd order differences between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimension. Corresponds to @inn_y(@d2_xa(A)).

source
ParallelStencil.FiniteDifferences2D.@d2_ya Macro

@d2_ya(A): Compute the 2nd order differences between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences2D.@d2_yi Macro

@d2_yi(A): Compute the 2nd order differences between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimension. Corresponds to @inn_x(@d2_ya(A)).

source
ParallelStencil.FiniteDifferences2D.@d_xa Macro

@d_xa(A): Compute differences between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences2D.@d_xi Macro

@d_xi(A): Compute differences between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimension. Corresponds to @inn_y(@d_xa(A)).

source
ParallelStencil.FiniteDifferences2D.@d_ya Macro

@d_ya(A): Compute differences between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences2D.@d_yi Macro

@d_yi(A): Compute differences between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimension. Corresponds to @inn_x(@d_ya(A)).

source
ParallelStencil.FiniteDifferences2D.@harm Macro

@harm(A): Compute harmonic averages between adjacent elements of A along the dimensions x and y.

source
ParallelStencil.FiniteDifferences2D.@harm_xa Macro

@harm_xa(A): Compute harmonic averages between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences2D.@harm_xi Macro

@harm_xi(A): Compute harmonic averages between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimension. Corresponds to @inn_y(@harm_xa(A)).

source
ParallelStencil.FiniteDifferences2D.@harm_ya Macro

@harm_ya(A): Compute harmonic averages between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences2D.@harm_yi Macro

@harm_yi(A): Compute harmonic averages between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimension. Corresponds to @inn_x(@harm_ya(A)).

source
ParallelStencil.FiniteDifferences2D.@inn Macro

@inn(A): Select the inner elements of A. Corresponds to A[2:end-1,2:end-1].

source
ParallelStencil.FiniteDifferences2D.@inn_x Macro

@inn_x(A): Select the inner elements of A in dimension x. Corresponds to A[2:end-1,:].

source
ParallelStencil.FiniteDifferences2D.@inn_y Macro

@inn_y(A): Select the inner elements of A in dimension y. Corresponds to A[:,2:end-1].

source
ParallelStencil.FiniteDifferences2D.@maxloc Macro

@maxloc(A): Compute the maximum between 2nd order adjacent elements of A, using a moving window of size 3.

source
ParallelStencil.FiniteDifferences2D.@minloc Macro

@minloc(A): Compute the minimum between 2nd order adjacent elements of A, using a moving window of size 3.

source
ParallelStencil.FiniteDifferences2D.@within Macro
julia
@within(macroname::String, A)

Return an expression that evaluates to true if the indices generated by @parallel (module ParallelStencil) point to elements in bounds of the selection of A by macroname.

Warning

This macro is not intended for explicit manual usage. Calls to it are automatically added by @parallel where required.

source

3-D ​

ParallelStencil.FiniteDifferences3D Module

Module FiniteDifferences3D

Provides macros for 3-D finite differences computations. The dimensions x, y and z refer to the 1st, 2nd and 3rd array dimensions, respectively. The module was designed to enable a math-close notation and, as a consequence, it does not allow for a nested invocation of the provided macros as, e.g., @inn_z(@inn_y(@d_xa(A))) (instead, one can simply write @d_xi(A)). Additional macros can be straightforwardly added in the caller module to cover eventual missing functionality. The module is intended for usage with the module ParallelStencil.

Usage

julia
using ParallelStencil.FiniteDifferences3D

Macros

Differences

Selection

Averages

Harmonic averages

Others

To see a description of a macro type ?<macroname> (including the @).

source
ParallelStencil.FiniteDifferences3D.@all Macro

@all(A): Select all elements of A. Corresponds to A[:,:,:].

source
ParallelStencil.FiniteDifferences3D.@av Macro

@av(A): Compute averages between adjacent elements of A along the dimensions x and y and z.

source
ParallelStencil.FiniteDifferences3D.@av_xa Macro

@av_xa(A): Compute averages between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences3D.@av_xi Macro

@av_xi(A): Compute averages between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimensions. Corresponds to @inn_yz(@av_xa(A)).

source
ParallelStencil.FiniteDifferences3D.@av_xya Macro

@av_xya(A): Compute averages between adjacent elements of A along the dimensions x and y.

source
ParallelStencil.FiniteDifferences3D.@av_xyi Macro

@av_xyi(A): Compute averages between adjacent elements of A along the dimensions x and y and select the inner elements of A in the remaining dimension. Corresponds to @inn_z(@av_xya(A)).

source
ParallelStencil.FiniteDifferences3D.@av_xza Macro

@av_xza(A): Compute averages between adjacent elements of A along the dimensions x and z.

source
ParallelStencil.FiniteDifferences3D.@av_xzi Macro

@av_xzi(A): Compute averages between adjacent elements of A along the dimensions x and z and select the inner elements of A in the remaining dimension. Corresponds to @inn_y(@av_xza(A)).

source
ParallelStencil.FiniteDifferences3D.@av_ya Macro

@av_ya(A): Compute averages between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences3D.@av_yi Macro

@av_yi(A): Compute averages between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xz(@av_ya(A)).

source
ParallelStencil.FiniteDifferences3D.@av_yza Macro

@av_yza(A): Compute averages between adjacent elements of A along the dimensions y and z.

source
ParallelStencil.FiniteDifferences3D.@av_yzi Macro

@av_yzi(A): Compute averages between adjacent elements of A along the dimensions y and z and select the inner elements of A in the remaining dimension. Corresponds to @inn_x(@av_yza(A)).

source
ParallelStencil.FiniteDifferences3D.@av_za Macro

@av_za(A): Compute averages between adjacent elements of A along the dimension z.

source
ParallelStencil.FiniteDifferences3D.@av_zi Macro

@av_zi(A): Compute averages between adjacent elements of A along the dimension z and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xy(@av_za(A)).

source
ParallelStencil.FiniteDifferences3D.@d2_xi Macro

@d2_xi(A): Compute the 2nd order differences between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimensions. Corresponds to @inn_yz(@d2_xa(A)).

source
ParallelStencil.FiniteDifferences3D.@d2_yi Macro

@d2_yi(A): Compute the 2nd order differences between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xz(@d2_ya(A)).

source
ParallelStencil.FiniteDifferences3D.@d2_zi Macro

@d2_zi(A): Compute the 2nd order differences between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xy(@d2_za(A)).

source
ParallelStencil.FiniteDifferences3D.@d_xa Macro

@d_xa(A): Compute differences between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences3D.@d_xi Macro

@d_xi(A): Compute differences between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimensions. Corresponds to @inn_yz(@d_xa(A)).

source
ParallelStencil.FiniteDifferences3D.@d_ya Macro

@d_ya(A): Compute differences between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences3D.@d_yi Macro

@d_yi(A): Compute differences between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xz(@d_ya(A)).

source
ParallelStencil.FiniteDifferences3D.@d_za Macro

@d_za(A): Compute differences between adjacent elements of A along the dimension z.

source
ParallelStencil.FiniteDifferences3D.@d_zi Macro

@d_zi(A): Compute differences between adjacent elements of A along the dimension z and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xy(@d_za(A)).

source
ParallelStencil.FiniteDifferences3D.@harm Macro

@harm(A): Compute harmonic averages between adjacent elements of A along the dimensions x and y and z.

source
ParallelStencil.FiniteDifferences3D.@harm_xa Macro

@harm_xa(A): Compute harmonic averages between adjacent elements of A along the dimension x.

source
ParallelStencil.FiniteDifferences3D.@harm_xi Macro

@harm_xi(A): Compute harmonic averages between adjacent elements of A along the dimension x and select the inner elements of A in the remaining dimensions. Corresponds to @inn_yz(@harm_xa(A)).

source
ParallelStencil.FiniteDifferences3D.@harm_xya Macro

@harm_xya(A): Compute harmonic averages between adjacent elements of A along the dimensions x and y.

source
ParallelStencil.FiniteDifferences3D.@harm_xyi Macro

@harm_xyi(A): Compute harmonic averages between adjacent elements of A along the dimensions x and y and select the inner elements of A in the remaining dimension. Corresponds to @inn_z(@harm_xya(A)).

source
ParallelStencil.FiniteDifferences3D.@harm_xza Macro

@harm_xza(A): Compute harmonic averages between adjacent elements of A along the dimensions x and z.

source
ParallelStencil.FiniteDifferences3D.@harm_xzi Macro

@harm_xzi(A): Compute harmonic averages between adjacent elements of A along the dimensions x and z and select the inner elements of A in the remaining dimension. Corresponds to @inn_y(@harm_xza(A)).

source
ParallelStencil.FiniteDifferences3D.@harm_ya Macro

@harm_ya(A): Compute harmonic averages between adjacent elements of A along the dimension y.

source
ParallelStencil.FiniteDifferences3D.@harm_yi Macro

@harm_yi(A): Compute harmonic averages between adjacent elements of A along the dimension y and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xz(@harm_ya(A)).

source
ParallelStencil.FiniteDifferences3D.@harm_yza Macro

@harm_yza(A): Compute harmonic averages between adjacent elements of A along the dimensions y and z.

source
ParallelStencil.FiniteDifferences3D.@harm_yzi Macro

@harm_yzi(A): Compute harmonic averages between adjacent elements of A along the dimensions y and z and select the inner elements of A in the remaining dimension. Corresponds to @inn_x(@harm_yza(A)).

source
ParallelStencil.FiniteDifferences3D.@harm_za Macro

@harm_za(A): Compute harmonic averages between adjacent elements of A along the dimension z.

source
ParallelStencil.FiniteDifferences3D.@harm_zi Macro

@harm_zi(A): Compute harmonic averages between adjacent elements of A along the dimension z and select the inner elements of A in the remaining dimensions. Corresponds to @inn_xy(@harm_za(A)).

source
ParallelStencil.FiniteDifferences3D.@inn Macro

@inn(A): Select the inner elements of A. Corresponds to A[2:end-1,2:end-1,2:end-1].

source
ParallelStencil.FiniteDifferences3D.@inn_x Macro

@inn_x(A): Select the inner elements of A in dimension x. Corresponds to A[2:end-1,:,:].

source
ParallelStencil.FiniteDifferences3D.@inn_xy Macro

@inn_xy(A): Select the inner elements of A in dimensions x and y. Corresponds to A[2:end-1,2:end-1,:].

source
ParallelStencil.FiniteDifferences3D.@inn_xz Macro

@inn_xz(A): Select the inner elements of A in dimensions x and z. Corresponds to A[2:end-1,:,2:end-1].

source
ParallelStencil.FiniteDifferences3D.@inn_y Macro

@inn_y(A): Select the inner elements of A in dimension y. Corresponds to A[:,2:end-1,:].

source
ParallelStencil.FiniteDifferences3D.@inn_yz Macro

@inn_yz(A): Select the inner elements of A in dimensions y and z. Corresponds to A[:,2:end-1,2:end-1].

source
ParallelStencil.FiniteDifferences3D.@inn_z Macro

@inn_z(A): Select the inner elements of A in dimension z. Corresponds to A[:,:,2:end-1].

source
ParallelStencil.FiniteDifferences3D.@maxloc Macro

@maxloc(A): Compute the maximum between 2nd order adjacent elements of A, using a moving window of size 3.

source
ParallelStencil.FiniteDifferences3D.@minloc Macro

@minloc(A): Compute the minimum between 2nd order adjacent elements of A, using a moving window of size 3.

source
ParallelStencil.FiniteDifferences3D.@within Macro
julia
@within(macroname::String, A)

Return an expression that evaluates to true if the indices generated by @parallel (module ParallelStencil) point to elements in bounds of the selection of A by macroname.

Warning

This macro is not intended for explicit manual usage. Calls to it are automatically added by @parallel where required.

source

Field allocators ​

ParallelStencil.FieldAllocators Module

Module FieldAllocators

Provides macros for the allocation of different kind of fields on a grid of size gridsize.

Usage

julia
using ParallelStencil.FieldAllocators

Macros

Multiple fields at once

Scalar fields

Vector fields

Tensor fields

To see a description of a macro type ?<macroname> (including the @).

source
ParallelStencil.FieldAllocators.@BVectorField Macro
julia
@BVectorField(gridsize)
@BVectorField(gridsize, allocator)
@BVectorField(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a BVectorField, a vector field including boundaries, on a grid of sizegridsize`.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field arrays (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@BXField Macro
julia
@B{X|Y|Z}Field(gridsize)
@B{X|Y|Z}Field(gridsize, allocator)
@B{X|Y|Z}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a B{X|Y|Z}Field, a scalar field of the same size as the {X|Y|Z}-component of a BVectorField (a vector field including boundaries), on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@BYField Macro
julia
@B{X|Y|Z}Field(gridsize)
@B{X|Y|Z}Field(gridsize, allocator)
@B{X|Y|Z}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a B{X|Y|Z}Field, a scalar field of the same size as the {X|Y|Z}-component of a BVectorField (a vector field including boundaries), on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@BZField Macro
julia
@B{X|Y|Z}Field(gridsize)
@B{X|Y|Z}Field(gridsize, allocator)
@B{X|Y|Z}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a B{X|Y|Z}Field, a scalar field of the same size as the {X|Y|Z}-component of a BVectorField (a vector field including boundaries), on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@Field Macro
julia
@Field(gridsize)
@Field(gridsize, allocator)
@Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a scalar Field on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@TensorField Macro
julia
@TensorField(gridsize)
@TensorField(gridsize, allocator)
@TensorField(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a TensorField on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field arrays (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@VectorField Macro
julia
@VectorField(gridsize)
@VectorField(gridsize, allocator)
@VectorField(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a VectorField on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field arrays (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@XField Macro
julia
@{X|Y|Z}Field(gridsize)
@{X|Y|Z}Field(gridsize, allocator)
@{X|Y|Z}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {X|Y|Z}Field, a scalar field of the same size as the {X|Y|Z}-component of a VectorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@XXField Macro
julia
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {XX|YY|ZZ|XY|XZ|YZ}Field, a scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@XYField Macro
julia
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {XX|YY|ZZ|XY|XZ|YZ}Field, a scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@XZField Macro
julia
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {XX|YY|ZZ|XY|XZ|YZ}Field, a scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@YField Macro
julia
@{X|Y|Z}Field(gridsize)
@{X|Y|Z}Field(gridsize, allocator)
@{X|Y|Z}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {X|Y|Z}Field, a scalar field of the same size as the {X|Y|Z}-component of a VectorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@YYField Macro
julia
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {XX|YY|ZZ|XY|XZ|YZ}Field, a scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@YZField Macro
julia
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {XX|YY|ZZ|XY|XZ|YZ}Field, a scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@ZField Macro
julia
@{X|Y|Z}Field(gridsize)
@{X|Y|Z}Field(gridsize, allocator)
@{X|Y|Z}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {X|Y|Z}Field, a scalar field of the same size as the {X|Y|Z}-component of a VectorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@ZZField Macro
julia
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator)
@{XX|YY|ZZ|XY|XZ|YZ}Field(gridsize, allocator, <keyword arguments>)

Using the allocator, allocate a {XX|YY|ZZ|XY|XZ|YZ}Field, a scalar field of the same size as the {XX|YY|ZZ|XY|XZ|YZ}-component of a TensorField, on a grid of size gridsize.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Arguments

  • gridsize::Tuple: the size of the grid.

Optional argument

  • allocator::Macro=@zeros: the macro to use for the allocation of the field array (@zeros,@ones,@rand,@falsesor@trues`).

Keyword arguments

  • eltype::DataType: the type of the elements (numbers or indices).

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source
ParallelStencil.FieldAllocators.@allocate Macro
julia
@allocate(<keyword arguments>)

Allocate different kinds of fields on a grid of size gridsize at once (and initialize them with zeros). Besides convenience and conciseness, this macro ensures that all fields are allocated using the same gridsize and is therefore recommended for the allocation of multiple fields.

Advanced

The eltype can be explicitly passed as keyword argument in order to be used instead of the default numbertype chosen with @init_parallel_stencil. If no default numbertype was chosen @init_parallel_stencil, then the keyword argument eltype is mandatory. This needs to be used with care to ensure that no datatype conversions occur in performance critical computations.

Mandatory keyword arguments

  • gridsize::Tuple: the size of the grid.

  • fields::Pair|NTuple{Pair}: a tuple of pairs (or a single pair) of a field type and a field name or a tuple of field names.

Keyword arguments

  • allocator::Macro=@zeros: the macro to use for the allocation of the field arrays (@zeros,@ones,@rand,@falsesor@trues`). !!! note "Advanced"
    • eltype::DataType: the type of the elements (numbers or indices).

Examples

julia
@allocate(gridsize = (nx,ny,nz), 
          fields   = (Field        => (Pt, dτPt, ∇V, Radc, Rog, Mus),
                      VectorField  => (R, dVdτ, dτV),
                      TensorField  => τ,
                      BVectorField => V
          )
)

See also: @allocate, @Field, @XField, @BXField, @XXField, @VectorField, @BVectorField, @TensorField

source

Automatic differentiation ​

ParallelStencil.AD Module

Module AD

Provides GPU-compatible wrappers for automatic differentiation functions of the Enzyme.jl package. Consult the Enzyme documentation to learn how to use the wrapped functions.

Usage

julia
import ParallelStencil.AD

Functions

  • autodiff_deferred!: wraps function Enzyme.autodiff_deferred, and supports the same arguments, with the exception of the return type activity (3rd argument) which must be omitted and will be automatically inserted (inserting it explicitly will raise a GPU compiler error when targeting a GPU). Additionally, it promotes all arguments that are not Enzyme.Annotation to Enzyme.Const. As a result, the function can be conveniently called as, e.g., autodiff_deferred!(Enzyme.Reverse, f!,...), instead of the fully explicit form, e.g., autodiff_deferred!(Enzyme.Reverse, Enzyme.Const(f!), Enzyme.Const,...) (which is not supported).

  • autodiff_deferred_thunk!: wraps function Enzyme.autodiff_deferred_thunk, in the same way as autodiff_deferred! wraps Enzyme.autodiff_deferred (see above).

Examples

julia
const USE_GPU = true
using ParallelStencil
import ParallelStencil.AD
using Enzyme
@static if USE_GPU
    @init_parallel_stencil(CUDA, Float64, 3);
else
    @init_parallel_stencil(Threads, Float64, 3);
end

@parallel_indices (ix) function f!(A, B, a)
    A[ix] += a * B[ix] * 100.65
    return
end

function main()
    N = 16
    a = 6.5
    A = @rand(N)
    B = @rand(N)
    Ā = @ones(size(A))
    B̄ = @ones(size(B))

    @info "running on CPU/GPU"
    @parallel f!(A, B, a) # normal call of f!
    @parallel configcall=f!(A, B, a) AD.autodiff_deferred!(Enzyme.Reverse, f!, Duplicated(A, Ā), DuplicatedNoNeed(B, B̄), a) # automatic differentiation of f!
    
    return
end

main()

To see a description of a function type ?<functionname>.

source