source: project/release/3/atlas-lapack/trunk/atlas-lapack-eggdoc.scm @ 11067

Last change on this file since 11067 was 11067, checked in by Ivan Raikov, 12 years ago

Added build system support for libraries linked with f2c.

File size: 18.6 KB
Line 
1;;
2;;
3;; atlas-lapack documentation for the Chicken Scheme module system.
4;;
5
6(use eggdoc)
7
8(define doc
9  `((eggdoc:begin
10     (name "atlas-lapack")
11     (description "An interface to the LAPACK routines implemented in ATLAS.")
12     (author (url "http://chicken.wiki.br/ivan raikov" "Ivan Raikov"))
13
14     (history 
15      (version "1.9" "Added build system support for libraries linked with f2c")
16      (version "1.8" "Build script updated for better cross-platform compatibility")
17      (version "1.7" "Fixed a bug in the trtri interface")
18      (version "1.6" "Changed matrix copying code to use BLAS routines instead of object-copy")
19      (version "1.5" "License upgrade to GPL v3")
20      (version "1.4" "Added -latlas to the compiler options in the setup script")
21      (version "1.3" "Minor changes in the setup script")
22      (version "1.2" "Bug fix in the setup script")
23      (version "1.1" "Created safe/unsafe variants of each routine, added optional leading dimensions")
24      (version "1.0" "Initial release"))
25
26     (requires (url "blas.html" "blas"))
27
28     (usage "(require-extension atlas-lapack)")
29
30     (download "atlas-lapack.egg")
31
32     (documentation
33      (p (url "http://math-atlas.sourceforge.net/" "ATLAS") " "
34         "stands for Automatically Tuned Linear Algebra Software. "
35         "Its purpose is to provide portably optimal linear algebra routines. The current version provides a complete " 
36         (url "http://www.netlib.org/blas" "BLAS") " API (for both C and Fortran77), and a very small subset of the " 
37         (url "http://www.netlib.org/lapack" "LAPACK") " API. " "Please see the documentation for the " 
38         (url "blas.html" "blas") " egg for definitions of the ORDER, UPLO, DIAG and TRANSPOSE datatypes.")
39
40      (subsection 
41       "Naming conventions for routines" 
42       
43       (p "Every routine in the LAPACK library comes in four flavors, "
44          "each prefixed by the letters S, D, C, and Z, respectively. " 
45          "Each letter indicates the format of input data: "
46          (ul 
47           (li "S stands for single-precision (32-bit IEEE floating point numbers), ")
48           (li "D stands for double-precision (64-bit IEEE floating point numbers), ")
49           (li "C stands for complex numbers (represented by pairs of 32-bit IEEE floating point numbers), ")
50           (li "Z stands for double complex numbers (represented by pairs of 64-bit IEEE floating point numbers)")))
51       
52       (p "In addition, each ATLAS-LAPACK routine in this egg comes in three flavors: " 
53          (ol (li "Safe, pure (prefix: " (b "atlas-lapack:") ")"
54                  (p (i "Safe") " routines check the sizes of their input arguments. "
55                     "For example, if a routine is supplied arguments that indicate that "
56                     "an input matrix is of dimensions " (i "M") "-by-" (i "N") ", then "
57                     "the argument corresponding to that matrix is checked that it is of size "
58                     (i "M * N") ". ")
59                  (p (i "Pure") " routines do not alter their arguments in any way. "
60                     "A new matrix or vector is allocated for the return value of the routine. "))
61              (li "Safe, destructive (prefix: " (b "atlas-lapack:") ", suffix: !)"
62                  (p (i "Safe") " routines check the sizes of their input arguments. "
63                     "For example, if a routine is supplied arguments that indicate that "
64                     "an input matrix is of dimensions " (i "M") "-by-" (i "N") ", then "
65                     "the argument corresponding to that matrix is checked that it is of size "
66                     (i "M * N") ". ")
67                  (p (i "Destructive") " routines can modify some or all of their arguments. "
68                     "They  are given names ending in exclamation mark. "
69                     "The matrix factorization routines in LAPACK overwrite the input matrix argument "
70                     "with the result of the factorization, and the linear system solvers overwrite "
71                     "the right-hand side vector with the system solution. "
72                     "Please consult the LAPACK documentation to determine which functions modify "
73                     "their input arguments. "))
74              (li "Unsafe, destructive (prefix: " (b "unsafe-atlas-lapack:") ", suffix: !)"
75                  (p (i "Unsafe") " routines do not check the sizes of their input arguments. "
76                     "They invoke the corresponding ATLAS-LAPACK routines directly. "
77                     "Unsafe routines do not have pure variants. "))))
78
79       (p "For example, function " (i "xGESV") " (N-by-N linear system solver) "
80          "comes in the following variants: "
81          (table (tr (th (b "LAPACK name"))
82                     (th (b "Safe, pure")) 
83                     (th (b "Safe, destructive")) 
84                     (th (b "Unsafe, destructive")))
85                 (tr (td (i "SGESV"))
86                     (td (i "atlas-lapack:sgesv"))
87                     (td (i "atlas-lapack:sgesv!"))
88                     (td (i "unsafe-atlas-lapack:sgesv!")))
89                 (tr (td (i "DGESV"))
90                     (td (i "atlas-lapack:dgesv"))
91                     (td (i "atlas-lapack:dgesv!"))
92                     (td (i "unsafe-atlas-lapack:dgesv!")))
93                 (tr (td (i "CGESV"))
94                     (td (i "atlas-lapack:cgesv"))
95                     (td (i "atlas-lapack:cgesv!"))
96                     (td (i "unsafe-atlas-lapack:cgesv!")))
97                 (tr (td (i "ZGESV"))
98                     (td (i "atlas-lapack:zgesv"))
99                     (td (i "atlas-lapack:zgesv!"))
100                     (td (i "unsafe-atlas-lapack:zgesv!"))))))
101             
102      (subsection "LAPACK driver routines" 
103                  (subsubsection "General linear system solving"
104                                 (procedure "atlas-lapack:sgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR * S32VECTOR"
105                                 (procedure "atlas-lapack:dgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR * S32VECTOR")
106                                 (procedure "atlas-lapack:cgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR * S32VECTOR")
107                                 (procedure "atlas-lapack:zgesv:: ORDER * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR * S32VECTOR")
108                                            (p "The routines compute the solution to a system of linear equations "
109                                               (i "A * X = B") ", where " (i "A") " is an N-by-N matrix and " (i "X")
110                                               " and " (i "B") " are N-by-NRHS matrices. "
111                                               "Optional arguments " (i "LDA") " and " (i "LDB") 
112                                               " are the leading dimensions of arrays " (i "A") " and " (i "B") 
113                                               ", respectively. "
114                                               "LU decomposition with partial pivoting and row interchanges "
115                                               "is used to factor " (i "A") " as " (i "A = P * L * U") ", "
116                                               "where " (i "P")  " is a permutation matrix, " (i "L") 
117                                               " is unit lower triangular, and " (i "U") " is upper triangular. "
118                                               "The factored form of " (i "A") " is then used to solve the system. "
119                                               "The return values are: "
120                                               (ol (li "a matrix containing the factors " (i "L") " and " (i "U") 
121                                                       " from the factorization " (i "A = P*L*U") "; " )
122                                                   (li "the N-by-NRHS solution matrix " (i "X"))
123                                                   (li " a vector with pivot indices:  for 1 <= i <= min(M,N), "
124                                                       "row " (i "i") " of the matrix " (i "A") " was interchanged with "
125                                                       "row pivot(" (i "i") ")")))))
126     
127                  (subsubsection "Symmetric positive definite linear system solving"
128                                 (procedure "atlas-lapack:sposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR"
129                                 (procedure "atlas-lapack:dposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR")
130                                 (procedure "atlas-lapack:cposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR * F32VECTOR")
131                                 (procedure "atlas-lapack:zposv:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR * F64VECTOR")
132                                            (p "The routines compute the solution to a system of linear equations "
133                                               (i "A * X = B") ", where " (i "A") 
134                                               " is an N-by-N symmetric positive definite matrix and " (i "X")
135                                               " and " (i "B") " are N-by-NRHS matrices. "
136                                               "Optional arguments " (i "LDA") " and " (i "LDB") 
137                                               " are the leading dimensions of arrays " (i "A") " and " (i "B") 
138                                               ", respectively. "
139                                               "Cholesky decomposition is used to factor " (i "A") " as " 
140                                               (ul (li (i "A = U**T * U")  "     if UPLO = " (b "blas:Upper"))
141                                                   (li (i "A = L  * L**T") "     if UPLO = " (b "blas:Lower")))
142                                               "where " (i "U") " is an upper triangular, and " (i "L") 
143                                               " is a lower triangular matrix. "
144                                               "The factored form of " (i "A") " is then used to solve the system. "
145                                               "The return values are: "
146                                               (ol 
147                                                (li "the factor " (i "U") " or " (i "L") 
148                                                    "from the Cholesky factorization, "
149                                                    "depending on the value of argument UPLO.")
150                                                   (li "the N-by-NRHS solution matrix " (i "X")))))))
151     
152
153      (subsection "LAPACK computational routines"
154                  (subsubsection "General matrix factorization"
155                                 (procedure "atlas-lapack:sgetrf:: ORDER * M * N * A * [LDA] -> F32VECTOR * S32VECTOR"
156                                            (procedure "atlas-lapack:dgetrf:: ORDER * M * N * A * [LDA] -> F64VECTOR * S32VECTOR")
157                                            (procedure "atlas-lapack:cgetrf:: ORDER * M * N * A * [LDA] -> F32VECTOR * S32VECTOR")
158                                            (procedure "atlas-lapack:zgetrf:: ORDER * M * N * A * [LDA] -> F64VECTOR * S32VECTOR")
159                                            (p "These routines compute an LU factorization of a general M-by-N matrix " 
160                                               (i "A") " using partial pivoting with row interchanges. "
161                                               "Optional argument " (i "LDA") " is the leading dimension of array " 
162                                               (i "A") ". "
163                                               "The return values are: "
164                                               (ol (li "a matrix containing the factors " (i "L") " and " (i "U") 
165                                                       " from the factorization " (i "A = P*L*U") "; " )
166                                                   (li " a vector with pivot indices:  for 1 <= i <= min(M,N), "
167                                                       "row " (i "i") " of the matrix was interchanged with "
168                                                       "row pivot(" (i "i") ")")))))
169
170                  (subsubsection "General linear system solving using factorization"
171                                 (procedure "atlas-lapack:sgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR"
172                                            (procedure "atlas-lapack:dgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR")
173                                            (procedure "atlas-lapack:cgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR")
174                                            (procedure "atlas-lapack:zgetrs:: ORDER * TRANSPOSE * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR")
175                                            (p "These routines solve a system of linear equations "
176                                               (i "A * X  = B") " or " (i "A' * X = B") " with a general N-by-N matrix "
177                                               (i "A") " using the LU factorization computed by the xGETRF routines. "
178                                               "Argument " (i "NRHS") " is the number of right-hand sides "
179                                               "(i.e. number of columns in " (i "B") "). "
180                                               "Optional arguments " (i "LDA") " and " (i "LDB") 
181                                               " are the leading dimensions of arrays " (i "A") " and " (i "B") 
182                                               ", respectively. "
183                                               "The return value is the solution matrix " (i "X") ".")))
184
185                  (subsubsection "General matrix invert using factorization"
186                                 (procedure "atlas-lapack:sgetri:: ORDER * N * A * PIVOT * [LDA] -> F32VECTOR"
187                                            (procedure "atlas-lapack:dgetri:: ORDER * N * A * PIVOT * [LDA] -> F64VECTOR")
188                                            (procedure "atlas-lapack:cgetri:: ORDER * N * A * PIVOT * [LDA] -> F32VECTOR")
189                                            (procedure "atlas-lapack:zgetri:: ORDER * N * A * PIVOT * [LDA] -> F64VECTOR")
190                                            (p "These routines compute the inverse of a matrix "
191                                               "using the LU factorization computed by the xGETRF routines. "
192                                               "Argument " (i "A") " must contain the factors L and U from the "
193                                               "LU factorization computed by xGETRF. Argument " (i "PIVOT") " must be "
194                                               "the pivot vector returned by the factorization routine. "
195                                               "Optional argument " (i "LDA") " is the leading dimension of array " 
196                                               (i "A") ". "
197                                               "The return value is the inverse of the original matrix " (i "A") ".")))
198
199                  (subsubsection "Symmetric positive definite matrix factorization"
200                                 (procedure "atlas-lapack:spotrf:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR"
201                                            (procedure "atlas-lapack:dpotrf:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR")
202                                            (procedure "atlas-lapack:cpotrf:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR")
203                                            (procedure "atlas-lapack:zpotrf:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR")
204                                            (p "These routines compute the Cholesky factorization of a "
205                                               "symmetric positive definite matrix " (i "A") ". "
206                                               "The factorization has the form: "
207                                               (ul (li (i "A = U**T * U")  "     if UPLO = " (b "blas:Upper"))
208                                                   (li (i "A = L  * L**T") "     if UPLO = " (b "blas:Lower")))
209                                               "where " (i "U") " is an upper triangular, and " (i "L") 
210                                               " is a lower triangular matrix. "
211                                               "Optional argument " (i "LDA") " is the leading dimension of array " 
212                                               (i "A") ". "
213                                               "The return value is the factor " (i "U") " or " (i "L") 
214                                               "from the Cholesky factorization, "
215                                               "depending on the value of argument UPLO.")))
216
217                  (subsubsection "Symmetric positive definite matrix solving using factorization"
218                                 (procedure "atlas-lapack:spotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR"
219                                            (procedure "atlas-lapack:dpotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR")
220                                            (procedure "atlas-lapack:cpotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F32VECTOR")
221                                            (procedure "atlas-lapack:zpotrs:: ORDER * UPLO * N * NRHS * A * B * [LDA] * [LDB] -> F64VECTOR")
222                                            (p "These routines solve a system of linear equations " 
223                                               (i "A * X = B") " with a  symmetric positive definite matrix " (i "A")
224                                               " using the Cholesky factorization computed by the xPOTRF routines. "
225                                               "Argument " (i "A") " is the triangular factor " (i "U") " or " (i "L")
226                                               " as computed by xPOTRF. "
227                                               "Argument " (i "NRHS") " is the number of right-hand sides "
228                                               "(i.e. number of columns in " (i "B") "). "
229                                               "Argument UPLO indicates whether upper or lower triangle of A is stored "
230                                               "(" (b "blas:Upper") " or " (b "blas:Lower") "). "
231                                               "Optional arguments " (i "LDA") " and " (i "LDB") 
232                                               " are the leading dimensions of arrays " (i "A") " and " (i "B") 
233                                               ", respectively. "
234                                               "The return value is the solution matrix " (i "X") ".")))
235
236                  (subsubsection "Symmetric positive definite matrix invert using factorization"
237                                 (procedure "atlas-lapack:spotri:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR"
238                                            (procedure "atlas-lapack:dpotri:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR")
239                                            (procedure "atlas-lapack:cpotri:: ORDER * UPLO * N * A * [LDA] -> F32VECTOR")
240                                            (procedure "atlas-lapack:zpotri:: ORDER * UPLO * N * A * [LDA] -> F64VECTOR")
241                                           
242                                            (p "These routines compute the inverse of a symmetric positive definite "
243                                               "matrix " (i "A") " using the Cholesky factorization " (i "A = U**T*U") 
244                                               " or " (i "A = L*L**T") " computed by xPOTRF. "
245                                               "Argument " (i "A") " is the triangular factor " (i "U") " or " (i "L")
246                                               " as computed by xPOTRF. "
247                                               "Argument UPLO indicates whether upper or lower triangle of A is stored "
248                                               "(" (b "blas:Upper") " or " (b "blas:Lower") "). "
249                                               "Optional argument " (i "LDA") " is the leading dimension of array " 
250                                               (i "A") ". "
251                                               "The return value is the upper or lower triangle of the inverse of "
252                                               (i "A") ".")))
253                                 
254                  (subsubsection "Triangular matrix invert"
255                                 (procedure "atlas-lapack:strtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR"
256                                 (procedure "atlas-lapack:dtrtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR")
257                                 (procedure "atlas-lapack:ctrtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR")
258                                 (procedure "atlas-lapack:ztrtri:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR")
259                                            (p "These routines compute the inverse of a triangular matrix " (i "A") 
260                                               ". "
261                                               "Argument " (i "A") " is the triangular factor " (i "U") " or " (i "L")
262                                               " as computed by xPOTRF. "
263                                               "Argument UPLO indicates whether upper or lower triangle of A is stored "
264                                               "(" (b "blas:Upper") " or " (b "blas:Lower") "). "
265                                               "Argument DIAG indicates whether A is non-unit triangular or "
266                                               "unit triangular " "(" (b "blas:NonUnit") " or " (b "blas:Unit") "). "
267                                               "Optional argument " (i "LDA") " is the leading dimension of array " 
268                                               (i "A") ". "
269                                               "The return value is the triangular inverse of the input matrix, "
270                                               "in the same storage format.")))
271                                 
272                  (subsubsection "Auxilliary routines"
273                                 (procedure "atlas-lapack:slauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR"
274                                 (procedure "atlas-lapack:dlauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR")
275                                 (procedure "atlas-lapack:clauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F32VECTOR")
276                                 (procedure "atlas-lapack:zlauum:: ORDER * UPLO * DIAG * N * A * [LDA] -> F64VECTOR")
277                                            (p "These routines compute the product " (i "U * U'")  " or " 
278                                               (i "L' * L") ", where the triangular factor " (i "U")  " or " 
279                                               (i "L") " is stored in the upper or lower triangular part of the array " 
280                                               (i "A") ". "
281                                               "Argument UPLO indicates whether upper or lower triangle of A is stored "
282                                               "(" (b "blas:Upper") " or " (b "blas:Lower") "). "
283                                               "Optional argument " (i "LDA") " is the leading dimension of array " 
284                                               (i "A") ". "
285                                               "The return value is the lower triangle of the lower triangular product, "
286                                               " or the upper triangle of upper triangular product, "
287                                               "in the respective storage format.")))
288                                  ))
289
290     (examples (pre #<<EOF
291
292(require-extension srfi-4)
293(require-extension blas)
294(require-extension atlas-lapack)
295
296(define order blas:ColMajor)
297(define n 4)
298(define nrhs 1)
299
300;; Solve the equations
301;;
302;; Ax = b,
303;;
304;; where A is the general matrix
305
306(define A (f64vector 1.8   5.25   1.58 -1.11  ;; column-major order
307                     2.88  -2.95 -2.69 -0.66 
308                     2.05  -0.95 -2.90 -0.59 
309                     -0.89 -3.80 -1.04  0.80))
310;;
311;; and b is
312;;
313(define b (f64vector 9.52 24.35 0.77 -6.22))
314
315;; A and b are not modified
316(define x (atlas-lapack:dgesv order n nrhs A b))
317
318;; A is overwritten with its LU decomposition, and
319;; b is overwritten with the solution of the system
320(atlas-lapack:dgesv! order n nrhs A b)
321
322EOF
323))
324
325     (license
326"Copyright 2007 Ivan Raikov and the Okinawa Institute of Science and Technology
327
328This program is free software: you can redistribute it and/or modify
329it under the terms of the GNU General Public License as published by
330the Free Software Foundation, either version 3 of the License, or (at
331your option) any later version.
332
333This program is distributed in the hope that it will be useful, but
334WITHOUT ANY WARRANTY; without even the implied warranty of
335MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
336General Public License for more details.
337
338A full copy of the GPL license can be found at
339<http://www.gnu.org/licenses/>."))))
340
341
342(if (eggdoc->html doc) (void))
Note: See TracBrowser for help on using the repository browser.