no.uib.cipr.matrix.Vector Maven / Gradle / Ivy
/*
* Copyright (C) 2003-2006 Bjørn-Ove Heimsund
*
* This file is part of MTJ.
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by the
* Free Software Foundation; either version 2.1 of the License, or (at your
* option) any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this library; if not, write to the Free Software Foundation,
* Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package no.uib.cipr.matrix;
import java.io.Serializable;
/**
* Basic vector interface. It holds doubles in an array, and is
* used alongside Matrix in numerical computations. Implementing
* classes decides on the actual storage.
*
* Basic operations
*
* Use size to get the vector size. get(int) gets an
* element, and there are corresponding set(int,double) and
* add(int,double) methods as well. Note that vector indices are
* zero-based (typical for Java and C). This means that they range from 0 to
* size-1. It is legal to have size equal zero.
*
*
* Other basic operations are zero which zeros all the entries of
* the vector, which can be cheaper than either zeroing the vector manually, or
* creating a new vector, and the operation copy which creates a
* deep copy of the vector. This copy has separate storage, but starts with the
* same contents as the current vector.
*
* Iterators
*
* The vector interface extends Iterable, and the iterator returns
* a VectorEntry which contains current index and entry value. Note
* that the iterator may skip non-zero entries. Using an iterator, many simple
* and efficient algorithms can be created. The iterator also permits changing
* values in the vector, however only non-zero entries can be changed.
*
* Basic linear algebra
*
* A selection of basic linear algebra operations are available. To ensure high
* efficiency, little or no internal memory allocation is done, and the user is
* required to supply the output arguments.
*
*
* The operations available include:
*
*
* - Additions
* - Vectors can be added to each other, even if their underlying vector
* structures are incompatible
* - Scaling
* - Scalar multiplication (scaling) of a whole vector
* - Norms
* - Both innerproducts and norms can be computed. Several common norms are
* supported
*
*/
public interface Vector extends Iterable, Serializable {
/**
* Size of the vector
*/
int size();
/**
* x(index) = value
*/
void set(int index, double value);
/**
* x(index) += value
*/
void add(int index, double value);
/**
* Returns x(index)
*/
double get(int index);
/**
* Creates a deep copy of the vector
*/
Vector copy();
/**
* Zeros all the entries in the vector, while preserving any underlying
* structure
*/
Vector zero();
/**
* x=alpha*x
*
* @return x
*/
Vector scale(double alpha);
/**
* x=y
*
* @return x
*/
Vector set(Vector y);
/**
* x=alpha*y
*
* @return x
*/
Vector set(double alpha, Vector y);
/**
* x = y + x
*
* @return x
*/
Vector add(Vector y);
/**
* x = alpha*y + x
*
* @return x
*/
Vector add(double alpha, Vector y);
/**
* xT*y
*/
double dot(Vector y);
/**
* Computes the given norm of the vector
*
* @param type
* The type of norm to compute
*/
double norm(Norm type);
/**
* Supported vector-norms. The difference between the two 2-norms is that
* one is fast, but can overflow, while the robust version is overflow
* resistant, but slower.
*/
enum Norm {
/**
* Sum of the absolute values of the entries
*/
One,
/**
* The root of sum of squares
*/
Two,
/**
* As the 2 norm may overflow, an overflow resistant version is also
* available. Note that it may be slower.
*/
TwoRobust,
/**
* Largest entry in absolute value
*/
Infinity
}
}