/usr/share/octave/packages/3.2/linear-algebra-2.1.0/doc-cache is in octave-linear-algebra 2.1.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 | # Created by Octave 3.2.4, Mon Dec 05 13:38:35 2011 UTC <root@yellow>
# name: cache
# type: cell
# rows: 3
# columns: 10
# name: <cell-element>
# type: string
# elements: 1
# length: 8
cartprod
# name: <cell-element>
# type: string
# elements: 1
# length: 771
-- Function File: cartprod (VARARGIN )
Computes the cartesian product of given column vectors ( row
vectors ). The vector elements are assumend to be numbers.
Alternatively the vectors can be specified by as a matrix, by its
columns.
To calculate the cartesian product of vectors, P = A x B x C x D
... . Requires A, B, C, D be column vectors. The algorithm is
iteratively calcualte the products, ( ( (A x B ) x C ) x D ) x
etc.
cartprod(1:2,3:4,0:1)
ans = 1 3 0
2 3 0
1 4 0
2 4 0
1 3 1
2 3 1
1 4 1
2 4 1
See also: kron
# name: <cell-element>
# type: string
# elements: 1
# length: 71
Computes the cartesian product of given column vectors ( row vectors ).
# name: <cell-element>
# type: string
# elements: 1
# length: 3
cod
# name: <cell-element>
# type: string
# elements: 1
# length: 885
-- Function File: [Q, R, Z] = cod (A)
-- Function File: [Q, R, Z, P] = cod (A)
-- Function File: [...] = cod (A, '0')
Computes the complete orthogonal decomposition (COD) of the matrix
A:
A = Q*R*Z'
Let A be an M-by-N matrix, and let `K = min(M, N)'. Then Q is
M-by-M orthogonal, Z is N-by-N orthogonal, and R is M-by-N such
that `R(:,1:K)' is upper trapezoidal and `R(:,K+1:N)' is zero.
The additional P output argument specifies that pivoting should be
used in the first step (QR decomposition). In this case,
A*P = Q*R*Z'
If a second argument of '0' is given, an economy-sized
factorization is returned so that R is K-by-K.
NOTE: This is currently implemented by double QR factorization
plus some tricky manipulations, and is not as efficient as using
xRZTZF from LAPACK.
See also: qr
# name: <cell-element>
# type: string
# elements: 1
# length: 80
Computes the complete orthogonal decomposition (COD) of the matrix A:
A =
# name: <cell-element>
# type: string
# elements: 1
# length: 7
condeig
# name: <cell-element>
# type: string
# elements: 1
# length: 784
-- Function File: C = condeig (A)
-- Function File: [V, LAMBDA, C] = condeig (A)
Compute condition numbers of the eigenvalues of a matrix. The
condition numbers are the reciprocals of the cosines of the angles
between the left and right eigenvectors.
Arguments
---------
* A must be a square numeric matrix.
Return values
-------------
* C is a vector of condition numbers of the eigenvalue of A.
* V is the matrix of right eigenvectors of A. The result is the
same as for `[v, lambda] = eig (a)'.
* LAMBDA is the diagonal matrix of eigenvalues of A. The result
is the same as for `[v, lambda] = eig (a)'.
Example
-------
a = [1, 2; 3, 4];
c = condeig (a)
=> [1.0150; 1.0150]
# name: <cell-element>
# type: string
# elements: 1
# length: 57
Compute condition numbers of the eigenvalues of a matrix.
# name: <cell-element>
# type: string
# elements: 1
# length: 4
funm
# name: <cell-element>
# type: string
# elements: 1
# length: 1117
-- Function File: B = funm (A, F)
Compute matrix equivalent of function F; F can be a function name
or a function handle.
For trigonometric and hyperbolic functions, `thfm' is automatically
invoked as that is based on `expm' and diagonalization is avoided.
For other functions diagonalization is invoked, which implies that
-depending on the properties of input matrix A- the results can be
very inaccurate _without any warning_. For easy diagonizable and
stable matrices results of funm will be sufficiently accurate.
Note that you should not use funm for 'sqrt', 'log' or 'exp';
instead use sqrtm, logm and expm as these are more robust.
Examples:
B = funm (A, sin);
(Compute matrix equivalent of sin() )
function bk1 = besselk1 (x)
bk1 = besselk(x, 1);
endfunction
B = funm (A, besselk1);
(Compute matrix equivalent of bessel function K1(); a helper function
is needed here to convey extra args for besselk() )
See also: thfm, expm, logm, sqrtm
# name: <cell-element>
# type: string
# elements: 1
# length: 80
Compute matrix equivalent of function F; F can be a function name or a
function
# name: <cell-element>
# type: string
# elements: 1
# length: 6
lobpcg
# name: <cell-element>
# type: string
# elements: 1
# length: 9717
-- Function File: [BLOCKVECTORX, LAMBDA] = lobpcg (BLOCKVECTORX,
OPERATORA)
-- Function File: [BLOCKVECTORX, LAMBDA, FAILUREFLAG] = lobpcg
(BLOCKVECTORX, OPERATORA)
-- Function File: [BLOCKVECTORX, LAMBDA, FAILUREFLAG, LAMBDAHISTORY,
RESIDUALNORMSHISTORY] = lobpcg (BLOCKVECTORX, OPERATORA, OPERATORB,
OPERATORT, BLOCKVECTORY, RESIDUALTOLERANCE, MAXITERATIONS,
VERBOSITYLEVEL)
Solves Hermitian partial eigenproblems using preconditioning.
The first form outputs the array of algebraic smallest eigenvalues
LAMBDA and corresponding matrix of orthonormalized eigenvectors
BLOCKVECTORX of the Hermitian (full or sparse) operator OPERATORA
using input matrix BLOCKVECTORX as an initial guess, without
preconditioning, somewhat similar to:
# for real symmetric operator operatorA
opts.issym = 1; opts.isreal = 1; K = size (blockVectorX, 2);
[blockVectorX, lambda] = eigs (operatorA, K, 'SR', opts);
# for Hermitian operator operatorA
K = size (blockVectorX, 2);
[blockVectorX, lambda] = eigs (operatorA, K, 'SR');
The second form returns a convergence flag. If FAILUREFLAG is 0
then all the eigenvalues converged; otherwise not all converged.
The third form computes smallest eigenvalues LAMBDA and
corresponding eigenvectors BLOCKVECTORX of the generalized
eigenproblem Ax=lambda Bx, where Hermitian operators OPERATORA and
OPERATORB are given as functions, as well as a preconditioner,
OPERATORT. The operators OPERATORB and OPERATORT must be in
addition _positive definite_. To compute the largest eigenpairs of
OPERATORA, simply apply the code to OPERATORA multiplied by -1.
The code does not involve _any_ matrix factorizations of OPERATORA
and OPERATORB, thus, e.g., it preserves the sparsity and the
structure of OPERATORA and OPERATORB.
RESIDUALTOLERANCE and MAXITERATIONS control tolerance and max
number of steps, and VERBOSITYLEVEL = 0, 1, or 2 controls the
amount of printed info. LAMBDAHISTORY is a matrix with all
iterative lambdas, and RESIDUALNORMSHISTORY are matrices of the
history of 2-norms of residuals
Required input:
* BLOCKVECTORX (class numeric) - initial approximation to
eigenvectors, full or sparse matrix n-by-blockSize.
BLOCKVECTORX must be full rank.
* OPERATORA (class numeric, char, or function_handle) - the
main operator of the eigenproblem, can be a matrix, a
function name, or handle
Optional function input:
* OPERATORB (class numeric, char, or function_handle) - the
second operator, if solving a generalized eigenproblem, can
be a matrix, a function name, or handle; by default if empty,
`operatorB = I'.
* OPERATORT (class char or function_handle) - the
preconditioner, by default `operatorT(blockVectorX) =
blockVectorX'.
Optional constraints input:
* BLOCKVECTORY (class numeric) - a full or sparse n-by-sizeY
matrix of constraints, where sizeY < n. BLOCKVECTORY must be
full rank. The iterations will be performed in the
(operatorB-) orthogonal complement of the column-space of
BLOCKVECTORY.
Optional scalar input parameters:
* RESIDUALTOLERANCE (class numeric) - tolerance, by default,
`residualTolerance = n * sqrt (eps)'
* MAXITERATIONS - max number of iterations, by default,
`maxIterations = min (n, 20)'
* VERBOSITYLEVEL - either 0 (no info), 1, or 2 (with pictures);
by default, `verbosityLevel = 0'.
Required output:
* BLOCKVECTORX and LAMBDA (class numeric) both are computed
blockSize eigenpairs, where `blockSize = size (blockVectorX,
2)' for the initial guess BLOCKVECTORX if it is full rank.
Optional output:
* FAILUREFLAG (class integer) as described above.
* LAMBDAHISTORY (class numeric) as described above.
* RESIDUALNORMSHISTORY (class numeric) as described above.
Functions `operatorA(blockVectorX)', `operatorB(blockVectorX)' and
`operatorT(blockVectorX)' must support BLOCKVECTORX being a
matrix, not just a column vector.
Every iteration involves one application of OPERATORA and
OPERATORB, and one of OPERATORT.
Main memory requirements: 6 (9 if `isempty(operatorB)=0') matrices
of the same size as BLOCKVECTORX, 2 matrices of the same size as
BLOCKVECTORY (if present), and two square matrices of the size
3*blockSize.
In all examples below, we use the Laplacian operator in a 20x20
square with the mesh size 1 which can be generated in MATLAB by
running:
A = delsq (numgrid ('S', 21));
n = size (A, 1);
or in MATLAB and Octave by:
[~,~,A] = laplacian ([19, 19]);
n = size (A, 1);
Note that `laplacian' is a function of the specfun octave-forge
package.
The following Example:
[blockVectorX, lambda, failureFlag] = lobpcg (randn (n, 8), A, 1e-5, 50, 2);
attempts to compute 8 first eigenpairs without preconditioning,
but not all eigenpairs converge after 50 steps, so failureFlag=1.
The next Example:
blockVectorY = [];
lambda_all = [];
for j = 1:4
[blockVectorX, lambda] = lobpcg (randn (n, 2), A, blockVectorY, 1e-5, 200, 2);
blockVectorY = [blockVectorY, blockVectorX];
lambda_all = [lambda_all' lambda']';
pause;
end
attemps to compute the same 8 eigenpairs by calling the code 4
times with blockSize=2 using orthogonalization to the previously
founded eigenvectors.
The following Example:
R = ichol (A, struct('michol', 'on'));
precfun = @(x)R\(R'\x);
[blockVectorX, lambda, failureFlag] = lobpcg (randn (n, 8), A, [], @(x)precfun(x), 1e-5, 60, 2);
computes the same eigenpairs in less then 25 steps, so that
failureFlag=0 using the preconditioner function `precfun', defined
inline. If `precfun' is defined as an octave function in a file,
the function handle `@(x)precfun(x)' can be equivalently replaced
by the function name `precfun'. Running:
[blockVectorX, lambda, failureFlag] = lobpcg (randn (n, 8), A, speye (n), @(x)precfun(x), 1e-5, 50, 2);
produces similar answers, but is somewhat slower and needs more
memory as technically a generalized eigenproblem with B=I is
solved here.
The following example for a mostly diagonally dominant sparse
matrix A demonstrates different types of preconditioning, compared
to the standard use of the main diagonal of A:
clear all; close all;
n = 1000;
M = spdiags ([1:n]', 0, n, n);
precfun = @(x)M\x;
A = M + sprandsym (n, .1);
Xini = randn (n, 5);
maxiter = 15;
tol = 1e-5;
[~,~,~,~,rnp] = lobpcg (Xini, A, tol, maxiter, 1);
[~,~,~,~,r] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
subplot (2,2,1), semilogy (r'); hold on;
semilogy (rnp', ':>');
title ('No preconditioning (top)'); axis tight;
M(1,2) = 2;
precfun = @(x)M\x; % M is no longer symmetric
[~,~,~,~,rns] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
subplot (2,2,2), semilogy (r'); hold on;
semilogy (rns', '--s');
title ('Nonsymmetric preconditioning (square)'); axis tight;
M(1,2) = 0;
precfun = @(x)M\(x+10*sin(x)); % nonlinear preconditioning
[~,~,~,~,rnl] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
subplot (2,2,3), semilogy (r'); hold on;
semilogy (rnl', '-.*');
title ('Nonlinear preconditioning (star)'); axis tight;
M = abs (M - 3.5 * speye (n, n));
precfun = @(x)M\x;
[~,~,~,~,rs] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
subplot (2,2,4), semilogy (r'); hold on;
semilogy (rs', '-d');
title ('Selective preconditioning (diamond)'); axis tight;
References
==========
This main function `lobpcg' is a version of the preconditioned
conjugate gradient method (Algorithm 5.1) described in A. V. Knyazev,
Toward the Optimal Preconditioned Eigensolver: Locally Optimal Block
Preconditioned Conjugate Gradient Method, SIAM Journal on Scientific
Computing 23 (2001), no. 2, pp. 517-541.
`http://dx.doi.org/10.1137/S1064827500366124'
Known bugs/features
===================
* an excessively small requested tolerance may result in often
restarts and instability. The code is not written to produce
an eps-level accuracy! Use common sense.
* the code may be very sensitive to the number of eigenpairs
computed, if there is a cluster of eigenvalues not completely
included, cf.
operatorA = diag ([1 1.99 2:99]);
[blockVectorX, lambda] = lobpcg (randn (100, 1),operatorA, 1e-10, 80, 2);
[blockVectorX, lambda] = lobpcg (randn (100, 2),operatorA, 1e-10, 80, 2);
[blockVectorX, lambda] = lobpcg (randn (100, 3),operatorA, 1e-10, 80, 2);
Distribution
============
The main distribution site: `http://math.ucdenver.edu/~aknyazev/'
A C-version of this code is a part of the
`http://code.google.com/p/blopex/' package and is directly available,
e.g., in PETSc and HYPRE.
# name: <cell-element>
# type: string
# elements: 1
# length: 61
Solves Hermitian partial eigenproblems using preconditioning.
# name: <cell-element>
# type: string
# elements: 1
# length: 7
ndcovlt
# name: <cell-element>
# type: string
# elements: 1
# length: 771
-- Function File: Y = ndcovlt (X, T1, T2, ...)
Computes an n-dimensional covariant linear transform of an n-d
tensor, given a transformation matrix for each dimension. The
number of columns of each transformation matrix must match the
corresponding extent of X, and the number of rows determines the
corresponding extent of Y. For example:
size (X, 2) == columns (T2)
size (Y, 2) == rows (T2)
The element `Y(i1, i2, ...)' is defined as a sum of
X(j1, j2, ...) * T1(i1, j1) * T2(i2, j2) * ...
over all j1, j2, .... For two dimensions, this reduces to
Y = T1 * X * T2.'
[] passed as a transformation matrix is converted to identity
matrix for the corresponding dimension.
# name: <cell-element>
# type: string
# elements: 1
# length: 80
Computes an n-dimensional covariant linear transform of an n-d tensor,
given a t
# name: <cell-element>
# type: string
# elements: 1
# length: 9
rotparams
# name: <cell-element>
# type: string
# elements: 1
# length: 466
-- Function File: [VSTACKED, ASTACKED] = rotparams ( rstacked )
The function w = rotparams (r) - Inverse to rotv().
Using, W = rotparams(R) is such that rotv(w)*r' == eye(3).
If used as, [v,a]=rotparams(r) , idem, with v (1 x 3) s.t. w ==
a*v.
0 <= norm(w)==a <= pi
:-O !! Does not check if 'r' is a rotation matrix.
Ignores matrices with zero rows or with NaNs. (returns 0 for them)
See also: rotv
# name: <cell-element>
# type: string
# elements: 1
# length: 62
The function w = rotparams (r) - Inverse to rotv().
# name: <cell-element>
# type: string
# elements: 1
# length: 4
rotv
# name: <cell-element>
# type: string
# elements: 1
# length: 500
-- Function File: R = rotv ( v, ang )
The functionrotv calculates a Matrix of rotation about V w/ angle
|v| r = rotv(v [,ang])
Returns the rotation matrix w/ axis v, and angle, in radians,
norm(v) or ang (if present).
rotv(v) == w'*w + cos(a) * (eye(3)-w'*w) - sin(a) * crossmat(w)
where a = norm (v) and w = v/a.
v and ang may be vertically stacked : If 'v' is 2x3, then rotv( v
) == [rotv(v(1,:)); rotv(v(2,:))]
See also: rotparams, rota, rot
# name: <cell-element>
# type: string
# elements: 1
# length: 80
The functionrotv calculates a Matrix of rotation about V w/ angle |v| r
= rotv(v
# name: <cell-element>
# type: string
# elements: 1
# length: 8
smwsolve
# name: <cell-element>
# type: string
# elements: 1
# length: 614
-- Function File: X = smwsolve (A, U, V, B)
-- Function File: smwsolve (SOLVER, U, V, B)
Solves the square system `(A + U*V')*X == B', where U and V are
matrices with several columns, using the Sherman-Morrison-Woodbury
formula, so that a system with A as left-hand side is actually
solved. This is especially advantageous if A is diagonal, sparse,
triangular or positive definite. A can be sparse or full, the
other matrices are expected to be full. Instead of a matrix A, a
user may alternatively provide a function SOLVER that performs the
left division operation.
# name: <cell-element>
# type: string
# elements: 1
# length: 80
Solves the square system `(A + U*V')*X == B', where U and V are
matrices with se
# name: <cell-element>
# type: string
# elements: 1
# length: 4
thfm
# name: <cell-element>
# type: string
# elements: 1
# length: 692
-- Function File: Y = thfm (X, MODE)
Trigonometric/hyperbolic functions of square matrix X.
MODE must be the name of a function. Valid functions are 'sin',
'cos', 'tan', 'sec', 'csc', 'cot' and all their inverses and/or
hyperbolic variants, and 'sqrt', 'log' and 'exp'.
The code `thfm (x, 'cos')' calculates matrix cosinus _even if_
input matrix X is _not_ diagonalizable.
_Important note_: This algorithm does _not_ use an eigensystem
similarity transformation. It maps the MODE functions to functions
of `expm', `logm' and `sqrtm', which are known to be robust with
respect to non-diagonalizable ('defective') X.
See also: funm
# name: <cell-element>
# type: string
# elements: 1
# length: 54
Trigonometric/hyperbolic functions of square matrix X.
|