# 2.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

  Methods

  `__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`()

    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`()

    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