/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.math3.linear;

import java.util.Iterator;
import java.util.NoSuchElementException;

import org.apache.commons.math3.exception.MathUnsupportedOperationException;
import org.apache.commons.math3.exception.DimensionMismatchException;
import org.apache.commons.math3.exception.NotPositiveException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.OutOfRangeException;
import org.apache.commons.math3.exception.MathArithmeticException;
import org.apache.commons.math3.analysis.FunctionUtils;
import org.apache.commons.math3.analysis.function.Add;
import org.apache.commons.math3.analysis.function.Multiply;
import org.apache.commons.math3.analysis.function.Divide;
import org.apache.commons.math3.analysis.UnivariateFunction;
import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.util.FastMath;

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));

Since:
2.1/**
 * Class defining a real-valued vector with basic algebraic operations.
 * <p>
 * vector element indexing is 0-based -- e.g., {@code getEntry(0)}
 * returns the first element of the vector.
 * </p>
 * <p>
 * The {@code code map} and {@code 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 {@code map}
 * versions create a new vector to hold the result and do not change the instance.
 * The {@code 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 <i>fluent API</i>
 * style, like this:
 * </p>
 * <pre>
 *   RealVector result = v.mapAddToSelf(3.4).mapToSelf(new Tan()).mapToSelf(new Power(2.3));
 * </pre>
 *
 * @since 2.1
 */
public abstract class RealVector {
    
Returns the size of the vector.
Returns:
the size of this vector./**
     * Returns the size of the vector.
     *
     * @return the size of this vector.
     */
    public abstract int getDimension();

    
Return the entry at the specified index.
Params:
index – Index location of entry to be fetched.
Throws:
OutOfRangeException – if the index is not valid.
See Also:
setEntry(int, double)
Returns:
the vector entry at index./**
     * Return the entry at the specified index.
     *
     * @param index Index location of entry to be fetched.
     * @return the vector entry at {@code index}.
     * @throws OutOfRangeException if the index is not valid.
     * @see #setEntry(int, double)
     */
    public abstract double getEntry(int index) throws OutOfRangeException;

    
Set a single element.
Params:
index – element index.
value – new value for the element.
Throws:
OutOfRangeException – if the index is not valid.
See Also:
getEntry(int)/**
     * Set a single element.
     *
     * @param index element index.
     * @param value new value for the element.
     * @throws OutOfRangeException if the index is not valid.
     * @see #getEntry(int)
     */
    public abstract void setEntry(int index, double value)
        throws OutOfRangeException;

    
Change an entry at the specified index.
Params:
index – Index location of entry to be set.
increment – Value to add to the vector entry.
Throws:
OutOfRangeException – if the index is not valid.
Since:
3.0/**
     * Change an entry at the specified index.
     *
     * @param index Index location of entry to be set.
     * @param increment Value to add to the vector entry.
     * @throws OutOfRangeException if the index is not valid.
     * @since 3.0
     */
    public void addToEntry(int index, double increment)
        throws OutOfRangeException {
        setEntry(index, getEntry(index) + increment);
    }

    
Construct a new vector by appending a vector to this vector.
Params:
v – vector to append to this one.
Returns:
a new vector./**
     * Construct a new vector by appending a vector to this vector.
     *
     * @param v vector to append to this one.
     * @return a new vector.
     */
    public abstract RealVector append(RealVector v);

    
Construct a new vector by appending a double to this vector.
Params:
d – double to append.
Returns:
a new vector./**
     * Construct a new vector by appending a double to this vector.
     *
     * @param d double to append.
     * @return a new vector.
     */
    public abstract RealVector append(double d);

    
Get a subvector from consecutive elements.
Params:
index – index of first element.
n – number of elements to be retrieved.
Throws:
OutOfRangeException – if the index is not valid.
NotPositiveException – if the number of elements is not positive.
Returns:
a vector containing n elements./**
     * Get a subvector from consecutive elements.
     *
     * @param index index of first element.
     * @param n number of elements to be retrieved.
     * @return a vector containing n elements.
     * @throws OutOfRangeException if the index is not valid.
     * @throws NotPositiveException if the number of elements is not positive.
     */
    public abstract RealVector getSubVector(int index, int n)
        throws NotPositiveException, OutOfRangeException;

    
Set a sequence of consecutive elements.
Params:
index – index of first element to be set.
v – vector containing the values to set.
Throws:
OutOfRangeException – if the index is not valid./**
     * Set a sequence of consecutive elements.
     *
     * @param index index of first element to be set.
     * @param v vector containing the values to set.
     * @throws OutOfRangeException if the index is not valid.
     */
    public abstract void setSubVector(int index, RealVector v)
        throws OutOfRangeException;

    
Check whether any coordinate of this vector is NaN. 
Returns:
true if any coordinate of this vector is NaN, false otherwise./**
     * Check whether any coordinate of this vector is {@code NaN}.
     *
     * @return {@code true} if any coordinate of this vector is {@code NaN},
     * {@code false} otherwise.
     */
    public abstract boolean isNaN();

    
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./**
     * Check whether any coordinate of this vector is infinite and none are {@code NaN}.
     *
     * @return {@code true} if any coordinate of this vector is infinite and
     * none are {@code NaN}, {@code false} otherwise.
     */
    public abstract boolean isInfinite();

    
Check if instance and specified vectors have the same dimension.
Params:
v – Vector to compare instance with.
Throws:
DimensionMismatchException – if the vectors do not
have the same dimension./**
     * Check if instance and specified vectors have the same dimension.
     *
     * @param v Vector to compare instance with.
     * @throws DimensionMismatchException if the vectors do not
     * have the same dimension.
     */
    protected void checkVectorDimensions(RealVector v)
        throws DimensionMismatchException {
        checkVectorDimensions(v.getDimension());
    }

    
Check if instance dimension is equal to some expected value.
Params:
n – Expected dimension.
Throws:
DimensionMismatchException – if the dimension is
inconsistent with the vector size./**
     * Check if instance dimension is equal to some expected value.
     *
     * @param n Expected dimension.
     * @throws DimensionMismatchException if the dimension is
     * inconsistent with the vector size.
     */
    protected void checkVectorDimensions(int n)
        throws DimensionMismatchException {
        int d = getDimension();
        if (d != n) {
            throw new DimensionMismatchException(d, n);
        }
    }

    
Check if an index is valid.
Params:
index – Index to check.
Throws:
OutOfRangeException – if index is not valid./**
     * Check if an index is valid.
     *
     * @param index Index to check.
     * @exception OutOfRangeException if {@code index} is not valid.
     */
    protected void checkIndex(final int index) throws OutOfRangeException {
        if (index < 0 ||
            index >= getDimension()) {
            throw new OutOfRangeException(LocalizedFormats.INDEX,
                                          index, 0, getDimension() - 1);
        }
    }

    
Checks that the indices of a subvector are valid.
Params:
start – the index of the first entry of the subvector
end – the index of the last entry of the subvector (inclusive)
Throws:
OutOfRangeException – if start of end are not valid
NumberIsTooSmallException – if end < start
Since:
3.1/**
     * Checks that the indices of a subvector are valid.
     *
     * @param start the index of the first entry of the subvector
     * @param end the index of the last entry of the subvector (inclusive)
     * @throws OutOfRangeException if {@code start} of {@code end} are not valid
     * @throws NumberIsTooSmallException if {@code end < start}
     * @since 3.1
     */
    protected void checkIndices(final int start, final int end)
        throws NumberIsTooSmallException, OutOfRangeException {
        final int dim = getDimension();
        if ((start < 0) || (start >= dim)) {
            throw new OutOfRangeException(LocalizedFormats.INDEX, start, 0,
                                          dim - 1);
        }
        if ((end < 0) || (end >= dim)) {
            throw new OutOfRangeException(LocalizedFormats.INDEX, end, 0,
                                          dim - 1);
        }
        if (end < start) {
            // TODO Use more specific error message
            throw new NumberIsTooSmallException(LocalizedFormats.INITIAL_ROW_AFTER_FINAL_ROW,
                                                end, start, false);
        }
    }

    
Compute the sum of this vector and v. Returns a new vector. Does not change instance data. 
Params:
v – Vector to be added.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
Returns:
this + v./**
     * Compute the sum of this vector and {@code v}.
     * Returns a new vector. Does not change instance data.
     *
     * @param v Vector to be added.
     * @return {@code this} + {@code v}.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     */
    public RealVector add(RealVector v) throws DimensionMismatchException {
        checkVectorDimensions(v);
        RealVector result = v.copy();
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            final int index = e.getIndex();
            result.setEntry(index, e.getValue() + result.getEntry(index));
        }
        return result;
    }

    
Subtract v from this vector. Returns a new vector. Does not change instance data. 
Params:
v – Vector to be subtracted.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
Returns:
this - v./**
     * Subtract {@code v} from this vector.
     * Returns a new vector. Does not change instance data.
     *
     * @param v Vector to be subtracted.
     * @return {@code this} - {@code v}.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     */
    public RealVector subtract(RealVector v) throws DimensionMismatchException {
        checkVectorDimensions(v);
        RealVector result = v.mapMultiply(-1d);
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            final int index = e.getIndex();
            result.setEntry(index, e.getValue() + result.getEntry(index));
        }
        return result;
    }

    
Add a value to each entry.
Returns a new vector. Does not change instance data.
Params:
d – Value to be added to each entry.
Returns:
this + d./**
     * Add a value to each entry.
     * Returns a new vector. Does not change instance data.
     *
     * @param d Value to be added to each entry.
     * @return {@code this} + {@code d}.
     */
    public RealVector mapAdd(double d) {
        return copy().mapAddToSelf(d);
    }

    
Add a value to each entry.
The instance is changed in-place.
Params:
d – Value to be added to each entry.
Returns:
this./**
     * Add a value to each entry.
     * The instance is changed in-place.
     *
     * @param d Value to be added to each entry.
     * @return {@code this}.
     */
    public RealVector mapAddToSelf(double d) {
        if (d != 0) {
            return mapToSelf(FunctionUtils.fix2ndArgument(new Add(), d));
        }
        return this;
    }

    
Returns a (deep) copy of this vector.
Returns:
a vector copy./**
     * Returns a (deep) copy of this vector.
     *
     * @return a vector copy.
     */
    public abstract RealVector copy();

    
Compute the dot product of this vector with v. 
Params:
v – Vector with which dot product should be computed
Throws:
DimensionMismatchException – if v is not the same size as this vector.
Returns:
the scalar dot product between this instance and v./**
     * Compute the dot product of this vector with {@code v}.
     *
     * @param v Vector with which dot product should be computed
     * @return the scalar dot product between this instance and {@code v}.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     */
    public double dotProduct(RealVector v) throws DimensionMismatchException {
        checkVectorDimensions(v);
        double d = 0;
        final int n = getDimension();
        for (int i = 0; i < n; i++) {
            d += getEntry(i) * v.getEntry(i);
        }
        return d;
    }

    
Computes the cosine of the angle between this vector and the
argument.
Params:
v – Vector.
Throws:
MathArithmeticException – if this or v is the null vector
DimensionMismatchException – if the dimensions of this and v do not match
Returns:
the cosine of the angle between this vector and v./**
     * Computes the cosine of the angle between this vector and the
     * argument.
     *
     * @param v Vector.
     * @return the cosine of the angle between this vector and {@code v}.
     * @throws MathArithmeticException if {@code this} or {@code v} is the null
     * vector
     * @throws DimensionMismatchException if the dimensions of {@code this} and
     * {@code v} do not match
     */
    public double cosine(RealVector v) throws DimensionMismatchException,
        MathArithmeticException {
        final double norm = getNorm();
        final double vNorm = v.getNorm();

        if (norm == 0 ||
            vNorm == 0) {
            throw new MathArithmeticException(LocalizedFormats.ZERO_NORM);
        }
        return dotProduct(v) / (norm * vNorm);
    }

    
Element-by-element division.
Params:
v – Vector by which instance elements must be divided.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
Returns:
a vector containing this[i] / v[i] for all i./**
     * Element-by-element division.
     *
     * @param v Vector by which instance elements must be divided.
     * @return a vector containing this[i] / v[i] for all i.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     */
    public abstract RealVector ebeDivide(RealVector v)
        throws DimensionMismatchException;

    
Element-by-element multiplication.
Params:
v – Vector by which instance elements must be multiplied
Throws:
DimensionMismatchException – if v is not the same size as this vector.
Returns:
a vector containing this[i] * v[i] for all i./**
     * Element-by-element multiplication.
     *
     * @param v Vector by which instance elements must be multiplied
     * @return a vector containing this[i] * v[i] for all i.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     */
    public abstract RealVector ebeMultiply(RealVector v)
        throws DimensionMismatchException;

    
Distance between two vectors.
This method computes the distance consistent with the
L2 norm, i.e. the square root of the sum of
element differences, or Euclidean distance.
Params:
v – Vector to which distance is requested.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
See Also:
getL1Distance(RealVector)
getLInfDistance(RealVector)
getNorm()
Returns:
the distance between two vectors./**
     * Distance between two vectors.
     * <p>This method computes the distance consistent with the
     * L<sub>2</sub> norm, i.e. the square root of the sum of
     * element differences, or Euclidean distance.</p>
     *
     * @param v Vector to which distance is requested.
     * @return the distance between two vectors.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     * @see #getL1Distance(RealVector)
     * @see #getLInfDistance(RealVector)
     * @see #getNorm()
     */
    public double getDistance(RealVector v) throws DimensionMismatchException {
        checkVectorDimensions(v);
        double d = 0;
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            final double diff = e.getValue() - v.getEntry(e.getIndex());
            d += diff * diff;
        }
        return FastMath.sqrt(d);
    }

    
Returns the L2 norm of the vector.
The L2 norm is the root of the sum of
the squared elements.
See Also:
getL1Norm()
getLInfNorm()
getDistance(RealVector)
Returns:
the norm./**
     * Returns the L<sub>2</sub> norm of the vector.
     * <p>The L<sub>2</sub> norm is the root of the sum of
     * the squared elements.</p>
     *
     * @return the norm.
     * @see #getL1Norm()
     * @see #getLInfNorm()
     * @see #getDistance(RealVector)
     */
    public double getNorm() {
        double sum = 0;
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            final double value = e.getValue();
            sum += value * value;
        }
        return FastMath.sqrt(sum);
    }

    
Returns the L1 norm of the vector.
The L1 norm is the sum of the absolute
values of the elements.
See Also:
getNorm()
getLInfNorm()
getL1Distance(RealVector)
Returns:
the norm./**
     * Returns the L<sub>1</sub> norm of the vector.
     * <p>The L<sub>1</sub> norm is the sum of the absolute
     * values of the elements.</p>
     *
     * @return the norm.
     * @see #getNorm()
     * @see #getLInfNorm()
     * @see #getL1Distance(RealVector)
     */
    public double getL1Norm() {
        double norm = 0;
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            norm += FastMath.abs(e.getValue());
        }
        return norm;
    }

    
Returns the L∞ norm of the vector.
The L∞ norm is the max of the absolute
values of the elements.
See Also:
getNorm()
getL1Norm()
getLInfDistance(RealVector)
Returns:
the norm./**
     * Returns the L<sub>&infin;</sub> norm of the vector.
     * <p>The L<sub>&infin;</sub> norm is the max of the absolute
     * values of the elements.</p>
     *
     * @return the norm.
     * @see #getNorm()
     * @see #getL1Norm()
     * @see #getLInfDistance(RealVector)
     */
    public double getLInfNorm() {
        double norm = 0;
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            norm = FastMath.max(norm, FastMath.abs(e.getValue()));
        }
        return norm;
    }

    
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.
Params:
v – Vector to which distance is requested.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
Returns:
the distance between two vectors./**
     * Distance between two vectors.
     * <p>This method computes the distance consistent with
     * L<sub>1</sub> norm, i.e. the sum of the absolute values of
     * the elements differences.</p>
     *
     * @param v Vector to which distance is requested.
     * @return the distance between two vectors.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     */
    public double getL1Distance(RealVector v)
        throws DimensionMismatchException {
        checkVectorDimensions(v);
        double d = 0;
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            d += FastMath.abs(e.getValue() - v.getEntry(e.getIndex()));
        }
        return d;
    }

    
Distance between two vectors.
This method computes the distance consistent with
L∞ norm, i.e. the max of the absolute values of
element differences.
Params:
v – Vector to which distance is requested.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
See Also:
getDistance(RealVector)
getL1Distance(RealVector)
getLInfNorm()
Returns:
the distance between two vectors./**
     * Distance between two vectors.
     * <p>This method computes the distance consistent with
     * L<sub>&infin;</sub> norm, i.e. the max of the absolute values of
     * element differences.</p>
     *
     * @param v Vector to which distance is requested.
     * @return the distance between two vectors.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     * @see #getDistance(RealVector)
     * @see #getL1Distance(RealVector)
     * @see #getLInfNorm()
     */
    public double getLInfDistance(RealVector v)
        throws DimensionMismatchException {
        checkVectorDimensions(v);
        double d = 0;
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            d = FastMath.max(FastMath.abs(e.getValue() - v.getEntry(e.getIndex())), d);
        }
        return d;
    }

    
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./**
     * Get the index of the minimum entry.
     *
     * @return the index of the minimum entry or -1 if vector length is 0
     * or all entries are {@code NaN}.
     */
    public int getMinIndex() {
        int minIndex    = -1;
        double minValue = Double.POSITIVE_INFINITY;
        Iterator<Entry> iterator = iterator();
        while (iterator.hasNext()) {
            final Entry entry = iterator.next();
            if (entry.getValue() <= minValue) {
                minIndex = entry.getIndex();
                minValue = entry.getValue();
            }
        }
        return minIndex;
    }

    
Get the value of the minimum entry.
Returns:
the value of the minimum entry or NaN if all entries are NaN./**
     * Get the value of the minimum entry.
     *
     * @return the value of the minimum entry or {@code NaN} if all
     * entries are {@code NaN}.
     */
    public double getMinValue() {
        final int minIndex = getMinIndex();
        return minIndex < 0 ? Double.NaN : getEntry(minIndex);
    }

    
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/**
     * Get the index of the maximum entry.
     *
     * @return the index of the maximum entry or -1 if vector length is 0
     * or all entries are {@code NaN}
     */
    public int getMaxIndex() {
        int maxIndex    = -1;
        double maxValue = Double.NEGATIVE_INFINITY;
        Iterator<Entry> iterator = iterator();
        while (iterator.hasNext()) {
            final Entry entry = iterator.next();
            if (entry.getValue() >= maxValue) {
                maxIndex = entry.getIndex();
                maxValue = entry.getValue();
            }
        }
        return maxIndex;
    }

    
Get the value of the maximum entry.
Returns:
the value of the maximum entry or NaN if all entries are NaN./**
     * Get the value of the maximum entry.
     *
     * @return the value of the maximum entry or {@code NaN} if all
     * entries are {@code NaN}.
     */
    public double getMaxValue() {
        final int maxIndex = getMaxIndex();
        return maxIndex < 0 ? Double.NaN : getEntry(maxIndex);
    }


    
Multiply each entry by the argument. Returns a new vector.
Does not change instance data.
Params:
d – Multiplication factor.
Returns:
this * d./**
     * Multiply each entry by the argument. Returns a new vector.
     * Does not change instance data.
     *
     * @param d Multiplication factor.
     * @return {@code this} * {@code d}.
     */
    public RealVector mapMultiply(double d) {
        return copy().mapMultiplyToSelf(d);
    }

    
Multiply each entry.
The instance is changed in-place.
Params:
d – Multiplication factor.
Returns:
this./**
     * Multiply each entry.
     * The instance is changed in-place.
     *
     * @param d Multiplication factor.
     * @return {@code this}.
     */
    public RealVector mapMultiplyToSelf(double d){
        return mapToSelf(FunctionUtils.fix2ndArgument(new Multiply(), d));
    }

    
Subtract a value from each entry. Returns a new vector.
Does not change instance data.
Params:
d – Value to be subtracted.
Returns:
this - d./**
     * Subtract a value from each entry. Returns a new vector.
     * Does not change instance data.
     *
     * @param d Value to be subtracted.
     * @return {@code this} - {@code d}.
     */
    public RealVector mapSubtract(double d) {
        return copy().mapSubtractToSelf(d);
    }

    
Subtract a value from each entry.
The instance is changed in-place.
Params:
d – Value to be subtracted.
Returns:
this./**
     * Subtract a value from each entry.
     * The instance is changed in-place.
     *
     * @param d Value to be subtracted.
     * @return {@code this}.
     */
    public RealVector mapSubtractToSelf(double d){
        return mapAddToSelf(-d);
    }

    
Divide each entry by the argument. Returns a new vector.
Does not change instance data.
Params:
d – Value to divide by.
Returns:
this / d./**
     * Divide each entry by the argument. Returns a new vector.
     * Does not change instance data.
     *
     * @param d Value to divide by.
     * @return {@code this} / {@code d}.
     */
    public RealVector mapDivide(double d) {
        return copy().mapDivideToSelf(d);
    }

    
Divide each entry by the argument.
The instance is changed in-place.
Params:
d – Value to divide by.
Returns:
this./**
     * Divide each entry by the argument.
     * The instance is changed in-place.
     *
     * @param d Value to divide by.
     * @return {@code this}.
     */
    public RealVector mapDivideToSelf(double d){
        return mapToSelf(FunctionUtils.fix2ndArgument(new Divide(), d));
    }

    
Compute the outer product.
Params:
v – Vector with which outer product should be computed.
Returns:
the matrix outer product between this instance and v./**
     * Compute the outer product.
     *
     * @param v Vector with which outer product should be computed.
     * @return the matrix outer product between this instance and {@code v}.
     */
    public RealMatrix outerProduct(RealVector v) {
        final int m = this.getDimension();
        final int n = v.getDimension();
        final RealMatrix product;
        if (v instanceof SparseRealVector || this instanceof SparseRealVector) {
            product = new OpenMapRealMatrix(m, n);
        } else {
            product = new Array2DRowRealMatrix(m, n);
        }
        for (int i = 0; i < m; i++) {
            for (int j = 0; j < n; j++) {
                product.setEntry(i, j, this.getEntry(i) * v.getEntry(j));
            }
        }
        return product;
    }

    
Find the orthogonal projection of this vector onto another vector.
Params:
v – vector onto which instance must be projected.
Throws:
DimensionMismatchException – if v is not the same size as this vector.
MathArithmeticException – if this or v is the null vector
Returns:
projection of the instance onto v./**
     * Find the orthogonal projection of this vector onto another vector.
     *
     * @param v vector onto which instance must be projected.
     * @return projection of the instance onto {@code v}.
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this} vector.
     * @throws MathArithmeticException if {@code this} or {@code v} is the null
     * vector
     */
    public RealVector projection(final RealVector v)
        throws DimensionMismatchException, MathArithmeticException {
        final double norm2 = v.dotProduct(v);
        if (norm2 == 0.0) {
            throw new MathArithmeticException(LocalizedFormats.ZERO_NORM);
        }
        return v.mapMultiply(dotProduct(v) / v.dotProduct(v));
    }

    
Set all elements to a single value.
Params:
value – Single value to set for all elements./**
     * Set all elements to a single value.
     *
     * @param value Single value to set for all elements.
     */
    public void set(double value) {
        Iterator<Entry> it = iterator();
        while (it.hasNext()) {
            final Entry e = it.next();
            e.setValue(value);
        }
    }

    
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./**
     * Convert the vector to an array of {@code double}s.
     * The array is independent from this vector data: the elements
     * are copied.
     *
     * @return an array containing a copy of the vector elements.
     */
    public double[] toArray() {
        int dim = getDimension();
        double[] values = new double[dim];
        for (int i = 0; i < dim; i++) {
            values[i] = getEntry(i);
        }
        return values;
    }

    
Creates a unit vector pointing in the direction of this vector.
The instance is not changed by this method.
Throws:
MathArithmeticException – if the norm is zero.
Returns:
a unit vector pointing in direction of this vector./**
     * Creates a unit vector pointing in the direction of this vector.
     * The instance is not changed by this method.
     *
     * @return a unit vector pointing in direction of this vector.
     * @throws MathArithmeticException if the norm is zero.
     */
    public RealVector unitVector() throws MathArithmeticException {
        final double norm = getNorm();
        if (norm == 0) {
            throw new MathArithmeticException(LocalizedFormats.ZERO_NORM);
        }
        return mapDivide(norm);
    }

    
Converts this vector into a unit vector.
The instance itself is changed by this method.
Throws:
MathArithmeticException – if the norm is zero./**
     * Converts this vector into a unit vector.
     * The instance itself is changed by this method.
     *
     * @throws MathArithmeticException if the norm is zero.
     */
    public void unitize() throws MathArithmeticException {
        final double norm = getNorm();
        if (norm == 0) {
            throw new MathArithmeticException(LocalizedFormats.ZERO_NORM);
        }
        mapDivideToSelf(getNorm());
    }

    
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 Entry objects as long as Iterator.hasNext() returns true.
Returns:
a sparse iterator./**
     * 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.
     *
     * <p>Note: derived classes are required to return an {@link Iterator} that
     * returns non-null {@link Entry} objects as long as {@link Iterator#hasNext()}
     * returns {@code true}.</p>
     *
     * @return a sparse iterator.
     */
    public Iterator<Entry> sparseIterator() {
        return new SparseEntryIterator();
    }

    
Generic dense iterator. Iteration is in increasing order
of the vector index.
Note: derived classes are required to return an Iterator that returns non-null Entry objects as long as Iterator.hasNext() returns true.
Returns:
a dense iterator./**
     * Generic dense iterator. Iteration is in increasing order
     * of the vector index.
     *
     * <p>Note: derived classes are required to return an {@link Iterator} that
     * returns non-null {@link Entry} objects as long as {@link Iterator#hasNext()}
     * returns {@code true}.</p>
     *
     * @return a dense iterator.
     */
    public Iterator<Entry> iterator() {
        final int dim = getDimension();
        return new Iterator<Entry>() {

            
Current index. /** Current index. */
            private int i = 0;

            
Current entry. /** Current entry. */
            private Entry e = new Entry();

            
{@inheritDoc} /** {@inheritDoc} */
            public boolean hasNext() {
                return i < dim;
            }

            
{@inheritDoc} /** {@inheritDoc} */
            public Entry next() {
                if (i < dim) {
                    e.setIndex(i++);
                    return e;
                } else {
                    throw new NoSuchElementException();
                }
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all circumstances.
             */
            public void remove() throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }
        };
    }

    
Acts as if implemented as:
 return copy().mapToSelf(function);

Returns a new vector. Does not change instance data.
Params:
function – Function to apply to each entry.
Returns:
a new vector./**
     * Acts as if implemented as:
     * <pre>
     *  return copy().mapToSelf(function);
     * </pre>
     * Returns a new vector. Does not change instance data.
     *
     * @param function Function to apply to each entry.
     * @return a new vector.
     */
    public RealVector map(UnivariateFunction function) {
        return copy().mapToSelf(function);
    }

    
Acts as if it is implemented as:
 Entry e = null;
 for(Iterator it = iterator(); it.hasNext(); e = it.next()) {
     e.setValue(function.value(e.getValue()));
 }

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

    
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. 
Params:
a – Coefficient of this.
b – Coefficient of y.
y – Vector with which this is linearly combined.
Throws:
DimensionMismatchException – if y is not the same size as this vector.
Returns:
a vector containing a * this[i] + b * y[i] for all i./**
     * Returns a new vector representing {@code a * this + b * y}, the linear
     * combination of {@code this} and {@code y}.
     * Returns a new vector. Does not change instance data.
     *
     * @param a Coefficient of {@code this}.
     * @param b Coefficient of {@code y}.
     * @param y Vector with which {@code this} is linearly combined.
     * @return a vector containing {@code a * this[i] + b * y[i]} for all
     * {@code i}.
     * @throws DimensionMismatchException if {@code y} is not the same size as
     * {@code this} vector.
     */
    public RealVector combine(double a, double b, RealVector y)
        throws DimensionMismatchException {
        return copy().combineToSelf(a, b, y);
    }

    
Updates this with the linear combination of this and y. 
Params:
a – Weight of this.
b – Weight of y.
y – Vector with which this is linearly combined.
Throws:
DimensionMismatchException – if y is not the same size as this vector.
Returns:
this, with components equal to a * this[i] + b * y[i] for all i./**
     * Updates {@code this} with the linear combination of {@code this} and
     * {@code y}.
     *
     * @param a Weight of {@code this}.
     * @param b Weight of {@code y}.
     * @param y Vector with which {@code this} is linearly combined.
     * @return {@code this}, with components equal to
     * {@code a * this[i] + b * y[i]} for all {@code i}.
     * @throws DimensionMismatchException if {@code y} is not the same size as
     * {@code this} vector.
     */
    public RealVector combineToSelf(double a, double b, RealVector y)
        throws DimensionMismatchException {
        checkVectorDimensions(y);
        for (int i = 0; i < getDimension(); i++) {
            final double xi = getEntry(i);
            final double yi = y.getEntry(i);
            setEntry(i, a * xi + b * yi);
        }
        return this;
    }

    
Visits (but does not alter) all entries of this vector in default order
(increasing index).
Params:
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
Since:
3.1/**
     * Visits (but does not alter) all entries of this vector in default order
     * (increasing index).
     *
     * @param visitor the visitor to be used to process the entries of this
     * vector
     * @return the value returned by {@link RealVectorPreservingVisitor#end()}
     * at the end of the walk
     * @since 3.1
     */
    public double walkInDefaultOrder(final RealVectorPreservingVisitor visitor) {
        final int dim = getDimension();
        visitor.start(dim, 0, dim - 1);
        for (int i = 0; i < dim; i++) {
            visitor.visit(i, getEntry(i));
        }
        return visitor.end();
    }

    
Visits (but does not alter) some entries of this vector in default order
(increasing index).
Params:
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)
Throws:
NumberIsTooSmallException – if end < start.
OutOfRangeException – if the indices are not valid.
Returns:
the value returned by RealVectorPreservingVisitor.end() at the end of the walk
Since:
3.1/**
     * Visits (but does not alter) some entries of this vector in default order
     * (increasing index).
     *
     * @param visitor visitor to be used to process the entries of this vector
     * @param start the index of the first entry to be visited
     * @param end the index of the last entry to be visited (inclusive)
     * @return the value returned by {@link RealVectorPreservingVisitor#end()}
     * at the end of the walk
     * @throws NumberIsTooSmallException if {@code end < start}.
     * @throws OutOfRangeException if the indices are not valid.
     * @since 3.1
     */
    public double walkInDefaultOrder(final RealVectorPreservingVisitor visitor,
                                     final int start, final int end)
        throws NumberIsTooSmallException, OutOfRangeException {
        checkIndices(start, end);
        visitor.start(getDimension(), start, end);
        for (int i = start; i <= end; i++) {
            visitor.visit(i, getEntry(i));
        }
        return visitor.end();
    }

    
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.
Params:
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
Since:
3.1/**
     * 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.
     *
     * @param visitor the visitor to be used to process the entries of this
     * vector
     * @return the value returned by {@link RealVectorPreservingVisitor#end()}
     * at the end of the walk
     * @since 3.1
     */
    public double walkInOptimizedOrder(final RealVectorPreservingVisitor visitor) {
        return walkInDefaultOrder(visitor);
    }

    
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.
Params:
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)
Throws:
NumberIsTooSmallException – if end < start.
OutOfRangeException – if the indices are not valid.
Returns:
the value returned by RealVectorPreservingVisitor.end() at the end of the walk
Since:
3.1/**
     * 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.
     *
     * @param visitor visitor to be used to process the entries of this vector
     * @param start the index of the first entry to be visited
     * @param end the index of the last entry to be visited (inclusive)
     * @return the value returned by {@link RealVectorPreservingVisitor#end()}
     * at the end of the walk
     * @throws NumberIsTooSmallException if {@code end < start}.
     * @throws OutOfRangeException if the indices are not valid.
     * @since 3.1
     */
    public double walkInOptimizedOrder(final RealVectorPreservingVisitor visitor,
                                       final int start, final int end)
        throws NumberIsTooSmallException, OutOfRangeException {
        return walkInDefaultOrder(visitor, start, end);
    }

    
Visits (and possibly alters) all entries of this vector in default order
(increasing index).
Params:
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
Since:
3.1/**
     * Visits (and possibly alters) all entries of this vector in default order
     * (increasing index).
     *
     * @param visitor the visitor to be used to process and modify the entries
     * of this vector
     * @return the value returned by {@link RealVectorChangingVisitor#end()}
     * at the end of the walk
     * @since 3.1
     */
    public double walkInDefaultOrder(final RealVectorChangingVisitor visitor) {
        final int dim = getDimension();
        visitor.start(dim, 0, dim - 1);
        for (int i = 0; i < dim; i++) {
            setEntry(i, visitor.visit(i, getEntry(i)));
        }
        return visitor.end();
    }

    
Visits (and possibly alters) some entries of this vector in default order
(increasing index).
Params:
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)
Throws:
NumberIsTooSmallException – if end < start.
OutOfRangeException – if the indices are not valid.
Returns:
the value returned by RealVectorChangingVisitor.end() at the end of the walk
Since:
3.1/**
     * Visits (and possibly alters) some entries of this vector in default order
     * (increasing index).
     *
     * @param visitor visitor to be used to process the entries of this vector
     * @param start the index of the first entry to be visited
     * @param end the index of the last entry to be visited (inclusive)
     * @return the value returned by {@link RealVectorChangingVisitor#end()}
     * at the end of the walk
     * @throws NumberIsTooSmallException if {@code end < start}.
     * @throws OutOfRangeException if the indices are not valid.
     * @since 3.1
     */
    public double walkInDefaultOrder(final RealVectorChangingVisitor visitor,
                              final int start, final int end)
        throws NumberIsTooSmallException, OutOfRangeException {
        checkIndices(start, end);
        visitor.start(getDimension(), start, end);
        for (int i = start; i <= end; i++) {
            setEntry(i, visitor.visit(i, getEntry(i)));
        }
        return visitor.end();
    }

    
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.
Params:
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
Since:
3.1/**
     * 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.
     *
     * @param visitor the visitor to be used to process the entries of this
     * vector
     * @return the value returned by {@link RealVectorChangingVisitor#end()}
     * at the end of the walk
     * @since 3.1
     */
    public double walkInOptimizedOrder(final RealVectorChangingVisitor visitor) {
        return walkInDefaultOrder(visitor);
    }

    
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.
Params:
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)
Throws:
NumberIsTooSmallException – if end < start.
OutOfRangeException – if the indices are not valid.
Returns:
the value returned by RealVectorChangingVisitor.end() at the end of the walk
Since:
3.1/**
     * 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.
     *
     * @param visitor visitor to be used to process the entries of this vector
     * @param start the index of the first entry to be visited
     * @param end the index of the last entry to be visited (inclusive)
     * @return the value returned by {@link RealVectorChangingVisitor#end()}
     * at the end of the walk
     * @throws NumberIsTooSmallException if {@code end < start}.
     * @throws OutOfRangeException if the indices are not valid.
     * @since 3.1
     */
    public double walkInOptimizedOrder(final RealVectorChangingVisitor visitor,
                                       final int start, final int end)
        throws NumberIsTooSmallException, OutOfRangeException {
        return walkInDefaultOrder(visitor, start, end);
    }

    
An entry in the vector. /** An entry in the vector. */
    protected class Entry {
        
Index of this entry. /** Index of this entry. */
        private int index;

        
Simple constructor. /** Simple constructor. */
        public Entry() {
            setIndex(0);
        }

        
Get the value of the entry.
Returns:
the value of the entry./**
         * Get the value of the entry.
         *
         * @return the value of the entry.
         */
        public double getValue() {
            return getEntry(getIndex());
        }

        
Set the value of the entry.
Params:
value – New value for the entry./**
         * Set the value of the entry.
         *
         * @param value New value for the entry.
         */
        public void setValue(double value) {
            setEntry(getIndex(), value);
        }

        
Get the index of the entry.
Returns:
the index of the entry./**
         * Get the index of the entry.
         *
         * @return the index of the entry.
         */
        public int getIndex() {
            return index;
        }

        
Set the index of the entry.
Params:
index – New index for the entry./**
         * Set the index of the entry.
         *
         * @param index New index for the entry.
         */
        public void setIndex(int index) {
            this.index = index;
        }
    }

    
 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). 
Params:
other – Object to test for equality.
Throws:
MathUnsupportedOperationException – if this method is not
overridden.
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./**
     * <p>
     * Test for the equality of two real vectors. If all coordinates of two real
     * vectors are exactly the same, and none are {@code NaN}, the two real
     * vectors are considered to be equal. {@code 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
     * {@code NaN}, the real vector is equal to a vector with all {@code NaN}
     * coordinates.
     * </p>
     * <p>
     * This method <em>must</em> be overriden by concrete subclasses of
     * {@link RealVector} (the current implementation throws an exception).
     * </p>
     *
     * @param other Object to test for equality.
     * @return {@code true} if two vector objects are equal, {@code false} if
     * {@code other} is null, not an instance of {@code RealVector}, or
     * not equal to this {@code RealVector} instance.
     * @throws MathUnsupportedOperationException if this method is not
     * overridden.
     */
    @Override
    public boolean equals(Object other)
        throws MathUnsupportedOperationException {
        throw new MathUnsupportedOperationException();
    }

    
{@inheritDoc}. This method must be overriden by concrete subclasses of RealVector (current implementation throws an exception). 
Throws:
MathUnsupportedOperationException – if this method is not
overridden./**
     * {@inheritDoc}. This method <em>must</em> be overriden by concrete
     * subclasses of {@link RealVector} (current implementation throws an
     * exception).
     *
     * @throws MathUnsupportedOperationException if this method is not
     * overridden.
     */
    @Override
    public int hashCode() throws MathUnsupportedOperationException {
        throw new MathUnsupportedOperationException();
    }

    
This class should rarely be used, but is here to provide
a default implementation of sparseIterator(), which is implemented
by walking over the entries, skipping those that are zero.
Concrete subclasses which are SparseVector implementations should
make their own sparse iterator, rather than using this one.
This implementation might be useful for ArrayRealVector, when expensive
operations which preserve the default value are to be done on the entries,
and the fraction of non-default values is small (i.e. someone took a
SparseVector, and passed it into the copy-constructor of ArrayRealVector)
/**
     * This class should rarely be used, but is here to provide
     * a default implementation of sparseIterator(), which is implemented
     * by walking over the entries, skipping those that are zero.
     *
     * Concrete subclasses which are SparseVector implementations should
     * make their own sparse iterator, rather than using this one.
     *
     * This implementation might be useful for ArrayRealVector, when expensive
     * operations which preserve the default value are to be done on the entries,
     * and the fraction of non-default values is small (i.e. someone took a
     * SparseVector, and passed it into the copy-constructor of ArrayRealVector)

     */
    protected class SparseEntryIterator implements Iterator<Entry> {
        
Dimension of the vector. /** Dimension of the vector. */
        private final int dim;
        
Last entry returned by next(). /** Last entry returned by {@link #next()}. */
        private Entry current;
        
Next entry for next() to return. /** Next entry for {@link #next()} to return. */
        private Entry next;

        
Simple constructor. /** Simple constructor. */
        protected SparseEntryIterator() {
            dim = getDimension();
            current = new Entry();
            next = new Entry();
            if (next.getValue() == 0) {
                advance(next);
            }
        }

        
Advance an entry up to the next nonzero one.
Params:
e – entry to advance./**
         * Advance an entry up to the next nonzero one.
         *
         * @param e entry to advance.
         */
        protected void advance(Entry e) {
            if (e == null) {
                return;
            }
            do {
                e.setIndex(e.getIndex() + 1);
            } while (e.getIndex() < dim && e.getValue() == 0);
            if (e.getIndex() >= dim) {
                e.setIndex(-1);
            }
        }

        
{@inheritDoc} /** {@inheritDoc} */
        public boolean hasNext() {
            return next.getIndex() >= 0;
        }

        
{@inheritDoc} /** {@inheritDoc} */
        public Entry next() {
            int index = next.getIndex();
            if (index < 0) {
                throw new NoSuchElementException();
            }
            current.setIndex(index);
            advance(next);
            return current;
        }

        
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all circumstances./**
         * {@inheritDoc}
         *
         * @throws MathUnsupportedOperationException in all circumstances.
         */
        public void remove() throws MathUnsupportedOperationException {
            throw new MathUnsupportedOperationException();
        }
    }

    
Returns an unmodifiable view of the specified vector. The returned vector has read-only access. An attempt to modify it will result in a MathUnsupportedOperationException. 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. 
Params:
v – Vector for which an unmodifiable view is to be returned.
Returns:
an unmodifiable view of 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 {@link MathUnsupportedOperationException}. However, the
     * returned vector is <em>not</em> immutable, since any modification of
     * {@code v} will also change the returned view.
     * For example, in the following piece of code
     * <pre>
     *     RealVector v = new ArrayRealVector(2);
     *     RealVector w = RealVector.unmodifiableRealVector(v);
     *     v.setEntry(0, 1.2);
     *     v.setEntry(1, -3.4);
     * </pre>
     * the changes will be seen in the {@code w} view of {@code v}.
     *
     * @param v Vector for which an unmodifiable view is to be returned.
     * @return an unmodifiable view of {@code v}.
     */
    public static RealVector unmodifiableRealVector(final RealVector v) {
        /**
         * This anonymous class is an implementation of {@link RealVector}
         * with read-only access.
         * It wraps any {@link RealVector}, and exposes all methods which
         * do not modify it. Invoking methods which should normally result
         * in the modification of the calling {@link RealVector} results in
         * a {@link MathUnsupportedOperationException}. It should be noted
         * that {@link UnmodifiableVector} is <em>not</em> immutable.
         */
        return new RealVector() {
            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all circumstances.
             */
            @Override
            public RealVector mapToSelf(UnivariateFunction function)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector map(UnivariateFunction function) {
                return v.map(function);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public Iterator<Entry> iterator() {
                final Iterator<Entry> i = v.iterator();
                return new Iterator<Entry>() {
                    
The current entry. /** The current entry. */
                    private final UnmodifiableEntry e = new UnmodifiableEntry();

                    
{@inheritDoc} /** {@inheritDoc} */
                    public boolean hasNext() {
                        return i.hasNext();
                    }

                    
{@inheritDoc} /** {@inheritDoc} */
                    public Entry next() {
                        e.setIndex(i.next().getIndex());
                        return e;
                    }

                    
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
                     * {@inheritDoc}
                     *
                     * @throws MathUnsupportedOperationException in all
                     * circumstances.
                     */
                    public void remove() throws MathUnsupportedOperationException {
                        throw new MathUnsupportedOperationException();
                    }
                };
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public Iterator<Entry> sparseIterator() {
                final Iterator<Entry> i = v.sparseIterator();

                return new Iterator<Entry>() {
                    
The current entry. /** The current entry. */
                    private final UnmodifiableEntry e = new UnmodifiableEntry();

                    
{@inheritDoc} /** {@inheritDoc} */
                    public boolean hasNext() {
                        return i.hasNext();
                    }

                    
{@inheritDoc} /** {@inheritDoc} */
                    public Entry next() {
                        e.setIndex(i.next().getIndex());
                        return e;
                    }

                    
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
                     * {@inheritDoc}
                     *
                     * @throws MathUnsupportedOperationException in all
                     * circumstances.
                     */
                    public void remove()
                        throws MathUnsupportedOperationException {
                        throw new MathUnsupportedOperationException();
                    }
                };
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector copy() {
                return v.copy();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector add(RealVector w)
                throws DimensionMismatchException {
                return v.add(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector subtract(RealVector w)
                throws DimensionMismatchException {
                return v.subtract(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector mapAdd(double d) {
                return v.mapAdd(d);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public RealVector mapAddToSelf(double d)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector mapSubtract(double d) {
                return v.mapSubtract(d);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public RealVector mapSubtractToSelf(double d)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector mapMultiply(double d) {
                return v.mapMultiply(d);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public RealVector mapMultiplyToSelf(double d)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector mapDivide(double d) {
                return v.mapDivide(d);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public RealVector mapDivideToSelf(double d)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector ebeMultiply(RealVector w)
                throws DimensionMismatchException {
                return v.ebeMultiply(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector ebeDivide(RealVector w)
                throws DimensionMismatchException {
                return v.ebeDivide(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double dotProduct(RealVector w)
                throws DimensionMismatchException {
                return v.dotProduct(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double cosine(RealVector w)
                throws DimensionMismatchException, MathArithmeticException {
                return v.cosine(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getNorm() {
                return v.getNorm();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getL1Norm() {
                return v.getL1Norm();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getLInfNorm() {
                return v.getLInfNorm();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getDistance(RealVector w)
                throws DimensionMismatchException {
                return v.getDistance(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getL1Distance(RealVector w)
                throws DimensionMismatchException {
                return v.getL1Distance(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getLInfDistance(RealVector w)
                throws DimensionMismatchException {
                return v.getLInfDistance(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector unitVector() throws MathArithmeticException {
                return v.unitVector();
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public void unitize() throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealMatrix outerProduct(RealVector w) {
                return v.outerProduct(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double getEntry(int index) throws OutOfRangeException {
                return v.getEntry(index);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public void setEntry(int index, double value)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public void addToEntry(int index, double value)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public int getDimension() {
                return v.getDimension();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector append(RealVector w) {
                return v.append(w);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector append(double d) {
                return v.append(d);
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector getSubVector(int index, int n)
                throws OutOfRangeException, NotPositiveException {
                return v.getSubVector(index, n);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public void setSubVector(int index, RealVector w)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public void set(double value)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public double[] toArray() {
                return v.toArray();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public boolean isNaN() {
                return v.isNaN();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public boolean isInfinite() {
                return v.isInfinite();
            }

            
{@inheritDoc} /** {@inheritDoc} */
            @Override
            public RealVector combine(double a, double b, RealVector y)
                throws DimensionMismatchException {
                return v.combine(a, b, y);
            }

            
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
             * {@inheritDoc}
             *
             * @throws MathUnsupportedOperationException in all
             * circumstances.
             */
            @Override
            public RealVector combineToSelf(double a, double b, RealVector y)
                throws MathUnsupportedOperationException {
                throw new MathUnsupportedOperationException();
            }

            
An entry in the vector. /** An entry in the vector. */
            class UnmodifiableEntry extends Entry {
                
{@inheritDoc} /** {@inheritDoc} */
                @Override
                public double getValue() {
                    return v.getEntry(getIndex());
                }

                
{@inheritDoc}
Throws:
MathUnsupportedOperationException – in all
circumstances./**
                 * {@inheritDoc}
                 *
                 * @throws MathUnsupportedOperationException in all
                 * circumstances.
                 */
                @Override
                public void setValue(double value)
                    throws MathUnsupportedOperationException {
                    throw new MathUnsupportedOperationException();
                }
            }
        };
    }
}