# 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`(queues) | Prepare the plan for execution.
  `enqueue_transform`(queues, in_buffers[, ...]) | 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:
      contex pyopencl.Context

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

      shape tuple

        the dimensionality of the transform

      lib no 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(queues)

    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:
      queues pyopencl.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(queues, in_buffers, out_buffers=None, direction_forward=True, wait_for_events=None, temp_buffer=None)

    Enqueue an FFT transform operation, and return immediately.

    Parameters:
      queues pyopencl.CommandQueue or iterable of pyopencl.CommandQueue
      in_buffers pyopencl.Buffer or iterable (1 or 2 items) of pyopencl.Buffer
      out_buffers pyopencl.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_forward bool, optional

        Perform forward transform (default True).

      wait_for_events iterable of pyopencl.Event, optional

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

      temp_buffer pyopencl.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