Package net.algart.matrices.spectra

Class RealVectorSampleArray

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

Array of samples, where each sample is a vector of real numbers with some fixed length, represented by an array of double values, stored in an AlgART arras UpdatablePNumberArray. These vectors correspond to ranges in this array, given with some fixed step.

Please use asSampleArray(MemoryModel, UpdatablePNumberArray, long, long, long) method for creating instances of this class. Please use comments to this method for more details about storing samples in an AlgART array.

All operations over samples (adding, subtracting, multiplying) are performed via corresponding operations over elements of the AlgART array. Elements of this array are interpreted as double values, as if they are read/written by PArray.getDouble(long) and UpdatablePArray.setDouble(long, double) methods. There is the only exception: if the element type of the underlying AlgART array is not float or double, and an operation leads to overflow (for example, we try to multiply a sample by the real scalar 1e10), then the results can differ from the results of the simplest code based on PArray.getDouble(long) and UpdatablePArray.setDouble(long, double) calls.

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

  • 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 RealVectorSampleArray
    asSampleArray(MemoryModel memoryModel, UpdatablePNumberArray samples, long vectorLength, long vectorStep, long length)
    Returns a view of the specified pair of AlgART arrays as an array of real vector 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.
    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.
    final 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 RealVectorSampleArray
    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.
    void
    swap(long firstIndex, long secondIndex)
    Swaps samples at positions #firstIndex and #secondIndex inside this array.
    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

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

    multiplyRangeByRealScalar

  • Method Details

    • asSampleArray

      public static RealVectorSampleArray asSampleArray(MemoryModel memoryModel, UpdatablePNumberArray samples, long vectorLength, long vectorStep, long length)
      Returns a view of the specified pair of AlgART arrays as an array of real vector samples. Real vectors are stored in the specified array samples. More precisely, the sample #k in the returned sample array is a vector of vectorLength real numbers, where the number #j is stored in the element #(k*vectorStep)+j of samples array.

      The returned sample array is backed by this AlgART array, so any changes of the samples in the returned array are reflected in this array, and vice-versa. More precisely, the returned sample array is backed by samples.asUnresizable(): if the passed arrays are resizable, posible future changes of its length will not affect behaviour of the returned sample array.

      The length of each vector sample, vectorLength, must be in range 0<=vectorLength<=vectorStep. Moreover, samples array must be long enough for storing length vectors with specified vectorStep: (length-1)*vectorStep+vectorLength <= samples.length().

      Parameters:
      memoryModel - the memory model, which will be used, when necessary, by newCompatibleSamplesArray(long) method; may be null, then SimpleMemoryModel will be used.
      samples - the samples.
      vectorLength - the length of each real vector.
      vectorStep - the step of storing vectors in samples array.
      length - the length of the returned sample array.
      Returns:
      the array of vector real samples, represented by corresponding ranges (subarrays) of this AlgART array.
      Throws:
      NullPointerException - if samples is null.
      IllegalArgumentException - if vectorLength<0, vectorStep<vectorLength, length<0 or (length-1)*vectorStep+vectorLength <= samples.length() (the last condition is checked mathematically accurately even if these values >Long.MAX_VALUE).
      TooLargeArrayException - (little probability) if the maximal length, supported by the specified memory model (or SimpleMemoryModel if memoryModel==null) is not enough for allocating SampleArray.GUARANTEED_COMPATIBLE_SAMPLES_ARRAY_LENGTH*vectorLength elements with the type samples.elementType().

    • 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 final 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 RealVectorSampleArray 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 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 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:

    • 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.

    • 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.

    • toString

      public 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.