Potential variants

Grid functions potential variants

syntax

• potentialIpps64(grid_data_item, kernel)
• potentialRaw64(grid_data_item, kernel)
• potentialSlow(grid_data_item, kernel)
• potentialPacked(grid_data_item, kernel)
• potentialRawPacked(grid_data_item, kernel)

definition

The potential function is available in a set of explicitly named variants. All variants have the same two arguments (a grid_data_item and a kernel) and calculate the same convolution sum; they differ in the algorithm used, the precision of the intermediate buffers and whether a smoothing step is applied to the result.

The plain potential function is a synonym for the fastest full-precision variant, currently potentialIpps64.

variants

function	algorithm	intermediate precision	smoothing	applies to
potential	FFT (same as potentialIpps64)	float64	yes	float32, float64
potentialIpps64	FFT	float64	yes	float32, float64
potentialRaw64	FFT	float64	no	float32, float64
potentialSlow	direct (four nested loops)	value type of arguments	no	float32, float64
potentialPacked	FFT	float32	yes	float32
potentialRawPacked	FFT	float32	no	float32

• potentialIpps64: the default implementation. The convolution is calculated with a Fast Fourier Transformation (FFT); kernel and intermediate buffers are kept in float64, also for float32 arguments, to give a more precise result. A smoothing step is applied afterwards.
• potentialRaw64: same as potentialIpps64, but without the smoothing step.
• potentialSlow: the classic reference implementation with four nested loops, without FFT. It calculates the sums directly in the value type of the arguments. As no FFT is used, no oscillation artifacts occur and no smoothing is applied. It requires O(n*m*k*j) operations for an n*m grid and a k*j kernel and is therefore much slower for large kernels; it is primarily meant for verifying and benchmarking the FFT-based variants.
• potentialPacked: an FFT-based implementation that keeps the kernel and intermediate buffers in float32 instead of float64, reducing memory usage at the cost of precision. Only available for float32 arguments and primarily meant for experimental and benchmarking purposes.
• potentialRawPacked: same as potentialPacked, but without the smoothing step.

description

smoothing: an FFT can result in small oscillations: values very close to zero, sometimes even slightly negative, in regions where the exact result is zero. The smoothing step resets to zero each result value whose absolute value is less than the square root of the sum of the squared result values, divided by 10^9. The raw variants (potentialRaw64 and potentialRawPacked) skip this step and return the FFT output as is.

naming: the Ipps part of the names refers to the Intel Performance Primitives signal processing library that was originally used for the FFT-based implementation. The current implementation uses the FFTW3 library; the operator names have been kept.

which variant to use: for regular use, apply potential. Use potentialRaw64 if near-zero result values are meaningful and must not be reset to zero by the smoothing step. Use potentialSlow to verify results of the FFT-based variants on small grids. The packed variants are primarily meant for testing and benchmarking.

applies to

• attribute grid_data_item with float32 or float64 value type (potentialPacked and potentialRawPacked: float32 only)

conditions

The domain unit of grid_data_item must be a Point value type of the group CanBeDomainUnit.

example

attribute<float32> potgrid_raw (GridDomain) := potentialRaw64(float32(sourcegrid), pot3Range/RelWeight);

see also

• potential
• potential with kernel
• proximity
• convolution