Value::Matrix class

This is the Math Object code for a Matrix.

References:

MathObject Matrix methods
MathObject Contexts
CPAN RealMatrix docs

MatrixReal1
MatrixReduce.pl
Matrix
MatrixCheckers.pl -- checking whether vectors form a basis
MatrixReduce.pl -- tools for row reduction via elementary matrices
MatrixUnits.pl -- Generates unimodular matrices with real entries
PGmatrixmacros.pl
PGmorematrixmacros.pl
PGnumericalmacros.pl
tableau.pl
quickMatrixEntry.pl
LinearProgramming.pl

Contexts

Matrix: Allows students to enter [[3,4],[3,6]]
Complex-Matrix: Allows complex entries

Creation of Matrix MathObjects

Examples:

$M1 = Matrix(1, 2, 3);    # degree 1 (row vector)
$M1 = Matrix([1, 2, 3]);

$M2 = Matrix([1, 2], [3, 4]);    # degree 2 (matrix)
$M2 = Matrix([[1, 2], [3, 4]]);

$M3 = Matrix([[1, 2], [3, 4]], [[5, 6], [7, 8]]);    # degree 3 (tensor)
$M3 = Matrix([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]);

$M4 = ...

Commands added in Value::matrix

Conversion

$matrix->value produces an array of references to nested arrays, except at
the deepest level, where there will be the more basic MathObjects that make
up the Matrix (e.g. Real, Complex, Fraction, a mix of these, etc)

$M1->value is (1, 2, 3)
$M2->value is ([1, 2], [3, 4])
$M3->value is ([[1, 2], [3, 4]], [[5, 6], [7, 8]])

$matrix->wwMatrix produces CPAN MatrixReal1 matrix, used for computation subroutines and can only
be used on a degree 1 or degree 2 Matrix.

Information

$matrix->dimensions produces an array. For an n-degree Matrix, the array has n entries for
the n dimensions.

$matrix->degree returns the degree of the Matrix (the depth of the nested array).

Access values

row(i) : MathObject Matrix
    For a degree 1 Matrix, produces a degree 1 Matrix
    For a degree n Matrix with n > 1, produces a degree (n-1) Matrix

column(j) : MathObject Matrix or Real or Complex
    For a degree 1 Matrix, produces a Real or Complex
    For a degree n Matrix with n > 1, produces a degree n Matrix where the 2nd dimension is length 1

element : Real/Complex/Fraction value when passed the same number of arguments as the degree of the Matrix.
    If passed more than n arguments, null. If the degree of the Matrix is n and C<element> is passed
    k arguments with k < n, then this produces the corresponding degree (n-k) tensor.

Update values (these need to be added)

replace(value, [ i, j, ... ])
    For a degree n matrix, the array reference for the second entry should have n elements.
    The entry at that location will be replaced with value.

see C<change_matrix_entry()> in MatrixReduce and L<https://wiki.openwebwork.org/moodle/mod/forum/discuss.php?d=2970>

Advanced

$matrix->data: ARRAY reference (internal data) of MathObjects (Real, Complex, Fractions)
    stored at each location.

Passthrough methods

These cover subroutines in Matrix.pm (which overrides or augment CPAN's MatrixReal1.pm). Matrix is a specialized subclass of MatrixReal1.pm. The actual calculations for these methods are done in pg/lib/Matrix.pm

trace
proj
proj_coeff
L
R
PL
PR

These cover subroutines in pg/lib/MatrixReal1.pm (this has been modified to handle complex numbers) The actual calculations are done in MatrixReal1.pm subroutines. The commands below are Value::Matrix methods unless otherwise noted.

condition
det
inverse
is_symmetric
decompose_LR
dim
norm_one
norm_max
kleene
normalize
solve_LR($v)    - LR decomposition
solve($M,$v)    - function version of solve_LR
order_LR        - order of LR decomposition matrix (number of non-zero equations)(also order() )
order($M)       - function version of order_LR
solve_GSM
solve_SSM
solve_RM

Fractions in Matrices

One can use fractions in Matrices by including Context("Fraction"). For example

Context("Fraction");

$A = Matrix([
  [Fraction(1,1), Fraction(1,2), Fraction(1,3)],
  [Fraction(1,2), Fraction(1,3), Fraction(1,4)],
  [Fraction(1,3), Fraction(1,4), Fraction(1,5)]
]);

and operations will be done using rational arithmetic. Also helpful is the method apply_fraction_to_matrix_entries in the MatrixReduce.pl macro. Some additional information can be found at https://forums.openwebwork.org/mod/forum/discuss.php?d=2978.

methods

`value`

Returns the array of arrayrefs of the matrix.

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A->value;

# returns ([1,2,3,4],[5,6,7,8],[9,10,11,12])

`dimensions`

Returns the dimensions of the matrix as an array

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A->dimensions;

returns the array (3,4)

$B = Matrix([ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ]);
$B->dimensions;

returns (2,2,2)

`isSquare`

Return true if the Matrix is degree 1 of length 1 or its last two dimensions are equal, false otherwise

Usage:

$A = Matrix([ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]);
$B = Matrix([ [ 1, 0, 0 ], [ 0, 1, 0 ] ]);
$C = Matrix(1);
$D = Matrix(1, 2);
$E = Matrix([ [ [ 1, 2 ], [ 3, 4 ] ] ]);
$F = Matrix([ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]);

$A->isSquare; # is 1  (true)  because it is a 3x3 matrix
$B->isSquare; # is '' (false) because it is a 2x3 matrix
$C->isSquare; # is 1  (true)  because it is a degree 1 matrix of length 1
$D->isSquare; # is '' (false) because it is a degree 1 matrix of length 2
$E->isSquare; # is 1  (true)  because it is a 1x2x2 tensor
$F->isSquare; # is '' (false) because it is a 2x1x2 tensor

`isRow`

Return true if the matrix is degree 1 (i.e., is a matrix row)

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$row_vect = Matrix([ 1, 2, 3, 4 ]);

$A->isRow;         # is '' (false)
$row_vect->isRow;  # is 1 (true)

`isOne`

Check for identity Matrix (for degree > 2, this means the last two dimensions hold identity matrices)

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ], [13, 14, 15, 16] ]);
$A->isOne;  # is false

$B = Matrix([ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]);
$B->isOne; # is true;

$C = Matrix(1);
$C->isOne; # is true

$D = Matrix([ [ [ 1, 0 ], [ 0, 1 ] ], [ [ 1, 0 ], [ 0, 1 ] ] ]);
$D->isOne; # is true

`isZero`

Check for zero Matrix

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ], [13, 14, 15, 16] ]);
$A->isZero; # is false

$B = Matrix([ [ 0, 0, 0 ], [ 0, 0, 0 ], [ 0, 0, 0 ] ]);
$B->isZero; # is true;

$C = Matrix([ [ [ 1, 0 ], [ 0, 1 ] ], [ [ 1, 0 ], [ 0, 1 ] ] ]);
$C->isZero; # is false

$D = Matrix([ [ [ 0, 0 ], [ 0, 0 ] ], [ [ 0, 0 ], [ 0, 0 ] ] ]);
$D->isZero; # is true

`isUpperTriangular`

Check if a Matrix is upper triangular (for degree > 2, applies to frontal slice matrices)

`isLowerTriangular`

Check if a Matrix is lower triangular (for degree > 2, applies to frontal slice matrices)

`isDiagonal`

Check if a Matrix is diagonal (for degree > 2, applies to frontal slice matrices)

`isSymmetric`

Check if a Matrix is symmetric (for degree > 2, applies to frontal slice matrices)

`isOrthogonal`

Check if a Matrix is orthogonal (for degree > 2, applies to frontal slice matrices)

`isREF`

Check if a Matrix is in row echelon form (for degree > 2, applies to frontal slice matrices)

`isRREF`

Check if a Matrix is in reduced row echelon form (for degree > 2, applies to frontal slice matrices)

`isREQ`

Fuzzy, probabilistic check for if two matrices are row equivalent.

Usage:

$A = Matrix([3, 1], [1, 0.3333]);
$B = Matrix([1, 1/3], [0, 0]);
$A->isREQ($B);   # true

`NGS`

Normalized Gram Schmidt basis for a given list of vectors. This uses "fuzzy" equivalency to avoid machine rounding issues. If called as a method on a Matrix, the rows of that Matrix are used as the list of vectors. If called as a method with the option cols => 1, then the columns are used as the list of vectors.

In array context, returns an array of 1D Matrix objects. In scalar context, returns a Matrix with those rows.

If cols => 1 was used, return the Matrix objects in column form.

Usage:

$A = Matrix([1, 2, 2], [2, 2, 1]);

@X = $A->NGS                                   # @X is (Matrix(1, 2, 2)/3, Matrix(10, 2, -7)/sqrt(153))
@X = Value::Matrix->NGS([1, 2, 2], [2, 2, 1])  # @X is the same as above
$X = $A->NGS                                   # $X is Matrix([1/3, 2/3, 2/3], [10/sqrt(153), 2/sqrt(153), -7/sqrt(153)])
$X = Value::Matrix->NGS([1, 2, 2], [2, 2, 1])  # $X is the same as above

@X = $A->NGS(cols => 1)                        # @X is (Matrix([1/sqrt(5)], [2/sqrt(5)]), Matrix([2/sqrt(5)], [-1/sqrt(5)]))
$X = $A->NGS(cols => 1)                        # $X is Matrix([1/sqrt(5), 2/sqrt(5)], [2/sqrt(5), -1/sqrt(5)])

`slice`

Apply this to a degree n Matrix, passing (m, k), and produce the degree (n-1) Matrix defined by taking all entries whose position has mth index with value k. For example if $M is a 4x5x6 Matrix, then m can be 1, 2, or 3. If m is 2, then k can be 1, 2, 3, 4, or 5. $M-<gtslice(2,3)> is the 4x6 Matrix such that the entry at position (i,j) is the entry of $M at position (i,3,j).

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A->slice(1, 2)
# Index 1 identifies the 1st, 2nd, or 3rd row above, and with value 2 we get the second one:
# Matrix([5, 6, 7, 8])

$B = Matrix([ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ]);
$B->slice(1, 2)
# Index 1 identifies the two arrays at depth 1, and with value 2 we get the second one:
# Matrix([ [ 5, 6 ], [ 7, 8 ] ])
$B->slice(2, 1)
# Here we take all entries from $B where the 2nd index is 1: the 1 at position (1,1,1),
# the 2 at position (1,1,2), the 5 at position (2,1,1), and the 6 at position (2,1,2):
# Matrix([ [ 1, 2 ], [ 5, 6 ] ])
$B->slice(3, 1)
# Here we take all entries from $B where the 3rd index is 1: the 1 at position (1,1,1),
# the 3 at position (1,2,1), the 5 at position (2,1,1), and the 7 at position (2,2,1):
# Matrix([ [ 1, 3 ], [ 5, 7 ] ])

`transpose`

Take the transpose of a matrix. For a degree 1 Matrix, first promote to a degree 2 Matrix. For a degree n Matrix, apply a permutation of the indices. The default permutation transposes the last two indices. To specify a permutation, provide an array reference representing a cycle or an array of array references that represents a product of cycles. If a permutation is not specified, the default is the usual transposition of the last two indices.

Usage:

$A = Matrix([
    [ 1,  2,  3,  4 ],
    [ 5,  6,  7,  8 ],
    [ 9, 10, 11, 12 ]
]);
$A->transpose
# will be
# [
#     [ 1, 5, 9 ],
#     [ 2, 6, 10 ],
#     [ 3, 7, 11 ],
#     [ 4, 8, 12 ]
# ]

$B = Matrix([
    [ [ 1, 2 ], [ 3, 4 ] ],
    [ [ 5, 6 ], [ 7, 8 ] ]
]);
$B->transpose([1, 2, 3])
# will be
# [
#     [ [ 1, 3 ], [ 5, 7 ] ],
#     [ [ 2, 4 ], [ 6, 8 ] ]
# ]

$C = Matrix([
    [ [ [ 1,  2 ], [  3,  4 ] ], [ [  5,  6 ], [  7,  8 ] ] ],
    [ [ [ 9, 10 ], [ 11, 12 ] ], [ [ 13, 14 ], [ 15, 16 ] ] ]
]);
$C->transpose([ [ 1, 2], [3, 4] ])
# will be
# [
#     [ [ [ 1, 3 ], [ 2, 4 ] ], [ [  9, 11 ], [ 10, 12 ] ] ],
#     [ [ [ 5, 7 ], [ 6, 8 ] ], [ [ 13, 15 ], [ 14, 16 ] ] ]
# ]

`I`

Get an identity Matrix of the requested size

Value::Matrix->I(n)

Usage:

Value::Matrix->I(3); # returns a 3x3 identity matrix.
Value::Matrix->I([2],3);  # returns a 2x3x3 identity Matrix (tensor)
Value::Matrix->I([2,4],2);  # returns a 2x4x2x2 identity Matrix (tensor)
$A->I; # return an identity matrix of the appropriate degree and dimensions such that I*A = A

`E`

Get a degree 2 elementary matrix of the requested size and type. These include matrix that upon left multiply will perform row operations.

Row Swap

The method Value::Matrix->E(n,[i, j]) returns the n by n elementary matrix that upon right multiplication performs the row swap between rows i and j.

Usage:
```
Value::Matrix->E(3, [ 1, 3 ]);
```
returns the matrix
```
[[0, 0, 1],
[0, 1, 0],
[1, 0, 0]]
```
or if the matrix $A exists then
```
$A->E([1, 3]);
```
where the size of the resulting matrix is the number of rows of $A.
Multiply a row by a constant

The method Value::Matrix->E(n, [i], k) returns the n by n elementary matrix that upon right multiplication will multiply a row i, by constant k.

Usage:
```
Value::Matrix->E(4, [2], 3);
```
generates the matrix
```
[ [ 1, 0, 0, 0 ],
  [ 0, 3, 0, 0 ],
  [ 0, 0, 1, 0 ],
  [ 0, 0, 0, 1 ] ]
```
or if the matrix $A exists then
```
$A->E([4], 3);
```
will generate the elementary matrix of size number of rows of $A, which multiplies row 4 by 3.
Multiply a row by a constant and add to another row.

The method Value::Matrix->E(n, [ i, j ], k) returns the n by n elementary matrix that upon right multiplication will replace row j with k times row i added to row j.

Usage:
```
Value::Matrix->E(4, [ 3, 2 ], -3);
```
generates the matrix:
```
[ [ 1, 0, 0, 0 ],
  [ 0, 1, -3, 0 ],
  [ 0, 0, 1, 0 ],
  [ 0, 0, 0, 1 ] ]
```
or if the matrix $A exists of size m by n then
```
$A->E([3, 4], -5);
```
will generate the m by m elementary matrix which replaces row 4 by -5 times row 3 added to row 4. If $A does not have at least 4 rows, an error is raised.

`P`

Creates a degree 2 permutation matrix of the requested size.

Value::Matrix->P(n,(cycles)) in general where cycles is a sequence of array references of the cycles.

If one has an existing matrix $A, then $A->P(cycles) generals a permutation matrix of the same size as $A.

Usage:

Value::Matrix->P(3,[1, 2, 3]);  # corresponds to cycle (123) applied to rows of I_3.

returns the matrix [[0,1,0],[0,0,1],[1,0,0]]

Value::Matrix->P(6,[1,3],[2,4,6]);  # permutation matrix on cycle product (13)(246)

returns the matrix

[[0,0,1,0,0,0],
[0,0,0,0,0,1],
[1,0,0,0,0,0],
[0,1,0,0,0,0],
[0,0,0,0,1,0],
[0,0,0,1,0,0]]

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ], [13, 14, 15, 16] ]);
$P3 = $A->P([1,4]);

returns the matrix [[0,0,0,1],[0,1,0,0],[0,0,1,0],[1,0,0,0]]

`Zero`

Create a degree 2 zero matrix of requested size. If called on existing matrix, creates a matrix as the same size as given matrix.

Usage:

Value::Matrix->Zero(m,n);  # creates a m by n zero matrix.
Value::Matrix->Zero(n);    # creates an n ny n zero matrix.

$A1 = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A1->Zero;    # generates a zero matrix as same size as $A1.

`row`

Extract a given row from the matrix. For a degree 1 Matrix, $M->row(1) will return $M itself. Otherwise, a "row" is defined by the first index. For an degree n Matrix, a "row" will be a degree (n-1) Matrix.

Usage:

$A1 = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A1->row(2);  # returns the row Matrix [5,6,7,8]

`column`

Extract a given column from the matrix. For a degree 1 Matrix, $M-column(j)> will return the jth entry. Otherwise, for an degree n Matrix, $M-column(j)> returns an degree n Matrix tensor using j for the second index. To obtain the corresponding degree (n-1) Matrix, see slice().

Usage:

$A1 = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A1->column(2);  # returns the column Matrix [[2],[6],[10]]

`element`

Extract an element from the given position.

Usage:

$A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
$A->element(2,3); # returns 7

$B = Matrix([ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ]);
$B->element(1,2,1); # returns 3;

$row = Matrix([4,3,2,1]);
$row->element(2); # returns 3;

`replace`

Replace an entry with a new element and return the replaced element.

Usage:

$A = Matrix([ [ 1, 2, 3 ], [ 4, 5, 6 ] ]);
$A->replace(7, [ 2, 1 ]);
# Now $A is the matrix [ [ 1, 2, 3 ], [ 7, 5, 6 ] ]

# Also, the method returns the value that is replaced.
$x = $A->replace(8, [ 1, 3 ]);
# Now $A is [ [ 1, 2, 8 ], [ 7, 5, 6 ] ] and $x is 3.

# It is also OK to specify the indices as an array instead of an array reference
$A->replace(7, 2, 1);

`subMatrix`

Return a submatrix of a Matrix. If the indices are array referencess, the rows, columns, etc. that are indicated are kept and used to return a Matrix of the same degree. Other rows, columns, etc. are removed.

Note this can be used to permute rows, columns, etc by specifying all rows, columns, etc. in a different order.

Each input can be an integer instead of an array reference, and the complement of that integer is used for the rows to keep. In other words, using an integer for input indicates that you wish for that one row, column, etc. to be removed. Using 0 as an input indicates that all rows, columns, etc. for that dimension should be kept.

You can mix and match using array references and integers.

Usage:

$A = Matrix([ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ]);
$A->subMatrix([2 .. 3], [2 .. 4]);     # returns Matrix([ 6, 7, 8 ], [ 10, 11, 12 ])
$A->subMatrix(2, 3);                   # returns Matrix([ 1, 2, 4 ], [ 9, 10, 12 ]);
$A->subMatrix([1], 0);                 # returns Matrix([ [ 1, 2, 3, 4 ] ]);
$A->subMatrix([3, 1, 2], [1, 4, 2]);   # returns Matrix([ 9, 12, 10 ], [ 1, 4, 2 ] ,[ 5, 8, 6 ]);

This can also be used on Matrix objects that are not degree 2.

$B = Matrix(2, 4, 6, 8);
$B->subMatrix([1, 3]);   # returns Matrix(2, 6);
$B->subMatrix(2);        # returns Matrix(2, 6, 8);

$C = Matrix([ [ 1, 2, 3 ], [ 4, 5, 6 ] ], [ [ 7, 8, 9 ], [ 10, 11, 12 ] ]);
$C->subMatrix(0, 1, [1, 3]);              # returns Matrix([ [ 4, 6 ] ], [ [ 10, 12 ] ]);
$C->subMatrix(1, 2, 3);                   # returns Matrix([ [ [ 7, 8 ] ] ]);

`removeRow`

Return a new Matrix, where a row has been removed from a Matrix. This is only valid for Matrix Math Objects with degree 2 or higher. Removing a ith "row" from a Matrix of degree 3 or higher means to remove all entries with first index i.

Usage:

$A = Matrix([ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ], [13, 14, 15, 16]);
$A->removeRow(3);   # returns Matrix([ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [13, 14, 15, 16]);

$B = Matrix([ [ 1, 2, 3 ], [ 4, 5, 6 ] ], [ [ 7, 8, 9 ], [ 10, 11, 12 ] ]);
$B->removeRow(2);   # returns Matrix([ [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] ]);

`removeColumn`

Return a new Matrix, where a column has been removed from a Matrix. This is only valid for Matrix Math Objects with degree 2 or higher. Removing a jth "column" from a Matrix of degree 3 or higher means to remove all entries with second index j.

Usage:

$A = Matrix([ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ], [13, 14, 15, 16]);
$A->removeColumn(3);   # returns Matrix([ 1, 2, 4 ], [ 5, 6, 8 ], [ 9, 10, 12 ], [13, 14, 16]);

$B = Matrix([ [ 1, 2, 3 ], [ 4, 5, 6 ] ], [ [ 7, 8, 9 ], [ 10, 11, 12 ] ]);
$B->removeColumn(2);   # returns Matrix([ [ 1, 2, 3 ] ], [ [ 7, 8, 9 ] ]);

Value::Matrix

Value::Matrix class

References:

Matrix-Related libraries and macros:

Contexts

Creation of Matrix MathObjects

Commands added in Value::matrix

Conversion

Information

Access values

Update values (these need to be added)

Advanced

Passthrough methods

Fractions in Matrices

methods

value

dimensions

isSquare

isRow

isOne

isZero

isUpperTriangular

isLowerTriangular

isDiagonal

isSymmetric

isOrthogonal

isREF

isRREF

isREQ

NGS

slice

transpose

I

E

P

Zero

row

column

element

replace

subMatrix

removeRow

removeColumn

`value`

`dimensions`

`isSquare`

`isRow`

`isOne`

`isZero`

`isUpperTriangular`

`isLowerTriangular`

`isDiagonal`

`isSymmetric`

`isOrthogonal`

`isREF`

`isRREF`

`isREQ`

`NGS`

`slice`

`transpose`

`I`

`E`

`P`

`Zero`

`row`

`column`

`element`

`replace`

`subMatrix`

`removeRow`

`removeColumn`