From 8cca321eb9045947cc3c2cc0c07f5e44102e3e8b Mon Sep 17 00:00:00 2001 From: David Bellot Date: Fri, 11 Jun 2010 07:57:49 +0000 Subject: [PATCH] changes on matrix, blas and new doc for sparse vectors svn path=/branches/ublas-doxygen/; revision=62789 --- blas.hpp | 139 +++++++++++++++++++++++++--------------------- matrix.hpp | 126 ++++++++++++++++++++++------------------- matrix_proxy.hpp | 2 + vector_sparse.hpp | 17 +++++- 4 files changed, 164 insertions(+), 120 deletions(-) diff --git a/blas.hpp b/blas.hpp index 6818a014..5f5dde4f 100644 --- a/blas.hpp +++ b/blas.hpp @@ -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 http://en.wikipedia.org/wiki/BLAS + /** \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 + * http://en.wikipedia.org/wiki/BLAS + */ 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 typename type_traits::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 typename type_traits::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 typename type_traits::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 typename promote_traits::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 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 + /** \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 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 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 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 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 http://en.wikipedia.org/wiki/BLAS + /** \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 + * http://en.wikipedia.org/wiki/BLAS + */ 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 http://en.wikipedia.org/wiki/BLAS + /** \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 + * http://en.wikipedia.org/wiki/BLAS + */ namespace blas_3 { /** \brief triangular matrix multiplication diff --git a/matrix.hpp b/matrix.hpp index d6140992..596832cc 100644 --- a/matrix.hpp +++ b/matrix.hpp @@ -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 bounded_matrix: public matrix > { @@ -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> 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> + /** + * \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> 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> + */ template class vector_of_vector: public matrix_container > { @@ -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 zero_matrix: public matrix_container > { @@ -2464,12 +2473,13 @@ namespace boost { namespace numeric { template const typename zero_matrix::value_type zero_matrix::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 identity_matrix: public matrix_container > { @@ -2878,15 +2888,12 @@ namespace boost { namespace numeric { const typename identity_matrix::value_type identity_matrix::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 scalar_matrix: public matrix_container > { @@ -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 my_4by4_matrix\endcode defines a 4x4 double-precision matrix. - /// You can also instantiate it directly with \code c_matrix 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 my_4by4_matrix + * \endcode + * defines a 4x4 double-precision matrix. + * You can also instantiate it directly with \code c_matrix 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 c_matrix: public matrix_container > { diff --git a/matrix_proxy.hpp b/matrix_proxy.hpp index d097af79..2cc98159 100644 --- a/matrix_proxy.hpp +++ b/matrix_proxy.hpp @@ -23,6 +23,8 @@ namespace boost { namespace numeric { namespace ublas { // Matrix based row vector class + /** \brief + */ template class matrix_row: public vector_expression > { diff --git a/vector_sparse.hpp b/vector_sparse.hpp index 6a49d060..edde0440 100644 --- a/vector_sparse.hpp +++ b/vector_sparse.hpp @@ -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 or \c map_array. 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 and + * \c map_std. The latter is equivalent to \c std::map. + * + * \tparam T + * \tparam A + */ template class mapped_vector: public vector_container > {