Subject: [Boost-commit] svn:boost r63425 - branches/ublas-doxygen
From: david.bellot_at_[hidden]
Date: 2010-06-29 04:35:18
Author: david.bellot
Date: 2010-06-29 04:35:17 EDT (Tue, 29 Jun 2010)
New Revision: 63425
URL: http://svn.boost.org/trac/boost/changeset/63425
Log:
more little doc everywhere, ongoing work, commit as a saving
Text files modified:
branches/ublas-doxygen/banded.hpp | 44 ++-
branches/ublas-doxygen/blas.hpp | 380 +++++++++++++++++++++++++++------------
branches/ublas-doxygen/lu.hpp | 5
3 files changed, 292 insertions(+), 137 deletions(-)
Modified: branches/ublas-doxygen/banded.hpp
==============================================================================
--- branches/ublas-doxygen/banded.hpp (original)
+++ branches/ublas-doxygen/banded.hpp 2010-06-29 04:35:17 EDT (Tue, 29 Jun 2010)
@@ -983,13 +983,14 @@
/** \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 @@
}
};
- /** \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$i<j-u\f$ then \f$b_{i,j}=0\f$.
- * The default storage for banded matrices is packed. Orientation and storage can also be specified.
- * Default is \c row_major and and unbounded_array. It is \b not required by the storage to initialize
- * elements of the matrix.
+ * For a \f$(mxn)\f$-dimensional matrix, the \c banded_adaptor will provide a 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$i<j-u\f$ then \f$b_{i,j}=0\f$.
*
- * \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
- * \tparam A the type of Storage array. Default is \c unbounded_array
+ * Storage and location are based on those of the underlying matrix. This is important because
+ * a \c banded_adaptor does not copy the matrix data to a new place. Therefore, modifying values
+ * in a \c banded_adaptor matrix will also modify the underlying matrix too.
+ *
+ * \tparam M the type of matrix used to generate a banded matrix
*/
template<class M>
class banded_adaptor:
@@ -2022,7 +2023,18 @@
template<class M>
typename banded_adaptor<M>::const_value_type banded_adaptor<M>::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 M>
class diagonal_adaptor:
public banded_adaptor<M> {
Modified: branches/ublas-doxygen/blas.hpp
==============================================================================
--- branches/ublas-doxygen/blas.hpp (original)
+++ branches/ublas-doxygen/blas.hpp 2010-06-29 04:35:17 EDT (Tue, 29 Jun 2010)
@@ -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 @@
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 @@
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 @@
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 @@
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 @@
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<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
- */
+ /** 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
+ /** 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<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)
+ /** 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<class T1, class V1, class T2, class V2>
void
@@ -151,40 +162,72 @@
*/
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<class V, class M>
- 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<class V, class M, class C>
- 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<class V1, class T1, class T2, class M, class V2>
- 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 v2<sup>T</sup>)
- \ingroup blas2
- */
+ /** \brief rank 1 update: \a m = \a m + \a t * (\a v1 * \a v2<sup>T</sup>)
+ *
+ * \param m
+ * \param t
+ * \param v1
+ * \param v2
+ *
+ * \tparam M
+ * \tparam T
+ * \tparam V1
+ * \tparam V2
+ */
template<class M, class T, class V1, class V2>
- 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 @@
#endif
}
- /** \brief symmetric rank 1 update: \a m = \a m + \a t * (\a v * \a v<sup>T</sup>)
- \ingroup blas2
- */
+ /** \brief symmetric rank 1 update: \a m = \a m + \a t * (\a v * \a v<sup>T</sup>)
+ *
+ * \param m
+ * \param t
+ * \param v
+ *
+ * \tparam M
+ * \tparam T
+ * \tparam V
+ */
template<class M, class T, class V>
- 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 v<sup>H</sup>)
- \ingroup blas2
- */
+
+ /** \brief hermitian rank 1 update: \a m = \a m + \a t * (\a v * \a v<sup>H</sup>)
+ *
+ * \param m
+ * \param t
+ * \param v
+ *
+ * \tparam M
+ * \tparam T
+ * \tparam V
+ */
template<class M, class T, class V>
- 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 @@
#endif
}
- /** \brief symmetric rank 2 update: \a m = \a m + \a t *
- (\a v1 * \a v2<sup>T</sup> + \a v2 * \a v1<sup>T</sup>)
- \ingroup blas2
+ /** \brief symmetric rank 2 update: \a m = \a m + \a t * (\a v1 * \a v2<sup>T</sup> + \a v2 * \a v1<sup>T</sup>)
+ *
+ * \param m
+ * \param t
+ * \param v1
+ * \param v2
+ *
+ * \tparam M
+ * \tparam T
+ * \tparam V1
+ * \tparam V2
*/
template<class M, class T, class V1, class V2>
- 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 v2<sup>H</sup>)
- + \a v2 * (\a t * \a v1)<sup>H</sup>)
- \ingroup blas2
- */
+
+ /** \brief hermitian rank 2 update: \a m = \a m + \a t * (\a v1 * \a v2<sup>H</sup>) + \a v2 * (\a t * \a v1)<sup>H</sup>)
+ *
+ * \param m
+ * \param t
+ * \param v1
+ * \param v2
+ *
+ * \tparam M
+ * \tparam T
+ * \tparam V1
+ * \tparam V2
+ */
template<class M, class T, class V1, class V2>
- 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<T>::conj (t) * outer_prod (v2, conj (v1));
#else
@@ -254,76 +327,143 @@
*/
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<class M1, class T, class M2, class M3>
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<class M1, class T, class M2, class C>
- 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<class M1, class T1, class T2, class M2, class M3>
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 m2<sup>T</sup>)
- \ingroup blas3
- \todo use opb_prod()
- */
+ /** \brief symmetric rank k update: \a m1 = \a t * \a m1 + \a t2 * (\a m2 * \a m2<sup>T</sup>)
+ *
+ * \param m1
+ * \param t1
+ * \param t2
+ * \param m2
+ *
+ * \tparam M1
+ * \tparam T1
+ * \tparam T2
+ * \tparam M2
+ * \todo use opb_prod()
+ */
template<class M1, class T1, class T2, class M2>
- 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 m2<sup>H</sup>)
- \ingroup blas3
- \todo use opb_prod()
- */
+
+ /** \brief hermitian rank k update: \a m1 = \a t * \a m1 + \a t2 * (\a m2 * \a m2<sup>H</sup>)
+ *
+ * \param m1
+ * \param t1
+ * \param t2
+ * \param m2
+ *
+ * \tparam M1
+ * \tparam T1
+ * \tparam T2
+ * \tparam M2
+ * \todo use opb_prod()
+ */
template<class M1, class T1, class T2, class M2>
- 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 m3<sup>T</sup>)
- + \a t2 * (\a m3 * \a m2<sup>T</sup>)
- \ingroup blas3
- \todo use opb_prod()
- */
+ /** \brief generalized symmetric rank k update: \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3<sup>T</sup>) + \a t2 * (\a m3 * \a m2<sup>T</sup>)
+ *
+ * \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<class M1, class T1, class T2, class M2, class M3>
- 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 m3<sup>H</sup>)
- + (\a m3 * (\a t2 * \a m2)<sup>H</sup>)
- \ingroup blas3
- \todo use opb_prod()
- */
+
+ /** \brief generalized hermitian rank k update: \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3<sup>H</sup>) + (\a m3 * (\a t2 * \a m2)<sup>H</sup>)
+ *
+ * \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<class M1, class T1, class T2, class M2, class M3>
- 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<T2>::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<T2>::conj (t2) * prod (m3, herm (m2));
}
}
@@ -331,5 +471,3 @@
}}}
#endif
-
-
Modified: branches/ublas-doxygen/lu.hpp
==============================================================================
--- branches/ublas-doxygen/lu.hpp (original)
+++ branches/ublas-doxygen/lu.hpp 2010-06-29 04:35:17 EDT (Tue, 29 Jun 2010)
@@ -23,6 +23,11 @@
namespace boost { namespace numeric { namespace ublas {
+ /** \brief
+ *
+ * \tparam T
+ * \tparam A
+ */
template<class T = std::size_t, class A = unbounded_array<T> >
class permutation_matrix:
public vector<T, A> {