Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Sebastien Brisard 2011-12-15 19:47:42 +00:00
parent f8a74e5e56
commit ead76ad6ac
3 changed files with 138 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/main/java/org/apache/commons/math/transform/FastCosineTransformer.java
View File

@ -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, <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.FastMath;
* + [2 / (N - 1)]<sup>1/2</sup> &sum;<sub>n=1</sub><sup>N-2</sup>
* y<sub>n</sub> cos[&pi; 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.FastMath;
* of the N first elements of the DFT of the extended data set
* x<sub>0</sub><sup>&#35;</sup>, &hellip;, x<sub>2N-3</sub><sup>&#35;</sup>
* <br/>
* 2y<sub>n</sub> = &sum;<sub>k=0</sub><sup>2N-3</sup>
* y<sub>n</sub> = (1 / 2) &sum;<sub>k=0</sub><sup>2N-3</sup>
* x<sub>k</sub><sup>&#35;</sup> exp[-2&pi;i nk / (2N - 2)]
* &nbsp;&nbsp;&nbsp;&nbsp;k = 0, &hellip;, 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&nbsp;=&nbsp;2<sup>n</sup>&nbsp;+&nbsp;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 $

83
src/main/java/org/apache/commons/math/transform/FastFourierTransformer.java
View File

@ -26,25 +26,57 @@ import org.apache.commons.math.exception.util.LocalizedFormats;
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> = &sum;<sub>k=0</sub><sup>N-1</sup>
* x<sub>k</sub> exp(-2&pi;i n k / N),</li>
* <li>inverse transform: x<sub>k</sub> = N<sup>-1</sup>
* &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> exp(2&pi;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 / &radic;N)
* &sum;<sub>k=0</sub><sup>N-1</sup> x<sub>k</sub> exp(-2&pi;i n k / N),</li>
* <li>inverse transform: x<sub>k</sub> = (1 / &radic;N)
* &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> exp(2&pi;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 implements Serializable {
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> = &sum;<sub>k=0</sub><sup>N-1</sup>
* x<sub>k</sub> exp(-2&pi;i n k / N),</li>
* <li>Inverse transform:
* x<sub>k</sub> = N<sup>-1</sup> &sum;<sub>n=0</sub><sup>N-1</sup>
* y<sub>n</sub> exp(2&pi;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 implements Serializable {
/**
* <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> &sum;<sub>k=0</sub><sup>N-1</sup>
* x<sub>k</sub> exp(-2&pi;i n k / N),</li>
* <li>Inverse transform:
* x<sub>k</sub> = N<sup>-1/2</sup> &sum;<sub>n=0</sub><sup>N-1</sup>
* y<sub>n</sub> exp(2&pi;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);

117
src/main/java/org/apache/commons/math/transform/FastSineTransformer.java
View File

@ -23,20 +23,87 @@ import org.apache.commons.math.exception.util.LocalizedFormats;
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>
* 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>
* 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>
* 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> = &sum;<sub>k=0</sub><sup>N-1</sup>
* x<sub>k</sub> sin(&pi; nk / N),</li>
* <li>inverse transform: x<sub>k</sub> = (2 / N)
* &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> sin(&pi; 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> = &radic;(2 / N)
* &sum;<sub>k=0</sub><sup>N-1</sup> x<sub>k</sub> sin(&pi; nk / N),</li>
* <li>Inverse transform: x<sub>k</sub> = &radic;(2 / N)
* &sum;<sub>n=0</sub><sup>N-1</sup> y<sub>n</sub> sin(&pi; 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>, &hellip;, x<sub>N-1</sub> is the data set
* to be sine transformed, the extended data set x<sub>0</sub><sup>&#35;</sup>,
* &hellip;, x<sub>2N-1</sub><sup>&#35;</sup> is defined as follows
* <ul>
* <li>x<sub>0</sub><sup>&#35;</sup> = x<sub>0</sub> = 0,</li>
* <li>x<sub>k</sub><sup>&#35;</sup> = x<sub>k</sub> if 1 &le; k &lt; N,</li>
* <li>x<sub>N</sub><sup>&#35;</sup> = 0,</li>
* <li>x<sub>k</sub><sup>&#35;</sup> = -x<sub>2N-k</sub> if N + 1 &le; k &lt;
* 2N.</li>
* </ul>
* </p>
* <p>
* Then, the standard DST-I y<sub>0</sub>, &hellip;, y<sub>N-1</sub> of the real
* data set x<sub>0</sub>, &hellip;, 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>&#35;</sup>, &hellip;,
* x<sub>2N-1</sub><sup>&#35;</sup> <br />
* y<sub>n</sub> = (i / 2) &sum;<sub>k=0</sub><sup>2N-1</sup>
* x<sub>k</sub><sup>&#35;</sup> exp[-2&pi;i nk / (2N)]
* &nbsp;&nbsp;&nbsp;&nbsp;k = 0, &hellip;, 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 implements RealTransformer {
/**
* <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> = &sum;<sub>k=0</sub><sup>N-1</sup>
* x<sub>k</sub> sin(&pi; nk / N),</li>
* <li>Inverse transform:
* x<sub>k</sub> = (2 / N) &sum;<sub>n=0</sub><sup>N-1</sup>
* y<sub>n</sub> sin(&pi; 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 implements RealTransformer {
/**
* <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> = &radic;(2 / N) &sum;<sub>k=0</sub><sup>N-1</sup>
* x<sub>k</sub> sin(&pi; nk / N),</li>
* <li>Inverse transform:
* x<sub>k</sub> = &radic;(2 / N) &sum;<sub>n=0</sub><sup>N-1</sup>
* y<sub>n</sub> sin(&pi; 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 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);
}