From 2e0b0f3c19018df43515c1a9e0a1215eb0920b6d Mon Sep 17 00:00:00 2001 From: David Bellot Date: Tue, 29 Jun 2010 08:35:17 +0000 Subject: [PATCH] more little doc everywhere, ongoing work, commit as a saving svn path=/branches/ublas-doxygen/; revision=63425 --- banded.hpp | 44 ++++--- blas.hpp | 380 ++++++++++++++++++++++++++++++++++++----------------- lu.hpp | 5 + 3 files changed, 292 insertions(+), 137 deletions(-) diff --git a/banded.hpp b/banded.hpp index 5c9ca5f7..2601faa4 100644 --- a/banded.hpp +++ b/banded.hpp @@ -983,13 +983,14 @@ namespace boost { namespace numeric { namespace ublas { /** \brief A diagonal matrix of values of type \c T, which is a specialization of a banded matrix * - * For a \f$(mxm)\f$-dimensional diagonal matrix, \f$0 \leq i < m\f$ and \f$0 \leq j < m\f$, if \f$i\neq j\f$ then - * \f$b_{i,j}=0\f$. The default storage for diagonal matrices is packed. Orientation and storage can also be specified. - * Default is \c row major \c unbounded_array. + * For a \f$(mxm)\f$-dimensional diagonal matrix, \f$0 \leq i < m\f$ and \f$0 \leq j < m\f$, + * if \f$i\neq j\f$ then \f$b_{i,j}=0\f$. The default storage for diagonal matrices is packed. + * Orientation and storage can also be specified. Default is \c row major \c unbounded_array. * - * As a specialization of a banded matrix, the constructor of the diagonal matrix creates a banded matrix with 0 upper - * and lower diagonals around the main diagonal and the matrix is obviously a square matrix. Operations are optimized - * based on these 2 assumptions. It is \b not required by the storage to initialize elements of the matrix. + * As a specialization of a banded matrix, the constructor of the diagonal matrix creates + * a banded matrix with 0 upper and lower diagonals around the main diagonal and the matrix is + * obviously a square matrix. Operations are optimized based on these 2 assumptions. It is + * \b not required by the storage to initialize elements of the matrix. * * \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. Default is \c row_major @@ -1037,17 +1038,17 @@ namespace boost { namespace numeric { namespace ublas { } }; - /** \brief A banded matrix adaptator: convert a matrix into a banded matrix + /** \brief A banded matrix adaptator: convert a any matrix into a banded matrix expression * - * For a \f$(mxn)\f$-dimensional banded matrix with \f$l\f$ lower and \f$u\f$ upper diagonals and - * \f$0 \leq i < m\f$ and \f$0 \leq j < n\f$, if \f$i>j+l\f$ or \f$ij+l\f$ or \f$i class banded_adaptor: @@ -2022,7 +2023,18 @@ namespace boost { namespace numeric { namespace ublas { template typename banded_adaptor::const_value_type banded_adaptor::zero_ = value_type/*zero*/(); - // Diagonal matrix adaptor class + /** \brief A diagonal matrix adaptator: convert a any matrix into a diagonal matrix expression + * + * For a \f$(mxm)\f$-dimensional matrix, the \c diagonal_adaptor will provide a diagonal matrix + * with \f$0 \leq i < m\f$ and \f$0 \leq j < m\f$, if \f$i\neq j\f$ then \f$b_{i,j}=0\f$. + * + * Storage and location are based on those of the underlying matrix. This is important because + * a \c diagonal_adaptor does not copy the matrix data to a new place. Therefore, modifying values + * in a \c diagonal_adaptor matrix will also modify the underlying matrix too. + * + * \tparam M the type of matrix used to generate the diagonal matrix + */ + template class diagonal_adaptor: public banded_adaptor { diff --git a/blas.hpp b/blas.hpp index 5f5dde4f..ed2acd13 100644 --- a/blas.hpp +++ b/blas.hpp @@ -18,14 +18,16 @@ 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 \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) + /** 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 @@ -36,7 +38,8 @@ namespace boost { namespace numeric { namespace ublas { return norm_1 (v); } - /** \brief 2-Norm: \f$\sum_i |x_i|^2\f$ (also called \f$\f$mathcal{L}_2 or Euclidean norm) + /** 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 @@ -47,7 +50,8 @@ namespace boost { namespace numeric { namespace ublas { return norm_2 (v); } - /** \brief Infinite-norm: \f$\max_i |x_i|\f$ (also called \f$\f$mathcal{L}_\infty norm) + /** 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 @@ -58,7 +62,8 @@ namespace boost { namespace numeric { namespace ublas { return norm_inf (v); } - /** \brief Inner product of vectors \a v1 and \a v2 + /** 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 @@ -71,7 +76,8 @@ namespace boost { namespace numeric { namespace ublas { return inner_prod (v1, v2); } - /** \brief Copy vector \a v2 to \a v1 + /** 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 @@ -84,54 +90,59 @@ namespace boost { namespace numeric { namespace ublas { 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 - */ + /** 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 - */ + /** 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 + /** Compute \f$v_1= v_1 + t.v_2\f$ + * + * \tparam V1 type of the first vector (not needed by default) + * \tparam T type of the scalar (not needed by default) + * \tparam V2 type of the second vector (not needed by default) + * \param v1 target and first vector + * \param t the scalar + * \param v2 second vector + * \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) + /** Performs rotation of points in the plane + * * \param t1 first scalar * \param v1 first vector * \param t2 second scalar * \param v2 second vector + * + * \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) */ template void @@ -151,40 +162,72 @@ namespace boost { namespace numeric { namespace ublas { */ namespace blas_2 { - /** \brief multiply vector \a v with triangular matrix \a m - \ingroup blas2 - \todo: check that matrix is really triangular - */ + /** \brief multiply vector \a v with triangular matrix \a m + * + * \param v a vector + * \param m a triangular matrix + * \return the result of the product + * + * \tparam V type of the vector (not needed by default) + * \tparam M type of the matrix (not needed by default) + */ template - V & - tmv (V &v, const M &m) { + V & tmv (V &v, const M &m) + { return v = prod (m, v); } - /** \brief solve \a m \a x = \a v in place, \a m is triangular matrix - \ingroup blas2 - */ + /** \brief solve \f$m.x = v\f$ in place, where \a m is a triangular matrix + * + * \param v a vector + * \param m a matrix + * \param C + * + * \tparam V a vector + * \tparam M a matrix + * \tparam C + */ template - V & - tsv (V &v, const M &m, C) { + V & tsv (V &v, const M &m, C) + { return v = solve (m, v, C ()); } - /** \brief compute \a v1 = \a t1 * \a v1 + \a t2 * (\a m * \a v2) - \ingroup blas2 - */ + /** \brief compute \a v1 = \a t1 * \a v1 + \a t2 * (\a m * \a v2) + * + * \param v1 + * \param t1 + * \param t2 + * \param m + * \param v2 + * + * \tparam V1 + * \tparam T1 + * \tparam T2 + * \tparam M + * \tparam V2 + */ template - V1 & - gmv (V1 &v1, const T1 &t1, const T2 &t2, const M &m, const V2 &v2) { + V1 & gmv (V1 &v1, const T1 &t1, const T2 &t2, const M &m, const V2 &v2) + { return v1 = t1 * v1 + t2 * prod (m, v2); } - /** \brief rank 1 update: \a m = \a m + \a t * (\a v1 * \a v2T) - \ingroup blas2 - */ + /** \brief rank 1 update: \a m = \a m + \a t * (\a v1 * \a v2T) + * + * \param m + * \param t + * \param v1 + * \param v2 + * + * \tparam M + * \tparam T + * \tparam V1 + * \tparam V2 + */ template - M & - gr (M &m, const T &t, const V1 &v1, const V2 &v2) { + M & gr (M &m, const T &t, const V1 &v1, const V2 &v2) + { #ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG return m += t * outer_prod (v1, v2); #else @@ -192,24 +235,38 @@ namespace boost { namespace numeric { namespace ublas { #endif } - /** \brief symmetric rank 1 update: \a m = \a m + \a t * (\a v * \a vT) - \ingroup blas2 - */ + /** \brief symmetric rank 1 update: \a m = \a m + \a t * (\a v * \a vT) + * + * \param m + * \param t + * \param v + * + * \tparam M + * \tparam T + * \tparam V + */ template - M & - sr (M &m, const T &t, const V &v) { + M & sr (M &m, const T &t, const V &v) { #ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG return m += t * outer_prod (v, v); #else return m = m + t * outer_prod (v, v); #endif } - /** \brief hermitian rank 1 update: \a m = \a m + \a t * (\a v * \a vH) - \ingroup blas2 - */ + + /** \brief hermitian rank 1 update: \a m = \a m + \a t * (\a v * \a vH) + * + * \param m + * \param t + * \param v + * + * \tparam M + * \tparam T + * \tparam V + */ template - M & - hr (M &m, const T &t, const V &v) { + M & hr (M &m, const T &t, const V &v) + { #ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG return m += t * outer_prod (v, conj (v)); #else @@ -217,27 +274,43 @@ namespace boost { namespace numeric { namespace ublas { #endif } - /** \brief symmetric rank 2 update: \a m = \a m + \a t * - (\a v1 * \a v2T + \a v2 * \a v1T) - \ingroup blas2 + /** \brief symmetric rank 2 update: \a m = \a m + \a t * (\a v1 * \a v2T + \a v2 * \a v1T) + * + * \param m + * \param t + * \param v1 + * \param v2 + * + * \tparam M + * \tparam T + * \tparam V1 + * \tparam V2 */ template - M & - sr2 (M &m, const T &t, const V1 &v1, const V2 &v2) { + M & sr2 (M &m, const T &t, const V1 &v1, const V2 &v2) + { #ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG return m += t * (outer_prod (v1, v2) + outer_prod (v2, v1)); #else return m = m + t * (outer_prod (v1, v2) + outer_prod (v2, v1)); #endif } - /** \brief hermitian rank 2 update: \a m = \a m + - \a t * (\a v1 * \a v2H) - + \a v2 * (\a t * \a v1)H) - \ingroup blas2 - */ + + /** \brief hermitian rank 2 update: \a m = \a m + \a t * (\a v1 * \a v2H) + \a v2 * (\a t * \a v1)H) + * + * \param m + * \param t + * \param v1 + * \param v2 + * + * \tparam M + * \tparam T + * \tparam V1 + * \tparam V2 + */ template - M & - hr2 (M &m, const T &t, const V1 &v1, const V2 &v2) { + M & hr2 (M &m, const T &t, const V1 &v1, const V2 &v2) + { #ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG return m += t * outer_prod (v1, conj (v2)) + type_traits::conj (t) * outer_prod (v2, conj (v1)); #else @@ -254,76 +327,143 @@ namespace boost { namespace numeric { namespace ublas { */ namespace blas_3 { - /** \brief triangular matrix multiplication - \ingroup blas3 - */ + /** \brief triangular matrix multiplication + * + * \param m1 + * \param t + * \param m2 + * \param m3 + * + * \tparam M1 + * \tparam T + * \tparam M2 + * \tparam M3 + * + */ template M1 & tmm (M1 &m1, const T &t, const M2 &m2, const M3 &m3) { return m1 = t * prod (m2, m3); } - /** \brief triangular solve \a m2 * \a x = \a t * \a m1 in place, - \a m2 is a triangular matrix - \ingroup blas3 - */ + /** \brief triangular solve \a m2 * \a x = \a t * \a m1 in place, \a m2 is a triangular matrix + * + * \param m1 + * \param t + * \param m2 + * \param C + * + * \tparam M1 + * \tparam T + * \tparam M2 + * \tparam C + */ template - M1 & - tsm (M1 &m1, const T &t, const M2 &m2, C) { + M1 & tsm (M1 &m1, const T &t, const M2 &m2, C) { return m1 = solve (m2, t * m1, C ()); } - /** \brief general matrix multiplication - \ingroup blas3 - */ + /** \brief general matrix multiplication + * + * \param m1 + * \param t1 + * \param t2 + * \param m2 + * \param m3 + * + * \tparam M1 + * \tparam T1 + * \tparam T2 + * \tparam M2 + * \tparam M3 + */ template M1 & gmm (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) { return m1 = t1 * m1 + t2 * prod (m2, m3); } - /** \brief symmetric rank k update: \a m1 = \a t * \a m1 + - \a t2 * (\a m2 * \a m2T) - \ingroup blas3 - \todo use opb_prod() - */ + /** \brief symmetric rank k update: \a m1 = \a t * \a m1 + \a t2 * (\a m2 * \a m2T) + * + * \param m1 + * \param t1 + * \param t2 + * \param m2 + * + * \tparam M1 + * \tparam T1 + * \tparam T2 + * \tparam M2 + * \todo use opb_prod() + */ template - M1 & - srk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2) { + M1 & srk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2) + { return m1 = t1 * m1 + t2 * prod (m2, trans (m2)); } - /** \brief hermitian rank k update: \a m1 = \a t * \a m1 + - \a t2 * (\a m2 * \a m2H) - \ingroup blas3 - \todo use opb_prod() - */ + + /** \brief hermitian rank k update: \a m1 = \a t * \a m1 + \a t2 * (\a m2 * \a m2H) + * + * \param m1 + * \param t1 + * \param t2 + * \param m2 + * + * \tparam M1 + * \tparam T1 + * \tparam T2 + * \tparam M2 + * \todo use opb_prod() + */ template - M1 & - hrk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2) { + M1 & hrk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2) + { return m1 = t1 * m1 + t2 * prod (m2, herm (m2)); } - /** \brief generalized symmetric rank k update: - \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3T) - + \a t2 * (\a m3 * \a m2T) - \ingroup blas3 - \todo use opb_prod() - */ + /** \brief generalized symmetric rank k update: \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3T) + \a t2 * (\a m3 * \a m2T) + * + * \param m1 + * \param t1 + * \param t1 + * \param m2 + * \param m3 + * + * \tparam M1 + * \tparam T1 + * \tparam T2 + * \tparam M2 + * \tparam M3 + * \todo use opb_prod() + */ template - M1 & - sr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) { + M1 & sr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) + { return m1 = t1 * m1 + t2 * (prod (m2, trans (m3)) + prod (m3, trans (m2))); } - /** \brief generalized hermitian rank k update: - \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3H) - + (\a m3 * (\a t2 * \a m2)H) - \ingroup blas3 - \todo use opb_prod() - */ + + /** \brief generalized hermitian rank k update: \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3H) + (\a m3 * (\a t2 * \a m2)H) + * + * \param m1 + * \param t1 + * \param t2 + * \param m2 + * \param m3 + * + * \tparam M1 + * \tparam T1 + * \tparam T2 + * \tparam M2 + * \tparam M3 + * \todo use opb_prod() + */ template - M1 & - hr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) { - return m1 = t1 * m1 + t2 * prod (m2, herm (m3)) + type_traits::conj (t2) * prod (m3, herm (m2)); + M1 & hr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) + { + return m1 = + t1 * m1 + + t2 * prod (m2, herm (m3)) + + type_traits::conj (t2) * prod (m3, herm (m2)); } } @@ -331,5 +471,3 @@ namespace boost { namespace numeric { namespace ublas { }}} #endif - - diff --git a/lu.hpp b/lu.hpp index a1b56658..f35f4d16 100644 --- a/lu.hpp +++ b/lu.hpp @@ -23,6 +23,11 @@ namespace boost { namespace numeric { namespace ublas { + /** \brief + * + * \tparam T + * \tparam A + */ template > class permutation_matrix: public vector {