
BoostCommit : 
Subject: [Boostcommit] svn:boost r64148  in sandbox/numeric_bindings/libs/numeric/bindings/doc/lapack: . computational driver
From: rutger_at_[hidden]
Date: 20100719 02:53:41
Author: rutger
Date: 20100719 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 20100719 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 20100719 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 compiletime,
+and is determined by the type of values contained in type `MatrixA`.
+The type of values is obtained through the `value_type` metafunction
+ `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/explorehtml/spstrf.f.html spstrf.f], [@http://www.netlib.org/lapack/explorehtml/dpstrf.f.html dpstrf.f], [@http://www.netlib.org/lapack/explorehtml/cpstrf.f.html cpstrf.f], and [@http://www.netlib.org/lapack/explorehtml/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 20100719 02:53:39 EDT (Mon, 19 Jul 2010)
@@ 66,7 +66,7 @@
Computer Science Division Technical Report No. UCB/CSD97971,
UC Berkeley, May 1997.
Notes:
+Further Details
1.`stemr` works only on machines which follow IEEE754
floatingpoint 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 20100719 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 MbyN
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 illconditioned
diagonal matrices and C is wellconditioned 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 wellconditioned 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 nonLAPACK 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. 13221342.
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. 13431362.
LAPACK Working note 170.
[3] Z. Drmac and Z. Bujanovic: On the failure of rankrevealing QR
factorization software  a case study.
ACM Trans. Math. Softw. Vol. 35, No 2 (2008), pp. 128.
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 compiletime,
and is determined by the type of values contained in type `MatrixA`.
The type of values is obtained through the `value_type` metafunction
BoostCommit 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