doc/info/Matrices.texi.m4

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