1NAME 2 Math::Matrix - multiply and invert matrices 3 4SYNOPSIS 5 use Math::Matrix; 6 7 # Generate a random 3-by-3 matrix. 8 srand(time); 9 my $A = Math::Matrix -> new([rand, rand, rand], 10 [rand, rand, rand], 11 [rand, rand, rand]); 12 $A -> print("A\n"); 13 14 # Append a fourth column to $A. 15 my $x = Math::Matrix -> new([rand, rand, rand]); 16 my $E = $A -> concat($x -> transpose); 17 $E -> print("Equation system\n"); 18 19 # Compute the solution. 20 my $s = $E -> solve; 21 $s -> print("Solutions s\n"); 22 23 # Verify that the solution equals $x. 24 $A -> multiply($s) -> print("A*s\n"); 25 26DESCRIPTION 27 This module implements various constructors and methods for creating and 28 manipulating matrices. 29 30 All methods return new objects, so, for example, "$X->add($Y)" does not 31 modify $X. 32 33 $X -> add($Y); # $X not modified; output is lost 34 $X = $X -> add($Y); # this works 35 36 Some operators are overloaded (see "OVERLOADING") and allow the operand 37 to be modified directly. 38 39 $X = $X + $Y; # this works 40 $X += $Y; # so does this 41 42METHODS 43 Constructors 44 new() 45 Creates a new object from the input arguments and returns it. 46 47 If a single input argument is given, and that argument is a 48 reference to array whose first element is itself a reference to an 49 array, it is assumed that the argument contains the whole matrix, 50 like this: 51 52 $x = Math::Matrix->new([[1, 2, 3], [4, 5, 6]]); # 2-by-3 matrix 53 $x = Math::Matrix->new([[1, 2, 3]]); # 1-by-3 matrix 54 $x = Math::Matrix->new([[1], [2], [3]]); # 3-by-1 matrix 55 56 If a single input argument is given, and that argument is not a 57 reference to an array, a 1-by-1 matrix is returned. 58 59 $x = Math::Matrix->new(1); # 1-by-1 matrix 60 61 Note that all the folling cases result in an empty matrix: 62 63 $x = Math::Matrix->new([[], [], []]); 64 $x = Math::Matrix->new([[]]); 65 $x = Math::Matrix->new([]); 66 67 If "new()" is called as an instance method with no input arguments, 68 a zero filled matrix with identical dimensions is returned: 69 70 $b = $a->new(); # $b is a zero matrix with the size of $a 71 72 Each row must contain the same number of elements. 73 74 new_from_sub() 75 Creates a new matrix object by doing a subroutine call to create 76 each element. 77 78 $sub = sub { ... }; 79 $x = Math::Matrix -> new_from_sub($sub); # 1-by-1 80 $x = Math::Matrix -> new_from_sub($sub, $m); # $m-by-$m 81 $x = Math::Matrix -> new_from_sub($sub, $m, $n); # $m-by-$n 82 83 The subroutine is called in scalar context with two input arguments, 84 the row and column indices of the element to be created. Note that 85 no checks are performed on the output of the subroutine. 86 87 Example 1, a 4-by-4 identity matrix can be created with 88 89 $sub = sub { $_[0] == $_[1] ? 1 : 0 }; 90 $x = Math::Matrix -> new_from_sub($sub, 4); 91 92 Example 2, the code 93 94 $x = Math::Matrix -> new_from_sub(sub { 2**$_[1] }, 1, 11); 95 96 creates the following 1-by-11 vector with powers of two 97 98 [ 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 ] 99 100 Example 3, the code, using $i and $j for increased readability 101 102 $sub = sub { 103 ($i, $j) = @_; 104 $d = $j - $i; 105 return $d == -1 ? 5 106 : $d == 0 ? 6 107 : $d == 1 ? 7 108 : 0; 109 }; 110 $x = Math::Matrix -> new_from_sub($sub, 5); 111 112 creates the tridiagonal matrix 113 114 [ 6 7 0 0 0 ] 115 [ 5 6 7 0 0 ] 116 [ 0 5 6 7 0 ] 117 [ 0 0 5 6 7 ] 118 [ 0 0 0 5 6 ] 119 120 new_from_rows() 121 Creates a new matrix by assuming each argument is a row vector. 122 123 $x = Math::Matrix -> new_from_rows($y, $z, ...); 124 125 For example 126 127 $x = Math::Matrix -> new_from_rows([1, 2, 3],[4, 5, 6]); 128 129 returns the matrix 130 131 [ 1 2 3 ] 132 [ 4 5 6 ] 133 134 new_from_cols() 135 Creates a matrix by assuming each argument is a column vector. 136 137 $x = Math::Matrix -> new_from_cols($y, $z, ...); 138 139 For example, 140 141 $x = Math::Matrix -> new_from_cols([1, 2, 3],[4, 5, 6]); 142 143 returns the matrix 144 145 [ 1 4 ] 146 [ 2 5 ] 147 [ 3 6 ] 148 149 id() 150 Returns a new identity matrix. 151 152 $I = Math::Matrix -> id($n); # $n-by-$n identity matrix 153 $I = $x -> id($n); # $n-by-$n identity matrix 154 $I = $x -> id(); # identity matrix with size of $x 155 156 new_identity() 157 This is an alias for "id()". 158 159 eye() 160 This is an alias for "id()". 161 162 exchg() 163 Exchange matrix. 164 165 $x = Math::Matrix -> exchg($n); # $n-by-$n exchange matrix 166 167 scalar() 168 Returns a scalar matrix, i.e., a diagonal matrix with all the 169 diagonal elements set to the same value. 170 171 # Create an $m-by-$m scalar matrix where each element is $c. 172 $x = Math::Matrix -> scalar($c, $m); 173 174 # Create an $m-by-$n scalar matrix where each element is $c. 175 $x = Math::Matrix -> scalar($c, $m, $n); 176 177 Multiplying a matrix A by a scalar matrix B is effectively the same 178 as multiply each element in A by the constant on the diagonal of B. 179 180 zeros() 181 Create a zero matrix. 182 183 # Create an $m-by-$m matrix where each element is 0. 184 $x = Math::Matrix -> zeros($m); 185 186 # Create an $m-by-$n matrix where each element is 0. 187 $x = Math::Matrix -> zeros($m, $n); 188 189 ones() 190 Create a matrix of ones. 191 192 # Create an $m-by-$m matrix where each element is 1. 193 $x = Math::Matrix -> ones($m); 194 195 # Create an $m-by-$n matrix where each element is 1. 196 $x = Math::Matrix -> ones($m, $n); 197 198 inf() 199 Create a matrix of positive infinities. 200 201 # Create an $m-by-$m matrix where each element is Inf. 202 $x = Math::Matrix -> inf($m); 203 204 # Create an $m-by-$n matrix where each element is Inf. 205 $x = Math::Matrix -> inf($m, $n); 206 207 nan() 208 Create a matrix of NaNs (Not-a-Number). 209 210 # Create an $m-by-$m matrix where each element is NaN. 211 $x = Math::Matrix -> nan($m); 212 213 # Create an $m-by-$n matrix where each element is NaN. 214 $x = Math::Matrix -> nan($m, $n); 215 216 constant() 217 Returns a constant matrix, i.e., a matrix whose elements all have 218 the same value. 219 220 # Create an $m-by-$m matrix where each element is $c. 221 $x = Math::Matrix -> constant($c, $m); 222 223 # Create an $m-by-$n matrix where each element is $c. 224 $x = Math::Matrix -> constant($c, $m, $n); 225 226 rand() 227 Returns a matrix of uniformly distributed random numbers in the 228 range [0,1). 229 230 $x = Math::Matrix -> rand($m); # $m-by-$m matrix 231 $x = Math::Matrix -> rand($m, $n); # $m-by-$n matrix 232 233 To generate an $m-by-$n matrix of uniformly distributed random 234 numbers in the range [0,$a), use 235 236 $x = $a * Math::Matrix -> rand($m, $n); 237 238 To generate an $m-by-$n matrix of uniformly distributed random 239 numbers in the range [$a,$b), use 240 241 $x = $a + ($b - $a) * Math::Matrix -> rand($m, $n); 242 243 See also "randi()" and "randn()". 244 245 randi() 246 Returns a matrix of uniformly distributed random integers. 247 248 $x = Math::Matrix -> randi($max); # 1-by-1 matrix 249 $x = Math::Matrix -> randi($max, $n); # $n-by-$n matrix 250 $x = Math::Matrix -> randi($max, $m, $n); # $m-by-$n matrix 251 252 $x = Math::Matrix -> randi([$min, $max]); # 1-by-1 matrix 253 $x = Math::Matrix -> randi([$min, $max], $n); # $n-by-$n matrix 254 $x = Math::Matrix -> randi([$min, $max], $m, $n); # $m-by-$n matrix 255 256 See also "rand()" and "randn()". 257 258 randn() 259 Returns a matrix of random numbers from the standard normal 260 distribution. 261 262 $x = Math::Matrix -> randn($m); # $m-by-$m matrix 263 $x = Math::Matrix -> randn($m, $n); # $m-by-$n matrix 264 265 To generate an $m-by-$n matrix with mean $mu and standard deviation 266 $sigma, use 267 268 $x = $mu + $sigma * Math::Matrix -> randn($m, $n); 269 270 See also "rand()" and "randi()". 271 272 clone() 273 Clones a matrix and returns the clone. 274 275 $b = $a->clone; 276 277 diagonal() 278 A constructor method that creates a diagonal matrix from a single 279 list or array of numbers. 280 281 $p = Math::Matrix->diagonal(1, 4, 4, 8); 282 $q = Math::Matrix->diagonal([1, 4, 4, 8]); 283 284 The matrix is zero filled except for the diagonal members, which 285 take the values of the vector. 286 287 The method returns undef in case of error. 288 289 tridiagonal() 290 A constructor method that creates a matrix from vectors of numbers. 291 292 $p = Math::Matrix->tridiagonal([1, 4, 4, 8]); 293 $q = Math::Matrix->tridiagonal([1, 4, 4, 8], [9, 12, 15]); 294 $r = Math::Matrix->tridiagonal([1, 4, 4, 8], [9, 12, 15], [4, 3, 2]); 295 296 In the first case, the main diagonal takes the values of the vector, 297 while both of the upper and lower diagonals's values are all set to 298 one. 299 300 In the second case, the main diagonal takes the values of the first 301 vector, while the upper and lower diagonals are each set to the 302 values of the second vector. 303 304 In the third case, the main diagonal takes the values of the first 305 vector, while the upper diagonal is set to the values of the second 306 vector, and the lower diagonal is set to the values of the third 307 vector. 308 309 The method returns undef in case of error. 310 311 blkdiag() 312 Create block diagonal matrix. Returns a block diagonal matrix given 313 a list of matrices. 314 315 $z = Math::Matrix -> blkdiag($x, $y, ...); 316 317 Identify matrices 318 is_empty() 319 Returns 1 is the invocand is empty, i.e., it has no elements. 320 321 $bool = $x -> is_empty(); 322 323 is_scalar() 324 Returns 1 is the invocand is a scalar, i.e., it has one element. 325 326 $bool = $x -> is_scalar(); 327 328 is_vector() 329 Returns 1 is the invocand is a vector, i.e., a row vector or a 330 column vector. 331 332 $bool = $x -> is_vector(); 333 334 is_row() 335 Returns 1 if the invocand has exactly one row, and 0 otherwise. 336 337 $bool = $x -> is_row(); 338 339 is_col() 340 Returns 1 if the invocand has exactly one column, and 0 otherwise. 341 342 $bool = $x -> is_col(); 343 344 is_square() 345 Returns 1 is the invocand is square, and 0 otherwise. 346 347 $bool = $x -> is_square(); 348 349 is_symmetric() 350 Returns 1 is the invocand is symmetric, and 0 otherwise. 351 352 $bool = $x -> is_symmetric(); 353 354 An symmetric matrix satisfies x(i,j) = x(j,i) for all i and j, for 355 example 356 357 [ 1 2 -3 ] 358 [ 2 -4 5 ] 359 [ -3 5 6 ] 360 361 is_antisymmetric() 362 Returns 1 is the invocand is antisymmetric a.k.a. skew-symmetric, 363 and 0 otherwise. 364 365 $bool = $x -> is_antisymmetric(); 366 367 An antisymmetric matrix satisfies x(i,j) = -x(j,i) for all i and j, 368 for example 369 370 [ 0 2 -3 ] 371 [ -2 0 4 ] 372 [ 3 -4 0 ] 373 374 is_persymmetric() 375 Returns 1 is the invocand is persymmetric, and 0 otherwise. 376 377 $bool = $x -> is_persymmetric(); 378 379 A persymmetric matrix is a square matrix which is symmetric with 380 respect to the anti-diagonal, e.g.: 381 382 [ f h j k ] 383 [ c g i j ] 384 [ b d g h ] 385 [ a b c f ] 386 387 is_hankel() 388 Returns 1 is the invocand is a Hankel matric a.k.a. a catalecticant 389 matrix, and 0 otherwise. 390 391 $bool = $x -> is_hankel(); 392 393 A Hankel matrix is a square matrix in which each ascending 394 skew-diagonal from left to right is constant, e.g.: 395 396 [ e f g h i ] 397 [ d e f g h ] 398 [ c d e f g ] 399 [ b c d e f ] 400 [ a b c d e ] 401 402 is_zero() 403 Returns 1 is the invocand is a zero matrix, and 0 otherwise. A zero 404 matrix contains no element whose value is different from zero. 405 406 $bool = $x -> is_zero(); 407 408 is_one() 409 Returns 1 is the invocand is a matrix of ones, and 0 otherwise. A 410 matrix of ones contains no element whose value is different from 411 one. 412 413 $bool = $x -> is_one(); 414 415 is_constant() 416 Returns 1 is the invocand is a constant matrix, and 0 otherwise. A 417 constant matrix is a matrix where no two elements have different 418 values. 419 420 $bool = $x -> is_constant(); 421 422 is_identity() 423 Returns 1 is the invocand is an identity matrix, and 0 otherwise. An 424 identity matrix contains ones on the main diagonal and zeros 425 elsewhere. 426 427 $bool = $x -> is_identity(); 428 429 is_exchg() 430 Returns 1 is the invocand is an exchange matrix, and 0 otherwise. 431 432 $bool = $x -> is_exchg(); 433 434 An exchange matrix contains ones on the main anti-diagonal and zeros 435 elsewhere, for example 436 437 [ 0 0 1 ] 438 [ 0 1 0 ] 439 [ 1 0 0 ] 440 441 is_bool() 442 Returns 1 is the invocand is a boolean matrix, and 0 otherwise. 443 444 $bool = $x -> is_bool(); 445 446 A boolean matrix is a matrix is a matrix whose entries are either 0 447 or 1, for example 448 449 [ 0 1 1 ] 450 [ 1 0 0 ] 451 [ 0 1 0 ] 452 453 is_perm() 454 Returns 1 is the invocand is an permutation matrix, and 0 otherwise. 455 456 $bool = $x -> is_perm(); 457 458 A permutation matrix is a square matrix with exactly one 1 in each 459 row and column, and all other elements 0, for example 460 461 [ 0 1 0 ] 462 [ 1 0 0 ] 463 [ 0 0 1 ] 464 465 is_int() 466 Returns 1 is the invocand is an integer matrix, i.e., a matrix of 467 integers, and 0 otherwise. 468 469 $bool = $x -> is_int(); 470 471 is_diag() 472 Returns 1 is the invocand is diagonal, and 0 otherwise. 473 474 $bool = $x -> is_diag(); 475 476 A diagonal matrix is a square matrix where all non-zero elements, if 477 any, are on the main diagonal. It has the following pattern, where 478 only the elements marked as "x" can be non-zero, 479 480 [ x 0 0 0 0 ] 481 [ 0 x 0 0 0 ] 482 [ 0 0 x 0 0 ] 483 [ 0 0 0 x 0 ] 484 [ 0 0 0 0 x ] 485 486 is_adiag() 487 Returns 1 is the invocand is anti-diagonal, and 0 otherwise. 488 489 $bool = $x -> is_adiag(); 490 491 A diagonal matrix is a square matrix where all non-zero elements, if 492 any, are on the main antidiagonal. It has the following pattern, 493 where only the elements marked as "x" can be non-zero, 494 495 [ 0 0 0 0 x ] 496 [ 0 0 0 x 0 ] 497 [ 0 0 x 0 0 ] 498 [ 0 x 0 0 0 ] 499 [ x 0 0 0 0 ] 500 501 is_tridiag() 502 Returns 1 is the invocand is tridiagonal, and 0 otherwise. 503 504 $bool = $x -> is_tridiag(); 505 506 A tridiagonal matrix is a square matrix with nonzero elements only 507 on the diagonal and slots horizontally or vertically adjacent the 508 diagonal (i.e., along the subdiagonal and superdiagonal). It has the 509 following pattern, where only the elements marked as "x" can be 510 non-zero, 511 512 [ x x 0 0 0 ] 513 [ x x x 0 0 ] 514 [ 0 x x x 0 ] 515 [ 0 0 x x x ] 516 [ 0 0 0 x x ] 517 518 is_atridiag() 519 Returns 1 is the invocand is anti-tridiagonal, and 0 otherwise. 520 521 $bool = $x -> is_tridiag(); 522 523 A anti-tridiagonal matrix is a square matrix with nonzero elements 524 only on the anti-diagonal and slots horizontally or vertically 525 adjacent the diagonal (i.e., along the anti-subdiagonal and 526 anti-superdiagonal). It has the following pattern, where only the 527 elements marked as "x" can be non-zero, 528 529 [ 0 0 0 x x ] 530 [ 0 0 x x x ] 531 [ 0 x x x 0 ] 532 [ x x x 0 0 ] 533 [ x x 0 0 0 ] 534 535 is_pentadiag() 536 Returns 1 is the invocand is pentadiagonal, and 0 otherwise. 537 538 $bool = $x -> is_pentadiag(); 539 540 A pentadiagonal matrix is a square matrix with nonzero elements only 541 on the diagonal and the two diagonals above and below the main 542 diagonal. It has the following pattern, where only the elements 543 marked as "x" can be non-zero, 544 545 [ x x x 0 0 0 ] 546 [ x x x x 0 0 ] 547 [ x x x x x 0 ] 548 [ 0 x x x x x ] 549 [ 0 0 x x x x ] 550 [ 0 0 0 x x x ] 551 552 is_apentadiag() 553 Returns 1 is the invocand is anti-pentadiagonal, and 0 otherwise. 554 555 $bool = $x -> is_pentadiag(); 556 557 A anti-pentadiagonal matrix is a square matrix with nonzero elements 558 only on the anti-diagonal and two anti-diagonals above and below the 559 main anti-diagonal. It has the following pattern, where only the 560 elements marked as "x" can be non-zero, 561 562 [ 0 0 0 x x x ] 563 [ 0 0 x x x x ] 564 [ 0 x x x x x ] 565 [ x x x x x 0 ] 566 [ x x x x 0 0 ] 567 [ x x x 0 0 0 ] 568 569 is_heptadiag() 570 Returns 1 is the invocand is heptadiagonal, and 0 otherwise. 571 572 $bool = $x -> is_heptadiag(); 573 574 A heptadiagonal matrix is a square matrix with nonzero elements only 575 on the diagonal and the two diagonals above and below the main 576 diagonal. It has the following pattern, where only the elements 577 marked as "x" can be non-zero, 578 579 [ x x x x 0 0 ] 580 [ x x x x x 0 ] 581 [ x x x x x x ] 582 [ x x x x x x ] 583 [ 0 x x x x x ] 584 [ 0 0 x x x x ] 585 586 is_aheptadiag() 587 Returns 1 is the invocand is anti-heptadiagonal, and 0 otherwise. 588 589 $bool = $x -> is_heptadiag(); 590 591 A anti-heptadiagonal matrix is a square matrix with nonzero elements 592 only on the anti-diagonal and two anti-diagonals above and below the 593 main anti-diagonal. It has the following pattern, where only the 594 elements marked as "x" can be non-zero, 595 596 [ 0 0 x x x x ] 597 [ 0 x x x x x ] 598 [ x x x x x x ] 599 [ x x x x x x ] 600 [ x x x x x 0 ] 601 [ x x x x 0 0 ] 602 603 is_band() 604 Returns 1 is the invocand is a band matrix with a specified 605 bandwidth, and 0 otherwise. 606 607 $bool = $x -> is_band($k); 608 609 A band matrix is a square matrix with nonzero elements only on the 610 diagonal and on the $k diagonals above and below the main diagonal. 611 The bandwidth $k must be non-negative. 612 613 $bool = $x -> is_band(0); # is $x diagonal? 614 $bool = $x -> is_band(1); # is $x tridiagonal? 615 $bool = $x -> is_band(2); # is $x pentadiagonal? 616 $bool = $x -> is_band(3); # is $x heptadiagonal? 617 618 See also "is_aband()" and "bandwidth()". 619 620 is_aband() 621 Returns 1 is the invocand is "anti-banded" with a specified 622 bandwidth, and 0 otherwise. 623 624 $bool = $x -> is_aband($k); 625 626 Some examples 627 628 $bool = $x -> is_aband(0); # is $x anti-diagonal? 629 $bool = $x -> is_aband(1); # is $x anti-tridiagonal? 630 $bool = $x -> is_aband(2); # is $x anti-pentadiagonal? 631 $bool = $x -> is_aband(3); # is $x anti-heptadiagonal? 632 633 A band matrix is a square matrix with nonzero elements only on the 634 diagonal and on the $k diagonals above and below the main diagonal. 635 The bandwidth $k must be non-negative. 636 637 A "anti-banded" matrix is a square matrix with nonzero elements only 638 on the anti-diagonal and $k anti-diagonals above and below the main 639 anti-diagonal. 640 641 See also "is_band()" and "bandwidth()". 642 643 is_triu() 644 Returns 1 is the invocand is upper triangular, and 0 otherwise. 645 646 $bool = $x -> is_triu(); 647 648 An upper triangular matrix is a square matrix where all non-zero 649 elements are on or above the main diagonal. It has the following 650 pattern, where only the elements marked as "x" can be non-zero. It 651 has the following pattern, where only the elements marked as "x" can 652 be non-zero, 653 654 [ x x x x ] 655 [ 0 x x x ] 656 [ 0 0 x x ] 657 [ 0 0 0 x ] 658 659 is_striu() 660 Returns 1 is the invocand is strictly upper triangular, and 0 661 otherwise. 662 663 $bool = $x -> is_striu(); 664 665 A strictly upper triangular matrix is a square matrix where all 666 non-zero elements are strictly above the main diagonal. It has the 667 following pattern, where only the elements marked as "x" can be 668 non-zero, 669 670 [ 0 x x x ] 671 [ 0 0 x x ] 672 [ 0 0 0 x ] 673 [ 0 0 0 0 ] 674 675 is_tril() 676 Returns 1 is the invocand is lower triangular, and 0 otherwise. 677 678 $bool = $x -> is_tril(); 679 680 A lower triangular matrix is a square matrix where all non-zero 681 elements are on or below the main diagonal. It has the following 682 pattern, where only the elements marked as "x" can be non-zero, 683 684 [ x 0 0 0 ] 685 [ x x 0 0 ] 686 [ x x x 0 ] 687 [ x x x x ] 688 689 is_stril() 690 Returns 1 is the invocand is strictly lower triangular, and 0 691 otherwise. 692 693 $bool = $x -> is_stril(); 694 695 A strictly lower triangular matrix is a square matrix where all 696 non-zero elements are strictly below the main diagonal. It has the 697 following pattern, where only the elements marked as "x" can be 698 non-zero, 699 700 [ 0 0 0 0 ] 701 [ x 0 0 0 ] 702 [ x x 0 0 ] 703 [ x x x 0 ] 704 705 is_atriu() 706 Returns 1 is the invocand is upper anti-triangular, and 0 otherwise. 707 708 $bool = $x -> is_atriu(); 709 710 An upper anti-triangular matrix is a square matrix where all 711 non-zero elements are on or above the main anti-diagonal. It has the 712 following pattern, where only the elements marked as "x" can be 713 non-zero, 714 715 [ x x x x ] 716 [ x x x 0 ] 717 [ x x 0 0 ] 718 [ x 0 0 0 ] 719 720 is_satriu() 721 Returns 1 is the invocand is strictly upper anti-triangular, and 0 722 otherwise. 723 724 $bool = $x -> is_satriu(); 725 726 A strictly anti-triangular matrix is a square matrix where all 727 non-zero elements are strictly above the main diagonal. It has the 728 following pattern, where only the elements marked as "x" can be 729 non-zero, 730 731 [ x x x 0 ] 732 [ x x 0 0 ] 733 [ x 0 0 0 ] 734 [ 0 0 0 0 ] 735 736 is_atril() 737 Returns 1 is the invocand is lower anti-triangular, and 0 otherwise. 738 739 $bool = $x -> is_atril(); 740 741 A lower anti-triangular matrix is a square matrix where all non-zero 742 elements are on or below the main anti-diagonal. It has the 743 following pattern, where only the elements marked as "x" can be 744 non-zero, 745 746 [ 0 0 0 x ] 747 [ 0 0 x x ] 748 [ 0 x x x ] 749 [ x x x x ] 750 751 is_satril() 752 Returns 1 is the invocand is strictly lower anti-triangular, and 0 753 otherwise. 754 755 $bool = $x -> is_satril(); 756 757 A strictly lower anti-triangular matrix is a square matrix where all 758 non-zero elements are strictly below the main anti-diagonal. It has 759 the following pattern, where only the elements marked as "x" can be 760 non-zero, 761 762 [ 0 0 0 0 ] 763 [ 0 0 0 x ] 764 [ 0 0 x x ] 765 [ 0 x x x ] 766 767 Identify elements 768 This section contains methods for identifying and locating elements 769 within an array. See also "Scalar comparison". 770 771 find() 772 Returns the location of each non-zero element. 773 774 $K = $x -> find(); # linear index 775 ($I, $J) = $x -> find(); # subscripts 776 777 For example, to find the linear index of each element that is 778 greater than or equal to 1, use 779 780 $K = $x -> sge(1) -> find(); 781 782 is_finite() 783 Returns a matrix of ones and zeros. The element is one if the 784 corresponding element in the invocand matrix is finite, and zero 785 otherwise. 786 787 $y = $x -> is_finite(); 788 789 is_inf() 790 Returns a matrix of ones and zeros. The element is one if the 791 corresponding element in the invocand matrix is positive or negative 792 infinity, and zero otherwise. 793 794 $y = $x -> is_inf(); 795 796 is_nan() 797 Returns a matrix of ones and zeros. The element is one if the 798 corresponding element in the invocand matrix is a NaN 799 (Not-a-Number), and zero otherwise. 800 801 $y = $x -> is_nan(); 802 803 all() 804 Tests whether all of the elements along various dimensions of a 805 matrix are non-zero. If the dimension argument is not given, the 806 first non-singleton dimension is used. 807 808 $y = $x -> all($dim); 809 $y = $x -> all(); 810 811 any() 812 Tests whether any of the elements along various dimensions of a 813 matrix are non-zero. If the dimension argument is not given, the 814 first non-singleton dimension is used. 815 816 $y = $x -> any($dim); 817 $y = $x -> any(); 818 819 cumall() 820 A cumulative variant of "all()". If the dimension argument is not 821 given, the first non-singleton dimension is used. 822 823 $y = $x -> cumall($dim); 824 $y = $x -> cumall(); 825 826 cumany() 827 A cumulative variant of "all()". If the dimension argument is not 828 given, the first non-singleton dimension is used. 829 830 $y = $x -> cumany($dim); 831 $y = $x -> cumany(); 832 833 Basic properties 834 size() 835 You can determine the dimensions of a matrix by calling: 836 837 ($m, $n) = $a -> size; 838 839 nelm() 840 Returns the number of elements in the matrix. 841 842 $n = $x -> nelm(); 843 844 nrow() 845 Returns the number of rows. 846 847 $m = $x -> nrow(); 848 849 ncol() 850 Returns the number of columns. 851 852 $n = $x -> ncol(); 853 854 npag() 855 Returns the number of pages. A non-matrix has one page. 856 857 $n = $x -> pag(); 858 859 ndim() 860 Returns the number of dimensions. This is the number of dimensions 861 along which the length is different from one. 862 863 $n = $x -> ndim(); 864 865 bandwidth() 866 Returns the bandwidth of a matrix. In scalar context, returns the 867 number of the non-zero diagonal furthest away from the main 868 diagonal. In list context, separate values are returned for the 869 lower and upper bandwidth. 870 871 $n = $x -> bandwidth(); 872 ($l, $u) = $x -> bandwidth(); 873 874 The bandwidth is a non-negative integer. If the bandwidth is 0, the 875 matrix is diagonal or zero. If the bandwidth is 1, the matrix is 876 tridiagonal. If the bandwidth is 2, the matrix is pentadiagonal etc. 877 878 A matrix with the following pattern, where "x" denotes a non-zero 879 value, would return 2 in scalar context, and (1,2) in list context. 880 881 [ x x x 0 0 0 ] 882 [ x x x x 0 0 ] 883 [ 0 x x x x 0 ] 884 [ 0 0 x x x x ] 885 [ 0 0 0 x x x ] 886 [ 0 0 0 0 x x ] 887 888 See also "is_band()" and "is_aband()". 889 890 Manipulate matrices 891 These methods are for combining matrices, splitting matrices, extracing 892 parts of a matrix, inserting new parts into a matrix, deleting parts of 893 a matrix etc. There are also methods for shuffling elements around 894 (relocating elements) inside a matrix. 895 896 These methods are not concerned with the values of the elements. 897 898 catrow() 899 Concatenate rows, i.e., concatenate matrices vertically. Any number 900 of arguments is allowed. All non-empty matrices must have the same 901 number or columns. The result is a new matrix. 902 903 $x = Math::Matrix -> new([1, 2], [4, 5]); # 2-by-2 matrix 904 $y = Math::Matrix -> new([3, 6]); # 1-by-2 matrix 905 $z = $x -> catrow($y); # 3-by-2 matrix 906 907 catcol() 908 Concatenate columns, i.e., matrices horizontally. Any number of 909 arguments is allowed. All non-empty matrices must have the same 910 number or rows. The result is a new matrix. 911 912 $x = Math::Matrix -> new([1, 2], [4, 5]); # 2-by-2 matrix 913 $y = Math::Matrix -> new([3], [6]); # 2-by-1 matrix 914 $z = $x -> catcol($y); # 2-by-3 matrix 915 916 getrow() 917 Get the specified row(s). Returns a new matrix with the specified 918 rows. The number of rows in the output is identical to the number of 919 elements in the input. 920 921 $y = $x -> getrow($i); # get one 922 $y = $x -> getrow([$i0, $i1, $i2]); # get multiple 923 924 getcol() 925 Get the specified column(s). Returns a new matrix with the specified 926 columns. The number of columns in the output is identical to the 927 number of elements in the input. 928 929 $y = $x -> getcol($j); # get one 930 $y = $x -> getcol([$j0, $j1, $j2]); # get multiple 931 932 delrow() 933 Delete row(s). Returns a new matrix identical to the invocand but 934 with the specified row(s) deleted. 935 936 $y = $x -> delrow($i); # delete one 937 $y = $x -> delrow([$i0, $i1, $i2]); # delete multiple 938 939 delcol() 940 Delete column(s). Returns a new matrix identical to the invocand but 941 with the specified column(s) deleted. 942 943 $y = $x -> delcol($j); # delete one 944 $y = $x -> delcol([$j0, $j1, $j2]); # delete multiple 945 946 concat() 947 Concatenate two matrices horizontally. The matrices must have the 948 same number of rows. The result is a new matrix or undef in case of 949 error. 950 951 $x = Math::Matrix -> new([1, 2], [4, 5]); # 2-by-2 matrix 952 $y = Math::Matrix -> new([3], [6]); # 2-by-1 matrix 953 $z = $x -> concat($y); # 2-by-3 matrix 954 955 splicerow() 956 Row splicing. This is like Perl's built-in splice() function, except 957 that it works on the rows of a matrix. 958 959 $y = $x -> splicerow($offset); 960 $y = $x -> splicerow($offset, $length); 961 $y = $x -> splicerow($offset, $length, $a, $b, ...); 962 963 The built-in splice() function modifies the first argument and 964 returns the removed elements, if any. However, since splicerow() 965 does not modify the invocand, it returns the modified version as the 966 first output argument and the removed part as a (possibly empty) 967 second output argument. 968 969 $x = Math::Matrix -> new([[ 1, 2], 970 [ 3, 4], 971 [ 5, 6], 972 [ 7, 8]]); 973 $a = Math::Matrix -> new([[11, 12], 974 [13, 14]]); 975 ($y, $z) = $x -> splicerow(1, 2, $a); 976 977 Gives $y 978 979 [ 1 2 ] 980 [ 11 12 ] 981 [ 13 14 ] 982 [ 7 8 ] 983 984 and $z 985 986 [ 3 4 ] 987 [ 5 6 ] 988 989 splicecol() 990 Column splicing. This is like Perl's built-in splice() function, 991 except that it works on the columns of a matrix. 992 993 $y = $x -> splicecol($offset); 994 $y = $x -> splicecol($offset, $length); 995 $y = $x -> splicecol($offset, $length, $a, $b, ...); 996 997 The built-in splice() function modifies the first argument and 998 returns the removed elements, if any. However, since splicecol() 999 does not modify the invocand, it returns the modified version as the 1000 first output argument and the removed part as a (possibly empty) 1001 second output argument. 1002 1003 $x = Math::Matrix -> new([[ 1, 3, 5, 7 ], 1004 [ 2, 4, 6, 8 ]]); 1005 $a = Math::Matrix -> new([[11, 13], 1006 [12, 14]]); 1007 ($y, $z) = $x -> splicerow(1, 2, $a); 1008 1009 Gives $y 1010 1011 [ 1 11 13 7 ] 1012 [ 2 12 14 8 ] 1013 1014 and $z 1015 1016 [ 3 5 ] 1017 [ 4 6 ] 1018 1019 swaprc() 1020 Swap rows and columns. This method does nothing but shuffle elements 1021 around. For real numbers, swaprc() is identical to the transpose() 1022 method. 1023 1024 A subclass implementing a matrix of complex numbers should provide a 1025 transpose() method that also takes the complex conjugate of each 1026 elements. The swaprc() method, on the other hand, should only 1027 shuffle elements around. 1028 1029 flipud() 1030 Flip upside-down, i.e., flip along dimension 1. 1031 1032 $y = $x -> flipud(); 1033 1034 fliplr() 1035 Flip left-to-right, i.e., flip along dimension 2. 1036 1037 $y = $x -> fliplr(); 1038 1039 flip() 1040 Flip along various dimensions of a matrix. If the dimension argument 1041 is not given, the first non-singleton dimension is used. 1042 1043 $y = $x -> flip($dim); 1044 $y = $x -> flip(); 1045 1046 See also "flipud()" and "fliplr()". 1047 1048 rot90() 1049 Rotate 90 degrees counterclockwise. 1050 1051 $y = $x -> rot90(); # rotate 90 degrees counterclockwise 1052 $y = $x -> rot90($n); # rotate 90*$n degrees counterclockwise 1053 1054 rot180() 1055 Rotate 180 degrees. 1056 1057 $y = $x -> rot180(); 1058 1059 rot270() 1060 Rotate 270 degrees counterclockwise, i.e., 90 degrees clockwise. 1061 1062 $y = $x -> rot270(); 1063 1064 repelm() 1065 Repeat elements. 1066 1067 $x -> repelm($y); 1068 1069 Repeats each element in $x the number of times specified in $y. 1070 1071 If $x is the matrix 1072 1073 [ 4 5 6 ] 1074 [ 7 8 9 ] 1075 1076 and $y is 1077 1078 [ 3 2 ] 1079 1080 the returned matrix is 1081 1082 [ 4 4 5 5 6 6 ] 1083 [ 4 4 5 5 6 6 ] 1084 [ 4 4 5 5 6 6 ] 1085 [ 7 7 8 8 9 9 ] 1086 [ 7 7 8 8 9 9 ] 1087 [ 7 7 8 8 9 9 ] 1088 1089 repmat() 1090 Repeat elements. 1091 1092 $x -> repmat($y); 1093 1094 Repeats the matrix $x the number of times specified in $y. 1095 1096 If $x is the matrix 1097 1098 [ 4 5 6 ] 1099 [ 7 8 9 ] 1100 1101 and $y is 1102 1103 [ 3 2 ] 1104 1105 the returned matrix is 1106 1107 [ 4 5 6 4 5 6 ] 1108 [ 7 8 9 7 8 9 ] 1109 [ 4 5 6 4 5 6 ] 1110 [ 7 8 9 7 8 9 ] 1111 [ 4 5 6 4 5 6 ] 1112 [ 7 8 9 7 8 9 ] 1113 1114 reshape() 1115 Returns a reshaped copy of a matrix. The reshaping is done by 1116 creating a new matrix and looping over the elements in column major 1117 order. The new matrix must have the same number of elements as the 1118 invocand matrix. The following returns an $m-by-$n matrix, 1119 1120 $y = $x -> reshape($m, $n); 1121 1122 The code 1123 1124 $x = Math::Matrix -> new([[1, 3, 5, 7], [2, 4, 6, 8]]); 1125 $y = $x -> reshape(4, 2); 1126 1127 creates the matrix $x 1128 1129 [ 1 3 5 7 ] 1130 [ 2 4 6 8 ] 1131 1132 and returns a reshaped copy $y 1133 1134 [ 1 5 ] 1135 [ 2 6 ] 1136 [ 3 7 ] 1137 [ 4 8 ] 1138 1139 to_row() 1140 Reshape to a row. 1141 1142 $x -> to_row(); 1143 1144 This method reshapes the matrix into a single row. It is essentially 1145 the same as, but faster than, 1146 1147 $x -> reshape(1, $x -> nelm()); 1148 1149 to_col() 1150 Reshape to a column. 1151 1152 $y = $x -> to_col(); 1153 1154 This method reshapes the matrix into a single column. It is 1155 essentially the same as, but faster than, 1156 1157 $x -> reshape($x -> nelm(), 1); 1158 1159 to_permmat() 1160 Permutation vector to permutation matrix. Converts a vector of 1161 zero-based permutation indices to a permutation matrix. 1162 1163 $P = $v -> to_permmat(); 1164 1165 For example 1166 1167 $v = Math::Matrix -> new([[0, 3, 1, 4, 2]]); 1168 $m = $v -> to_permmat(); 1169 1170 gives the permutation matrix $m 1171 1172 [ 1 0 0 0 0 ] 1173 [ 0 0 0 1 0 ] 1174 [ 0 1 0 0 0 ] 1175 [ 0 0 0 0 1 ] 1176 [ 0 0 1 0 0 ] 1177 1178 to_permvec() 1179 Permutation matrix to permutation vector. Converts a permutation 1180 matrix to a vector of zero-based permutation indices. 1181 1182 $v = $P -> to_permvec(); 1183 1184 $v = Math::Matrix -> new([[0, 3, 1, 4, 2]]); 1185 $m = $v -> to_permmat(); 1186 1187 Gives the permutation matrix $m 1188 1189 [ 1 0 0 0 0 ] 1190 [ 0 0 0 1 0 ] 1191 [ 0 1 0 0 0 ] 1192 [ 0 0 0 0 1 ] 1193 [ 0 0 1 0 0 ] 1194 1195 See also "to_permmat()". 1196 1197 triu() 1198 Upper triangular part. Extract the upper triangular part of a matrix 1199 and set all other elements to zero. 1200 1201 $y = $x -> triu(); 1202 $y = $x -> triu($n); 1203 1204 The optional second argument specifies how many diagonals above or 1205 below the main diagonal should also be set to zero. The default 1206 value of $n is zero which includes the main diagonal. 1207 1208 tril() 1209 Lower triangular part. Extract the lower triangular part of a matrix 1210 and set all other elements to zero. 1211 1212 $y = $x -> tril(); 1213 $y = $x -> tril($n); 1214 1215 The optional second argument specifies how many diagonals above or 1216 below the main diagonal should also be set to zero. The default 1217 value of $n is zero which includes the main diagonal. 1218 1219 slice() 1220 Extract columns: 1221 1222 a->slice(1,3,5); 1223 1224 diagonal_vector() 1225 Extract the diagonal as an array: 1226 1227 $diag = $a->diagonal_vector; 1228 1229 tridiagonal_vector() 1230 Extract the diagonals that make up a tridiagonal matrix: 1231 1232 ($main_d, $upper_d, $lower_d) = $a->tridiagonal_vector; 1233 1234 Mathematical functions 1235 Addition 1236 add() 1237 Addition. If one operands is a scalar, it is treated like a constant 1238 matrix with the same size as the other operand. Otherwise ordinary 1239 matrix addition is performed. 1240 1241 $z = $x -> add($y); 1242 1243 See also "madd()" and "sadd()". 1244 1245 madd() 1246 Matrix addition. Add two matrices of the same dimensions. An error 1247 is thrown if the matrices don't have the same size. 1248 1249 $z = $x -> madd($y); 1250 1251 See also "add()" and "sadd()". 1252 1253 sadd() 1254 Scalar (element by element) addition with scalar expansion. This 1255 method places no requirements on the size of the input matrices. 1256 1257 $z = $x -> sadd($y); 1258 1259 See also "add()" and "madd()". 1260 1261 Subtraction 1262 sub() 1263 Subtraction. If one operands is a scalar, it is treated as a 1264 constant matrix with the same size as the other operand. Otherwise, 1265 ordinarly matrix subtraction is performed. 1266 1267 $z = $x -> sub($y); 1268 1269 See also "msub()" and "ssub()". 1270 1271 msub() 1272 Matrix subtraction. Subtract two matrices of the same size. An error 1273 is thrown if the matrices don't have the same size. 1274 1275 $z = $x -> msub($y); 1276 1277 See also "sub()" and "ssub()". 1278 1279 ssub() 1280 Scalar (element by element) subtraction with scalar expansion. This 1281 method places no requirements on the size of the input matrices. 1282 1283 $z = $x -> ssub($y); 1284 1285 See also "sub()" and "msub()". 1286 1287 subtract() 1288 This is an alias for "msub()". 1289 1290 Negation 1291 neg() 1292 Negation. Negate a matrix. 1293 1294 $y = $x -> neg(); 1295 1296 It is effectively equivalent to 1297 1298 $y = $x -> map(sub { -$_ }); 1299 1300 negative() 1301 This is an alias for "neg()". 1302 1303 Multiplication 1304 mul() 1305 Multiplication. If one operands is a scalar, it is treated as a 1306 constant matrix with the same size as the other operand. Otherwise, 1307 ordinary matrix multiplication is performed. 1308 1309 $z = $x -> mul($y); 1310 1311 mmul() 1312 Matrix multiplication. An error is thrown if the sizes don't match; 1313 the number of columns in the first operand must be equal to the 1314 number of rows in the second operand. 1315 1316 $z = $x -> mmul($y); 1317 1318 smul() 1319 Scalar (element by element) multiplication with scalar expansion. 1320 This method places no requirements on the size of the input 1321 matrices. 1322 1323 $z = $x -> smul($y); 1324 1325 mmuladd() 1326 Matrix fused multiply and add. If $x is a $p-by-$q matrix, then $y 1327 must be a $q-by-$r matrix and $z must be a $p-by-$r matrix. An error 1328 is thrown if the sizes don't match. 1329 1330 $w = $x -> mmuladd($y, $z); 1331 1332 The fused multiply and add is equivalent to, but computed with 1333 higher accuracy than 1334 1335 $w = $x -> mmul($y) -> madd($z); 1336 1337 This method can be used to improve the solution of linear systems. 1338 1339 kron() 1340 Kronecker tensor product. 1341 1342 $A -> kronprod($B); 1343 1344 If $A is an $m-by-$n matrix and $B is a $p-by-$q matrix, then "$A -> 1345 kron($B)" is an $m*$p-by-$n*$q matrix formed by taking all possible 1346 products between the elements of $A and the elements of $B. 1347 1348 multiply() 1349 This is an alias for "mmul()". 1350 1351 multiply_scalar() 1352 Multiplies a matrix and a scalar resulting in a matrix of the same 1353 dimensions with each element scaled with the scalar. 1354 1355 $a->multiply_scalar(2); scale matrix by factor 2 1356 1357 Powers 1358 pow() 1359 Power function. 1360 1361 This is an alias for "mpow()". 1362 1363 See also "spow()". 1364 1365 mpow() 1366 Matrix power. The second operand must be a non-negative integer. 1367 1368 $y = $x -> mpow($n); 1369 1370 The following example 1371 1372 $x = Math::Matrix -> new([[0, -2],[1, 4]]); 1373 $y = 4; 1374 $z = $x -> pow($y); 1375 1376 returns the matrix 1377 1378 [ -28 -96 ] 1379 [ 48 164 ] 1380 1381 See also "spow()". 1382 1383 spow() 1384 Scalar (element by element) power function. This method doesn't 1385 require the matrices to have the same size. 1386 1387 $z = $x -> spow($y); 1388 1389 See also "mpow()". 1390 1391 Inversion 1392 inv() 1393 This is an alias for "minv()". 1394 1395 invert() 1396 Invert a Matrix using "solve". 1397 1398 minv() 1399 Matrix inverse. Invert a matrix. 1400 1401 $y = $x -> inv(); 1402 1403 See the section "IMPROVING THE SOLUTION OF LINEAR SYSTEMS" for a 1404 list of additional parameters that can be used for trying to obtain 1405 a better solution through iteration. 1406 1407 sinv() 1408 Scalar (element by element) inverse. Invert each element in a 1409 matrix. 1410 1411 $y = $x -> sinv(); 1412 1413 mldiv() 1414 Matrix left division. Returns the solution x of the linear system of 1415 equations A*x = y, by computing A^(-1)*y. 1416 1417 $x = $y -> mldiv($A); 1418 1419 This method also handles overdetermined and underdetermined systems. 1420 There are three cases 1421 1422 * If A is a square matrix, then 1423 1424 x = A\y = inv(A)*y 1425 1426 so that A*x = y to within round-off accuracy. 1427 1428 * If A is an M-by-N matrix where M > N, then A\y is computed as 1429 1430 A\y = (A'*A)\(A'*y) = inv(A'*A)*(A'*y) 1431 1432 where A' denotes the transpose of A. The returned matrix is the 1433 least squares solution to the linear system of equations A*x = 1434 y, if it exists. The matrix A'*A must be non-singular. 1435 1436 * If A is an where M < N, then A\y is computed as 1437 1438 A\y = A'*((A*A')\y) 1439 1440 This solution is not unique. The matrix A*A' must be 1441 non-singular. 1442 1443 See the section "IMPROVING THE SOLUTION OF LINEAR SYSTEMS" for a 1444 list of additional parameters that can be used for trying to obtain 1445 a better solution through iteration. 1446 1447 sldiv() 1448 Scalar (left) division. 1449 1450 $x -> sldiv($y); 1451 1452 For scalars, there is no difference between left and right division, 1453 so this is just an alias for "sdiv()". 1454 1455 mrdiv() 1456 Matrix right division. Returns the solution x of the linear system 1457 of equations x*A = y, by computing x = y/A = y*inv(A) = (A'\y')', 1458 where A' and y' denote the transpose of A and y, respectively, and \ 1459 is matrix left division (see "mldiv()"). 1460 1461 $x = $y -> mrdiv($A); 1462 1463 See the section "IMPROVING THE SOLUTION OF LINEAR SYSTEMS" for a 1464 list of additional parameters that can be used for trying to obtain 1465 a better solution through iteration. 1466 1467 srdiv() 1468 Scalar (right) division. 1469 1470 $x -> srdiv($y); 1471 1472 For scalars, there is no difference between left and right division, 1473 so this is just an alias for "sdiv()". 1474 1475 sdiv() 1476 Scalar division. Performs scalar (element by element) division. 1477 1478 $x -> sdiv($y); 1479 1480 mpinv() 1481 Matrix pseudo-inverse, "(A'*A)^(-1)*A'", where ""'"" is the 1482 transpose operator. 1483 1484 See the section "IMPROVING THE SOLUTION OF LINEAR SYSTEMS" for a 1485 list of additional parameters that can be used for trying to obtain 1486 a better solution through iteration. 1487 1488 pinv() 1489 This is an alias for "mpinv()". 1490 1491 pinvert() 1492 This is an alias for "mpinv()". 1493 1494 solve() 1495 Solves a equation system given by the matrix. The number of colums 1496 must be greater than the number of rows. If variables are dependent 1497 from each other, the second and all further of the dependent 1498 coefficients are 0. This means the method can handle such systems. 1499 The method returns a matrix containing the solutions in its columns 1500 or undef in case of error. 1501 1502 Factorisation 1503 chol() 1504 Cholesky decomposition. 1505 1506 $L = $A -> chol(); 1507 1508 Every symmetric, positive definite matrix A can be decomposed into a 1509 product of a unique lower triangular matrix L and its transpose, so 1510 that A = L*L', where L' denotes the transpose of L. L is called the 1511 Cholesky factor of A. 1512 1513 Miscellaneous matrix functions 1514 transpose() 1515 Returns the transposed matrix. This is the matrix where colums and 1516 rows of the argument matrix are swapped. 1517 1518 A subclass implementing matrices of complex numbers should provide a 1519 "transpose()" method that takes the complex conjugate of each 1520 element. 1521 1522 minormatrix() 1523 Minor matrix. The (i,j) minor matrix of a matrix is identical to the 1524 original matrix except that row i and column j has been removed. 1525 1526 $y = $x -> minormatrix($i, $j); 1527 1528 See also "minor()". 1529 1530 minor() 1531 Minor. The (i,j) minor of a matrix is the determinant of the (i,j) 1532 minor matrix. 1533 1534 $y = $x -> minor($i, $j); 1535 1536 See also "minormatrix()". 1537 1538 cofactormatrix() 1539 Cofactor matrix. Element (i,j) in the cofactor matrix is the (i,j) 1540 cofactor, which is (-1)^(i+j) multiplied by the determinant of the 1541 (i,j) minor matrix. 1542 1543 $y = $x -> cofactormatrix(); 1544 1545 cofactor() 1546 Cofactor. The (i,j) cofactor of a matrix is (-1)**(i+j) times the 1547 (i,j) minor of the matrix. 1548 1549 $y = $x -> cofactor($i, $j); 1550 1551 adjugate() 1552 Adjugate of a matrix. The adjugate, also called classical adjoint or 1553 adjunct, of a square matrix is the transpose of the cofactor matrix. 1554 1555 $y = $x -> adjugate(); 1556 1557 det() 1558 Determinant. Returns the determinant of a matrix. The matrix must be 1559 square. 1560 1561 $y = $x -> det(); 1562 1563 The matrix is computed by forward elimination, which might cause 1564 round-off errors. So for example, the determinant might be a 1565 non-integer even for an integer matrix. 1566 1567 determinant() 1568 This is an alias for "det()". 1569 1570 detr() 1571 Determinant. Returns the determinant of a matrix. The matrix must be 1572 square. 1573 1574 $y = $x -> determinant(); 1575 1576 The determinant is computed by recursion, so it is generally much 1577 slower than "det()". 1578 1579 Elementwise mathematical functions 1580 These method work on each element of a matrix. 1581 1582 int() 1583 Truncate to integer. Truncates each element to an integer. 1584 1585 $y = $x -> int(); 1586 1587 This function is effectivly the same as 1588 1589 $y = $x -> map(sub { int }); 1590 1591 floor() 1592 Round to negative infinity. Rounds each element to negative 1593 infinity. 1594 1595 $y = $x -> floor(); 1596 1597 ceil() 1598 Round to positive infinity. Rounds each element to positive 1599 infinity. 1600 1601 $y = $x -> int(); 1602 1603 abs() 1604 Absolute value. The absolute value of each element. 1605 1606 $y = $x -> abs(); 1607 1608 This is effectivly the same as 1609 1610 $y = $x -> map(sub { abs }); 1611 1612 sign() 1613 Sign function. Apply the sign function to each element. 1614 1615 $y = $x -> sign(); 1616 1617 This is effectivly the same as 1618 1619 $y = $x -> map(sub { $_ <=> 0 }); 1620 1621 Columnwise or rowwise mathematical functions 1622 These method work along each column or row of a matrix. Some of these 1623 methods return a matrix with the same size as the invocand matrix. Other 1624 methods collapse the dimension, so that, e.g., if the method is applied 1625 to the first dimension a *p*-by-*q* matrix becomes a 1-by-*q* matrix, 1626 and if applied to the second dimension, it becomes a *p*-by-1 matrix. 1627 Others, like "diff()", reduces the length along the dimension by one, so 1628 a *p*-by-*q* matrix becomes a (*p*-1)-by-*q* or a *p*-by-(*q*-1) matrix. 1629 1630 sum() 1631 Sum of elements along various dimensions of a matrix. If the 1632 dimension argument is not given, the first non-singleton dimension 1633 is used. 1634 1635 $y = $x -> sum($dim); 1636 $y = $x -> sum(); 1637 1638 prod() 1639 Product of elements along various dimensions of a matrix. If the 1640 dimension argument is not given, the first non-singleton dimension 1641 is used. 1642 1643 $y = $x -> prod($dim); 1644 $y = $x -> prod(); 1645 1646 mean() 1647 Mean of elements along various dimensions of a matrix. If the 1648 dimension argument is not given, the first non-singleton dimension 1649 is used. 1650 1651 $y = $x -> mean($dim); 1652 $y = $x -> mean(); 1653 1654 hypot() 1655 Hypotenuse. Computes the square root of the sum of the square of 1656 each element along various dimensions of a matrix. If the dimension 1657 argument is not given, the first non-singleton dimension is used. 1658 1659 $y = $x -> hypot($dim); 1660 $y = $x -> hypot(); 1661 1662 For example, 1663 1664 $x = Math::Matrix -> new([[3, 4], 1665 [5, 12]]); 1666 $y = $x -> hypot(2); 1667 1668 returns the 2-by-1 matrix 1669 1670 [ 5 ] 1671 [ 13 ] 1672 1673 min() 1674 Minimum of elements along various dimensions of a matrix. If the 1675 dimension argument is not given, the first non-singleton dimension 1676 is used. 1677 1678 $y = $x -> min($dim); 1679 $y = $x -> min(); 1680 1681 max() 1682 Maximum of elements along various dimensions of a matrix. If the 1683 dimension argument is not given, the first non-singleton dimension 1684 is used. 1685 1686 $y = $x -> max($dim); 1687 $y = $x -> max(); 1688 1689 median() 1690 Median of elements along various dimensions of a matrix. If the 1691 dimension argument is not given, the first non-singleton dimension 1692 is used. 1693 1694 $y = $x -> median($dim); 1695 $y = $x -> median(); 1696 1697 cumsum() 1698 Returns the cumulative sum along various dimensions of a matrix. If 1699 the dimension argument is not given, the first non-singleton 1700 dimension is used. 1701 1702 $y = $x -> cumsum($dim); 1703 $y = $x -> cumsum(); 1704 1705 cumprod() 1706 Returns the cumulative product along various dimensions of a matrix. 1707 If the dimension argument is not given, the first non-singleton 1708 dimension is used. 1709 1710 $y = $x -> cumprod($dim); 1711 $y = $x -> cumprod(); 1712 1713 cummean() 1714 Returns the cumulative mean along various dimensions of a matrix. If 1715 the dimension argument is not given, the first non-singleton 1716 dimension is used. 1717 1718 $y = $x -> cummean($dim); 1719 $y = $x -> cummean(); 1720 1721 diff() 1722 Returns the differences between adjacent elements. If the dimension 1723 argument is not given, the first non-singleton dimension is used. 1724 1725 $y = $x -> diff($dim); 1726 $y = $x -> diff(); 1727 1728 vecnorm() 1729 Return the $p-norm of the elements of $x. If the dimension argument 1730 is not given, the first non-singleton dimension is used. 1731 1732 $y = $x -> vecnorm($p, $dim); 1733 $y = $x -> vecnorm($p); 1734 $y = $x -> vecnorm(); 1735 1736 The $p-norm of a vector is defined as the $pth root of the sum of 1737 the absolute values fo the elements raised to the $pth power. 1738 1739 apply() 1740 Applies a subroutine to each row or column of a matrix. If the 1741 dimension argument is not given, the first non-singleton dimension 1742 is used. 1743 1744 $y = $x -> apply($sub, $dim); 1745 $y = $x -> apply($sub); 1746 1747 The subroutine is passed a list with all elements in a single column 1748 or row. 1749 1750 Comparison 1751 Matrix comparison 1752 Methods matrix comparison. These methods return a scalar value. 1753 1754 meq() 1755 Matrix equal to. Returns 1 if two matrices are identical and 0 1756 otherwise. 1757 1758 $bool = $x -> meq($y); 1759 1760 mne() 1761 Matrix not equal to. Returns 1 if two matrices are different and 0 1762 otherwise. 1763 1764 $bool = $x -> mne($y); 1765 1766 equal() 1767 Decide if two matrices are equal. The criterion is, that each pair 1768 of elements differs less than $Math::Matrix::eps. 1769 1770 $bool = $x -> equal($y); 1771 1772 Scalar comparison 1773 Each of these methods performs scalar (element by element) comparison 1774 and returns a matrix of ones and zeros. Scalar expansion is performed if 1775 necessary. 1776 1777 seq() 1778 Scalar equality. Performs scalar (element by element) comparison of 1779 two matrices. 1780 1781 $bool = $x -> seq($y); 1782 1783 sne() 1784 Scalar (element by element) not equal to. Performs scalar (element 1785 by element) comparison of two matrices. 1786 1787 $bool = $x -> sne($y); 1788 1789 slt() 1790 Scalar (element by element) less than. Performs scalar (element by 1791 element) comparison of two matrices. 1792 1793 $bool = $x -> slt($y); 1794 1795 sle() 1796 Scalar (element by element) less than or equal to. Performs scalar 1797 (element by element) comparison of two matrices. 1798 1799 $bool = $x -> sle($y); 1800 1801 sgt() 1802 Scalar (element by element) greater than. Performs scalar (element 1803 by element) comparison of two matrices. 1804 1805 $bool = $x -> sgt($y); 1806 1807 sge() 1808 Scalar (element by element) greater than or equal to. Performs 1809 scalar (element by element) comparison of two matrices. 1810 1811 $bool = $x -> sge($y); 1812 1813 scmp() 1814 Scalar (element by element) comparison. Performs scalar (element by 1815 element) comparison of two matrices. Each element in the output 1816 matrix is either -1, 0, or 1 depending on whether the elements are 1817 less than, equal to, or greater than each other. 1818 1819 $bool = $x -> scmp($y); 1820 1821 Vector functions 1822 dot_product() 1823 Compute the dot product of two vectors. The second operand does not 1824 have to be an object. 1825 1826 # $x and $y are both objects 1827 $x = Math::Matrix -> new([1, 2, 3]); 1828 $y = Math::Matrix -> new([4, 5, 6]); 1829 $p = $x -> dot_product($y); # $p = 32 1830 1831 # Only $x is an object. 1832 $p = $x -> dot_product([4, 5, 6]); # $p = 32 1833 1834 outer_product() 1835 Compute the outer product of two vectors. The second operand does 1836 not have to be an object. 1837 1838 # $x and $y are both objects 1839 $x = Math::Matrix -> new([1, 2, 3]); 1840 $y = Math::Matrix -> new([4, 5, 6, 7]); 1841 $p = $x -> outer_product($y); 1842 1843 # Only $x is an object. 1844 $p = $x -> outer_product([4, 5, 6, y]); 1845 1846 absolute() 1847 Compute the absolute value (i.e., length) of a vector. 1848 1849 $v = Math::Matrix -> new([3, 4]); 1850 $a = $v -> absolute(); # $v = 5 1851 1852 normalize() 1853 Normalize a vector, i.e., scale a vector so its length becomes 1. 1854 1855 $v = Math::Matrix -> new([3, 4]); 1856 $u = $v -> normalize(); # $u = [ 0.6, 0.8 ] 1857 1858 cross_product() 1859 Compute the cross-product of vectors. 1860 1861 $x = Math::Matrix -> new([1,3,2], 1862 [5,4,2]); 1863 $p = $x -> cross_product(); # $p = [ -2, 8, -11 ] 1864 1865 Conversion 1866 as_string() 1867 Creates a string representation of the matrix and returns it. 1868 1869 $x = Math::Matrix -> new([1, 2], [3, 4]); 1870 $s = $x -> as_string(); 1871 1872 as_array() 1873 Returns the matrix as an unblessed Perl array, i.e., and ordinary, 1874 unblessed reference. 1875 1876 $y = $x -> as_array(); # ref($y) returns 'ARRAY' 1877 1878 Matrix utilities 1879 Apply a subroutine to each element 1880 map() 1881 Call a subroutine for every element of a matrix, locally setting $_ 1882 to each element and passing the matrix row and column indices as 1883 input arguments. 1884 1885 # square each element 1886 $y = $x -> map(sub { $_ ** 2 }); 1887 1888 # set strictly lower triangular part to zero 1889 $y = $x -> map(sub { $_[0] > $_[1] ? 0 : $_ })' 1890 1891 sapply() 1892 Applies a subroutine to each element of a matrix, or each set of 1893 corresponding elements if multiple matrices are given, and returns 1894 the result. The first argument is the subroutine to apply. The 1895 following arguments, if any, are additional matrices on which to 1896 apply the subroutine. 1897 1898 $w = $x -> sapply($sub); # single operand 1899 $w = $x -> sapply($sub, $y); # two operands 1900 $w = $x -> sapply($sub, $y, $z); # three operands 1901 1902 Each matrix element, or corresponding set of elements, are passed to 1903 the subroutine as input arguments. 1904 1905 When used with a single operand, this method is similar to the 1906 "map()" method, the syntax is different, since "sapply()" supports 1907 multiple operands. 1908 1909 See also "map()". 1910 1911 * The subroutine is run in scalar context. 1912 1913 * No checks are done on the return value of the subroutine. 1914 1915 * The number of rows in the output matrix equals the number of 1916 rows in the operand with the largest number of rows. Ditto for 1917 columns. So if $x is 5-by-2 matrix, and $y is a 3-by-4 matrix, 1918 the result is a 5-by-4 matrix. 1919 1920 * For each operand that has a number of rows smaller than the 1921 maximum value, the rows are recyled. Ditto for columns. 1922 1923 * Don't modify the variables $_[0], $_[1] etc. inside the 1924 subroutine. Otherwise, there is a risk of modifying the operand 1925 matrices. 1926 1927 * If the matrix elements are objects that are not cloned when the 1928 "=" (assignment) operator is used, you might have to explicitly 1929 clone the objects used inside the subroutine. Otherwise, the 1930 elements in the output matrix might be references to objects in 1931 the operand matrices, rather than references to new objects. 1932 1933 Some examples 1934 1935 One operand 1936 With one operand, i.e., the invocand matrix, the subroutine is 1937 applied to each element of the invocand matrix. The returned 1938 matrix has the same size as the invocand. For example, 1939 multiplying the matrix $x with the scalar $c 1940 1941 $sub = sub { $c * $_[0] }; # subroutine to multiply by $c 1942 $z = $x -> sapply($sub); # multiply each element by $c 1943 1944 Two operands 1945 When two operands are specfied, the subroutine is applied to 1946 each pair of corresponding elements in the two operands. For 1947 example, adding two matrices can be implemented as 1948 1949 $sub = sub { $_[0] * $_[1] }; 1950 $z = $x -> sapply($sub, $y); 1951 1952 Note that if the matrices have different sizes, the rows and/or 1953 columns of the smaller are recycled to match the size of the 1954 larger. If $x is a $p-by-$q matrix and $y is a $r-by-$s matrix, 1955 then $z is a max($p,$r)-by-max($q,$s) matrix, and 1956 1957 $z -> [$i][$j] = $sub -> ($x -> [$i % $p][$j % $q], 1958 $y -> [$i % $r][$j % $s]); 1959 1960 Because of this recycling, multiplying the matrix $x with the 1961 scalar $c (see above) can also be implemented as 1962 1963 $sub = sub { $_[0] * $_[1] }; 1964 $z = $x -> sapply($sub, $c); 1965 1966 Generating a matrix with all combinations of "$x**$y" for $x 1967 being 4, 5, and 6 and $y being 1, 2, 3, and 4 can be done with 1968 1969 $c = Math::Matrix -> new([[4], [5], [6]]); # 3-by-1 column 1970 $r = Math::Matrix -> new([[1, 2, 3, 4]]); # 1-by-4 row 1971 $x = $c -> sapply(sub { $_[0] ** $_[1] }, $r); # 3-by-4 matrix 1972 1973 Multiple operands 1974 In general, the sapply() method can have any number of 1975 arguments. For example, to compute the sum of the four matrices 1976 $x, $y, $z, and $w, 1977 1978 $sub = sub { 1979 $sum = 0; 1980 for $val (@_) { 1981 $sum += $val; 1982 }; 1983 return $sum; 1984 }; 1985 $sum = $x -> sapply($sub, $y, $z, $w); 1986 1987 Forward elimination 1988 These methods take a matrix as input, performs forward elimination, and 1989 returns a matrix where all elements below the main diagonal are zero. In 1990 list context, four additional arguments are returned: an array with the 1991 row permutations, an array with the column permutations, an integer with 1992 the number of row swaps and an integer with the number of column swaps 1993 performed during elimination. 1994 1995 The permutation vectors can be converted to permutation matrices with 1996 "to_permmat()". 1997 1998 felim_np() 1999 Perform forward elimination with no pivoting. 2000 2001 $y = $x -> felim_np(); 2002 2003 Forward elimination without pivoting may fail even when the matrix 2004 is non-singular. 2005 2006 This method is provided mostly for illustration purposes. 2007 2008 felim_tp() 2009 Perform forward elimination with trivial pivoting, a variant of 2010 partial pivoting. 2011 2012 $y = $x -> felim_tp(); 2013 2014 If A is a p-by-q matrix, and the so far remaining unreduced 2015 submatrix starts at element (i,i), the pivot element is the first 2016 element in column i that is non-zero. 2017 2018 This method is provided mostly for illustration purposes. 2019 2020 felim_pp() 2021 Perform forward elimination with (unscaled) partial pivoting. 2022 2023 $y = $x -> felim_pp(); 2024 2025 If A is a p-by-q matrix, and the so far remaining unreduced 2026 submatrix starts at element (i,i), the pivot element is the element 2027 in column i that has the largest absolute value. 2028 2029 This method is provided mostly for illustration purposes. 2030 2031 felim_sp() 2032 Perform forward elimination with scaled pivoting, a variant of 2033 partial pivoting. 2034 2035 $y = $x -> felim_sp(); 2036 2037 If A is a p-by-q matrix, and the so far remaining unreduced 2038 submatrix starts at element (i,i), the pivot element is the element 2039 in column i that has the largest absolute value relative to the 2040 other elements on the same row. 2041 2042 felim_fp() 2043 Performs forward elimination with full pivoting. 2044 2045 $y = $x -> felim_fp(); 2046 2047 The elimination is done with full pivoting, also called complete 2048 pivoting or total pivoting. If A is a p-by-q matrix, and the so far 2049 remaining unreduced submatrix starts at element (i,i), the pivot 2050 element is the element in the whole submatrix that has the largest 2051 absolute value. With full pivoting, both rows and columns might be 2052 swapped. 2053 2054 Back-substitution 2055 bsubs() 2056 Performs back-substitution. 2057 2058 $y = $x -> bsubs(); 2059 2060 The leftmost square portion of the matrix must be upper triangular. 2061 2062 Miscellaneous methods 2063 print() 2064 Prints the matrix on STDOUT. If the method has additional 2065 parameters, these are printed before the matrix is printed. 2066 2067 version() 2068 Returns a string contining the package name and version number. 2069 2070OVERLOADING 2071 The following operators are overloaded. 2072 2073 "+" and "+=" 2074 Matrix or scalar addition. Unless one or both of the operands is a 2075 scalar, both operands must have the same size. 2076 2077 $C = $A + $B; # assign $A + $B to $C 2078 $A += $B; # assign $A + $B to $A 2079 2080 Note that 2081 2082 "-" and "-=" 2083 Matrix or scalar subtraction. Unless one or both of the operands is 2084 a scalar, both operands must have the same size. 2085 2086 $C = $A + $B; # assign $A - $B to $C 2087 $A += $B; # assign $A - $B to $A 2088 2089 "*" and "*=" 2090 Matrix or scalar multiplication. Unless one or both of the operands 2091 is a scalar, the number of columns in the first operand must be 2092 equal to the number of rows in the second operand. 2093 2094 $C = $A * $B; # assign $A * $B to $C 2095 $A *= $B; # assign $A * $B to $A 2096 2097 "**" and "**=" 2098 Matrix power. The second operand must be a scalar. 2099 2100 $C = $A * $B; # assign $A ** $B to $C 2101 $A *= $B; # assign $A ** $B to $A 2102 2103 "==" 2104 Equal to. 2105 2106 $A == $B; # is $A equal to $B? 2107 2108 "!=" 2109 Not equal to. 2110 2111 $A != $B; # is $A not equal to $B? 2112 2113 "neg" 2114 Negation. 2115 2116 $B = -$A; # $B is the negative of $A 2117 2118 "~" Transpose. 2119 2120 $B = ~$A; # $B is the transpose of $A 2121 2122 "abs" 2123 Absolute value. 2124 2125 $B = abs $A; # $B contains absolute values of $A 2126 2127 "int" 2128 Truncate to integer. 2129 2130 $B = int $A; # $B contains only integers 2131 2132IMPROVING THE SOLUTION OF LINEAR SYSTEMS 2133 The methods that do an explicit or implicit matrix left division accept 2134 some additional parameters. If these parameters are specified, the 2135 matrix left division is done repeatedly in an iterative way, which often 2136 gives a better solution. 2137 2138 Background 2139 The linear system of equations 2140 2141 $A * $x = $y 2142 2143 can be solved for $x with 2144 2145 $x = $y -> mldiv($A); 2146 2147 Ideally "$A * $x" should equal $y, but due to numerical errors, this is 2148 not always the case. The following illustrates how to improve the 2149 solution $x computed above: 2150 2151 $r = $A -> mmuladd($x, -$y); # compute the residual $A*$x-$y 2152 $d = $r -> mldiv($A); # compute the delta for $x 2153 $x -= $d; # improve the solution $x 2154 2155 This procedure is repeated, and at each step, the absolute error 2156 2157 ||$A*$x - $y|| = ||$r|| 2158 2159 and the relative error 2160 2161 ||$A*$x - $y|| / ||$y|| = ||$r|| / ||$y|| 2162 2163 are computed and compared to the tolerances. Once one of the stopping 2164 criteria is satisfied, the algorithm terminates. 2165 2166 Stopping criteria 2167 The algorithm stops when at least one of the errors are within the 2168 specified tolerances or the maximum number of iterations is reached. If 2169 the maximum number of iterations is reached, but noen of the errors are 2170 within the tolerances, a warning is displayed and the best solution so 2171 far is returned. 2172 2173 Parameters 2174 MaxIter 2175 The maximum number of iterations to perform. The value must be a 2176 positive integer. The default is 20. 2177 2178 RelTol 2179 The limit for the relative error. The value must be a non-negative. 2180 The default value is 1e-19 when perl is compiled with long doubles 2181 or quadruple precision, and 1e-9 otherwise. 2182 2183 AbsTol 2184 The limit for the absolute error. The value must be a non-negative. 2185 The default value is 0. 2186 2187 Debug 2188 If this parameter does not affect when the algorithm terminates, but 2189 when set to non-zero, some information is displayed at each step. 2190 2191 Example 2192 If 2193 2194 $A = [[ 8, -8, -5, 6, -1, 3 ], 2195 [ -7, -1, 5, -9, 5, 6 ], 2196 [ -7, 8, 9, -2, -4, 3 ], 2197 [ 3, -4, 5, 5, 3, 3 ], 2198 [ 9, 8, -3, -4, 1, 6 ], 2199 [ -8, 9, -1, 3, 5, 2 ]]; 2200 2201 $y = [[ 80, -13 ], 2202 [ -2, 104 ], 2203 [ -57, -27 ], 2204 [ 47, -28 ], 2205 [ 5, 77 ], 2206 [ 91, 133 ]]; 2207 2208 the result of "$x = $y -> mldiv($A);", using double precision 2209 arithmetic, is the approximate solution 2210 2211 $x = [[ -2.999999999999998, -5.000000000000000 ], 2212 [ -1.000000000000000, 3.000000000000001 ], 2213 [ -5.999999999999997, -8.999999999999996 ], 2214 [ 8.000000000000000, -2.000000000000003 ], 2215 [ 6.000000000000003, 9.000000000000002 ], 2216 [ 7.999999999999997, 8.999999999999995 ]]; 2217 2218 The residual "$res = $A -> mmuladd($x, -$y);" is 2219 2220 $res = [[ 1.24344978758018e-14, 1.77635683940025e-15 ], 2221 [ 8.88178419700125e-15, -5.32907051820075e-15 ], 2222 [ -1.24344978758018e-14, 1.77635683940025e-15 ], 2223 [ -7.10542735760100e-15, -4.08562073062058e-14 ], 2224 [ -1.77635683940025e-14, -3.81916720471054e-14 ], 2225 [ 1.24344978758018e-14, 8.43769498715119e-15 ]]; 2226 2227 and the delta "$dx = $res -> mldiv($A);" is 2228 2229 $dx = [[ -8.592098303124e-16, -2.86724066474914e-15 ], 2230 [ -7.92220125658508e-16, -2.99693950082398e-15 ], 2231 [ -2.22533360993874e-16, 3.03465504177947e-16 ], 2232 [ 6.47376093198353e-17, -1.12378127899388e-15 ], 2233 [ 6.35204502123966e-16, 2.40938179521241e-15 ], 2234 [ 1.55166908001001e-15, 2.08339859425849e-15 ]]; 2235 2236 giving the improved, and in this case exact, solution "$x -= $dx;", 2237 2238 $x = [[ -3, -5 ], 2239 [ -1, 3 ], 2240 [ -6, -9 ], 2241 [ 8, -2 ], 2242 [ 6, 9 ], 2243 [ 8, 9 ]]; 2244 2245SUBCLASSING 2246 The methods should work fine with any kind of numerical objects, 2247 provided that the assignment operator "=" is overloaded, so that Perl 2248 knows how to create a copy. 2249 2250 You can check the behaviour of the assignment operator by assigning a 2251 value to a new variable, modify the new variable, and check whether this 2252 also modifies the original value. Here is an example: 2253 2254 $x = Some::Class -> new(0); # create object $x 2255 $y = $x; # create new variable $y 2256 $y++; # modify $y 2257 print "it's a clone\n" if $x != $y; # is $x modified? 2258 2259 The subclass might need to implement some methods of its own. For 2260 instance, if each element is a complex number, a transpose() method 2261 needs to be implemented to take the complex conjugate of each value. An 2262 as_string() method might also be useful for displaying the matrix in a 2263 format more suitable for the subclass. 2264 2265 Here is an example showing Math::Matrix::Complex, a fully-working 2266 subclass of Math::Matrix, where each element is a Math::Complex object. 2267 2268 use strict; 2269 use warnings; 2270 2271 package Math::Matrix::Complex; 2272 2273 use Math::Matrix; 2274 use Scalar::Util 'blessed'; 2275 use Math::Complex 1.57; # "=" didn't clone before 1.57 2276 2277 our @ISA = ('Math::Matrix'); 2278 2279 # We need a new() method to make sure every element is an object. 2280 2281 sub new { 2282 my $self = shift; 2283 my $x = $self -> SUPER::new(@_); 2284 2285 my $sub = sub { 2286 defined(blessed($_[0])) && $_[0] -> isa('Math::Complex') 2287 ? $_[0] 2288 : Math::Complex -> new($_[0]); 2289 }; 2290 2291 return $x -> sapply($sub); 2292 } 2293 2294 # We need a transpose() method, since the transpose of a matrix 2295 # with complex numbers also takes the conjugate of all elements. 2296 2297 sub transpose { 2298 my $x = shift; 2299 my $y = $x -> SUPER::transpose(@_); 2300 2301 return $y -> sapply(sub { ~$_[0] }); 2302 } 2303 2304 # We need an as_string() method, since our parent's methods 2305 # doesn't format complex numbers correctly. 2306 2307 sub as_string { 2308 my $self = shift; 2309 my $out = ""; 2310 for my $row (@$self) { 2311 for my $elm (@$row) { 2312 $out = $out . sprintf "%10s ", $elm; 2313 } 2314 $out = $out . sprintf "\n"; 2315 } 2316 $out; 2317 } 2318 2319 1; 2320 2321BUGS 2322 Please report any bugs or feature requests via 2323 <https://github.com/pjacklam/p5-Math-Matrix/issues>. 2324 2325 Old bug reports and feature requests can be found at 2326 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Math-Matrix>. 2327 2328SUPPORT 2329 You can find documentation for this module with the perldoc command. 2330 2331 perldoc Math::Matrix 2332 2333 You can also look for information at: 2334 2335 * GitHub Source Repository 2336 2337 <https://github.com/pjacklam/p5-Math-Matrix> 2338 2339 * MetaCPAN 2340 2341 <https://metacpan.org/release/Math-Matrix> 2342 2343 * CPAN Ratings 2344 2345 <http://cpanratings.perl.org/d/Math-Matrix> 2346 2347 * CPAN Testers PASS Matrix 2348 2349 <http://pass.cpantesters.org/distro/A/Math-Matrix.html> 2350 2351 * CPAN Testers Reports 2352 2353 <http://www.cpantesters.org/distro/A/Math-Matrix.html> 2354 2355 * CPAN Testers Matrix 2356 2357 <http://matrix.cpantesters.org/?dist=Math-Matrix> 2358 2359LICENSE AND COPYRIGHT 2360 Copyright (c) 2020-2021, Peter John Acklam 2361 2362 Copyright (C) 2013, John M. Gamble <jgamble@ripco.com>, all rights 2363 reserved. 2364 2365 Copyright (C) 2009, oshalla 2366 https://rt.cpan.org/Public/Bug/Display.html?id=42919 2367 2368 Copyright (C) 2002, Bill Denney <gte273i@prism.gatech.edu>, all rights 2369 reserved. 2370 2371 Copyright (C) 2001, Brian J. Watson <bjbrew@power.net>, all rights 2372 reserved. 2373 2374 Copyright (C) 2001, Ulrich Pfeifer <pfeifer@wait.de>, all rights 2375 reserved. Copyright (C) 1995, Universität Dortmund, all rights reserved. 2376 2377 Copyright (C) 2001, Matthew Brett <matthew.brett@mrc-cbu.cam.ac.uk> 2378 2379 This program is free software; you may redistribute it and/or modify it 2380 under the same terms as Perl itself. 2381 2382AUTHORS 2383 Peter John Acklam <pjacklam@gmail.com> (2020-2021) 2384 2385 Ulrich Pfeifer <pfeifer@ls6.informatik.uni-dortmund.de> (1995-2013) 2386 2387 Brian J. Watson <bjbrew@power.net> 2388 2389 Matthew Brett <matthew.brett@mrc-cbu.cam.ac.uk> 2390 2391