Package org.hipparchus.linear

Class RealVector

  • Direct Known Subclasses:
    ArrayRealVector, SparseRealVector
    public abstract class RealVector
extends Object
    Class defining a real-valued vector with basic algebraic operations.

    vector element indexing is 0-based -- e.g., getEntry(0) returns the first element of the vector.

    The code map and mapToSelf methods operate on vectors element-wise, i.e. they perform the same operation (adding a scalar, applying a function ...) on each element in turn. The map versions create a new vector to hold the result and do not change the instance. The mapToSelf version uses the instance itself to store the results, so the instance is changed by this method. In all cases, the result vector is returned by the methods, allowing the fluent API style, like this: 

       RealVector result = v.mapAddToSelf(3.4).mapToSelf(new Tan()).mapToSelf(new Power(2.3));

    • Constructor Detail

      • RealVector

        public RealVector()
        Empty constructor.

        This constructor is not strictly necessary, but it prevents spurious javadoc warnings with JDK 18 and later.

        Since:
        3.0

    • Method Detail

      • getDimension

        public abstract int getDimension()
        Returns the size of the vector.
        Returns:
        the size of this vector.

      • addToEntry

        public void addToEntry​(int index,
                       double increment)
                throws MathIllegalArgumentException
        Change an entry at the specified index.
        Parameters:
        index - Index location of entry to be set.
        increment - Value to add to the vector entry.
        Throws:
        MathIllegalArgumentException - if the index is not valid.

      • append

        public abstract RealVector append​(RealVector v)
        Construct a new vector by appending a vector to this vector.
        Parameters:
        v - vector to append to this one.
        Returns:
        a new vector.

      • append

        public abstract RealVector append​(double d)
        Construct a new vector by appending a double to this vector.
        Parameters:
        d - double to append.
        Returns:
        a new vector.

      • isNaN

        public abstract boolean isNaN()
        Check whether any coordinate of this vector is NaN.
        Returns:
        true if any coordinate of this vector is NaN, false otherwise.

      • isInfinite

        public abstract boolean isInfinite()
        Check whether any coordinate of this vector is infinite and none are NaN.
        Returns:
        true if any coordinate of this vector is infinite and none are NaN, false otherwise.

      • checkVectorDimensions

        protected void checkVectorDimensions​(int n)
                              throws MathIllegalArgumentException
        Check if instance dimension is equal to some expected value.
        Parameters:
        n - Expected dimension.
        Throws:
        MathIllegalArgumentException - if the dimension is inconsistent with the vector size.

      • mapAdd

        public RealVector mapAdd​(double d)
        Add a value to each entry. Returns a new vector. Does not change instance data.
        Parameters:
        d - Value to be added to each entry.
        Returns:
        this + d.

      • mapAddToSelf

        public RealVector mapAddToSelf​(double d)
        Add a value to each entry. The instance is changed in-place.
        Parameters:
        d - Value to be added to each entry.
        Returns:
        this.

      • copy

        public abstract RealVector copy()
        Returns a (deep) copy of this vector.
        Returns:
        a vector copy.

      • dotProduct

        public double dotProduct​(RealVector v)
                  throws MathIllegalArgumentException
        Compute the dot product of this vector with v.
        Parameters:
        v - Vector with which dot product should be computed
        Returns:
        the scalar dot product between this instance and v.
        Throws:
        MathIllegalArgumentException - if v is not the same size as this vector.

      • getL1Distance

        public double getL1Distance​(RealVector v)
                     throws MathIllegalArgumentException
        Distance between two vectors.

        This method computes the distance consistent with L1 norm, i.e. the sum of the absolute values of the elements differences.

        Parameters:
        v - Vector to which distance is requested.
        Returns:
        the distance between two vectors.
        Throws:
        MathIllegalArgumentException - if v is not the same size as this vector.

      • getMinIndex

        public int getMinIndex()
        Get the index of the minimum entry.
        Returns:
        the index of the minimum entry or -1 if vector length is 0 or all entries are NaN.

      • getMinValue

        public double getMinValue()
        Get the value of the minimum entry.
        Returns:
        the value of the minimum entry or NaN if all entries are NaN.

      • getMaxIndex

        public int getMaxIndex()
        Get the index of the maximum entry.
        Returns:
        the index of the maximum entry or -1 if vector length is 0 or all entries are NaN

      • getMaxValue

        public double getMaxValue()
        Get the value of the maximum entry.
        Returns:
        the value of the maximum entry or NaN if all entries are NaN.

      • mapMultiply

        public RealVector mapMultiply​(double d)
        Multiply each entry by the argument. Returns a new vector. Does not change instance data.
        Parameters:
        d - Multiplication factor.
        Returns:
        this * d.

      • mapMultiplyToSelf

        public RealVector mapMultiplyToSelf​(double d)
        Multiply each entry. The instance is changed in-place.
        Parameters:
        d - Multiplication factor.
        Returns:
        this.

      • mapSubtract

        public RealVector mapSubtract​(double d)
        Subtract a value from each entry. Returns a new vector. Does not change instance data.
        Parameters:
        d - Value to be subtracted.
        Returns:
        this - d.

      • mapSubtractToSelf

        public RealVector mapSubtractToSelf​(double d)
        Subtract a value from each entry. The instance is changed in-place.
        Parameters:
        d - Value to be subtracted.
        Returns:
        this.

      • mapDivide

        public RealVector mapDivide​(double d)
        Divide each entry by the argument. Returns a new vector. Does not change instance data.
        Parameters:
        d - Value to divide by.
        Returns:
        this / d.

      • mapDivideToSelf

        public RealVector mapDivideToSelf​(double d)
        Divide each entry by the argument. The instance is changed in-place.
        Parameters:
        d - Value to divide by.
        Returns:
        this.

      • outerProduct

        public RealMatrix outerProduct​(RealVector v)
        Compute the outer product.
        Parameters:
        v - Vector with which outer product should be computed.
        Returns:
        the matrix outer product between this instance and v.

      • set

        public void set​(double value)
        Set all elements to a single value.
        Parameters:
        value - Single value to set for all elements.

      • toArray

        public double[] toArray()
        Convert the vector to an array of doubles. The array is independent from this vector data: the elements are copied.
        Returns:
        an array containing a copy of the vector elements.

      • unitVector

        public RealVector unitVector()
                      throws MathRuntimeException
        Creates a unit vector pointing in the direction of this vector. The instance is not changed by this method.
        Returns:
        a unit vector pointing in direction of this vector.
        Throws:
        MathRuntimeException - if the norm is zero.

      • unitize

        public void unitize()
             throws MathRuntimeException
        Converts this vector into a unit vector. The instance itself is changed by this method.
        Throws:
        MathRuntimeException - if the norm is zero.

      • sparseIterator

        public Iterator<RealVector.Entry> sparseIterator()
        Create a sparse iterator over the vector, which may omit some entries. The ommitted entries are either exact zeroes (for dense implementations) or are the entries which are not stored (for real sparse vectors). No guarantees are made about order of iteration.

        Note: derived classes are required to return an Iterator that returns non-null RealVector.Entry objects as long as Iterator.hasNext() returns true.

        Returns:
        a sparse iterator.

      • map

        public RealVector map​(UnivariateFunction function)
        Acts as if implemented as: 
          return copy().mapToSelf(function);
        Returns a new vector. Does not change instance data.
        Parameters:
        function - Function to apply to each entry.
        Returns:
        a new vector.

      • mapToSelf

        public RealVector mapToSelf​(UnivariateFunction function)
        Acts as if it is implemented as: 
          Entry e = null;
  for(Iterator<Entry> it = iterator(); it.hasNext(); e = it.next()) {
      e.setValue(function.value(e.getValue()));
  }
        Entries of this vector are modified in-place by this method.
        Parameters:
        function - Function to apply to each entry.
        Returns:
        a reference to this vector.

      • combine

        public RealVector combine​(double a,
                          double b,
                          RealVector y)
                   throws MathIllegalArgumentException
        Returns a new vector representing a * this + b * y, the linear combination of this and y. Returns a new vector. Does not change instance data.
        Parameters:
        a - Coefficient of this.
        b - Coefficient of y.
        y - Vector with which this is linearly combined.
        Returns:
        a vector containing a * this[i] + b * y[i] for all i.
        Throws:
        MathIllegalArgumentException - if y is not the same size as this vector.

      • combineToSelf

        public RealVector combineToSelf​(double a,
                                double b,
                                RealVector y)
                         throws MathIllegalArgumentException
        Updates this with the linear combination of this and y.
        Parameters:
        a - Weight of this.
        b - Weight of y.
        y - Vector with which this is linearly combined.
        Returns:
        this, with components equal to a * this[i] + b * y[i] for all i.
        Throws:
        MathIllegalArgumentException - if y is not the same size as this vector.

      • walkInDefaultOrder

        public double walkInDefaultOrder​(RealVectorPreservingVisitor visitor)
        Visits (but does not alter) all entries of this vector in default order (increasing index).
        Parameters:
        visitor - the visitor to be used to process the entries of this vector
        Returns:
        the value returned by RealVectorPreservingVisitor.end() at the end of the walk

      • walkInOptimizedOrder

        public double walkInOptimizedOrder​(RealVectorPreservingVisitor visitor)
        Visits (but does not alter) all entries of this vector in optimized order. The order in which the entries are visited is selected so as to lead to the most efficient implementation; it might depend on the concrete implementation of this abstract class.
        Parameters:
        visitor - the visitor to be used to process the entries of this vector
        Returns:
        the value returned by RealVectorPreservingVisitor.end() at the end of the walk

      • walkInOptimizedOrder

        public double walkInOptimizedOrder​(RealVectorPreservingVisitor visitor,
                                   int start,
                                   int end)
                            throws MathIllegalArgumentException
        Visits (but does not alter) some entries of this vector in optimized order. The order in which the entries are visited is selected so as to lead to the most efficient implementation; it might depend on the concrete implementation of this abstract class.
        Parameters:
        visitor - visitor to be used to process the entries of this vector
        start - the index of the first entry to be visited
        end - the index of the last entry to be visited (inclusive)
        Returns:
        the value returned by RealVectorPreservingVisitor.end() at the end of the walk
        Throws:
        MathIllegalArgumentException - if end < start.
        MathIllegalArgumentException - if the indices are not valid.

      • walkInDefaultOrder

        public double walkInDefaultOrder​(RealVectorChangingVisitor visitor)
        Visits (and possibly alters) all entries of this vector in default order (increasing index).
        Parameters:
        visitor - the visitor to be used to process and modify the entries of this vector
        Returns:
        the value returned by RealVectorChangingVisitor.end() at the end of the walk

      • walkInOptimizedOrder

        public double walkInOptimizedOrder​(RealVectorChangingVisitor visitor)
        Visits (and possibly alters) all entries of this vector in optimized order. The order in which the entries are visited is selected so as to lead to the most efficient implementation; it might depend on the concrete implementation of this abstract class.
        Parameters:
        visitor - the visitor to be used to process the entries of this vector
        Returns:
        the value returned by RealVectorChangingVisitor.end() at the end of the walk

      • walkInOptimizedOrder

        public double walkInOptimizedOrder​(RealVectorChangingVisitor visitor,
                                   int start,
                                   int end)
                            throws MathIllegalArgumentException
        Visits (and possibly change) some entries of this vector in optimized order. The order in which the entries are visited is selected so as to lead to the most efficient implementation; it might depend on the concrete implementation of this abstract class.
        Parameters:
        visitor - visitor to be used to process the entries of this vector
        start - the index of the first entry to be visited
        end - the index of the last entry to be visited (inclusive)
        Returns:
        the value returned by RealVectorChangingVisitor.end() at the end of the walk
        Throws:
        MathIllegalArgumentException - if end < start.
        MathIllegalArgumentException - if the indices are not valid.

      • equals

        public boolean equals​(Object other)
               throws MathRuntimeException

        Test for the equality of two real vectors. If all coordinates of two real vectors are exactly the same, and none are NaN, the two real vectors are considered to be equal. NaN coordinates are considered to affect globally the vector and be equals to each other - i.e, if either (or all) coordinates of the real vector are equal to NaN, the real vector is equal to a vector with all NaN coordinates.

        This method must be overriden by concrete subclasses of RealVector (the current implementation throws an exception).

        Overrides:
        equals in class Object
        Parameters:
        other - Object to test for equality.
        Returns:
        true if two vector objects are equal, false if other is null, not an instance of RealVector, or not equal to this RealVector instance.
        Throws:
        MathRuntimeException - if this method is not overridden.

      • unmodifiableRealVector

        public static RealVector unmodifiableRealVector​(RealVector v)
        Returns an unmodifiable view of the specified vector. The returned vector has read-only access. An attempt to modify it will result in a MathRuntimeException. However, the returned vector is not immutable, since any modification of v will also change the returned view. For example, in the following piece of code 
             RealVector v = new ArrayRealVector(2);
     RealVector w = RealVector.unmodifiableRealVector(v);
     v.setEntry(0, 1.2);
     v.setEntry(1, -3.4);
        the changes will be seen in the w view of v.
        Parameters:
        v - Vector for which an unmodifiable view is to be returned.
        Returns:
        an unmodifiable view of v.