|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r62789 - branches/ublas-doxygen
From: david.bellot_at_[hidden]
Date: 2010-06-11 03:57:54
Author: david.bellot
Date: 2010-06-11 03:57:49 EDT (Fri, 11 Jun 2010)
New Revision: 62789
URL: http://svn.boost.org/trac/boost/changeset/62789
Log:
changes on matrix, blas and new doc for sparse vectors
Text files modified:
branches/ublas-doxygen/blas.hpp | 139 ++++++++++++++++++++++-----------------
branches/ublas-doxygen/matrix.hpp | 126 +++++++++++++++++++----------------
branches/ublas-doxygen/matrix_proxy.hpp | 2
branches/ublas-doxygen/vector_sparse.hpp | 17 ++++
4 files changed, 164 insertions(+), 120 deletions(-)
Modified: branches/ublas-doxygen/blas.hpp
==============================================================================
--- branches/ublas-doxygen/blas.hpp (original)
+++ branches/ublas-doxygen/blas.hpp 2010-06-11 03:57:49 EDT (Fri, 11 Jun 2010)
@@ -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<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 @@
}
- /// \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 @@
}
- /// \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
Modified: branches/ublas-doxygen/matrix.hpp
==============================================================================
--- branches/ublas-doxygen/matrix.hpp (original)
+++ branches/ublas-doxygen/matrix.hpp 2010-06-11 03:57:49 EDT (Fri, 11 Jun 2010)
@@ -1011,14 +1011,22 @@
// 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 @@
}
};
- // ------------------------
- // 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 @@
};
- // -----------------
- // 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 @@
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 @@
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 @@
};
- // 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> > {
Modified: branches/ublas-doxygen/matrix_proxy.hpp
==============================================================================
--- branches/ublas-doxygen/matrix_proxy.hpp (original)
+++ branches/ublas-doxygen/matrix_proxy.hpp 2010-06-11 03:57:49 EDT (Fri, 11 Jun 2010)
@@ -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> > {
Modified: branches/ublas-doxygen/vector_sparse.hpp
==============================================================================
--- branches/ublas-doxygen/vector_sparse.hpp (original)
+++ branches/ublas-doxygen/vector_sparse.hpp 2010-06-11 03:57:49 EDT (Fri, 11 Jun 2010)
@@ -260,7 +260,22 @@
#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> > {
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk