public interface SpectralTransform
Spectral transform: Fourier, Hartley, Hadamar, etc.
This interface is an abstraction, allowing to perform two basic operations: direct transform and inverse transform over an array or ndimensional matrix, consisting of some samples. The transformed samples can be represented in two forms:
SampleArray
interface;AlgART numeric matrices
.In the first case, the transformation is performed by
directTransform
/ inverseTransform
methods,
in the second case — by directTransformMatrix
/ inverseTransformMatrix
methods.
This package, in the current implementation, offers implementations of two transforms:
FastFourierTransform
class;SeparableFastHartleyTransform
class.These classes also contain additional methods, allowing to convert the Hartley spectrum to Fourier one and vise versa, and also to calculate the spectrum of the convolution of two matrices (real or complex) on the base of spectra of the source matrices.
Some implementations of this interface can work with complex numbers only, other implementations can process
both complex and real samples. In this package, FastFourierTransform
class requires complex samples,
but SeparableFastHartleyTransform
can be applied to real samples also.
You can check, whether complex numbers are required or no, by areComplexSamplesRequired()
method.
If you work with real numbers only, in most cases you don't need FastFourierTransform
,
because the separable Hartley transform works essentially faster and allows to solve the same tasks,
including getting the Fourier spectrum.
The implementations of this interface can require that the length of the processed sample arrays
or dimensions of the processed matrices should fulfil some restrictions. In particular, both implementations,
offered by this package, require that all dimensions should be powers of two (2^{k}).
To process an array or matrix with another sizes, you must append it to the nearest allowed sizes,
usually by zeroes or by another form of continuation: see Matrix.ContinuationMode
class.
You can check, whether some size is allowed or no, by isLengthAllowed(long)
method.
All numeric algorithms, performed by methods of this interface and its implementations,
are performed over floatingpoint numbers, corresponding to float or double Java types.
Single precision is used, if the passed sample arrays are represented by float element type;
double precision is used, if the passed sample arrays are represented by double element type.
It is theoretically possible to process sample arrays, represented by fixedpoint numbers,
alike Java int, long, short and other types (for example,
if the passed AlgART matrix is Matrix <? extends UpdatableIntArray>
SampleArray
is RealScalarSampleArray
, built on the base of
UpdatableByteArray
). In this situation,
calculations can be performed with some form of rounding, possible overflows lead to unspecified results
and algorithms can work slower.
If some methods of this interface or its implementations have several arguments, representing arrays
of samples — for example, real and imaginary part in
directTransformMatrix
/ inverseTransformMatrix
methods,
or source and target spectra in
FastFourierTransform.spectrumOfConvolution
method,
or Fourier and Hartley spectra in
SeparableFastHartleyTransform.separableHartleyToFourier
method —
then all passed arrays usually have the same numeric precision (float, double
or some fixedpoint type). But it is not a requirement: for example, you may store the real part
of the complex matrix in Matrix <? extends UpdatableDoubleArray>
Matrix <? extends UpdatableFloatArray>
Most of methods of this interface and its implementations work with an array context
,
passed to them in the first argument. This context is used as in
Arrays.ParallelExecutor
class for interruption, showing the progress,
allocating work memory (if necessary) and multiprocessing on several CPUs.
If this argument is null, then all temporary AlgART arrays are allocated by
SimpleMemoryModel
, multiprocessing (when possible) is implemented by
DefaultThreadPoolFactory
class, interrupting by the user is impossible
and showing the progress is not supported.
The implementations of this class are not threadsafe, but are threadcompatible and can be synchronized manually if multithread access is necessary.
Modifier and Type  Method and Description 

boolean 
areComplexSamplesRequired()
Returns true if the transformation methods of this class (
directTransform ,
inverseTransform , directTransformMatrix ,
inverseTransformMatrix ) can process only complex samples,
false if the real samples are also allowed. 
void 
directTransform(ArrayContext context,
SampleArray samples)
Direct transform of the passed sample array to its spectrum.

void 
directTransformMatrix(ArrayContext context,
Matrix<? extends UpdatablePNumberArray> matrixRe,
Matrix<? extends UpdatablePNumberArray> matrixIm)
Direct transform of the passed matrix of real or complex numbers to its spectrum.

void 
inverseTransform(ArrayContext context,
SampleArray samples)
Inverse transform of the spectrum back to the original sample array.

void 
inverseTransformMatrix(ArrayContext context,
Matrix<? extends UpdatablePNumberArray> matrixRe,
Matrix<? extends UpdatablePNumberArray> matrixIm)
Inverse transform of the spectrum back to the original matrix of real or complex numbers.

boolean 
isLengthAllowed(long length)
Returns true if the specified argument is an allowed dimension for arrays or matrices,
transformed by
directTransform , inverseTransform ,
directTransformMatrix or inverseTransformMatrix
method. 
boolean isLengthAllowed(long length)
directTransform
, inverseTransform
,
directTransformMatrix
or inverseTransformMatrix
method.
More precisely, if this method returns false for the length of a sample array,
passed to 1st or 2nd methods, or for some dimension of some matrix, passed to 3rd or 4th method,
then those methods throw IllegalArgumentException
.
In other case, those methods will process that passed data.
In both implementations of this interface, offered by this package, this method returns true if the passed length is a power of two (2^{k}).
If the length argument is negative, the result of this method is unspecified. It is not a problem, because lengths of sample arrays and dimensions of AlgART matrices cannot be negative.
length
 the checked length or matrix dimension.boolean areComplexSamplesRequired()
directTransform
,
inverseTransform
, directTransformMatrix
,
inverseTransformMatrix
) can process only complex samples,
false if the real samples are also allowed.
More precisely, if this method returns true,
then the methods directTransform
/ inverseTransform
checks, whether SampleArray.isComplex()
method returns true for the samples argument,
and the methods directTransformMatrix
/
inverseTransformMatrix
checks, whether the matrixIm argument is
not null. If this condition is not fulfilled, these methods throw
UnsupportedOperationException.
In other case, these methods work normally.
In implementations, offered by this package, this method returns true
in FastFourierTransform
class and false in SeparableFastHartleyTransform
class.
void directTransform(ArrayContext context, SampleArray samples)
context
 the context that will be used by this algorithm; may be null
(see comments to SpectralTransform
).samples
 the transformed samples.java.lang.NullPointerException
 if the samples argument is null.java.lang.IllegalArgumentException
 if the length
of the passed array
is not allowed, i.e. if isLengthAllowed(long)
method
returns false for this value.java.lang.UnsupportedOperationException
 if areComplexSamplesRequired()
method returns true,
but samples.isComplex()
method
returns false.void inverseTransform(ArrayContext context, SampleArray samples)
context
 the context that will be used by this algorithm; may be null
(see comments to SpectralTransform
).samples
 the transformed samples.java.lang.NullPointerException
 if the samples argument is null.java.lang.IllegalArgumentException
 if the length
of the passed array
is not allowed, i.e. if isLengthAllowed(long)
method
returns false for this value.java.lang.UnsupportedOperationException
 if areComplexSamplesRequired()
method returns true,
but samples.isComplex()
method
returns false.void directTransformMatrix(ArrayContext context, Matrix<? extends UpdatablePNumberArray> matrixRe, Matrix<? extends UpdatablePNumberArray> matrixIm)
areComplexSamplesRequired()
method returns false.)
The resulting data are returned in the same AlgART matrices.context
 the context that will be used by this algorithm; may be null
(see comments to SpectralTransform
).matrixRe
 the transformed matrix if we have a real matrix;
the real parts of the elements of the transformed matrix if it is a complex matrix.matrixIm
 null if we have a real matrix;
the imaginary parts of the elements of the transformed matrix if it is a complex matrix.java.lang.NullPointerException
 if the matrixRe argument is null.java.lang.IllegalArgumentException
 if the some of dimensions
of the passed matrices
is not allowed, i.e. if isLengthAllowed(long)
method
returns false for this value.SizeMismatchException
 if both passed matrices are not null (the case of the complex
matrix) and have different dimensions.java.lang.UnsupportedOperationException
 if areComplexSamplesRequired()
method returns true
and matrixIm argument is null.void inverseTransformMatrix(ArrayContext context, Matrix<? extends UpdatablePNumberArray> matrixRe, Matrix<? extends UpdatablePNumberArray> matrixIm)
areComplexSamplesRequired()
method returns false.)
The resulting data are returned in the same AlgART matrices.context
 the context that will be used by this algorithm; may be null
(see comments to SpectralTransform
).matrixRe
 the transformed matrix if we have a real matrix;
the real parts of the elements of the transformed matrix if it is a complex matrix.matrixIm
 null if we have a real matrix;
the imaginary parts of the elements of the transformed matrix if it is a complex matrix.java.lang.NullPointerException
 if the matrixRe argument is null.java.lang.IllegalArgumentException
 if the some of dimensions
of the passed matrices
is not allowed, i.e. if isLengthAllowed(long)
method
returns false for this value.SizeMismatchException
 if both passed matrices are not null (the case of the complex
matrix) and have different dimensions.java.lang.UnsupportedOperationException
 if areComplexSamplesRequired()
method returns true
and matrixIm argument is null.