boost/ublas
2
0
Fork 0
mirror of https://github.com/boostorg/ublas.git synced 2026-02-26 05:02:16 +00:00
Code Issues Projects Releases Wiki Activity

changes on matrix, blas and new doc for sparse vectors

Browse Source 
svn path=/branches/ublas-doxygen/; revision=62789
This commit is contained in:
David Bellot
2010-06-11 07:57:49 +00:00
parent 254881809a
commit 8cca321eb9
4 changed files with 164 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
blas.hpp
View File

@@ -18,110 +18,121 @@
namespace boost { namespace numeric { namespace ublas {
/// \brief Interface and implementation of BLAS level 1
/// Interface and implementation of BLAS level 1. This includes functions which perform vector-vector operations.
/// More information about BLAS can be found at <a href="http://en.wikipedia.org/wiki/BLAS">http://en.wikipedia.org/wiki/BLAS</a>
/** \brief Interface and implementation of BLAS level 1
* This includes functions which perform \b vector-vector operations.
* More information about BLAS can be found at
* <a href="http://en.wikipedia.org/wiki/BLAS">http://en.wikipedia.org/wiki/BLAS</a>
*/
namespace blas_1 {
/// \brief 1-Norm: \f$\sum_i |x_i|\f$ (also called \f$\f$mathcal{L}_1 or Manhattan norm)
/// \tparam V type of the vector (not needed by default)
/// \param v a vector or vector expression
/// \return the 1-Norm with type of the vector's type
/** \brief 1-Norm: \f$\sum_i |x_i|\f$ (also called \f$\f$mathcal{L}_1 or Manhattan norm)
* \tparam V type of the vector (not needed by default)
* \param v a vector or vector expression
* \return the 1-Norm with type of the vector's type
*/
template<class V>
typename type_traits<typename V::value_type>::real_type
asum (const V &v) {
return norm_1 (v);
}
/// \brief 2-Norm: \f$\sum_i |x_i|^2\f$ (also called \f$\f$mathcal{L}_2 or Euclidean norm)
/// \tparam V type of the vector (not needed by default)
/// \param v a vector or vector expression
/// \return the 2-Norm with type of the vector's type
/** \brief 2-Norm: \f$\sum_i |x_i|^2\f$ (also called \f$\f$mathcal{L}_2 or Euclidean norm)
* \tparam V type of the vector (not needed by default)
* \param v a vector or vector expression
* \return the 2-Norm with type of the vector's type
*/
template<class V>
typename type_traits<typename V::value_type>::real_type
nrm2 (const V &v) {
return norm_2 (v);
}
/// \brief Infinite-norm: \f$\max_i |x_i|\f$ (also called \f$\f$mathcal{L}_\infty norm)
/// \tparam V type of the vector (not needed by default)
/// \param v a vector or vector expression
/// \return the Infinite-Norm with type of the vector's type
/** \brief Infinite-norm: \f$\max_i |x_i|\f$ (also called \f$\f$mathcal{L}_\infty norm)
* \tparam V type of the vector (not needed by default)
* \param v a vector or vector expression
* \return the Infinite-Norm with type of the vector's type
*/
template<class V>
typename type_traits<typename V::value_type>::real_type
amax (const V &v) {
return norm_inf (v);
}
/// \brief Inner product of vectors \a v1 and \a v2
/// \tparam V1 type of first vector (not needed by default)
/// \tparam V2 type of second vector (not needed by default)
/// \param v1 first vector of the inner product
/// \param v2 second vector of the inner product
/// \return the inner product of the type of the most generic type of the 2 vectors
/** \brief Inner product of vectors \a v1 and \a v2
* \tparam V1 type of first vector (not needed by default)
* \tparam V2 type of second vector (not needed by default)
* \param v1 first vector of the inner product
* \param v2 second vector of the inner product
* \return the inner product of the type of the most generic type of the 2 vectors
*/
template<class V1, class V2>
typename promote_traits<typename V1::value_type, typename V2::value_type>::promote_type
dot (const V1 &v1, const V2 &v2) {
return inner_prod (v1, v2);
}
/// \brief Copy vector \a v2 to \a v1
/// \tparam V1 type of first vector (not needed by default)
/// \tparam V2 type of second vector (not needed by default)
/// \param v1 target vector
/// \param v2 source vector
/// \return a reference to the target vector
/** \brief Copy vector \a v2 to \a v1
* \tparam V1 type of first vector (not needed by default)
* \tparam V2 type of second vector (not needed by default)
* \param v1 target vector
* \param v2 source vector
* \return a reference to the target vector
*/
template<class V1, class V2>
V1 &
copy (V1 &v1, const V2 &v2) {
return v1.assign (v2);
}
/// \brief swap vectors \a v1 and \a v2
/// \tparam V1 type of first vector (not needed by default)
/// \tparam V2 type of second vector (not needed by default)
/// \param v1 first vector
/// \param v2 second vector
template<class V1, class V2>
/** \brief swap vectors \a v1 and \a v2
* \tparam V1 type of first vector (not needed by default)
* \tparam V2 type of second vector (not needed by default)
* \param v1 first vector
* \param v2 second vector
*/
template<class V1, class V2>
void swap (V1 &v1, V2 &v2) {
v1.swap (v2);
}
/// \brief scale vector \a v with scalar \a t
/// \tparam V type of the vector (not needed by default)
/// \tparam T type of the scalar (not needed by default)
/// \param v vector to be scaled
/// \param t the scalar
/// \return \c t*v
/** \brief scale vector \a v with scalar \a t
* \tparam V type of the vector (not needed by default)
* \tparam T type of the scalar (not needed by default)
* \param v vector to be scaled
* \param t the scalar
* \return \c t*v
*/
template<class V, class T>
V &
scal (V &v, const T &t) {
return v *= t;
}
/// \brief Compute \f$v_1= v_1 + t.v_2\f$
/// \tparam V1 type of the first vector (not needed by default)
/// \tparam V2 type of the second vector (not needed by default)
/// \tparam T type of the scalar (not needed by default)
/// \param v1 target and first vector
/// \param v2 second vector
/// \param t the scalar
/// \return a reference to the first and target vector
/** \brief Compute \f$v_1= v_1 + t.v_2\f$
* \tparam V1 type of the first vector (not needed by default)
* \tparam V2 type of the second vector (not needed by default)
* \tparam T type of the scalar (not needed by default)
* \param v1 target and first vector
* \param v2 second vector
* \param t the scalar
*/
\return a reference to the first and target vector
template<class V1, class T, class V2>
V1 &
axpy (V1 &v1, const T &t, const V2 &v2) {
return v1.plus_assign (t * v2);
}
/// \brief Apply plane rotation
/// \tparam T1 type of the first scalar (not needed by default)
/// \tparam V1 type of the first vector (not needed by default)
/// \tparam T2 type of the second scalar (not needed by default)
/// \tparam V2 type of the second vector (not needed by default)
/// \param t1 first scalar
/// \param v1 first vector
/// \param t2 second scalar
/// \param v2 second vector
/** \brief Apply plane rotation
* \tparam T1 type of the first scalar (not needed by default)
* \tparam V1 type of the first vector (not needed by default)
* \tparam T2 type of the second scalar (not needed by default)
* \tparam V2 type of the second vector (not needed by default)
* \param t1 first scalar
* \param v1 first vector
* \param t2 second scalar
* \param v2 second vector
*/
template<class T1, class V1, class T2, class V2>
void
rot (const T1 &t1, V1 &v1, const T2 &t2, V2 &v2) {
@@ -133,9 +144,11 @@ namespace boost { namespace numeric { namespace ublas {
}
/// \brief Interface and implementation of BLAS level 2
/// Interface and implementation of BLAS level 2. This includes functions which perform matrix-vector operations.
/// More information about BLAS can be found at <a href="http://en.wikipedia.org/wiki/BLAS">http://en.wikipedia.org/wiki/BLAS</a>
/** \brief Interface and implementation of BLAS level 2
* This includes functions which perform \b matrix-vector operations.
* More information about BLAS can be found at
* <a href="http://en.wikipedia.org/wiki/BLAS">http://en.wikipedia.org/wiki/BLAS</a>
*/
namespace blas_2 {
/** \brief multiply vector \a v with triangular matrix \a m
@@ -234,9 +247,11 @@ namespace boost { namespace numeric { namespace ublas {
}
/// \brief Interface and implementation of BLAS level 3
/// Interface and implementation of BLAS level 3. This includes functions which perform matrix-matrix operations.
/// More information about BLAS can be found at <a href="http://en.wikipedia.org/wiki/BLAS">http://en.wikipedia.org/wiki/BLAS</a>
/** \brief Interface and implementation of BLAS level 3
* This includes functions which perform \b matrix-matrix operations.
* More information about BLAS can be found at
* <a href="http://en.wikipedia.org/wiki/BLAS">http://en.wikipedia.org/wiki/BLAS</a>
*/
namespace blas_3 {
/** \brief triangular matrix multiplication

126
matrix.hpp
View File

@@ -1011,14 +1011,22 @@ namespace boost { namespace numeric {
// Bounded matrix class
// --------------------
/// \brief A dense matrix of values of type \c T with a variable size bounded to a maximum of \f$M\f$ by \f$N\f$. Orientation can be specified. By default it is a row major orientation.
/// A dense matrix of values of type \c T with a variable size bounded to a maximum of \f$M\f$ by \f$N\f$. Orientation can be specified. By default it is a row major orientation. /// The default constructor creates the matrix with size \f$M\f$ by \f$N\f$. Elements are constructed by the storage type \c bounded_array, which need not initialise their value. /// For a \f$(m x n)\f$-dimensional matrix and \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$m_{i,j} is mapped to the \f$(i x n + j)\f$-th element of the container for
/// row major orientation or the \f$(i + j x m)\f$-th element of the container for column major orientation. Finally in a dense matrix all elements are represented in memory
/// in a contiguous chunk of memory.
/// \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
/// \tparam M maximum and default number of rows (if not specified at construction)
/// \tparam N maximum and default number of columns (if not specified at construction)
/// \tparam L the storage organization. It can be either \c row_major or \c column_major. By default it is \c row_major
/** \brief A dense matrix of values of type \c T with a variable size bounded to a maximum of \f$M\f$ by \f$N\f$.
*
* For a \f$(m x n)\f$-dimensional matrix and \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$m_{i,j} is mapped
* to the \f$(i x n + j)\f$-th element of the container for row major orientation or the \f$(i + j x m)\f$-th element
* of the container for column major orientation. Finally in a dense matrix all elements are represented in memory
* in a contiguous chunk of memory.
*
* Orientation can be specified. Default is \c row_major
* The default constructor creates the matrix with size \f$M\f$ by \f$N\f$. Elements are constructed by the storage
* type \c bounded_array, which need not initialise their value.
*
* \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
* \tparam M maximum and default number of rows (if not specified at construction)
* \tparam N maximum and default number of columns (if not specified at construction)
* \tparam L the storage organization. It can be either \c row_major or \c column_major. Default is \c row_major
*/
template<class T, std::size_t M, std::size_t N, class L>
class bounded_matrix:
public matrix<T, L, bounded_array<T, M * N> > {
@@ -1086,18 +1094,21 @@ namespace boost { namespace numeric {
}
};
// ------------------------
// Array based matrix class
// ------------------------
/// \brief A dense matrix of values of type \c T with a given size. The data is stored as a vector of vectors, meaning that either rows or columns might not be stored into contiguous chunks of memory. Orientation and storage can also be specified, otherwise a row major and unbounded arrays are used.
/// A dense matrix of values of type \c T with a given size. The data is stored as a vector of vectors, meaning that rows or columns might not be stored into contiguous chunks
/// of memory. Orientation and storage can also be specified, otherwise a row major and unbounded arrays are used. The storage type defaults to
/// \c unbounded_array<unbounded_array<T>> and orientation is \c row_major. It is \b not required by the storage to initialize elements of the matrix. For a
/// \f$(m x n)\f$-dimensional matrix and \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$m_{i,j} is mapped to the \f$(i x n + j)\f$-th element of the container for row
/// major orientation or the \f$(i + j x m)\f$-th element of the container for column major orientation.
/// \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
/// \tparam L the storage organization. It can be either \c row_major or \c column_major. By default it is \c row_major
/// \tparam A the type of Storage array. By default, it is an \unbounded_array<unbounder_array<T>>
/**
* \brief A dense matrix of values of type \c T stored as a vector of vectors.
*
* Rows or columns are not stored into contiguous chunks of memory but data inside rows (or columns) are.
* Orientation and storage can also be specified, otherwise a row major and unbounded arrays are used.
* A dense matrix of values of type \c T with a given size. The data is stored as a vector of vectors, meaning that rows or columns might not be stored into contiguous chunks
* of memory. Orientation and storage can also be specified, otherwise a row major and unbounded arrays are used. The storage type defaults to
* \c unbounded_array<unbounded_array<T>> and orientation is \c row_major. It is \b not required by the storage to initialize elements of the matrix. For a
* \f$(m x n)\f$-dimensional matrix and \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$m_{i,j} is mapped to the \f$(i x n + j)\f$-th element of the container for row
* major orientation or the \f$(i + j x m)\f$-th element of the container for column major orientation.
*
* \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
* \tparam L the storage organization. It can be either \c row_major or \c column_major. By default it is \c row_major
* \tparam A the type of Storage array. By default, it is an \unbounded_array<unbounder_array<T>>
*/
template<class T, class L, class A>
class vector_of_vector:
public matrix_container<vector_of_vector<T, L, A> > {
@@ -2078,14 +2089,12 @@ namespace boost { namespace numeric {
};
// -----------------
// Zero matrix class
// -----------------
/// \brief A matrix with all values of type \c T equal to zero.
/// A matrix with all values of type \c T equal to zero. Changing values does not affect the matrix, however assigning it to a normal matrix will put zero
/// everywhere in the target matrix. All accesses are constant time, due to the trivial value.
/// \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
/// \tparam ALLOC an allocator for storing the zero element. By default, a standar allocator is used.
/** \brief A matrix with all values of type \c T equal to zero
* Changing values does not affect the matrix, however assigning it to a normal matrix will put zero
* everywhere in the target matrix. All accesses are constant time, due to the trivial value.
* \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
* \tparam ALLOC an allocator for storing the zero element. By default, a standar allocator is used.
*/
template<class T, class ALLOC>
class zero_matrix:
public matrix_container<zero_matrix<T, ALLOC> > {
@@ -2464,12 +2473,13 @@ namespace boost { namespace numeric {
template<class T, class ALLOC>
const typename zero_matrix<T, ALLOC>::value_type zero_matrix<T, ALLOC>::zero_ = T(/*zero*/);
// Identity matrix class
/// \brief An identity matrix with values of type \c T
/// An identity matrix with values of type \c T. Elements or cordinates \f$(i,i)\f$ are equal to 1 (one) and all others to 0 (zero). Changing values does not affect the matrix, however assigning it to a normal matrix will make the matrix equal to an identity matrix. All accesses are constant du to the trivial values.
/// \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
/// \tparam ALLOC an allocator for storing the zeros and one elements. By default, a standar allocator is used.
/** \brief An identity matrix with values of type \c T
* Elements or cordinates \f$(i,i)\f$ are equal to 1 (one) and all others to 0 (zero).
* Changing values does not affect the matrix, however assigning it to a normal matrix will
* make the matrix equal to an identity matrix. All accesses are constant du to the trivial values.
* \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
* \tparam ALLOC an allocator for storing the zeros and one elements. By default, a standar allocator is used.
*/
template<class T, class ALLOC>
class identity_matrix:
public matrix_container<identity_matrix<T, ALLOC> > {
@@ -2878,15 +2888,12 @@ namespace boost { namespace numeric {
const typename identity_matrix<T, ALLOC>::value_type identity_matrix<T, ALLOC>::one_ (1); // ISSUE: need 'one'-traits here
// -------------------
// Scalar matrix class
// -------------------
/// \brief A matrix with all values of type \c T equal to the same value
/// A matrix with all values of type \c T equal to the same value. Changing one value has the effect of changing all the values. Assigning it to a normal matrix will copy.
/// the same value everywhere in this matrix. All accesses are constant time, due to the trivial value.
/// \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
/// \tparam ALLOC an allocator for storing the unique value. By default, a standar allocator is used.
/** \brief A matrix with all values of type \c T equal to the same value
* Changing one value has the effect of changing all the values. Assigning it to a normal matrix will copy
* the same value everywhere in this matrix. All accesses are constant time, due to the trivial value.
* \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
* \tparam ALLOC an allocator for storing the unique value. By default, a standar allocator is used.
*/
template<class T, class ALLOC>
class scalar_matrix:
public matrix_container<scalar_matrix<T, ALLOC> > {
@@ -3340,20 +3347,25 @@ namespace boost { namespace numeric {
};
// Array based matrix class
/// \brief An array based matrix class which size is defined at type specification or object instanciation
/// An array based matrix class which size is defined at type specification or object instanciation.
/// This matrix is directly based on a predefinec C-style arry of data, thus providing the fastest
/// implementation possible. The constraint is that dimensions of the matrix must be specified at
/// the instanciation or the type specification. For instance,
/// \code typedef c_matrix<double,4,4> my_4by4_matrix\endcode defines a 4x4 double-precision matrix.
/// You can also instantiate it directly with \code c_matrix<int,8,5> my_fast_matrix\endcode.
/// This will make a 8 by 5 integer matrix. The price to pay for this speed is that you cannot resize it
/// to a size larger than the one defined in the template parameters. In the previous example, a size of
/// 4 by 5 or 3 by 2 is acceptable, but a new size of 9 by 5 or even 10 by 10 will raise a bad_size() exception.
/// \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
/// \tparam N the default maximum number of rows
/// \tparam M the default maximum number of columns
/** \brief An array based matrix class which size is defined at type specification or object instanciation
* This matrix is directly based on a predefined C-style arry of data, thus providing the fastest
* implementation possible. The constraint is that dimensions of the matrix must be specified at
* the instanciation or the type specification.
*
* For instance,
* \code
* typedef c_matrix<double,4,4> my_4by4_matrix
* \endcode
* defines a 4x4 double-precision matrix.
* You can also instantiate it directly with \code c_matrix<int,8,5> my_fast_matrix\endcode.
* This will make a 8 by 5 integer matrix. The price to pay for this speed is that you cannot resize it
* to a size larger than the one defined in the template parameters. In the previous example, a size of
* 4 by 5 or 3 by 2 is acceptable, but a new size of 9 by 5 or even 10 by 10 will raise a bad_size() exception.
*
* \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
* \tparam N the default maximum number of rows
* \tparam M the default maximum number of columns
*/
template<class T, std::size_t N, std::size_t M>
class c_matrix:
public matrix_container<c_matrix<T, N, M> > {

2
matrix_proxy.hpp
View File

@@ -23,6 +23,8 @@
namespace boost { namespace numeric { namespace ublas {
// Matrix based row vector class
/** \brief
*/
template<class M>
class matrix_row:
public vector_expression<matrix_row<M> > {

17
vector_sparse.hpp
View File

@@ -260,7 +260,22 @@ namespace boost { namespace numeric { namespace ublas {
#endif
// Index map based sparse vector class
/** \brief Index map based sparse vector
*
* A sparse vector of values of type T of variable size. The sparse storage type A can be
* \c std::map<size_t, T> or \c map_array<size_t, T>. This means that only non-zero elements
* are effectively stored.
*
* For a \f$n\f$-dimensional sparse vector, and 0 <= i < n the non-zero elements \f$v_i\f$
* are mapped to consecutive elements of the associative container, i.e. for elements
* \f$k = v_{i_1}\f$ and \f$k + 1 = v_{i_2}\f$ of the container, holds \f$i_1 < i_2\f$.
*
* Supported parameters for the adapted array are \c map_array<std::size_t, T> and
* \c map_std<std::size_t, T>. The latter is equivalent to \c std::map<std::size_t, T>.
*
* \tparam T
* \tparam A
*/
template<class T, class A>
class mapped_vector:
public vector_container<mapped_vector<T, A> > {