============ FLENS-LAPACK [TOC:2] ============ At the moment we are working on a C++ port of __LAPACK__. *Sound tedious? It is a joy with FLENS*! This is because FLENS gives you easy-to-use tools for implementing efficient, robust and reliable numerical software. Not all LAPACK function have been ported so far. However, if you have an external LAPACK implementation on your system then you can use FLENS-LAPACK as a high-level interface. FLENS-LAPACK accesses the external LAPACK library through the low-level CXXLAPACK layer. The usage and concept of this high-level (CXX)LAPACK interface is illustrated in the __tutorial__. :links: __LAPACK__ -> http://www.netlib.org/lapack/ __tutorial__ -> doc:flens/examples/tut05-page01 Generic FLENS-LAPACK: Purpose ============================= FLENS is a comfortable tool for the implementation of numerical algorithms. At the same time we avoid negative impacts on efficiency due to abstraction. Our FLENS-LAPACK port demonstrates the following features of FLENS: - *Easy to read and understand* There are many C++ libraries that implement LAPACK functionality. But when you look at their code it is often hard to even recognize the underlying algorithm. It is like the algorithm gets lost in all these C++ template tricks and tweaks. The Fortan implementation of LAPACK is much easier to read and understand than all these C++ implementations. Even if you are not very familiar with Fortran! So even if some C++ nerds don't like to hear it Fortran LAPACK is great. However, there is one drawback. As there are no actual matrix/vector types many parameters have to be passed to LAPACK routines. This is sometimes error-prone and hard to read. But still better than many other C++ implementations. The FLENS-LAPACK not only competes in terms of readability with the FORTRAN implementation but even exceeds it. FLENS provides a very expressive notation for numerical linear algebra. Therefore FLENS-LAPACK implementation of numerical algorithms is *really readable*. You can consider FLENS-LAPACK as an improved reimplementation of Fortran LAPACK. - *Same results as the Fortran Implementation of LAPACK* LAPACK is the king in the numerical software field,established and well tested. Our implementation is intended to produce exactly the same results as the Fortran LAPACK (Version 3.3.1). As long as the same BLAS implementation gets used. And with *exactly the same results* we mean that we even produce the same roundoff errors. - *Same performance as the Fortran implementation of LAPACK* While we have not begun with benchmarking we are confident that in the end we achieve the same performance as the Fortran LAPACK. Again under the assumption that in both cases the same BLAS implementation is used. - *CXXBLAS* We provide a generic BLAS implementation that gets called if no native BLAS implementation like __ATLAS__, __GotoBLAS__ or __OpenBLAS__ is available or if the involved data types are not supported. While CXXBLAS currently passes all BLAS test we plan to modify its implementation such that it produces exactly the same results as the BLAS reference implementation. Due to CXXBLAS the FLENS-LAPACK routines can be used with data types from C++ multi-precision libraries. :links: __ATLAS__ -> http://math-atlas.sourceforge.net/ __GotoBLAS__ -> http://www.tacc.utexas.edu/tacc-projects/gotoblas2 __OpenBLAS__ -> http://xianyi.github.com/OpenBLAS/ Current Status ============== Below we give an overview of the functionality currently provided by FLENS-LAPACK. Function names of FLENS-LAPACK are derived from corresponding LAPACK. We removed letters from the function names that merely specify the argument types: - __sv__ in FLENS-LAPACK corresponds to __dgesv__ and __zgesv__ in LAPACK - __trs__ in FLENS-LAPACK corresponds to __dgetrs__, __zgetrs__, __dtrtrs__ and __ztrtrs__ in LAPACK - ... At the moment only a subset of LAPACK is re-implemented in FLENS-LAPACK. For other LAPACK functions FLENS-LAPACK serves as a high-level interface. Have a look into the __tutorial__ for learning how to use an external LAPACK implementation. By default FLENS-LAPACK will prefer a generic LAPACK implementation over a external implementation. An external implementation only gets called if no generic implementation is available. You can change this default behavior through macros as described in the tutorial. Routines for Matrices with Full Storage ======================================= Linear Equation Routines ------------------------ +----------+---------------+----------------------------------------+----------------+ | TYPE | FLENS-LAPACK | DESCRIPTION | LAPACK | +==========+===============+========================================+================+ | General | __sv__ | Solves a general system of linear | __dgesv__, | | | | equations $AX=B$. | __zgesv__ | | | | | | | | | *Example:* __lapack-gesv__. | | + +---------------+----------------------------------------+----------------+ | | __svx__ | Solves a general system of linear | __dgesvx__ | | | | equations $AX=B$. Error bounds on | | | | | the solution and a condition estimate | | | | | are also provided. | | + +---------------+----------------------------------------+----------------+ | | __trf__ | Computes an $LU$ factorization of a | __dgetrf__, | | | | general matrix, using partial pivoting | __zgetrf__ | | | | with row interchanges. | | | | | | | | | | *Example:* __lapack-getrf__. | | + +---------------+----------------------------------------+----------------+ | | __trs__ | Solves a general system of linear | __dgetrs__, | | | | equations $AX=B,$ $A^T X=B,$ or | __zgetrs__ | | | | $A^H X=B,$ using the $LU$ | | | | | factorization. | | | | | | | | | | *Example:* __lapack-getrs__. | | + +---------------+----------------------------------------+----------------+ | | __tri__ | Computes the inverse of a general | __dgetri__, | | | | matrix, using the $LU$ factorization. | __zgetri__^[1] | | | | | | | | | *Example:* __lapack-getri__. | | +----------+---------------+----------------------------------------+----------------+ | Positive | __posv__ | Solves a symmetric positive definite | __dposv__ | | Definite | | system of linear equations $AX=B.$ | __zposv__^[1] | | | | | | | | | *Example:* __lapack-posv__. | | + +---------------+----------------------------------------+----------------+ | | __potrf__ | Computes the Cholesky factorization | __dpotrf__, | | | | of a symmetric positive definite | __zpotrf__^[1] | | | | matrix. | | | | | | | | | | *Example:* __lapack-potrs__, | | | | | __lapack-potri__. | | + +---------------+----------------------------------------+----------------+ | | __potrs__ | Solves a symmetric positive definite | __dpotrs__, | | | | system of linear equations $AX=B,$ | __zpotrs__^[1] | | | | using the Cholesky factorization | | | | | computed by __potrf__. | | | | | | | | | | *Example:* __lapack-potrs__. | | + +---------------+----------------------------------------+----------------+ | | __potri__ | Computes the inverse of a positive | __dpotri__, | | | | definite matrix, using the Cholesky | __zpotri__^[1] | | | | factorization computed by __potrf__. | | | | | | | | | | *Example:* __lapack-potri__. | | +----------+---------------+----------------------------------------+----------------+ |Triangular| __trs__ | Solves a triangular system of linear | __dtrtrs__, | | | | equations $AX=B,$ $A^T X=B,$ or | __ztrtrs__ | | | | $A^H X=B,$ using the $LU$ | | | | | factorization. | | | | | | | | | | *Example:* __lapack-trtrs__. | | + +---------------+----------------------------------------+----------------+ | | __tri__ | Computes the inverse of a triangular | __dtrtri__, | | | | matrix, using the $LU$ factorization. | __ztrtri__^[1] | | | | | | | | | *Example:* __lapack-trtri__. | | +----------+---------------+----------------------------------------+----------------+ :links: __lapack-gesv__ -> doc:flens/examples/tut04-page03 __lapack-getrf__ -> doc:flens/examples/tut04-page01 __lapack-getrs__ -> doc:flens/examples/lapack-getrs __lapack-getri__ -> doc:flens/examples/lapack-getri __lapack-posv__ -> doc:flens/examples/lapack-posv __lapack-potrs__ -> doc:flens/examples/lapack-potrs __lapack-potri__ -> doc:flens/examples/lapack-potri __lapack-trtrs__ -> doc:flens/examples/lapack-trtrs __lapack-trtri__ -> doc:flens/examples/lapack-trtri __tutorial__ -> doc:flens/examples/tut05-page01 __(d.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(z.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(po.+)__ -> doc:flens/lapack/po/$1 __(.+)__ -> doc:flens/lapack/ge/$1 Orthogonal Factorizations ------------------------- +-----------+------------------------------------------------+---------------+ | FLENS | DESCRIPTION | LAPACK | +===========+================================================+===============+ | __qrf__ | Computes a $QR$ factorization of a general | __dgeqrf__, | | | rectangular matrix. | __zgeqrf__^[1]| | | | | | | *Example:* __lapack-geqrf__. | | +-----------+------------------------------------------------+---------------+ | __qp3__ | Computes a $QR$ factorization with column | __dgeqp3__, | | | pivoting of a matrix $A$ such that $AP = QP$. | __zgeqp3__^[1]| | | | | | | *Example:* __lapack-geqp3__. | | +-----------+------------------------------------------------+---------------+ | __orgqr__,| Generates all or part of the orthogonal/unitary| __dorgqr__, | | __ungqr__ | matrix $Q$ from a $QR$ factorization. | __zungqr__^[1]| | | | | | | *Example:* __lapack-orgqr__, __lapack-ungqr__. | | +-----------+------------------------------------------------+---------------+ | __ormqr__,| Multiplies a general matrix by the | __dormqr__, | | __unmqr__ | orthogonal/unitary matrix $Q$ from a $QR$ | __zunmqr__^[1]| | | factorization. | | | | | | | | *Example:* __lapack-ormqr__, __lapack-unmqr__. | | +-----------+------------------------------------------------+---------------+ | __lqf__ | Computes a $LQ$ factorization of a general | __dgelqf__, | | | rectangular matrix. | __zgelqf__^[1]| | | | | | | *Example:* __lapack-gelqf__. | | +-----------+------------------------------------------------+---------------+ | __ormlq__,| Multiplies a general matrix by the | __dormlq__, | | __unmlq__ | orthogonal/unitary matrix $Q$ from a $LQ$ | __zunmlq__^[1]| | | factorization. | | | | | | | | *Example:* see __lapack-gelqf__. | | +-----------+------------------------------------------------+---------------+ | __orglq__,| Generates all or part of the orthogonal/unitary| __dorglq__, | | __unglq__ | matrix $Q$ from a $LQ$ factorization. | __zunglq__^[1]| | | | | | | *Example:* __lapack-orglq__, __lapack-unglq__. | | +-----------+------------------------------------------------+---------------+ :links: __lapack-geqrf__ -> doc:flens/examples/tut04-page02 __lapack-geqp3__ -> doc:flens/examples/lapack-geqp3 __lapack-orgqr__ -> doc:flens/examples/lapack-orgqr __lapack-ungqr__ -> doc:flens/examples/lapack-ungqr __lapack-ormqr__ -> doc:flens/examples/lapack-ormqr __lapack-unmqr__ -> doc:flens/examples/lapack-unmqr __lapack-gelqf__ -> doc:flens/examples/lapack-gelqf __lapack-orglq__ -> doc:flens/examples/lapack-orglq __lapack-unglq__ -> doc:flens/examples/lapack-unglq __(d.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(z.+)__ -> file:cxxlapack/netlib/lapack/$1.f __([ou].*)__ -> file:flens/lapack/impl/$1.h __(.*)__ -> file:flens/lapack/ge/$1.h Least Square Problems --------------------- +-----------+------------------------------------------------+---------------+ | FLENS | DESCRIPTION | LAPACK | +===========+================================================+===============+ | __ls__ | Solves overdetermined or underdetermined real | __dgels__, | | | linear systems involving an $m \times n$ | __zgels__^[1] | | | matrix $A$, or its transpose, using a $QR$ or | | | | $LQ$ factorization of $A$. It is assumed that | | | | $A$ has *full rank*. | | | | | | | | The following options are provided: | | | | | | | | - If $m \geq n$: | | | | - find the least squares solution of an | | | | overdetermined system, i.e., solve the | | | | least squares problem: minimize | | | | $\| B - AX \|$ or | | | | - find the minimum norm solution of an | | | | undetermined system $A^T X = B$ (or | | | | $A^H X =B$). | | | | - If $m < n$: | | | | - find the minimum norm solution of an | | | | underdetermined system $A X = B$ or | | | | - find the least squares solution of an | | | | overdetermined system, i.e., solve the | | | | least squares problem minimize | | | | $\| B - A^T X \|$ (or $\| B - A^H X \|$). | | | | | | | | *Example:* __lapack-gels__. | | +-----------+------------------------------------------------+---------------+ | __lsy__ | Computes the *minimum-norm solution* to a real | __dgelsy__, | | | linear least squares problem: | __zgelsy__^[1]| | | minimize $\| A X - B \|$ using a complete | | | | orthogonal factorization of $A$. $A$ is an | | | | $m \times n$ matrix which may be | | | | *rank-deficient*. The rank of $A$ gets | | | | determined using a | | | | __incremental condition estimation__. | | | | | | | | *Example:* __lapack-gelsy__. | | +-----------+------------------------------------------------+---------------+ :links: __lapack-gels__ -> doc:flens/examples/lapack-gels __incremental condition estimation__ -> http://www.netlib.org/lapack/lawnspdf/lawn33.pdf __lapack-gelsy__ -> doc:flens/examples/lapack-gelsy __(d.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(z.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(.*)__ -> file:flens/lapack/ge/$1.h Non-Symmetric Eigenvalue Routines --------------------------------- +-----------+---------------------------------------------------+------------+ | FLENS | DESCRIPTION | LAPACK | +===========+===================================================+============+ | __ev__ | Computes the eigenvalues and left and right | __dgeev__ | | | eigenvectors of a general matrix. | | | | | | | | *Example:* __lapack-geev__. | | +-----------+---------------------------------------------------+------------+ | __evx__ | Computes the eigenvalues and left and right | __dgeevx__ | | | eigenvectors of a general matrix. Optionally | | | | also, it computes a balancing transformation to | | | | improve the conditioning of the eigenvalues and | | | | eigenvectors, reciprocal condition numbers | | | | for the eigenvalues, and reciprocal condition | | | | numbers for the right eigenvectors. | | +-----------+---------------------------------------------------+------------+ | __es__ | Computes for a general matrix, the eigenvalues, | __dgees__ | | | the real Schur form $T$, and, optionally, the | | | | matrix of Schur vectors $Z$. This gives the | | | | Schur factorization $A = Z T Z^T.$ | | +-----------+---------------------------------------------------+------------+ | __esx__ | Like __es__ but optionally, it also orders the | __dgeesx__ | | | eigenvalues on the diagonal of the real Schur | | | | form so that selected eigenvalues are at the top | | | | left; computes a reciprocal condition number for | | | | the average of the selected eigenvalues; | | | | and computes a reciprocal condition number for | | | | the right invariant subspace corresponding to the | | | | selected eigenvalues. The leading columns of $Z$ | | | | form an orthonormal basis for this invariant | | | | subspace. | | +-----------+---------------------------------------------------+------------+ | __hrd__ | Reduces a general matrix to upper Hessenberg form | __dgehrd__ | | | by an orthogonal similarity transformation. | | +-----------+---------------------------------------------------+------------+ | __orghr__ | Generates the orthogonal transformation matrix | __dorghr__ | | | from a reduction to Hessenberg form. | | +-----------+---------------------------------------------------+------------+ :links: __lapack-geev__ -> doc:flens/examples/tut04-page04 __(d.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(o.*)__ -> file:flens/lapack/impl/$1.h __(.*)__ -> file:flens/lapack/ge/$1.h Routines for Matrices with Band Storage ======================================= Linear Equation Routines ------------------------ +----------+---------------+----------------------------------------+----------------+ | TYPE | FLENS-LAPACK | DESCRIPTION | LAPACK | +==========+===============+========================================+================+ | General | __sv__ | Solves a general system of linear | __dgbsv__^[1] | | | | equations $AX=B$. | __zgbsv__^[1] | | | | | | | | | *Example:* __lapack-gbsv__. | | + +---------------+----------------------------------------+----------------+ | | __trf__ | Computes an $LU$ factorization of a | __dgbtrf__^[1] | | | | general matrix, using partial pivoting | __zgbtrf__^[1] | | | | with row interchanges. | | | | | | | | | | *Example:* see __lapack-gbtrs__. | | + +---------------+----------------------------------------+----------------+ | | __trs__ | Solves a general system of linear | __dgbtrs__^[1] | | | | equations $AX=B,$ $A^T X=B,$ or | __zgbtrs__^[1] | | | | $A^H X=B,$ using the $LU$ | | | | | factorization. | | | | | | | | | | *Example:* __lapack-gbtrs__. | | +----------+---------------+----------------------------------------+----------------+ | Positive | __pbsv__ | Solves a symmetric positive definite | __dpbsv__^[1] | | Definite | | system of linear equations $AX=B.$ | __zpbsv__^[1] | | | | | | | | | *Example:* __lapack-pbsv__. | | + +---------------+----------------------------------------+----------------+ | | __pbtrf__ | Computes the Cholesky factorization | __dpbtrf__^[1] | | | | of a symmetric positive definite | __zpbtrf__^[1] | | | | matrix. | | | | | | | | | | *Example:* see __lapack-pbtrs__. | | + +---------------+----------------------------------------+----------------+ | | __pbtrs__ | Solves a symmetric positive definite | __dpbtrs__^[1] | | | | system of linear equations $AX=B,$ | __zpbtrs__^[1] | | | | using the Cholesky factorization | | | | | computed by __pbtrf__. | | | | | | | | | | *Example:* __lapack-pbtrs__. | | +----------+---------------+----------------------------------------+----------------+ *Note:* Maybe we should brake with the strict naming scheme and rename functions `pbsv`, `pbtrf`, `pbtrs` just to `posv`, `potrf`, `potrs`. :links: __lapack-gbsv__ -> doc:flens/examples/lapack-gbsv __lapack-gbtrs__ -> doc:flens/examples/lapack-gbtrs __lapack-pbsv__ -> doc:flens/examples/lapack-pbsv __lapack-pbtrs__ -> doc:flens/examples/lapack-pbtrs __(d.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(z.+)__ -> file:cxxlapack/netlib/lapack/$1.f __(pb.+)__ -> doc:flens/lapack/pb/$1 __(.+)__ -> doc:flens/lapack/gb/$1 Related Projects ================ - __LAPACK__ itself of course. - __mpack__ which is also a generic C++ port of LAPACK. To our knowledge the following strategy gets used for porting LAPACK: - __f2c__ is used to create a C implementation of LAPACK - Various scripts (the magic ingredient) are used to create a generic C++ implementation from the C code. This approach has both, advantages and (depending on your own goals) disadvantages: - *Pros:* You have a complete generic C++ port of LAPACK that supports various multiple precision arithmetic libraries like __GMP__, __MPFR__ and __QD__. - *Cons:* The automatic generated code is hard to read (as is typical for f2c-generated code). :links: __LAPACK__ -> http://www.netlib.org/lapack/ __mpack__ -> http://mplapack.sourceforge.net/ __f2c__ -> http://en.wikipedia.org/wiki/F2c __GMP__ -> http://gmplib.org/ __MPFR__ -> http://www.mpfr.org/ __QD__ -> http://crd-legacy.lbl.gov/~dhbailey/mpdist/ Footnotes ========= :footnotes: [1] This functionality is only available through an external LAPACK implementation. See the examples or the __CXXLAPACK__ section of the tutorial for further details on using an external LAPACK. :links: __CXXLAPACK__ -> doc:flens/examples/tut05-page01