chippyash/Matrix
Quality Assurance
, (*1)
The above badges represent the current development branch. As a rule, I don't push
to GitHub unless tests, coverage and usability are acceptable. This may not be
true for short periods of time; on holiday, need code for some other downstream
project etc. If you need stable code, use a tagged version. Read 'Further Documentation'
and 'Installation'., (*2)
Test Contract in the docs directory., (*3)
Please note that developer support for PHP5.4 & 5.5 was withdrawn at version 3.0.0 of this library.
If you need support for PHP 5.4 or 5.5, please use a version >=2,<3, (*4)
What?
This library aims to provide matrix transformation functionality given that:, (*5)
- Everything has a test case
- It's PHP 5.4+
The matrix supplied in this library is a generic one. It treats a matrix as a
data structure giving the ability to create matrices and carry out transformations., (*6)
The library is released under the GNU GPL V3 or later license, (*7)
Why?
I finally got round, after too may years, to investigate
TDD as a serious methodology.
Always interested in something a bit maths related, I thought that having a go at
matrices would brush up on old forgotten things and provide a bit of entertainment.
So this library is as much about using TDD as it is about matrices. The bonus for
taking the TDD approach is that as I've (re)learnt something about matrices,
I've been able to refactor in safety., (*8)
When
The current library covers basic matrix manipulation. The library will cover most
well known generic matrix transformations and derivatives., (*9)
If you want more, either suggest it, or better still, fork it and provide a pull request., (*10)
Check out chippyash/Logical-Matrix for logical matrix operations, (*11)
Check out chippyash/Math-Matrix for mathematical matrix operations, (*12)
Check out chippyash/Strong-Type for strong type including numeric,
rational and complex type support, (*13)
Check out chippyash/Math-Type-Calculator for arithmetic operations on aforementioned strong types, (*14)
Check out ZF4 Packages for more packages, (*15)
How
Coding Basics
In PHP terms a matrix is an array of arrays, 2 dimensional i.e, (*16)
A shortcut for a single item matrix is to supply a single array, (*17)
use Chippyash/Matrix/Matrix;
$mA = new Matrix([]); //empty matrix
$mA = new Matrix([[]]); //empty matrix
$mA = new Matrix([1]); //single item matrix
As with any TDD application, the tests tell you everything you need to know about
the SUT. Read them! However for the short of temper amongst us, the salient
points are:, (*18)
A basic Matrix type is supplied, (*19)
- Matrix(array $source, bool $complete = false, bool $normalize= false, bool $normalizeDefault = null)
Matrices are 1 based, not 0 (zero) based, (*20)
The following methods on a matrix are supported:, (*21)
- toArray() : array - return matrix data as an array
- rows(): int - number of rows (n) in the matrix
- columns(): int - number of columns (m) in the matrix
- vertices(): int - number of entries in matrix (== n * m)
- get(int $row >= 0, int $col >= 0): mixed - if either row or col are zero, then return
a row vector if col == 0, column vector if row == 0, else return single vertex from matrix
indictated by row, col.
- is(string $attribute): boolean - see attributes below
- test(string $attribute): boolean - Raw form of is() method. You can use this to test for attributes
not supplied with the library by passing in $attribute conforming to AttributeInterface
- transform(TransformationInterface $transformation, $extra = null): Matrix - see transformations below
- setFormatter(FormatterInterface $formatter): fluent - set a display formatter
- display(): mixed - Return the matrix in some displayable format
- equality(Matrix $mB, boolean $strict = true): boolean - Is the matrix equal to matrix mB?
- mA->rows() == mB->rows()
- mA->columns() == mB->columns()
- mA->get(i,j) ==[=] mB->get(i,j)
If strict then type and value checked else only equivalence of value
Matrices are immutable
No operation on a matrix will change the internal structure of the matrix. Any
transformation or similar will return another matrix, leaving the original alone.
This allows for arithmetic stability., (*22)
However, a Mutability trait is provided for you to create a mutable matrix for special
purposes., (*23)
use Chippyash\Matrix\Traits\Mutability;
class MutableMatrix extends Matrix
{
use Mutability;
}
This provides a set() method:, (*24)
/**
* Set a matrix vertex, row or column vector
* If row == 0 && col > 0, then set the column vector indicated by col
* If col == 0 && row > 0, then set the row vector indicated by row
* if row > 0 && col > 0, set the vertex
* row == col == 0 is an error
*
* @param int $row
* @param int $col
* @param mixed|Matrix $data If setting a vector, supply the correct vector matrix
*
* @return Matrix
* @throws VerticeOutOfBoundsException
* @throws MatrixException
*/
public function set($row, $col, $data);
Matrices have attributes
- Attributes always return a boolean.
- Attributes implement the Chippyash\Matrix\Interfaces\AttributeInterface
- You can use the is() method of a Matrix to test for an attribute
if ($mA->is('square')) {}
//is the same as
$attr = new Matrix/Attribute/IsSquare();
if ($attr($mA) {}
Attributes supported:, (*25)
- IsColumnvector() - Is the matrix a column vector?
- IsComplete() - Does the matrix have all its entries present?
- IsDiagonal() - Are only entries on the main diagonal non-zero?
- IsEmpty() - Is the matrix an empty one?
- IsRectangle() - Is matrix non-empty and non-square?
- IsRowVector() - Is the matrix a row vector?
- IsSquare() - Is the matrix square? i.e. n == m & n >= 0
- IsVector() - Is the matrix a row vector or a column vector?
- Transformation always returns a Matrix
- The original matrix is untouched
- You can use the magic __invoke functionality
- Transformations implement the Chippyash\Matrix\Interfaces\TransformationInterface
$mB = $mA("Transpose");
//same as :
$comp = new Matrix\Transformation\Transpose;
$mB = $comp($mA);
//or
$mB = $mA->transform($comp);
Transformations supported:, (*26)
- Circshift - shift columns in matrix left or right (default) around the Y axis
- Cofactor - return the cofactor matrix of a vertice
- Colreduce - return matrix reduced by 1+ columns
- Colslice - return a slice (1+) of the matrix columns
- Concatenate - return matrix with extra matrix appended to the right
- Diagonal - reduce a matrix to its diagonal elements substituting non diagonal entries with zero
- MFunction - apply a function to every entry in the matrix
- Reflect - reflect matrix on X plane, Y plane, y=x plane and through origin
- Resize - resize a matrix by adding or subtracting rows and columns from bottom and right side respectively
- Rotate - rotate matrix through 90, 180 or 270 degrees
- Rowreduce - return matrix reduced by 1+ rows
- Rowslice - return a slice (1+) of matrix rows
- Shift - shift matrix rows columns left or right across the matrix replacing new columns with a value
- Stack - return matrix stacked on top of extra matrix
- Transpose - return matrix with rows and columns swapped around the diagonal
The magic invoke methods allow you to write in a functional way
For example (taken from Transformation\Cofactor):, (*27)
$fC = new Colreduce();
$fR = new Rowreduce();
//R(C(mA))
return $fR($fC($mA,[$col]),[$row]);
or this (from Transformation\Colreduce):, (*28)
$fT = new Transpose();
$fR = new Rowreduce();
return $fT($fR($fT($mA), [$col, $numCols]));
Matrices can be output for display
You can supply a formatter to create output via the display() method. The library
currently has an Ascii formatter. To use it, (*29)
use Chippyash\Matrix\Formatter\Ascii;
use Chippyash\Matrix\Matrix;
$mA = new Matrix([[1,2,3],['a','b','c'],[true, false, 'foo']]);
echo $mA->setFormatter(new Asciii())->display();
- Formatters implement the Chippyash\Matrix\Interfaces\FormatterInterface
- The Matrix::display() method accepts an optional array of options that are passed to the formatter
- Formatters are not limited to string output. You could for instance, write a formatter to output an SVG file
You can debug a Matrix
If you find something weird happening, utilise the Debug trait to dump out the
matrix to screen using the Ascii formatter., (*30)
Changing the library
- fork it
- write the test
- amend it
- do a pull request
Found a bug you can't figure out?, (*31)
- fork it
- write the test
- do a pull request
NB. Make sure you rebase to HEAD before your pull request, (*32)
Where?
The library is hosted at Github. It is
available at Packagist.org, (*33)
Installation
Install Composer, (*34)
For production
add, (*35)
"chippyash/matrix": ">=3,
to your composer.json "requires" section
#### For development
Clone this repo, and then run Composer in local repo root to pull in dependencies
git clone git@github.com:chippyash/Matrix.git Matrix
cd Matrix
composer update
To run the tests:, (*36)
cd Matrix
vendor/bin/phpunit -c test/phpunit.xml test/
License
This software library is released under the BSD 3 Clause license, (*37)
This software library is Copyright (c) 2014-2018, Ashley Kitson, UK, (*38)
History
V1.0.0 Original release, (*39)
V1.0.1 Minor bug fixes, (*40)
V1.1.0 New transformations, (*41)
V1.1.1 Code analysis conformance, (*42)
V1.1.2 Update readme, (*43)
V1.2.0 New transformation, (*44)
V1.2.1 Code analysis conformance, (*45)
V1.2.2 Fix Ascii formatter to work with descendent matrices, (*46)
V1.2.3 Fix transformations to work with descendent matrices, (*47)
V1.2.4 Amend IsSquare attribute test to accept empty matrix as square, (*48)
Update documentation
V1.2.5 Add equality() method, (*49)
V1.2.6 Add ability to set the formatter on Debug trait, (*50)
V1.2.7 Add ability to set the formatter options for debug, (*51)
V1.2.8 update phpunit to ~V4.3.0, (*52)
V2.0.0 BC Break: change chippyash\Matrix namespace to Chippyash\Matrix, (*53)
V2.0.1 remove duplicated tests, (*54)
V2.0.2 Add link to packages, (*55)
V2.0.3 code cleanup, (*56)
V2.1.0 Add Circshift transformation, (*57)
V2.2.0 Add Shift transformation, (*58)
V2.3.0 Add IsVector attribute, (*59)
V2.3.1 Add ability to get() method to return vectors, (*60)
V2.4.0 Add Mutable Set Trait, (*61)
V2.4.1 code cleanup, (*62)
V2.4.2 remove user config files, (*63)
V2.5.0 add Resize transformation, (*64)
V2.5.1 update build script, (*65)
V3.0.0 BC Break. Withdraw support for old PHP versions, (*66)
V3.1.0 Change of license from GPL V3 to BSD 3 Clause, (*67)
Wallogit.com
