Package ru.sscc.util.data

Collection of data access classes implementing such concepts as a data container, data vector, data pointer, and array of vectors.

See:
Description

Class Summary

ChainPointer	The implementation of RealPointer based on ChainVector.
ChainVector	Logically chains the array of objects convertible to the RealVector type as one RealVector instance.
DoubleContainer	An implementation of RealContainer based on double[] type vector.
DoubleIRefPointer	An implementation of RealPointer based on double[] type container indexed by int[] reference vector.
DoubleIRefVector	The implementation of RealVector vector based on double[] type container with indexing by int[] reference vector.
DoubleIRefVectors	An implementation of RealVectors based on double[] vector with indexing by int[] refence vector.
DoubleIVecPointer	An implementation of RealPointer for access to a component of vectors array based on double[] type container indexed by int[] reference vector.
DoubleIVecVector	The implementation of RealVector for access to a component of vectors array based on double[] type container indexed by int[] reference vector.
DoublePointer	An implementation of RealPointer based on double[] type container.
DoubleSRefPointer	An implementation of RealPointer based on double[] type container indexed by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
DoubleSRefVector	The implementation of RealVector vector based on double[] type container with indexing by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
DoubleSRefVectors	An implementation of RealVectors based on double[] vector with indexing by short[] refence vector (the sign bit of reference entries is considered as the numeric bit).
DoubleSVecPointer	An implementation of RealPointer for access to a component of vectors array based on double[] type container indexed by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
DoubleSVecVector	The implementation of RealVector vector for access to a component of vectors array based on double[] type container and indexed by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
DoubleVector	The implementation of RealVector vector based on double[] type container.
DoubleVectors	An implementation of RealVectors based on double[] vector.
FloatContainer	An implementation of RealContainer based on float[] type vector.
FloatIRefPointer	An implementation of RealPointer based on float[] type container indexed by int[] reference vector.
FloatIRefVector	An implementation of RealVector based on float[] type container with indexing by int[] reference vector.
FloatIRefVectors	An implementation of RealVectors based on float[] vector with indexing by int[] refence vector.
FloatIVecPointer	An implementation of RealPointer for access to a component of vectors array based on float[] type container indexed by int[] reference vector.
FloatIVecVector	The implementation of RealVector vector for access to a component of vectors array based on float[] type container indexed by int[] reference vector.
FloatPointer	An implementation of RealPointer based on float[] type container.
FloatSRefPointer	An implementation of RealPointer based on float[] type container indexed by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
FloatSRefVector	An implementation of RealVector based on float[] type container with indexing by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
FloatSRefVectors	An implementation of RealVectors based on float[] vector with indexing by short[] refence vector (the sign bit of reference entries is considered as the numeric bit).
FloatSVecPointer	An implementation of RealPointer for access to a component of vectors array based on float[] type container indexed by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
FloatSVecVector	The implementation of RealVector vector for access to a component of vectors array based on float[] type container and indexed by short[] reference vector (the sign bit of reference entries is considered as the numeric bit).
FloatVector	Implementation of RealVector based on float[] type container.
FloatVectors	An implementation of RealVectors based on float[] vector.
RealContainer	This abstract class implements Cloneable and Serializable interfaces for real data container which is an array of the float[] or double[] type.
RealMath	A collection of basic algebraic operations with real vectors.
RealPointer	An abstract implementation of the sequential access to the vector distributed within a real data container by the regular manner (for example, with the fixed distance between neighbouring entries).
RealPointers	An implementation of RealPointer based on RealVectors type container.
RealVector	An abstract implementation of a real data vector distributed within a real data container by the regular manner (for example, with the fixed distance between neighbouring entries).
RealVectors	An abstract class for access to vectors container.
SimplePointer	An implementation of simple RealPointer that every time points to one double value stored in it.

Package ru.sscc.util.data Description

Collection of data access classes implementing such concepts as a data container, data vector, data pointer, and array of vectors.

RealContainer, RealVector, and RealPointer

We begin with the RealContainer concept. Numerical data are usually stored in a float[] or double[] array which we call a data container. The RealContainer class and its subclasses encapsulate a data container and get unified access to its entries via get(i), set(i,value), add(i,value), and mul(i,value) methods (i is a zero based index and value is a value to modify). All these primitive methods return the new value of entry except the set method that returns exactly the same value as was passed in parameters.

A data container is useful for many purposes, for example as a matrix body container. To provide the efficiency of matrix decomposition and matrix by vector multiplication, many useful vector operations are implemented, for example, the inner product calculation (the inner product of two vectors is the sum of their per-component products).

The RealContainer class allows cloning and serialization operations.

The next abstraction is a data vector concept implemented by the RealVector class and its subclasses. A data vector is a subset of a data container. Its entries are indexed from zero. The package supports a number of storage methods in the container via subtypes of the RealVector type.

• Usually a data vector is stored in a container by a regular manner: starting from a certain container's entry with a constant increment step. In this case the real position of i-th vector entry in the container is calculated by the formula index + i * step where index is a position of the first entry and step is the increment step.

• More complicated case of a data vector is its irregular storage within a container. In this case a special reference vector may be used to point to vector's positions in the container and a data vector is defined as a subset of container entries which indices are extracted from a reference vector by a regular manner. The resulting position calculating formula is ref[index + i * step] where ref is a reference vector.

• The last case of a data vector storage corresponds to cutting a component out of a vectors array indexed through a reference vector. The position calculation formula is the following component + ref[index + i * step] * dimension where dimension is a vectors dimension and component is a component to cut out.

You can use all of this cases for a data vector with the float[] or double[] type container and the short[] or int[] type reference vector. You have the direct access to vector entries via get(i), set(i,value), add(i,value), and mul(i,value) operations. You can cut out a subvector from the vector (logically, not really) via subvector(index,step,length) operation (all these operations are supported by the RealContainer class also, but you must call the getVector method instead of the subvector).

An instance of the RealContainer type may move or shift the starting index of a vector created by it with the moveVector(vec,newStartIndex) and shiftVector(vec,increment) methods. In attempt to change the starting index of an alien vector, the IllegalArgumentException will be thrown. The container's ownership is tested by the following rules: the data type of the vector must correspond to the data type of the container, and the underlying array must be the same.

The RealVector class supports a number of service methods: assign a vector or constant or vector multiplied by a constant, add a vector multiplied by a factor, multiply by a constant, calculate inner product, weighted inner product, useful norms, and others.

The RealVector class permits serialization.

To access sequentially to RealVector entries, the RealPointer class may be used. Its subtypes support all RealVector subtypes. A number of pointer moving operations are implemented:

next()

moves the pointer to the next vector entry;

previous()

moves the pointer to the previous vector entry;

shift(i)

moves the pointer up to i vector entries;

invert()

inverts the pointer direction (changes the increment sign);

reset(index,step)

resets the position and the increment step of the pointer respectively to the vector that created the pointer.

All above mentioned operations return the pointer itself. So, you can use them in the header of the for statement and can write, for example,

pointer.next().next() The primitive operations get(), set(value), add(value), and mul(value) provide an access to the entry pointed by the pointer.

To get a RealPointer instance from a RealContainer or RealVector instance the getPointer operation in these classes is used. You can get a pointer by two manners: getPointer() returns a pointer to the beginning of the container or the vector with the unit increment in it; the getPointer(index,step) returns a pointer starting from index-th entry with the increment defined by the step. Note that in the case of a data vector the index and the step mean the initial index and the increment step in the vector, not in its container! So, the last operation is equivalent to

vector.getPointer().reset(index,step)

The RealPointer class is transient. It isn't serializable, but it supports cloning. The clone refers to the same vector as the original pointer.

As the RealPointer is a Java object, it is passed into Java methods by the reference. So, it's moving inside a method can cause the side effect. To remove the side effect (keep the incoming pointer unchanged) you can move the pointer back after the use, or clone the pointer by the clone() operation and modify the cloned pointer, or use save/restore methods: the save() operation returns the current pointer's index and step packed into the long value and the restore(saved) operation restores index and step by unpacking its long type argument.

All operations in this package dealing with the RealPointer type arguments have no side effect. They keep incoming pointers unchanged.

Two special subclasses, ChainVector and ChainPointer, provide the access to the chain of vectors considered as one composite vector.

Data conversions

We say that a type is convertible to another type if there exists an operation which performs such a conversion.

The float[] and double[] types are convertible to the RealContainer. To do this you can use the corresponding subtype constructors or call the static RealContainer's by(object) conversion method:

     RealContainer y = RealContainer.by(x);

Here x may be an instance of the float[], or double[], or RealContainer type. In the last case y will refer to the same instance as x.

All 3 previous types are convertible to the RealVector. You can receive RealVector from RealContainer using the getVector() method. You can also call the static RealVector's by(object) conversion method:

     RealVector y = RealVector.by(x);

where x may be an instance of the float[], or double[], or RealContainer, or RealVector type. In the last case y will refer to the same instance as x.

All 4 previous types are convertible to the RealPointer. You can use the getPointer operations in the RealContainer or RealVector classes. You can also call the static RealPointer's by(object) conversion method:

     RealPointer y = RealPointer.by(x);

where x may be an instance of the float[], or double[], or RealContainer, or RealVector, or RealPointer type. In the last case y will be a clone of x pointer (not the same object!).

There is an additional static method useful for creation of indexed vectors:

RealVector.by(data,ref)

It converts the pair consisting of instances of the double[] or float[] type and the int[] or short[] type to the corresponding RealVector's subtype.

RealVectors

The RealVectors class stands apart to the previous classes. It implements a concept of an array of vectors which are stored in a data container in the vector per vector order. The useful example of such an array is a set of points in a multidimensional space of independent variables. Logically, this is a 2D array with the dimension parameter defining the dimensionality of the vector space (a number of columns in the array) and the size parameter specifying a number of vectors (a number of rows in the array).

A random access to vectors via reference array is possible. In this case reference array entries contain vector indices in the container. To calculate a starting vector position from a vector index the multiplication on the dimension is applied.

The RealVectors class was performed at first to support the set of points concept. So, such operation as an Euclidian distance between two vectors is implemented. Exactly, these operation calculates a squared Euclidian distance between a vector within RealVectors and an external point.

You have the direct access to j-th component of i-th vector via the following primitive operations: get(i,j), set(i,j,value), add(i,j,value), and mul(i,j,value).

You can get i-th vector of RealVectors using getVector(i) operation (the operation returns a RealVector instance). You can also get a pointer to i-th vector by the getPointer(i) operation. You can also get j-th component of all vectors of a RealVectors instance by the getComponent(i) operation (the operation returns a RealVector instance). Finally, you can get a pointer by the getPointers() operation that considers the vectors array as one continuous vector with the natural ordering in it, e.g. the 0th vector goes first, then goes the 1th vector, then 2nd and so on, independently to the storages of the vectors in the underlying container.

Note that all these operations allow an access to the corresponding entries of vectors array and not create a new data container.

Finally we describe two static methods for creation of a vectors array:

RealVectors.by(data,dimension)

creates an instance of the RealVectors type on the float[] or double[] type data container which dimensionality is specified by the dimension variable and the size is defined as a container size divided by vectors dimension;

RealVectors.by(data,ref,dimension)

creates an instance of the RealVectors type on the float[] or double[] type data container with referencing by the int[] or short[] type ref array. A vectors dimensionality is specified by the dimension variable and a number of vectors is equal to the length of ref array.

The RealVectors class permits serialization.

RealMath

The RealMath class contains the large collection of useful static algebraic methods upon the double[], float[], and RealPointer instances. Many methods dealing with the RealPointer class are optimized in such a way to recognize pointers' types and select the direct calculation formulas without use of pointers if it is possible.