Package net.algart.matrices.spectra

Class ComplexScalarSampleArray

java.lang.Object
net.algart.matrices.spectra.ComplexScalarSampleArray
All Implemented Interfaces:
SampleArray
public abstract class ComplexScalarSampleArray extends Object implements SampleArray

Array of samples, where each sample is a complex number, represented by a pair of double values, stored in two AlgART arrays UpdatablePNumberArray.

Please use asSampleArray(UpdatablePNumberArray, UpdatablePNumberArray) method for creating instances of this class.

All operations over samples (adding, subtracting, multiplying) are performed via corresponding operations over elements of the AlgART arrays. Elements of these arrays are interpreted as double values, as if they are read/written by PArray.getDouble(long) and UpdatablePArray.setDouble(long, double) methods.

The instances of this class are not thread-safe, but are thread-compatible and can may be synchronized manually if multithread access is necessary.

Author:
Daniel Alievsky

  • Field Summary

    Fields inherited from interface net.algart.matrices.spectra.SampleArray

    GUARANTEED_COMPATIBLE_SAMPLES_ARRAY_LENGTH

  • Constructor Summary

    Constructors
    Constructor
    Description
    ComplexScalarSampleArray()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    add(long destIndex, long srcIndex1, long srcIndex2)
    Adds the sample #srcIndex2 of this array to the sample #srcIndex1 of this array and stores the result into position #destIndex of this array.
    abstract void
    add(long destIndex, long srcIndex1, SampleArray src2, long srcIndex2)
    Adds the sample #srcIndex2 of src2 array to the sample #srcIndex1 of this array and stores the result into position #destIndex of this array.
    abstract void
    add(long destIndex, SampleArray src, long srcIndex1, long srcIndex2)
    Adds the sample #srcIndex2 of src array to the sample #srcIndex1 of src array and stores the result into position #destIndex of this array.
    static ComplexScalarSampleArray
    asSampleArray(UpdatablePNumberArray samplesRe, UpdatablePNumberArray samplesIm)
    Returns a view of the specified pair of AlgART arrays as an array of scalar complex samples.
    abstract void
    combineWithRealMultipliers(long destIndex, long srcIndex1, double a1, long srcIndex2, double a2)
    Multiplies the sample #srcIndex1 of this array by the real scalar a1, multiplies the sample #srcIndex2 of this array by the real scalar a2 and stores the sum of this two products result into position #destIndex of this array.
    abstract void
    copy(long destIndex, SampleArray src, long srcIndex)
    Copies the sample #srcIndex from src array into position #destIndex in this array.
    final boolean
    isComplex()
    Returns true if the samples in this array are complex, false if they are real.
    abstract long
    length()
    Returns the length: number of elements in this array.
    abstract void
    multiplyByRealScalar(long index, double a)
    Multiplies the sample #destIndex of this array by the real scalar a and stores the result into the same position #destIndex of this array.
    abstract void
    multiplyByScalar(long destIndex, SampleArray src, long srcIndex, double aRe, double aIm)
    Multiplies the sample #srcIndex of src array by the complex scalar aRe+aIm*i (i is the imaginary unit) and stores the result into position #destIndex of this array.
    abstract void
    multiplyRangeByRealScalar(long from, long to, double a)
    Multiplies the samples #fromIndex..toIndex-1 of this array by the real scalar a and stores the result into the same positions of this array.
    abstract ComplexScalarSampleArray
    newCompatibleSamplesArray(long length)
    Creates a new array of samples of the same kind as this one.
    abstract void
    sub(long destIndex, long srcIndex1, long srcIndex2)
    Subtracts the sample #srcIndex2 of this array from the sample #srcIndex1 of this array and stores the result into position #destIndex of this array.
    abstract void
    sub(long destIndex, long srcIndex1, SampleArray src2, long srcIndex2)
    Subtracts the sample #srcIndex2 of src2 array from the sample #srcIndex1 of this array and stores the result into position #destIndex of this array.
    abstract void
    sub(long destIndex, SampleArray src, long srcIndex1, long srcIndex2)
    Subtracts the sample #srcIndex2 of src array from the sample #srcIndex1 of src array and stores the result into position #destIndex of this array.
    abstract void
    swap(long firstIndex, long secondIndex)
    Swaps samples at positions #firstIndex and #secondIndex inside this array.
    abstract String
    toString(String format, String separator, int maxStringLength)
    Returns a string representation of this sample array as contatenated string representations of samples, separating by the given separator.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ComplexScalarSampleArray

      public ComplexScalarSampleArray()

  • Method Details

    • asSampleArray

      public static ComplexScalarSampleArray asSampleArray(UpdatablePNumberArray samplesRe, UpdatablePNumberArray samplesIm)
      Returns a view of the specified pair of AlgART arrays as an array of scalar complex samples. More precisely, the real part of the sample #k in the returned sample array is stored in the element #k of samplesRe array, and the imaginary part of the sample #k in the returned sample array is stored in the element #k of samplesIm array.

      The returned sample array is backed by these two arrays, so any changes of the samples in the returned array are reflected in these arrays, and vice-versa. More precisely, the returned sample array is backed by samplesRe.asUnresizable() and samplesIm.asUnresizable(): if the passed arrays are resizable, posible future changes of their lengths will not affect behaviour of the returned sample array.

      The length of the returned sample array is equal to lengths of samplesRe and samplesIm arrays. (Their lengths must be equal to each other.)

      This method detects, if the passed arrays are DirectAccessible (i.e. the data are stored in usual Java arrays), and provides optimized implementations for this case.

      Parameters:
      samplesRe - the real parts of all samples.
      samplesIm - the imaginary parts of all samples.
      Returns:
      the array of scalar complex samples, represented by these two arrays.
      Throws:
      NullPointerException - if samplesRe or samplesIm is null.
      SizeMismatchException - if samplesRe.length() != samplesIm.length().

    • isComplex

      public final boolean isComplex()
      Description copied from interface: SampleArray
      Returns true if the samples in this array are complex, false if they are real. The method SampleArray.multiplyByScalar(long, SampleArray, long, double, double) works correctly if and only if this method returns true.

      Some methods of this package, for example, Fourier transformations throw UnsupportedOperationException if this method returns false.

      Specified by:
      isComplex in interface SampleArray
      Returns:
      true if the samples in this array are complex.

    • length

      public abstract long length()
      Description copied from interface: SampleArray
      Returns the length: number of elements in this array. The result is never negative.
      Specified by:
      length in interface SampleArray
      Returns:
      the length: number of elements in this array.

    • newCompatibleSamplesArray

      public abstract ComplexScalarSampleArray newCompatibleSamplesArray(long length)
      Description copied from interface: SampleArray
      Creates a new array of samples of the same kind as this one. For example, if the samples are vectors of N complex numbers with float precision, then the elements of the returned arrays will also be vectors of N complex numbers with float precision.

      The typical usage of this method is allocating temporary elements for storing one or several samples inside FFT algorithm.

      Usually this method allocates new array in a usual Java heap (i.e. SimpleMemoryModel when it is based on AlgART arrays). But some implementations can use another storages, like LargeMemoryModel or another custom memory models, specified while creating the sample array. This package provides two implementations, illustrating this: the results of RealVectorSampleArray.asSampleArray and ComplexVectorSampleArray.asSampleArray method, but only in a case, when the length of each real/complex vector (a sample) is large (for relatively little samples, SimpleMemoryModel is used always).

      If the required length is too long and there is not enough memory, OutOfMemoryError or similar errors will be thrown. However, for very large length values, it is also possible that there is enough memory, but this method throws an exception — because the technology of storing elements does not support such large lengths. For example, if it is an array of real vectors with length 1000000, and all vectors are stored inside a single Java array float[], then length=10000 will lead to an exception, even if there is necessary amount of Java memory (~40 GB) — because Java cannot allocate an array longer than Integer.MAX_VALUE. But there is the following guarantee: this method always works correctly, if there is enough memory and 

       length <= max(thisArray.length(), GUARANTEED_COMPATIBLE_SAMPLES_ARRAY_LENGTH).

      So, your can freely use this method for allocating new sample arrays, not greater than this instance, or for allocating a short arrays for temporary values, if their lengths does not exceed GUARANTEED_COMPATIBLE_SAMPLES_ARRAY_LENGTH limit.

      Specified by:
      newCompatibleSamplesArray in interface SampleArray
      Parameters:
      length - the length of new sample array.
      Returns:
      new sample array, compatible with this one.

    • copy

      public abstract void copy(long destIndex, SampleArray src, long srcIndex)
      Description copied from interface: SampleArray
      Copies the sample #srcIndex from src array into position #destIndex in this array.
      Specified by:
      copy in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to replace.
      src - the source sample array (maybe, a reference to this array).
      srcIndex - index of sample in src array to be copied.

    • swap

      public abstract void swap(long firstIndex, long secondIndex)
      Description copied from interface: SampleArray
      Swaps samples at positions #firstIndex and #secondIndex inside this array. #destIndex in this array.
      Specified by:
      swap in interface SampleArray
      Parameters:
      firstIndex - first index of sample to exchange.
      secondIndex - second index of sample to exchange.

    • add

      public abstract void add(long destIndex, SampleArray src, long srcIndex1, long srcIndex2)
      Description copied from interface: SampleArray
      Adds the sample #srcIndex2 of src array to the sample #srcIndex1 of src array and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex1 or srcIndex2, and src array can be a reference to this array: these situations are processed correctly.
      Specified by:
      add in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      src - some other array (or, maybe, a reference to this array).
      srcIndex1 - the index of the first summand in src array.
      srcIndex2 - the index of the second summand in src array.

    • sub

      public abstract void sub(long destIndex, SampleArray src, long srcIndex1, long srcIndex2)
      Description copied from interface: SampleArray
      Subtracts the sample #srcIndex2 of src array from the sample #srcIndex1 of src array and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex1 or srcIndex2, and src array can be a reference to this array: these situations are processed correctly.
      Specified by:
      sub in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      src - some other array (or, maybe, a reference to this array).
      srcIndex1 - the index of the minuend in src array.
      srcIndex2 - the index of the subtrahend in src array.

    • add

      public abstract void add(long destIndex, long srcIndex1, SampleArray src2, long srcIndex2)
      Description copied from interface: SampleArray
      Adds the sample #srcIndex2 of src2 array to the sample #srcIndex1 of this array and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex1 or srcIndex2, and src2 array can be a reference to this array: these situations are processed correctly.
      Specified by:
      add in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      srcIndex1 - the index of the first summand in this array.
      src2 - some other array (or, maybe, a reference to this array).
      srcIndex2 - the index of the second summand in src2 array.

    • sub

      public abstract void sub(long destIndex, long srcIndex1, SampleArray src2, long srcIndex2)
      Description copied from interface: SampleArray
      Subtracts the sample #srcIndex2 of src2 array from the sample #srcIndex1 of this array and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex1 or srcIndex2, and src2 array can be a reference to this array: these situations are processed correctly.
      Specified by:
      sub in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      srcIndex1 - the index of the minuend in this array.
      src2 - some other array (or, maybe, a reference to this array).
      srcIndex2 - the index of the subtrahend in src2 array.

    • add

      public abstract void add(long destIndex, long srcIndex1, long srcIndex2)
      Description copied from interface: SampleArray
      Adds the sample #srcIndex2 of this array to the sample #srcIndex1 of this array and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex1 or srcIndex2: these situations are processed correctly.
      Specified by:
      add in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      srcIndex1 - the index of the first summand in this array.
      srcIndex2 - the index of the second summand in this array.

    • sub

      public abstract void sub(long destIndex, long srcIndex1, long srcIndex2)
      Description copied from interface: SampleArray
      Subtracts the sample #srcIndex2 of this array from the sample #srcIndex1 of this array and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex1 or srcIndex2: these situations are processed correctly.
      Specified by:
      sub in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      srcIndex1 - the index of the minuend in this array.
      srcIndex2 - the index of the subtrahend in this array.

    • multiplyByScalar

      public abstract void multiplyByScalar(long destIndex, SampleArray src, long srcIndex, double aRe, double aIm)
      Description copied from interface: SampleArray
      Multiplies the sample #srcIndex of src array by the complex scalar aRe+aIm*i (i is the imaginary unit) and stores the result into position #destIndex of this array. The destIndex can be the same as srcIndex and src array can be a reference to this array: this situations is processed correctly.

      If this sample array consists of real samples (for example, real numbers or vectors of real numbers), then the imaginary part aIm is ignored.

      Specified by:
      multiplyByScalar in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      src - some other array (or, maybe, a reference to this array).
      srcIndex - the index of the sample in src array.
      aRe - the real part of the complex scalar.
      aIm - the imaginary part of the complex scalar.
      See Also:

    • multiplyByRealScalar

      public abstract void multiplyByRealScalar(long index, double a)
      Description copied from interface: SampleArray
      Multiplies the sample #destIndex of this array by the real scalar a and stores the result into the same position #destIndex of this array. Equivalent to multiplyByScalar(destIndex,thisInstance,destIndex,a,0.0).
      Specified by:
      multiplyByRealScalar in interface SampleArray
      Parameters:
      index - index of sample in this array.
      a - the real scalar.

    • combineWithRealMultipliers

      public abstract void combineWithRealMultipliers(long destIndex, long srcIndex1, double a1, long srcIndex2, double a2)
      Description copied from interface: SampleArray
      Multiplies the sample #srcIndex1 of this array by the real scalar a1, multiplies the sample #srcIndex2 of this array by the real scalar a2 and stores the sum of this two products result into position #destIndex of this array.
      Specified by:
      combineWithRealMultipliers in interface SampleArray
      Parameters:
      destIndex - index of sample in this array to store the result.
      srcIndex1 - the index of the first sample in this array.
      a1 - the multiplier for the first sample.
      srcIndex2 - the index of the second sample in this array.
      a2 - the multiplier for the second sample.

    • multiplyRangeByRealScalar

      public abstract void multiplyRangeByRealScalar(long from, long to, double a)
      Description copied from interface: SampleArray
      Multiplies the samples #fromIndex..toIndex-1 of this array by the real scalar a and stores the result into the same positions of this array. Equivalent to the loop of multiplyByRealScalar(index, a) for index=fromIndex,fromIndex+1,...,toIndex-1.
      Specified by:
      multiplyRangeByRealScalar in interface SampleArray
      Parameters:
      from - low index (inclusive) of elements to be multiplied.
      to - high index (exclusive) of elements to be multiplied.
      a - the real scalar.

    • toString

      public abstract String toString(String format, String separator, int maxStringLength)
      Description copied from interface: SampleArray
      Returns a string representation of this sample array as contatenated string representations of samples, separating by the given separator.

      If the samples are numbers (real or complex) or vectors of numbers, this method may use the format argument to clarify the format of numbers according the rules of String.format method. In other cases, this argument may be ignored.

      If the necessary string length exceeds maxStringLength characters, this method break concatenation after the element, which leads to exceeding this limit, and adds "..." instead of all further elements. So, the length of returning string will never be essentially larger than maxStringLength characters.

      If the passed array is empty, returns the empty string ("").

      Specified by:
      toString in interface SampleArray
      Parameters:
      format - format string for numeric samples.
      separator - the string used for separating elements.
      maxStringLength - the maximal allowed length of returned string (longer results are trunctated with adding "..." at the end).
      Returns:
      the string representations of all samples joined into one string.