PCFFT API
===================

Specifying kernels and points
------------------------------

This package expects points to specified using a struct with field ``r`` containing the coordinates of the points. If there are :math:`N` points in :math:`\mathbb{R}^d` for `d=2,3`, the ``r`` field should be an array with shape ``[d, N]``. It should also contain any other point information, such as a normal vector ``n`` with shape ``[d, N]``, or a curvature ``kappa`` with shape ``[1,N]``. For example, in 3 dimensions the source and target points might be generated by

.. code:: matlab

   N = 1000; % number of sources
   M = 3000; % number of targets
   src_info = struct();
   targ_info = struct();
   src_info.r = rand(3, N);
   src_info.kappa = rand(1, N);
   targ_info.r = rand(3, M);
   targ_info.n = rand(3, M);

Now, suppose we have a kernel function

.. math:: 

   k : \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{R}^{o_1 \times o_2}

The PCFFT package requires the kernel to be specified as a function handle or as an object with an ``eval`` method. We assume a few things about the kernel function (or its ``eval`` method):

 * The first argument is the source point structure, and the second argument is the target point structure. The kernel function should not require other arguments.
 * If there are :math:`N` source points and :math:`M` target points, the kernel function should return an array of shape ``[opdim(1)*M, opdim(2)*N]`` containing the kernel evaluations between each target and source point. If the kernel is vector-valued, then the result should be interleaved, i.e. ``vals(1:opdim(1),1:opdim(2))```` should be the interaction between the first source and the first target.

Here is an example of a kernel function which matches these requirements:

.. code:: matlab

   function evals = kern(src_info, targ_info)
       % evaluate the gradient of the electrostatic kernel between N source points src_info.r and 
       % M target points targ_info.r, weighted by src_info.kappa
       %
       % Output shape is (3M, N)

       % Shape (M, N)
       rx = src_info.r(1, :) - targ_info.r(1, :).';
       ry = src_info.r(2, :) - targ_info.r(2, :).';
       rz = src_info.r(3, :) - targ_info.r(3, :).';

       dist = sqrt(rx.^2 + ry.^2 + rz.^2);
       gradx = rx ./ dist.^2; gradx = reshape(gradx,1,[]); 
       grady = ry ./ dist.^2; grady = reshape(grady,1,[]);
       gradz = rz ./ dist.^2; gradz = reshape(gradz,1,[]);

       % Shape (3M, N)
       evals = reshape([gradx;grady;gradz], 3*size(targ_info.r(:,:),2), size(src_info.r(:,:),2));
       evals = evals .* src_info.kappa(:,:) / (4*pi);
    end

In the following documentation, we will use the types ``point_info`` and  ``kernel`` to refer to structures containing point information and kernel function handles, respectively.

Function API
-------------
.. mat:currentmodule:: pcfft
.. mat:autofunction:: get_grid
.. mat:autofunction:: get_spread
.. mat:autofunction:: get_addsub
.. mat:autofunction:: get_kernhat
.. mat:autofunction:: pcfft_apply


Built-in classes
-------------------
.. autoclass:: pcfft.classes.GridInfo
   :members:

.. autoclass:: pcfft.classes.ProxyInfo
   :members:

.. autoclass:: pcfft.classes.SortInfo
   :members: