Package net.algart.matrices.spectra

Interface SpectralTransform

All Known Implementing Classes:
AbstractSpectralTransform, FastFourierTransform, SeparableFastHartleyTransform
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 n-dimensional matrix, consisting of some samples. The transformed samples can be represented in two forms:

  1. maximally abstract 1-dimensional array of samples, stored in some implementation of SampleArray interface;
  2. n-dimensional matrix (N=1,2,3,...) of real / complex numbers, stored in one / two 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:

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 (2k). 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 floating-point 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 fixed-point numbers, alike Java int, long, short and other types (for example, if the passed AlgART matrix is Matrix <? extends UpdatableIntArray> or if the passed 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 fixed-point type). But it is not a requirement: for example, you may store the real part of the complex matrix in Matrix <? extends UpdatableDoubleArray> and the imaginary part in Matrix <? extends UpdatableFloatArray>. In any case, if such a method allocates some temporary numeric arrays, it uses for them the precision of one of the passed arguments or better.

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 thread-safe, but are thread-compatible and can be synchronized manually if multithread access is necessary.

Author:
Daniel Alievsky

  • Method Details

    • isLengthAllowed

      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.

      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 (2k).

      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.

      Parameters:
      length - the checked length or matrix dimension.
      Returns:
      whether the specified argument is an allowed dimension for arrays or matrices, trasformed by this transformation.

    • areComplexSamplesRequired

      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.

      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.

      Returns:
      true if this class can transform complex samples only, false if real samples can be transformed too.

    • directTransform

      void directTransform(ArrayContext context, SampleArray samples)
      Direct transform of the passed sample array to its spectrum. The resulting data are returned in the same sample array.
      Parameters:
      context - the context that will be used by this algorithm; may be null (see comments to SpectralTransform).
      samples - the transformed samples.
      Throws:
      NullPointerException - if the samples argument is null.
      IllegalArgumentException - if the length of the passed array is not allowed, i.e. if isLengthAllowed(long) method returns false for this value.
      UnsupportedOperationException - if areComplexSamplesRequired() method returns true, but samples.isComplex() method returns false.

    • inverseTransform

      void inverseTransform(ArrayContext context, SampleArray samples)
      Inverse transform of the spectrum back to the original sample array. The resulting data are returned in the same sample array.
      Parameters:
      context - the context that will be used by this algorithm; may be null (see comments to SpectralTransform).
      samples - the transformed samples.
      Throws:
      NullPointerException - if the samples argument is null.
      IllegalArgumentException - if the length of the passed array is not allowed, i.e. if isLengthAllowed(long) method returns false for this value.
      UnsupportedOperationException - if areComplexSamplesRequired() method returns true, but samples.isComplex() method returns false.

    • directTransformMatrix

      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. The complex matrix is represented as a pair of AlgART matrices (matrixRe,matrixIm): the corresponding elements of these 2 matrices contain the real and imaginary parts of the corresponding elements of the complex matrix. The real matrix is represented as a single AlgART matrix matrixRe; in this case, matrixIm argument must be null. (It is allowed only if areComplexSamplesRequired() method returns false.) The resulting data are returned in the same AlgART matrices.
      Parameters:
      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.
      Throws:
      NullPointerException - if the matrixRe argument is null.
      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.
      UnsupportedOperationException - if areComplexSamplesRequired() method returns true and matrixIm argument is null.

    • inverseTransformMatrix

      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. The complex matrix is represented as a pair of AlgART matrices (matrixRe,matrixIm): the corresponding elements of these 2 matrices contain the real and imaginary parts of the corresponding elements of the complex matrix. The real matrix is represented as a single AlgART matrix matrixRe; in this case, matrixIm argument must be null. (It is allowed only if areComplexSamplesRequired() method returns false.) The resulting data are returned in the same AlgART matrices.
      Parameters:
      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.
      Throws:
      NullPointerException - if the matrixRe argument is null.
      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.
      UnsupportedOperationException - if areComplexSamplesRequired() method returns true and matrixIm argument is null.