3.2. Plan

class gpyfft.Plan

A plan is the collection of (almost) all parameters needed to specify an FFT computation. This includes:

  • What pyopencl context executes the transform?

  • Is this a 1D, 2D or 3D transform?

  • What are the lengths or extents of the data in each dimension?

  • How many datasets are being transformed?

  • What is the data precision?

  • Should a scaling factor be applied to the transformed data?

  • Does the output transformed data replace the original input data in the same buffer (or buffers), or is the output data written to a different buffer (or buffers).

  • How is the input data stored in its data buffers?

  • How is the output data stored in its data buffers?

The plan does not include:

  • The pyopencl handles to the input and output data buffers.

  • The pyopencl handle to a temporary scratch buffer (if needed).

  • Whether to execute a forward or reverse transform.

These are specified later, when the plan is executed.

Attributes:
batch_size

the number of discrete arrays that this plan can handle concurrently

distances

the distance between array objects

inplace

determines if the input buffers are going to be overwritten with

layouts

the expected layout of the output buffers

precision

the floating point precision of the FFT data

scale_backward

the scaling factor to be applied to the FFT data for backward transforms

scale_forward

the scaling factor to be applied to the FFT data for forward transforms

shape

the length of each dimension of the FFT

strides_in

the distance between consecutive elements for input buffers

strides_out

the distance between consecutive elements for output buffers

temp_array_size

Buffer size (in bytes), which may be needed internally for an intermediate buffer.

transpose_result

the final transpose setting of a multi-dimensional FFT

Methods

bake

Prepare the plan for execution.

enqueue_transform

Enqueue an FFT transform operation, and return immediately.

__init__()

Instantiates a Plan object

Plan objects are created internally by gpyfft; normally a user does not create these objects

Parameters:
contexpyopencl.Context

http://documen.tician.de/pyopencl/runtime.html#pyopencl.Context

shapetuple

the dimensionality of the transform

libno idea

this is a thing that does lib things

Raises:
ValueError

when the shape isn’t a tuple of length 1, 2 or 3

TypeError

because the context argument isn’t a valid pyopencl.Context

Notes

The underlying clFFT call is ‘clfftCreateDefaultPlan’

bake()

Prepare the plan for execution.

Prepares and compiles OpenCL kernels internally used to perform the transform. At this point, the clfft runtime applies all implemented optimizations, possibly including running kernel experiments on the devices in the plan context. This can take a long time to execute. If not called, this is performed when the plan is execute for the first time.

Parameters:
queuespyopencl.CommandQueue or list of pyopencl.CommandQueue
Returns:
None
Raises:
GpyFFT_Error

An error occurred accessing the clfftBakePlan function

Notes

The underlying clFFT call is ‘clfftBakePlan’

batch_size

the number of discrete arrays that this plan can handle concurrently

distances

the distance between array objects

enqueue_transform()

Enqueue an FFT transform operation, and return immediately.

Parameters:
queuespyopencl.CommandQueue or iterable of pyopencl.CommandQueue
in_bufferspyopencl.Buffer or iterable (1 or 2 items) of pyopencl.Buffer
out_bufferspyopencl.Buffer or iterable (1 or 2 items) of pyopencl.Buffer, optional

can be None for inplace transforms

Returns:
tuple of pyopencl.Event, one event for each command queue in queues
Other Parameters:
direction_forwardbool, optional

Perform forward transform (default True).

wait_for_eventsiterable of pyopencl.Event, optional

Ensures that all events in this list have finished execution before transform is performed.

temp_bufferpyopencl.Buffer, optional

For intermediate results a temporary buffer can be provided. The size (in bytes) of this buffer is given by the temp_array_size property.

Raises:
GpyFFT_Error

An error occurred accessing the clfftEnqueueTransform function

Notes

The underlying clFFT call is ‘clfftEnqueueTransform’

inplace

determines if the input buffers are going to be overwritten with results (True == inplace, False == out of place)

layouts

the expected layout of the output buffers

precision

the floating point precision of the FFT data

scale_backward

the scaling factor to be applied to the FFT data for backward transforms

scale_forward

the scaling factor to be applied to the FFT data for forward transforms

shape

the length of each dimension of the FFT

strides_in

the distance between consecutive elements for input buffers in a dimension

strides_out

the distance between consecutive elements for output buffers in a dimension

temp_array_size

Buffer size (in bytes), which may be needed internally for an intermediate buffer. Requires that transform plan is baked before.

transpose_result

the final transpose setting of a multi-dimensional FFT

True: transpose the final result (default) False: skip final transpose