-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A binding to the fftw library for one-dimensional vectors.
--   
--   This package provides bindings to the fftw library for one-dimensional
--   vectors. It provides both high-level functions and more low-level
--   manipulation of fftw plans.
--   
--   We provide three different modules which wrap fftw's operations:
--   
--   <ul>
--   <li><a>Numeric.FFT.Vector.Unnormalized</a> contains the raw
--   transforms;</li>
--   <li><a>Numeric.FFT.Vector.Invertible</a> scales the backwards
--   transforms to be true inverses;</li>
--   <li><a>Numeric.FFT.Vector.Unitary</a> additionally scales all
--   transforms to preserve the L2 (sum-of-squares) norm of the input.</li>
--   </ul>
@package vector-fftw
@version 0.1.3.8

module Numeric.FFT.Vector.Plan

-- | A transform which may be applied to vectors of different sizes.
data Transform a b

-- | Create a <a>Plan</a> of a specific size for this transform.
planOfType :: (Storable a, Storable b) => PlanType -> Transform a b -> Int -> Plan a b
data PlanType
Estimate :: PlanType
Measure :: PlanType
Patient :: PlanType
Exhaustive :: PlanType

-- | Create a <a>Plan</a> of a specific size. This function is equivalent
--   to <tt><a>planOfType</a> <a>Estimate</a></tt>.
plan :: (Storable a, Storable b) => Transform a b -> Int -> Plan a b

-- | Create and run a <a>Plan</a> for the given transform.
run :: (Vector v a, Vector v b, Storable a, Storable b) => Transform a b -> v a -> v b

-- | A <a>Plan</a> can be used to run an <tt>fftw</tt> algorithm for a
--   specific input/output size.
data Plan a b

-- | The (only) valid input size for this plan.
planInputSize :: Storable a => Plan a b -> Int

-- | The (only) valid output size for this plan.
planOutputSize :: Storable b => Plan a b -> Int

-- | Run a plan on the given <a>Vector</a>.
--   
--   If <tt><a>planInputSize</a> p /= length v</tt>, then calling
--   <tt>execute p v</tt> will throw an exception.
execute :: (Vector v a, Vector v b, Storable a, Storable b) => Plan a b -> v a -> v b

-- | Run a plan on the given mutable vectors. The same vector may be used
--   for both input and output.
--   
--   If <tt><a>planInputSize</a> p /= length vIn</tt> or
--   <tt><a>planOutputSize</a> p /= length vOut</tt>, then calling
--   <tt>unsafeExecuteM p vIn vOut</tt> will throw an exception.
executeM :: forall m v a b. (PrimBase m, MVector v a, MVector v b, Storable a, Storable b) => Plan a b -> v (PrimState m) a -> v (PrimState m) b -> m ()


-- | Raw, unnormalized versions of the transforms in <tt>fftw</tt>.
--   
--   Note that the forwards and backwards transforms of this module are not
--   actually inverses. For example, <tt>run idft (run dft v) /= v</tt> in
--   general.
--   
--   For more information on the individual transforms, see
--   <a>http://www.fftw.org/fftw3_doc/What-FFTW-Really-Computes.html</a>.
module Numeric.FFT.Vector.Unnormalized

-- | Create and run a <a>Plan</a> for the given transform.
run :: (Vector v a, Vector v b, Storable a, Storable b) => Transform a b -> v a -> v b

-- | Create a <a>Plan</a> of a specific size. This function is equivalent
--   to <tt><a>planOfType</a> <a>Estimate</a></tt>.
plan :: (Storable a, Storable b) => Transform a b -> Int -> Plan a b

-- | Run a plan on the given <a>Vector</a>.
--   
--   If <tt><a>planInputSize</a> p /= length v</tt>, then calling
--   <tt>execute p v</tt> will throw an exception.
execute :: (Vector v a, Vector v b, Storable a, Storable b) => Plan a b -> v a -> v b

-- | A forward discrete Fourier transform. The output and input sizes are
--   the same (<tt>n</tt>).
--   
--   <pre>
--   y_k = sum_(j=0)^(n-1) x_j e^(-2pi i j k/n)
--   </pre>
dft :: Transform (Complex Double) (Complex Double)

-- | A backward discrete Fourier transform. The output and input sizes are
--   the same (<tt>n</tt>).
--   
--   <pre>
--   y_k = sum_(j=0)^(n-1) x_j e^(2pi i j k/n)
--   </pre>
idft :: Transform (Complex Double) (Complex Double)

-- | A forward discrete Fourier transform with real data. If the input size
--   is <tt>n</tt>, the output size will be <tt>n `div` 2 + 1</tt>.
dftR2C :: Transform Double (Complex Double)

-- | A backward discrete Fourier transform which produces real data.
--   
--   This <a>Transform</a> behaves differently than the others:
--   
--   <ul>
--   <li>Calling <tt>plan dftC2R n</tt> creates a <a>Plan</a> whose
--   <i>output</i> size is <tt>n</tt>, and whose <i>input</i> size is <tt>n
--   `div` 2 + 1</tt>.</li>
--   <li>If <tt>length v == n</tt>, then <tt>length (run dftC2R v) ==
--   2*(n-1)</tt>.</li>
--   </ul>
dftC2R :: Transform (Complex Double) Double

-- | A type-1 discrete cosine transform.
--   
--   <pre>
--   y_k = x_0 + (-1)^k x_(n-1) + 2 sum_(j=1)^(n-2) x_j cos(pi j k/(n-1))
--   </pre>
dct1 :: Transform Double Double

-- | A type-2 discrete cosine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j cos(pi(j+1/2)k/n)
--   </pre>
dct2 :: Transform Double Double

-- | A type-3 discrete cosine transform.
--   
--   <pre>
--   y_k = x_0 + 2 sum_(j=1)^(n-1) x_j cos(pi j(k+1/2)/n)
--   </pre>
dct3 :: Transform Double Double

-- | A type-4 discrete cosine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j cos(pi(j+1/2)(k+1/2)/n)
--   </pre>
dct4 :: Transform Double Double

-- | A type-1 discrete sine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j sin(pi(j+1)(k+1)/(n+1))
--   </pre>
dst1 :: Transform Double Double

-- | A type-2 discrete sine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j sin(pi(j+1/2)(k+1)/n)
--   </pre>
dst2 :: Transform Double Double

-- | A type-3 discrete sine transform.
--   
--   <pre>
--   y_k = (-1)^k x_(n-1) + 2 sum_(j=0)^(n-2) x_j sin(pi(j+1)(k+1/2)/n)
--   </pre>
dst3 :: Transform Double Double

-- | A type-4 discrete sine transform.
--   
--   <pre>
--   y_k = sum_(j=0)^(n-1) x_j sin(pi(j+1/2)(k+1/2)/n)
--   </pre>
dst4 :: Transform Double Double


-- | This module provides normalized versions of the transforms in
--   <tt>fftw</tt>.
--   
--   The forwards transforms in this module are identical to those in
--   <a>Numeric.FFT.Vector.Unnormalized</a>. The backwards transforms are
--   normalized to be their inverse operations (approximately, due to
--   floating point precision).
--   
--   For more information on the underlying transforms, see
--   <a>http://www.fftw.org/fftw3_doc/What-FFTW-Really-Computes.html</a>.
module Numeric.FFT.Vector.Invertible

-- | Create and run a <a>Plan</a> for the given transform.
run :: (Vector v a, Vector v b, Storable a, Storable b) => Transform a b -> v a -> v b

-- | Create a <a>Plan</a> of a specific size. This function is equivalent
--   to <tt><a>planOfType</a> <a>Estimate</a></tt>.
plan :: (Storable a, Storable b) => Transform a b -> Int -> Plan a b

-- | Run a plan on the given <a>Vector</a>.
--   
--   If <tt><a>planInputSize</a> p /= length v</tt>, then calling
--   <tt>execute p v</tt> will throw an exception.
execute :: (Vector v a, Vector v b, Storable a, Storable b) => Plan a b -> v a -> v b

-- | A forward discrete Fourier transform. The output and input sizes are
--   the same (<tt>n</tt>).
--   
--   <pre>
--   y_k = sum_(j=0)^(n-1) x_j e^(-2pi i j k/n)
--   </pre>
dft :: Transform (Complex Double) (Complex Double)

-- | A backward discrete Fourier transform which is the inverse of
--   <a>dft</a>. The output and input sizes are the same (<tt>n</tt>).
--   
--   <pre>
--   y_k = (1/n) sum_(j=0)^(n-1) x_j e^(2pi i j k/n)
--   </pre>
idft :: Transform (Complex Double) (Complex Double)

-- | A forward discrete Fourier transform with real data. If the input size
--   is <tt>n</tt>, the output size will be <tt>n `div` 2 + 1</tt>.
dftR2C :: Transform Double (Complex Double)

-- | A normalized backward discrete Fourier transform which is the left
--   inverse of <a>dftR2C</a>. (Specifically, <tt>run dftC2R . run dftR2C
--   == id</tt>.)
--   
--   This <a>Transform</a> behaves differently than the others:
--   
--   <ul>
--   <li>Calling <tt>plan dftC2R n</tt> creates a <a>Plan</a> whose
--   <i>output</i> size is <tt>n</tt>, and whose <i>input</i> size is <tt>n
--   `div` 2 + 1</tt>.</li>
--   <li>If <tt>length v == n</tt>, then <tt>length (run dftC2R v) ==
--   2*(n-1)</tt>.</li>
--   </ul>
dftC2R :: Transform (Complex Double) Double

-- | A type-1 discrete cosine transform.
--   
--   <pre>
--   y_k = x_0 + (-1)^k x_(n-1) + 2 sum_(j=1)^(n-2) x_j cos(pi j k/(n-1))
--   </pre>
dct1 :: Transform Double Double

-- | A type-1 discrete cosine transform which is the inverse of
--   <a>dct1</a>.
--   
--   <pre>
--   y_k = (1/(2(n-1)) [x_0 + (-1)^k x_(n-1) + 2 sum_(j=1)^(n-2) x_j cos(pi j k/(n-1))]
--   </pre>
idct1 :: Transform Double Double

-- | A type-2 discrete cosine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j cos(pi(j+1/2)k/n)
--   </pre>
dct2 :: Transform Double Double

-- | A type-3 discrete cosine transform which is the inverse of
--   <a>dct2</a>.
--   
--   <pre>
--   y_k = (1/(2n)) [x_0 + 2 sum_(j=1)^(n-1) x_j cos(pi j(k+1/2)/n)]
--   </pre>
idct2 :: Transform Double Double

-- | A type-3 discrete cosine transform.
--   
--   <pre>
--   y_k = x_0 + 2 sum_(j=1)^(n-1) x_j cos(pi j(k+1/2)/n)
--   </pre>
dct3 :: Transform Double Double

-- | A type-2 discrete cosine transform which is the inverse of
--   <a>dct3</a>.
--   
--   <pre>
--   y_k = (1/n) sum_(j=0)^(n-1) x_j cos(pi(j+1/2)k/n)
--   </pre>
idct3 :: Transform Double Double

-- | A type-4 discrete cosine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j cos(pi(j+1/2)(k+1/2)/n)
--   </pre>
dct4 :: Transform Double Double

-- | A type-4 discrete cosine transform which is the inverse of
--   <a>dct4</a>.
--   
--   <pre>
--   y_k = (1/n) sum_(j=0)^(n-1) x_j cos(pi(j+1/2)(k+1/2)/n)
--   </pre>
idct4 :: Transform Double Double

-- | A type-1 discrete sine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j sin(pi(j+1)(k+1)/(n+1))
--   </pre>
dst1 :: Transform Double Double

-- | A type-1 discrete sine transform which is the inverse of <a>dst1</a>.
--   
--   <pre>
--   y_k = (1/(n+1)) sum_(j=0)^(n-1) x_j sin(pi(j+1)(k+1)/(n+1))
--   </pre>
idst1 :: Transform Double Double

-- | A type-2 discrete sine transform.
--   
--   <pre>
--   y_k = 2 sum_(j=0)^(n-1) x_j sin(pi(j+1/2)(k+1)/n)
--   </pre>
dst2 :: Transform Double Double

-- | A type-3 discrete sine transform which is the inverse of <a>dst2</a>.
--   
--   <pre>
--   y_k = (1/(2n)) [(-1)^k x_(n-1) + 2 sum_(j=0)^(n-2) x_j sin(pi(j+1)(k+1/2)/n)]
--   </pre>
idst2 :: Transform Double Double

-- | A type-3 discrete sine transform.
--   
--   <pre>
--   y_k = (-1)^k x_(n-1) + 2 sum_(j=0)^(n-2) x_j sin(pi(j+1)(k+1/2)/n)
--   </pre>
dst3 :: Transform Double Double

-- | A type-2 discrete sine transform which is the inverse of <a>dst3</a>.
--   
--   <pre>
--   y_k = (1/n) sum_(j=0)^(n-1) x_j sin(pi(j+1/2)(k+1)/n)
--   </pre>
idst3 :: Transform Double Double

-- | A type-4 discrete sine transform.
--   
--   <pre>
--   y_k = sum_(j=0)^(n-1) x_j sin(pi(j+1/2)(k+1/2)/n)
--   </pre>
dst4 :: Transform Double Double

-- | A type-4 discrete sine transform which is the inverse of <a>dst4</a>.
--   
--   <pre>
--   y_k = (1/(2n)) sum_(j=0)^(n-1) x_j sin(pi(j+1/2)(k+1/2)/n)
--   </pre>
idst4 :: Transform Double Double


-- | This module provides normalized versions of the transforms in
--   <tt>fftw</tt>.
--   
--   All of the transforms are normalized so that
--   
--   <ul>
--   <li>Each transform is unitary, i.e., preserves the inner product and
--   the sum-of-squares norm of its input.</li>
--   <li>Each backwards transform is the inverse of the corresponding
--   forwards transform.</li>
--   </ul>
--   
--   (Both conditions only hold approximately, due to floating point
--   precision.)
--   
--   For more information on the underlying transforms, see
--   <a>http://www.fftw.org/fftw3_doc/What-FFTW-Really-Computes.html</a>.
module Numeric.FFT.Vector.Unitary

-- | Create and run a <a>Plan</a> for the given transform.
run :: (Vector v a, Vector v b, Storable a, Storable b) => Transform a b -> v a -> v b

-- | Create a <a>Plan</a> of a specific size. This function is equivalent
--   to <tt><a>planOfType</a> <a>Estimate</a></tt>.
plan :: (Storable a, Storable b) => Transform a b -> Int -> Plan a b

-- | Run a plan on the given <a>Vector</a>.
--   
--   If <tt><a>planInputSize</a> p /= length v</tt>, then calling
--   <tt>execute p v</tt> will throw an exception.
execute :: (Vector v a, Vector v b, Storable a, Storable b) => Plan a b -> v a -> v b

-- | A discrete Fourier transform. The output and input sizes are the same
--   (<tt>n</tt>).
--   
--   <pre>
--   y_k = (1/sqrt n) sum_(j=0)^(n-1) x_j e^(-2pi i j k/n)
--   </pre>
dft :: Transform (Complex Double) (Complex Double)

-- | An inverse discrete Fourier transform. The output and input sizes are
--   the same (<tt>n</tt>).
--   
--   <pre>
--   y_k = (1/sqrt n) sum_(j=0)^(n-1) x_j e^(2pi i j k/n)
--   </pre>
idft :: Transform (Complex Double) (Complex Double)

-- | A forward discrete Fourier transform with real data. If the input size
--   is <tt>n</tt>, the output size will be <tt>n `div` 2 + 1</tt>.
dftR2C :: Transform Double (Complex Double)

-- | A normalized backward discrete Fourier transform which is the left
--   inverse of <a>dftR2C</a>. (Specifically, <tt>run dftC2R . run dftR2C
--   == id</tt>.)
--   
--   This <a>Transform</a> behaves differently than the others:
--   
--   <ul>
--   <li>Calling <tt>plan dftC2R n</tt> creates a <a>Plan</a> whose
--   <i>output</i> size is <tt>n</tt>, and whose <i>input</i> size is <tt>n
--   `div` 2 + 1</tt>.</li>
--   <li>If <tt>length v == n</tt>, then <tt>length (run dftC2R v) ==
--   2*(n-1)</tt>.</li>
--   </ul>
dftC2R :: Transform (Complex Double) Double

-- | A type-2 discrete cosine transform. Its inverse is <tt>dct3</tt>.
--   
--   <tt>y_k = w(k) sum_(j=0)^(n-1) x_j cos(pi(j+1/2)k/n);</tt> where
--   <tt>w(0)=1/sqrt n</tt>, and <tt>w(k)=sqrt(2/n)</tt> for
--   <tt>k&gt;0</tt>.
dct2 :: Transform Double Double

-- | A type-3 discrete cosine transform which is the inverse of
--   <a>dct2</a>.
--   
--   <tt>y_k = (-1)^k w(n-1) x_(n-1) + 2 sum_(j=0)^(n-2) w(j) x_j
--   sin(pi(j+1)(k+1/2)/n);</tt> where <tt>w(0)=1/sqrt(n)</tt>, and
--   <tt>w(k)=1/sqrt(2n)</tt> for <tt>k&gt;0</tt>.
idct2 :: Transform Double Double

-- | A type-4 discrete cosine transform. It is its own inverse.
--   
--   <pre>
--   y_k = (1/sqrt n) sum_(j=0)^(n-1) x_j cos(pi(j+1/2)(k+1/2)/n)
--   </pre>
dct4 :: Transform Double Double
