[Boost-commit] svn:boost r64148 - in sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack: . computational driver

Subject: [Boost-commit] svn:boost r64148 - in sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack: . computational driver
From: rutger_at_[hidden]
Date: 2010-07-19 02:53:41

Author: rutger
Date: 2010-07-19 02:53:39 EDT (Mon, 19 Jul 2010)
New Revision: 64148
URL: http://svn.boost.org/trac/boost/changeset/64148

Log:
Lapack version bump; docs 

Added:
   sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/pstrf.qbk   (contents, props changed)
Text files modified: 
   sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational.qbk       |     1                                         
   sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/stemr.qbk |     2                                         
   sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/driver/gejsv.qbk        |    67 --------------------------------------- 
   3 files changed, 3 insertions(+), 67 deletions(-)

Modified: sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational.qbk	2010-07-19 02:53:39 EDT (Mon, 19 Jul 2010)
@@ -102,6 +102,7 @@
 [include computational/pptrf.qbk]
 [include computational/pptri.qbk]
 [include computational/pptrs.qbk]
+[include computational/pstrf.qbk]
 [include computational/ptcon.qbk]
 [include computational/ptrfs.qbk]
 [include computational/pttrf.qbk]

Added: sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/pstrf.qbk
==============================================================================
--- (empty file)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/pstrf.qbk	2010-07-19 02:53:39 EDT (Mon, 19 Jul 2010)
@@ -0,0 +1,94 @@
+[/ 
+
+THIS FILE IS AUTOMATICALLY GENERATED, PLEASE DO NOT EDIT!
+
+]
+
+[section pstrf]
+
+[heading Prototype]
+There is one prototype of `pstrf` available, please see below.
+``
+pstrf( MatrixA& a, VectorPIV& piv, int_t& rank,
+        const Scalar > );
+``
+
+
+[heading Description]
+
+`pstrf` (short for $FRIENDLY_NAME) provides a C++
+interface to LAPACK routines SPSTRF, DPSTRF, CPSTRF, and ZPSTRF. 
+`pstrf` computes the Cholesky factorization with complete
+pivoting of a complex Hermitian positive semidefinite matrix A.
+
+The factorization has the form
+P' * A * P = U' * U , if UPLO = 'U',
+P' * A * P = L * L', if UPLO = 'L',
+where U is an upper triangular matrix and L is lower triangular, and
+P is stored as vector PIV.
+
+This algorithm does not attempt to check that A is positive
+semidefinite. This version of the algorithm calls level 3 BLAS.
+
+The selection of the LAPACK routine is done during compile-time, 
+and is determined by the type of values contained in type `MatrixA`.
+The type of values is obtained through the `value_type` meta-function
+ `typename value_type<MatrixA>::type`.
+The dispatching table below illustrates to which specific routine 
+the code path will be generated. 
+
+[table Dispatching of pstrf
+[  [ Value type of MatrixA ] [LAPACK routine] ]
+[  [`float`][SPSTRF] ]
+[  [`double`][DPSTRF] ]
+[  [`complex<float>`][CPSTRF] ]
+[  [`complex<double>`][ZPSTRF] ]
+
+]
+
+
+[heading Definition]
+Defined in header [headerref boost/numeric/bindings/lapack/computational/pstrf.hpp].
+
+
+[heading Parameters or Requirements on Types]
+
+[variablelist Parameters
+    [[MatrixA] [The definition of term 1]]
+    [[MatrixB] [The definition of term 2]]
+    [[MatrixC] [
+    The definition of term 3.
+
+    Definitions may contain paragraphs.
+    ]]
+]
+
+
+[heading Complexity]
+
+
+[heading Example]
+``
+#include <boost/numeric/bindings/lapack/computational/pstrf.hpp>
+using namespace boost::numeric::bindings;
+
+lapack::pstrf( x, y, z );
+
+``
+
+this will output
+
+``
+[5] 0 1 2 3 4 5
+``
+
+
+
+[heading Notes]
+
+
+[heading See Also]
+
+* Originating Fortran source files [@http://www.netlib.org/lapack/explore-html/spstrf.f.html spstrf.f], [@http://www.netlib.org/lapack/explore-html/dpstrf.f.html dpstrf.f], [@http://www.netlib.org/lapack/explore-html/cpstrf.f.html cpstrf.f], and [@http://www.netlib.org/lapack/explore-html/zpstrf.f.html zpstrf.f] at Netlib.
+
+[endsect]

Modified: sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/stemr.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/stemr.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/computational/stemr.qbk	2010-07-19 02:53:39 EDT (Mon, 19 Jul 2010)
@@ -66,7 +66,7 @@
 Computer Science Division Technical Report No. UCB/CSD-97-971,
 UC Berkeley, May 1997.
 
-Notes:
+Further Details
 1.`stemr` works only on machines which follow IEEE-754
 floating-point standard in their handling of infinities and NaNs.
 This permits the use of efficient inner loops avoiding a check for

Modified: sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/driver/gejsv.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/driver/gejsv.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack/driver/gejsv.qbk	2010-07-19 02:53:39 EDT (Mon, 19 Jul 2010)
@@ -19,6 +19,7 @@
 
 `gejsv` (short for $FRIENDLY_NAME) provides a C++
 interface to LAPACK routines SGEJSV and DGEJSV. 
+`gejsv` computes the singular value decomposition (SVD) of a real M-by-N
 matrix [A], where M >= N. The SVD of [A] is written as
 
 [A] = [U] * [SIGMA] * [V]^t,
@@ -31,72 +32,6 @@
 are computed and stored in the arrays U and V, respectively. The diagonal
 of [SIGMA] is computed and stored in the array SVA.
 
-Further details
-~~~~~~~~~~~~~~~
-`gejsv` implements a preconditioned Jacobi SVD algorithm. It uses SGEQP3,
-SGEQRF, and SGELQF as preprocessors and preconditioners. Optionally, an
-additional row pivoting can be used as a preprocessor, which in some
-cases results in much higher accuracy. An example is matrix A with the
-structure A = D1 * C * D2, where D1, D2 are arbitrarily ill-conditioned
-diagonal matrices and C is well-conditioned matrix. In that case, complete
-pivoting in the first QR factorizations provides accuracy dependent on the
-condition number of C, and independent of D1, D2. Such higher accuracy is
-not completely understood theoretically, but it works well in practice.
-Further, if A can be written as A = B*D, with well-conditioned B and some
-diagonal D, then the high accuracy is guaranteed, both theoretically and
-in software, independent of D. For more details see [1], [2].
-The computational range for the singular values can be the full range
-( UNDERFLOW,OVERFLOW ), provided that the machine arithmetic and the BLAS
-& LAPACK routines called by `gejsv` are implemented to work in that range.
-If that is not the case, then the restriction for safe computation with
-the singular values in the range of normalized IEEE numbers is that the
-spectral condition number kappa(A)=sigma_max(A)/sigma_min(A) does not
-overflow. This code (`gejsv`) is best used in this restricted range,
-meaning that singular values of magnitude below ||A||_2 / SLAMCH('O') are
-returned as zeros. See JOBR for details on this.
-Further, this implementation is somewhat slower than the one described
-in [1,2] due to replacement of some non-LAPACK components, and because
-the choice of some tuning parameters in the iterative part (DGESVJ) is
-left to the implementer on a particular machine.
-The rank revealing QR factorization (in this code: SGEQP3) should be
-implemented as in [3]. We have a new version of SGEQP3 under development
-that is more robust than the current one in LAPACK, with a cleaner cut in
-rank defficient cases. It will be available in the SIGMA library [4].
-If M is much larger than N, it is obvious that the inital QRF with
-column pivoting can be preprocessed by the QRF without pivoting. That
-well known trick is not used in `gejsv` because in some cases heavy row
-weighting can be treated with complete pivoting. The overhead in cases
-M much larger than N is then only due to pivoting, but the benefits in
-terms of accuracy have prevailed. The implementer/user can incorporate
-this extra QRF step easily. The implementer can also improve data movement
-(matrix transpose, matrix copy, matrix transposed copy) - this
-implementation of `gejsv` uses only the simplest, naive data movement.
-
-Contributors
-~~~~~~~~~~~~
-Zlatko Drmac (Zagreb, Croatia) and Kresimir Veselic (Hagen, Germany)
-
-References
-~~~~~~~~~~
-[1] Z. Drmac and K. Veselic: New fast and accurate Jacobi SVD algorithm I.
-SIAM J. Matrix Anal. Appl. Vol. 35, No. 2 (2008), pp. 1322-1342.
-LAPACK Working note 169.
-[2] Z. Drmac and K. Veselic: New fast and accurate Jacobi SVD algorithm II.
-SIAM J. Matrix Anal. Appl. Vol. 35, No. 2 (2008), pp. 1343-1362.
-LAPACK Working note 170.
-[3] Z. Drmac and Z. Bujanovic: On the failure of rank-revealing QR
-factorization software - a case study.
-ACM Trans. Math. Softw. Vol. 35, No 2 (2008), pp. 1-28.
-LAPACK Working note 176.
-[4] Z. Drmac: SIGMA - mathematical software library for accurate SVD, PSV,
-QSVD, (H,K)-SVD computations.
-Department of Mathematics, University of Zagreb, 2008.
-
-Bugs, examples and comments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Please report all bugs and send interesting examples and/or comments to
-drmac_at_math.hr. Thank you.
-
 The selection of the LAPACK routine is done during compile-time, 
 and is determined by the type of values contained in type `MatrixA`.
 The type of values is obtained through the `value_type` meta-function