doc/info/Matrices.texi

   1 @menu
   2 * Introduction to Matrices and Linear Algebra::
   3 * Functions and Variables for Matrices and Linear Algebra::
   4 @end menu
   5
   6 @c -----------------------------------------------------------------------------
   7 @node Introduction to Matrices and Linear Algebra, Functions and Variables for Matrices and Linear Algebra, Matrices and Linear Algebra, Matrices and Linear Algebra
   8 @section Introduction to Matrices and Linear Algebra
   9 @c -----------------------------------------------------------------------------
  10
  11 @menu
  12 * Dot::
  13 * Matrices::
  14 * Vectors::
  15 * eigen::
  16 @end menu
  17
  18 @c -----------------------------------------------------------------------------
  19 @node Dot, Matrices, Introduction to Matrices and Linear Algebra, Introduction to Matrices and Linear Algebra
  20 @subsection Dot
  21 @c -----------------------------------------------------------------------------
  22
  23 The operator @code{.} represents noncommutative multiplication and scalar
  24 product.  When the operands are 1-column or 1-row matrices @code{a} and
  25 @code{b}, the expression @code{a.b} is equivalent to
  26 @code{sum (a[i]*b[i], i, 1, length(a))}.  If @code{a} and @code{b} are not
  27 complex, this is the scalar product, also called the inner product or dot
  28 product, of @code{a} and @code{b}.  The scalar product is defined as
  29 @code{conjugate(a).b} when @code{a} and @code{b} are complex;
  30 @mref{innerproduct} in the @code{eigen} package provides the complex scalar
  31 product.
  32
  33 When the operands are more general matrices,
  34 the product is the matrix product @code{a} and @code{b}.
  35 The number of rows of @code{b} must equal the number of columns of @code{a},
  36 and the result has number of rows equal to the number of rows of @code{a}
  37 and number of columns equal to the number of columns of @code{b}.
  38
  39 To distinguish @code{.} as an arithmetic operator from the decimal point in a
  40 floating point number, it may be necessary to leave spaces on either side.
  41 For example, @code{5.e3} is @code{5000.0} but @code{5 . e3} is @code{5}
  42 times @code{e3}.
  43
  44 There are several flags which govern the simplification of expressions
  45 involving @code{.}, namely @mrefcomma{dot0nscsimp} @mrefcomma{dot0simp}@w{}
  46 @mrefcomma{dot1simp} @mrefcomma{dotassoc} @mrefcomma{dotconstrules}@w{}
  47 @mrefcomma{dotdistrib} @mrefcomma{dotexptsimp} @mrefcomma{dotident} and
  48 @mrefdot{dotscrules}
  49
  50 @c -----------------------------------------------------------------------------
  51 @node Matrices, Vectors, Dot, Introduction to Matrices and Linear Algebra
  52 @subsection Matrices
  53 @c -----------------------------------------------------------------------------
  54 Matrices are handled with speed and memory-efficiency in mind. This means that
  55 assigning a matrix to a variable will create a reference to, not a copy of the
  56 matrix. If the matrix is modified all references to the matrix point to the
  57 modified object (See @mref{copymatrix} for a way of avoiding this):
  58 @c ===beg===
  59 @c M1: matrix([0,0],[0,0]);
  60 @c M2: M1;
  61 @c M1[1][1]: 2;
  62 @c M2;
  63 @c ===end===
  64 @example
  65 @group
  66 (%i1) M1: matrix([0,0],[0,0]);
  67                             [ 0  0 ]
  68 (%o1)                       [      ]
  69                             [ 0  0 ]
  70 @end group
  71 @group
  72 (%i2) M2: M1;
  73                             [ 0  0 ]
  74 (%o2)                       [      ]
  75                             [ 0  0 ]
  76 @end group
  77 @group
  78 (%i3) M1[1][1]: 2;
  79 (%o3)                           2
  80 @end group
  81 @group
  82 (%i4) M2;
  83                             [ 2  0 ]
  84 (%o4)                       [      ]
  85                             [ 0  0 ]
  86 @end group
  87 @end example
  88
  89 Converting a matrix to nested lists and vice versa works the following way:
  90 @c ===beg===
  91 @c l: [[1,2],[3,4]];
  92 @c M1: apply('matrix,l);
  93 @c M2: transpose(M1);
  94 @c args(M2);
  95 @c ===end===
  96 @example
  97 @group
  98 (%i1) l: [[1,2],[3,4]];
  99 (%o1)                   [[1, 2], [3, 4]]
 100 @end group
 101 @group
 102 (%i2) M1: apply('matrix,l);
 103                             [ 1  2 ]
 104 (%o2)                       [      ]
 105                             [ 3  4 ]
 106 @end group
 107 @group
 108 (%i3) M2: transpose(M1);
 109                             [ 1  3 ]
 110 (%o3)                       [      ]
 111                             [ 2  4 ]
 112 @end group
 113 @group
 114 (%i4) args(M2);
 115 (%o4)                   [[1, 3], [2, 4]]
 116 @end group
 117 @end example
 118 @c -----------------------------------------------------------------------------
 119 @node Vectors, eigen, Matrices, Introduction to Matrices and Linear Algebra
 120 @subsection Vectors
 121 @c -----------------------------------------------------------------------------
 122
 123 @code{vect} is a package of functions for vector analysis.  @code{load ("vect")}
 124 loads this package, and @code{demo ("vect")} displays a demonstration.
 125 @c find maxima -name \*orth\* YIELDS NOTHING; ARE THESE FUNCTIONS IN ANOTHER FILE NOW ??
 126 @c and SHARE;VECT ORTH contains definitions of various orthogonal curvilinear coordinate systems.
 127
 128 The vector analysis package can combine and simplify symbolic
 129 expressions including dot products and cross products, together with
 130 the gradient, divergence, curl, and Laplacian operators.  The
 131 distribution of these operators over sums or products is governed
 132 by several flags, as are various other expansions, including expansion
 133 into components in any specific orthogonal coordinate systems.
 134 There are also functions for deriving the scalar or vector potential
 135 of a field.
 136
 137 The @code{vect} package contains these functions:
 138 @mrefcomma{vectorsimp} @mrefcomma{scalefactors} @mrefcomma{express}@w{}
 139 @mrefcomma{potential} and @mrefdot{vectorpotential}
 140 @c REVIEW vect.usg TO ENSURE THAT TEXINFO HAS WHATEVER IS THERE
 141 @c PRINTFILE(VECT,USAGE,SHARE); for details.
 142
 143 By default the @code{vect} package does not declare the dot operator to be a
 144 commutative operator.  To get a commutative dot operator @code{.}, the command
 145 @code{declare(".", commutative)} must be executed.
 146
 147 @opencatbox{Categories:}
 148 @category{Vectors}
 149 @category{Share packages}
 150 @category{Package vect}
 151 @closecatbox
 152
 153 @c -----------------------------------------------------------------------------
 154 @node eigen, , Vectors, Introduction to Matrices and Linear Algebra
 155 @subsection eigen
 156 @c -----------------------------------------------------------------------------
 157
 158 The package @code{eigen} contains several functions devoted to the
 159 symbolic computation of eigenvalues and eigenvectors.
 160 Maxima loads the package automatically if one of the functions
 161 @code{eigenvalues} or @code{eigenvectors} is invoked.
 162 The package may be loaded explicitly as @code{load ("eigen")}.
 163
 164 @code{demo ("eigen")} displays a demonstration of the capabilities
 165 of this package.
 166 @code{batch ("eigen")} executes the same demonstration,
 167 but without the user prompt between successive computations.
 168
 169 The functions in the @code{eigen} package are:@*
 170 @mrefcomma{innerproduct} @mrefcomma{unitvector} @mrefcomma{columnvector}@w{}
 171 @mrefcomma{gramschmidt} @mrefcomma{eigenvalues}@*
 172 @mrefcomma{eigenvectors} @mrefcomma{uniteigenvectors} and
 173 @mrefdot{similaritytransform}
 174
 175 @opencatbox{Categories:}
 176 @category{Vectors}
 177 @category{Matrices}
 178 @category{Share packages}
 179 @category{Package eigen}
 180 @closecatbox
 181
 182 @c end concepts Matrices and Linear Algebra
 183
 184 @c -----------------------------------------------------------------------------
 185 @node Functions and Variables for Matrices and Linear Algebra,  , Introduction to Matrices and Linear Algebra, Matrices and Linear Algebra
 186 @section Functions and Variables for Matrices and Linear Algebra
 187 @c -----------------------------------------------------------------------------
 188
 189 @c -----------------------------------------------------------------------------
 190 @anchor{addcol}
 191 @deffn {Function} addcol (@var{M}, @var{list_1}, @dots{}, @var{list_n})
 192
 193 Appends the column(s) given by the one
 194 or more lists (or matrices) onto the matrix @var{M}.
 195
 196 See also @mref{addrow} and @mrefdot{append}
 197
 198 @opencatbox{Categories:}
 199 @category{Matrices}
 200 @closecatbox
 201 @end deffn
 202
 203 @c -----------------------------------------------------------------------------
 204 @anchor{addrow}
 205 @deffn {Function} addrow (@var{M}, @var{list_1}, @dots{}, @var{list_n})
 206
 207 Appends the row(s) given by the one or
 208 more lists (or matrices) onto the matrix @var{M}.
 209
 210 See also @mref{addcol} and @mrefdot{append}
 211
 212 @opencatbox{Categories:}
 213 @category{Matrices}
 214 @closecatbox
 215 @end deffn
 216
 217 @c -----------------------------------------------------------------------------
 218 @anchor{adjoint}
 219 @deffn {Function} adjoint (@var{M})
 220
 221 Returns the adjoint of the matrix @var{M}.
 222 The adjoint matrix is the transpose of the matrix of cofactors of @var{M}.
 223
 224 @opencatbox{Categories:}
 225 @category{Matrices}
 226 @closecatbox
 227 @end deffn
 228
 229 @c -----------------------------------------------------------------------------
 230 @anchor{augcoefmatrix}
 231 @deffn {Function} augcoefmatrix ([@var{eqn_1}, @dots{}, @var{eqn_m}], [@var{x_1}, @dots{}, @var{x_n}])
 232
 233 Returns the augmented coefficient
 234 matrix for the variables @var{x_1}, @dots{}, @var{x_n} of the system of linear
 235 equations @var{eqn_1}, @dots{}, @var{eqn_m}.  This is the coefficient matrix
 236 with a column adjoined for the constant terms in each equation (i.e., those
 237 terms not dependent upon @var{x_1}, @dots{}, @var{x_n}).
 238
 239 @example
 240 (%i1) m: [2*x - (a - 1)*y = 5*b, c + b*y + a*x = 0]$
 241 (%i2) augcoefmatrix (m, [x, y]);
 242                        [ 2  1 - a  - 5 b ]
 243 (%o2)                  [                 ]
 244                        [ a    b      c   ]
 245 @end example
 246
 247 @opencatbox{Categories:}
 248 @category{Linear equations}
 249 @category{Matrices}
 250 @closecatbox
 251 @end deffn
 252
 253 @c --- 04.10.2010 --------------------------------------------------------------
 254 @anchor{cauchy_matrix}
 255 @deffn {Function} cauchy_matrix @
 256 @fname{cauchy_matrix} ([@var{x_1}, @var{x_2}, @dots{}, @var{x_m}], [@var{y_1}, @var{y_2}, @dots{}, @var{y_n}]) @
 257 @fname{cauchy_matrix} ([@var{x_1}, @var{x_2}, @dots{}, @var{x_n}])
 258
 259 Returns a @code{n} by @var{m} Cauchy matrix with the elements @var{a[i,j]}
 260 = 1/(@var{x_i}+@var{y_i}).  The second argument of @code{cauchy_matrix} is
 261 optional.  For this case the elements of the Cauchy matrix are
 262 @var{a[i,j]} = 1/(@var{x_i}+@var{x_j}).
 263
 264 Remark: In the literature the Cauchy matrix can be found defined in two forms.
 265 A second definition is @var{a[i,j]} = 1/(@var{x_i}-@var{y_i}).
 266
 267 Examples:
 268
 269 @c ===beg===
 270 @c cauchy_matrix([x1, x2], [y1, y2]);
 271 @c cauchy_matrix([x1, x2]);
 272 @c ===end===
 273 @example
 274 (%i1) cauchy_matrix([x1, x2], [y1, y2]);
 275 @group
 276                       [    1        1    ]
 277                       [ -------  ------- ]
 278                       [ y1 + x1  y2 + x1 ]
 279 (%o1)                 [                  ]
 280                       [    1        1    ]
 281                       [ -------  ------- ]
 282                       [ y1 + x2  y2 + x2 ]
 283 @end group
 284
 285 (%i2) cauchy_matrix([x1, x2]);
 286                       [   1         1    ]
 287                       [  ----    ------- ]
 288                       [  2 x1    x2 + x1 ]
 289 (%o2)                 [                  ]
 290                       [    1       1     ]
 291                       [ -------   ----   ]
 292                       [ x2 + x1   2 x2   ]
 293 @end example
 294
 295 @opencatbox{Categories:}
 296 @category{Matrices}
 297 @closecatbox
 298 @end deffn
 299
 300 @c -----------------------------------------------------------------------------
 301 @anchor{charpoly}
 302 @deffn {Function} charpoly (@var{M}, @var{x})
 303
 304 Returns the characteristic polynomial for the matrix @var{M}
 305 with respect to variable @var{x}.  That is,
 306 @code{determinant (@var{M} - diagmatrix (length (@var{M}), @var{x}))}.
 307
 308 @example
 309 (%i1) a: matrix ([3, 1], [2, 4]);
 310                             [ 3  1 ]
 311 (%o1)                       [      ]
 312                             [ 2  4 ]
 313 (%i2) expand (charpoly (a, lambda));
 314                            2
 315 (%o2)                lambda  - 7 lambda + 10
 316 (%i3) (programmode: true, solve (%));
 317 (%o3)               [lambda = 5, lambda = 2]
 318 (%i4) matrix ([x1], [x2]);
 319                              [ x1 ]
 320 (%o4)                        [    ]
 321                              [ x2 ]
 322 (%i5) ev (a . % - lambda*%, %th(2)[1]);
 323                           [ x2 - 2 x1 ]
 324 (%o5)                     [           ]
 325                           [ 2 x1 - x2 ]
 326 (%i6) %[1, 1] = 0;
 327 (%o6)                     x2 - 2 x1 = 0
 328 (%i7) x2^2 + x1^2 = 1;
 329                             2     2
 330 (%o7)                     x2  + x1  = 1
 331 (%i8) solve ([%th(2), %], [x1, x2]);
 332 @group
 333                   1               2
 334 (%o8) [[x1 = - -------, x2 = - -------],
 335                sqrt(5)         sqrt(5)
 336
 337                                              1             2
 338                                     [x1 = -------, x2 = -------]]
 339                                           sqrt(5)       sqrt(5)
 340 @end group
 341 @end example
 342
 343 @opencatbox{Categories:}
 344 @category{Matrices}
 345 @closecatbox
 346 @end deffn
 347
 348 @c -----------------------------------------------------------------------------
 349 @anchor{coefmatrix}
 350 @deffn {Function} coefmatrix ([@var{eqn_1}, @dots{}, @var{eqn_m}], [@var{x_1}, @dots{}, @var{x_n}])
 351
 352 Returns the coefficient matrix for the
 353 variables @var{x_1}, @dots{}, @var{x_n} of the system of linear equations
 354 @var{eqn_1}, @dots{}, @var{eqn_m}.
 355
 356 @example
 357 (%i1) coefmatrix([2*x-(a-1)*y+5*b = 0, b*y+a*x = 3], [x,y]);
 358                                  [ 2  1 - a ]
 359 (%o1)                            [          ]
 360                                  [ a    b   ]
 361 @end example
 362
 363 @opencatbox{Categories:}
 364 @category{Linear equations}
 365 @category{Matrices}
 366 @closecatbox
 367 @end deffn
 368
 369 @c -----------------------------------------------------------------------------
 370 @anchor{col}
 371 @deffn {Function} col (@var{M}, @var{i})
 372
 373 Returns the @var{i}'th column of the matrix @var{M}.
 374 The return value is a matrix.
 375 @c EXAMPLE HERE
 376
 377 @opencatbox{Categories:}
 378 @category{Matrices}
 379 @closecatbox
 380 @end deffn
 381
 382 @c -----------------------------------------------------------------------------
 383 @anchor{columnvector}
 384 @anchor{covect}
 385 @deffn  {Function} columnvector (@var{L})
 386 @deffnx {Function} covect (@var{L})
 387
 388 Returns a matrix of one column and @code{length (@var{L})} rows,
 389 containing the elements of the list @var{L}.
 390
 391 @code{covect} is a synonym for @code{columnvector}.
 392
 393 @code{load ("eigen")} loads this function.
 394
 395 @c FOLLOWING COMMENT PRESERVED. WHAT DOES THIS MEAN ??
 396 This is useful if you want to use parts of the outputs of
 397 the functions in this package in matrix calculations.
 398
 399 Example:
 400
 401 @c HMM, SPURIOUS "redefining the Macsyma function".
 402 @c LEAVE IT HERE SINCE THAT'S WHAT A USER ACTUALLY SEES.
 403 @example
 404 (%i1) load ("eigen")$
 405 Warning - you are redefining the Macsyma function eigenvalues
 406 Warning - you are redefining the Macsyma function eigenvectors
 407 (%i2) columnvector ([aa, bb, cc, dd]);
 408                              [ aa ]
 409                              [    ]
 410                              [ bb ]
 411 (%o2)                        [    ]
 412                              [ cc ]
 413                              [    ]
 414                              [ dd ]
 415 @end example
 416
 417 @opencatbox{Categories:}
 418 @category{Matrices}
 419 @closecatbox
 420 @end deffn
 421
 422 @c -----------------------------------------------------------------------------
 423 @anchor{copymatrix}
 424 @deffn {Function} copymatrix (@var{M})
 425
 426 Returns a copy of the matrix @var{M}.  This is the only way
 427 to make a copy aside from copying @var{M} element by element.
 428
 429 Note that an assignment of one matrix to another, as in @code{m2: m1}, does not
 430 copy @code{m1}.  An assignment @code{m2 [i,j]: x} or @code{setelmx(x, i, j, m2)}
 431 also modifies @code{m1 [i,j]}.  Creating a copy with @code{copymatrix} and then
 432 using assignment creates a separate, modified copy.
 433
 434 @c NEED EXAMPLE HERE
 435 @opencatbox{Categories:}
 436 @category{Matrices}
 437 @closecatbox
 438 @end deffn
 439
 440 @c -----------------------------------------------------------------------------
 441 @anchor{determinant}
 442 @deffn {Function} determinant (@var{M})
 443
 444 Computes the determinant of @var{M} by a method similar to
 445 Gaussian elimination.
 446
 447 @c JUST HOW DOES ratmx AFFECT THE RESULT ??
 448 The form of the result depends upon the setting of the switch @mrefdot{ratmx}
 449
 450 @c IS A SPARSE DETERMINANT SOMETHING OTHER THAN THE DETERMINANT OF A SPARSE MATRIX ??
 451 There is a special routine for computing sparse determinants which is called
 452 when the switches @code{ratmx} and @mref{sparse} are both @code{true}.
 453
 454 @c EXAMPLES NEEDED HERE
 455 @opencatbox{Categories:}
 456 @category{Matrices}
 457 @closecatbox
 458 @end deffn
 459
 460 @c -----------------------------------------------------------------------------
 461 @anchor{detout}
 462 @defvr {Option variable} detout
 463 Default value: @code{false}
 464
 465 When @code{detout} is @code{true}, the determinant of a
 466 matrix whose inverse is computed is factored out of the inverse.
 467
 468 For this switch to have an effect @mref{doallmxops} and @mref{doscmxops} should
 469 be @code{false} (see their descriptions).  Alternatively this switch can be
 470 given to @mref{ev} which causes the other two to be set correctly.
 471
 472 Example:
 473
 474 @example
 475 (%i1) m: matrix ([a, b], [c, d]);
 476                             [ a  b ]
 477 (%o1)                       [      ]
 478                             [ c  d ]
 479 (%i2) detout: true$
 480 (%i3) doallmxops: false$
 481 (%i4) doscmxops: false$
 482 (%i5) invert (m);
 483                           [  d   - b ]
 484                           [          ]
 485                           [ - c   a  ]
 486 (%o5)                     ------------
 487                            a d - b c
 488 @end example
 489 @c THERE'S MORE TO THIS STORY: detout: false$ invert (m); RETURNS THE SAME THING.
 490 @c IT APPEARS THAT doallmxops IS CRUCIAL HERE.
 491
 492 @opencatbox{Categories:}
 493 @category{Matrices}
 494 @category{Evaluation flags}
 495 @closecatbox
 496 @end defvr
 497
 498 @c -----------------------------------------------------------------------------
 499 @anchor{diagmatrix}
 500 @deffn {Function} diagmatrix (@var{n}, @var{x})
 501
 502 Returns a diagonal matrix of size @var{n} by @var{n} with the diagonal elements
 503 all equal to @var{x}.  @code{diagmatrix (@var{n}, 1)} returns an identity matrix
 504 (same as @code{ident (@var{n})}).
 505
 506 @var{n} must evaluate to an integer, otherwise @code{diagmatrix} complains with
 507 an error message.
 508
 509 @var{x} can be any kind of expression, including another matrix.  If @var{x} is
 510 a matrix, it is not copied; all diagonal elements refer to the same instance,
 511 @var{x}.
 512
 513 @c NEED EXAMPLE HERE
 514 @opencatbox{Categories:}
 515 @category{Matrices}
 516 @closecatbox
 517 @end deffn
 518
 519 @c -----------------------------------------------------------------------------
 520 @anchor{doallmxops}
 521 @defvr {Option variable} doallmxops
 522 Default value: @code{true}
 523
 524 When @code{doallmxops} is @code{true},
 525 @c UMM, WHAT DOES THIS MEAN EXACTLY ??
 526 all operations relating to matrices are carried out.
 527 When it is @code{false} then the setting of the
 528 individual @code{dot} switches govern which operations are performed.
 529
 530 @c NEED EXAMPLES HERE
 531 @opencatbox{Categories:}
 532 @category{Matrices}
 533 @closecatbox
 534 @end defvr
 535
 536 @c -----------------------------------------------------------------------------
 537 @anchor{domxexpt}
 538 @defvr {Option variable} domxexpt
 539 Default value: @code{true}
 540
 541 When @code{domxexpt} is @code{true},
 542 a matrix exponential, @code{exp (@var{M})} where @var{M} is a matrix, is
 543 interpreted as a matrix with element @code{[i,j]} equal to @code{exp (m[i,j])}.
 544 Otherwise @code{exp (@var{M})} evaluates to @code{exp (@var{ev(M)})}.
 545
 546 @code{domxexpt} affects all expressions of the form
 547 @code{@var{base}^@var{power}} where @var{base} is an expression assumed scalar
 548 or constant, and @var{power} is a list or matrix.
 549
 550 Example:
 551
 552 @example
 553 (%i1) m: matrix ([1, %i], [a+b, %pi]);
 554                          [   1    %i  ]
 555 (%o1)                    [            ]
 556                          [ b + a  %pi ]
 557 (%i2) domxexpt: false$
 558 (%i3) (1 - c)^m;
 559                              [   1    %i  ]
 560                              [            ]
 561                              [ b + a  %pi ]
 562 (%o3)                 (1 - c)
 563 (%i4) domxexpt: true$
 564 (%i5) (1 - c)^m;
 565                   [                      %i  ]
 566                   [    1 - c      (1 - c)    ]
 567 (%o5)             [                          ]
 568                   [        b + a         %pi ]
 569                   [ (1 - c)       (1 - c)    ]
 570 @end example
 571
 572 @opencatbox{Categories:}
 573 @category{Matrices}
 574 @closecatbox
 575 @end defvr
 576
 577 @c -----------------------------------------------------------------------------
 578 @anchor{domxmxops}
 579 @defvr {Option variable} domxmxops
 580 Default value: @code{true}
 581
 582 When @code{domxmxops} is @code{true}, all matrix-matrix or
 583 matrix-list operations are carried out (but not scalar-matrix
 584 operations); if this switch is @code{false} such operations are not carried out.
 585 @c IS THIS AN EVALUATION OR A SIMPLIFICATION FLAG ??
 586
 587 @c NEED EXAMPLE HERE
 588 @opencatbox{Categories:}
 589 @category{Matrices}
 590 @closecatbox
 591 @end defvr
 592
 593 @c -----------------------------------------------------------------------------
 594 @anchor{domxnctimes}
 595 @defvr {Option variable} domxnctimes
 596 Default value: @code{false}
 597
 598 When @code{domxnctimes} is @code{true}, non-commutative products of
 599 matrices are carried out.
 600 @c IS THIS AN EVALUATION OR A SIMPLIFICATION FLAG ??
 601
 602 @c NEED EXAMPLE HERE
 603 @opencatbox{Categories:}
 604 @category{Matrices}
 605 @closecatbox
 606 @end defvr
 607
 608 @c -----------------------------------------------------------------------------
 609 @anchor{dontfactor}
 610 @defvr {Option variable} dontfactor
 611 Default value: @code{[]}
 612
 613 @code{dontfactor} may be set to a list of variables with respect to which
 614 factoring is not to occur.  (The list is initially empty.) Factoring also will
 615 not take place with respect to any variables which are less important, according
 616 the variable ordering assumed for canonical rational expression (CRE) form, than
 617 those on the @code{dontfactor} list.
 618
 619 @opencatbox{Categories:}
 620 @category{Expressions}
 621 @closecatbox
 622 @end defvr
 623
 624 @c -----------------------------------------------------------------------------
 625 @anchor{doscmxops}
 626 @defvr {Option variable} doscmxops
 627 Default value: @code{false}
 628
 629 When @code{doscmxops} is @code{true}, scalar-matrix operations are
 630 carried out.
 631 @c IS THIS AN EVALUATION OR A SIMPLIFICATION FLAG ??
 632
 633 @c NEED EXAMPLE HERE
 634 @opencatbox{Categories:}
 635 @category{Matrices}
 636 @closecatbox
 637 @end defvr
 638
 639 @c -----------------------------------------------------------------------------
 640 @anchor{doscmxplus}
 641 @defvr {Option variable} doscmxplus
 642 Default value: @code{false}
 643
 644 When @code{doscmxplus} is @code{true}, scalar-matrix operations yield
 645 a matrix result.  This switch is not subsumed under @mrefdot{doallmxops}
 646 @c IS THIS AN EVALUATION OR A SIMPLIFICATION FLAG ??
 647
 648 @c NEED EXAMPLE HERE
 649 @opencatbox{Categories:}
 650 @category{Matrices}
 651 @closecatbox
 652 @end defvr
 653
 654 @c -----------------------------------------------------------------------------
 655 @anchor{dot0nscsimp}
 656 @defvr {Option variable} dot0nscsimp
 657 Default value: @code{true}
 658
 659 @c WHAT DOES THIS MEAN EXACTLY ??
 660 When @code{dot0nscsimp} is @code{true}, a non-commutative product of zero
 661 and a nonscalar term is simplified to a commutative product.
 662
 663 @c NEED EXAMPLE HERE
 664 @opencatbox{Categories:}
 665 @category{Simplification flags and variables}
 666 @closecatbox
 667 @end defvr
 668
 669 @c -----------------------------------------------------------------------------
 670 @anchor{dot0simp}
 671 @defvr {Option variable} dot0simp
 672 Default value: @code{true}
 673
 674 @c WHAT DOES THIS MEAN EXACTLY ??
 675 When @code{dot0simp} is @code{true},
 676 a non-commutative product of zero and
 677 a scalar term is simplified to a commutative product.
 678
 679 @c NEED EXAMPLE HERE
 680 @opencatbox{Categories:}
 681 @category{Simplification flags and variables}
 682 @closecatbox
 683 @end defvr
 684
 685 @c -----------------------------------------------------------------------------
 686 @anchor{dot1simp}
 687 @defvr {Option variable} dot1simp
 688 Default value: @code{true}
 689
 690 @c WHAT DOES THIS MEAN EXACTLY ??
 691 When @code{dot1simp} is @code{true},
 692 a non-commutative product of one and
 693 another term is simplified to a commutative product.
 694
 695 @c NEED EXAMPLE HERE
 696 @opencatbox{Categories:}
 697 @category{Simplification flags and variables}
 698 @closecatbox
 699 @end defvr
 700
 701 @c -----------------------------------------------------------------------------
 702 @anchor{dotassoc}
 703 @defvr {Option variable} dotassoc
 704 Default value: @code{true}
 705
 706 When @code{dotassoc} is @code{true}, an expression @code{(A.B).C} simplifies to
 707 @code{A.(B.C)}.
 708 @c "." MEANS NONCOMMUTATIVE MULTIPLICATION RIGHT ??
 709
 710 @c NEED EXAMPLE HERE
 711 @opencatbox{Categories:}
 712 @category{Simplification flags and variables}
 713 @closecatbox
 714 @end defvr
 715
 716 @c -----------------------------------------------------------------------------
 717 @anchor{dotconstrules}
 718 @defvr {Option variable} dotconstrules
 719 Default value: @code{true}
 720
 721 When @code{dotconstrules} is @code{true}, a non-commutative product of a
 722 constant and another term is simplified to a commutative product.
 723 @c TERMINOLOGY: (1) SWITCH/FLAG/SOME OTHER TERM ??
 724 @c              (2) ASSIGN/SET/TURN ON/SOME OTHER TERM ??
 725 Turning on this flag effectively turns on @mrefcomma{dot0simp}@w{}
 726 @mrefcomma{dot0nscsimp} and @mref{dot1simp} as well.
 727
 728 @c NEED EXAMPLE HERE
 729 @opencatbox{Categories:}
 730 @category{Simplification flags and variables}
 731 @closecatbox
 732 @end defvr
 733
 734 @c -----------------------------------------------------------------------------
 735 @anchor{dotdistrib}
 736 @defvr {Option variable} dotdistrib
 737 Default value: @code{false}
 738
 739 When @code{dotdistrib} is @code{true}, an expression @code{A.(B + C)} simplifies
 740 to @code{A.B + A.C}.
 741
 742 @c NEED EXAMPLE HERE
 743 @opencatbox{Categories:}
 744 @category{Simplification flags and variables}
 745 @closecatbox
 746 @end defvr
 747
 748 @c -----------------------------------------------------------------------------
 749 @anchor{dotexptsimp}
 750 @defvr {Option variable} dotexptsimp
 751 Default value: @code{true}
 752
 753 When @code{dotexptsimp} is @code{true}, an expression @code{A.A} simplifies to
 754 @code{A^^2}.
 755
 756 @c NEED EXAMPLE HERE
 757 @opencatbox{Categories:}
 758 @category{Simplification flags and variables}
 759 @closecatbox
 760 @end defvr
 761
 762 @c -----------------------------------------------------------------------------
 763 @anchor{dotident}
 764 @defvr {Option variable} dotident
 765 Default value: 1
 766
 767 @code{dotident} is the value returned by @code{X^^0}.
 768 @c "RETURNED" ?? IS THIS A SIMPLIFICATION OR AN EVALUATION ??
 769
 770 @c NEED EXAMPLE HERE
 771 @opencatbox{Categories:}
 772 @category{Simplification flags and variables}
 773 @closecatbox
 774 @end defvr
 775
 776 @c -----------------------------------------------------------------------------
 777 @anchor{dotscrules}
 778 @defvr {Option variable} dotscrules
 779 Default value: @code{false}
 780
 781 When @code{dotscrules} is @code{true}, an expression @code{A.SC} or @code{SC.A}
 782 simplifies to @code{SC*A} and @code{A.(SC*B)} simplifies to @code{SC*(A.B)}.
 783 @c HMM, DOES "SC" MEAN "SCALAR" HERE ?? CLARIFY
 784
 785 @c NEED EXAMPLE HERE
 786 @opencatbox{Categories:}
 787 @category{Simplification flags and variables}
 788 @closecatbox
 789 @end defvr
 790
 791 @c -----------------------------------------------------------------------------
 792 @anchor{echelon}
 793 @deffn {Function} echelon (@var{M})
 794
 795 Returns the echelon form of the matrix @var{M},
 796 as produced by Gaussian elimination.
 797 The echelon form is computed from @var{M}
 798 by elementary row operations such that the first
 799 non-zero element in each row in the resulting matrix is one and the
 800 column elements under the first one in each row are all zero.
 801
 802 @mref{triangularize} also carries out Gaussian elimination, but it does not
 803 normalize the leading non-zero element in each row.
 804
 805 @mref{lu_factor} and @mref{cholesky} are other functions which yield
 806 triangularized matrices.
 807
 808 @c ===beg===
 809 @c M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
 810 @c echelon (M);
 811 @c ===end===
 812 @example
 813 @group
 814 (%i1) M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
 815                        [  3   7  aa  bb ]
 816                        [                ]
 817 (%o1)                  [ - 1  8  5   2  ]
 818                        [                ]
 819                        [  9   2  11  4  ]
 820 @end group
 821 @group
 822 (%i2) echelon (M);
 823                   [ 1  - 8  - 5      - 2     ]
 824                   [                          ]
 825                   [         28       11      ]
 826                   [ 0   1   --       --      ]
 827 (%o2)             [         37       37      ]
 828                   [                          ]
 829                   [              37 bb - 119 ]
 830                   [ 0   0    1   ----------- ]
 831                   [              37 aa - 313 ]
 832 @end group
 833 @end example
 834
 835 @opencatbox{Categories:}
 836 @category{Linear equations}
 837 @category{Matrices}
 838 @closecatbox
 839 @end deffn
 840
 841 @c -----------------------------------------------------------------------------
 842 @anchor{eigenvalues}
 843 @anchor{eivals}
 844 @deffn  {Function} eigenvalues (@var{M})
 845 @deffnx {Function} eivals (@var{M})
 846
 847 @c eigen.mac IS AUTOLOADED IF eigenvalues OR eigenvectors IS REFERENCED; EXTEND THAT TO ALL FUNCTIONS ??
 848 @c EACH FUNCTION INTENDED FOR EXTERNAL USE SHOULD HAVE ITS OWN DOCUMENTATION ITEM
 849 Returns a list of two lists containing the eigenvalues of the matrix @var{M}.
 850 The first sublist of the return value is the list of eigenvalues of the
 851 matrix, and the second sublist is the list of the
 852 multiplicities of the eigenvalues in the corresponding order.
 853
 854 @code{eivals} is a synonym for @code{eigenvalues}.
 855
 856 @code{eigenvalues} calls the function @mref{solve} to find the roots of the
 857 characteristic polynomial of the matrix.  Sometimes @code{solve} may not be able
 858 to find the roots of the polynomial; in that case some other functions in this
 859 package (except @mrefcomma{innerproduct} @mrefcomma{unitvector}@w{}
 860 @mref{columnvector} and @mref{gramschmidt}) will not work.
 861 @c WHICH ONES ARE THE FUNCTIONS WHICH DON'T WORK ??
 862 @c ACTUALLY IT'S MORE IMPORTANT TO LIST THE ONES WHICH DON'T WORK HERE
 863 @c WHAT DOES "will not work" MEAN, ANYWAY ??
 864 Sometimes @code{solve} may find only a subset of the roots of the polynomial.
 865 This may happen when the factoring of the polynomial contains polynomials
 866 of degree 5 or more. In such cases a warning message is displayed and the
 867 only the roots found and their corresponding multiplicities are returned.
 868
 869 In some cases the eigenvalues found by @code{solve} may be complicated
 870 expressions.  (This may happen when @code{solve} returns a not-so-obviously real
 871 expression for an eigenvalue which is known to be real.)  It may be possible to
 872 simplify the eigenvalues using some other functions.
 873 @c WHAT ARE THOSE OTHER FUNCTIONS ??
 874
 875 The package @code{eigen.mac} is loaded automatically when
 876 @code{eigenvalues} or @mref{eigenvectors} is referenced.
 877 If @code{eigen.mac} is not already loaded,
 878 @code{load ("eigen")} loads it.
 879 After loading, all functions and variables in the package are available.
 880 @c REFER TO OVERVIEW OF PACKAGE (INCLUDING LIST OF FUNCTIONS) HERE
 881
 882 @c NEED EXAMPLES HERE
 883 @opencatbox{Categories:}
 884 @category{Package eigen}
 885 @closecatbox
 886 @end deffn
 887
 888 @c -----------------------------------------------------------------------------
 889 @anchor{eigenvectors}
 890 @anchor{eivects}
 891 @deffn  {Function} eigenvectors (@var{M})
 892 @deffnx {Function} eivects (@var{M})
 893
 894 Computes eigenvectors of the matrix @var{M}.
 895 The return value is a list of two elements.
 896 The first is a list of the eigenvalues of @var{M}
 897 and a list of the multiplicities of the eigenvalues.
 898 The second is a list of lists of eigenvectors.
 899 There is one list of eigenvectors for each eigenvalue.
 900 There may be one or more eigenvectors in each list.
 901
 902 @code{eivects} is a synonym for @code{eigenvectors}.
 903
 904 The package @code{eigen.mac} is loaded automatically when
 905 @mref{eigenvalues} or @code{eigenvectors} is referenced.
 906 If @code{eigen.mac} is not already loaded,
 907 @code{load ("eigen")} loads it.
 908 After loading, all functions and variables in the package are available.
 909
 910 Note that @code{eigenvectors} internally calls @code{eigenvalues} to
 911 obtain eigenvalues. So, when @code{eigenvalues} returns a subset of
 912 all the eigenvalues, the @code{eigenvectors} returns the corresponding
 913 subset of the all the eigenvectors, with the same warning displayed as
 914 @code{eigenvalues}.
 915
 916 The flags that affect this function are:
 917
 918 @code{nondiagonalizable} is set to @code{true} or @code{false} depending on
 919 whether the matrix is nondiagonalizable or diagonalizable after
 920 @code{eigenvectors} returns.
 921
 922 @code{hermitianmatrix} when @code{true}, causes the degenerate
 923 eigenvectors of the Hermitian matrix to be orthogonalized using the
 924 Gram-Schmidt algorithm.
 925
 926 @code{knowneigvals} when @code{true} causes the @code{eigen} package to assume
 927 the eigenvalues of the matrix are known to the user and stored under the global
 928 name @code{listeigvals}.  @code{listeigvals} should be set to a list similar
 929 to the output @code{eigenvalues}.
 930
 931 The function @mref{algsys} is used here to solve for the eigenvectors.
 932 Sometimes if the eigenvalues are messy, @code{algsys} may not be able to find a
 933 solution.  In some cases, it may be possible to simplify the eigenvalues by
 934 first finding them using @code{eigenvalues} command and then using other
 935 functions to reduce them to something simpler.  Following simplification,
 936 @code{eigenvectors} can be called again with the @code{knowneigvals} flag set
 937 to @code{true}.
 938
 939 See also @mrefdot{eigenvalues}
 940
 941 Examples:
 942
 943 A matrix which has just one eigenvector per eigenvalue.
 944
 945 @c ===beg===
 946 @c M1: matrix ([11, -1], [1, 7]);
 947 @c [vals, vecs] : eigenvectors (M1);
 948 @c for i thru length (vals[1]) do disp (val[i] = vals[1][i],
 949 @c   mult[i] = vals[2][i], vec[i] = vecs[i]);
 950 @c ===end===
 951 @example
 952 @group
 953 (%i1) M1: matrix ([11, -1], [1, 7]);
 954                            [ 11  - 1 ]
 955 (%o1)                      [         ]
 956                            [ 1    7  ]
 957 @end group
 958 @group
 959 (%i2) [vals, vecs] : eigenvectors (M1);
 960 (%o2) [[[9 - sqrt(3), sqrt(3) + 9], [1, 1]],
 961                         [[[1, sqrt(3) + 2]], [[1, 2 - sqrt(3)]]]]
 962 @end group
 963 @group
 964 (%i3) for i thru length (vals[1]) do disp (val[i] = vals[1][i],
 965   mult[i] = vals[2][i], vec[i] = vecs[i]);
 966                        val  = 9 - sqrt(3)
 967                           1
 968
 969                             mult  = 1
 970                                 1
 971
 972                     vec  = [[1, sqrt(3) + 2]]
 973                        1
 974
 975                        val  = sqrt(3) + 9
 976                           2
 977
 978                             mult  = 1
 979                                 2
 980
 981                     vec  = [[1, 2 - sqrt(3)]]
 982                        2
 983
 984 (%o3)                         done
 985 @end group
 986 @end example
 987
 988 A matrix which has two eigenvectors for one eigenvalue (namely 2).
 989
 990 @c ===beg===
 991 @c M1 : matrix ([0, 1, 0, 0], [0, 0, 0, 0], [0, 0, 2, 0], [0, 0, 0, 2]);
 992 @c [vals, vecs] : eigenvectors (M1);
 993 @c for i thru length (vals[1]) do disp (val[i] = vals[1][i],
 994 @c   mult[i] = vals[2][i], vec[i] = vecs[i]);
 995 @c ===end===
 996 @example
 997 @group
 998 (%i1) M1: matrix ([0, 1, 0, 0], [0, 0, 0, 0], [0, 0, 2, 0],
 999                   [0, 0, 0, 2]);
1000                         [ 0  1  0  0 ]
1001                         [            ]
1002                         [ 0  0  0  0 ]
1003 (%o1)                   [            ]
1004                         [ 0  0  2  0 ]
1005                         [            ]
1006                         [ 0  0  0  2 ]
1007 @end group
1008 @group
1009 (%i2) [vals, vecs]: eigenvectors (M1);
1010 (%o2) [[[0, 2], [2, 2]], [[[1, 0, 0, 0]],
1011                                    [[0, 0, 1, 0], [0, 0, 0, 1]]]]
1012 @end group
1013 @group
1014 (%i3) for i thru length (vals[1]) do disp (val[i] = vals[1][i],
1015   mult[i] = vals[2][i], vec[i] = vecs[i]);
1016                             val  = 0
1017                                1
1018
1019                             mult  = 2
1020                                 1
1021
1022                       vec  = [[1, 0, 0, 0]]
1023                          1
1024
1025                             val  = 2
1026                                2
1027
1028                             mult  = 2
1029                                 2
1030
1031                vec  = [[0, 0, 1, 0], [0, 0, 0, 1]]
1032                   2
1033
1034 (%o3)                         done
1035 @end group
1036 @end example
1037
1038 @opencatbox{Categories:}
1039 @category{Package eigen}
1040 @closecatbox
1041 @end deffn
1042
1043 @c -----------------------------------------------------------------------------
1044 @anchor{ematrix}
1045 @deffn {Function} ematrix (@var{m}, @var{n}, @var{x}, @var{i}, @var{j})
1046
1047 Returns an @var{m} by @var{n} matrix, all elements of which
1048 are zero except for the @code{[@var{i}, @var{j}]} element which is @var{x}.
1049 @c WOW, THAT SEEMS PRETTY SPECIALIZED ...
1050
1051 @opencatbox{Categories:}
1052 @category{Matrices}
1053 @closecatbox
1054 @end deffn
1055
1056 @c -----------------------------------------------------------------------------
1057 @anchor{entermatrix}
1058 @deffn {Function} entermatrix (@var{m}, @var{n})
1059
1060 Returns an @var{m} by @var{n} matrix, reading the elements interactively.
1061
1062 If @var{n} is equal to @var{m}, Maxima prompts for the type of the matrix
1063 (diagonal, symmetric, antisymmetric, or general) and for each element.
1064 Each response is terminated by a semicolon @code{;} or dollar sign @code{$}.
1065
1066 If @var{n} is not equal to @var{m},
1067 Maxima prompts for each element.
1068
1069 The elements may be any expressions, which are evaluated.
1070 @code{entermatrix} evaluates its arguments.
1071
1072 @example
1073 (%i1) n: 3$
1074 (%i2) m: entermatrix (n, n)$
1075
1076 Is the matrix  1. Diagonal  2. Symmetric  3. Antisymmetric
1077 4. General
1078 Answer 1, 2, 3 or 4 :
1079 1$
1080 Row 1 Column 1:
1081 (a+b)^n$
1082 Row 2 Column 2:
1083 (a+b)^(n+1)$
1084 Row 3 Column 3:
1085 (a+b)^(n+2)$
1086
1087 Matrix entered.
1088 (%i3) m;
1089                 [        3                     ]
1090                 [ (b + a)      0         0     ]
1091                 [                              ]
1092 (%o3)           [                  4           ]
1093                 [    0      (b + a)      0     ]
1094                 [                              ]
1095                 [                            5 ]
1096                 [    0         0      (b + a)  ]
1097 @end example
1098
1099 @opencatbox{Categories:}
1100 @category{Console interaction}
1101 @category{Matrices}
1102 @closecatbox
1103 @end deffn
1104
1105 @c -----------------------------------------------------------------------------
1106 @anchor{genmatrix}
1107 @deffn  {Function} genmatrix @
1108 @fname{genmatrix} (@var{a}, @var{i_2}, @var{j_2}, @var{i_1}, @var{j_1}) @
1109 @fname{genmatrix} (@var{a}, @var{i_2}, @var{j_2}, @var{i_1}) @
1110 @fname{genmatrix} (@var{a}, @var{i_2}, @var{j_2})
1111
1112 Returns a matrix generated from @var{a}, taking element
1113 @code{@var{a}[@var{i_1}, @var{j_1}]} as the upper-left element and
1114 @code{@var{a}[@var{i_2}, @var{j_2}]} as the lower-right element of the matrix.
1115 Here @var{a} is a declared array (created by @code{array} but not by
1116 @mref{make_array}) or a @mrefcomma{hashed array} or a @mrefcomma{memoizing function} or a lambda
1117 expression of two arguments.  (A @mref{memoizing function} is created like other functions
1118 with @mref{:=} or @mrefcomma{define} but arguments are enclosed in square
1119 brackets instead of parentheses.)
1120
1121 If @var{j_1} is omitted, it is assumed equal to @var{i_1}.
1122 If both @var{j_1} and @var{i_1} are omitted, both are assumed equal to 1.
1123
1124 If a selected element @code{i,j} of the array is undefined,
1125 the matrix will contain a symbolic element @code{@var{a}[i,j]}.
1126
1127 Examples:
1128
1129 @c ===beg===
1130 @c h [i, j] := 1 / (i + j - 1);
1131 @c genmatrix (h, 3, 3);
1132 @c array (a, fixnum, 2, 2);
1133 @c a [1, 1] : %e;
1134 @c a [2, 2] : %pi;
1135 @c genmatrix (a, 2, 2);
1136 @c genmatrix (lambda ([i, j], j - i), 3, 3);
1137 @c genmatrix (B, 2, 2);
1138 @c ===end===
1139 @example
1140 @group
1141 (%i1) h [i, j] := 1 / (i + j - 1);
1142                                     1
1143 (%o1)                  h     := ---------
1144                         i, j    i + j - 1
1145 @end group
1146 @group
1147 (%i2) genmatrix (h, 3, 3);
1148                            [    1  1 ]
1149                            [ 1  -  - ]
1150                            [    2  3 ]
1151                            [         ]
1152                            [ 1  1  1 ]
1153 (%o2)                      [ -  -  - ]
1154                            [ 2  3  4 ]
1155                            [         ]
1156                            [ 1  1  1 ]
1157                            [ -  -  - ]
1158                            [ 3  4  5 ]
1159 @end group
1160 @group
1161 (%i3) array (a, fixnum, 2, 2);
1162 (%o3)                           a
1163 @end group
1164 @group
1165 (%i4) a [1, 1] : %e;
1166 (%o4)                          %e
1167 @end group
1168 @group
1169 (%i5) a [2, 2] : %pi;
1170 (%o5)                          %pi
1171 @end group
1172 @group
1173 (%i6) genmatrix (a, 2, 2);
1174                            [ %e   0  ]
1175 (%o6)                      [         ]
1176                            [ 0   %pi ]
1177 @end group
1178 @group
1179 (%i7) genmatrix (lambda ([i, j], j - i), 3, 3);
1180                          [  0    1   2 ]
1181                          [             ]
1182 (%o7)                    [ - 1   0   1 ]
1183                          [             ]
1184                          [ - 2  - 1  0 ]
1185 @end group
1186 @group
1187 (%i8) genmatrix (B, 2, 2);
1188                         [ B      B     ]
1189                         [  1, 1   1, 2 ]
1190 (%o8)                   [              ]
1191                         [ B      B     ]
1192                         [  2, 1   2, 2 ]
1193 @end group
1194 @end example
1195
1196 @opencatbox{Categories:}
1197 @category{Matrices}
1198 @closecatbox
1199 @end deffn
1200
1201 @c -----------------------------------------------------------------------------
1202 @anchor{gramschmidt}
1203 @deffn  {Function} gramschmidt @
1204 @fname{gramschmidt} (@var{x}) @
1205 @fname{gramschmidt} (@var{x}, @var{F})
1206
1207 Carries out the Gram-Schmidt orthogonalization algorithm on @var{x}, which is
1208 either a matrix or a list of lists.  @var{x} is not modified by
1209 @code{gramschmidt}.  The inner product employed by @code{gramschmidt} is
1210 @var{F}, if present, otherwise the inner product is the function
1211 @mrefdot{innerproduct}
1212
1213 If @var{x} is a matrix, the algorithm is applied to the rows of @var{x}.  If
1214 @var{x} is a list of lists, the algorithm is applied to the sublists, which must
1215 have equal numbers of elements.  In either case, the return value is a list of
1216 lists, the sublists of which are orthogonal and span the same space as @var{x}.
1217 If the dimension of the span of @var{x} is less than the number of rows or
1218 sublists, some sublists of the return value are zero.
1219
1220 @mref{factor} is called at each stage of the algorithm to simplify intermediate
1221 results.  As a consequence, the return value may contain factored integers.
1222
1223 @code{load("eigen")} loads this function.
1224
1225 Example:
1226
1227 Gram-Schmidt algorithm using default inner product function.
1228
1229 @c ===beg===
1230 @c load ("eigen")$
1231 @c x: matrix ([1, 2, 3], [9, 18, 30], [12, 48, 60]);
1232 @c y: gramschmidt (x);
1233 @c map (innerproduct, [y[1], y[2], y[3]], [y[2], y[3], y[1]]);
1234 @c ===end===
1235 @example
1236 (%i1) load ("eigen")$
1237 @group
1238 (%i2) x: matrix ([1, 2, 3], [9, 18, 30], [12, 48, 60]);
1239                          [ 1   2   3  ]
1240                          [            ]
1241 (%o2)                    [ 9   18  30 ]
1242                          [            ]
1243                          [ 12  48  60 ]
1244 @end group
1245 @group
1246 (%i3) y: gramschmidt (x);
1247                        2      2            4     3
1248                       3      3   3 5      2  3  2  3
1249 (%o3)  [[1, 2, 3], [- ---, - --, ---], [- ----, ----, 0]]
1250                       2 7    7   2 7       5     5
1251 @end group
1252 @group
1253 (%i4) map (innerproduct, [y[1], y[2], y[3]], [y[2], y[3], y[1]]);
1254 (%o4)                       [0, 0, 0]
1255 @end group
1256 @end example
1257
1258 Gram-Schmidt algorithm using a specified inner product function.
1259
1260 @c ===beg===
1261 @c load ("eigen")$
1262 @c ip (f, g) := integrate (f * g, u, a, b);
1263 @c y: gramschmidt ([1, sin(u), cos(u)], ip), a=-%pi/2, b=%pi/2;
1264 @c map (ip, [y[1], y[2], y[3]], [y[2], y[3], y[1]]), a=-%pi/2,
1265 @c          b=%pi/2;
1266 @c ===end===
1267 @example
1268 (%i1) load ("eigen")$
1269 @group
1270 (%i2) ip (f, g) := integrate (f * g, u, a, b);
1271 (%o2)          ip(f, g) := integrate(f g, u, a, b)
1272 @end group
1273 @group
1274 (%i3) y: gramschmidt ([1, sin(u), cos(u)], ip), a=-%pi/2, b=%pi/2;
1275                                %pi cos(u) - 2
1276 (%o3)              [1, sin(u), --------------]
1277                                     %pi
1278 @end group
1279 @group
1280 (%i4) map (ip, [y[1], y[2], y[3]], [y[2], y[3], y[1]]), a=-%pi/2,
1281          b=%pi/2;
1282 (%o4)                       [0, 0, 0]
1283 @end group
1284 @end example
1285
1286 @opencatbox{Categories:}
1287 @category{Package eigen}
1288 @closecatbox
1289 @end deffn
1290
1291 @c -----------------------------------------------------------------------------
1292 @anchor{ident}
1293 @deffn {Function} ident (@var{n})
1294
1295 Returns an @var{n} by @var{n} identity matrix.
1296
1297 @opencatbox{Categories:}
1298 @category{Matrices}
1299 @closecatbox
1300 @end deffn
1301
1302 @c -----------------------------------------------------------------------------
1303 @anchor{innerproduct}
1304 @anchor{inprod}
1305 @deffn  {Function} innerproduct (@var{x}, @var{y})
1306 @deffnx {Function} inprod (@var{x}, @var{y})
1307
1308 Returns the inner product (also called the scalar product or dot product) of
1309 @var{x} and @var{y}, which are lists of equal length, or both 1-column or 1-row
1310 matrices of equal length.  The return value is @code{conjugate (x) . y},
1311 where @code{.} is the noncommutative multiplication operator.
1312
1313 @code{load ("eigen")} loads this function.
1314
1315 @code{inprod} is a synonym for @code{innerproduct}.
1316
1317 @c NEED EXAMPLE HERE
1318 @opencatbox{Categories:}
1319 @category{Package eigen}
1320 @closecatbox
1321 @end deffn
1322
1323 @c -----------------------------------------------------------------------------
1324 @anchor{invert_by_adjoint}
1325 @deffn {Function} invert_by_adjoint (@var{M})
1326 Returns the inverse of the matrix @var{M}.
1327 The inverse is computed by the adjoint method.
1328
1329 @code{invert_by_adjoint} honors the @mref{ratmx} and @mref{detout} flags,
1330 the same as @mrefdot{invert}
1331
1332 @end deffn
1333
1334 @c -----------------------------------------------------------------------------
1335 @anchor{invert}
1336 @deffn {Function} invert (@var{M})
1337
1338 Returns the inverse of the matrix @var{M}.
1339 The inverse is computed via the LU decomposition.
1340
1341 When @mref{ratmx} is @code{true},
1342 elements of @var{M} are converted to canonical rational expressions (CRE),
1343 and the elements of the return value are also CRE.
1344
1345 When @mref{ratmx} is @code{false},
1346 elements of @var{M} are not converted to a common representation.
1347 In particular, float and bigfloat elements are not converted to rationals.
1348
1349 When @mref{detout} is @code{true}, the determinant is factored out of the inverse.
1350 The global flags @mref{doallmxops} and @mref{doscmxops} must be @code{false}
1351 to prevent the determinant from being absorbed into the inverse.
1352 @mref{xthru} can multiply the determinant into the inverse.
1353
1354 @mref{invert} does not apply any simplifications to the elements of the inverse
1355 apart from the default arithmetic simplifications.
1356 @mref{ratsimp} and @mref{expand} can apply additional simplifications.
1357 In particular, when @var{M} has polynomial elements,
1358 @code{expand(invert(@var{M}))} might be preferable.
1359
1360 @code{invert(@var{M})} is equivalent to @code{@var{M}^^-1}.
1361
1362 @c NEED EXAMPLES HERE
1363 @opencatbox{Categories:}
1364 @category{Matrices}
1365 @closecatbox
1366 @end deffn
1367
1368 @c -----------------------------------------------------------------------------
1369 @anchor{list_matrix_entries}
1370 @deffn {Function} list_matrix_entries (@var{M})
1371
1372 Returns a list containing the elements of the matrix @var{M}.
1373
1374 Example:
1375
1376 @c ===beg===
1377 @c list_matrix_entries(matrix([a,b],[c,d]));
1378 @c ===end===
1379 @example
1380 @group
1381 (%i1) list_matrix_entries(matrix([a,b],[c,d]));
1382 (%o1)                     [a, b, c, d]
1383 @end group
1384 @end example
1385
1386 @opencatbox{Categories:}
1387 @category{Matrices}
1388 @closecatbox
1389 @end deffn
1390
1391 @c -----------------------------------------------------------------------------
1392 @anchor{lmxchar}
1393 @defvr {Option variable} lmxchar
1394 Default value: @code{[}
1395
1396 @code{lmxchar} is the character displayed as the left delimiter of a matrix.
1397 See also @mrefdot{rmxchar}
1398
1399 Example:
1400
1401 @example
1402 (%i1) lmxchar: "|"$
1403 (%i2) matrix ([a, b, c], [d, e, f], [g, h, i]);
1404                            | a  b  c ]
1405                            |         ]
1406 (%o2)                      | d  e  f ]
1407                            |         ]
1408                            | g  h  i ]
1409 @end example
1410
1411 @opencatbox{Categories:}
1412 @category{Display flags and variables}
1413 @category{Matrices}
1414 @closecatbox
1415 @end defvr
1416
1417 @c -----------------------------------------------------------------------------
1418 @anchor{matrix}
1419 @deffn {Function} matrix (@var{row_1}, @dots{}, @var{row_n})
1420
1421 Returns a rectangular matrix which has the rows @var{row_1}, @dots{},
1422 @var{row_n}.  Each row is a list of expressions.  All rows must be the same
1423 length.
1424
1425 The operations @code{+} (addition), @code{-} (subtraction), @code{*}
1426 (multiplication), and @code{/} (division), are carried out element by element
1427 when the operands are two matrices, a scalar and a matrix, or a matrix and a
1428 scalar.  The operation @code{^} (exponentiation, equivalently @code{**})
1429 is carried out element by element if the operands are a scalar and a matrix or
1430 a matrix and a scalar, but not if the operands are two matrices.
1431 @c WHAT DOES THIS NEXT PHRASE MEAN EXACTLY ??
1432 All operations are normally carried out in full,
1433 including @code{.} (noncommutative multiplication).
1434
1435 Matrix multiplication is represented by the noncommutative multiplication
1436 operator @code{.}.  The corresponding noncommutative exponentiation operator
1437 is @code{^^}.  For a matrix @code{@var{A}}, @code{@var{A}.@var{A} = @var{A}^^2}
1438 and @code{@var{A}^^-1} is the inverse of @var{A}, if it exists.
1439 @code{@var{A}^^-1} is equivalent to @code{invert(@var{A})}.
1440
1441 There are switches for controlling simplification of expressions involving dot
1442 and matrix-list operations.  These are
1443 @mrefcomma{doallmxops} @mrefcomma{domxexpt} @mrefcomma{domxmxops}@w{}
1444 @mrefcomma{doscmxops} and @mrefdot{doscmxplus}
1445 @c CHECK -- WE PROBABLY WANT EXHAUSTIVE LIST HERE
1446
1447 There are additional options which are related to matrices.  These are:
1448 @mrefcomma{lmxchar} @mrefcomma{rmxchar} @mrefcomma{ratmx}@w{}
1449 @mrefcomma{listarith} @mrefcomma{detout} @code{scalarmatrix} and
1450 @mrefdot{sparse}
1451 @c CHECK -- WE PROBABLY WANT EXHAUSTIVE LIST HERE
1452
1453 There are a number of functions which take matrices as arguments or yield
1454 matrices as return values.
1455 See @mrefcomma{eigenvalues} @mrefcomma{eigenvectors} @mrefcomma{determinant}@w{}
1456 @mrefcomma{charpoly} @mrefcomma{genmatrix} @mrefcomma{addcol}@w{}
1457 @mrefcomma{addrow} @mrefcomma{copymatrix} @mrefcomma{transpose}@w{}
1458 @mrefcomma{echelon} and @mrefdot{rank}
1459 @c CHECK -- WE PROBABLY WANT EXHAUSTIVE LIST HERE
1460
1461 Examples:
1462
1463 @itemize @bullet
1464 @item
1465 Construction of matrices from lists.
1466 @end itemize
1467 @example
1468 (%i1) x: matrix ([17, 3], [-8, 11]);
1469                            [ 17   3  ]
1470 (%o1)                      [         ]
1471                            [ - 8  11 ]
1472 (%i2) y: matrix ([%pi, %e], [a, b]);
1473                            [ %pi  %e ]
1474 (%o2)                      [         ]
1475                            [  a   b  ]
1476 @end example
1477 @itemize @bullet
1478 @item
1479 Addition, element by element.
1480 @end itemize
1481 @example
1482 (%i3) x + y;
1483                       [ %pi + 17  %e + 3 ]
1484 (%o3)                 [                  ]
1485                       [  a - 8    b + 11 ]
1486 @end example
1487 @itemize @bullet
1488 @item
1489 Subtraction, element by element.
1490 @end itemize
1491 @example
1492 (%i4) x - y;
1493                       [ 17 - %pi  3 - %e ]
1494 (%o4)                 [                  ]
1495                       [ - a - 8   11 - b ]
1496 @end example
1497 @itemize @bullet
1498 @item
1499 Multiplication, element by element.
1500 @end itemize
1501 @example
1502 (%i5) x * y;
1503                         [ 17 %pi  3 %e ]
1504 (%o5)                   [              ]
1505                         [ - 8 a   11 b ]
1506 @end example
1507 @itemize @bullet
1508 @item
1509 Division, element by element.
1510 @end itemize
1511 @example
1512 (%i6) x / y;
1513                         [ 17       - 1 ]
1514                         [ ---  3 %e    ]
1515                         [ %pi          ]
1516 (%o6)                   [              ]
1517                         [   8    11    ]
1518                         [ - -    --    ]
1519                         [   a    b     ]
1520 @end example
1521 @itemize @bullet
1522 @item
1523 Matrix to a scalar exponent, element by element.
1524 @end itemize
1525 @example
1526 (%i7) x ^ 3;
1527                          [ 4913    27  ]
1528 (%o7)                    [             ]
1529                          [ - 512  1331 ]
1530 @end example
1531 @itemize @bullet
1532 @item
1533 Scalar base to a matrix exponent, element by element.
1534 @end itemize
1535 @example
1536 (%i8) exp(y);
1537                          [   %pi    %e ]
1538                          [ %e     %e   ]
1539 (%o8)                    [             ]
1540                          [    a     b  ]
1541                          [  %e    %e   ]
1542 @end example
1543 @itemize @bullet
1544 @item
1545 Matrix base to a matrix exponent.  This is not carried out element by element.
1546 See also @mrefdot{matrixexp}
1547 @c WHAT IS THIS ??
1548 @end itemize
1549 @example
1550 (%i9) x ^ y;
1551                                 [ %pi  %e ]
1552                                 [         ]
1553                                 [  a   b  ]
1554                      [ 17   3  ]
1555 (%o9)                [         ]
1556                      [ - 8  11 ]
1557 @end example
1558 @itemize @bullet
1559 @item
1560 Noncommutative matrix multiplication.
1561 @end itemize
1562 @example
1563 (%i10) x . y;
1564                   [ 3 a + 17 %pi  3 b + 17 %e ]
1565 (%o10)            [                           ]
1566                   [ 11 a - 8 %pi  11 b - 8 %e ]
1567 (%i11) y . x;
1568                 [ 17 %pi - 8 %e  3 %pi + 11 %e ]
1569 (%o11)          [                              ]
1570                 [  17 a - 8 b     11 b + 3 a   ]
1571 @end example
1572 @itemize @bullet
1573 @item
1574 Noncommutative matrix exponentiation.
1575 A scalar base @var{b} to a matrix power @var{M}
1576 is carried out element by element and so @code{b^^m} is the same as @code{b^m}.
1577 @end itemize
1578 @example
1579 (%i12) x ^^ 3;
1580                         [  3833   1719 ]
1581 (%o12)                  [              ]
1582                         [ - 4584  395  ]
1583 (%i13) %e ^^ y;
1584 @group
1585                          [   %pi    %e ]
1586                          [ %e     %e   ]
1587 (%o13)                   [             ]
1588                          [    a     b  ]
1589                          [  %e    %e   ]
1590 @end group
1591 @end example
1592 @itemize @bullet
1593 @item
1594 A matrix raised to a -1 exponent with noncommutative exponentiation is the
1595 matrix inverse, if it exists.
1596 @end itemize
1597 @example
1598 (%i14) x ^^ -1;
1599                          [ 11      3  ]
1600                          [ ---  - --- ]
1601                          [ 211    211 ]
1602 (%o14)                   [            ]
1603                          [  8    17   ]
1604                          [ ---   ---  ]
1605                          [ 211   211  ]
1606 (%i15) x . (x ^^ -1);
1607                             [ 1  0 ]
1608 (%o15)                      [      ]
1609                             [ 0  1 ]
1610 @end example
1611
1612 @opencatbox{Categories:}
1613 @category{Matrices}
1614 @closecatbox
1615 @end deffn
1616
1617 @c -----------------------------------------------------------------------------
1618 @anchor{matrixexp}
1619 @deffn {Function} matrixexp @
1620 @fname{matrixexp} (@var{M}) @
1621 @fname{matrixexp} (@var{M}, @var{n}) @
1622 @fname{matrixexp} (@var{M}, @var{V})
1623
1624 Calculates the matrix exponential
1625 @ifnotinfo
1626 @tex
1627 @math{e^{MV}}
1628 @end tex
1629 @ifset mathjax
1630 @html
1631 $$e^{M\cdot V}$$
1632 @end html
1633 @end ifset
1634 @ifclear mathjax
1635 @math{e^(M*V)}
1636 @end ifclear
1637 @end ifnotinfo
1638 @ifinfo
1639 @math{e^(M*V)}
1640 @end ifinfo
1641 . Instead of the vector @var{V} a number @var{n} can be specified as the second
1642 argument. If this argument is omitted @code{matrixexp} replaces it by @code{1}.
1643
1644 The matrix exponential of a matrix @var{M} can be expressed as a power series:
1645 @ifnotinfo
1646 @tex
1647 @math{e^M=\sum_{k=0}^\infty{{M^k}\over{k!}}}
1648 @end tex
1649 @ifset mathjax
1650 @html
1651 $$e^M=\sum_{k=0}^\infty{\left(\frac{M^k}{k!}\right)}$$
1652 @end html
1653 @end ifset
1654 @ifclear mathjax
1655 @math{e^M=sum(M^k/k!,0,inf)}
1656 @end ifclear
1657 @end ifnotinfo
1658 @ifinfo
1659 @math{e^M=sum(M^k/k!,0,inf)}
1660 @end ifinfo
1661
1662 @c NEED EXAMPLE HERE
1663 @opencatbox{Categories:}
1664 @category{Matrices}
1665 @closecatbox
1666 @end deffn
1667
1668
1669 @c -----------------------------------------------------------------------------
1670 @anchor{matrixmap}
1671 @deffn {Function} matrixmap (@var{f}, @var{M})
1672
1673 Returns a matrix with element @code{i,j} equal to @code{@var{f}(@var{M}[i,j])}.
1674
1675 See also @mrefcomma{map} @mrefcomma{fullmap} @mrefcomma{fullmapl} and
1676 @mrefdot{apply}
1677
1678 @c NEED EXAMPLE HERE
1679 @opencatbox{Categories:}
1680 @category{Matrices}
1681 @closecatbox
1682 @end deffn
1683
1684 @c -----------------------------------------------------------------------------
1685 @anchor{matrixp}
1686 @deffn {Function} matrixp (@var{expr})
1687
1688 Returns @code{true} if @var{expr} is a matrix, otherwise @code{false}.
1689
1690 @opencatbox{Categories:}
1691 @category{Predicate functions}
1692 @category{Matrices}
1693 @closecatbox
1694 @end deffn
1695
1696 @c -----------------------------------------------------------------------------
1697 @anchor{matrix_element_add}
1698 @defvr {Option variable} matrix_element_add
1699 Default value: @code{+}
1700
1701 @code{matrix_element_add} is the operation
1702 invoked in place of addition in a matrix multiplication.
1703 @code{matrix_element_add} can be assigned any n-ary operator
1704 (that is, a function which handles any number of arguments).
1705 The assigned value may be the name of an operator enclosed in quote marks,
1706 the name of a function,
1707 or a lambda expression.
1708
1709 See also @mref{matrix_element_mult} and @mrefdot{matrix_element_transpose}
1710
1711 Example:
1712
1713 @example
1714 (%i1) matrix_element_add: "*"$
1715 (%i2) matrix_element_mult: "^"$
1716 (%i3) aa: matrix ([a, b, c], [d, e, f]);
1717                            [ a  b  c ]
1718 (%o3)                      [         ]
1719                            [ d  e  f ]
1720 (%i4) bb: matrix ([u, v, w], [x, y, z]);
1721 @group
1722                            [ u  v  w ]
1723 (%o4)                      [         ]
1724                            [ x  y  z ]
1725 @end group
1726 (%i5) aa . transpose (bb);
1727                      [  u  v  w   x  y  z ]
1728                      [ a  b  c   a  b  c  ]
1729 (%o5)                [                    ]
1730                      [  u  v  w   x  y  z ]
1731                      [ d  e  f   d  e  f  ]
1732 @end example
1733
1734 @opencatbox{Categories:}
1735 @category{Matrices}
1736 @closecatbox
1737 @end defvr
1738
1739 @c -----------------------------------------------------------------------------
1740 @anchor{matrix_element_mult}
1741 @defvr {Option variable} matrix_element_mult
1742 Default value: @code{*}
1743
1744 @code{matrix_element_mult} is the operation
1745 invoked in place of multiplication in a matrix multiplication.
1746 @code{matrix_element_mult} can be assigned any binary operator.
1747 The assigned value may be the name of an operator enclosed in quote marks,
1748 the name of a function,
1749 or a lambda expression.
1750
1751 The dot operator @code{.} is a useful choice in some contexts.
1752
1753 See also @mref{matrix_element_add} and @mrefdot{matrix_element_transpose}
1754
1755 Example:
1756
1757 @example
1758 (%i1) matrix_element_add: lambda ([[x]], sqrt (apply ("+", x)))$
1759 (%i2) matrix_element_mult: lambda ([x, y], (x - y)^2)$
1760 (%i3) [a, b, c] . [x, y, z];
1761                           2          2          2
1762 (%o3)         sqrt((c - z)  + (b - y)  + (a - x) )
1763 (%i4) aa: matrix ([a, b, c], [d, e, f]);
1764                            [ a  b  c ]
1765 (%o4)                      [         ]
1766                            [ d  e  f ]
1767 (%i5) bb: matrix ([u, v, w], [x, y, z]);
1768                            [ u  v  w ]
1769 (%o5)                      [         ]
1770                            [ x  y  z ]
1771 (%i6) aa . transpose (bb);
1772                [             2          2          2  ]
1773                [ sqrt((c - w)  + (b - v)  + (a - u) ) ]
1774 (%o6)  Col 1 = [                                      ]
1775                [             2          2          2  ]
1776                [ sqrt((f - w)  + (e - v)  + (d - u) ) ]
1777
1778                          [             2          2          2  ]
1779                          [ sqrt((c - z)  + (b - y)  + (a - x) ) ]
1780                  Col 2 = [                                      ]
1781                          [             2          2          2  ]
1782                          [ sqrt((f - z)  + (e - y)  + (d - x) ) ]
1783 @end example
1784
1785 @opencatbox{Categories:}
1786 @category{Matrices}
1787 @closecatbox
1788 @end defvr
1789
1790 @c -----------------------------------------------------------------------------
1791 @anchor{matrix_element_transpose}
1792 @defvr {Option variable} matrix_element_transpose
1793 Default value: @code{false}
1794
1795 @code{matrix_element_transpose} is the operation
1796 applied to each element of a matrix when it is transposed.
1797 @mref{matrix_element_mult} can be assigned any unary operator.
1798 The assigned value may be the name of an operator enclosed in quote marks,
1799 the name of a function, or a lambda expression.
1800
1801 When @code{matrix_element_transpose} equals @mrefcomma{transpose}
1802 the @code{transpose} function is applied to every element.
1803 When @code{matrix_element_transpose} equals @code{nonscalars},
1804 the @code{transpose} function is applied to every nonscalar element.
1805 If some element is an atom, the @code{nonscalars} option applies
1806 @code{transpose} only if the atom is declared nonscalar,
1807 while the @code{transpose} option always applies @code{transpose}.
1808
1809 The default value, @code{false}, means no operation is applied.
1810
1811 See also @mref{matrix_element_add} and @mrefdot{matrix_element_mult}
1812
1813 Examples:
1814
1815 @example
1816 (%i1) declare (a, nonscalar)$
1817 (%i2) transpose ([a, b]);
1818                         [ transpose(a) ]
1819 (%o2)                   [              ]
1820                         [      b       ]
1821 (%i3) matrix_element_transpose: nonscalars$
1822 (%i4) transpose ([a, b]);
1823                         [ transpose(a) ]
1824 (%o4)                   [              ]
1825                         [      b       ]
1826 (%i5) matrix_element_transpose: transpose$
1827 (%i6) transpose ([a, b]);
1828                         [ transpose(a) ]
1829 (%o6)                   [              ]
1830                         [ transpose(b) ]
1831 (%i7) matrix_element_transpose: lambda ([x], realpart(x)
1832       - %i*imagpart(x))$
1833 (%i8) m: matrix ([1 + 5*%i, 3 - 2*%i], [7*%i, 11]);
1834                      [ 5 %i + 1  3 - 2 %i ]
1835 (%o8)                [                    ]
1836                      [   7 %i       11    ]
1837 (%i9) transpose (m);
1838                       [ 1 - 5 %i  - 7 %i ]
1839 (%o9)                 [                  ]
1840                       [ 2 %i + 3    11   ]
1841 @end example
1842
1843 @opencatbox{Categories:}
1844 @category{Matrices}
1845 @closecatbox
1846 @end defvr
1847
1848 @c IS THIS THE ONLY MATRIX TRACE FUNCTION ??
1849
1850 @c -----------------------------------------------------------------------------
1851 @anchor{mattrace}
1852 @deffn {Function} mattrace (@var{M})
1853
1854 Returns the trace (that is, the sum of the elements on the main diagonal) of
1855 the square matrix @var{M}.
1856
1857 @code{mattrace} is called by @mrefcomma{ncharpoly} an alternative to Maxima's
1858 @mrefdot{charpoly}
1859 @c UMM, HOW IS THAT RELEVANT HERE ??
1860
1861 @code{load ("nchrpl")} loads this function.
1862
1863 @opencatbox{Categories:}
1864 @category{Matrices}
1865 @category{Package nchrpl}
1866 @closecatbox
1867 @end deffn
1868
1869 @c -----------------------------------------------------------------------------
1870 @anchor{minor}
1871 @deffn {Function} minor (@var{M}, @var{i}, @var{j})
1872
1873 Returns the @var{i}, @var{j} minor of the matrix @var{M}.  That is, @var{M}
1874 with row @var{i} and column @var{j} removed.
1875
1876 @opencatbox{Categories:}
1877 @category{Matrices}
1878 @closecatbox
1879 @end deffn
1880
1881 @c -----------------------------------------------------------------------------
1882 @anchor{ncharpoly}
1883 @deffn {Function} ncharpoly (@var{M}, @var{x})
1884
1885 Returns the characteristic polynomial of the matrix @var{M}
1886 with respect to @var{x}.  This is an alternative to Maxima's @mrefdot{charpoly}
1887
1888 @code{ncharpoly} works by computing traces of powers of the given matrix,
1889 which are known to be equal to sums of powers of the roots of the
1890 characteristic polynomial.  From these quantities the symmetric
1891 functions of the roots can be calculated, which are nothing more than
1892 the coefficients of the characteristic polynomial.  @code{charpoly} works by
1893 @c SHOULD THAT BE "m" INSTEAD OF "a" IN THE NEXT LINE ??
1894 forming the determinant of @code{@var{x} * ident [n] - a}.  Thus
1895 @code{ncharpoly} wins, for example, in the case of large dense matrices filled
1896 with integers, since it avoids polynomial arithmetic altogether.
1897
1898 @code{load ("nchrpl")} loads this file.
1899
1900 @opencatbox{Categories:}
1901 @category{Matrices}
1902 @category{Package nchrpl}
1903 @closecatbox
1904 @end deffn
1905
1906 @c -----------------------------------------------------------------------------
1907 @anchor{newdet}
1908 @deffn {Function} newdet (@var{M})
1909
1910 Computes the determinant of the matrix @var{M} by the Johnson-Gentleman tree
1911 minor algorithm.  @code{newdet} returns the result in CRE form.
1912
1913 @opencatbox{Categories:}
1914 @category{Matrices}
1915 @closecatbox
1916 @end deffn
1917
1918 @c -----------------------------------------------------------------------------
1919 @anchor{permanent}
1920 @deffn {Function} permanent (@var{M})
1921
1922 Computes the permanent of the matrix @var{M} by the Johnson-Gentleman tree
1923 minor algorithm.  A permanent is like a determinant but with no sign changes.
1924 @code{permanent} returns the result in CRE form.
1925
1926 See also @code{newdet}.
1927
1928 @opencatbox{Categories:}
1929 @category{Matrices}
1930 @closecatbox
1931 @end deffn
1932
1933 @c -----------------------------------------------------------------------------
1934 @anchor{rank}
1935 @deffn {Function} rank (@var{M})
1936
1937 Computes the rank of the matrix @var{M}.  That is, the order of the
1938 largest non-singular subdeterminant of @var{M}.
1939
1940 @c STATEMENT NEEDS CLARIFICATION
1941 @var{rank} may return the
1942 wrong answer if it cannot determine that a matrix element that is
1943 equivalent to zero is indeed so.
1944
1945 @opencatbox{Categories:}
1946 @category{Matrices}
1947 @closecatbox
1948 @end deffn
1949
1950 @c -----------------------------------------------------------------------------
1951 @anchor{ratmx}
1952 @defvr {Option variable} ratmx
1953 Default value: @code{false}
1954
1955 When @code{ratmx} is @code{false}, determinant and matrix
1956 addition, subtraction, and multiplication are performed in the
1957 representation of the matrix elements and cause the result of
1958 matrix inversion to be left in general representation.
1959
1960 When @code{ratmx} is @code{true},
1961 the 4 operations mentioned above are performed in CRE form and the
1962 result of matrix inverse is in CRE form.  Note that this may
1963 cause the elements to be expanded (depending on the setting of @mref{ratfac})
1964 which might not always be desired.
1965
1966 @opencatbox{Categories:}
1967 @category{Matrices}
1968 @category{Rational expressions}
1969 @closecatbox
1970 @end defvr
1971
1972 @c -----------------------------------------------------------------------------
1973 @anchor{row}
1974 @deffn {Function} row (@var{M}, @var{i})
1975
1976 Returns the @var{i}'th row of the matrix @var{M}.
1977 The return value is a matrix.
1978
1979 @opencatbox{Categories:}
1980 @category{Matrices}
1981 @closecatbox
1982 @end deffn
1983
1984 @c -----------------------------------------------------------------------------
1985 @anchor{rmxchar}
1986 @defvr {Option variable} rmxchar
1987 Default value: @code{]}
1988
1989 @code{rmxchar} is the character drawn on the right-hand side of a matrix.
1990
1991 See also @mrefdot{lmxchar}
1992
1993 @opencatbox{Categories:}
1994 @category{Display flags and variables}
1995 @closecatbox
1996 @end defvr
1997
1998 @c -----------------------------------------------------------------------------
1999 @anchor{scalarmatrixp}
2000 @defvr {Option variable} scalarmatrixp
2001 Default value: @code{true}
2002
2003 When @code{scalarmatrixp} is @code{true}, then whenever a 1 x 1 matrix
2004 is produced as a result of computing the dot product of matrices it
2005 is simplified to a scalar, namely the sole element of the matrix.
2006
2007 When @code{scalarmatrixp} is @code{all},
2008 then all 1 x 1 matrices are simplified to scalars.
2009
2010 When @code{scalarmatrixp} is @code{false}, 1 x 1 matrices are not simplified
2011 to scalars.
2012
2013 @opencatbox{Categories:}
2014 @category{Matrices}
2015 @category{Simplification flags and variables}
2016 @closecatbox
2017 @end defvr
2018
2019 @c I WONDER WHAT THIS IS ABOUT
2020
2021 @c -----------------------------------------------------------------------------
2022 @anchor{scalefactors}
2023 @deffn {Function} scalefactors (@var{coordinatetransform})
2024
2025 Here the argument @var{coordinatetransform} evaluates to the form
2026 @code{[[expression1, expression2, ...], indeterminate1, indeterminat2, ...]},
2027 where the variables @var{indeterminate1}, @var{indeterminate2}, etc. are the
2028 curvilinear coordinate variables and where a set of rectangular Cartesian
2029 components is given in terms of the curvilinear coordinates by
2030 @code{[expression1, expression2, ...]}.  @code{coordinates} is set to the vector
2031 @code{[indeterminate1, indeterminate2,...]}, and @code{dimension} is set to the
2032 length of this vector.  SF[1], SF[2], @dots{}, SF[DIMENSION] are set to the
2033 coordinate scale factors, and @code{sfprod} is set to the product of these scale
2034 factors.  Initially, @code{coordinates} is @code{[X, Y, Z]}, @code{dimension}
2035 is 3, and SF[1]=SF[2]=SF[3]=SFPROD=1, corresponding to 3-dimensional rectangular
2036 Cartesian coordinates.  To expand an expression into physical components in the
2037 current coordinate system, there is a function with usage of the form
2038 @c SOME TEXT HAS GONE MISSING HERE
2039
2040 @opencatbox{Categories:}
2041 @category{Package vect}
2042 @closecatbox
2043 @end deffn
2044
2045 @c -----------------------------------------------------------------------------
2046 @anchor{setelmx}
2047 @deffn {Function} setelmx (@var{x}, @var{i}, @var{j}, @var{M})
2048
2049 Assigns @var{x} to the (@var{i}, @var{j})'th element of the matrix @var{M},
2050 and returns the altered matrix.
2051
2052 @code{@var{M} [@var{i}, @var{j}]: @var{x}} has the same effect,
2053 but returns @var{x} instead of @var{M}.
2054
2055 @opencatbox{Categories:}
2056 @category{Matrices}
2057 @closecatbox
2058 @end deffn
2059
2060 @c -----------------------------------------------------------------------------
2061 @anchor{similaritytransform}
2062 @anchor{simtran}
2063 @deffn  {Function} similaritytransform (@var{M})
2064 @deffnx {Function} simtran (@var{M})
2065
2066 @code{similaritytransform} computes a similarity transform of the matrix
2067 @code{M}.  It returns a list which is the output of the @code{uniteigenvectors}
2068 command.  In addition if the flag @code{nondiagonalizable} is @code{false} two
2069 global matrices @code{leftmatrix} and @code{rightmatrix} are computed.  These
2070 matrices have the property that @code{leftmatrix . @var{M} . rightmatrix} is a
2071 diagonal matrix with the eigenvalues of @var{M} on the diagonal.  If
2072 @code{nondiagonalizable} is @code{true} the left and right matrices are not
2073 computed.
2074
2075 If the flag @code{hermitianmatrix} is @code{true} then @code{leftmatrix} is the
2076 complex conjugate of the transpose of @code{rightmatrix}.  Otherwise
2077 @code{leftmatrix} is the inverse of @code{rightmatrix}.
2078
2079 @code{rightmatrix} is the matrix the columns of which are the unit
2080 eigenvectors of @var{M}.  The other flags (see @code{eigenvalues} and
2081 @code{eigenvectors}) have the same effects since
2082 @code{similaritytransform} calls the other functions in the package in order
2083 to be able to form @code{rightmatrix}.
2084
2085 @code{load ("eigen")} loads this function.
2086
2087 @code{simtran} is a synonym for @code{similaritytransform}.
2088
2089 @opencatbox{Categories:}
2090 @category{Package eigen}
2091 @closecatbox
2092 @end deffn
2093
2094 @c -----------------------------------------------------------------------------
2095 @anchor{sparse}
2096 @defvr {Option variable} sparse
2097 Default value: @code{false}
2098
2099 When @code{sparse} is @code{true}, and if @code{ratmx} is @code{true}, then
2100 @code{determinant} will use special routines for computing sparse determinants.
2101
2102 @opencatbox{Categories:}
2103 @category{Matrices}
2104 @closecatbox
2105 @end defvr
2106
2107 @c -----------------------------------------------------------------------------
2108 @anchor{submatrix}
2109 @deffn {Function} submatrix @
2110 @fname{submatrix} (@var{i_1}, @dots{}, @var{i_m}, @var{M}, @var{j_1}, @dots{}, @var{j_n}) @
2111 @fname{submatrix} (@var{i_1}, @dots{}, @var{i_m}, @var{M}) @
2112 @fname{submatrix} (@var{M}, @var{j_1}, @dots{}, @var{j_n})
2113
2114 Returns a new matrix composed of the matrix @var{M} with rows @var{i_1},
2115 @dots{}, @var{i_m} deleted, and columns @var{j_1}, @dots{}, @var{j_n} deleted.
2116
2117 @opencatbox{Categories:}
2118 @category{Matrices}
2119 @closecatbox
2120 @end deffn
2121
2122 @c -----------------------------------------------------------------------------
2123 @anchor{transpose}
2124 @deffn {Function} transpose (@var{M})
2125
2126 Returns the transpose of @var{M}.
2127
2128 If @var{M} is a matrix, the return value is another matrix @var{N}
2129 such that @code{N[i,j] = M[j,i]}.
2130
2131 If @var{M} is a list, the return value is a matrix @var{N}
2132 of @code{length (m)} rows and 1 column, such that @code{N[i,1] = M[i]}.
2133
2134 Otherwise @var{M} is a symbol,
2135 and the return value is a noun expression @code{'transpose (@var{M})}.
2136
2137 @opencatbox{Categories:}
2138 @category{Matrices}
2139 @closecatbox
2140 @end deffn
2141
2142 @c -----------------------------------------------------------------------------
2143 @anchor{triangularize}
2144 @deffn {Function} triangularize (@var{M})
2145
2146 Returns the upper triangular form of the matrix @code{M},
2147 as produced by Gaussian elimination.
2148 The return value is the same as @code{echelon},
2149 except that the leading nonzero coefficient in each row is not normalized to 1.
2150
2151 @code{lu_factor} and @code{cholesky} are other functions which yield
2152 triangularized matrices.
2153
2154 @c ===beg===
2155 @c M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
2156 @c triangularize (M);
2157 @c ===end===
2158 @example
2159 @group
2160 (%i1) M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
2161                        [  3   7  aa  bb ]
2162                        [                ]
2163 (%o1)                  [ - 1  8  5   2  ]
2164                        [                ]
2165                        [  9   2  11  4  ]
2166 @end group
2167 @group
2168 (%i2) triangularize (M);
2169              [ - 1   8         5            2      ]
2170              [                                     ]
2171 (%o2)        [  0   - 74     - 56         - 22     ]
2172              [                                     ]
2173              [  0    0    626 - 74 aa  238 - 74 bb ]
2174 @end group
2175 @end example
2176
2177 @opencatbox{Categories:}
2178 @category{Linear equations}
2179 @category{Matrices}
2180 @closecatbox
2181 @end deffn
2182
2183 @c -----------------------------------------------------------------------------
2184 @anchor{uniteigenvectors}
2185 @anchor{ueivects}
2186 @deffn  {Function} uniteigenvectors (@var{M})
2187 @deffnx {Function} ueivects (@var{M})
2188
2189 Computes unit eigenvectors of the matrix @var{M}.
2190 The return value is a list of lists, the first sublist of which is the
2191 output of the @code{eigenvalues} command, and the other sublists of which are
2192 the unit eigenvectors of the matrix corresponding to those eigenvalues
2193 respectively.
2194
2195 @c COPY DESCRIPTIONS OF THOSE FLAGS HERE
2196 The flags mentioned in the description of the
2197 @code{eigenvectors} command have the same effects in this one as well.
2198
2199 When @code{knowneigvects} is @code{true}, the @code{eigen} package assumes
2200 that the eigenvectors of the matrix are known to the user and are
2201 stored under the global name @code{listeigvects}.  @code{listeigvects} should
2202 be set to a list similar to the output of the @code{eigenvectors} command.
2203
2204 @c FOLLOWING PARAGRAPH IS IN NEED OF SERIOUS CLARIFICATION
2205 If @code{knowneigvects} is set to @code{true} and the list of eigenvectors is
2206 given the setting of the flag @code{nondiagonalizable} may not be correct.  If
2207 that is the case please set it to the correct value.  The author assumes that
2208 the user knows what he is doing and will not try to diagonalize a matrix the
2209 eigenvectors of which do not span the vector space of the appropriate dimension.
2210
2211 @code{load ("eigen")} loads this function.
2212
2213 @code{ueivects} is a synonym for @code{uniteigenvectors}.
2214
2215 @opencatbox{Categories:}
2216 @category{Package eigen}
2217 @closecatbox
2218 @end deffn
2219
2220 @c -----------------------------------------------------------------------------
2221 @anchor{unitvector}
2222 @anchor{uvect}
2223 @deffn  {Function} unitvector (@var{x})
2224 @deffnx {Function} uvect (@var{x})
2225
2226 Returns @math{@var{x}/norm(@var{x})};
2227 this is a unit vector in the same direction as @var{x}.
2228
2229 @code{load ("eigen")} loads this function.
2230
2231 @code{uvect} is a synonym for @code{unitvector}.
2232
2233 @opencatbox{Categories:}
2234 @category{Package eigen}
2235 @closecatbox
2236 @end deffn
2237
2238 @c NEEDS EXAMPLES
2239
2240 @c -----------------------------------------------------------------------------
2241 @anchor{vectorpotential}
2242 @deffn {Function} vectorpotential (@var{givencurl})
2243
2244 Returns the vector potential of a given curl vector, in the current coordinate
2245 system.  @code{potentialzeroloc} has a similar role as for @code{potential}, but
2246 the order of the left-hand sides of the equations must be a cyclic permutation
2247 of the coordinate variables.
2248
2249 @opencatbox{Categories:}
2250 @category{Package vect}
2251 @closecatbox
2252 @end deffn
2253
2254 @c NEEDS A LOT OF WORK: MAKE SURE THAT ALL VECTOR SIMPLIFICATION FLAGS HAVE A
2255 @c DESCRIPTION HERE
2256
2257 @c -----------------------------------------------------------------------------
2258 @anchor{vectorsimp}
2259 @deffn {Function} vectorsimp (@var{expr})
2260
2261 Applies simplifications and expansions according to the following global flags:
2262
2263 @flushleft
2264 @code{expandall}, @code{expanddot}, @code{expanddotplus}, @code{expandcross}, @code{expandcrossplus},
2265 @code{expandcrosscross}, @code{expandgrad}, @code{expandgradplus}, @code{expandgradprod},
2266 @code{expanddiv}, @code{expanddivplus}, @code{expanddivprod}, @code{expandcurl}, @code{expandcurlplus},
2267 @code{expandcurlcurl}, @code{expandlaplacian}, @code{expandlaplacianplus},
2268 and @code{expandlaplacianprod}.
2269 @end flushleft
2270
2271 All these flags have default value @code{false}.  The @code{plus} suffix refers
2272 to employing additivity or distributivity.  The @code{prod} suffix refers to the
2273 expansion for an operand that is any kind of product.
2274
2275 @table @code
2276 @item expandcrosscross
2277 Simplifies @math{p ~ (q ~ r)} to @math{(p . r)*q - (p . q)*r}.
2278 @item expandcurlcurl
2279 Simplifies @math{curl curl p} to @math{grad div p + div grad p}.
2280 @item expandlaplaciantodivgrad
2281 Simplifies @math{laplacian p} to @math{div grad p}.
2282 @item expandcross
2283 Enables @code{expandcrossplus} and @code{expandcrosscross}.
2284 @item expandplus
2285 @flushleft
2286 Enables @code{expanddotplus}, @code{expandcrossplus}, @code{expandgradplus},
2287 @code{expanddivplus}, @code{expandcurlplus}, and @code{expandlaplacianplus}.
2288 @end flushleft
2289 @item expandprod
2290 Enables @code{expandgradprod}, @code{expanddivprod}, and @code{expandlaplacianprod}.
2291 @end table
2292
2293 @c EXPLAIN THE IMPORT OF THIS STATEMENT
2294 These flags have all been declared @code{evflag}.
2295
2296 @c SEEMS SOME TEXT HAS GONE MISSING HERE; COMMENT OUT FRAGMENT PENDING
2297 @c RECOVERY AND/OR RECONSTRUCTION OF THIS PARAGRAPH
2298 @c For orthogonal curvilinear coordinates, the global variables
2299 @c COORDINATES[[X,Y,Z]], DIMENSION[3], SF[[1,1,1]], and SFPROD[1] are set
2300 @c by the function invocation
2301
2302 @opencatbox{Categories:}
2303 @category{Package vect}
2304 @category{Simplification functions}
2305 @closecatbox
2306 @end deffn
2307
2308 @c -----------------------------------------------------------------------------
2309 @anchor{vect_cross}
2310 @defvr {Option variable} vect_cross
2311 Default value: @code{false}
2312
2313 @c WHAT DOES THIS MEAN EXACTLY ??
2314 When @code{vect_cross} is @code{true}, it allows DIFF(X~Y,T) to work where
2315 ~ is defined in SHARE;VECT (where VECT_CROSS is set to @code{true}, anyway.)
2316
2317 @opencatbox{Categories:}
2318 @category{Package vect}
2319 @category{Differential calculus}
2320 @closecatbox
2321 @end defvr
2322
2323 @c -----------------------------------------------------------------------------
2324 @anchor{zeromatrix}
2325 @deffn {Function} zeromatrix (@var{m}, @var{n})
2326
2327 Returns an @var{m} by @var{n} matrix, all elements of which are zero.
2328
2329 @opencatbox{Categories:}
2330 @category{Matrices}
2331 @closecatbox
2332 @end deffn
2333