Author: celestin
Date: Thu Dec 15 19:47:42 2011
New Revision: 1214932
URL: http://svn.apache.org/viewvc?rev=1214932&view=rev
Log:
Further alterations to javadoc (MATH-677).
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java?rev=1214932&r1=1214931&r2=1214932&view=diff
==============================================================================
---
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java
(original)
+++
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java
Thu Dec 15 19:47:42 2011
@@ -27,7 +27,7 @@ import org.apache.commons.math.util.Fast
* Implements the Fast Cosine Transform for transformation of one-dimensional
* real data sets. For reference, see James S. Walker, <em>Fast Fourier
* Transforms</em>, chapter 3 (ISBN 0849371635).
- * <p>
+ * </p>
* <p>
* 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.Fast
* + [2 / (N - 1)]<sup>1/2</sup> ∑<sub>n=1</sub><sup>N-2</sup>
* y<sub>n</sub> cos[π nk / (N - 1)],</li>
* </ul>
- * 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.
* </p>
* <p> {@link RealTransformer}s following this convention are returned by the
* factory method {@link #createOrthogonal()}.
@@ -91,17 +91,17 @@ import org.apache.commons.math.util.Fast
* of the N first elements of the DFT of the extended data set
* x<sub>0</sub><sup>#</sup>, …, x<sub>2N-3</sub><sup>#</sup>
* <br/>
- * 2y<sub>n</sub> = ∑<sub>k=0</sub><sup>2N-3</sup>
+ * y<sub>n</sub> = (1 / 2) ∑<sub>k=0</sub><sup>2N-3</sup>
* x<sub>k</sub><sup>#</sup> exp[-2πi nk / (2N - 2)]
* k = 0, …, N-1.
* </p>
* <p>
- * 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 = 2<sup>n</sup> + 1). Besides, it implicitly assumes
* that the sampled function is even.
* </p>
- * <p>As of version 2.0 this no longer implements Serializable</p>
+ * <p>As of version 2.0 this no longer implements Serializable.</p>
*
* @version $Id: FastCosineTransformer.java 1213585 2011-12-13 07:44:52Z
* celestin $
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java?rev=1214932&r1=1214931&r2=1214932&view=diff
==============================================================================
---
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java
(original)
+++
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java
Thu Dec 15 19:47:42 2011
@@ -26,25 +26,57 @@ import org.apache.commons.math.exception
import org.apache.commons.math.util.FastMath;
/**
- * Implements the <a
href="http://mathworld.wolfram.com/FastFourierTransform.html";>
- * Fast Fourier Transform</a> for transformation of one-dimensional data sets.
- * For reference, see <b>Applied Numerical Linear Algebra</b>, ISBN 0898713897,
- * chapter 6.
* <p>
- * 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 <em>Applied Numerical Linear
+ * Algebra</em>, ISBN 0898713897, chapter 6.
* </p>
* <p>
- * 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.
+ * </p>
+ * <p>
+ * 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,
* <i>On computing the discrete Fourier transform</i>, Mathematics of
* Computation, 32 (1978), 175 - 199.
* </p>
+ * <h3><a id="standard">Standard DFT</a></h3>
+ * <p>
+ * The standard normalization convention is defined as follows
+ * <ul>
+ * <li>forward transform: y<sub>n</sub> = ∑<sub>k=0</sub><sup>N-1</sup>
+ * x<sub>k</sub> exp(-2πi n k / N),</li>
+ * <li>inverse transform: x<sub>k</sub> = N<sup>-1</sup>
+ * ∑<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> exp(2πi n k / N),</li>
+ * </ul>
+ * where N is the size of the data sample.
+ * </p>
+ * <p>
+ * {@link FastFourierTransformer}s following this convention are returned by
the
+ * factory method {@link #create()}.
+ * </p>
+ * <h3><a id="unitary">Unitary DFT</a></h3>
+ * <p>
+ * The unitary normalization convention is defined as follows
+ * <ul>
+ * <li>forward transform: y<sub>n</sub> = (1 / √N)
+ * ∑<sub>k=0</sub><sup>N-1</sup> x<sub>k</sub> exp(-2πi n k / N),</li>
+ * <li>inverse transform: x<sub>k</sub> = (1 / √N)
+ * ∑<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> exp(2πi n k / N),</li>
+ * </ul>
+ * which makes the transform unitary. N is the size of the data sample.
+ * </p>
+ * <p>
+ * {@link FastFourierTransformer}s following this convention are returned by
the
+ * factory method {@link #createUnitary()}.
+ * </p>
*
- * @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 impl
this.unitary = unitary;
}
+
/**
* <p>
* Returns a new instance of this class. The returned transformer uses the
- * normalizing conventions described below.
- * <ul>
- * <li>Forward transform:
- * y<sub>n</sub> = ∑<sub>k=0</sub><sup>N-1</sup>
- * x<sub>k</sub> exp(-2πi n k / N),</li>
- * <li>Inverse transform:
- * x<sub>k</sub> = N<sup>-1</sup> ∑<sub>n=0</sub><sup>N-1</sup>
- * y<sub>n</sub> exp(2πi n k / N),</li>
- * </ul>
- * where N is the size of the data sample.
+ * <a href="#standard">standard normalizing conventions</a>.
* </p>
*
- * @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 impl
/**
* <p>
* Returns a new instance of this class. The returned transformer uses the
- * normalizing conventions described below.
- * <ul>
- * <li>Forward transform:
- * y<sub>n</sub> = N<sup>-1/2</sup> ∑<sub>k=0</sub><sup>N-1</sup>
- * x<sub>k</sub> exp(-2πi n k / N),</li>
- * <li>Inverse transform:
- * x<sub>k</sub> = N<sup>-1/2</sup> ∑<sub>n=0</sub><sup>N-1</sup>
- * y<sub>n</sub> exp(2πi n k / N),</li>
- * </ul>
- * which make the transform unitary. N is the size of the data sample.
+ * <a href="#unitary">unitary normalizing conventions</a>.
* </p>
*
- * @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);
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java?rev=1214932&r1=1214931&r2=1214932&view=diff
==============================================================================
---
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java
(original)
+++
commons/proper/math/trunk/src/main/java/org/apache/commons/math/transform/FastSineTransformer.java
Thu Dec 15 19:47:42 2011
@@ -23,20 +23,87 @@ import org.apache.commons.math.exception
import org.apache.commons.math.util.FastMath;
/**
- * Implements the <a href="http://documents.wolfram.com/v5/Add-onsLinks/
- * StandardPackages/LinearAlgebra/FourierTrig.html">Fast Sine Transform</a>
- * for transformation of one-dimensional data sets. For reference, see
- * <b>Fast Fourier Transforms</b>, ISBN 0849371635, chapter 3.
- * <p>
- * FST is its own inverse, up to a multiplier depending on conventions.
- * The equations are listed in the comments of the corresponding methods.</p>
- * <p>
- * 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.</p>
- * <p>As of version 2.0 this no longer implements Serializable</p>
+ * <p>
+ * Implements the Fast Sine Transform for transformation of one-dimensional
real
+ * data sets. For reference, see James S. Walker, <em>Fast Fourier
+ * Transforms</em>, chapter 3 (ISBN 0849371635).
+ * </p>
+ * <p>
+ * There are several variants of the discrete sine transform. The present
+ * implementation corresponds to DST-I, with various normalization conventions,
+ * which are described below. <strong>It should be noted that regardless to the
+ * convention, the first element of the dataset to be transformed must be
+ * zero.</strong>
+ * </p>
+ * <h3><a id="standard">Standard DST-I</a></h3>
+ * <p>
+ * The standard normalization convention is defined as follows
+ * <ul>
+ * <li>forward transform: y<sub>n</sub> = ∑<sub>k=0</sub><sup>N-1</sup>
+ * x<sub>k</sub> sin(π nk / N),</li>
+ * <li>inverse transform: x<sub>k</sub> = (2 / N)
+ * ∑<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> sin(π nk / N),</li>
+ * </ul>
+ * where N is the size of the data sample, and x<sub>0</sub> = 0.
+ * </p>
+ * <p>
+ * {@link RealTransformer}s following this convention are returned by the
+ * factory method {@link #create()}.
+ * </p>
+ * <h3><a id="orthogonal">Orthogonal DST-I</a></h3>
+ * <p>
+ * The orthogonal normalization convention is defined as follows
+ * <ul>
+ * <li>Forward transform: y<sub>n</sub> = √(2 / N)
+ * ∑<sub>k=0</sub><sup>N-1</sup> x<sub>k</sub> sin(π nk / N),</li>
+ * <li>Inverse transform: x<sub>k</sub> = √(2 / N)
+ * ∑<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> sin(π nk / N),</li>
+ * </ul>
+ * which makes the transform orthogonal. N is the size of the data sample, and
+ * x<sub>0</sub> = 0.
+ * </p>
+ * <p>
+ * {@link RealTransformer}s following this convention are returned by the
+ * factory method {@link #createOrthogonal()}.
+ * </p>
+ * <h3>Link with the DFT, and assumptions on the layout of the data set</h3>
+ * <p>
+ * DST-I is equivalent to DFT of an <em>odd extension</em> of the data series.
+ * More precisely, if x<sub>0</sub>, …, x<sub>N-1</sub> is the data set
+ * to be sine transformed, the extended data set x<sub>0</sub><sup>#</sup>,
+ * …, x<sub>2N-1</sub><sup>#</sup> is defined as follows
+ * <ul>
+ * <li>x<sub>0</sub><sup>#</sup> = x<sub>0</sub> = 0,</li>
+ * <li>x<sub>k</sub><sup>#</sup> = x<sub>k</sub> if 1 ≤ k < N,</li>
+ * <li>x<sub>N</sub><sup>#</sup> = 0,</li>
+ * <li>x<sub>k</sub><sup>#</sup> = -x<sub>2N-k</sub> if N + 1 ≤ k <
+ * 2N.</li>
+ * </ul>
+ * </p>
+ * <p>
+ * Then, the standard DST-I y<sub>0</sub>, …, y<sub>N-1</sub> of the
real
+ * data set x<sub>0</sub>, …, x<sub>N-1</sub> is equal to <em>half</em>
+ * of i (the pure imaginary number) times the N first elements of the DFT of
the
+ * extended data set x<sub>0</sub><sup>#</sup>, …,
+ * x<sub>2N-1</sub><sup>#</sup> <br />
+ * y<sub>n</sub> = (i / 2) ∑<sub>k=0</sub><sup>2N-1</sup>
+ * x<sub>k</sub><sup>#</sup> exp[-2πi nk / (2N)]
+ * k = 0, …, N-1.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * As of version 2.0 this no longer implements Serializable.
+ * </p>
*
- * @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 impleme
/**
* <p>
* Returns a new instance of this class. The returned transformer uses the
- * normalizing conventions described below.
- * <ul>
- * <li>Forward transform:
- * y<sub>n</sub> = ∑<sub>k=0</sub><sup>N-1</sup>
- * x<sub>k</sub> sin(π nk / N),</li>
- * <li>Inverse transform:
- * x<sub>k</sub> = (2 / N) ∑<sub>n=0</sub><sup>N-1</sup>
- * y<sub>n</sub> sin(π nk / N),</li>
- * </ul>
- * where N is the size of the data sample.
+ * <a href="#standard">standard normalizing conventions</a>.
* </p>
*
- * @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 impleme
/**
* <p>
* Returns a new instance of this class. The returned transformer uses the
- * normalizing conventions described below.
- * <ul>
- * <li>Forward transform:
- * y<sub>n</sub> = √(2 / N) ∑<sub>k=0</sub><sup>N-1</sup>
- * x<sub>k</sub> sin(π nk / N),</li>
- * <li>Inverse transform:
- * x<sub>k</sub> = √(2 / N) ∑<sub>n=0</sub><sup>N-1</sup>
- * y<sub>n</sub> sin(π nk / N),</li>
- * </ul>
- * which make the transform orthogonal. N is the size of the data sample.
+ * <a href="#orthogonal">orthogonal normalizing conventions</a>.
* </p>
*
- * @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 impleme
* 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);
}
