README

ZMatrix is a high-performance PHP extension for matrix and N-dimensional tensor operations, implemented in C++ with optimizations for parallel processing and BLAS integration.

🚀 Installation

git clone https://github.com/omegaalfa/zmatrix.git
cd zmatrix
phpize
./configure --enable-zmatrix
make
sudo make install

Add the extension to your php.ini:

extension=zmatrix.so

📋 Features

The ZMatrix extension implements the following functionalities:

Tensor Creation

ZTensor::zeros() - Creates a tensor filled with zeros
ZTensor::ones() - Creates a tensor filled with ones
ZTensor::full() - Creates a tensor filled with a constant value
ZTensor::identity() - Creates an identity matrix
ZTensor::eye() - Creates a diagonal matrix with optional offset
ZTensor::arange() - Creates a 1D tensor with values in a range
ZTensor::linspace() - Creates a 1D tensor with evenly spaced values
ZTensor::logspace() - Creates a 1D tensor with logarithmically spaced values
ZTensor::random() - Creates a tensor with uniformly distributed random values
ZTensor::randn() - Creates a tensor with normally distributed random values

Tensor Properties

$tensor->ndim() - Returns the number of dimensions
$tensor->shape() - Returns the shape (dimensions)
$tensor->size() - Returns the total number of elements
$tensor->isEmpty() - Checks whether the tensor is empty
$tensor->toArray() - Converts tensor to PHP array

Basic Operations

$tensor->add() - Element-wise addition
$tensor->sub() - Element-wise subtraction
$tensor->mul() - Element-wise multiplication
$tensor->divide() - Element-wise division
$tensor->pow() - Raises each element to a power
$tensor->scalarMultiply() - Multiplies tensor by scalar
$tensor->scalarDivide() - Divides tensor by scalar
$tensor->transpose() - Matrix transpose (2D only)
$tensor->dot() - Dot product
$tensor->matmul() - Matrix multiplication (2D only)

Reshaping and Views

$tensor->reshape() - Returns a reshaped view of the tensor
ZTensor::tile() - Repeats a tensor vertically

Reductions and Statistics

$tensor->sum() - Sum over axis or globally
$tensor->sumtotal() - Global sum of all elements
$tensor->mean() - Mean of elements
$tensor->std() - Standard deviation (sample)
$tensor->min() - Minimum value
$tensor->max() - Maximum value

Activation Functions

$tensor->abs() - Absolute value
$tensor->sigmoid() - Sigmoid activation
$tensor->sigmoidDerivative() - Derivative of sigmoid
$tensor->relu() - ReLU activation
$tensor->reluDerivative() - Derivative of ReLU
$tensor->tanh() - Tanh activation
$tensor->tanhDerivative() - Derivative of tanh
$tensor->leakyRelu() - Leaky ReLU
$tensor->leakyReluDerivative() - Derivative of Leaky ReLU
$tensor->softmax() - Softmax activation
$tensor->softmaxDerivative() - Derivative of Softmax

Utilities

ZTensor::arr() - Creates a tensor from PHP array
ZTensor::safe() - Same as arr(), returns a ZTensor
$tensor->copy() - Deep copy
$tensor->key([...]) - Gets an element from coordinates
$tensor->broadcast($bias) - Adds 1D bias to rows of 2D tensor
ZTensor::clip($tensor, $min, $max) - Clamps tensor values within range
ZTensor::minimum($tensor, $value) - Element-wise min with scalar
ZTensor::maximum($tensor, $value) - Element-wise max with scalar
$tensor->greater($other) - Returns 1.0 where $this > $other

📊 Performance

ZMatrix offers significant performance improvements over pure PHP implementations:

Matrix Multiplication: Up to 100x faster than native PHP
N-dimensional Tensors: Efficient memory layout and computation
Automatic Parallelism: Uses multiple CPU cores when available (OpenMP or threads)
BLAS Integration: Optional BLAS acceleration for linear algebra

🚜 Use Cases

Machine Learning
Numerical Computing
Image Processing
Scientific Simulation
Data Analysis and Statistics

ZTensor PHP Extension - Usage Examples

This document provides comprehensive usage examples for all public methods available in the ZTensor PHP extension. The ZTensor class represents a multidimensional tensor implemented in C++ for high-performance mathematical operations.

Creation and Initialization
Special Tensors
Sequence Generation
Random Number Generation
Basic Arithmetic Operations
Linear Algebra
Mathematical Functions
Activation Functions
Statistics and Aggregations
Comparison and Clipping
Shape Manipulation
Special Operations

Use

use ZMatrix\ZTensor;

Create an empty tensor:

$empty = new ZTensor();
echo "Empty tensor: " . ($empty->isEmpty() ? "yes" : "no") . "\n";

Create tensor from 1D array:

$tensor1d = new ZTensor([1, 2, 3, 4, 5]);
print_r($tensor1d->toArray());

Create tensor from 2D array:

$tensor2d = new ZTensor([
    [1, 2, 3],
    [4, 5, 6]
]);
print_r($tensor2d->toArray());

Safe Creation - `safe()`

$safe_tensor = ZTensor::safe([
    [1.5, 2.7],
    [3.1, 4.9]
]);
print_r($safe_tensor->shape());

Array Factory - `arr()`

$arr_tensor = ZTensor::arr([
    [10, 20],
    [30, 40],
    [50, 60]
]);
print_r($arr_tensor->toArray());

Deep Copy - `copy()`

$original = ZTensor::arr([1, 2, 3]);
$copy = $original->copy();
print_r($original->toArray());
print_r($copy->toArray());

Special Tensors

Zeros Tensor - `zeros()`

$zeros = ZTensor::zeros([2, 3]);
print_r($zeros->toArray());
// Output: [[0, 0, 0], [0, 0, 0]]

Ones Tensor - `ones()`

$ones = ZTensor::ones([3, 2]);
print_r($ones->toArray());
// Output: [[1, 1], [1, 1], [1, 1]]

Constant Value Tensor - `full()`

$full = ZTensor::full([2, 2], 7.5);
print_r($full->toArray());
// Output: [[7.5, 7.5], [7.5, 7.5]]

Identity Matrix - `identity()`

$identity = ZTensor::identity(3);
print_r($identity->toArray());
// Output: [[1, 0, 0], [0, 1, 0], [0, 0, 1]]

Eye Matrix - `eye()`

$eye = ZTensor::eye(3, 4, 1); // 3 rows, 4 columns, upper diagonal
print_r($eye->toArray());
// Output: [[0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]

Sequence Generation

Range Sequence - `arange()`

Simple range (0 to 4):

$arange1 = ZTensor::arange(5);
print_r($arange1->toArray());
// Output: [0, 1, 2, 3, 4]

Range with start and stop:

$arange2 = ZTensor::arange(2, 8);
print_r($arange2->toArray());
// Output: [2, 3, 4, 5, 6, 7]

Range with step:

$arange3 = ZTensor::arange(0, 10, 2.5);
print_r($arange3->toArray());
// Output: [0, 2.5, 5.0, 7.5]

Linear Space - `linspace()`

$linspace = ZTensor::linspace(0, 1, 5);
print_r($linspace->toArray());
// Output: [0, 0.25, 0.5, 0.75, 1.0]

Logarithmic Space - `logspace()`

$logspace = ZTensor::logspace(1, 3, 3); // 10^1, 10^2, 10^3
print_r($logspace->toArray());
// Output: [10, 100, 1000]

Random Number Generation

Uniform Random - `random()`

$random = ZTensor::random([2, 3], 0.0, 10.0);
echo "Random tensor shape: ";
print_r($random->shape());
// Generates random values between 0.0 and 10.0

Normal Distribution - `randn()`

$randn = ZTensor::randn([2, 2], 0.0, 1.0);
echo "Normal distribution tensor shape: ";
print_r($randn->shape());
// Generates normally distributed random values

Basic Arithmetic Operations

Addition - `add()`

$a = ZTensor::arr([[1, 2], [3, 4]]);
$b = ZTensor::arr([[5, 6], [7, 8]]);
$sum = $a->add($b);
print_r($sum->toArray());
// Output: [[6, 8], [10, 12]]

Subtraction - `sub()`

$a = ZTensor::arr([[1, 2], [3, 4]]);
$b = ZTensor::arr([[5, 6], [7, 8]]);
$diff = $a->sub($b);
print_r($diff->toArray());
// Output: [[-4, -4], [-4, -4]]

Element-wise Multiplication - `mul()`

$a = ZTensor::arr([[1, 2], [3, 4]]);
$b = ZTensor::arr([[5, 6], [7, 8]]);
$product = $a->mul($b);
print_r($product->toArray());
// Output: [[5, 12], [21, 32]]

Element-wise Division - `divide()`

$a = ZTensor::arr([[10, 20], [30, 40]]);
$b = ZTensor::arr([[2, 4], [5, 8]]);
$division = $a->divide($b);
print_r($division->toArray());
// Output: [[5, 5], [6, 5]]

Scalar Multiplication - `scalarMultiply()`

$a = ZTensor::arr([[1, 2], [3, 4]]);
$scalar_mul = $a->scalarMultiply(2.5);
print_r($scalar_mul->toArray());
// Output: [[2.5, 5], [7.5, 10]]

Scalar Division - `scalarDivide()`

$a = ZTensor::arr([[4, 8], [12, 16]]);
$scalar_div = $a->scalarDivide(2.0);
print_r($scalar_div->toArray());
// Output: [[2, 4], [6, 8]]

Power - `pow()`

$a = ZTensor::arr([[2, 3], [4, 5]]);
$power = $a->pow(2);
print_r($power->toArray());
// Output: [[4, 9], [16, 25]]

Linear Algebra

Matrix Multiplication - `matmul()`

$matrix_a = ZTensor::arr([
    [1, 2, 3],
    [4, 5, 6]
]);
$matrix_b = ZTensor::arr([
    [7, 8],
    [9, 10],
    [11, 12]
]);
$matrix_product = $matrix_a->matmul($matrix_b);
print_r($matrix_product->toArray());
// Output: [[58, 64], [139, 154]]

Transpose - `transpose()`

$matrix = ZTensor::arr([
    [1, 2, 3],
    [4, 5, 6]
]);
$transposed = $matrix->transpose();
print_r($transposed->toArray());
// Output: [[1, 4], [2, 5], [3, 6]]

Dot Product - `dot()`

Vector dot product:

$vec1 = ZTensor::arr([1, 2, 3]);
$vec2 = ZTensor::arr([4, 5, 6]);
$dot_product = $vec1->dot($vec2);
echo "Dot product: $dot_product\n";
// Output: 32 (1*4 + 2*5 + 3*6)

Matrix-vector multiplication:

$matrix = ZTensor::arr([[1, 2], [3, 4]]);
$vector = ZTensor::arr([5, 6]);
$result = $matrix->dot($vector);
print_r($result->toArray());
// Output: [17, 39]

Mathematical Functions

Absolute Value - `abs()`

$negative = ZTensor::arr([-1, -2, 3, -4]);
$absolute = $negative->abs();
print_r($absolute->toArray());
// Output: [1, 2, 3, 4]

Square Root - `sqrt()`

$values = ZTensor::arr([1, 4, 9, 16]);
$sqrt_result = $values->sqrt();
print_r($sqrt_result->toArray());
// Output: [1, 2, 3, 4]

Exponential - `exp()`

$values = ZTensor::arr([0, 1, 2]);
$exp_result = $values->exp();
print_r($exp_result->toArray());
// Output: [1, 2.718..., 7.389...]

Natural Logarithm - `log()`

$values = ZTensor::arr([1, 2.718, 7.389]);
$log_result = $values->log();
print_r($log_result->toArray());
// Output: [0, 1, 2] (approximately)

Activation Functions

Sigmoid - `sigmoid()`

$data = ZTensor::arr([-2, -1, 0, 1, 2]);
$sigmoid_result = $data->sigmoid();
print_r($sigmoid_result->toArray());
// Output: [0.119, 0.269, 0.5, 0.731, 0.881] (approximately)

Sigmoid Derivative - `sigmoidDerivative()`

$sigmoid_values = ZTensor::arr([0.119, 0.269, 0.5, 0.731, 0.881]);
$sigmoid_deriv = $sigmoid_values->sigmoidDerivative();
print_r($sigmoid_deriv->toArray());
// Output: derivative values

ReLU - `relu()`

$data = ZTensor::arr([-2, -1, 0, 1, 2]);
$relu_result = $data->relu();
print_r($relu_result->toArray());
// Output: [0, 0, 0, 1, 2]

ReLU Derivative - `reluDerivative()`

$data = ZTensor::arr([-2, -1, 0, 1, 2]);
$relu_deriv = $data->reluDerivative();
print_r($relu_deriv->toArray());
// Output: [0, 0, 0, 1, 1]

Leaky ReLU - `leakyRelu()`

$data = ZTensor::arr([-2, -1, 0, 1, 2]);
$leaky_relu = $data->leakyRelu(0.1);
print_r($leaky_relu->toArray());
// Output: [-0.2, -0.1, 0, 1, 2]

Leaky ReLU Derivative - `leakyReluDerivative()`

$data = ZTensor::arr([-2, -1, 0, 1, 2]);
$leaky_deriv = $data->leakyReluDerivative(0.1);
print_r($leaky_deriv->toArray());
// Output: [0.1, 0.1, 0.1, 1, 1]

Hyperbolic Tangent - `tanh()`

$data = ZTensor::arr([-2, -1, 0, 1, 2]);
$tanh_result = $data->tanh();
print_r($tanh_result->toArray());
// Output: [-0.964, -0.762, 0, 0.762, 0.964] (approximately)

Tanh Derivative - `tanhDerivative()`

$tanh_values = ZTensor::arr([-0.964, -0.762, 0, 0.762, 0.964]);
$tanh_deriv = $tanh_values->tanhDerivative();
print_r($tanh_deriv->toArray());
// Output: derivative values

Softmax - `softmax()`

$data = ZTensor::arr([
    [1, 2, 3],
    [4, 5, 6]
]);
$softmax_result = $data->softmax();
print_r($softmax_result->toArray());
// Output: normalized probabilities for each row

Softmax Derivative - `softmaxDerivative()`

$softmax_values = ZTensor::arr([
    [0.09, 0.244, 0.665],
    [0.09, 0.244, 0.665]
]);
$softmax_deriv = $softmax_values->softmaxDerivative();
print_r($softmax_deriv->toArray());
// Output: derivative values

Statistics and Aggregations

Total Sum - `sumtotal()`

$tensor = ZTensor::arr([
    [1, 2, 3],
    [4, 5, 6]
]);
$total_sum = $tensor->sumtotal();
echo "Total sum: $total_sum\n";
// Output: 21

Mean - `mean()`

$tensor = ZTensor::arr([1, 2, 3, 4, 5]);
$mean_value = $tensor->mean();
echo "Mean: $mean_value\n";
// Output: 3.0

Minimum - `min()`

$tensor = ZTensor::arr([5, 2, 8, 1, 9]);
$min_value = $tensor->min();
echo "Minimum: $min_value\n";
// Output: 1

Maximum - `max()`

$tensor = ZTensor::arr([5, 2, 8, 1, 9]);
$max_value = $tensor->max();
echo "Maximum: $max_value\n";
// Output: 9

Standard Deviation - `std()`

$tensor = ZTensor::arr([1, 2, 3, 4, 5]);
$std_value = $tensor->std();
echo "Standard deviation: $std_value\n";
// Output: approximately 1.58

Sum Along Axis - `sum()`

$tensor = ZTensor::arr([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]);
$sum_result = ZTensor::zeros([3]);
$tensor->sum($sum_result, 1); // sum along axis 1
print_r($sum_result->toArray());
// Output: [6, 15, 24]

Comparison and Clipping

Greater Than - `greater()`

$a = ZTensor::arr([1, 5, 3, 8, 2]);
$b = ZTensor::arr([2, 4, 3, 6, 9]);
$greater_result = $a->greater($b);
print_r($greater_result->toArray());
// Output: [0, 1, 0, 1, 0]

Clip Values - `clip()`

$data = ZTensor::arr([[-2, 5, 10], [0, 15, 1]]);
$clipped = ZTensor::clip($data, 0, 10);
print_r($clipped->toArray());
// Output: [[0, 5, 10], [0, 10, 1]]

Element-wise Minimum with Scalar - `minimum()`

$data = ZTensor::arr([1, 5, 3, 8, 2]);
$min_result = ZTensor::minimum($data, 4.0);
print_r($min_result->toArray());
// Output: [1, 4, 3, 4, 2]

Element-wise Maximum with Scalar - `maximum()`

$data = ZTensor::arr([1, 5, 3, 8, 2]);
$max_result = ZTensor::maximum($data, 4.0);
print_r($max_result->toArray());
// Output: [4, 5, 4, 8, 4]

Shape Manipulation

Get Shape - `shape()`

$tensor = ZTensor::arr([
    [1, 2, 3, 4],
    [5, 6, 7, 8]
]);
$shape = $tensor->shape();
print_r($shape);
// Output: [2, 4]

Number of Dimensions - `ndim()`

$tensor = ZTensor::arr([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]);
$dimensions = $tensor->ndim();
echo "Number of dimensions: $dimensions\n";
// Output: 3

Total Size - `size()`

$tensor = ZTensor::arr([[1, 2, 3], [4, 5, 6]]);
$total_size = $tensor->size();
echo "Total elements: $total_size\n";
// Output: 6

Check if Empty - `isEmpty()`

$tensor = ZTensor::arr([1, 2, 3]);
$is_empty = $tensor->isEmpty();
echo "Is empty: " . ($is_empty ? "yes" : "no") . "\n";
// Output: no

Reshape - `reshape()`

$tensor = ZTensor::arr([
    [1, 2, 3, 4],
    [5, 6, 7, 8]
]);
$reshaped = $tensor->reshape([4, 2]);
print_r($reshaped->toArray());
// Output: [[1, 2], [3, 4], [5, 6], [7, 8]]

Convert to Array - `toArray()`

$tensor = ZTensor::arr([[1, 2], [3, 4]]);
$php_array = $tensor->toArray();
print_r($php_array);
// Output: [[1, 2], [3, 4]]

Access Element by Index - `key()`

$tensor = ZTensor::arr([
    [1, 2, 3],
    [4, 5, 6]
]);
$element = $tensor->key([1, 2]);
echo "Element at [1,2]: $element\n";
// Output: 6

Special Operations

Broadcasting - `broadcast()`

$matrix = ZTensor::arr([
    [1, 2],
    [3, 4],
    [5, 6]
]);
$bias = ZTensor::arr([10, 20]);
$broadcasted = $matrix->broadcast($bias);
print_r($broadcasted->toArray());
// Output: [[11, 22], [13, 24], [15, 26]]

Tile/Repeat - `tile()`

$tensor = ZTensor::arr([
    [1, 2],
    [3, 4]
]);
$tiled = ZTensor::tile($tensor, 3);
print_r($tiled->toArray());
// Output: [[1, 2], [3, 4], [1, 2], [3, 4], [1, 2], [3, 4]]

Support

For issues related to the ZTensor extension itself, please refer to the official repository or documentation provided by the extension maintainers.

🙌 Contribution

Contributions are welcome! Feel free to open issues or submit pull requests.

📄 License

MIT License. See LICENSE.

webtec3 / zmatrix

Maintainers

Details

README

🚀 Installation

📋 Features

Tensor Creation

Tensor Properties

Basic Operations

Reshaping and Views

Reductions and Statistics

Activation Functions

Utilities

📊 Performance

🚜 Use Cases

ZTensor PHP Extension - Usage Examples

Table of Contents

Use

Safe Creation - safe()

Array Factory - arr()

Deep Copy - copy()

Special Tensors

Zeros Tensor - zeros()

Ones Tensor - ones()

Constant Value Tensor - full()

Identity Matrix - identity()

Eye Matrix - eye()

Sequence Generation

Range Sequence - arange()

Linear Space - linspace()

Logarithmic Space - logspace()

Random Number Generation

Uniform Random - random()

Normal Distribution - randn()

Basic Arithmetic Operations

Addition - add()

Subtraction - sub()

Element-wise Multiplication - mul()

Element-wise Division - divide()

Scalar Multiplication - scalarMultiply()

Scalar Division - scalarDivide()

Power - pow()

Linear Algebra

Matrix Multiplication - matmul()

Transpose - transpose()

Dot Product - dot()

Mathematical Functions

Absolute Value - abs()

Square Root - sqrt()

Exponential - exp()

Natural Logarithm - log()

Activation Functions

Sigmoid - sigmoid()

Sigmoid Derivative - sigmoidDerivative()

ReLU - relu()

ReLU Derivative - reluDerivative()

Leaky ReLU - leakyRelu()

Leaky ReLU Derivative - leakyReluDerivative()

Hyperbolic Tangent - tanh()

Tanh Derivative - tanhDerivative()

Softmax - softmax()

Softmax Derivative - softmaxDerivative()

Statistics and Aggregations

Total Sum - sumtotal()

Mean - mean()

Minimum - min()

Maximum - max()

Standard Deviation - std()

Sum Along Axis - sum()

Comparison and Clipping

Greater Than - greater()

Clip Values - clip()

Element-wise Minimum with Scalar - minimum()

Element-wise Maximum with Scalar - maximum()

Shape Manipulation

Get Shape - shape()

Number of Dimensions - ndim()

Total Size - size()

Check if Empty - isEmpty()

Reshape - reshape()

Safe Creation - `safe()`

Array Factory - `arr()`

Deep Copy - `copy()`

Zeros Tensor - `zeros()`

Ones Tensor - `ones()`

Constant Value Tensor - `full()`

Identity Matrix - `identity()`

Eye Matrix - `eye()`

Range Sequence - `arange()`

Linear Space - `linspace()`

Logarithmic Space - `logspace()`

Uniform Random - `random()`

Normal Distribution - `randn()`

Addition - `add()`

Subtraction - `sub()`

Element-wise Multiplication - `mul()`

Element-wise Division - `divide()`

Scalar Multiplication - `scalarMultiply()`

Scalar Division - `scalarDivide()`

Power - `pow()`

Matrix Multiplication - `matmul()`

Transpose - `transpose()`

Dot Product - `dot()`

Absolute Value - `abs()`

Square Root - `sqrt()`

Exponential - `exp()`

Natural Logarithm - `log()`

Sigmoid - `sigmoid()`

Sigmoid Derivative - `sigmoidDerivative()`

ReLU - `relu()`

ReLU Derivative - `reluDerivative()`

Leaky ReLU - `leakyRelu()`

Leaky ReLU Derivative - `leakyReluDerivative()`

Hyperbolic Tangent - `tanh()`

Tanh Derivative - `tanhDerivative()`

Softmax - `softmax()`

Softmax Derivative - `softmaxDerivative()`

Total Sum - `sumtotal()`

Mean - `mean()`

Minimum - `min()`

Maximum - `max()`

Standard Deviation - `std()`

Sum Along Axis - `sum()`

Greater Than - `greater()`

Clip Values - `clip()`

Element-wise Minimum with Scalar - `minimum()`

Element-wise Maximum with Scalar - `maximum()`

Get Shape - `shape()`

Number of Dimensions - `ndim()`

Total Size - `size()`

Check if Empty - `isEmpty()`

Reshape - `reshape()`

Convert to Array - `toArray()`

Access Element by Index - `key()`

Broadcasting - `broadcast()`

Tile/Repeat - `tile()`