LU and QR Decomposition (#9)

README.md

@@ -17,42 +17,52 @@ Matrix Transform
 
 This library currently provides the following operations:
 
- - addition
- - direct sum
- - subtraction
- - multiplication
- - division (using [A].[B]<sup>-1</sup>)
-    - division by
-    - division into
-
-together with functions for 
-
- - adjoint
- - antidiagonal
- - cofactors
- - determinant
- - diagonal
- - identity
- - inverse
- - minors
- - trace
- - transpose
+- addition
+- direct sum
+- subtraction
+- multiplication
+- division (using [A].[B]<sup>-1</sup>)
+   - division by
+   - division into
 
+together with functions for
+
+- adjoint
+- antidiagonal
+- cofactors
+- determinant
+- diagonal
+- identity
+- inverse
+- minors
+- trace
+- transpose
+
+and classes for
+
+- Decomposition
+   - LU Decomposition with partial row pivoting,
+
+     such that [P].[A] = [L].[U] and [A] = [P]<sup>|</sup>.[L].[U]
+   - QR Decomposition
+
+     such that [A] = [Q].[R]
 
 ## TO DO
 
- - power()
- - EigenValues
- - EigenVectors
- - Decomposition
+- power() function
+- EigenValues
+- EigenVectors
+- Decomposition
+   - Cholesky Decomposition
 
 ---
 
 # Usage
 
 To create a new Matrix object, provide an array as the constructor argument
 
-```
+```php
 $grid = [
     [16,  3,  2, 13],
     [ 5, 10, 11,  8],
@@ -63,12 +73,12 @@ $grid = [
 $matrix = new Matrix\Matrix($grid);
 ```
 The `Builder` class provides helper methods for creating specific matrices, specifically an identity matrix of a specified size; or a matrix of a specified dimensions, with every cell containing a set value.
-```
-$matrix = new Matrix\Builder::createFilledMatrix(1, 5, 3);
+```php
+$matrix = Matrix\Builder::createFilledMatrix(1, 5, 3);
 ```
 Will create a matrix of 5 rows and 3 columns, filled with a `1` in every cell; while
-```
-$matrix = new Matrix\Builder::createIdentityMatrix(3);
+```php
+$matrix = Matrix\Builder::createIdentityMatrix(3);
 ```
 will create a 3x3 identity matrix.
 
@@ -79,34 +89,34 @@ Matrix objects are immutable: whenever you call a method or pass a grid to a fun
 
 To perform mathematical operations with Matrices, you can call the appropriate method against a matrix value, passing other values as arguments
 
-```
-$matrix1 = new Matrix([
+```php
+$matrix1 = new Matrix\Matrix([
     [2, 7, 6],
     [9, 5, 1],
     [4, 3, 8],
 ]);
-$matrix2 = new Matrix([
+$matrix2 = new Matrix\Matrix([
     [1, 2, 3],
     [4, 5, 6],
     [7, 8, 9],
 ]);
 
-echo $matrix1->multiply($matrix2);
+var_dump($matrix1->multiply($matrix2)->toArray());
 ```
 or pass all values to the appropriate function
-```
-$matrix1 = new Matrix([
+```php
+$matrix1 = new Matrix\Matrix([
     [2, 7, 6],
     [9, 5, 1],
     [4, 3, 8],
 ]);
-$matrix2 = new Matrix([
+$matrix2 = new Matrix\Matrix([
     [1, 2, 3],
     [4, 5, 6],
     [7, 8, 9],
 ]);
 
-echo Matrix\multiply($matrix1, $matrix2);
+var_dump(Matrix\multiply($matrix1, $matrix2)->toArray());
 ```
 You can pass in the arguments as Matrix objects, or as arrays.
 
@@ -115,7 +125,7 @@ If you want to perform the same operation against multiple values (e.g. to add t
 ## Using functions
 
 When calling any of the available functions for a matrix value, you can either call the relevant method for the Matrix object
-```
+```php
 $grid = [
     [16,  3,  2, 13],
     [ 5, 10, 11,  8],
@@ -127,8 +137,8 @@ $matrix = new Matrix\Matrix($grid);
 
 echo $matrix->trace();
 ```
-or you can call the function as you would in procedural code, passing the Matrix object as an argument 
-```
+or you can call the function as you would in procedural code, passing the Matrix object as an argument
+```php
 $grid = [
     [16,  3,  2, 13],
     [ 5, 10, 11,  8],
@@ -140,7 +150,7 @@ $matrix = new Matrix\Matrix($grid);
 echo Matrix\trace($matrix);
 ```
 When called procedurally using the function, you can pass in the argument as a Matrix object, or as an array.
-```
+```php
 $grid = [
     [16,  3,  2, 13],
     [ 5, 10, 11,  8],
@@ -151,7 +161,7 @@ $grid = [
 echo Matrix\trace($grid);
 ```
 As an alternative, it is also possible to call the method directly from the `Functions` class.
-```
+```php
 $grid = [
     [16,  3,  2, 13],
     [ 5, 10, 11,  8],
@@ -163,3 +173,33 @@ $matrix = new Matrix\Matrix($grid);
 echo Matrix\Functions::trace($matrix);
 ```
 Used this way, methods must be called statically, and the argument must be the Matrix object, and cannot be an array.
+
+## Decomposition
+
+The library also provides classes for matrix decomposition. You can access these using
+```php
+$grid = [
+    [1, 2],
+    [3, 4],
+];
+
+$matrix = new Matrix\Matrix($grid);
+
+$decomposition = new Matrix\Decomposition\QR($matrix);
+$Q = $decomposition->getQ();
+$R = $decomposition->getR();
+```
+
+or alternatively us the `Decomposition` factory, identifying which form of decomposition you want to use
+```php
+$grid = [
+    [1, 2],
+    [3, 4],
+];
+
+$matrix = new Matrix\Matrix($grid);
+
+$decomposition = Matrix\Decomposition\Decomposition::decomposition(Matrix\Decomposition\Decomposition::QR, $matrix);
+$Q = $decomposition->getQ();
+$R = $decomposition->getR();
+```

classes/src/Decomposition/Decomposition.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Matrix\Decomposition;
+
+use Matrix\Exception;
+use Matrix\Matrix;
+
+class Decomposition
+{
+    const LU = 'LU';
+    const QR = 'QR';
+
+    /**
+     * @throws Exception
+     */
+    public static function decomposition($type, Matrix $matrix)
+    {
+        switch (strtoupper($type)) {
+            case self::LU:
+                return new LU($matrix);
+            case self::QR:
+                return new QR($matrix);
+            default:
+                throw new Exception('Invalid Decomposition');
+        }
+    }
+}