/ 
Math-Matrix-0.91
River stage one • 5 direct dependents • 6 total dependents
/ Math::Matrix

NAME

Math::Matrix - multiply and invert matrices

SYNOPSIS

use Math::Matrix;

# Generate a random 3-by-3 matrix.
srand(time);
my $A = Math::Matrix -> new([rand, rand, rand],
                            [rand, rand, rand],
                            [rand, rand, rand]);
$A -> print("A\n");

# Append a fourth column to $A.
my $x = Math::Matrix -> new([rand, rand, rand]);
my $E = $A -> concat($x -> transpose);
$E -> print("Equation system\n");

# Compute the solution.
my $s = $E -> solve;
$s -> print("Solutions s\n");

# Verify that the solution equals $x.
$A -> multiply($s) -> print("A*s\n");

DESCRIPTION

This module implements various constructors and methods for creating and manipulating matrices.

All methods return new objects, so, for example, $X->add($Y) does not modify $X.

$X -> add($Y);         # $X not modified; output is lost
$X = $X -> add($Y);    # this works

Some operators are overloaded (see "OVERLOADING") and allow the operand to be modified directly.

$X = $X + $Y;          # this works
$X += $Y;              # so does this

METHODS

Constructors

new()

Creates a new object from the input arguments and returns it.

If a single input argument is given, and that argument is a reference to array whose first element is itself a reference to an array, it is assumed that the argument contains the whole matrix, like this:

$x = Math::Matrix->new([[1, 2, 3], [4, 5, 6]]); # 2-by-3 matrix
$x = Math::Matrix->new([[1, 2, 3]]);            # 1-by-3 matrix
$x = Math::Matrix->new([[1], [2], [3]]);        # 3-by-1 matrix

If a single input argument is given, and that argument is not a reference to an array, a 1-by-1 matrix is returned.

$x = Math::Matrix->new(1);                      # 1-by-1 matrix

Otherwise it is assumed that each input argument is a row, like this:

$x = Math::Matrix->new([1, 2, 3], [4, 5, 6]);   # 2-by-3 matrix
$x = Math::Matrix->new([1, 2, 3]);              # 1-by-3 matrix
$x = Math::Matrix->new([1], [2], [3]);          # 3-by-1 matrix

Note that all the folling cases result in an empty matrix:

$x = Math::Matrix->new([[], [], []]);
$x = Math::Matrix->new([[]]);
$x = Math::Matrix->new([]);

If new is called as an instance method with no input arguments, a zero filled matrix with identical dimensions is returned:

$b = $a->new();     # $b is a zero matrix with the size of $a

Each row must contain the same number of elements.

In case of an erry, undef is returned.

new_identity()

Returns a new identity matrix.

$a = Math::Matrix -> new(3);        # $a is a 3-by-3 identity matrix
eye()

This is an alias for new_identity.

clone()

Clones a matrix and returns the clone.

$b = $a->clone;
diagonal()

A constructor method that creates a diagonal matrix from a single list or array of numbers.

$p = Math::Matrix->diagonal(1, 4, 4, 8);
$q = Math::Matrix->diagonal([1, 4, 4, 8]);

The matrix is zero filled except for the diagonal members, which take the values of the vector.

The method returns undef in case of error.

tridiagonal()

A constructor method that creates a matrix from vectors of numbers.

$p = Math::Matrix->tridiagonal([1, 4, 4, 8]);
$q = Math::Matrix->tridiagonal([1, 4, 4, 8], [9, 12, 15]);
$r = Math::Matrix->tridiagonal([1, 4, 4, 8], [9, 12, 15], [4, 3, 2]);

In the first case, the main diagonal takes the values of the vector, while both of the upper and lower diagonals's values are all set to one.

In the second case, the main diagonal takes the values of the first vector, while the upper and lower diagonals are each set to the values of the second vector.

In the third case, the main diagonal takes the values of the first vector, while the upper diagonal is set to the values of the second vector, and the lower diagonal is set to the values of the third vector.

The method returns undef in case of error.

Other methods

size()

You can determine the dimensions of a matrix by calling:

($m, $n) = $a->size;
concat()

Concatenate matrices horizontally. The matrices must have the same number or rows. The result is a new matrix or undef in case of error.

$x = Math::Matrix -> new([1, 2], [4, 5]);   # 2-by-2 matrix
$y = Math::Matrix -> new([3], [6]);         # 2-by-1 matrix
$z = $x -> concat($y);                      # 2-by-3 matrix
transpose()

Returns the transposed matrix. This is the matrix where colums and rows of the argument matrix are swapped.

negative()

Negate a matrix and return it.

$a = Math::Matrix -> new([-2, 3]);
$b = $a -> negative();                  # $b = [[2, -3]]
multiply()

Multiplies two matrices where the length of the rows in the first matrix is the same as the length of the columns in the second matrix. Returns the product or undef in case of error.

solve()

Solves a equation system given by the matrix. The number of colums must be greater than the number of rows. If variables are dependent from each other, the second and all further of the dependent coefficients are 0. This means the method can handle such systems. The method returns a matrix containing the solutions in its columns or undef in case of error.

invert()

Invert a Matrix using solve.

pinvert()

Compute the pseudo-inverse of the matrix: ((A'A)^-1)A'

multiply_scalar()

Multiplies a matrix and a scalar resulting in a matrix of the same dimensions with each element scaled with the scalar.

$a->multiply_scalar(2);  scale matrix by factor 2
add()

Add two matrices of the same dimensions.

subtract()

Shorthand for add($other->negative)

equal()

Decide if two matrices are equal. The criterion is, that each pair of elements differs less than $Math::Matrix::eps.

slice()

Extract columns:

a->slice(1,3,5);
diagonal_vector()

Extract the diagonal as an array:

$diag = $a->diagonal_vector;
tridiagonal_vector()

Extract the diagonals that make up a tridiagonal matrix:

($main_d, $upper_d, $lower_d) = $a->tridiagonal_vector;
determinant()

Compute the determinant of a matrix.

$a = Math::Matrix->new([3, 1],
                       [4, 2]);
$d = $a->determinant;                   # $d = 2
dot_product()

Compute the dot product of two vectors. The second operand does not have to be an object.

# $x and $y are both objects
$x = Math::Matrix -> new([1, 2, 3]);
$y = Math::Matrix -> new([4, 5, 6]);
$p = $x -> dot_product($y);             # $p = 32

# Only $x is an object.
$p = $x -> dot_product([4, 5, 6]);      # $p = 32
absolute()

Compute the absolute value (i.e., length) of a vector.

$v = Math::Matrix -> new([3, 4]);
$a = $v -> absolute();                  # $v = 5
normalize()

Normalize a vector, i.e., scale a vector so its length becomes 1.

$v = Math::Matrix -> new([3, 4]);
$u = $v -> normalize();                 # $u = [ 0.6, 0.8 ]
cross_product()

Compute the cross-product of vectors.

$x = Math::Matrix -> new([1,3,2],
                         [5,4,2]);
$p = $x -> cross_product();             # $p = [ -2, 8, -11 ]
as_string()

Creates a string representation of the matrix and returns it.

$x = Math::Matrix -> new([1, 2], [3, 4]);
$s = $x -> as_string();
print()

Prints the matrix on STDOUT. If the method has additional parameters, these are printed before the matrix is printed.

version()

Returns a string contining the package name and version number.

OVERLOADING

The following operators are overloaded.

+ and +=

Matrix addition. The two operands must have the same size.

$C  = $A + $B;      # assign $A + $B to $C
$A += $B;           # assign $A + $B to $A
- and -=

Matrix subtraction. The two operands must have the same size.

$C  = $A + $B;      # assign $A - $B to $C
$A += $B;           # assign $A - $B to $A
* and *=

Matrix multiplication. The number of columns in the first operand must be equal to the number of rows in the second operand.

$C  = $A * $B;      # assign $A * $B to $C
$A *= $B;           # assign $A * $B to $A
~

Transpose.

$B = ~$A;           # $B is the transpose of $A

BUGS

Please report any bugs through the web interface at https://rt.cpan.org/Ticket/Create.html?Queue=Math-Matrix (requires login). We will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Math::Matrix

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (c) 2020, Peter John Acklam.

Copyright (C) 2013, John M. Gamble <jgamble@ripco.com>, all rights reserved.

Copyright (C) 2009, oshalla https://rt.cpan.org/Public/Bug/Display.html?id=42919

Copyright (C) 2002, Bill Denney <gte273i@prism.gatech.edu>, all rights reserved.

Copyright (C) 2001, Brian J. Watson <bjbrew@power.net>, all rights reserved.

Copyright (C) 2001, Ulrich Pfeifer <pfeifer@wait.de>, all rights reserved. Copyright (C) 1995, Universität Dortmund, all rights reserved.

Copyright (C) 2001, Matthew Brett <matthew.brett@mrc-cbu.cam.ac.uk>

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Peter John Acklam <pjacklam@gmail.com> (2020)

Ulrich Pfeifer <pfeifer@ls6.informatik.uni-dortmund.de> (1995-2013)

Brian J. Watson <bjbrew@power.net>

Matthew Brett <matthew.brett@mrc-cbu.cam.ac.uk>