1math::linearalgebra(n)         Tcl Math Library         math::linearalgebra(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       math::linearalgebra - Linear Algebra
9

SYNOPSIS

11       package require Tcl  ?8.4?
12
13       package require math::linearalgebra  ?1.1.5?
14
15       ::math::linearalgebra::mkVector ndim value
16
17       ::math::linearalgebra::mkUnitVector ndim ndir
18
19       ::math::linearalgebra::mkMatrix nrows ncols value
20
21       ::math::linearalgebra::getrow matrix row ?imin? ?imax?
22
23       ::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?
24
25       ::math::linearalgebra::getcol matrix col ?imin? ?imax?
26
27       ::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?
28
29       ::math::linearalgebra::getelem matrix row col
30
31       ::math::linearalgebra::setelem matrix row ?col? newvalue
32
33       ::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?
34
35       ::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?
36
37       ::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?
38
39       ::math::linearalgebra::dim obj
40
41       ::math::linearalgebra::shape obj
42
43       ::math::linearalgebra::conforming type obj1 obj2
44
45       ::math::linearalgebra::symmetric matrix ?eps?
46
47       ::math::linearalgebra::norm vector type
48
49       ::math::linearalgebra::norm_one vector
50
51       ::math::linearalgebra::norm_two vector
52
53       ::math::linearalgebra::norm_max vector ?index?
54
55       ::math::linearalgebra::normMatrix matrix type
56
57       ::math::linearalgebra::dotproduct vect1 vect2
58
59       ::math::linearalgebra::unitLengthVector vector
60
61       ::math::linearalgebra::normalizeStat mv
62
63       ::math::linearalgebra::axpy scale mv1 mv2
64
65       ::math::linearalgebra::add mv1 mv2
66
67       ::math::linearalgebra::sub mv1 mv2
68
69       ::math::linearalgebra::scale scale mv
70
71       ::math::linearalgebra::rotate c s vect1 vect2
72
73       ::math::linearalgebra::transpose matrix
74
75       ::math::linearalgebra::matmul mv1 mv2
76
77       ::math::linearalgebra::angle vect1 vect2
78
79       ::math::linearalgebra::crossproduct vect1 vect2
80
81       ::math::linearalgebra::matmul mv1 mv2
82
83       ::math::linearalgebra::mkIdentity size
84
85       ::math::linearalgebra::mkDiagonal diag
86
87       ::math::linearalgebra::mkRandom size
88
89       ::math::linearalgebra::mkTriangular size ?uplo? ?value?
90
91       ::math::linearalgebra::mkHilbert size
92
93       ::math::linearalgebra::mkDingdong size
94
95       ::math::linearalgebra::mkOnes size
96
97       ::math::linearalgebra::mkMoler size
98
99       ::math::linearalgebra::mkFrank size
100
101       ::math::linearalgebra::mkBorder size
102
103       ::math::linearalgebra::mkWilkinsonW+ size
104
105       ::math::linearalgebra::mkWilkinsonW- size
106
107       ::math::linearalgebra::solveGauss matrix bvect
108
109       ::math::linearalgebra::solvePGauss matrix bvect
110
111       ::math::linearalgebra::solveTriangular matrix bvect ?uplo?
112
113       ::math::linearalgebra::solveGaussBand matrix bvect
114
115       ::math::linearalgebra::solveTriangularBand matrix bvect
116
117       ::math::linearalgebra::determineSVD A eps
118
119       ::math::linearalgebra::eigenvectorsSVD A eps
120
121       ::math::linearalgebra::leastSquaresSVD A y qmin eps
122
123       ::math::linearalgebra::choleski matrix
124
125       ::math::linearalgebra::orthonormalizeColumns matrix
126
127       ::math::linearalgebra::orthonormalizeRows matrix
128
129       ::math::linearalgebra::dger matrix alpha x y ?scope?
130
131       ::math::linearalgebra::dgetrf matrix
132
133       ::math::linearalgebra::det matrix
134
135       ::math::linearalgebra::largesteigen matrix tolerance maxiter
136
137       ::math::linearalgebra::to_LA mv
138
139       ::math::linearalgebra::from_LA mv
140
141______________________________________________________________________________
142

DESCRIPTION

144       This package offers both low-level procedures and high-level algorithms
145       to deal with linear algebra problems:
146
147       ·      robust solution of linear equations or least squares problems
148
149       ·      determining eigenvectors and eigenvalues of symmetric matrices
150
151       ·      various decompositions of general matrices or matrices of a spe‐
152              cific form
153
154       ·      (limited) support for matrices in band storage, a common type of
155              sparse matrices
156
157       It arose as a re-implementation of Hume's LA package and the desire  to
158       offer  low-level  procedures  as  found in the well-known BLAS library.
159       Matrices are implemented as lists of lists  rather  linear  lists  with
160       reserved  elements, as in the original LA package, as it was found that
161       such an implementation is actually faster.
162
163       It is advisable, however, to use the procedures that are offered,  such
164       as  setrow  and getrow, rather than rely on this representation explic‐
165       itly: that way it is to switch  to  a  possibly  even  faster  compiled
166       implementation that supports the same API.
167
168       Note:  When  using  this package in combination with Tk, there may be a
169       naming conflict, as both this package and Tk define  a  command  scale.
170       See the NAMING CONFLICT section below.
171

PROCEDURES

173       The  package  defines the following public procedures (several exist as
174       specialised procedures, see below):
175
176       Constructing matrices and vectors
177
178       ::math::linearalgebra::mkVector ndim value
179              Create a vector with ndim elements, each with the value value.
180
181              integer ndim
182                     Dimension of the vector (number of components)
183
184              double value
185                     Uniform value to be used (default: 0.0)
186
187
188       ::math::linearalgebra::mkUnitVector ndim ndir
189              Create a unit vector in ndim-dimensional space, along the  ndir-
190              th direction.
191
192              integer ndim
193                     Dimension of the vector (number of components)
194
195              integer ndir
196                     Direction (0, ..., ndim-1)
197
198
199       ::math::linearalgebra::mkMatrix nrows ncols value
200              Create  a matrix with nrows rows and ncols columns. All elements
201              have the value value.
202
203              integer nrows
204                     Number of rows
205
206              integer ncols
207                     Number of columns
208
209              double value
210                     Uniform value to be used (default: 0.0)
211
212
213       ::math::linearalgebra::getrow matrix row ?imin? ?imax?
214              Returns a single row of a matrix as a list
215
216              list matrix
217                     Matrix in question
218
219              integer row
220                     Index of the row to return
221
222              integer imin
223                     Minimum index of the column (default: 0)
224
225              integer imax
226                     Maximum index of the column (default: ncols-1)
227
228
229       ::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?
230              Set a single row of a matrix to new values (this list must  have
231              the  same  number  of  elements  as the number of columns in the
232              matrix)
233
234              list matrix
235                     name of the matrix in question
236
237              integer row
238                     Index of the row to update
239
240              list newvalues
241                     List of new values for the row
242
243              integer imin
244                     Minimum index of the column (default: 0)
245
246              integer imax
247                     Maximum index of the column (default: ncols-1)
248
249
250       ::math::linearalgebra::getcol matrix col ?imin? ?imax?
251              Returns a single column of a matrix as a list
252
253              list matrix
254                     Matrix in question
255
256              integer col
257                     Index of the column to return
258
259              integer imin
260                     Minimum index of the row (default: 0)
261
262              integer imax
263                     Maximum index of the row (default: nrows-1)
264
265
266       ::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?
267              Set a single column of a matrix to new values  (this  list  must
268              have  the  same  number of elements as the number of rows in the
269              matrix)
270
271              list matrix
272                     name of the matrix in question
273
274              integer col
275                     Index of the column to update
276
277              list newvalues
278                     List of new values for the column
279
280              integer imin
281                     Minimum index of the row (default: 0)
282
283              integer imax
284                     Maximum index of the row (default: nrows-1)
285
286
287       ::math::linearalgebra::getelem matrix row col
288              Returns a single element of a matrix/vector
289
290              list matrix
291                     Matrix or vector in question
292
293              integer row
294                     Row of the element
295
296              integer col
297                     Column of the element (not present for vectors)
298
299
300       ::math::linearalgebra::setelem matrix row ?col? newvalue
301              Set a single element of a matrix (or vector) to a new value
302
303              list matrix
304                     name of the matrix in question
305
306              integer row
307                     Row of the element
308
309              integer col
310                     Column of the element (not present for vectors)
311
312
313       ::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?
314              Swap two rows in a matrix completely or only a selected part
315
316              list matrix
317                     name of the matrix in question
318
319              integer irow1
320                     Index of first row
321
322              integer irow2
323                     Index of second row
324
325              integer imin
326                     Minimum column index (default: 0)
327
328              integer imin
329                     Maximum column index (default: ncols-1)
330
331
332       ::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?
333              Swap two columns in a matrix completely or only a selected part
334
335              list matrix
336                     name of the matrix in question
337
338              integer irow1
339                     Index of first column
340
341              integer irow2
342                     Index of second column
343
344              integer imin
345                     Minimum row index (default: 0)
346
347              integer imin
348                     Maximum row index (default: nrows-1)
349
350       Querying matrices and vectors
351
352       ::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?
353              Return a string representing the  vector  or  matrix,  for  easy
354              printing.   (There  is  currently  no way to print fixed sets of
355              columns)
356
357              list obj
358                     Matrix or vector in question
359
360              string format
361                     Format for printing the numbers (default: %6.4f)
362
363              string rowsep
364                     String to use for separating rows (default: newline)
365
366              string colsep
367                     String to use for separating columns (default: space)
368
369
370       ::math::linearalgebra::dim obj
371              Returns the number of dimensions for the object (either 0 for  a
372              scalar, 1 for a vector and 2 for a matrix)
373
374              any obj
375                     Scalar, vector, or matrix
376
377
378       ::math::linearalgebra::shape obj
379              Returns  the number of elements in each dimension for the object
380              (either an empty list for a scalar, a single number for a vector
381              and a list of the number of rows and columns for a matrix)
382
383              any obj
384                     Scalar, vector, or matrix
385
386
387       ::math::linearalgebra::conforming type obj1 obj2
388              Checks if two objects (vector or matrix) have conforming shapes,
389              that is if they can be applied in an operation like addition  or
390              matrix multiplication.
391
392              string type
393                     Type of check:
394
395                     ·      "shape" - the two objects have the same shape (for
396                            all element-wise operations)
397
398                     ·      "rows" - the two objects have the same  number  of
399                            rows  (for  use  as  A and b in a system of linear
400                            equations Ax = b
401
402                     ·      "matmul" - the first object has the same number of
403                            columns  as  the  number  of  rows  of  the second
404                            object. Useful for matrix-matrix or  matrix-vector
405                            multiplication.
406
407              list obj1
408                     First vector or matrix (left operand)
409
410              list obj2
411                     Second vector or matrix (right operand)
412
413
414       ::math::linearalgebra::symmetric matrix ?eps?
415              Checks  if  the given (square) matrix is symmetric. The argument
416              eps is the tolerance.
417
418              list matrix
419                     Matrix to be inspected
420
421              float eps
422                     Tolerance for determining approximate equality  (defaults
423                     to 1.0e-8)
424
425       Basic operations
426
427       ::math::linearalgebra::norm vector type
428              Returns  the norm of the given vector. The type argument can be:
429              1, 2, inf or max, respectively the sum of absolute  values,  the
430              ordinary Euclidean norm or the max norm.
431
432              list vector
433                     Vector, list of coefficients
434
435              string type
436                     Type of norm (default: 2, the Euclidean norm)
437
438       ::math::linearalgebra::norm_one vector
439              Returns  the  L1  norm  of the given vector, the sum of absolute
440              values
441
442              list vector
443                     Vector, list of coefficients
444
445       ::math::linearalgebra::norm_two vector
446              Returns the L2 norm of the given vector, the ordinary  Euclidean
447              norm
448
449              list vector
450                     Vector, list of coefficients
451
452       ::math::linearalgebra::norm_max vector ?index?
453              Returns  the Linf norm of the given vector, the maximum absolute
454              coefficient
455
456              list vector
457                     Vector, list of coefficients
458
459              integer index
460                     (optional) if non zero, returns a list made of the  maxi‐
461                     mum value and the index where that maximum was found.  if
462                     zero, returns the maximum value.
463
464
465       ::math::linearalgebra::normMatrix matrix type
466              Returns the norm of the given matrix. The type argument can  be:
467              1,  2,  inf or max, respectively the sum of absolute values, the
468              ordinary Euclidean norm or the max norm.
469
470              list matrix
471                     Matrix, list of row vectors
472
473              string type
474                     Type of norm (default: 2, the Euclidean norm)
475
476
477       ::math::linearalgebra::dotproduct vect1 vect2
478              Determine the inproduct or dot product  of  two  vectors.  These
479              must have the same shape (number of dimensions)
480
481              list vect1
482                     First vector, list of coefficients
483
484              list vect2
485                     Second vector, list of coefficients
486
487
488       ::math::linearalgebra::unitLengthVector vector
489              Return a vector in the same direction with length 1.
490
491              list vector
492                     Vector to be normalized
493
494
495       ::math::linearalgebra::normalizeStat mv
496              Normalize  the matrix or vector in a statistical sense: the mean
497              of the elements of the columns of the result  is  zero  and  the
498              standard deviation is 1.
499
500              list mv
501                     Vector or matrix to be normalized in the above sense
502
503
504       ::math::linearalgebra::axpy scale mv1 mv2
505              Return a vector or matrix that results from a "daxpy" operation,
506              that is: compute a*x+y (a a scalar and x and y both  vectors  or
507              matrices of the same shape) and return the result.
508
509              Specialised  variants  are:  axpy_vect  and  axpy_mat  (slightly
510              faster, but no check on the arguments)
511
512              double scale
513                     The scale factor for the first vector/matrix (a)
514
515              list mv1
516                     First vector or matrix (x)
517
518              list mv2
519                     Second vector or matrix (y)
520
521
522       ::math::linearalgebra::add mv1 mv2
523              Return a vector or matrix that is the sum of the  two  arguments
524              (x+y)
525
526              Specialised variants are: add_vect and add_mat (slightly faster,
527              but no check on the arguments)
528
529              list mv1
530                     First vector or matrix (x)
531
532              list mv2
533                     Second vector or matrix (y)
534
535
536       ::math::linearalgebra::sub mv1 mv2
537              Return a vector or matrix that is  the  difference  of  the  two
538              arguments (x-y)
539
540              Specialised variants are: sub_vect and sub_mat (slightly faster,
541              but no check on the arguments)
542
543              list mv1
544                     First vector or matrix (x)
545
546              list mv2
547                     Second vector or matrix (y)
548
549
550       ::math::linearalgebra::scale scale mv
551              Scale a vector or matrix and return the result, that is: compute
552              a*x.
553
554              Specialised  variants  are:  scale_vect  and scale_mat (slightly
555              faster, but no check on the arguments)
556
557              double scale
558                     The scale factor for the vector/matrix (a)
559
560              list mv
561                     Vector or matrix (x)
562
563
564       ::math::linearalgebra::rotate c s vect1 vect2
565              Apply a planar rotation to two vectors and return the result  as
566              a  list  of  two vectors: c*x-s*y and s*x+c*y. In algorithms you
567              can often easily determine the cosine and sine of the angle,  so
568              it is more efficient to pass that information directly.
569
570              double c
571                     The cosine of the angle
572
573              double s
574                     The sine of the angle
575
576              list vect1
577                     First vector (x)
578
579              list vect2
580                     Seocnd vector (x)
581
582
583       ::math::linearalgebra::transpose matrix
584              Transpose a matrix
585
586              list matrix
587                     Matrix to be transposed
588
589
590       ::math::linearalgebra::matmul mv1 mv2
591              Multiply  a vector/matrix with another vector/matrix. The result
592              is a matrix, if both x and y are matrices or both  are  vectors,
593              in  which case the "outer product" is computed. If one is a vec‐
594              tor and the other is a matrix, then the result is a vector.
595
596              list mv1
597                     First vector/matrix (x)
598
599              list mv2
600                     Second vector/matrix (y)
601
602
603       ::math::linearalgebra::angle vect1 vect2
604              Compute the angle between two vectors (in radians)
605
606              list vect1
607                     First vector
608
609              list vect2
610                     Second vector
611
612
613       ::math::linearalgebra::crossproduct vect1 vect2
614              Compute the cross product of two (three-dimensional) vectors
615
616              list vect1
617                     First vector
618
619              list vect2
620                     Second vector
621
622
623       ::math::linearalgebra::matmul mv1 mv2
624              Multiply a vector/matrix with another vector/matrix. The  result
625              is  a  matrix, if both x and y are matrices or both are vectors,
626              in which case the "outer product" is computed. If one is a  vec‐
627              tor and the other is a matrix, then the result is a vector.
628
629              list mv1
630                     First vector/matrix (x)
631
632              list mv2
633                     Second vector/matrix (y)
634
635       Common matrices and test matrices
636
637       ::math::linearalgebra::mkIdentity size
638              Create an identity matrix of dimension size.
639
640              integer size
641                     Dimension of the matrix
642
643
644       ::math::linearalgebra::mkDiagonal diag
645              Create  a  diagonal  matrix whose diagonal elements are the ele‐
646              ments of the vector diag.
647
648              list diag
649                     Vector whose elements are used for the diagonal
650
651
652       ::math::linearalgebra::mkRandom size
653              Create a square matrix whose elements are uniformly  distributed
654              random numbers between 0 and 1 of dimension size.
655
656              integer size
657                     Dimension of the matrix
658
659
660       ::math::linearalgebra::mkTriangular size ?uplo? ?value?
661              Create  a  triangular matrix with non-zero elements in the upper
662              or lower part, depending on argument uplo.
663
664              integer size
665                     Dimension of the matrix
666
667              string uplo
668                     Fill the upper (U) or lower part (L)
669
670              double value
671                     Value to fill the matrix with
672
673
674       ::math::linearalgebra::mkHilbert size
675              Create a Hilbert matrix of dimension size.  Hilbert matrices are
676              very  ill-conditioned  with  respect  to  eigenvalue/eigenvector
677              problems. Therefore they are good  candidates  for  testing  the
678              accuracy of algorithms and implementations.
679
680              integer size
681                     Dimension of the matrix
682
683
684       ::math::linearalgebra::mkDingdong size
685              Create a "dingdong" matrix of dimension size.  Dingdong matrices
686              are imprecisely represented, but have the property of being very
687              stable in such algorithms as Gauss elimination.
688
689              integer size
690                     Dimension of the matrix
691
692
693       ::math::linearalgebra::mkOnes size
694              Create  a  square matrix of dimension size whose entries are all
695              1.
696
697              integer size
698                     Dimension of the matrix
699
700
701       ::math::linearalgebra::mkMoler size
702              Create a Moler matrix of size size. (Moler matrices have a  very
703              simple  Choleski  decomposition. It has one small eigenvalue and
704              it can easily upset elimination methods for  systems  of  linear
705              equations.)
706
707              integer size
708                     Dimension of the matrix
709
710
711       ::math::linearalgebra::mkFrank size
712              Create  a  Frank matrix of size size. (Frank matrices are fairly
713              well-behaved matrices)
714
715              integer size
716                     Dimension of the matrix
717
718
719       ::math::linearalgebra::mkBorder size
720              Create a bordered matrix of size size. (Bordered matrices have a
721              very low rank and can upset certain specialised algorithms.)
722
723              integer size
724                     Dimension of the matrix
725
726
727       ::math::linearalgebra::mkWilkinsonW+ size
728              Create  a  Wilkinson  W+  of  size size. This kind of matrix has
729              pairs of eigenvalues that are very close together.  Usually  the
730              order (size) is odd.
731
732              integer size
733                     Dimension of the matrix
734
735
736       ::math::linearalgebra::mkWilkinsonW- size
737              Create  a  Wilkinson  W-  of  size size. This kind of matrix has
738              pairs of eigenvalues with opposite signs, when the order  (size)
739              is odd.
740
741              integer size
742                     Dimension of the matrix
743
744       Common algorithms
745
746       ::math::linearalgebra::solveGauss matrix bvect
747              Solve  a  system of linear equations (Ax=b) using Gauss elimina‐
748              tion.  Returns the solution (x) as a vector  or  matrix  of  the
749              same shape as bvect.
750
751              list matrix
752                     Square matrix (matrix A)
753
754              list bvect
755                     Vector  or matrix whose columns are the individual b-vec‐
756                     tors
757
758       ::math::linearalgebra::solvePGauss matrix bvect
759              Solve a system of linear equations (Ax=b) using  Gauss  elimina‐
760              tion with partial pivoting. Returns the solution (x) as a vector
761              or matrix of the same shape as bvect.
762
763              list matrix
764                     Square matrix (matrix A)
765
766              list bvect
767                     Vector or matrix whose columns are the individual  b-vec‐
768                     tors
769
770
771       ::math::linearalgebra::solveTriangular matrix bvect ?uplo?
772              Solve  a system of linear equations (Ax=b) by backward substitu‐
773              tion. The matrix is supposed to be upper-triangular.
774
775              list matrix
776                     Lower or upper-triangular matrix (matrix A)
777
778              list bvect
779                     Vector or matrix whose columns are the individual  b-vec‐
780                     tors
781
782              string uplo
783                     Indicates  whether  the matrix is lower-triangular (L) or
784                     upper-triangular (U). Defaults to "U".
785
786       ::math::linearalgebra::solveGaussBand matrix bvect
787              Solve a system of linear equations (Ax=b) using  Gauss  elimina‐
788              tion, where the matrix is stored as a band matrix (cf. STORAGE).
789              Returns the solution (x) as a vector or matrix of the same shape
790              as bvect.
791
792              list matrix
793                     Square matrix (matrix A; in band form)
794
795              list bvect
796                     Vector  or matrix whose columns are the individual b-vec‐
797                     tors
798
799
800       ::math::linearalgebra::solveTriangularBand matrix bvect
801              Solve a system of linear equations (Ax=b) by backward  substitu‐
802              tion.  The  matrix is supposed to be upper-triangular and stored
803              in band form.
804
805              list matrix
806                     Upper-triangular matrix (matrix A)
807
808              list bvect
809                     Vector or matrix whose columns are the individual  b-vec‐
810                     tors
811
812
813       ::math::linearalgebra::determineSVD A eps
814              Determines the Singular Value Decomposition of a matrix: A = U S
815              Vtrans.  Returns a list with the matrix U, the vector of  singu‐
816              lar values S and the matrix V.
817
818              list A Matrix to be decomposed
819
820              float eps
821                     Tolerance (defaults to 2.3e-16)
822
823
824       ::math::linearalgebra::eigenvectorsSVD A eps
825              Determines  the eigenvectors and eigenvalues of a real symmetric
826              matrix, using SVD. Returns a list with the matrix of  normalized
827              eigenvectors and their eigenvalues.
828
829              list A Matrix whose eigenvalues must be determined
830
831              float eps
832                     Tolerance (defaults to 2.3e-16)
833
834
835       ::math::linearalgebra::leastSquaresSVD A y qmin eps
836              Determines  the  solution  to a least-sqaures problem Ax ~ y via
837              singular value decomposition. The result is the vector x.
838
839              Note that if you add a column of 1s to  the  matrix,  then  this
840              column  will  represent a constant like in: y = a*x1 + b*x2 + c.
841              To force the intercept to be zero, simply leave it out.
842
843              list A Matrix of independent variables
844
845              list y List of observed values
846
847              float qmin
848                     Minimum singular value to be considered (defaults to 0.0)
849
850              float eps
851                     Tolerance (defaults to 2.3e-16)
852
853
854       ::math::linearalgebra::choleski matrix
855              Determine the Choleski decomposition  of  a  symmetric  positive
856              semidefinite matrix (this condition is not checked!). The result
857              is the lower-triangular matrix L such that L Lt = matrix.
858
859              list matrix
860                     Matrix to be decomposed
861
862
863       ::math::linearalgebra::orthonormalizeColumns matrix
864              Use the modified Gram-Schmidt method to orthogonalize  and  nor‐
865              malize the columns of the given matrix and return the result.
866
867              list matrix
868                     Matrix whose columns must be orthonormalized
869
870
871       ::math::linearalgebra::orthonormalizeRows matrix
872              Use  the  modified Gram-Schmidt method to orthogonalize and nor‐
873              malize the rows of the given matrix and return the result.
874
875              list matrix
876                     Matrix whose rows must be orthonormalized
877
878
879       ::math::linearalgebra::dger matrix alpha x y ?scope?
880              Perform the rank 1 operation A + alpha*x*y' inline (that is: the
881              matrix  A  is adjusted).  For convenience the new matrix is also
882              returned as the result.
883
884              list matrix
885                     Matrix whose rows must be adjusted
886
887              double alpha
888                     Scale factor
889
890              list x A column vector
891
892              list y A column vector
893
894              list scope
895                     If not  provided,  the  operation  is  performed  on  all
896                     rows/columns  of  A if provided, it is expected to be the
897                     list {imin imax jmin jmax} where:
898
899                     ·      imin Minimum row index
900
901                     ·      imax Maximum row index
902
903                     ·      jmin Minimum column index
904
905                     ·      jmax Maximum column index
906
907
908       ::math::linearalgebra::dgetrf matrix
909              Computes an LU factorization of a general matrix, using partial,
910              pivoting with row interchanges. Returns the permutation vector.
911
912              The factorization has the form
913
914
915                 P * A = L * U
916
917
918              where P is a permutation matrix, L is lower triangular with unit
919              diagonal elements, and U is upper triangular.  Returns the  per‐
920              mutation vector, as a list of length n-1.  The last entry of the
921              permutation is not stored, since it is implicitely  known,  with
922              value  n  (the  last row is not swapped with any other row).  At
923              index #i of the permutation is stored the index of  the  row  #j
924              which  is  swapped  with row #i at step #i. That means that each
925              index of the permutation gives the permutation at each step, not
926              the cumulated permutation matrix, which is the product of permu‐
927              tations.
928
929              list matrix
930                     On entry, the matrix to be factored.  On exit,  the  fac‐
931                     tors  L  and U from the factorization P*A = L*U; the unit
932                     diagonal elements of L are not stored.
933
934
935       ::math::linearalgebra::det matrix
936              Returns the determinant of the  given  matrix,  based  on  PA=LU
937              decomposition, i.e. Gauss partial pivotal.
938
939              list matrix
940                     Square matrix (matrix A)
941
942              list ipiv
943                     The  pivots (optionnal).  If the pivots are not provided,
944                     a PA=LU decomposition is performed.  If  the  pivots  are
945                     provided,  we assume that it contains the pivots and that
946                     the matrix A contains the L and U factors, as provided by
947                     dgterf.  b-vectors
948
949
950       ::math::linearalgebra::largesteigen matrix tolerance maxiter
951              Returns a list made of the largest eigenvalue (in magnitude) and
952              associated eigenvector.  Uses iterative Power Method as provided
953              as algorithm #7.3.3 of Golub & Van Loan.  This algorithm is used
954              here for a dense matrix (but is usually used for  sparse  matri‐
955              ces).
956
957              list matrix
958                     Square matrix (matrix A)
959
960              double tolerance
961                     The relative tolerance of the eigenvalue (default:1.e-8).
962
963              integer maxiter
964                     The maximum number of iterations (default:10).
965
966       Compability with the LA package Two procedures are provided for compat‐
967       ibility with Hume's LA package:
968
969       ::math::linearalgebra::to_LA mv
970              Transforms a vector or matrix into the format used by the origi‐
971              nal LA package.
972
973              list mv
974                     Matrix or vector
975
976       ::math::linearalgebra::from_LA mv
977              Transforms a vector or matrix from the format used by the origi‐
978              nal LA package into the format used by the  present  implementa‐
979              tion.
980
981              list mv
982                     Matrix or vector as used by the LA package
983

STORAGE

985       While  most procedures assume that the matrices are given in full form,
986       the procedures solveGaussBand and solveTriangularBand assume  that  the
987       matrices  are  stored  as  band  matrices. This common type of "sparse"
988       matrices is related to ordinary matrices as follows:
989
990       ·      "A" is a full-size matrix with N rows and M columns.
991
992       ·      "B" is a band matrix, with m upper and  lower  diagonals  and  n
993              rows.
994
995       ·      "B"  can  be stored in an ordinary matrix of (2m+1) columns (one
996              for each off-diagonal and the main diagonal) and n rows.
997
998       ·      Element i,j (i = -m,...,m; j =1,...,n)  of  "B"  corresponds  to
999              element  k,j of "A" where k = M+i-1 and M is at least (!) n, the
1000              number of rows in "B".
1001
1002       ·      To set element (i,j) of matrix "B" use:
1003
1004
1005                  setelem B $j [expr {$N+$i-1}] $value
1006
1007
1008       (There is no convenience procedure for this yet)
1009

REMARKS ON THE IMPLEMENTATION

1011       There is a difference between the original LA package by Hume  and  the
1012       current  implementation. Whereas the LA package uses a linear list, the
1013       current package uses lists of lists to represent matrices. It turns out
1014       that  with this representation, the algorithms are faster and easier to
1015       implement.
1016
1017       The LA package was used as a model and in fact the  implementation  of,
1018       for instance, the SVD algorithm was taken from that package. The set of
1019       procedures was expanded using ideas from the  well-known  BLAS  library
1020       and some algorithms were updated from the second edition of J.C. Nash's
1021       book, Compact Numerical Methods for Computers, (Adam Hilger, 1990) that
1022       inspired the LA package.
1023
1024       Two  procedures  are  provided  to  make the transition between the two
1025       implementations easier: to_LA and from_LA. They are described above.
1026

TODO

1028       Odds and ends: the following algorithms have not been implemented yet:
1029
1030       ·      determineQR
1031
1032       ·      certainlyPositive, diagonallyDominant
1033

NAMING CONFLICT

1035       If you load this package in a Tk-enabled shell like wish, then the com‐
1036       mand
1037
1038              namespace import ::math::linearalgebra
1039       results in an error message about "scale". This is due to the fact that
1040       Tk defines all its commands in the global namespace. The solution is to
1041       import  the  linear  algebra  commands  in  a namespace that is not the
1042       global one:
1043
1044
1045              package require math::linearalgebra
1046              namespace eval compute {
1047                  namespace import ::math::linearalgebra::*
1048                  ... use the linear algebra version of scale ...
1049              }
1050
1051       To use Tk's scale command in that same namespace you can rename it:
1052
1053
1054              namespace eval compute {
1055                  rename ::scale scaleTk
1056                  scaleTk .scale ...
1057              }
1058
1059

BUGS, IDEAS, FEEDBACK

1061       This document, and the package it describes, will  undoubtedly  contain
1062       bugs  and  other  problems.  Please report such in the category math ::
1063       linearalgebra         of          the          Tcllib          Trackers
1064       [http://core.tcl.tk/tcllib/reportlist].   Please  also report any ideas
1065       for enhancements you may have for either package and/or documentation.
1066
1067       When proposing code changes, please provide unified diffs, i.e the out‐
1068       put of diff -u.
1069
1070       Note  further  that  attachments  are  strongly  preferred over inlined
1071       patches. Attachments can be made by going  to  the  Edit  form  of  the
1072       ticket  immediately  after  its  creation, and then using the left-most
1073       button in the secondary navigation bar.
1074

KEYWORDS

1076       least  squares,  linear  algebra,  linear  equations,  math,  matrices,
1077       matrix, vectors
1078

CATEGORY

1080       Mathematics
1081
1083       Copyright (c) 2004-2008 Arjen Markus <arjenmarkus@users.sourceforge.net>
1084       Copyright (c) 2004 Ed Hume <http://www.hume.com/contact.us.htm>
1085       Copyright (c) 2008 Michael Buadin <relaxkmike@users.sourceforge.net>
1086
1087
1088
1089
1090tcllib                               1.1.5              math::linearalgebra(n)
Impressum