[Boost-commit] svn:boost r58100 - sandbox/numeric_bindings/libs/numeric/bindings/doc

Subject: [Boost-commit] svn:boost r58100 - sandbox/numeric_bindings/libs/numeric/bindings/doc
From: rutger_at_[hidden]
Date: 2009-12-02 10:50:58

Author: rutger
Date: 2009-12-02 10:50:57 EST (Wed, 02 Dec 2009)
New Revision: 58100
URL: http://svn.boost.org/trac/boost/changeset/58100

Log:
Start of documentation update 

Added:
   sandbox/numeric_bindings/libs/numeric/bindings/doc/traits.qbk   (contents, props changed)
   sandbox/numeric_bindings/libs/numeric/bindings/doc/tutorial.qbk   (contents, props changed)
Text files modified: 
   sandbox/numeric_bindings/libs/numeric/bindings/doc/blas.qbk             |    33 +++++++-                                
   sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack.qbk           |     5 +                                       
   sandbox/numeric_bindings/libs/numeric/bindings/doc/numeric_bindings.qbk |   149 ++++++++++++++++++++++++++++++++++----- 
   3 files changed, 162 insertions(+), 25 deletions(-)

Modified: sandbox/numeric_bindings/libs/numeric/bindings/doc/blas.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/doc/blas.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/blas.qbk	2009-12-02 10:50:57 EST (Wed, 02 Dec 2009)
@@ -1,5 +1,11 @@
 
-[section:blas BLAS Bindings]
+[section:blas BLAS]
+
+BLAS consists of three levels of routines: 
+
+* *level 1* routines involve scalar-vector and vector-vector operations, like computing an inne product,
+* *level 2* routines cover vector-matrix operations, and
+* *level 3* routines perform matrix-matrix operations.
 
 [table Level 1 BLAS
     [         [BLAS] [Boost.Numeric_Bindings Equivalent]]
@@ -10,14 +16,14 @@
     [         [xSWAP]     [ [funcref blas::swap] ] ]
     [         [xSCAL]     [ [funcref blas::scale] ] ]
     [         [xCOPY]     [ [funcref blas::copy] ] ]
-    [         [xAXPY]     [ [funcref blas::add] ] ]
+    [         [xAXPY]     [ [funcref blas::transform] ] ]
     [         [xDOT]      [ [funcref blas::dot] ] ]
     [         [xDOTU]     [ [funcref blas::dot] ] ]
     [         [xDOTC]     [ [funcref blas::dot] ] ]
-    [         [xxDOT]     [ [funcref blas::prec_dot] ] ]
+    [         [xxDOT]     [ [funcref blas::dot] ] ]
     [         [xNRM2]     [ [funcref blas::norm_2] ] ]
-    [         [xASUM]     [ [funcref blas::norm_1] ] ] 
-    [         [IxAMAX]    [ [funcref blas::norm_inf], [funcref blas::index_norm_inf]  ] ]
+    [         [xASUM]     [ [funcref blas::abs_sum] ] ] 
+    [         [IxAMAX]    [ [funcref blas::index_norm_inf] ] ]
 ]
 
 [table Level 2 BLAS
@@ -60,5 +66,22 @@
     [  [xTRSM]      [ [funcref blas::forward_solve], [funcref blas::back_solve] ] ]
 ]
 
+
+[include blas/level1.qbk]
+[include blas/level2.qbk]
+[include blas/level3.qbk]
+
 [endsect]
 
+
+
+
+
+
+
+
+
+
+
+
+

Modified: sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack.qbk	2009-12-02 10:50:57 EST (Wed, 02 Dec 2009)
@@ -1,5 +1,5 @@
 
-[section:lapack LAPACK Bindings]
+[section:lapack LAPACK]
 
 Here, the high-level LAPACK bindings will be described.
 
@@ -32,6 +32,9 @@
 
 `lapack::solve( a, b );`
 
+[include lapack/computational.qbk]
+[include lapack/driver.qbk]
+
 [endsect]
 
 

Modified: sandbox/numeric_bindings/libs/numeric/bindings/doc/numeric_bindings.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/doc/numeric_bindings.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/numeric_bindings.qbk	2009-12-02 10:50:57 EST (Wed, 02 Dec 2009)
@@ -1,9 +1,10 @@
 [article Boost.Numeric_Bindings
     [quickbook 1.4]
-    [version alpha]
-    [authors [author1],[author2]]
-    [copyright 2008 author1 author2]
+    [copyright 2002-2009 Rutger ter Borg, Krešimir Fresl, Thomas Klimpel, Toon Knapen, Karl Meerbergen]
     [purpose C++ bindings to widely used numeric libraries.]
+    [id numeric_bindings]
+    [dirname numeric/bindings/]
+    [authors [Authors, Various]]
     [license
         Distributed under the Boost Software License, Version 1.0.
         (See accompanying file LICENSE_1_0.txt or copy at
@@ -11,14 +12,27 @@
     ]
 ]
 
-[section:preface Preface]
-
+[def __unspecified__            /unspecified/]
 
+[section:preface Preface]
 [endsect]
 
 [section:introduction Introduction]
 
-Boost.Numeric_Bindings is a library for high-performance numeric computing. 
+Boost.Numeric_Bindings is a C++ library for numeric computing. It
+is a generic layer between linear algebra algorithms and data containers. 
+
+For the data container part, it supports both compile-time statically sized 
+and run-time dynamically sized vectors, matrices, through a 
+traits system. Currently it includes traits for C-arrays, 
+for standard vectors, for uBLAS' containers, Eigen containers, 
+TNT, Boost.Array, to name a few. It offers compile-time inspection, iterators, and views on all mentioned containers.
+
+For the algorithm part, 
+it provides a C++ interface to algorithms offered by 
+BLAS, LAPACK, and more. This covers algorithms from most 
+vendor-provided math libraries, such as the reference BLAS, 
+ATLAS, Intel's MKL, AMD's CML, NVidia's CUDA, etc.. 
 
 The Bindings Library contains bindings to popular non-boost 
 (numeric) libraries, usually written in Fortran or C. 
@@ -29,40 +43,137 @@
 data structures from different origins and usually hides or reduces the 
 complexity of the original API.
 
-For instance, [@http://math-atlas.sourceforge.net/ ATLAS] a C library
-implementing BLAS (and few LAPACK routines), represents matrices
-by means of a pointer and the dimensions. Now boost also contains
-matrix classes [@http://www.boost.org/libs/numeric/ublas/doc/index.htm uBLAS] 
-and there are also other matrix libraries in widespread use.
+E.g., it allows you to write
 
-Therefore the Bindings library features a generic interface 
-for ATLAS which provides the possibility
-to call e.g. the matrix-multiplication routine of ATLAS using matrices defined
-in uBLAS, TNT, etc.
+``
+double a[5] = { 1,2,3,4,5 };
+double b[5][5];
+...
+``
+
+In scope are container adaptors and algorithms:
+
+* Adaptors for a wide variety of foreign container types, supporting both 
+  compile-time statically sized and run-time dynamically sized containers.
+  At the moment, the library includes bindings for C-style arrays, 
+  ISO C++ standard vectors, uBLAS', Eigen2, TNT, Boost.Array, 
+  to name a few.
+* Meta-adaptors to create views on these containers, 
+  such as row, transpose, and upper. These are convenient when addressing BLAS or LAPACK.
+* Iterators supporting different strategies to inspect and modify all containers 
+  mentioned above. This invites users to write container-independent algorithms.
+* A BLAS module supporting cblas, blas, and cublas backends. This covers algorithms from 
+  the reference BLAS, ATLAS, Intel's MKL, AMD's CML, NVidia's CUBLAS, and 
+  many more vendor-specific BLASs.
+* LAPACK. 
+
+Out of scope:
+
+* Another set of containers.
+* A domain-specific language.
+
+What's hopefully to be added in the future:
+
+* Backends for BLAS / LAPACK containing compile-time implementations, e.g., for 
+  small and/or statically sized objects. 
+* Support for FFT libraries.
 
 [endsect]
 
-[section:traits Datatype Concepts and Traits]
+[include tutorial.qbk]
+
+[section:organization Library Organization]
+
+Boost.Numeric_Bindings is organized as a generic layer between 
+linear algebra algorithms and matrix and vector classes. The 
+following hierarchy is available:
+
+* blas
+ * level1
+ * level2
+ * level3
+* lapack
+ * auxiliary
+ * computational
+ * driver
+* std
+* ublas
+* tnt
+
+The library is header-only, i.e., there is no need to compile or create shared library files for it.
+
+Example
+
+If you would like to include the whole of BLAS, just do a 
+
+``#include <boost/numeric/bindings/blas.hpp``
+
+or, if you desire BLAS level2 only, doing a 
+
+``#include <boost/numeric/bindings/blas/level2.hpp``
+
+or, if you only want include per-operation, doing a 
+
+``#include <boost/numeric/bindings/blas/level3/gemm.hpp``
+
+will be the most granular level. 
+
 [endsect]
 
-[section:tutorial Tutorial]
+[section:containers Containers]
+[endsect]
 
+[section Views]
 
+[section Functions]
 
+[section trans]
+[endsect]
+[section upper]
+[endsect]
+[section lower]
+[endsect]
+[section row]
+[endsect]
+[section column]
+[endsect]
+
+[endsect]
 
+[section Metafunctions]
 
+[section trans]
+[endsect]
+[section upper]
+[endsect]
+[section lower]
+[endsect]
+[section row]
+[endsect]
+[section column]
 [endsect]
 
+[endsect]
 
+[endsect]
+
+
+[include traits.qbk]
+
+
+[section Algorithms]
 [include blas.qbk]
+
 [include lapack.qbk]
 
 
+[endsect]
+
 [section:license License]
 
-Copyright 2008 author1, author2.
+Copyright 2002-2009 author1, author2.
 Distributed under the Boost Software License, Version 1.0. (See
 accompanying file LICENSE_1_0.txt or copy at
 [@http://www.boost.org/LICENSE_1_0.txt])
 
-[endsect]
\ No newline at end of file
+[endsect]

Added: sandbox/numeric_bindings/libs/numeric/bindings/doc/traits.qbk
==============================================================================
--- (empty file)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/traits.qbk	2009-12-02 10:50:57 EST (Wed, 02 Dec 2009)
@@ -0,0 +1,147 @@
+
+[section Functions]
+
+[section begin]
+
+``
+// Entity stuff, e.g., in case of Matrix:
+begin< tag::index<1> >(m)        // Row iterator
+begin< tag::index<2> >(m)        // Column iterator
+begin< tag::row >(m)            // Same as <1>
+begin< tag::column >(m)         // Same as <2>
+begin< tag::major >(m)          // Depends on data_order
+begin< tag::minor >(m)          // Depends on data_order
+
+// Data stuff, e.g.,:
+begin< tag::value >(m)          // Begin of value array or main diagonal
+begin< tag::inner >(m)          // Begin of Yale sparse index array of row/columns
+begin< tag::outer >(m)          // Begin of Yale sparse starting points in row/columns
+begin< tag::subdiagonal >(m)    // Begin of subdiagonal value array
+begin< tag::superdiagonal >(m)  // Begin of superdiagonal value array
+
+// Convenience
+begin1(m)                       // Convenience for tagged version
+begin2(m)                       // Convenience for tagged version
+begin_row(m)                    // Convenience for tagged version
+begin_column(m)                 // Convenience for tagged version
+begin_major(m)                  // Convenience for tagged version
+begin_minor(m)                  // Convenience for tagged version
+
+begin_value(m)                  // Convenience for tagged version
+begin_inner(m)                  // Convenience for tagged version
+begin_outer(m)                  // Convenience for tagged version
+
+begin_subdiagonal(m)            // Convenience for tagged version
+begin_superdiagonal(m)          // Convenience for tagged version
+``
+
+[endsect]
+
+[section end]
+Identical to begin for semantics.
+[endsect]
+
+[section minimal_rank]
+
+This function returns the minimal rank needed to represent the underlying,
+0 <= minimal_rank <= rank.
+
+[endsect]
+
+[section size]
+Identical to begin for semantics.
+[endsect]
+
+[section stride]
+
+Only defined in case of 
+
+``
+// E.g., for matrices
+stride< 1 >(m)                   // Stride for increment of index 1
+stride< 2 >(m)                   // Stride for increment of index 2
+stride< tag::major >(m)          // Depends on data_order
+stride< tag::minor >(m)          // Depends on data_order
+
+// Convenience stuff
+stride1(m)
+stride_major(m)
+stride_minor(m)
+
+``
+
+
+[endsect]
+
+[endsect]
+
+[section Metafunctions]
+
+
+[section begin]
+
+[heading Description]
+Returns the result type of begin
+
+[heading Synopsis]
+``
+template< typename T >
+struct begin {
+    typedef __unspecified__ type;
+};
+``
+
+[heading Expression Semantics]
+``
+result_of::begin<T>::type
+``
+
+[endsect]
+
+[section rank]
+[heading Description]
+Returns the rank of the underlying
+
+[heading Synopsis]
+``
+template< typename T >
+struct rank: integral_constant {};
+``
+[endsect]
+
+
+
+[section size]
+
+[heading Description]
+Returns the result type of size
+
+[heading Synopsis]
+``
+template< typename T >
+struct size {
+    typedef __unspecified__ type;
+};
+``
+[endsect]
+
+
+
+
+[section value]
+[heading Description]
+Returns the value type of the underlying
+
+[heading Synopsis]
+``
+template< typename T >
+struct value {
+    typedef __unspecified__ type;
+};
+``
+[endsect]
+
+
+[endsect]
+
+

Added: sandbox/numeric_bindings/libs/numeric/bindings/doc/tutorial.qbk
==============================================================================
--- (empty file)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/tutorial.qbk	2009-12-02 10:50:57 EST (Wed, 02 Dec 2009)
@@ -0,0 +1,68 @@
+
+[section:tutorial Tutorial]
+
+[section Hello, World!]
+
+To work with numeric bindings, usually you need
+to do at least two includes: one for the container you're using, 
+and one for some operation you would like to perform.
+
+Please see below.
+
+``
+#include <boost/numeric/bindings/std/vector.hpp>
+#include <boost/numeric/bindings/size.hpp>
+
+int main() {
+    std::vector<double> a;
+    a.push_back( 1.0 );
+    a.push_back( 2.0 );
+    a.push_back( 3.0 );
+    std::cout << bindings::size( a ) << std::endl;
+}
+
+``
+
+Although this isn't that interesting, it illustrates you're 
+bringing in support for standard vectors and the size operation.
+
+[endsect]
+
+
+[section Basic Linear Algebra]
+[endsect]
+
+[section Advanced Linear Algebra]
+[endsect]
+
+[section Inverting a matrix]
+
+Suppose you would like to invert a matrix given by
+
+``
+    [ 1 2 3 ]
+A = [ 3 1 2 ]
+    [ 2 3 1 ] ``
+
+[endsect]
+
+
+[section Inspecting a type]
+[endsect]
+
+[section Writing a generic numeric algorithm]
+
+* Generic in the sense that you don't know the matrix and/or vector
+  classes that you will be supplied with.
+* No memory allocations.
+
+[endsect]
+
+[section Adapting your own type]
+[endsect]
+
+
+
+
+
+[endsect]