From ead76ad6aceb93de5bcef423ace01650f0558804 Mon Sep 17 00:00:00 2001 From: Sebastien Brisard Date: Thu, 15 Dec 2011 19:47:42 +0000 Subject: [PATCH] Further alterations to javadoc (MATH-677). git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1214932 13f79535-47bb-0310-9956-ffa450edef68 --- .../math/transform/FastCosineTransformer.java | 12 +- .../transform/FastFourierTransformer.java | 83 ++++++++----- .../math/transform/FastSineTransformer.java | 117 +++++++++++++----- 3 files changed, 138 insertions(+), 74 deletions(-) diff --git a/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java b/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java index 14ea0927c..b3fc001f0 100644 --- a/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java +++ b/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java @@ -27,7 +27,7 @@ import org.apache.commons.math.util.FastMath; * Implements the Fast Cosine Transform for transformation of one-dimensional * real data sets. For reference, see James S. Walker, Fast Fourier * Transforms, chapter 3 (ISBN 0849371635). - *

+ *

*

* There are several variants of the discrete cosine transform. The present * implementation corresponds to DCT-I, with various normalization conventions, @@ -67,7 +67,7 @@ import org.apache.commons.math.util.FastMath; * + [2 / (N - 1)]1/2 ∑n=1N-2 * yn cos[π nk / (N - 1)], * - * which make the transform orthogonal. N is the size of the data sample. + * which makes the transform orthogonal. N is the size of the data sample. *

*

{@link RealTransformer}s following this convention are returned by the * factory method {@link #createOrthogonal()}. @@ -91,17 +91,17 @@ import org.apache.commons.math.util.FastMath; * of the N first elements of the DFT of the extended data set * x0#, …, x2N-3# *
- * 2yn = ∑k=02N-3 + * yn = (1 / 2) ∑k=02N-3 * xk# exp[-2πi nk / (2N - 2)] *     k = 0, …, N-1. *

*

- * The present implementation of the fast cosine transform requires the length - * of the data set to be a power of two plus one + * The present implementation of the discrete cosine transform as a fast cosine + * transform requires the length of the data set to be a power of two plus one * (N = 2n + 1). Besides, it implicitly assumes * that the sampled function is even. *

- *

As of version 2.0 this no longer implements Serializable

+ *

As of version 2.0 this no longer implements Serializable.

* * @version $Id: FastCosineTransformer.java 1213585 2011-12-13 07:44:52Z * celestin $ diff --git a/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java b/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java index 933a42067..f3e47ce42 100644 --- a/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java +++ b/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java @@ -26,25 +26,57 @@ import org.apache.commons.math.exception.util.LocalizedFormats; import org.apache.commons.math.util.FastMath; /** - * Implements the - * Fast Fourier Transform for transformation of one-dimensional data sets. - * For reference, see Applied Numerical Linear Algebra, ISBN 0898713897, - * chapter 6. *

- * There are several conventions for the definition of FFT and inverse FFT, - * mainly on different coefficient and exponent. The conventions adopted in the - * present implementation are specified in the comments of the two provided - * factory methods, {@link #create()} and {@link #createUnitary()}. + * Implements the Fast Fourier Transform for transformation of one-dimensional + * real or complex data sets. For reference, see Applied Numerical Linear + * Algebra, ISBN 0898713897, chapter 6. *

*

- * We require the length of data set to be power of 2, this greatly simplifies - * and speeds up the code. Users can pad the data with zeros to meet this - * requirement. There are other flavors of FFT, for reference, see S. Winograd, + * There are several variants of the discrete Fourier transform, with various + * normalization conventions, which are described below. + *

+ *

+ * The current implementation of the discrete Fourier transform as a fast + * Fourier transform requires the length of the data set to be a power of 2. + * This greatly simplifies and speeds up the code. Users can pad the data with + * zeros to meet this requirement. There are other flavors of FFT, for + * reference, see S. Winograd, * On computing the discrete Fourier transform, Mathematics of * Computation, 32 (1978), 175 - 199. *

+ *

Standard DFT

+ *

+ * The standard normalization convention is defined as follows + *

+ * where N is the size of the data sample. + *

+ *

+ * {@link FastFourierTransformer}s following this convention are returned by the + * factory method {@link #create()}. + *

+ *

Unitary DFT

+ *

+ * The unitary normalization convention is defined as follows + *

+ * which makes the transform unitary. N is the size of the data sample. + *

+ *

+ * {@link FastFourierTransformer}s following this convention are returned by the + * factory method {@link #createUnitary()}. + *

* - * @version $Id$ + * @version $Id: FastFourierTransformer.java 1212260 2011-12-09 06:45:09Z + * celestin $ * @since 1.2 */ public class FastFourierTransformer implements Serializable { @@ -76,22 +108,14 @@ public class FastFourierTransformer implements Serializable { this.unitary = unitary; } + /** *

* Returns a new instance of this class. The returned transformer uses the - * normalizing conventions described below. - *

- * where N is the size of the data sample. + * standard normalizing conventions. *

* - * @return a new DFT transformer, with "standard" normalizing conventions + * @return a new DFT transformer, with standard normalizing conventions */ public static FastFourierTransformer create() { return new FastFourierTransformer(false); @@ -100,19 +124,10 @@ public class FastFourierTransformer implements Serializable { /** *

* Returns a new instance of this class. The returned transformer uses the - * normalizing conventions described below. - *

- * which make the transform unitary. N is the size of the data sample. + * unitary normalizing conventions. *

* - * @return a new FFT transformer, with unitary normalizing conventions + * @return a new DFT transformer, with unitary normalizing conventions */ public static FastFourierTransformer createUnitary() { return new FastFourierTransformer(true); diff --git a/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java b/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java index 3b9031b01..597d922f1 100644 --- a/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java +++ b/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java @@ -23,20 +23,87 @@ import org.apache.commons.math.exception.util.LocalizedFormats; import org.apache.commons.math.util.FastMath; /** - * Implements the Fast Sine Transform - * for transformation of one-dimensional data sets. For reference, see - * Fast Fourier Transforms, ISBN 0849371635, chapter 3. *

- * FST is its own inverse, up to a multiplier depending on conventions. - * The equations are listed in the comments of the corresponding methods.

+ * Implements the Fast Sine Transform for transformation of one-dimensional real + * data sets. For reference, see James S. Walker, Fast Fourier + * Transforms, chapter 3 (ISBN 0849371635). + *

*

- * Similar to FFT, we also require the length of data set to be power of 2. - * In addition, the first element must be 0 and it's enforced in function - * transformation after sampling.

- *

As of version 2.0 this no longer implements Serializable

+ * There are several variants of the discrete sine transform. The present + * implementation corresponds to DST-I, with various normalization conventions, + * which are described below. It should be noted that regardless to the + * convention, the first element of the dataset to be transformed must be + * zero. + *

+ *

Standard DST-I

+ *

+ * The standard normalization convention is defined as follows + *

+ * where N is the size of the data sample, and x0 = 0. + *

+ *

+ * {@link RealTransformer}s following this convention are returned by the + * factory method {@link #create()}. + *

+ *

Orthogonal DST-I

+ *

+ * The orthogonal normalization convention is defined as follows + *

+ * which makes the transform orthogonal. N is the size of the data sample, and + * x0 = 0. + *

+ *

+ * {@link RealTransformer}s following this convention are returned by the + * factory method {@link #createOrthogonal()}. + *

+ *

Link with the DFT, and assumptions on the layout of the data set

+ *

+ * DST-I is equivalent to DFT of an odd extension of the data series. + * More precisely, if x0, …, xN-1 is the data set + * to be sine transformed, the extended data set x0#, + * …, x2N-1# is defined as follows + *

+ *

+ *

+ * Then, the standard DST-I y0, …, yN-1 of the real + * data set x0, …, xN-1 is equal to half + * of i (the pure imaginary number) times the N first elements of the DFT of the + * extended data set x0#, …, + * x2N-1#
+ * yn = (i / 2) ∑k=02N-1 + * xk# exp[-2πi nk / (2N)] + *     k = 0, …, N-1. + *

+ *

+ * The present implementation of the discrete sine transform as a fast sine + * transform requires the length of the data to be a power of two. Besides, + * it implicitly assumes that the sampled function is odd. In particular, the + * first element of the data set must be 0, which is enforced in + * {@link #transform(UnivariateFunction, double, double, int)} and + * {@link #inverseTransform(UnivariateFunction, double, double, int)}, after + * sampling. + *

+ *

+ * As of version 2.0 this no longer implements Serializable. + *

* - * @version $Id$ + * @version $Id: FastSineTransformer.java 1213157 2011-12-12 07:19:23Z celestin$ * @since 1.2 */ public class FastSineTransformer implements RealTransformer { @@ -65,19 +132,10 @@ public class FastSineTransformer implements RealTransformer { /** *

* Returns a new instance of this class. The returned transformer uses the - * normalizing conventions described below. - *

- * where N is the size of the data sample. + * standard normalizing conventions. *

* - * @return a new DST transformer, with "standard" normalizing conventions + * @return a new DST transformer, with standard normalizing conventions */ public static FastSineTransformer create() { return new FastSineTransformer(false); @@ -86,19 +144,10 @@ public class FastSineTransformer implements RealTransformer { /** *

* Returns a new instance of this class. The returned transformer uses the - * normalizing conventions described below. - *

- * which make the transform orthogonal. N is the size of the data sample. + * orthogonal normalizing conventions. *

* - * @return a new DST transformer, with "orthogonal" normalizing conventions + * @return a new DST transformer, with orthogonal normalizing conventions */ public static FastSineTransformer createOrthogonal() { return new FastSineTransformer(true); @@ -110,7 +159,7 @@ public class FastSineTransformer implements RealTransformer { * The first element of the specified data set is required to be {@code 0}. */ public double[] transform(double[] f) throws IllegalArgumentException { - if (orthogonal){ + if (orthogonal) { final double s = FastMath.sqrt(2.0 / f.length); return FastFourierTransformer.scaleArray(fst(f), s); }