Rindow Math Matrix Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require rindow/rindow-math-matrix
   

2. Verify installation (check service level):

   vendor/bin/rindow-math-matrix
   

   • Expected output: Service Level: Accelerated (if drivers are properly configured).

3. Basic usage (create and manipulate matrices):

   use Rindow\Math\Matrix\MatrixOperator;
   
   $mo = new MatrixOperator();
   $matrix = $mo->array([[1, 2], [3, 4]]);
   echo $mo->toString($matrix); // Output: [[1,2],[3,4]]
   

First Use Case: Matrix Multiplication

$a = $mo->array([[1, 2], [3, 4]]);
$b = $mo->array([[5, 6], [7, 8]]);
$c = $mo->matmul($a, $b); // Matrix multiplication
echo $mo->toString($c); // Output: [[19,22],[43,50]]

Key Entry Points

• MatrixOperator: Core class for all operations.
• NDArray: N-dimensional array object (e.g., $mo->array()).
• BLAS/LAPACK functions: Access via $mo->gemm(), $mo->svd(), etc.
• GPU acceleration: Configure via $mo->laAccelerated(['deviceType' => 'GPU']).

Implementation Patterns

1. Matrix Operations Workflow

$mo = new MatrixOperator();

// Create matrices
$A = $mo->array([[1, 2], [3, 4]], dtype: 'float64');
$B = $mo->array([[5, 6], [7, 8]], dtype: 'float64');

// Basic operations
$sum = $mo->add($A, $B);          // Element-wise addition
$product = $mo->matmul($A, $B);   // Matrix multiplication
$transpose = $mo->transpose($A);  // Transpose

// Broadcasting (auto-handled)
$vector = $mo->array([1, 2, 3]);
$broadcasted = $mo->add($A, $vector); // Adds [1,2,3] to each row of A

2. Linear Algebra (BLAS/LAPACK)

// Solve linear system: Ax = b
$A = $mo->array([[1, 2], [3, 4]], dtype: 'float64');
$b = $mo->array([5, 6], dtype: 'float64');
$x = $mo->solve($A, $b); // Returns solution vector

// Singular Value Decomposition (SVD)
$U = $mo->zeros(2, 2);
$S = $mo->zeros(2);
$V = $mo->zeros(2, 2);
$mo->svd($A, $U, $S, $V); // In-place decomposition

3. GPU Acceleration

// Enable GPU (OpenCL) for acceleration
$mo->laAccelerated(['deviceType' => 'GPU']);

// Perform operation on GPU
$A_gpu = $mo->toGPU($A); // Transfer matrix to GPU
$B_gpu = $mo->toGPU($B);
$C_gpu = $mo->matmul($A_gpu, $B_gpu); // Compute on GPU
$C_cpu = $mo->toCPU($C_gpu); // Transfer back to CPU

4. Machine Learning Utilities

// Batch normalization
$mean = $mo->mean($A, axes: [0, 1]); // Global mean
$var = $mo->var($A, axes: [0, 1]);   // Global variance
$normalized = $mo->batchNorm($A, $mean, $var);

// Activation functions
$relu = $mo->relu($A);
$sigmoid = $mo->sigmoid($A);

5. Integration with FFI (OpenBLAS/OpenCL)

// Check loaded drivers
$status = $mo->getStatus();
echo "BLAS Driver: " . $status['BLAS Driver'];

// Switch drivers dynamically (e.g., for testing)
$mo->setDriver('Rindow\OpenBLAS\FFI\Blas');

Gotchas and Tips

1. Performance Pitfalls

• Default "Basic" Mode: Without FFI drivers, operations run in pure PHP (slow). Always check service level:

  vendor/bin/rindow-math-matrix
  

  • Fix: Install rindow/rindow-math-matrix-matlibffi and pre-built binaries (OpenBLAS/OpenCL).
  • macOS Limitation: Only "Basic" mode works natively. Use Docker/Linux for GPU acceleration.

• Data Type Mismatches: Explicitly specify dtype (e.g., 'float32', 'float64') to avoid silent precision loss.

  $A = $mo->array([[1, 2]], dtype: 'float64'); // Force 64-bit
  

2. Debugging Tips

• Verbose Mode: Enable boot logs to diagnose driver issues:

  vendor/bin/rindow-math-matrix -v
  

• GPU Device Selection: Specify platform/device explicitly:

  $mo->laAccelerated(['device' => '0,1']); // Platform 0, Device 1
  

• Memory Leaks: Avoid chaining operations without releasing buffers:

  $temp = $mo->zeros(1000, 1000); // Large buffer
  // ... use $temp ...
  $temp = null; // Explicitly free
  

3. Common Errors & Fixes

4. Extension Points

• Custom Drivers: Replace FFI plugins (e.g., swap OpenBLAS for CUDA):

  $mo->setDriver('MyCustom\BlasDriver');
  

• Serialization: Use NDArray::serialize()/unserialize() for inter-process communication.
• Preview Functions: Test topk() or gathernd() (may change in future releases).

5. Configuration Quirks

• Range Style: Version 2 uses [0,5) (exclusive end). Force v1 style with:

  $mo->array([[1, 2]], rangeStyle: NDArray::RANGE_STYLE_1);
  

• Complex Numbers: Only supported in BLAS functions (e.g., gemm). Use 'complex64' dtype.
• GPU Limits: OpenCL devices may have memory constraints. Monitor with:

  $mo->getOpenCLInfo();
  

6. Laravel-Specific Tips

• Service Provider: Register the operator as a singleton:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(MatrixOperator::class, function () {
          return new MatrixOperator();
      });
  }
  

• Queue Jobs: Offload heavy computations to queues:

  dispatch(new MatrixOperationJob($matrixData));
  

• Caching: Cache precomputed matrices (e.g., for ML models):

  $cacheKey = 'model_weights_v1';
  $weights = Cache::remember($cacheKey, now()->addHours(1), function () {
      return $mo->load('weights.npy');
  });