doc/info/diag.texi

   1 @menu
   2 * Functions and Variables for diag::
   3 @end menu
   4
   5 @node Functions and Variables for diag,  , Package diag, Package diag
   6 @section Functions and Variables for diag
   7
   8
   9 @anchor{diag_function}
  10 @deffn {Function} diag (@var{lm})
  11 Constructs a matrix that is the block sum of the elements of
  12 @var{lm}. The elements of @var{lm} are assumed to be matrices; if an
  13 element is scalar, it treated as a 1 by 1 matrix.
  14
  15 The resulting matrix will be square if each of the elements of
  16 @var{lm} is square.
  17
  18 Example:
  19 @example
  20 (%i1) load("diag")$
  21
  22 (%i2) a1:matrix([1,2,3],[0,4,5],[0,0,6])$
  23
  24 (%i3) a2:matrix([1,1],[1,0])$
  25
  26 (%i4) diag([a1,x,a2]);
  27                    [ 1  2  3  0  0  0 ]
  28                    [                  ]
  29                    [ 0  4  5  0  0  0 ]
  30                    [                  ]
  31                    [ 0  0  6  0  0  0 ]
  32 (%o4)              [                  ]
  33                    [ 0  0  0  x  0  0 ]
  34                    [                  ]
  35                    [ 0  0  0  0  1  1 ]
  36                    [                  ]
  37                    [ 0  0  0  0  1  0 ]
  38 (%i5) diag ([matrix([1,2]), 3]);
  39                         [ 1  2  0 ]
  40 (%o5)                   [         ]
  41                         [ 0  0  3 ]
  42 @end example
  43
  44 To use this function write first @code{load("diag")}.
  45
  46 @opencatbox{Categories:}
  47 @category{Matrices}
  48 @category{Share packages}
  49 @category{Package diag}
  50 @closecatbox
  51
  52 @end deffn
  53
  54
  55 @anchor{JF}
  56 @deffn {Function} JF (@var{lambda},@var{n})
  57 Returns the Jordan cell of order @var{n} with eigenvalue @var{lambda}.
  58
  59 Example:
  60 @example
  61 (%i1) load("diag")$
  62
  63 (%i2) JF(2,5);
  64                     [ 2  1  0  0  0 ]
  65                     [               ]
  66                     [ 0  2  1  0  0 ]
  67                     [               ]
  68 (%o2)               [ 0  0  2  1  0 ]
  69                     [               ]
  70                     [ 0  0  0  2  1 ]
  71                     [               ]
  72                     [ 0  0  0  0  2 ]
  73 (%i3) JF(3,2);
  74                          [ 3  1 ]
  75 (%o3)                    [      ]
  76                          [ 0  3 ]
  77 @end example
  78
  79 To use this function write first @code{load("diag")}.
  80
  81 @opencatbox{Categories:}
  82 @category{Package diag}
  83 @closecatbox
  84
  85 @end deffn
  86
  87
  88 @anchor{jordan}
  89 @deffn {Function} jordan (@var{mat})
  90 Returns the Jordan form of matrix @var{mat}, encoded as a list in a
  91 particular format. To get the corresponding matrix, call the function
  92 @code{dispJordan} using the output of @code{jordan} as the argument.
  93
  94 The elements of the returned list are themselves lists. The first
  95 element of each is an eigenvalue of @var{mat}. The remaining elements
  96 are positive integers which are the lengths of the Jordan blocks for
  97 this eigenvalue. These integers are listed in decreasing
  98 order. Eigenvalues are not repeated.
  99
 100 The functions @code{dispJordan}, @code{minimalPoly} and
 101 @code{ModeMatrix} expect the output of a call to @code{jordan} as an
 102 argument. If you construct this argument by hand, rather than by
 103 calling @code{jordan}, you must ensure that each eigenvalue only
 104 appears once and that the block sizes are listed in decreasing order,
 105 otherwise the functions might give incorrect answers.
 106
 107 Example:
 108 @c ===beg===
 109 @c load("diag")$
 110 @c A: matrix([2,0,0,0,0,0,0,0],
 111 @c                 [1,2,0,0,0,0,0,0],
 112 @c                 [-4,1,2,0,0,0,0,0],
 113 @c                 [2,0,0,2,0,0,0,0],
 114 @c                 [-7,2,0,0,2,0,0,0],
 115 @c                 [9,0,-2,0,1,2,0,0],
 116 @c                 [-34,7,1,-2,-1,1,2,0],
 117 @c                 [145,-17,-16,3,9,-2,0,3])$
 118 @c jordan (A);
 119 @c dispJordan (%);
 120 @c ===end===
 121 @example
 122 (%i1) load("diag")$
 123 @group
 124 (%i2) A: matrix([2,0,0,0,0,0,0,0],
 125                 [1,2,0,0,0,0,0,0],
 126                 [-4,1,2,0,0,0,0,0],
 127                 [2,0,0,2,0,0,0,0],
 128                 [-7,2,0,0,2,0,0,0],
 129                 [9,0,-2,0,1,2,0,0],
 130                 [-34,7,1,-2,-1,1,2,0],
 131                 [145,-17,-16,3,9,-2,0,3])$
 132 @end group
 133 @group
 134 (%i3) jordan (A);
 135 (%o3)                [[2, 3, 3, 1], [3, 1]]
 136 @end group
 137 (%i4) dispJordan (%);
 138                    [ 2  1  0  0  0  0  0  0 ]
 139                    [                        ]
 140                    [ 0  2  1  0  0  0  0  0 ]
 141                    [                        ]
 142                    [ 0  0  2  0  0  0  0  0 ]
 143                    [                        ]
 144                    [ 0  0  0  2  1  0  0  0 ]
 145 (%o4)              [                        ]
 146                    [ 0  0  0  0  2  1  0  0 ]
 147                    [                        ]
 148                    [ 0  0  0  0  0  2  0  0 ]
 149                    [                        ]
 150                    [ 0  0  0  0  0  0  2  0 ]
 151                    [                        ]
 152                    [ 0  0  0  0  0  0  0  3 ]
 153 @end example
 154
 155 To use this function write first @code{load("diag")}. See also @mref{dispJordan} and @mrefdot{minimalPoly}
 156
 157 @opencatbox{Categories:}
 158 @category{Package diag}
 159 @closecatbox
 160
 161 @end deffn
 162
 163
 164 @anchor{dispJordan}
 165 @deffn {Function} dispJordan (@var{l})
 166 Returns a matrix in Jordan canonical form (JCF) corresponding to the
 167 list of eigenvalues and multiplicities given by @var{l}. This list
 168 should be in the format given by the @mref{jordan} function. See
 169 @mref{jordan} for details of this format.
 170
 171 Example:
 172 @example
 173 (%i1) load("diag")$
 174
 175 (%i2) b1:matrix([0,0,1,1,1],
 176                 [0,0,0,1,1],
 177                 [0,0,0,0,1],
 178                 [0,0,0,0,0],
 179                 [0,0,0,0,0])$
 180
 181 (%i3) jordan(b1);
 182 (%o3)                  [[0, 3, 2]]
 183 (%i4) dispJordan(%);
 184                     [ 0  1  0  0  0 ]
 185                     [               ]
 186                     [ 0  0  1  0  0 ]
 187                     [               ]
 188 (%o4)               [ 0  0  0  0  0 ]
 189                     [               ]
 190                     [ 0  0  0  0  1 ]
 191                     [               ]
 192                     [ 0  0  0  0  0 ]
 193 @end example
 194
 195 To use this function write first @code{load("diag")}. See also @mref{jordan} and @mrefdot{minimalPoly}
 196
 197 @opencatbox{Categories:}
 198 @category{Package diag}
 199 @closecatbox
 200
 201 @end deffn
 202
 203
 204 @anchor{minimalPoly}
 205 @deffn {Function} minimalPoly (@var{l})
 206 Returns the minimal polynomial of the matrix whose Jordan form is
 207 described by the list @var{l}. This list should be in the format given
 208 by the @mref{jordan} function. See @mref{jordan} for details of this
 209 format.
 210
 211 Example:
 212 @example
 213 (%i1) load("diag")$
 214
 215 (%i2) a:matrix([2,1,2,0],
 216                [-2,2,1,2],
 217                [-2,-1,-1,1],
 218                [3,1,2,-1])$
 219
 220 (%i3) jordan(a);
 221 (%o3)               [[- 1, 1], [1, 3]]
 222 (%i4) minimalPoly(%);
 223                             3
 224 (%o4)                (x - 1)  (x + 1)
 225 @end example
 226
 227 To use this function write first @code{load("diag")}. See also @mref{jordan} and @mrefdot{dispJordan}
 228
 229 @opencatbox{Categories:}
 230 @category{Package diag}
 231 @closecatbox
 232
 233 @end deffn
 234
 235 @anchor{ModeMatrix}
 236 @deffn {Function} ModeMatrix (@var{A}, [@var{jordan_info}])
 237 Returns an invertible matrix @var{M} such that @math{(M^^-1).A.M} is
 238 the Jordan form of @var{A}.
 239
 240 To calculate this, Maxima must find the Jordan form of @var{A}, which
 241 might be quite computationally expensive. If that has already been
 242 calculated by a previous call to @mref{jordan}, pass it as a second
 243 argument, @var{jordan_info}. See @mref{jordan} for details of the
 244 required format.
 245
 246 Example:
 247 @c ===beg===
 248 @c load("diag")$
 249 @c A: matrix([2,1,2,0], [-2,2,1,2], [-2,-1,-1,1], [3,1,2,-1])$
 250 @c M: ModeMatrix (A);
 251 @c is ((M^^-1) . A . M = dispJordan (jordan (A)));
 252 @c ===end===
 253 @example
 254 (%i1) load("diag")$
 255 (%i2) A: matrix([2,1,2,0], [-2,2,1,2], [-2,-1,-1,1], [3,1,2,-1])$
 256 (%i3) M: ModeMatrix (A);
 257                       [  1    - 1   1   1 ]
 258                       [                   ]
 259                       [   1               ]
 260                       [ - -   - 1   0   0 ]
 261                       [   9               ]
 262                       [                   ]
 263 (%o3)                 [   13              ]
 264                       [ - --   1   - 1  0 ]
 265                       [   9               ]
 266                       [                   ]
 267                       [  17               ]
 268                       [  --   - 1   1   1 ]
 269                       [  9                ]
 270 @group
 271 (%i4) is ((M^^-1) . A . M = dispJordan (jordan (A)));
 272 (%o4)                         true
 273 @end group
 274 @end example
 275
 276 Note that, in this example, the Jordan form of @code{A} is computed
 277 twice. To avoid this, we could have stored the output of
 278 @code{jordan(A)} in a variable and passed that to both
 279 @code{ModeMatrix} and @code{dispJordan}.
 280
 281 To use this function write first @code{load("diag")}. See also
 282 @mref{jordan} and @mrefdot{dispJordan}
 283
 284 @opencatbox{Categories:}
 285 @category{Package diag}
 286 @closecatbox
 287
 288 @end deffn
 289
 290
 291 @anchor{mat_function}
 292 @deffn {Function} mat_function (@var{f},@var{A})
 293 Returns @math{f(A)}, where @var{f} is an analytic function and @var{A}
 294 a matrix. This computation is based on the Taylor expansion of
 295 @var{f}. It is not efficient for numerical evaluation, but can give
 296 symbolic answers for small matrices.
 297
 298 @c What other methods do we have in Maxima at the moment? We should
 299 @c probably give links here...
 300
 301 Example 1:
 302
 303 The exponential of a matrix. We only give the first row of the answer,
 304 since the output is rather large.
 305 @c ===beg===
 306 @c load("diag")$
 307 @c A: matrix ([0,1,0], [0,0,1], [-1,-3,-3])$
 308 @c ratsimp (mat_function (exp, t*A)[1]);
 309 @c ===end===
 310 @example
 311 (%i1) load("diag")$
 312 (%i2) A: matrix ([0,1,0], [0,0,1], [-1,-3,-3])$
 313 @group
 314 (%i3) ratsimp (mat_function (exp, t*A)[1]);
 315            2              - t                   2   - t
 316          (t  + 2 t + 2) %e       2        - t  t  %e
 317 (%o3)   [--------------------, (t  + t) %e   , --------]
 318                   2                               2
 319 @end group
 320 @end example
 321
 322 Example 2:
 323
 324 Comparison with the Taylor series for the exponential and also
 325 comparing @code{exp(%i*A)} with sine and cosine.
 326 @c ===beg===
 327 @c load("diag")$
 328 @c A: matrix ([0,1,1,1],
 329 @c                  [0,0,0,1],
 330 @c                  [0,0,0,1],
 331 @c                  [0,0,0,0])$
 332 @c ratsimp (mat_function (exp, t*A));
 333 @c minimalPoly (jordan (A));
 334 @c ratsimp (ident(4) + t*A + 1/2*(t^2)*A^^2);
 335 @c ratsimp (mat_function (exp, %i*t*A));
 336 @c ratsimp (mat_function (cos, t*A) + %i*mat_function (sin, t*A));
 337 @c ===end===
 338 @example
 339 (%i1) load("diag")$
 340 @group
 341 (%i2) A: matrix ([0,1,1,1],
 342                  [0,0,0,1],
 343                  [0,0,0,1],
 344                  [0,0,0,0])$
 345 @end group
 346 @group
 347 (%i3) ratsimp (mat_function (exp, t*A));
 348                        [           2     ]
 349                        [ 1  t  t  t  + t ]
 350                        [                 ]
 351 (%o3)                  [ 0  1  0    t    ]
 352                        [                 ]
 353                        [ 0  0  1    t    ]
 354                        [                 ]
 355                        [ 0  0  0    1    ]
 356 @end group
 357 @group
 358 (%i4) minimalPoly (jordan (A));
 359                                 3
 360 (%o4)                          x
 361 @end group
 362 @group
 363 (%i5) ratsimp (ident(4) + t*A + 1/2*(t^2)*A^^2);
 364                        [           2     ]
 365                        [ 1  t  t  t  + t ]
 366                        [                 ]
 367 (%o5)                  [ 0  1  0    t    ]
 368                        [                 ]
 369                        [ 0  0  1    t    ]
 370                        [                 ]
 371                        [ 0  0  0    1    ]
 372 @end group
 373 @group
 374 (%i6) ratsimp (mat_function (exp, %i*t*A));
 375                   [                        2 ]
 376                   [ 1  %i t  %i t  %i t - t  ]
 377                   [                          ]
 378 (%o6)             [ 0   1     0      %i t    ]
 379                   [                          ]
 380                   [ 0   0     1      %i t    ]
 381                   [                          ]
 382                   [ 0   0     0        1     ]
 383 @end group
 384 @group
 385 (%i7) ratsimp (mat_function (cos, t*A) + %i*mat_function (sin, t*A));
 386                   [                        2 ]
 387                   [ 1  %i t  %i t  %i t - t  ]
 388                   [                          ]
 389 (%o7)             [ 0   1     0      %i t    ]
 390                   [                          ]
 391                   [ 0   0     1      %i t    ]
 392                   [                          ]
 393                   [ 0   0     0        1     ]
 394 @end group
 395 @end example
 396
 397 Example 3:
 398
 399 Power operations.
 400 @c ===beg===
 401 @c load("diag")$
 402 @c A: matrix([1,2,0], [0,1,0], [1,0,1])$
 403 @c integer_pow(x) := block ([k], declare (k, integer), x^k)$
 404 @c mat_function (integer_pow, A);
 405 @c A^^20;
 406 @c ===end===
 407 @example
 408 (%i1) load("diag")$
 409 (%i2) A: matrix([1,2,0], [0,1,0], [1,0,1])$
 410 (%i3) integer_pow(x) := block ([k], declare (k, integer), x^k)$
 411 @group
 412 (%i4) mat_function (integer_pow, A);
 413                        [ 1     2 k     0 ]
 414                        [                 ]
 415 (%o4)                  [ 0      1      0 ]
 416                        [                 ]
 417                        [ k  (k - 1) k  1 ]
 418 @end group
 419 @group
 420 (%i5) A^^20;
 421                          [ 1   40   0 ]
 422                          [            ]
 423 (%o5)                    [ 0    1   0 ]
 424                          [            ]
 425                          [ 20  380  1 ]
 426 @end group
 427 @end example
 428
 429 To use this function write first @code{load("diag")}.
 430
 431 @opencatbox{Categories:}
 432 @category{Package diag}
 433 @closecatbox
 434
 435 @end deffn
 436
 437