Update API to match Ext

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+- 4.0.0
+    - Made the pure-PHP library byte-compatible with the tensor_ext extension for `serialize()` / `unserialize()`: `Vector`, `Matrix`, and `ColumnVector` now implement `__serialize()` and `__unserialize()` so that payloads written by either implementation can be read by the other.
+    - Renamed the `build()` / `quick()` factories to `Vector::fromArray(array $a = [], bool $validate = true)` and `Matrix::fromArray(array $a = [], bool $validate = true)` to match the Tensor-Ext API.
+
 - 3.1.0
     - Implemented the singular value decomposition (SVD) in the pure-PHP library
     - Implemented the Moore-Penrose pseudoinverse in the pure-PHP library via SVD

docs/Matrix.md

@@ -27,13 +27,17 @@ Instantiate a matrix directly.
 - **Throws:** `Tensor\Exceptions\InvalidArgumentException` if rows have unequal column counts
 - **Note:** Prefer the factory methods below.
 
-### `Matrix::build(array $a = []) : Matrix`
+### `Matrix::fromArray(array $a = [], bool $validate = true) : Matrix`
 
-Factory method to build a new matrix from an array, running validation.
+Build a matrix from a PHP array of rows, normalising each value to a `float`
+and (by default) validating rectangularity and casting non-floats. Pass
+`$validate = false` to skip validation for quicker construction, e.g. when
+the source is already known to be a well-formed `list<list<float>>`.
 
-### `Matrix::quick(array $a = []) : Matrix`
-
-Build a new matrix foregoing any validation for quicker instantiation.
+- **Parameters:**
+  - `$a` — `array<array<int|float>>`
+  - `$validate` — whether to validate rows and cast non-floats to `float` (default `true`)
+- **Throws:** `Tensor\Exceptions\InvalidArgumentException` if `$validate = true` and rows have unequal column counts
 
 ### `Matrix::identity(int $n) : Matrix`
 
@@ -135,6 +139,23 @@ Return the elements of the matrix in a 2-d array.
 
 - **Returns:** `list<list<float>>`
 
+### `asTensorBuffer() : TensorBuffer`
+
+Return the underlying elements (flattened in row-major order) wrapped as a
+`Tensor` `TensorBuffer`, mirroring the Tensor-Ext surface area.
+
+- **Returns:** `Tensor\TensorBuffer`
+
+### `__serialize() : array`
+
+Return the elements of the matrix as a plain PHP array of rows so that only
+the values, and not the object structure, appear in the serialized form.
+Output is byte-compatible with the `Tensor-Ext` polyfill.
+
+### `__unserialize(array $data) : void`
+
+Restore the matrix from a plain array of rows produced by `__serialize()`.
+
 ### `asVectors() : array`
 
 Return each row as a vector in an array.

docs/Vector.md

@@ -23,18 +23,16 @@ Instantiate a vector directly.
   - `$validate` — whether to validate and cast elements to floats (default `true`)
 - **Note:** Prefer the factory methods below.
 
-### `Vector::build(array $a = [])`
+### `Vector::fromArray(array $a = [], bool $validate = true)`
 
-Factory method to build a new vector from an array, running validation.
+Build a vector from a PHP array of elements, normalising each value to a
+`float` and (by default) validating the input. Pass `$validate = false` to
+skip validation for quicker construction, e.g. when the source is already
+trusted and known to be a `list<float>`.
 
-- **Parameters:** `$a` — `(int|float)[]`
-- **Returns:** `mixed` (a `Vector`/`static`)
-
-### `Vector::quick(array $a = [])`
-
-Build a vector foregoing any validation for quicker instantiation.
-
-- **Parameters:** `$a` — `(int|float)[]`
+- **Parameters:**
+  - `$a` — `(int|float)[]`
+  - `$validate` — whether to cast non-floats to `float` (default `true`)
 - **Returns:** `mixed` (a `Vector`/`static`)
 
 ### `Vector::zeros(int $n) : Vector`
@@ -140,6 +138,23 @@ Return the vector as an array.
 
 - **Returns:** `list<float>`
 
+### `asTensorBuffer() : TensorBuffer`
+
+Return the underlying elements wrapped as a `Tensor` `TensorBuffer`, mirroring
+the Tensor-Ext surface area.
+
+- **Returns:** `Tensor\TensorBuffer`
+
+### `__serialize() : array`
+
+Return the elements of the vector as a plain PHP array so that only the values,
+and not the object structure, appear in the serialized form. Output is
+byte-compatible with the `Tensor-Ext` polyfill.
+
+### `__unserialize(array $data) : void`
+
+Restore the vector from a plain array of elements produced by `__serialize()`.
+
 ### `asRowMatrix() : Matrix`
 
 Return this vector as a 1 x n row matrix.

docs/getting-started.md

@@ -28,13 +28,13 @@ use Tensor\Matrix;
 use Tensor\Vector;
 
 // Build a 2 x 3 matrix.
-$a = Matrix::build([
+$a = Matrix::fromArray([
     [1.0, 2.0, 3.0],
     [4.0, 5.0, 6.0],
 ]);
 
 // Build a 3 x 2 matrix.
-$b = Matrix::build([
+$b = Matrix::fromArray([
     [7.0, 8.0],
     [9.0, 10.0],
     [11.0, 12.0],

src/ColumnVector.php

@@ -42,7 +42,7 @@ public function n() : int
      */
     public function transpose()
     {
-        return Vector::quick($this->a);
+        return Vector::fromArray($this->a, false);
     }
 
     /**
@@ -84,7 +84,7 @@ public function multiplyMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -115,7 +115,7 @@ public function divideMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -146,7 +146,7 @@ public function addMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -177,7 +177,7 @@ public function subtractMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -208,7 +208,7 @@ public function powMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -239,7 +239,7 @@ public function modMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -271,7 +271,7 @@ public function equalMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -303,7 +303,7 @@ public function notEqualMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -335,7 +335,7 @@ public function greaterMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -367,7 +367,7 @@ public function greaterEqualMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -399,7 +399,7 @@ public function lessMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 
     /**
@@ -431,6 +431,6 @@ public function lessEqualMatrix(Matrix $b) : Matrix
             $c[] = $rowC;
         }
 
-        return Matrix::quick($c);
+        return Matrix::fromArray($c, false);
     }
 }

src/Decompositions/Cholesky.php

@@ -71,7 +71,7 @@ public static function decompose(Matrix $a) : self
             }
         }
 
-        $l = Matrix::quick($l);
+        $l = Matrix::fromArray($l, false);
 
         return new self($l);
     }

src/Decompositions/Eigen.php

@@ -51,7 +51,7 @@ public static function decompose(Matrix $a, bool $symmetric = false) : self
         $n = $a->n();
 
         if ($n === 1) {
-            return new self($a->rowAsVector(0)->asArray(), Matrix::quick([[1.0]]));
+            return new self($a->rowAsVector(0)->asArray(), Matrix::fromArray([[1.0]], false));
         }
 
         if ($symmetric) {
@@ -83,7 +83,7 @@ public static function decompose(Matrix $a, bool $symmetric = false) : self
             }
         }
 
-        return new self($d, Matrix::quick($rows));
+        return new self($d, Matrix::fromArray($rows, false));
     }
 
     /**

src/Decompositions/LU.php

@@ -123,9 +123,9 @@ public static function decompose(Matrix $a) : self
         }
 
         return new self(
-            Matrix::quick($l),
-            Matrix::quick($u),
-            Matrix::quick($p)
+            Matrix::fromArray($l, false),
+            Matrix::fromArray($u, false),
+            Matrix::fromArray($p, false)
         );
     }
 

src/Decompositions/SVD.php

@@ -250,9 +250,9 @@ public static function decompose(Matrix $a) : self
         }
 
         return new self(
-            Matrix::quick($uMatrix),
+            Matrix::fromArray($uMatrix, false),
             array_slice($singularValues, 0, $k),
-            Matrix::quick($vT)
+            Matrix::fromArray($vT, false)
         );
     }
 
@@ -307,7 +307,7 @@ public function s() : Matrix
             $s[$i][$i] = $value;
         }
 
-        return Matrix::quick($s);
+        return Matrix::fromArray($s, false);
     }
 
     /**