atlas-lapack

An interface to the LAPACK routines implemented in ATLAS.

  1. atlas-lapack
  2. Usage
  3. Documentation
    1. Naming conventions for routines
    2. LAPACK driver routines
      1. General linear system solving
      2. Symmetric positive definite linear system solving
    3. LAPACK computational routines
      1. General matrix factorization
      2. General linear system solving using factorization
      3. General matrix invert using factorization
      4. Symmetric positive definite matrix factorization
      5. Symmetric positive definite matrix solving using factorization
      6. Symmetric positive definite matrix invert using factorization
      7. Triangular matrix invert
      8. Auxilliary routines
  4. Examples
  5. About this egg
    1. Author
    2. Version history
    3. Requirements
    4. License

Usage

(require-extension atlas-lapack)

Documentation

ATLAS stands for Automatically Tuned Linear Algebra Software. Its purpose is to provide portably optimal linear algebra routines. The current version provides a complete BLAS API (for both C and Fortran77), and a very small subset of the LAPACK API. Please see the documentation for the blas egg for definitions of the ORDER, UPLO, DIAG and TRANSPOSE datatypes.

Naming conventions for routines

Every routine in the LAPACK library comes in four flavors, each prefixed by the letters S, D, C, and Z, respectively. Each letter indicates the format of input data:

In addition, each ATLAS-LAPACK routine in this egg comes in three flavors:

Pure routines do not alter their arguments in any way. A new matrix or vector is allocated for the return value of the routine.

Destructive routines can modify some or all of their arguments. They are given names ending in exclamation mark. The matrix factorization routines in LAPACK overwrite the input matrix argument with the result of the factorization, and the linear system solvers overwrite the right-hand side vector with the system solution. Please consult the LAPACK documentation to determine which functions modify their input arguments.

For example, function xGESV (N-by-N linear system solver) comes in the following variants:

LAPACK name Safe, pure Safe, destructive Unsafe, destructive
SGESV sgesv sgesv! unsafe-sgesv!
DGESV dgesv dgesv! unsafe-dgesv!
CGESV cgesv cgesv! unsafe-cgesv!
ZGESV zgesv zgesv! unsafe-zgesv!

LAPACK driver routines

General linear system solving

[procedure] sgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR * S32VECTOR
[procedure] dgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR * S32VECTOR
[procedure] cgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR * S32VECTOR
[procedure] zgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR * S32VECTOR

The routines compute the solution to a system of linear equations ''A

Symmetric positive definite linear system solving

[procedure] sposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR
[procedure] dposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR
[procedure] cposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR
[procedure] zposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR

The routines compute the solution to a system of linear equations ''A

LAPACK computational routines

General matrix factorization

[procedure] sgetrf:: ORDER * M * N * A * [LDA] -> F32VECTOR * S32VECTOR
[procedure] dgetrf:: ORDER * M * N * A * [LDA] -> F64VECTOR * S32VECTOR
[procedure] cgetrf:: ORDER * M * N * A * [LDA] -> F32VECTOR * S32VECTOR
[procedure] zgetrf:: ORDER * M * N * A * [LDA] -> F64VECTOR * S32VECTOR

These routines compute an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges. Optional argument LDA is the leading dimension of array A. The return values are:

  1. a matrix containing the factors L and U from the factorization A = P*L*U;
  2. a vector with pivot indices: for 1 <= i <= min(M,N), row i of the matrix was interchanged with row pivot(i)

General linear system solving using factorization

[procedure] sgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR
[procedure] dgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR
[procedure] cgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR
[procedure] zgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR

These routines solve a system of linear equations A * X = B or A' * X = B with a general N-by-N matrix A using the LU factorization computed by the xGETRF routines. Argument NRHS is the number of right-hand sides (i.e. number of columns in B). Optional arguments LDA and LDB are the leading dimensions of arrays A and B, respectively. The return value is the solution matrix X.

General matrix invert using factorization

[procedure] sgetri:: ORDER * N * A * PIVOT * [LDA] -> F32VECTOR
[procedure] dgetri:: ORDER * N * A * PIVOT * [LDA] -> F64VECTOR
[procedure] cgetri:: ORDER * N * A * PIVOT * [LDA] -> F32VECTOR
[procedure] zgetri:: ORDER * N * A * PIVOT * [LDA] -> F64VECTOR

These routines compute the inverse of a matrix using the LU factorization computed by the xGETRF routines. Argument A must contain the factors L and U from the LU factorization computed by xGETRF. Argument PIVOT must be the pivot vector returned by the factorization routine. Optional argument LDA is the leading dimension of array A. The return value is the inverse of the original matrix A.

Symmetric positive definite matrix factorization

[procedure] spotrf:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR
[procedure] dpotrf:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR
[procedure] cpotrf:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR
[procedure] zpotrf:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR

These routines compute the Cholesky factorization of a symmetric positive definite matrix A. The factorization has the form:

Symmetric positive definite matrix solving using factorization

[procedure] spotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR
[procedure] dpotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR
[procedure] cpotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR
[procedure] zpotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR

These routines solve a system of linear equations A * X = B with a symmetric positive definite matrix A using the Cholesky factorization computed by the xPOTRF routines. Argument A is the triangular factor U or L as computed by xPOTRF. Argument NRHS is the number of right-hand sides (i.e. number of columns in B). Argument UPLO indicates whether upper or lower triangle of A is stored (Upper or Lower). Optional arguments LDA and LDB are the leading dimensions of arrays A and B, respectively. The return value is the solution matrix X.

Symmetric positive definite matrix invert using factorization

[procedure] spotri:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR
[procedure] dpotri:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR
[procedure] cpotri:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR
[procedure] zpotri:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR

These routines compute the inverse of a symmetric positive definite matrix A using the Cholesky factorization A = U**T*U or A = L*L**T computed by xPOTRF. Argument A is the triangular factor U or L as computed by xPOTRF. Argument UPLO indicates whether upper or lower triangle of A is stored (Upper or Lower). Optional argument LDA is the leading dimension of array A. The return value is the upper or lower triangle of the inverse of A.

Triangular matrix invert

[procedure] strtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR
[procedure] dtrtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR
[procedure] ctrtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR
[procedure] ztrtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR

These routines compute the inverse of a triangular matrix A. Argument A is the triangular factor U or L as computed by xPOTRF. Argument UPLO indicates whether upper or lower triangle of A is stored (Upper or Lower). Argument DIAG indicates whether A is non-unit triangular or unit triangular (NonUnit or Unit). Optional argument LDA is the leading dimension of array A. The return value is the triangular inverse of the input matrix, in the same storage format.

Auxilliary routines

[procedure] slauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR
[procedure] dlauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR
[procedure] clauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR
[procedure] zlauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR

These routines compute the product U * U' or L' * L, where the triangular factor U or L is stored in the upper or lower triangular part of the array A. Argument UPLO indicates whether upper or lower triangle of A is stored (Upper or Lower'). Optional argument LDA is the leading dimension of array A. The return value is the lower triangle of the lower triangular product, or the upper triangle of upper triangular product, in the respective storage format.

Examples


(use srfi-4 blas atlas-lapack)

(define order ColMajor)
(define n 4)
(define nrhs 1)

;; Solve the equations
;;
;; Ax = b,
;;
;; where A is the general matrix

(define A (f64vector 1.8   5.25   1.58 -1.11  ;; column-major order
		     2.88  -2.95 -2.69 -0.66 
		     2.05  -0.95 -2.90 -0.59 
		     -0.89 -3.80 -1.04  0.80))
;;
;; and b is
;;
(define b (f64vector 9.52 24.35 0.77 -6.22))

;; A and b are not modified
(define-values (LU x piv) (dgesv order n nrhs A b))

;; A is overwritten with its LU decomposition, and 
;; b is overwritten with the solution of the system
(dgesv! order n nrhs A b)

About this egg

Author

Ivan Raikov

Version history

3.0
Using bind instead of easyffi
2.1
Ensure that unit test script exists with a non-zero exit status on error (thanks to mario)
2.0
Eliminated reduntant atlas-lapack: prefix from names of exported symbols
1.12
Switched to wiki documentation
1.11
Ported to Chicken 4
1.10
Bug fix in the detection of ATLAS library
1.9
Added build system support for libraries linked with f2c
1.8
Build script updated for better cross-platform compatibility
1.7
Fixed a bug in the trtri interface
1.6
Changed matrix copying code to use BLAS routines instead of object-copy
1.5
License upgrade to GPL v3
1.4
Added -latlas to the compiler options in the setup script
1.3
Minor changes in the setup script
1.2
Bug fix in the setup script
1.1
Created safe/unsafe variants of each routine, added optional leading dimensions
1.0
Initial release

Requirements

blas

License

Copyright 2007-2012 Ivan Raikov and the Okinawa Institute of Science and Technology

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.