public abstract class ComplexVectorSampleArray extends java.lang.Object implements SampleArray
Array of samples, where each sample is a vector of complex numbers with some fixed length,
represented by an array of pairs of double values,
stored in two AlgART arrays UpdatablePNumberArray
.
These vectors correspond to ranges in these arrays, given with some fixed step.
Please use asSampleArray(MemoryModel, UpdatablePNumberArray, UpdatablePNumberArray, long, long, long)
method for creating instances of this class. Please use comments to this method for more details about storing
samples in two AlgART arrays.
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. There is the only exception: if the element type of the underlying AlgART arrays
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 threadsafe, but are threadcompatible and can may be synchronized manually if multithread access is necessary.
AlgART Laboratory 2007–2014
GUARANTEED_COMPATIBLE_SAMPLES_ARRAY_LENGTH
Modifier and Type  Method and 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 ComplexVectorSampleArray 
asSampleArray(MemoryModel memoryModel,
UpdatablePNumberArray samplesRe,
UpdatablePNumberArray samplesIm,
long vectorLength,
long vectorStep,
long length)
Returns a view of the specified pair of AlgART arrays as an array of complex 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.

boolean 
isComplex()
Returns true if the samples in this array are complex, false if they are real.

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

java.lang.String 
toString(java.lang.String format,
java.lang.String separator,
int maxStringLength)
Returns a string representation of this sample array as contatenated string representations of samples,
separating by the given separator.

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
multiplyRangeByRealScalar
public static ComplexVectorSampleArray asSampleArray(MemoryModel memoryModel, UpdatablePNumberArray samplesRe, UpdatablePNumberArray samplesIm, long vectorLength, long vectorStep, long length)
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 viceversa.
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 each vector sample, vectorLength, must be in range
0<=vectorLength<=vectorStep. Moreover, samplesRe and samplesIm
arrays must be long enough for storing length vectors with specified vectorStep:
memoryModel
 the memory model, which will be used, when necessary, by
newCompatibleSamplesArray(long)
method; may be null,
then SimpleMemoryModel
will be used.samplesRe
 the real parts of all samples.samplesIm
 the imaginary parts of all samples.vectorLength
 the length of each complex vector.vectorStep
 the step of storing vectors in samplesRe and samplesIm arrays.length
 the length of the returned sample array.java.lang.NullPointerException
 if samplesRe or samplesIm is null.java.lang.IllegalArgumentException
 if vectorLength<0, vectorStep<vectorLength,
length<0 or
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 samplesRe.elementType() or
samplesIm.elementType().public final boolean isComplex()
SampleArray
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.
isComplex
in interface SampleArray
public final long length()
SampleArray
length
in interface SampleArray
public abstract ComplexVectorSampleArray newCompatibleSamplesArray(long length)
SampleArray
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
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.
newCompatibleSamplesArray
in interface SampleArray
length
 the length of new sample array.public void copy(long destIndex, SampleArray src, long srcIndex)
SampleArray
copy
in interface SampleArray
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.public void swap(long firstIndex, long secondIndex)
SampleArray
swap
in interface SampleArray
firstIndex
 first index of sample to exchange.secondIndex
 second index of sample to exchange.public abstract void add(long destIndex, SampleArray src, long srcIndex1, long srcIndex2)
SampleArray
add
in interface SampleArray
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.public abstract void sub(long destIndex, SampleArray src, long srcIndex1, long srcIndex2)
SampleArray
sub
in interface SampleArray
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.public abstract void add(long destIndex, long srcIndex1, SampleArray src2, long srcIndex2)
SampleArray
add
in interface SampleArray
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.public abstract void sub(long destIndex, long srcIndex1, SampleArray src2, long srcIndex2)
SampleArray
sub
in interface SampleArray
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.public abstract void add(long destIndex, long srcIndex1, long srcIndex2)
SampleArray
add
in interface SampleArray
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.public abstract void sub(long destIndex, long srcIndex1, long srcIndex2)
SampleArray
sub
in interface SampleArray
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.public abstract void multiplyByScalar(long destIndex, SampleArray src, long srcIndex, double aRe, double aIm)
SampleArray
If this sample array consists of real samples (for example, real numbers or vectors of real numbers), then the imaginary part aIm is ignored.
multiplyByScalar
in interface SampleArray
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.SampleArray.isComplex()
public abstract void combineWithRealMultipliers(long destIndex, long srcIndex1, double a1, long srcIndex2, double a2)
SampleArray
combineWithRealMultipliers
in interface SampleArray
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.public abstract void multiplyByRealScalar(long index, double a)
SampleArray
multiplyByScalar
(destIndex,thisInstance,destIndex,a,0.0)multiplyByRealScalar
in interface SampleArray
index
 index of sample in this array.a
 the real scalar.public java.lang.String toString(java.lang.String format, java.lang.String separator, int maxStringLength)
SampleArray
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 ("").
toString
in interface SampleArray
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).