| blob | aa9cef68f9a5a60f47e1beeff965b7210c567f58 |
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
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 -----------------------------------------------------------------------------
12 @menu
13 * Dot::
14 * Matrices::
15 * Vectors::
16 * eigen::
17 @end menu
19 @c -----------------------------------------------------------------------------
20 @node Dot, Matrices, Introduction to Matrices and Linear Algebra, Introduction to Matrices and Linear Algebra
21 @subsection Dot
22 @c -----------------------------------------------------------------------------
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.
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}.
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}.
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}
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
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 -----------------------------------------------------------------------------
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.
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.
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.
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.
148 @opencatbox{Categories:}
149 @category{Vectors}
150 @category{Share packages}
151 @category{Package vect}
152 @closecatbox
154 @c -----------------------------------------------------------------------------
155 @node eigen, , Vectors, Introduction to Matrices and Linear Algebra
156 @subsection eigen
157 @c -----------------------------------------------------------------------------
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")}.
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.
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}
176 @opencatbox{Categories:}
177 @category{Vectors}
178 @category{Matrices}
179 @category{Share packages}
180 @category{Package eigen}
181 @closecatbox
183 @c end concepts Matrices and Linear Algebra
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 -----------------------------------------------------------------------------
190 @c -----------------------------------------------------------------------------
191 @anchor{addcol}
192 @deffn {Function} addcol (@var{M}, @var{list_1}, @dots{}, @var{list_n})
194 Appends the column(s) given by the one
195 or more lists (or matrices) onto the matrix @var{M}.
197 See also @mref{addrow} and @mrefdot{append}
199 @opencatbox{Categories:}
200 @category{Matrices}
201 @closecatbox
202 @end deffn
204 @c -----------------------------------------------------------------------------
205 @anchor{addrow}
206 @deffn {Function} addrow (@var{M}, @var{list_1}, @dots{}, @var{list_n})
208 Appends the row(s) given by the one or
209 more lists (or matrices) onto the matrix @var{M}.
211 See also @mref{addcol} and @mrefdot{append}
213 @opencatbox{Categories:}
214 @category{Matrices}
215 @closecatbox
216 @end deffn
218 @c -----------------------------------------------------------------------------
219 @anchor{adjoint}
220 @deffn {Function} adjoint (@var{M})
222 Returns the adjoint of the matrix @var{M}.
223 The adjoint matrix is the transpose of the matrix of cofactors of @var{M}.
225 @opencatbox{Categories:}
226 @category{Matrices}
227 @closecatbox
228 @end deffn
230 @c -----------------------------------------------------------------------------
231 @anchor{augcoefmatrix}
232 @deffn {Function} augcoefmatrix ([@var{eqn_1}, @dots{}, @var{eqn_m}], [@var{x_1}, @dots{}, @var{x_n}])
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}).
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
248 @opencatbox{Categories:}
249 @category{Linear equations}
250 @category{Matrices}
251 @closecatbox
252 @end deffn
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}])
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}).
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}).
268 Examples:
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
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
296 @opencatbox{Categories:}
297 @category{Matrices}
298 @closecatbox
299 @end deffn
301 @c -----------------------------------------------------------------------------
302 @anchor{charpoly}
303 @deffn {Function} charpoly (@var{M}, @var{x})
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}))}.
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)
338 1 2
339 [x1 = -------, x2 = -------]]
340 sqrt(5) sqrt(5)
341 @end group
342 @end example
344 @opencatbox{Categories:}
345 @category{Matrices}
346 @closecatbox
347 @end deffn
349 @c -----------------------------------------------------------------------------
350 @anchor{coefmatrix}
351 @deffn {Function} coefmatrix ([@var{eqn_1}, @dots{}, @var{eqn_m}], [@var{x_1}, @dots{}, @var{x_n}])
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}.
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
364 @opencatbox{Categories:}
365 @category{Linear equations}
366 @category{Matrices}
367 @closecatbox
368 @end deffn
370 @c -----------------------------------------------------------------------------
371 @anchor{col}
372 @deffn {Function} col (@var{M}, @var{i})
374 Returns the @var{i}'th column of the matrix @var{M}.
375 The return value is a matrix.
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}.
380 Examples:
382 @code{col} returns the @var{i}'th column of the matrix @var{M}.
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
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}.
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
467 @opencatbox{Categories:}
468 @category{Matrices}
469 @closecatbox
470 @end deffn
472 @c -----------------------------------------------------------------------------
473 @anchor{columnvector}
474 @anchor{covect}
475 @deffn {Function} columnvector (@var{L})
476 @deffnx {Function} covect (@var{L})
478 Returns a matrix of one column and @code{length (@var{L})} rows,
479 containing the elements of the list @var{L}.
481 @code{covect} is a synonym for @code{columnvector}.
483 @code{load ("eigen")} loads this function.
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.
489 Example:
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
507 @opencatbox{Categories:}
508 @category{Matrices}
509 @closecatbox
510 @end deffn
512 @c -----------------------------------------------------------------------------
513 @anchor{copymatrix}
514 @deffn {Function} copymatrix (@var{M})
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.
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.
524 @c NEED EXAMPLE HERE
525 @opencatbox{Categories:}
526 @category{Matrices}
527 @closecatbox
528 @end deffn
530 @c -----------------------------------------------------------------------------
531 @anchor{determinant}
532 @deffn {Function} determinant (@var{M})
534 Computes the determinant of @var{M} by a method similar to
535 Gaussian elimination.
537 @c JUST HOW DOES ratmx AFFECT THE RESULT ??
538 The form of the result depends upon the setting of the switch @mrefdot{ratmx}
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}.
544 @c EXAMPLES NEEDED HERE
545 @opencatbox{Categories:}
546 @category{Matrices}
547 @closecatbox
548 @end deffn
550 @c -----------------------------------------------------------------------------
551 @anchor{detout}
552 @defvr {Option variable} detout
553 Default value: @code{false}
555 When @code{detout} is @code{true}, the determinant of a
556 matrix whose inverse is computed is factored out of the inverse.
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.
562 Example:
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.
582 @opencatbox{Categories:}
583 @category{Matrices}
584 @category{Evaluation flags}
585 @closecatbox
586 @end defvr
588 @c -----------------------------------------------------------------------------
589 @anchor{diagmatrix}
590 @deffn {Function} diagmatrix (@var{n}, @var{x})
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})}).
596 @var{n} must evaluate to an integer, otherwise @code{diagmatrix} complains with
597 an error message.
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}.
603 @c NEED EXAMPLE HERE
604 @opencatbox{Categories:}
605 @category{Matrices}
606 @closecatbox
607 @end deffn
609 @c -----------------------------------------------------------------------------
610 @anchor{doallmxops}
611 @defvr {Option variable} doallmxops
612 Default value: @code{true}
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.
620 @c NEED EXAMPLES HERE
621 @opencatbox{Categories:}
622 @category{Matrices}
623 @closecatbox
624 @end defvr
626 @c -----------------------------------------------------------------------------
627 @anchor{domxexpt}
628 @defvr {Option variable} domxexpt
629 Default value: @code{true}
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)})}.
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.
640 Example:
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
662 @opencatbox{Categories:}
663 @category{Matrices}
664 @closecatbox
665 @end defvr
667 @c -----------------------------------------------------------------------------
668 @anchor{domxmxops}
669 @defvr {Option variable} domxmxops
670 Default value: @code{true}
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 ??
677 @c NEED EXAMPLE HERE
678 @opencatbox{Categories:}
679 @category{Matrices}
680 @closecatbox
681 @end defvr
683 @c -----------------------------------------------------------------------------
684 @anchor{domxnctimes}
685 @defvr {Option variable} domxnctimes
686 Default value: @code{false}
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 ??
692 @c NEED EXAMPLE HERE
693 @opencatbox{Categories:}
694 @category{Matrices}
695 @closecatbox
696 @end defvr
698 @c -----------------------------------------------------------------------------
699 @anchor{dontfactor}
700 @defvr {Option variable} dontfactor
701 Default value: @code{[]}
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.
709 @opencatbox{Categories:}
710 @category{Expressions}
711 @closecatbox
712 @end defvr
714 @c -----------------------------------------------------------------------------
715 @anchor{doscmxops}
716 @defvr {Option variable} doscmxops
717 Default value: @code{false}
719 When @code{doscmxops} is @code{true}, scalar-matrix operations are
720 carried out.
721 @c IS THIS AN EVALUATION OR A SIMPLIFICATION FLAG ??
723 @c NEED EXAMPLE HERE
724 @opencatbox{Categories:}
725 @category{Matrices}
726 @closecatbox
727 @end defvr
729 @c -----------------------------------------------------------------------------
730 @anchor{doscmxplus}
731 @defvr {Option variable} doscmxplus
732 Default value: @code{false}
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 ??
738 @c NEED EXAMPLE HERE
739 @opencatbox{Categories:}
740 @category{Matrices}
741 @closecatbox
742 @end defvr
744 @c -----------------------------------------------------------------------------
745 @anchor{dot0nscsimp}
746 @defvr {Option variable} dot0nscsimp
747 Default value: @code{true}
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.
753 @c NEED EXAMPLE HERE
754 @opencatbox{Categories:}
755 @category{Simplification flags and variables}
756 @closecatbox
757 @end defvr
759 @c -----------------------------------------------------------------------------
760 @anchor{dot0simp}
761 @defvr {Option variable} dot0simp
762 Default value: @code{true}
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.
769 @c NEED EXAMPLE HERE
770 @opencatbox{Categories:}
771 @category{Simplification flags and variables}
772 @closecatbox
773 @end defvr
775 @c -----------------------------------------------------------------------------
776 @anchor{dot1simp}
777 @defvr {Option variable} dot1simp
778 Default value: @code{true}
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.
785 @c NEED EXAMPLE HERE
786 @opencatbox{Categories:}
787 @category{Simplification flags and variables}
788 @closecatbox
789 @end defvr
791 @c -----------------------------------------------------------------------------
792 @anchor{dotassoc}
793 @defvr {Option variable} dotassoc
794 Default value: @code{true}
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 ??
800 @c NEED EXAMPLE HERE
801 @opencatbox{Categories:}
802 @category{Simplification flags and variables}
803 @closecatbox
804 @end defvr
806 @c -----------------------------------------------------------------------------
807 @anchor{dotconstrules}
808 @defvr {Option variable} dotconstrules
809 Default value: @code{true}
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.
818 @c NEED EXAMPLE HERE
819 @opencatbox{Categories:}
820 @category{Simplification flags and variables}
821 @closecatbox
822 @end defvr
824 @c -----------------------------------------------------------------------------
825 @anchor{dotdistrib}
826 @defvr {Option variable} dotdistrib
827 Default value: @code{false}
829 When @code{dotdistrib} is @code{true}, an expression @code{A.(B + C)} simplifies
830 to @code{A.B + A.C}.
832 @c NEED EXAMPLE HERE
833 @opencatbox{Categories:}
834 @category{Simplification flags and variables}
835 @closecatbox
836 @end defvr
838 @c -----------------------------------------------------------------------------
839 @anchor{dotexptsimp}
840 @defvr {Option variable} dotexptsimp
841 Default value: @code{true}
843 When @code{dotexptsimp} is @code{true}, an expression @code{A.A} simplifies to
844 @code{A^^2}.
846 @c NEED EXAMPLE HERE
847 @opencatbox{Categories:}
848 @category{Simplification flags and variables}
849 @closecatbox
850 @end defvr
852 @c -----------------------------------------------------------------------------
853 @anchor{dotident}
854 @defvr {Option variable} dotident
855 Default value: 1
857 @code{dotident} is the value returned by @code{X^^0}.
858 @c "RETURNED" ?? IS THIS A SIMPLIFICATION OR AN EVALUATION ??
860 @c NEED EXAMPLE HERE
861 @opencatbox{Categories:}
862 @category{Simplification flags and variables}
863 @closecatbox
864 @end defvr
866 @c -----------------------------------------------------------------------------
867 @anchor{dotscrules}
868 @defvr {Option variable} dotscrules
869 Default value: @code{false}
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
875 @c NEED EXAMPLE HERE
876 @opencatbox{Categories:}
877 @category{Simplification flags and variables}
878 @closecatbox
879 @end defvr
881 @c -----------------------------------------------------------------------------
882 @anchor{echelon}
883 @deffn {Function} echelon (@var{M})
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.
892 @mref{triangularize} also carries out Gaussian elimination, but it does not
893 normalize the leading non-zero element in each row.
895 @mref{lu_factor} and @mref{cholesky} are other functions which yield
896 triangularized matrices.
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
925 @opencatbox{Categories:}
926 @category{Linear equations}
927 @category{Matrices}
928 @closecatbox
929 @end deffn
931 @c -----------------------------------------------------------------------------
932 @anchor{eigenvalues}
933 @anchor{eivals}
934 @deffn {Function} eigenvalues (@var{M})
935 @deffnx {Function} eivals (@var{M})
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.
944 @code{eivals} is a synonym for @code{eigenvalues}.
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.
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 ??
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
972 For matrices consisting of only floating-point values, see also
973 @mrefdot{dgeev}
975 @c NEED EXAMPLES HERE
976 @opencatbox{Categories:}
977 @category{Package eigen}
978 @closecatbox
979 @end deffn
981 @c -----------------------------------------------------------------------------
982 @anchor{eigenvectors}
983 @anchor{eivects}
984 @deffn {Function} eigenvectors (@var{M})
985 @deffnx {Function} eivects (@var{M})
987 Computes eigenvectors of the matrix @var{M}.
988 The return value is a list of two elements.
989 The first is a list of the eigenvalues of @var{M}
990 and a list of the multiplicities of the eigenvalues.
991 The second is a list of lists of eigenvectors.
992 There is one list of eigenvectors for each eigenvalue.
993 There may be one or more eigenvectors in each list.
995 @code{eivects} is a synonym for @code{eigenvectors}.
997 The package @code{eigen.mac} is loaded automatically when
998 @mref{eigenvalues} or @code{eigenvectors} is referenced.
999 If @code{eigen.mac} is not already loaded,
1000 @code{load ("eigen")} loads it.
1001 After loading, all functions and variables in the package are available.
1003 Note that @code{eigenvectors} internally calls @code{eigenvalues} to
1004 obtain eigenvalues. So, when @code{eigenvalues} returns a subset of
1005 all the eigenvalues, the @code{eigenvectors} returns the corresponding
1006 subset of the all the eigenvectors, with the same warning displayed as
1007 @code{eigenvalues}.
1009 The flags that affect this function are:
1011 @code{nondiagonalizable} is set to @code{true} or @code{false} depending on
1012 whether the matrix is nondiagonalizable or diagonalizable after
1013 @code{eigenvectors} returns.
1015 @code{hermitianmatrix} when @code{true}, causes the degenerate
1016 eigenvectors of the Hermitian matrix to be orthogonalized using the
1017 Gram-Schmidt algorithm.
1019 @code{knowneigvals} when @code{true} causes the @code{eigen} package to assume
1020 the eigenvalues of the matrix are known to the user and stored under the global
1021 name @code{listeigvals}. @code{listeigvals} should be set to a list similar
1022 to the output @code{eigenvalues}.
1024 The function @mref{algsys} is used here to solve for the eigenvectors.
1025 Sometimes if the eigenvalues are messy, @code{algsys} may not be able to find a
1026 solution. In some cases, it may be possible to simplify the eigenvalues by
1027 first finding them using @code{eigenvalues} command and then using other
1028 functions to reduce them to something simpler. Following simplification,
1029 @code{eigenvectors} can be called again with the @code{knowneigvals} flag set
1030 to @code{true}.
1032 See also @mrefdot{eigenvalues}
1034 For matrices consisting of only floating-point values, see also
1035 @mrefdot{dgeev}
1037 Examples:
1039 A matrix which has just one eigenvector per eigenvalue.
1041 @c ===beg===
1042 @c M1: matrix ([11, -1], [1, 7]);
1043 @c [vals, vecs] : eigenvectors (M1);
1044 @c for i thru length (vals[1]) do disp (val[i] = vals[1][i],
1045 @c mult[i] = vals[2][i], vec[i] = vecs[i]);
1046 @c ===end===
1047 @example
1048 @group
1049 (%i1) M1: matrix ([11, -1], [1, 7]);
1050 [ 11 - 1 ]
1051 (%o1) [ ]
1052 [ 1 7 ]
1053 @end group
1054 @group
1055 (%i2) [vals, vecs] : eigenvectors (M1);
1056 (%o2) [[[9 - sqrt(3), sqrt(3) + 9], [1, 1]],
1057 [[[1, sqrt(3) + 2]], [[1, 2 - sqrt(3)]]]]
1058 @end group
1059 @group
1060 (%i3) for i thru length (vals[1]) do disp (val[i] = vals[1][i],
1061 mult[i] = vals[2][i], vec[i] = vecs[i]);
1062 val = 9 - sqrt(3)
1063 1
1065 mult = 1
1066 1
1068 vec = [[1, sqrt(3) + 2]]
1069 1
1071 val = sqrt(3) + 9
1072 2
1074 mult = 1
1075 2
1077 vec = [[1, 2 - sqrt(3)]]
1078 2
1080 (%o3) done
1081 @end group
1082 @end example
1084 A matrix which has two eigenvectors for one eigenvalue (namely 2).
1086 @c ===beg===
1087 @c M1 : matrix ([0, 1, 0, 0], [0, 0, 0, 0], [0, 0, 2, 0], [0, 0, 0, 2]);
1088 @c [vals, vecs] : eigenvectors (M1);
1089 @c for i thru length (vals[1]) do disp (val[i] = vals[1][i],
1090 @c mult[i] = vals[2][i], vec[i] = vecs[i]);
1091 @c ===end===
1092 @example
1093 @group
1094 (%i1) M1: matrix ([0, 1, 0, 0], [0, 0, 0, 0], [0, 0, 2, 0],
1095 [0, 0, 0, 2]);
1096 [ 0 1 0 0 ]
1097 [ ]
1098 [ 0 0 0 0 ]
1099 (%o1) [ ]
1100 [ 0 0 2 0 ]
1101 [ ]
1102 [ 0 0 0 2 ]
1103 @end group
1104 @group
1105 (%i2) [vals, vecs]: eigenvectors (M1);
1106 (%o2) [[[0, 2], [2, 2]], [[[1, 0, 0, 0]],
1107 [[0, 0, 1, 0], [0, 0, 0, 1]]]]
1108 @end group
1109 @group
1110 (%i3) for i thru length (vals[1]) do disp (val[i] = vals[1][i],
1111 mult[i] = vals[2][i], vec[i] = vecs[i]);
1112 val = 0
1113 1
1115 mult = 2
1116 1
1118 vec = [[1, 0, 0, 0]]
1119 1
1121 val = 2
1122 2
1124 mult = 2
1125 2
1127 vec = [[0, 0, 1, 0], [0, 0, 0, 1]]
1128 2
1130 (%o3) done
1131 @end group
1132 @end example
1134 @opencatbox{Categories:}
1135 @category{Package eigen}
1136 @closecatbox
1137 @end deffn
1139 @c -----------------------------------------------------------------------------
1140 @anchor{ematrix}
1141 @deffn {Function} ematrix (@var{m}, @var{n}, @var{x}, @var{i}, @var{j})
1143 Returns an @var{m} by @var{n} matrix, all elements of which
1144 are zero except for the @code{[@var{i}, @var{j}]} element which is @var{x}.
1145 @c WOW, THAT SEEMS PRETTY SPECIALIZED ...
1147 @opencatbox{Categories:}
1148 @category{Matrices}
1149 @closecatbox
1150 @end deffn
1152 @c -----------------------------------------------------------------------------
1153 @anchor{entermatrix}
1154 @deffn {Function} entermatrix (@var{m}, @var{n})
1156 Returns an @var{m} by @var{n} matrix, reading the elements interactively.
1158 If @var{n} is equal to @var{m}, Maxima prompts for the type of the matrix
1159 (diagonal, symmetric, antisymmetric, or general) and for each element.
1160 Each response is terminated by a semicolon @code{;} or dollar sign @code{$}.
1162 If @var{n} is not equal to @var{m},
1163 Maxima prompts for each element.
1165 The elements may be any expressions, which are evaluated.
1166 @code{entermatrix} evaluates its arguments.
1168 @example
1169 (%i1) n: 3$
1170 (%i2) m: entermatrix (n, n)$
1172 Is the matrix 1. Diagonal 2. Symmetric 3. Antisymmetric
1173 4. General
1174 Answer 1, 2, 3 or 4 :
1175 1$
1176 Row 1 Column 1:
1177 (a+b)^n$
1178 Row 2 Column 2:
1179 (a+b)^(n+1)$
1180 Row 3 Column 3:
1181 (a+b)^(n+2)$
1183 Matrix entered.
1184 (%i3) m;
1185 [ 3 ]
1186 [ (b + a) 0 0 ]
1187 [ ]
1188 (%o3) [ 4 ]
1189 [ 0 (b + a) 0 ]
1190 [ ]
1191 [ 5 ]
1192 [ 0 0 (b + a) ]
1193 @end example
1195 @opencatbox{Categories:}
1196 @category{Console interaction}
1197 @category{Matrices}
1198 @closecatbox
1199 @end deffn
1201 @c -----------------------------------------------------------------------------
1202 @anchor{genmatrix}
1203 @deffn {Function} genmatrix @
1204 @fname{genmatrix} (@var{a}, @var{i_2}, @var{j_2}, @var{i_1}, @var{j_1}) @
1205 @fname{genmatrix} (@var{a}, @var{i_2}, @var{j_2}, @var{i_1}) @
1206 @fname{genmatrix} (@var{a}, @var{i_2}, @var{j_2})
1208 Returns a matrix generated from @var{a}, taking element
1209 @code{@var{a}[@var{i_1}, @var{j_1}]} as the upper-left element and
1210 @code{@var{a}[@var{i_2}, @var{j_2}]} as the lower-right element of the matrix.
1211 Here @var{a} is a declared array (created by @code{array} but not by
1212 @mref{make_array}) or a @mrefcomma{hashed array} or a @mrefcomma{memoizing function} or a lambda
1213 expression of two arguments. (A @mref{memoizing function} is created like other functions
1214 with @mref{:=} or @mrefcomma{define} but arguments are enclosed in square
1215 brackets instead of parentheses.)
1217 If @var{j_1} is omitted, it is assumed equal to @var{i_1}.
1218 If both @var{j_1} and @var{i_1} are omitted, both are assumed equal to 1.
1220 If a selected element @code{i,j} of the array is undefined,
1221 the matrix will contain a symbolic element @code{@var{a}[i,j]}.
1223 Examples:
1225 @c ===beg===
1226 @c h [i, j] := 1 / (i + j - 1);
1227 @c genmatrix (h, 3, 3);
1228 @c array (a, fixnum, 2, 2);
1229 @c a [1, 1] : %e;
1230 @c a [2, 2] : %pi;
1231 @c genmatrix (a, 2, 2);
1232 @c genmatrix (lambda ([i, j], j - i), 3, 3);
1233 @c genmatrix (B, 2, 2);
1234 @c ===end===
1235 @example
1236 @group
1237 (%i1) h [i, j] := 1 / (i + j - 1);
1238 1
1239 (%o1) h := ---------
1240 i, j i + j - 1
1241 @end group
1242 @group
1243 (%i2) genmatrix (h, 3, 3);
1244 [ 1 1 ]
1245 [ 1 - - ]
1246 [ 2 3 ]
1247 [ ]
1248 [ 1 1 1 ]
1249 (%o2) [ - - - ]
1250 [ 2 3 4 ]
1251 [ ]
1252 [ 1 1 1 ]
1253 [ - - - ]
1254 [ 3 4 5 ]
1255 @end group
1256 @group
1257 (%i3) array (a, fixnum, 2, 2);
1258 (%o3) a
1259 @end group
1260 @group
1261 (%i4) a [1, 1] : %e;
1262 (%o4) %e
1263 @end group
1264 @group
1265 (%i5) a [2, 2] : %pi;
1266 (%o5) %pi
1267 @end group
1268 @group
1269 (%i6) genmatrix (a, 2, 2);
1270 [ %e 0 ]
1271 (%o6) [ ]
1272 [ 0 %pi ]
1273 @end group
1274 @group
1275 (%i7) genmatrix (lambda ([i, j], j - i), 3, 3);
1276 [ 0 1 2 ]
1277 [ ]
1278 (%o7) [ - 1 0 1 ]
1279 [ ]
1280 [ - 2 - 1 0 ]
1281 @end group
1282 @group
1283 (%i8) genmatrix (B, 2, 2);
1284 [ B B ]
1285 [ 1, 1 1, 2 ]
1286 (%o8) [ ]
1287 [ B B ]
1288 [ 2, 1 2, 2 ]
1289 @end group
1290 @end example
1292 @opencatbox{Categories:}
1293 @category{Matrices}
1294 @closecatbox
1295 @end deffn
1297 @c -----------------------------------------------------------------------------
1298 @anchor{gramschmidt}
1299 @deffn {Function} gramschmidt @
1300 @fname{gramschmidt} (@var{x}) @
1301 @fname{gramschmidt} (@var{x}, @var{F})
1303 Carries out the Gram-Schmidt orthogonalization algorithm on @var{x}, which is
1304 either a matrix or a list of lists. @var{x} is not modified by
1305 @code{gramschmidt}. The inner product employed by @code{gramschmidt} is
1306 @var{F}, if present, otherwise the inner product is the function
1307 @mrefdot{innerproduct}
1309 If @var{x} is a matrix, the algorithm is applied to the rows of @var{x}. If
1310 @var{x} is a list of lists, the algorithm is applied to the sublists, which must
1311 have equal numbers of elements. In either case, the return value is a list of
1312 lists, the sublists of which are orthogonal and span the same space as @var{x}.
1313 If the dimension of the span of @var{x} is less than the number of rows or
1314 sublists, some sublists of the return value are zero.
1316 @mref{factor} is called at each stage of the algorithm to simplify intermediate
1317 results. As a consequence, the return value may contain factored integers.
1319 @code{load("eigen")} loads this function.
1321 Example:
1323 Gram-Schmidt algorithm using default inner product function.
1325 @c ===beg===
1326 @c load ("eigen")$
1327 @c x: matrix ([1, 2, 3], [9, 18, 30], [12, 48, 60]);
1328 @c y: gramschmidt (x);
1329 @c map (innerproduct, [y[1], y[2], y[3]], [y[2], y[3], y[1]]);
1330 @c ===end===
1331 @example
1332 (%i1) load ("eigen")$
1333 @group
1334 (%i2) x: matrix ([1, 2, 3], [9, 18, 30], [12, 48, 60]);
1335 [ 1 2 3 ]
1336 [ ]
1337 (%o2) [ 9 18 30 ]
1338 [ ]
1339 [ 12 48 60 ]
1340 @end group
1341 @group
1342 (%i3) y: gramschmidt (x);
1343 2 2 4 3
1344 3 3 3 5 2 3 2 3
1345 (%o3) [[1, 2, 3], [- ---, - --, ---], [- ----, ----, 0]]
1346 2 7 7 2 7 5 5
1347 @end group
1348 @group
1349 (%i4) map (innerproduct, [y[1], y[2], y[3]], [y[2], y[3], y[1]]);
1350 (%o4) [0, 0, 0]
1351 @end group
1352 @end example
1354 Gram-Schmidt algorithm using a specified inner product function.
1356 @c ===beg===
1357 @c load ("eigen")$
1358 @c ip (f, g) := integrate (f * g, u, a, b);
1359 @c y: gramschmidt ([1, sin(u), cos(u)], ip), a=-%pi/2, b=%pi/2;
1360 @c map (ip, [y[1], y[2], y[3]], [y[2], y[3], y[1]]), a=-%pi/2,
1361 @c b=%pi/2;
1362 @c ===end===
1363 @example
1364 (%i1) load ("eigen")$
1365 @group
1366 (%i2) ip (f, g) := integrate (f * g, u, a, b);
1367 (%o2) ip(f, g) := integrate(f g, u, a, b)
1368 @end group
1369 @group
1370 (%i3) y: gramschmidt ([1, sin(u), cos(u)], ip), a=-%pi/2, b=%pi/2;
1371 %pi cos(u) - 2
1372 (%o3) [1, sin(u), --------------]
1373 %pi
1374 @end group
1375 @group
1376 (%i4) map (ip, [y[1], y[2], y[3]], [y[2], y[3], y[1]]), a=-%pi/2,
1377 b=%pi/2;
1378 (%o4) [0, 0, 0]
1379 @end group
1380 @end example
1382 @opencatbox{Categories:}
1383 @category{Package eigen}
1384 @closecatbox
1385 @end deffn
1387 @c -----------------------------------------------------------------------------
1388 @anchor{ident}
1389 @deffn {Function} ident (@var{n})
1391 Returns an @var{n} by @var{n} identity matrix.
1393 @opencatbox{Categories:}
1394 @category{Matrices}
1395 @closecatbox
1396 @end deffn
1398 @c -----------------------------------------------------------------------------
1399 @anchor{innerproduct}
1400 @anchor{inprod}
1401 @deffn {Function} innerproduct (@var{x}, @var{y})
1402 @deffnx {Function} inprod (@var{x}, @var{y})
1404 Returns the inner product (also called the scalar product or dot product) of
1405 @var{x} and @var{y}, which are lists of equal length, or both 1-column or 1-row
1406 matrices of equal length. The return value is @code{conjugate (x) . y},
1407 where @code{.} is the noncommutative multiplication operator.
1409 @code{load ("eigen")} loads this function.
1411 @code{inprod} is a synonym for @code{innerproduct}.
1413 @c NEED EXAMPLE HERE
1414 @opencatbox{Categories:}
1415 @category{Package eigen}
1416 @closecatbox
1417 @end deffn
1419 @c -----------------------------------------------------------------------------
1420 @anchor{invert_by_adjoint}
1421 @deffn {Function} invert_by_adjoint (@var{M})
1422 Returns the inverse of the matrix @var{M}.
1423 The inverse is computed by the adjoint method.
1425 @code{invert_by_adjoint} honors the @mref{ratmx} and @mref{detout} flags,
1426 the same as @mrefdot{invert}
1428 @end deffn
1430 @c -----------------------------------------------------------------------------
1431 @anchor{invert}
1432 @deffn {Function} invert (@var{M})
1434 Returns the inverse of the matrix @var{M}.
1435 The inverse is computed via the LU decomposition.
1437 When @mref{ratmx} is @code{true},
1438 elements of @var{M} are converted to canonical rational expressions (CRE),
1439 and the elements of the return value are also CRE.
1441 When @mref{ratmx} is @code{false},
1442 elements of @var{M} are not converted to a common representation.
1443 In particular, float and bigfloat elements are not converted to rationals.
1445 When @mref{detout} is @code{true}, the determinant is factored out of the inverse.
1446 The global flags @mref{doallmxops} and @mref{doscmxops} must be @code{false}
1447 to prevent the determinant from being absorbed into the inverse.
1448 @mref{xthru} can multiply the determinant into the inverse.
1450 @mref{invert} does not apply any simplifications to the elements of the inverse
1451 apart from the default arithmetic simplifications.
1452 @mref{ratsimp} and @mref{expand} can apply additional simplifications.
1453 In particular, when @var{M} has polynomial elements,
1454 @code{expand(invert(@var{M}))} might be preferable.
1456 @code{invert(@var{M})} is equivalent to @code{@var{M}^^-1}.
1458 @c NEED EXAMPLES HERE
1459 @opencatbox{Categories:}
1460 @category{Matrices}
1461 @closecatbox
1462 @end deffn
1464 @c -----------------------------------------------------------------------------
1465 @anchor{list_matrix_entries}
1466 @deffn {Function} list_matrix_entries (@var{M})
1468 Returns a list containing the elements of the matrix @var{M}.
1470 Example:
1472 @c ===beg===
1473 @c list_matrix_entries(matrix([a,b],[c,d]));
1474 @c ===end===
1475 @example
1476 @group
1477 (%i1) list_matrix_entries(matrix([a,b],[c,d]));
1478 (%o1) [a, b, c, d]
1479 @end group
1480 @end example
1482 @opencatbox{Categories:}
1483 @category{Matrices}
1484 @closecatbox
1485 @end deffn
1487 @c -----------------------------------------------------------------------------
1488 @anchor{lmxchar}
1489 @defvr {Option variable} lmxchar
1490 Default value: @code{[}
1492 @code{lmxchar} is the character displayed as the left delimiter of a matrix.
1493 See also @mrefdot{rmxchar}
1495 @code{lmxchar} is only used when @code{display2d_unicode} is @code{false}.
1497 Example:
1499 @example
1500 (%i1) display2d_unicode: false $
1501 (%i2) lmxchar: "|"$
1502 (%i3) matrix ([a, b, c], [d, e, f], [g, h, i]);
1503 | a b c ]
1504 | ]
1505 (%o3) | d e f ]
1506 | ]
1507 | g h i ]
1508 @end example
1510 @opencatbox{Categories:}
1511 @category{Display flags and variables}
1512 @category{Matrices}
1513 @closecatbox
1514 @end defvr
1516 @c -----------------------------------------------------------------------------
1517 @anchor{matrix}
1518 @deffn {Function} matrix (@var{row_1}, @dots{}, @var{row_n})
1520 Returns a rectangular matrix which has the rows @var{row_1}, @dots{},
1521 @var{row_n}. Each row is a list of expressions. All rows must be the same
1522 length.
1524 The operations @code{+} (addition), @code{-} (subtraction), @code{*}
1525 (multiplication), and @code{/} (division), are carried out element by element
1526 when the operands are two matrices, a scalar and a matrix, or a matrix and a
1527 scalar. The operation @code{^} (exponentiation, equivalently @code{**})
1528 is carried out element by element if the operands are a scalar and a matrix or
1529 a matrix and a scalar, but not if the operands are two matrices.
1530 @c WHAT DOES THIS NEXT PHRASE MEAN EXACTLY ??
1531 All operations are normally carried out in full,
1532 including @code{.} (noncommutative multiplication).
1534 Matrix multiplication is represented by the noncommutative multiplication
1535 operator @code{.}. The corresponding noncommutative exponentiation operator
1536 is @code{^^}. For a matrix @code{@var{A}}, @code{@var{A}.@var{A} = @var{A}^^2}
1537 and @code{@var{A}^^-1} is the inverse of @var{A}, if it exists.
1538 @code{@var{A}^^-1} is equivalent to @code{invert(@var{A})}.
1540 There are switches for controlling simplification of expressions involving dot
1541 and matrix-list operations. These are
1542 @mrefcomma{doallmxops} @mrefcomma{domxexpt} @mrefcomma{domxmxops}@w{}
1543 @mrefcomma{doscmxops} and @mrefdot{doscmxplus}
1544 @c CHECK -- WE PROBABLY WANT EXHAUSTIVE LIST HERE
1546 There are additional options which are related to matrices. These are:
1547 @mrefcomma{lmxchar} @mrefcomma{rmxchar} @mrefcomma{ratmx}@w{}
1548 @mrefcomma{listarith} @mrefcomma{detout} @code{scalarmatrix} and
1549 @mrefdot{sparse}
1550 @c CHECK -- WE PROBABLY WANT EXHAUSTIVE LIST HERE
1552 There are a number of functions which take matrices as arguments or yield
1553 matrices as return values.
1554 See @mrefcomma{eigenvalues} @mrefcomma{eigenvectors} @mrefcomma{determinant}@w{}
1555 @mrefcomma{charpoly} @mrefcomma{genmatrix} @mrefcomma{addcol}@w{}
1556 @mrefcomma{addrow} @mrefcomma{copymatrix} @mrefcomma{transpose}@w{}
1557 @mrefcomma{echelon} and @mrefdot{rank}
1558 @c CHECK -- WE PROBABLY WANT EXHAUSTIVE LIST HERE
1560 Examples:
1562 @itemize @bullet
1563 @item
1564 Construction of matrices from lists.
1565 @end itemize
1566 @example
1567 (%i1) x: matrix ([17, 3], [-8, 11]);
1568 [ 17 3 ]
1569 (%o1) [ ]
1570 [ - 8 11 ]
1571 (%i2) y: matrix ([%pi, %e], [a, b]);
1572 [ %pi %e ]
1573 (%o2) [ ]
1574 [ a b ]
1575 @end example
1576 @itemize @bullet
1577 @item
1578 Addition, element by element.
1579 @end itemize
1580 @example
1581 (%i3) x + y;
1582 [ %pi + 17 %e + 3 ]
1583 (%o3) [ ]
1584 [ a - 8 b + 11 ]
1585 @end example
1586 @itemize @bullet
1587 @item
1588 Subtraction, element by element.
1589 @end itemize
1590 @example
1591 (%i4) x - y;
1592 [ 17 - %pi 3 - %e ]
1593 (%o4) [ ]
1594 [ - a - 8 11 - b ]
1595 @end example
1596 @itemize @bullet
1597 @item
1598 Multiplication, element by element.
1599 @end itemize
1600 @example
1601 (%i5) x * y;
1602 [ 17 %pi 3 %e ]
1603 (%o5) [ ]
1604 [ - 8 a 11 b ]
1605 @end example
1606 @itemize @bullet
1607 @item
1608 Division, element by element.
1609 @end itemize
1610 @example
1611 (%i6) x / y;
1612 [ 17 - 1 ]
1613 [ --- 3 %e ]
1614 [ %pi ]
1615 (%o6) [ ]
1616 [ 8 11 ]
1617 [ - - -- ]
1618 [ a b ]
1619 @end example
1620 @itemize @bullet
1621 @item
1622 Matrix to a scalar exponent, element by element.
1623 @end itemize
1624 @example
1625 (%i7) x ^ 3;
1626 [ 4913 27 ]
1627 (%o7) [ ]
1628 [ - 512 1331 ]
1629 @end example
1630 @itemize @bullet
1631 @item
1632 Scalar base to a matrix exponent, element by element.
1633 @end itemize
1634 @example
1635 (%i8) exp(y);
1636 [ %pi %e ]
1637 [ %e %e ]
1638 (%o8) [ ]
1639 [ a b ]
1640 [ %e %e ]
1641 @end example
1642 @itemize @bullet
1643 @item
1644 Matrix base to a matrix exponent. This is not carried out element by element.
1645 See also @mrefdot{matrixexp}
1646 @c WHAT IS THIS ??
1647 @end itemize
1648 @example
1649 (%i9) x ^ y;
1650 [ %pi %e ]
1651 [ ]
1652 [ a b ]
1653 [ 17 3 ]
1654 (%o9) [ ]
1655 [ - 8 11 ]
1656 @end example
1657 @itemize @bullet
1658 @item
1659 Noncommutative matrix multiplication.
1660 @end itemize
1661 @example
1662 (%i10) x . y;
1663 [ 3 a + 17 %pi 3 b + 17 %e ]
1664 (%o10) [ ]
1665 [ 11 a - 8 %pi 11 b - 8 %e ]
1666 (%i11) y . x;
1667 [ 17 %pi - 8 %e 3 %pi + 11 %e ]
1668 (%o11) [ ]
1669 [ 17 a - 8 b 11 b + 3 a ]
1670 @end example
1671 @itemize @bullet
1672 @item
1673 Noncommutative matrix exponentiation.
1674 A scalar base @var{b} to a matrix power @var{M}
1675 is carried out element by element and so @code{b^^m} is the same as @code{b^m}.
1676 @end itemize
1677 @example
1678 (%i12) x ^^ 3;
1679 [ 3833 1719 ]
1680 (%o12) [ ]
1681 [ - 4584 395 ]
1682 (%i13) %e ^^ y;
1683 @group
1684 [ %pi %e ]
1685 [ %e %e ]
1686 (%o13) [ ]
1687 [ a b ]
1688 [ %e %e ]
1689 @end group
1690 @end example
1691 @itemize @bullet
1692 @item
1693 A matrix raised to a -1 exponent with noncommutative exponentiation is the
1694 matrix inverse, if it exists.
1695 @end itemize
1696 @example
1697 (%i14) x ^^ -1;
1698 [ 11 3 ]
1699 [ --- - --- ]
1700 [ 211 211 ]
1701 (%o14) [ ]
1702 [ 8 17 ]
1703 [ --- --- ]
1704 [ 211 211 ]
1705 (%i15) x . (x ^^ -1);
1706 [ 1 0 ]
1707 (%o15) [ ]
1708 [ 0 1 ]
1709 @end example
1711 @opencatbox{Categories:}
1712 @category{Matrices}
1713 @closecatbox
1714 @end deffn
1716 @c -----------------------------------------------------------------------------
1717 @anchor{matrixexp}
1718 @deffn {Function} matrixexp @
1719 @fname{matrixexp} (@var{M}) @
1720 @fname{matrixexp} (@var{M}, @var{n}) @
1721 @fname{matrixexp} (@var{M}, @var{V})
1723 Calculates the matrix exponential
1724 m4_math(
1725 <<<e^{M\cdot V}>>>,
1726 <<<e^(M*V)>>>,
1727 <<<e^{MV}>>>)
1728 @c @ifnotinfo
1729 @c @tex
1730 @c @math{e^{MV}}
1731 @c @end tex
1732 @c @ifset mathjax
1733 @c @html
1734 @c $$e^{M\cdot V}$$
1735 @c @end html
1736 @c @end ifset
1737 @c @ifclear mathjax
1738 @c @math{e^(M*V)}
1739 @c @end ifclear
1740 @c @end ifnotinfo
1741 @c @ifinfo
1742 @c @math{e^(M*V)}
1743 @c @end ifinfo
1744 . Instead of the vector @var{V} a number @var{n} can be specified as the second
1745 argument. If this argument is omitted @code{matrixexp} replaces it by @code{1}.
1747 The matrix exponential of a matrix @var{M} can be expressed as a power series:
1748 m4_displaymath(
1749 <<<e^M=\sum_{k=0}^\infty{\left(\frac{M^k}{k!}\right)}>>>,
1750 <<<@math{e^M=sum(M^k/k!,0,inf)}>>>
1751 )
1752 @c @ifnotinfo
1753 @c @tex
1754 @c @math{e^M=\sum_{k=0}^\infty{{M^k}\over{k!}}}
1755 @c @end tex
1756 @c @ifset mathjax
1757 @c @html
1758 @c $$e^M=\sum_{k=0}^\infty{\left(\frac{M^k}{k!}\right)}$$
1759 @c @end html
1760 @c @end ifset
1761 @c @ifclear mathjax
1762 @c @math{e^M=sum(M^k/k!,0,inf)}
1763 @c @end ifclear
1764 @c @end ifnotinfo
1765 @c @ifinfo
1766 @c @math{e^M=sum(M^k/k!,0,inf)}
1767 @c @end ifinfo
1768 @c
1769 @c NEED EXAMPLE HERE
1770 @opencatbox{Categories:}
1771 @category{Matrices}
1772 @closecatbox
1773 @end deffn
1776 @c -----------------------------------------------------------------------------
1777 @anchor{matrixmap}
1778 @deffn {Function} matrixmap (@var{f}, @var{M})
1780 Returns a matrix with element @code{i,j} equal to @code{@var{f}(@var{M}[i,j])}.
1782 See also @mrefcomma{map} @mrefcomma{fullmap} @mrefcomma{fullmapl} and
1783 @mrefdot{apply}
1785 @c NEED EXAMPLE HERE
1786 @opencatbox{Categories:}
1787 @category{Matrices}
1788 @closecatbox
1789 @end deffn
1791 @c -----------------------------------------------------------------------------
1792 @anchor{matrixp}
1793 @deffn {Function} matrixp (@var{expr})
1795 Returns @code{true} if @var{expr} is a matrix, otherwise @code{false}.
1797 @opencatbox{Categories:}
1798 @category{Predicate functions}
1799 @category{Matrices}
1800 @closecatbox
1801 @end deffn
1803 @c -----------------------------------------------------------------------------
1804 @anchor{matrix_element_add}
1805 @defvr {Option variable} matrix_element_add
1806 Default value: @code{+}
1808 @code{matrix_element_add} is the operation
1809 invoked in place of addition in a matrix multiplication.
1810 @code{matrix_element_add} can be assigned any n-ary operator
1811 (that is, a function which handles any number of arguments).
1812 The assigned value may be the name of an operator enclosed in quote marks,
1813 the name of a function,
1814 or a lambda expression.
1816 See also @mref{matrix_element_mult} and @mrefdot{matrix_element_transpose}
1818 Example:
1820 @example
1821 (%i1) matrix_element_add: "*"$
1822 (%i2) matrix_element_mult: "^"$
1823 (%i3) aa: matrix ([a, b, c], [d, e, f]);
1824 [ a b c ]
1825 (%o3) [ ]
1826 [ d e f ]
1827 (%i4) bb: matrix ([u, v, w], [x, y, z]);
1828 @group
1829 [ u v w ]
1830 (%o4) [ ]
1831 [ x y z ]
1832 @end group
1833 (%i5) aa . transpose (bb);
1834 [ u v w x y z ]
1835 [ a b c a b c ]
1836 (%o5) [ ]
1837 [ u v w x y z ]
1838 [ d e f d e f ]
1839 @end example
1841 @opencatbox{Categories:}
1842 @category{Matrices}
1843 @closecatbox
1844 @end defvr
1846 @c -----------------------------------------------------------------------------
1847 @anchor{matrix_element_mult}
1848 @defvr {Option variable} matrix_element_mult
1849 Default value: @code{*}
1851 @code{matrix_element_mult} is the operation
1852 invoked in place of multiplication in a matrix multiplication.
1853 @code{matrix_element_mult} can be assigned any binary operator.
1854 The assigned value may be the name of an operator enclosed in quote marks,
1855 the name of a function,
1856 or a lambda expression.
1858 The dot operator @code{.} is a useful choice in some contexts.
1860 See also @mref{matrix_element_add} and @mrefdot{matrix_element_transpose}
1862 Example:
1864 @example
1865 (%i1) matrix_element_add: lambda ([[x]], sqrt (apply ("+", x)))$
1866 (%i2) matrix_element_mult: lambda ([x, y], (x - y)^2)$
1867 (%i3) [a, b, c] . [x, y, z];
1868 2 2 2
1869 (%o3) sqrt((c - z) + (b - y) + (a - x) )
1870 (%i4) aa: matrix ([a, b, c], [d, e, f]);
1871 [ a b c ]
1872 (%o4) [ ]
1873 [ d e f ]
1874 (%i5) bb: matrix ([u, v, w], [x, y, z]);
1875 [ u v w ]
1876 (%o5) [ ]
1877 [ x y z ]
1878 (%i6) aa . transpose (bb);
1879 [ 2 2 2 ]
1880 [ sqrt((c - w) + (b - v) + (a - u) ) ]
1881 (%o6) Col 1 = [ ]
1882 [ 2 2 2 ]
1883 [ sqrt((f - w) + (e - v) + (d - u) ) ]
1885 [ 2 2 2 ]
1886 [ sqrt((c - z) + (b - y) + (a - x) ) ]
1887 Col 2 = [ ]
1888 [ 2 2 2 ]
1889 [ sqrt((f - z) + (e - y) + (d - x) ) ]
1890 @end example
1892 @opencatbox{Categories:}
1893 @category{Matrices}
1894 @closecatbox
1895 @end defvr
1897 @c -----------------------------------------------------------------------------
1898 @anchor{matrix_element_transpose}
1899 @defvr {Option variable} matrix_element_transpose
1900 Default value: @code{false}
1902 @code{matrix_element_transpose} is the operation
1903 applied to each element of a matrix when it is transposed.
1904 @mref{matrix_element_mult} can be assigned any unary operator.
1905 The assigned value may be the name of an operator enclosed in quote marks,
1906 the name of a function, or a lambda expression.
1908 When @code{matrix_element_transpose} equals @mrefcomma{transpose}
1909 the @code{transpose} function is applied to every element.
1910 When @code{matrix_element_transpose} equals @code{nonscalars},
1911 the @code{transpose} function is applied to every nonscalar element.
1912 If some element is an atom, the @code{nonscalars} option applies
1913 @code{transpose} only if the atom is declared nonscalar,
1914 while the @code{transpose} option always applies @code{transpose}.
1916 The default value, @code{false}, means no operation is applied.
1918 See also @mref{matrix_element_add} and @mrefdot{matrix_element_mult}
1920 Examples:
1922 @example
1923 (%i1) declare (a, nonscalar)$
1924 (%i2) transpose ([a, b]);
1925 [ transpose(a) ]
1926 (%o2) [ ]
1927 [ b ]
1928 (%i3) matrix_element_transpose: nonscalars$
1929 (%i4) transpose ([a, b]);
1930 [ transpose(a) ]
1931 (%o4) [ ]
1932 [ b ]
1933 (%i5) matrix_element_transpose: transpose$
1934 (%i6) transpose ([a, b]);
1935 [ transpose(a) ]
1936 (%o6) [ ]
1937 [ transpose(b) ]
1938 (%i7) matrix_element_transpose: lambda ([x], realpart(x)
1939 - %i*imagpart(x))$
1940 (%i8) m: matrix ([1 + 5*%i, 3 - 2*%i], [7*%i, 11]);
1941 [ 5 %i + 1 3 - 2 %i ]
1942 (%o8) [ ]
1943 [ 7 %i 11 ]
1944 (%i9) transpose (m);
1945 [ 1 - 5 %i - 7 %i ]
1946 (%o9) [ ]
1947 [ 2 %i + 3 11 ]
1948 @end example
1950 @opencatbox{Categories:}
1951 @category{Matrices}
1952 @closecatbox
1953 @end defvr
1955 @c IS THIS THE ONLY MATRIX TRACE FUNCTION ??
1957 @c -----------------------------------------------------------------------------
1958 @anchor{mattrace}
1959 @deffn {Function} mattrace (@var{M})
1961 Returns the trace (that is, the sum of the elements on the main diagonal) of
1962 the square matrix @var{M}.
1964 @code{mattrace} is called by @mrefcomma{ncharpoly} an alternative to Maxima's
1965 @mrefdot{charpoly}
1966 @c UMM, HOW IS THAT RELEVANT HERE ??
1968 @code{load ("nchrpl")} loads this function.
1970 @opencatbox{Categories:}
1971 @category{Matrices}
1972 @category{Package nchrpl}
1973 @closecatbox
1974 @end deffn
1976 @c -----------------------------------------------------------------------------
1977 @anchor{minor}
1978 @deffn {Function} minor (@var{M}, @var{i}, @var{j})
1980 Returns the @var{i}, @var{j} minor of the matrix @var{M}. That is, @var{M}
1981 with row @var{i} and column @var{j} removed.
1983 @opencatbox{Categories:}
1984 @category{Matrices}
1985 @closecatbox
1986 @end deffn
1988 @c -----------------------------------------------------------------------------
1989 @anchor{ncharpoly}
1990 @deffn {Function} ncharpoly (@var{M}, @var{x})
1992 Returns the characteristic polynomial of the matrix @var{M}
1993 with respect to @var{x}. This is an alternative to Maxima's @mrefdot{charpoly}
1995 @code{ncharpoly} works by computing traces of powers of the given matrix,
1996 which are known to be equal to sums of powers of the roots of the
1997 characteristic polynomial. From these quantities the symmetric
1998 functions of the roots can be calculated, which are nothing more than
1999 the coefficients of the characteristic polynomial. @code{charpoly} works by
2000 @c SHOULD THAT BE "m" INSTEAD OF "a" IN THE NEXT LINE ??
2001 forming the determinant of @code{@var{x} * ident [n] - a}. Thus
2002 @code{ncharpoly} wins, for example, in the case of large dense matrices filled
2003 with integers, since it avoids polynomial arithmetic altogether.
2005 @code{load ("nchrpl")} loads this file.
2007 @opencatbox{Categories:}
2008 @category{Matrices}
2009 @category{Package nchrpl}
2010 @closecatbox
2011 @end deffn
2013 @c -----------------------------------------------------------------------------
2014 @anchor{newdet}
2015 @deffn {Function} newdet (@var{M})
2017 Computes the determinant of the matrix @var{M} by the Johnson-Gentleman tree
2018 minor algorithm. @code{newdet} returns the result in CRE form.
2020 @opencatbox{Categories:}
2021 @category{Matrices}
2022 @closecatbox
2023 @end deffn
2025 @c -----------------------------------------------------------------------------
2026 @anchor{permanent}
2027 @deffn {Function} permanent (@var{M})
2029 Computes the permanent of the matrix @var{M} by the Johnson-Gentleman tree
2030 minor algorithm. A permanent is like a determinant but with no sign changes.
2031 @code{permanent} returns the result in CRE form.
2033 See also @code{newdet}.
2035 @opencatbox{Categories:}
2036 @category{Matrices}
2037 @closecatbox
2038 @end deffn
2040 @c -----------------------------------------------------------------------------
2041 @anchor{rank}
2042 @deffn {Function} rank (@var{M})
2044 Computes the rank of the matrix @var{M}. That is, the order of the
2045 largest non-singular subdeterminant of @var{M}.
2047 @c STATEMENT NEEDS CLARIFICATION
2048 @var{rank} may return the
2049 wrong answer if it cannot determine that a matrix element that is
2050 equivalent to zero is indeed so.
2052 @opencatbox{Categories:}
2053 @category{Matrices}
2054 @closecatbox
2055 @end deffn
2057 @c -----------------------------------------------------------------------------
2058 @anchor{ratmx}
2059 @defvr {Option variable} ratmx
2060 Default value: @code{false}
2062 When @code{ratmx} is @code{false}, determinant and matrix
2063 addition, subtraction, and multiplication are performed in the
2064 representation of the matrix elements and cause the result of
2065 matrix inversion to be left in general representation.
2067 When @code{ratmx} is @code{true},
2068 the 4 operations mentioned above are performed in CRE form and the
2069 result of matrix inverse is in CRE form. Note that this may
2070 cause the elements to be expanded (depending on the setting of @mref{ratfac})
2071 which might not always be desired.
2073 @opencatbox{Categories:}
2074 @category{Matrices}
2075 @category{Rational expressions}
2076 @closecatbox
2077 @end defvr
2079 @c -----------------------------------------------------------------------------
2080 @anchor{row}
2081 @deffn {Function} row (@var{M}, @var{i})
2083 Returns the @var{i}'th row of the matrix @var{M}.
2084 The return value is a matrix.
2086 The matrix returned by @code{row} shares memory with the argument @var{M};
2087 a modification to the return value modifies @var{M}.
2089 Examples:
2091 @code{row} returns the @var{i}'th row of the matrix @var{M}.
2093 @c ===beg===
2094 @c abc: matrix ([12, 14, -4], [2, x, b], [3*y, -7, 9]);
2095 @c row (abc, 1);
2096 @c row (abc, 2);
2097 @c row (abc, 3);
2098 @c ===end===
2099 @example
2100 @group
2101 (%i1) abc: matrix ([12, 14, -4], [2, x, b], [3*y, -7, 9]);
2102 [ 12 14 - 4 ]
2103 [ ]
2104 (%o1) [ 2 x b ]
2105 [ ]
2106 [ 3 y - 7 9 ]
2107 @end group
2108 @group
2109 (%i2) row (abc, 1);
2110 (%o2) [ 12 14 - 4 ]
2111 @end group
2112 @group
2113 (%i3) row (abc, 2);
2114 (%o3) [ 2 x b ]
2115 @end group
2116 @group
2117 (%i4) row (abc, 3);
2118 (%o4) [ 3 y - 7 9 ]
2119 @end group
2120 @end example
2122 The matrix returned by @code{row} shares memory with the argument.
2123 In this example,
2124 assigning a new value to @code{aa2} also modifies @code{aa}.
2126 @c ===beg===
2127 @c aa: matrix ([1, 2, x], [7, y, 3]);
2128 @c aa2: row (aa, 2);
2129 @c aa2[1, 3]: 123;
2130 @c aa2;
2131 @c aa;
2132 @c ===end===
2133 @example
2134 @group
2135 (%i1) aa: matrix ([1, 2, x], [7, y, 3]);
2136 [ 1 2 x ]
2137 (%o1) [ ]
2138 [ 7 y 3 ]
2139 @end group
2140 @group
2141 (%i2) aa2: row (aa, 2);
2142 (%o2) [ 7 y 3 ]
2143 @end group
2144 @group
2145 (%i3) aa2[1, 3]: 123;
2146 (%o3) 123
2147 @end group
2148 @group
2149 (%i4) aa2;
2150 (%o4) [ 7 y 123 ]
2151 @end group
2152 @group
2153 (%i5) aa;
2154 [ 1 2 x ]
2155 (%o5) [ ]
2156 [ 7 y 123 ]
2157 @end group
2158 @end example
2160 @opencatbox{Categories:}
2161 @category{Matrices}
2162 @closecatbox
2163 @end deffn
2165 @c -----------------------------------------------------------------------------
2166 @anchor{rmxchar}
2167 @defvr {Option variable} rmxchar
2168 Default value: @code{]}
2170 @code{rmxchar} is the character drawn on the right-hand side of a matrix.
2172 @code{rmxchar} is only used when @code{display2d_unicode} is @code{false}.
2174 See also @mrefdot{lmxchar}
2176 @opencatbox{Categories:}
2177 @category{Display flags and variables}
2178 @closecatbox
2179 @end defvr
2181 @c -----------------------------------------------------------------------------
2182 @anchor{scalarmatrixp}
2183 @defvr {Option variable} scalarmatrixp
2184 Default value: @code{true}
2186 When @code{scalarmatrixp} is @code{true}, then whenever a 1 x 1 matrix
2187 is produced as a result of computing the dot product of matrices it
2188 is simplified to a scalar, namely the sole element of the matrix.
2190 When @code{scalarmatrixp} is @code{all},
2191 then all 1 x 1 matrices are simplified to scalars.
2193 When @code{scalarmatrixp} is @code{false}, 1 x 1 matrices are not simplified
2194 to scalars.
2196 @opencatbox{Categories:}
2197 @category{Matrices}
2198 @category{Simplification flags and variables}
2199 @closecatbox
2200 @end defvr
2202 @c I WONDER WHAT THIS IS ABOUT
2204 @c -----------------------------------------------------------------------------
2205 @anchor{scalefactors}
2206 @deffn {Function} scalefactors (@var{coordinatetransform})
2208 Here the argument @var{coordinatetransform} evaluates to the form
2209 @code{[[expression1, expression2, ...], indeterminate1, indeterminat2, ...]},
2210 where the variables @var{indeterminate1}, @var{indeterminate2}, etc. are the
2211 curvilinear coordinate variables and where a set of rectangular Cartesian
2212 components is given in terms of the curvilinear coordinates by
2213 @code{[expression1, expression2, ...]}. @code{coordinates} is set to the vector
2214 @code{[indeterminate1, indeterminate2,...]}, and @code{dimension} is set to the
2215 length of this vector. SF[1], SF[2], @dots{}, SF[DIMENSION] are set to the
2216 coordinate scale factors, and @code{sfprod} is set to the product of these scale
2217 factors. Initially, @code{coordinates} is @code{[X, Y, Z]}, @code{dimension}
2218 is 3, and SF[1]=SF[2]=SF[3]=SFPROD=1, corresponding to 3-dimensional rectangular
2219 Cartesian coordinates. To expand an expression into physical components in the
2220 current coordinate system, there is a function with usage of the form
2221 @c SOME TEXT HAS GONE MISSING HERE
2223 @opencatbox{Categories:}
2224 @category{Package vect}
2225 @closecatbox
2226 @end deffn
2228 @c -----------------------------------------------------------------------------
2229 @anchor{setelmx}
2230 @deffn {Function} setelmx (@var{x}, @var{i}, @var{j}, @var{M})
2232 Assigns @var{x} to the (@var{i}, @var{j})'th element of the matrix @var{M},
2233 and returns the altered matrix.
2235 @code{@var{M} [@var{i}, @var{j}]: @var{x}} has the same effect,
2236 but returns @var{x} instead of @var{M}.
2238 @opencatbox{Categories:}
2239 @category{Matrices}
2240 @closecatbox
2241 @end deffn
2243 @c -----------------------------------------------------------------------------
2244 @anchor{similaritytransform}
2245 @anchor{simtran}
2246 @deffn {Function} similaritytransform (@var{M})
2247 @deffnx {Function} simtran (@var{M})
2249 @code{similaritytransform} computes a similarity transform of the matrix
2250 @code{M}. It returns a list which is the output of the @code{uniteigenvectors}
2251 command. In addition if the flag @code{nondiagonalizable} is @code{false} two
2252 global matrices @code{leftmatrix} and @code{rightmatrix} are computed. These
2253 matrices have the property that @code{leftmatrix . @var{M} . rightmatrix} is a
2254 diagonal matrix with the eigenvalues of @var{M} on the diagonal. If
2255 @code{nondiagonalizable} is @code{true} the left and right matrices are not
2256 computed.
2258 If the flag @code{hermitianmatrix} is @code{true} then @code{leftmatrix} is the
2259 complex conjugate of the transpose of @code{rightmatrix}. Otherwise
2260 @code{leftmatrix} is the inverse of @code{rightmatrix}.
2262 @code{rightmatrix} is the matrix the columns of which are the unit
2263 eigenvectors of @var{M}. The other flags (see @code{eigenvalues} and
2264 @code{eigenvectors}) have the same effects since
2265 @code{similaritytransform} calls the other functions in the package in order
2266 to be able to form @code{rightmatrix}.
2268 @code{load ("eigen")} loads this function.
2270 @code{simtran} is a synonym for @code{similaritytransform}.
2272 @opencatbox{Categories:}
2273 @category{Package eigen}
2274 @closecatbox
2275 @end deffn
2277 @c -----------------------------------------------------------------------------
2278 @anchor{sparse}
2279 @defvr {Option variable} sparse
2280 Default value: @code{false}
2282 When @code{sparse} is @code{true}, and if @code{ratmx} is @code{true}, then
2283 @code{determinant} will use special routines for computing sparse determinants.
2285 @opencatbox{Categories:}
2286 @category{Matrices}
2287 @closecatbox
2288 @end defvr
2290 @c -----------------------------------------------------------------------------
2291 @anchor{submatrix}
2292 @deffn {Function} submatrix @
2293 @fname{submatrix} (@var{i_1}, @dots{}, @var{i_m}, @var{M}, @var{j_1}, @dots{}, @var{j_n}) @
2294 @fname{submatrix} (@var{i_1}, @dots{}, @var{i_m}, @var{M}) @
2295 @fname{submatrix} (@var{M}, @var{j_1}, @dots{}, @var{j_n})
2297 Returns a new matrix composed of the matrix @var{M} with rows @var{i_1},
2298 @dots{}, @var{i_m} deleted, and columns @var{j_1}, @dots{}, @var{j_n} deleted.
2300 @opencatbox{Categories:}
2301 @category{Matrices}
2302 @closecatbox
2303 @end deffn
2305 @c -----------------------------------------------------------------------------
2306 @anchor{transpose}
2307 @deffn {Function} transpose (@var{M})
2309 Returns the transpose of @var{M}.
2311 If @var{M} is a matrix, the return value is another matrix @var{N}
2312 such that @code{N[i,j] = M[j,i]}.
2314 If @var{M} is a list, the return value is a matrix @var{N}
2315 of @code{length (m)} rows and 1 column, such that @code{N[i,1] = M[i]}.
2317 Otherwise @var{M} is a symbol,
2318 and the return value is a noun expression @code{'transpose (@var{M})}.
2320 @opencatbox{Categories:}
2321 @category{Matrices}
2322 @closecatbox
2323 @end deffn
2325 @c -----------------------------------------------------------------------------
2326 @anchor{triangularize}
2327 @deffn {Function} triangularize (@var{M})
2329 Returns the upper triangular form of the matrix @code{M},
2330 as produced by Gaussian elimination.
2331 The return value is the same as @code{echelon},
2332 except that the leading nonzero coefficient in each row is not normalized to 1.
2334 @code{lu_factor} and @code{cholesky} are other functions which yield
2335 triangularized matrices.
2337 @c ===beg===
2338 @c M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
2339 @c triangularize (M);
2340 @c ===end===
2341 @example
2342 @group
2343 (%i1) M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
2344 [ 3 7 aa bb ]
2345 [ ]
2346 (%o1) [ - 1 8 5 2 ]
2347 [ ]
2348 [ 9 2 11 4 ]
2349 @end group
2350 @group
2351 (%i2) triangularize (M);
2352 [ - 1 8 5 2 ]
2353 [ ]
2354 (%o2) [ 0 - 74 - 56 - 22 ]
2355 [ ]
2356 [ 0 0 626 - 74 aa 238 - 74 bb ]
2357 @end group
2358 @end example
2360 @opencatbox{Categories:}
2361 @category{Linear equations}
2362 @category{Matrices}
2363 @closecatbox
2364 @end deffn
2366 @c -----------------------------------------------------------------------------
2367 @anchor{uniteigenvectors}
2368 @anchor{ueivects}
2369 @deffn {Function} uniteigenvectors (@var{M})
2370 @deffnx {Function} ueivects (@var{M})
2372 Computes unit eigenvectors of the matrix @var{M}.
2373 The return value is a list of lists, the first sublist of which is the
2374 output of the @code{eigenvalues} command, and the other sublists of which are
2375 the unit eigenvectors of the matrix corresponding to those eigenvalues
2376 respectively.
2378 @c COPY DESCRIPTIONS OF THOSE FLAGS HERE
2379 The flags mentioned in the description of the
2380 @code{eigenvectors} command have the same effects in this one as well.
2382 When @code{knowneigvects} is @code{true}, the @code{eigen} package assumes
2383 that the eigenvectors of the matrix are known to the user and are
2384 stored under the global name @code{listeigvects}. @code{listeigvects} should
2385 be set to a list similar to the output of the @code{eigenvectors} command.
2387 @c FOLLOWING PARAGRAPH IS IN NEED OF SERIOUS CLARIFICATION
2388 If @code{knowneigvects} is set to @code{true} and the list of eigenvectors is
2389 given the setting of the flag @code{nondiagonalizable} may not be correct. If
2390 that is the case please set it to the correct value. The author assumes that
2391 the user knows what he is doing and will not try to diagonalize a matrix the
2392 eigenvectors of which do not span the vector space of the appropriate dimension.
2394 @code{load ("eigen")} loads this function.
2396 @code{ueivects} is a synonym for @code{uniteigenvectors}.
2398 @opencatbox{Categories:}
2399 @category{Package eigen}
2400 @closecatbox
2401 @end deffn
2403 @c -----------------------------------------------------------------------------
2404 @anchor{unitvector}
2405 @anchor{uvect}
2406 @deffn {Function} unitvector (@var{x})
2407 @deffnx {Function} uvect (@var{x})
2409 Returns @math{@var{x}/norm(@var{x})};
2410 this is a unit vector in the same direction as @var{x}.
2412 @code{load ("eigen")} loads this function.
2414 @code{uvect} is a synonym for @code{unitvector}.
2416 @opencatbox{Categories:}
2417 @category{Package eigen}
2418 @closecatbox
2419 @end deffn
2421 @c NEEDS EXAMPLES
2423 @c -----------------------------------------------------------------------------
2424 @anchor{vectorpotential}
2425 @deffn {Function} vectorpotential (@var{givencurl})
2427 Returns the vector potential of a given curl vector, in the current coordinate
2428 system. @code{potentialzeroloc} has a similar role as for @code{potential}, but
2429 the order of the left-hand sides of the equations must be a cyclic permutation
2430 of the coordinate variables.
2432 @opencatbox{Categories:}
2433 @category{Package vect}
2434 @closecatbox
2435 @end deffn
2437 @c NEEDS A LOT OF WORK: MAKE SURE THAT ALL VECTOR SIMPLIFICATION FLAGS HAVE A
2438 @c DESCRIPTION HERE
2440 @c -----------------------------------------------------------------------------
2441 @anchor{vectorsimp}
2442 @deffn {Function} vectorsimp (@var{expr})
2444 Applies simplifications and expansions according to the following global flags:
2446 @flushleft
2447 @code{expandall}, @code{expanddot}, @code{expanddotplus}, @code{expandcross}, @code{expandcrossplus},
2448 @code{expandcrosscross}, @code{expandgrad}, @code{expandgradplus}, @code{expandgradprod},
2449 @code{expanddiv}, @code{expanddivplus}, @code{expanddivprod}, @code{expandcurl}, @code{expandcurlplus},
2450 @code{expandcurlcurl}, @code{expandlaplacian}, @code{expandlaplacianplus},
2451 and @code{expandlaplacianprod}.
2452 @end flushleft
2454 All these flags have default value @code{false}. The @code{plus} suffix refers
2455 to employing additivity or distributivity. The @code{prod} suffix refers to the
2456 expansion for an operand that is any kind of product.
2458 @table @code
2459 @item expandcrosscross
2460 Simplifies
2461 m4_math(<<<p \sim (q \sim r)>>>, <<<p ~ (q ~ r)>>>)
2462 to
2463 m4_mathdot(<<<(p . r)q - (p . q)r>>>, <<<(p . r)*q-(p . q)*r>>>)
2464 @item expandcurlcurl
2465 Simplifies
2466 m4_math(<<<{\rm curl}\; {\rm curl}\; p>>>, <<<curl curl p>>>)
2467 to
2468 m4_mathdot(<<<{\rm grad}\; {\rm div}\; p + {\rm div}\; {\rm grad}\; p>>>, <<<grad div p + div grad p>>>)
2469 @item expandlaplaciantodivgrad
2470 Simplifies
2471 m4_math(<<<{\rm laplacian}\; p>>>,<<<laplacian p>>>)
2472 to
2473 m4_mathdot(<<<{\rm div}\; {\rm grad}\; p>>>, <<<div grad p>>>)
2474 @item expandcross
2475 Enables @code{expandcrossplus} and @code{expandcrosscross}.
2476 @item expandplus
2477 @flushleft
2478 Enables @code{expanddotplus}, @code{expandcrossplus}, @code{expandgradplus},
2479 @code{expanddivplus}, @code{expandcurlplus}, and @code{expandlaplacianplus}.
2480 @end flushleft
2481 @item expandprod
2482 Enables @code{expandgradprod}, @code{expanddivprod}, and @code{expandlaplacianprod}.
2483 @end table
2485 @c EXPLAIN THE IMPORT OF THIS STATEMENT
2486 These flags have all been declared @code{evflag}.
2488 @c SEEMS SOME TEXT HAS GONE MISSING HERE; COMMENT OUT FRAGMENT PENDING
2489 @c RECOVERY AND/OR RECONSTRUCTION OF THIS PARAGRAPH
2490 @c For orthogonal curvilinear coordinates, the global variables
2491 @c COORDINATES[[X,Y,Z]], DIMENSION[3], SF[[1,1,1]], and SFPROD[1] are set
2492 @c by the function invocation
2494 @opencatbox{Categories:}
2495 @category{Package vect}
2496 @category{Simplification functions}
2497 @closecatbox
2498 @end deffn
2500 @c -----------------------------------------------------------------------------
2501 @anchor{vect_cross}
2502 @defvr {Option variable} vect_cross
2503 Default value: @code{false}
2505 @c WHAT DOES THIS MEAN EXACTLY ??
2506 When @code{vect_cross} is @code{true}, it allows DIFF(X~Y,T) to work where
2507 ~ is defined in SHARE;VECT (where VECT_CROSS is set to @code{true}, anyway.)
2509 @opencatbox{Categories:}
2510 @category{Package vect}
2511 @category{Differential calculus}
2512 @closecatbox
2513 @end defvr
2515 @c -----------------------------------------------------------------------------
2516 @anchor{zeromatrix}
2517 @deffn {Function} zeromatrix (@var{m}, @var{n})
2519 Returns an @var{m} by @var{n} matrix, all elements of which are zero.
2521 @opencatbox{Categories:}
2522 @category{Matrices}
2523 @closecatbox
2524 @end deffn