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
Prepare the plan for execution.
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