Mercurial > hg > octave-lyh
annotate doc/interpreter/linalg.txi @ 17522:b66f068e4468
linsolve.m: Use Octave coding conventions.
* doc/interpreter/linalg.txi: Add linsolve to manual.
* scripts/linear-algebra/linsolve.m: Redo docstring. Use Octave coding conventions.
Add %!error input validation tests.
author | Rik <rik@octave.org> |
---|---|
date | Thu, 26 Sep 2013 09:38:51 -0700 |
parents | f2a8592b8fbd |
children |
rev | line source |
---|---|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
13021
diff
changeset
|
1 @c Copyright (C) 1996-2012 John W. Eaton |
7018 | 2 @c |
3 @c This file is part of Octave. | |
4 @c | |
5 @c Octave is free software; you can redistribute it and/or modify it | |
6 @c under the terms of the GNU General Public License as published by the | |
7 @c Free Software Foundation; either version 3 of the License, or (at | |
8 @c your option) any later version. | |
9 @c | |
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
13 @c for more details. | |
14 @c | |
15 @c You should have received a copy of the GNU General Public License | |
16 @c along with Octave; see the file COPYING. If not, see | |
17 @c <http://www.gnu.org/licenses/>. | |
3294 | 18 |
4167 | 19 @node Linear Algebra |
3294 | 20 @chapter Linear Algebra |
21 | |
22 This chapter documents the linear algebra functions of Octave. | |
23 Reference material for many of these functions may be found in | |
24 Golub and Van Loan, @cite{Matrix Computations, 2nd Ed.}, Johns Hopkins, | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9065
diff
changeset
|
25 1989, and in the @cite{@sc{lapack} Users' Guide}, SIAM, 1992. |
3294 | 26 |
27 @menu | |
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
28 * Techniques Used for Linear Algebra:: |
17160
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
29 * Basic Matrix Functions:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
30 * Matrix Factorizations:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
31 * Functions of a Matrix:: |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
32 * Specialized Solvers:: |
3294 | 33 @end menu |
34 | |
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
35 @node Techniques Used for Linear Algebra |
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
36 @section Techniques Used for Linear Algebra |
6531 | 37 |
8488
cdb4788879b3
[docs] poly-morphic => polymorphic
Brian Gough <bjg@gnu.org>
parents:
8347
diff
changeset
|
38 Octave includes a polymorphic solver, that selects an appropriate |
6531 | 39 matrix factorization depending on the properties of the matrix itself. |
40 Generally, the cost of determining the matrix type is small relative to | |
41 the cost of factorizing the matrix itself, but in any case the matrix | |
42 type is cached once it is calculated, so that it is not re-determined | |
43 each time it is used in a linear equation. | |
44 | |
45 The selection tree for how the linear equation is solve or a matrix | |
46 inverse is form is given by | |
47 | |
48 @enumerate 1 | |
49 @item If the matrix is upper or lower triangular sparse a forward or | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9065
diff
changeset
|
50 backward substitution using the @sc{lapack} xTRTRS function, and goto 4. |
6531 | 51 |
52 @c Permuted triangular matrices currently disabled in the code | |
53 @c | |
54 @c @item If the matrix is a upper triangular matrix with column permutations | |
55 @c or lower triangular matrix with row permutations, perform a forward or | |
56 @c backward substitution, and goto 5. | |
57 | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9709
diff
changeset
|
58 @item If the matrix is square, Hermitian with a real positive diagonal, |
11593
1577c6f80926
Use non-breaking spaces between certain adjectives and their nouns in docstrings.
Rik <octave@nomad.inbox5.com>
parents:
11533
diff
changeset
|
59 attempt Cholesky@tie{}factorization using the @sc{lapack} xPOTRF function. |
6531 | 60 |
11593
1577c6f80926
Use non-breaking spaces between certain adjectives and their nouns in docstrings.
Rik <octave@nomad.inbox5.com>
parents:
11533
diff
changeset
|
61 @item If the Cholesky@tie{}factorization failed or the matrix is not |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9709
diff
changeset
|
62 Hermitian with a real positive diagonal, and the matrix is square, factorize |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9065
diff
changeset
|
63 using the @sc{lapack} xGETRF function. |
6531 | 64 |
9065
8207b833557f
Cleanup documentation for arith.texi, linalg.texi, nonlin.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
65 @item If the matrix is not square, or any of the previous solvers flags |
6531 | 66 a singular or near singular matrix, find a least squares solution using |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9065
diff
changeset
|
67 the @sc{lapack} xGELSD function. |
6531 | 68 @end enumerate |
69 | |
70 The user can force the type of the matrix with the @code{matrix_type} | |
9065
8207b833557f
Cleanup documentation for arith.texi, linalg.texi, nonlin.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
71 function. This overcomes the cost of discovering the type of the matrix. |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7984
diff
changeset
|
72 However, it should be noted that identifying the type of the matrix incorrectly |
6531 | 73 will lead to unpredictable results, and so @code{matrix_type} should be |
74 used with care. | |
75 | |
76 It should be noted that the test for whether a matrix is a candidate for | |
11593
1577c6f80926
Use non-breaking spaces between certain adjectives and their nouns in docstrings.
Rik <octave@nomad.inbox5.com>
parents:
11533
diff
changeset
|
77 Cholesky@tie{}factorization, performed above and by the @code{matrix_type} |
6531 | 78 function, does not give a certainty that the matrix is |
9065
8207b833557f
Cleanup documentation for arith.texi, linalg.texi, nonlin.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
79 Hermitian. However, the attempt to factorize the matrix will quickly |
6531 | 80 flag a non-Hermitian matrix. |
81 | |
4167 | 82 @node Basic Matrix Functions |
3294 | 83 @section Basic Matrix Functions |
84 | |
3373 | 85 @DOCSTRING(balance) |
3294 | 86 |
3373 | 87 @DOCSTRING(cond) |
3294 | 88 |
3373 | 89 @DOCSTRING(det) |
3294 | 90 |
3373 | 91 @DOCSTRING(eig) |
3294 | 92 |
3373 | 93 @DOCSTRING(givens) |
3294 | 94 |
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
95 @DOCSTRING(planerot) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
96 |
3373 | 97 @DOCSTRING(inv) |
3294 | 98 |
17522
b66f068e4468
linsolve.m: Use Octave coding conventions.
Rik <rik@octave.org>
parents:
17160
diff
changeset
|
99 @DOCSTRING(linsolve) |
b66f068e4468
linsolve.m: Use Octave coding conventions.
Rik <rik@octave.org>
parents:
17160
diff
changeset
|
100 |
6531 | 101 @DOCSTRING(matrix_type) |
102 | |
3373 | 103 @DOCSTRING(norm) |
3294 | 104 |
3373 | 105 @DOCSTRING(null) |
3294 | 106 |
3373 | 107 @DOCSTRING(orth) |
3294 | 108 |
12509
e742720c5e71
Add mgorth and gmres functions from Octave Forge
Carlo de Falco <kingcrimson@tiscali.it>
parents:
12188
diff
changeset
|
109 @DOCSTRING(mgorth) |
e742720c5e71
Add mgorth and gmres functions from Octave Forge
Carlo de Falco <kingcrimson@tiscali.it>
parents:
12188
diff
changeset
|
110 |
3373 | 111 @DOCSTRING(pinv) |
3294 | 112 |
3373 | 113 @DOCSTRING(rank) |
3294 | 114 |
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
115 @DOCSTRING(rcond) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
116 |
3373 | 117 @DOCSTRING(trace) |
3294 | 118 |
6502 | 119 @DOCSTRING(rref) |
120 | |
4167 | 121 @node Matrix Factorizations |
3294 | 122 @section Matrix Factorizations |
123 | |
3373 | 124 @DOCSTRING(chol) |
3294 | 125 |
6502 | 126 @DOCSTRING(cholinv) |
127 | |
128 @DOCSTRING(chol2inv) | |
129 | |
7638
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
130 @DOCSTRING(cholupdate) |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
131 |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
132 @DOCSTRING(cholinsert) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
133 |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
134 @DOCSTRING(choldelete) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
135 |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
136 @DOCSTRING(cholshift) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
137 |
3373 | 138 @DOCSTRING(hess) |
3294 | 139 |
3373 | 140 @DOCSTRING(lu) |
3294 | 141 |
9709 | 142 @DOCSTRING(luupdate) |
143 | |
3373 | 144 @DOCSTRING(qr) |
3294 | 145 |
7638
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
146 @DOCSTRING(qrupdate) |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
147 |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
148 @DOCSTRING(qrinsert) |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
149 |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
150 @DOCSTRING(qrdelete) |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7072
diff
changeset
|
151 |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
152 @DOCSTRING(qrshift) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
153 |
3373 | 154 @DOCSTRING(qz) |
3372 | 155 |
3373 | 156 @DOCSTRING(qzhess) |
3294 | 157 |
3373 | 158 @DOCSTRING(schur) |
3294 | 159 |
12188
1e206c8713a7
Add function rsf2csf to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11593
diff
changeset
|
160 @DOCSTRING(rsf2csf) |
1e206c8713a7
Add function rsf2csf to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11593
diff
changeset
|
161 |
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
162 @DOCSTRING(subspace) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
163 |
3373 | 164 @DOCSTRING(svd) |
3294 | 165 |
11533
06c80c90a246
Add undocumented function svd_driver to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
166 @DOCSTRING(svd_driver) |
06c80c90a246
Add undocumented function svd_driver to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
167 |
5775 | 168 @c FIXME -- should there be a new section here? |
3428 | 169 |
170 @DOCSTRING(housh) | |
171 | |
172 @DOCSTRING(krylov) | |
173 | |
4167 | 174 @node Functions of a Matrix |
3294 | 175 @section Functions of a Matrix |
176 | |
3373 | 177 @DOCSTRING(expm) |
3294 | 178 |
3373 | 179 @DOCSTRING(logm) |
3294 | 180 |
3373 | 181 @DOCSTRING(sqrtm) |
3294 | 182 |
3373 | 183 @DOCSTRING(kron) |
3294 | 184 |
12572
dffd30f12752
Add blkmm function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
12520
diff
changeset
|
185 @DOCSTRING(blkmm) |
dffd30f12752
Add blkmm function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
12520
diff
changeset
|
186 |
3373 | 187 @DOCSTRING(syl) |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
188 |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
189 @node Specialized Solvers |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
190 @section Specialized Solvers |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
191 |
13021
d55d396a9a55
Add an implementation of the biconjugate gradient iterative method
Carlo de Falco <kingcrimson@tiscali.it>
parents:
12572
diff
changeset
|
192 @DOCSTRING(bicg) |
d55d396a9a55
Add an implementation of the biconjugate gradient iterative method
Carlo de Falco <kingcrimson@tiscali.it>
parents:
12572
diff
changeset
|
193 |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
194 @DOCSTRING(bicgstab) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
195 |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8488
diff
changeset
|
196 @DOCSTRING(cgs) |
12509
e742720c5e71
Add mgorth and gmres functions from Octave Forge
Carlo de Falco <kingcrimson@tiscali.it>
parents:
12188
diff
changeset
|
197 |
e742720c5e71
Add mgorth and gmres functions from Octave Forge
Carlo de Falco <kingcrimson@tiscali.it>
parents:
12188
diff
changeset
|
198 @DOCSTRING(gmres) |