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

Javadoc cleanup of transform package, removed unnecessary paragraph tags. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1385310 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2012-09-16 16:32:10 +00:00
parent 75fe8b8b99
commit 7536672818
9 changed files with 46 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/main/java/org/apache/commons/math3/transform/DctNormalization.java
View File

@ -27,7 +27,6 @@ package org.apache.commons.math3.transform;
*/
public enum DctNormalization {
/**
* <p>
* Should be passed to the constructor of {@link FastCosineTransformer}
* to use the <em>standard</em> normalization convention. The standard
* DCT-I normalization convention is defined as follows
@ -43,12 +42,10 @@ public enum DctNormalization {
* y<sub>n</sub> cos[&pi; nk / (N - 1)],</li>
* </ul>
* where N is the size of the data sample.
* </p>
*/
STANDARD_DCT_I,
/**
* <p>
* Should be passed to the constructor of {@link FastCosineTransformer}
* to use the <em>orthogonal</em> normalization convention. The orthogonal
* DCT-I normalization convention is defined as follows

4
src/main/java/org/apache/commons/math3/transform/DftNormalization.java
View File

@ -27,7 +27,6 @@ package org.apache.commons.math3.transform;
*/
public enum DftNormalization {
/**
* <p>
* Should be passed to the constructor of {@link FastFourierTransformer}
* to use the <em>standard</em> normalization convention. This normalization
* convention is defined as follows
@ -38,12 +37,10 @@ public enum DftNormalization {
* &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>
*/
STANDARD,
/**
* <p>
* Should be passed to the constructor of {@link FastFourierTransformer}
* to use the <em>unitary</em> normalization convention. This normalization
* convention is defined as follows
@ -55,7 +52,6 @@ public enum DftNormalization {
* &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>
*/
UNITARY;
}

4
src/main/java/org/apache/commons/math3/transform/DstNormalization.java
View File

@ -27,7 +27,6 @@ package org.apache.commons.math3.transform;
*/
public enum DstNormalization {
/**
* <p>
* Should be passed to the constructor of {@link FastSineTransformer} to
* use the <em>standard</em> normalization convention. The standard DST-I
* normalization convention is defined as follows
@ -38,12 +37,10 @@ public enum DstNormalization {
* &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>
*/
STANDARD_DST_I,
/**
* <p>
* Should be passed to the constructor of {@link FastSineTransformer} to
* use the <em>orthogonal</em> normalization convention. The orthogonal
* DCT-I normalization convention is defined as follows
@ -55,7 +52,6 @@ public enum DstNormalization {
* </ul>
* which makes the transform orthogonal. N is the size of the data sample,
* and x<sub>0</sub> = 0.
* </p>
*/
ORTHOGONAL_DST_I
}

6
src/main/java/org/apache/commons/math3/transform/FastCosineTransformer.java
View File

@ -27,16 +27,13 @@ import org.apache.commons.math3.util.ArithmeticUtils;
import org.apache.commons.math3.util.FastMath;
/**
* <p>
* 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>
* There are several variants of the discrete cosine transform. The present
* implementation corresponds to DCT-I, with various normalization conventions,
* which are specified by the parameter {@link DctNormalization}.
* </p>
* <p>
* DCT-I is equivalent to DFT of an <em>even extension</em> of the data series.
* More precisely, if x<sub>0</sub>, &hellip;, x<sub>N-1</sub> is the data set
@ -48,7 +45,6 @@ import org.apache.commons.math3.util.FastMath;
* <li>x<sub>k</sub><sup>&#35;</sup> = x<sub>2N-2-k</sub>
* if N &le; k &lt; 2N - 2.</li>
* </ul>
* </p>
* <p>
* Then, the standard DCT-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>
@ -58,13 +54,11 @@ import org.apache.commons.math3.util.FastMath;
* 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 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>
*
* @version $Id$
* @since 1.2

48
src/main/java/org/apache/commons/math3/transform/FastFourierTransformer.java
View File

@ -31,16 +31,13 @@ import org.apache.commons.math3.util.FastMath;
import org.apache.commons.math3.util.MathArrays;
/**
* <p>
* 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>
* There are several variants of the discrete Fourier transform, with various
* normalization conventions, which are specified by the parameter
* {@link DftNormalization}.
* </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.
@ -49,7 +46,6 @@ import org.apache.commons.math3.util.MathArrays;
* reference, see S. Winograd,
* <i>On computing the discrete Fourier transform</i>, Mathematics of
* Computation, 32 (1978), 175 - 199.
* </p>
*
* @see DftNormalization
* @version $Id$
@ -162,8 +158,7 @@ public class FastFourierTransformer implements Serializable {
*
* @param dataRI the unscaled transformed data
* @param normalization the normalization to be applied
* @param type the type of transform (forward, inverse) which resulted in the
* specified data
* @param type the type of transform (forward, inverse) which resulted in the specified data
*/
private static void normalizeTransformedData(final double[][] dataRI,
final DftNormalization normalization, final TransformType type) {
@ -205,21 +200,17 @@ public class FastFourierTransformer implements Serializable {
* Computes the standard transform of the specified complex data. The
* computation is done in place. The input data is laid out as follows
* <ul>
* <li>{@code dataRI[0][i]} is the real part of the {@code i}-th data point,
* </li>
* <li>{@code dataRI[1][i]} is the imaginary part of the {@code i}-th data
* point.</li>
* <li>{@code dataRI[0][i]} is the real part of the {@code i}-th data point,</li>
* <li>{@code dataRI[1][i]} is the imaginary part of the {@code i}-th data point.</li>
* </ul>
*
* @param dataRI the two dimensional array of real and imaginary parts of
* the data
* @param normalization the normalization to be applied to the transformed
* data
* @param dataRI the two dimensional array of real and imaginary parts of the data
* @param normalization the normalization to be applied to the transformed data
* @param type the type of transform (forward, inverse) to be performed
* @throws DimensionMismatchException if the number of rows of the specified
* array is not two, or the array is not rectangular
* array is not two, or the array is not rectangular
* @throws MathIllegalArgumentException if the number of data points is not
* a power of two
* a power of two
*/
public static void transformInPlace(final double[][] dataRI,
final DftNormalization normalization, final TransformType type) {
@ -374,8 +365,7 @@ public class FastFourierTransformer implements Serializable {
* @param f the real data array to be transformed
* @param type the type of transform (forward, inverse) to be performed
* @return the complex transformed array
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two
* @throws MathIllegalArgumentException if the length of the data array is not a power of two
*/
public Complex[] transform(final double[] f, final TransformType type) {
final double[][] dataRI = new double[][] {
@ -398,29 +388,27 @@ public class FastFourierTransformer implements Serializable {
* @param type the type of transform (forward, inverse) to be performed
* @return the complex transformed array
* @throws org.apache.commons.math3.exception.NumberIsTooLargeException
* if the lower bound is greater than, or equal to the upper bound
* if the lower bound is greater than, or equal to the upper bound
* @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
* if the number of sample points {@code n} is negative
* if the number of sample points {@code n} is negative
* @throws MathIllegalArgumentException if the number of sample points
* {@code n} is not a power of two
* {@code n} is not a power of two
*/
public Complex[] transform(final UnivariateFunction f,
final double min, final double max, final int n,
final TransformType type) {
final double min, final double max, final int n,
final TransformType type) {
final double[] data = FunctionUtils.sample(f, min, max, n);
return transform(data, type);
}
/**
* Returns the (forward, inverse) transform of the specified complex data
* set.
* Returns the (forward, inverse) transform of the specified complex data set.
*
* @param f the complex data array to be transformed
* @param type the type of transform (forward, inverse) to be performed
* @return the complex transformed array
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two
* @throws MathIllegalArgumentException if the length of the data array is not a power of two
*/
public Complex[] transform(final Complex[] f, final TransformType type) {
final double[][] dataRI = TransformUtils.createRealImaginaryArray(f);
@ -439,11 +427,9 @@ public class FastFourierTransformer implements Serializable {
* &times; n<sub>d</sub>, where n<sub>k</sub> is the number of elements in
* dimension k, and d is the total number of dimensions.
*
* @param mdca Multi-Dimensional Complex Array id est
* {@code Complex[][][][]}
* @param mdca Multi-Dimensional Complex Array, i.e. {@code Complex[][][][]}
* @param type the type of transform (forward, inverse) to be performed
* @return transform of {@code mdca} as a Multi-Dimensional Complex Array
* id est {@code Complex[][][][]}
* @return transform of {@code mdca} as a Multi-Dimensional Complex Array, i.e. {@code Complex[][][][]}
* @throws IllegalArgumentException if any dimension is not a power of two
* @deprecated see MATH-736
*/

22
src/main/java/org/apache/commons/math3/transform/FastHadamardTransformer.java
View File

@ -27,11 +27,13 @@ import org.apache.commons.math3.util.ArithmeticUtils;
/**
* Implements the <a href="http://www.archive.chipcenter.com/dsp/DSP000517F1.html">Fast Hadamard Transform</a> (FHT).
* Transformation of an input vector x to the output vector y.
* <p>In addition to transformation of real vectors, the Hadamard transform can
* <p>
* In addition to transformation of real vectors, the Hadamard transform can
* transform integer vectors into integer vectors. However, this integer transform
* cannot be inverted directly. Due to a scaling factor it may lead to rational results.
* As an example, the inverse transform of integer vector (0, 1, 0, 1) is rational
* vector (1/2, -1/2, 0, 0).</p>
* vector (1/2, -1/2, 0, 0).
*
* @version $Id$
* @since 2.0
*/
@ -57,11 +59,10 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
* {@inheritDoc}
*
* @throws org.apache.commons.math3.exception.NonMonotonicSequenceException
* if the lower bound is greater than, or equal to the upper bound
* if the lower bound is greater than, or equal to the upper bound
* @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
* if the number of sample points is negative
* @throws MathIllegalArgumentException if the number of sample points is
* not a power of two
* if the number of sample points is negative
* @throws MathIllegalArgumentException if the number of sample points is not a power of two
*/
public double[] transform(final UnivariateFunction f,
final double min, final double max, final int n,
@ -77,8 +78,7 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
*
* @param f the integer data array to be transformed (signal)
* @return the integer transformed array (spectrum)
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two
* @throws MathIllegalArgumentException if the length of the data array is not a power of two
*/
public int[] transform(final int[] f) {
return fht(f);
@ -224,8 +224,7 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
*
* @param x the real data array to be transformed
* @return the real transformed array, {@code y}
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two
* @throws MathIllegalArgumentException if the length of the data array is not a power of two
*/
protected double[] fht(double[] x) throws MathIllegalArgumentException {
@ -276,8 +275,7 @@ public class FastHadamardTransformer implements RealTransformer, Serializable {
*
* @param x the integer data array to be transformed
* @return the integer transformed array, {@code y}
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two
* @throws MathIllegalArgumentException if the length of the data array is not a power of two
*/
protected int[] fht(int[] x) throws MathIllegalArgumentException {

23
src/main/java/org/apache/commons/math3/transform/FastSineTransformer.java
View File

@ -27,18 +27,15 @@ import org.apache.commons.math3.util.ArithmeticUtils;
import org.apache.commons.math3.util.FastMath;
/**
* <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 specified by the parameter {@link DstNormalization}.
* <strong>It should be noted that regardless to the convention, the first
* element of the dataset to be transformed must be zero.</strong>
* </p>
* <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
@ -51,7 +48,6 @@ import org.apache.commons.math3.util.FastMath;
* <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>
@ -61,7 +57,6 @@ import org.apache.commons.math3.util.FastMath;
* 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,
@ -69,7 +64,6 @@ import org.apache.commons.math3.util.FastMath;
* first element of the data set must be 0, which is enforced in
* {@link #transform(UnivariateFunction, double, double, int, TransformType)},
* after sampling.
* </p>
*
* @version $Id$
* @since 1.2
@ -83,11 +77,9 @@ public class FastSineTransformer implements RealTransformer, Serializable {
private final DstNormalization normalization;
/**
* Creates a new instance of this class, with various normalization
* conventions.
* Creates a new instance of this class, with various normalization conventions.
*
* @param normalization the type of normalization to be applied to the
* transformed data
* @param normalization the type of normalization to be applied to the transformed data
*/
public FastSineTransformer(final DstNormalization normalization) {
this.normalization = normalization;
@ -99,7 +91,7 @@ public class FastSineTransformer implements RealTransformer, Serializable {
* The first element of the specified data set is required to be {@code 0}.
*
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two, or the first element of the data array is not zero
* not a power of two, or the first element of the data array is not zero
*/
public double[] transform(final double[] f, final TransformType type) {
if (normalization == DstNormalization.ORTHOGONAL_DST_I) {
@ -119,11 +111,10 @@ public class FastSineTransformer implements RealTransformer, Serializable {
* This implementation enforces {@code f(x) = 0.0} at {@code x = 0.0}.
*
* @throws org.apache.commons.math3.exception.NonMonotonicSequenceException
* if the lower bound is greater than, or equal to the upper bound
* if the lower bound is greater than, or equal to the upper bound
* @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
* if the number of sample points is negative
* @throws MathIllegalArgumentException if the number of sample points is
* not a power of two
* if the number of sample points is negative
* @throws MathIllegalArgumentException if the number of sample points is not a power of two
*/
public double[] transform(final UnivariateFunction f,
final double min, final double max, final int n,
@ -141,7 +132,7 @@ public class FastSineTransformer implements RealTransformer, Serializable {
* @param f the real data array to be transformed
* @return the real transformed array
* @throws MathIllegalArgumentException if the length of the data array is
* not a power of two, or the first element of the data array is not zero
* not a power of two, or the first element of the data array is not zero
*/
protected double[] fst(double[] f) throws MathIllegalArgumentException {

19
src/main/java/org/apache/commons/math3/transform/RealTransformer.java
View File

@ -22,14 +22,14 @@ import org.apache.commons.math3.exception.NonMonotonicSequenceException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException;
/**
* <p>Interface for one-dimensional data sets transformations producing real
* results.</p>
* <p>Such transforms include {@link FastSineTransformer sine transform},
* Interface for one-dimensional data sets transformations producing real results.
* <p>
* Such transforms include {@link FastSineTransformer sine transform},
* {@link FastCosineTransformer cosine transform} or {@link
* FastHadamardTransformer Hadamard transform}. {@link FastFourierTransformer
* Fourier transform} is of a different kind and does not implement this
* interface since it produces {@link org.apache.commons.math3.complex.Complex}
* results instead of real ones.</p>
* results instead of real ones.
*
* @version $Id$
* @since 2.0
@ -43,8 +43,8 @@ public interface RealTransformer {
* @param type the type of transform (forward, inverse) to be performed
* @return the real transformed array (spectrum)
* @throws MathIllegalArgumentException if the array cannot be transformed
* with the given type (this may be for example due to array size, which is
* constrained in some transforms)
* with the given type (this may be for example due to array size, which is
* constrained in some transforms)
*/
double[] transform(double[] f, TransformType type) throws MathIllegalArgumentException;
@ -58,12 +58,11 @@ public interface RealTransformer {
* @param n the number of sample points
* @param type the type of transform (forward, inverse) to be performed
* @return the real transformed array
* @throws NonMonotonicSequenceException if the lower bound is greater than,
* or equal to the upper bound
* @throws NonMonotonicSequenceException if the lower bound is greater than, or equal to the upper bound
* @throws NotStrictlyPositiveException if the number of sample points is negative
* @throws MathIllegalArgumentException if the sample cannot be transformed
* with the given type (this may be for example due to sample size, which is
* constrained in some transforms)
* with the given type (this may be for example due to sample size, which is
* constrained in some transforms)
*/
double[] transform(UnivariateFunction f, double min, double max, int n,
TransformType type)

7
src/main/java/org/apache/commons/math3/transform/TransformUtils.java
View File

@ -93,7 +93,7 @@ public class TransformUtils {
*
* @param dataC the array of {@link Complex} data to be transformed
* @return a two dimensional array filled with the real and imaginary parts
* of the specified complex input
* of the specified complex input
*/
public static double[][] createRealImaginaryArray(final Complex[] dataC) {
final double[][] dataRI = new double[2][dataC.length];
@ -117,10 +117,9 @@ public class TransformUtils {
* </ul>
*
* @param dataRI the array of real and imaginary parts to be transformed
* @return an array of {@link Complex} with specified real and imaginary
* parts.
* @return an array of {@link Complex} with specified real and imaginary parts.
* @throws DimensionMismatchException if the number of rows of the specified
* array is not two, or the array is not rectangular
* array is not two, or the array is not rectangular
*/
public static Complex[] createComplexArray(final double[][] dataRI)
throws DimensionMismatchException{