johannesbuchner / nfftpy Goto Github PK

NFFTPY - Cython wrapper for NFFT library
========================================

"NFFT is a C subroutine library for computing the nonequispaced discrete
Fourier transform (NDFT) and its generalisations in one or more dimensions, of
arbitrary input size, and of complex data."

NFFTPY wraps NFFT using Cython, to make it usable from Python.

NFFTPY License:

    Open-source, BSD-like.


Prerequisites:

    * FFTW library: http://www.fftw.org/
    On a Linux 64-bit system, before installing FFTW, set compile flags:
        $ export CFLAGS=-fPIC
    Otherwise NFFT may not be able to link correctly.

    * NFFT library: http://www-user.tu-chemnitz.de/~potts/nfft/

    * distribute-0.6.14-3 (bug-fix for hassle-free installation.)
      If you have EPD, you can update distribute by typing at any shell prompt:
         $ enpkg distribute

Notes:

    * NFFTPY is an early-stage work in progress. Contributions are welcome.
    So far, has only been tested on Linux 32- and 64-bit systems.

    * NFFTPY's python interface represents samples and Fourier coefficients as
    complex numpy arrays. By default, FFTW (and so also NFFT) represent these
    numbers internally as "double fftw_complex[2]".

    FFTW can optionally be compiled to use C99 complex data types internally:
        http://www.fftw.org/fftw3_doc/Complex-numbers.html
    However, NFFTPY does not yet support this FFTW configuration.


Cython wrapper files:

    * cnfft3.pxd - Cython interface file for nfft3.h (main NFFT header).
    Currently contains only the functions from the first half of nfft3.h,
    and only exposes the nfft_plan members which are used by the simple_test
    example. As other functions and members are needed, they can easily
    be added following the pattern of those already exposed.

    * cnfftutil.pxd - Cython interface file for nfft3util.h (NFFT utility
    functions). Currently contains only those functions used in simple_test.pxd.

    * nfftpy.pyx - Class wrapper for NFFT. Defines class NfftPlanWrapper,
    which is at the heart of the wrapping.

    * nfftpy.pxd - Cython interface for nfftpy.pyx. Needed when a Cython
    module wants to cimport from nfftpy.


Example and test files:

    * simple_test.pyx - Cython module which does not use the wrapper class. It
    is a trivial cython translation of the NFFT example
    nfft-3.1.3/examples/nfft/simple_test.c, using only the interface files
    cnfft3.pxd and cnfftutil.pxd. Produces the same output as simple_test.c

    * simple_test_class.pyx - Cython module which uses the wrapper class. As
    such, it is intermediate between simple_test.pyx and test_nfftpy.py. Uses
    the wrapper class to perform the same transformations on the same data as
    simple_test.pyx. Also saves vectors to files for use in test_nfftpy.py.

    * tests/test_nfftpy.py - Python module which (of necessity) uses the
    wrapper class. As such, it is the example for how to use NFFTPY from
    Python. It also serves as the unit test module (using nosetests) for the
    wrapper.

    * tests/simple_test_nfft_*.txt - test data files written by
    simple_test_class.pyx and read by test_nfftpy.py.


Build files:

    * makefile - Build and test NFFTPY.

        make clean - delete files generated by previous builds

        make (or make all)- build all Cython extensions (nfftpy.so,
        simple_test.so, and simple_test_class.so) using setup.py

        make test - run nosetests (for test_nfftpy.py)

        make test_simple - run simple_test.so

        make test_simple_class - run simple_test_class.so

    * setup.py - Build cython extensions. See docstrings, and makefile usage.


To do:

    * Add unit tests of non-random data sampled from simple functions with
    known transforms.

    * In cnfft3.pxd (cython interface), expose additional members of struct
    nfft_plan as needed. In nfftpy.pyx, provide accessor properties for them.

    * In cnfftutil.pxd, expose additional utility functions as needed.

    * Consider allowing write-access to NfftPlanWrapper attributes which
    define array and data sizes and dimensions. (Now these are only set
    by the instantiating class methods.)

    * Consider giving the NfftPlanWrapper attributes more informative names
    (now they have the same names as in the original struct nfft_plan).

    * In nfftpy.pyx, allow numpy and C arrays to share the same memory to
    avoid copy overhead. (Especially relevant for large 3D data).

    * Support FFTW configuration when fftw_complex is c99 complex.