Rindow Openblas Ffi Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rindow/rindow-openblas-ffi
   

   Ensure system dependencies are met (see README).

2. Verify FFI Availability:

   use Rindow\OpenBLAS\OpenBLAS;
   
   if (!OpenBLAS::isAvailable()) {
       throw new \RuntimeException("OpenBLAS not available. Check system dependencies.");
   }
   

3. First Use Case: Matrix Multiplication

   $matrixA = OpenBLAS::createMatrix([2, 2], [1.0, 2.0, 3.0, 4.0]);
   $matrixB = OpenBLAS::createMatrix([2, 2], [5.0, 6.0, 7.0, 8.0]);
   $result = OpenBLAS::gemm('N', 'N', 2, 2, 2, 1.0, $matrixA, $matrixB, 0.0);
   

Implementation Patterns

Core Workflows

1. Buffer Management:

   • Use OpenBLAS::createBuffer() for 1D arrays (e.g., vectors).
   • Use OpenBLAS::createMatrix() for 2D arrays (e.g., matrices).
   • Example:

     $buffer = OpenBLAS::createBuffer(5, [1.0, 2.0, 3.0, 4.0, 5.0]);
     $matrix = OpenBLAS::createMatrix([3, 3], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]);
     

2. BLAS Operations:

   • Vector Operations: axpy, dot, nrm2.

     $result = OpenBLAS::axpy(5, 2.0, $buffer, 0, $buffer, 0); // y = 2x + y
     

   • Matrix Operations: gemm, gemv, gesvd.

     $result = OpenBLAS::gemv('N', 3, 3, 1.0, $matrix, $buffer, 0.0, $resultBuffer);
     

3. Integration with Rindow Math Matrix:

   • Convert between OpenBLAS buffers and Rindow\Math\Matrix objects for higher-level operations.
   • Example:

     use Rindow\Math\Matrix;
     
     $mathMatrix = Matrix::fromArray($matrix->toArray());
     $eigenvalues = $mathMatrix->eigenvalues(); // Use Rindow Math for advanced ops
     

4. Error Handling:

   • Wrap operations in try-catch blocks to handle FFI errors gracefully.

     try {
         $result = OpenBLAS::gesvd($matrix, $s, $u, $vt);
     } catch (\FFI\Exception $e) {
         \Log::error("OpenBLAS error: " . $e->getMessage());
     }
     

Advanced Patterns

1. Custom FFI Extensions:

   • Extend the package by defining new FFI types or functions in a custom class.
   • Example:

     class CustomOpenBLAS extends OpenBLAS {
         public static function customFunction($arg1, $arg2) {
             $ffi = self::getFFI();
             return $ffi->custom_c_function($arg1, $arg2);
         }
     }
     

2. Performance Optimization:

   • Pre-allocate buffers for repeated operations to avoid reallocations.
   • Use OpenBLAS::freeBuffer() to release memory when done.

     $buffer = OpenBLAS::createBuffer(1000);
     // Perform operations...
     OpenBLAS::freeBuffer($buffer);
     

3. Thread Safety:

   • OpenBLAS operations are thread-safe when using the pthread version (Linux/macOS). Avoid mixing OpenMP and pthread versions in the same process.

Gotchas and Tips

Common Pitfalls

1. OpenBLAS Version Conflicts:

   • Linux: Ensure libopenblas0-pthread is installed (not libopenblas0-openmp).

     sudo apt install libopenblas0-pthread liblapacke
     

   • macOS: Use vecLib (default). Avoid mixing with OpenBLAS if stability issues arise.

2. FFI Availability:

   • Check OpenBLAS::isAvailable() before operations. Common causes for failure:
     • Missing system libraries (e.g., libopenblas.so.0).
     • Incorrect LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS).
     • PHP compiled without FFI support (--enable-ffi).

3. Memory Leaks:

   • Always call OpenBLAS::freeBuffer() for dynamically allocated buffers.
   • Avoid reusing buffers across threads without synchronization.

4. Type Mismatches:

   • OpenBLAS expects double precision by default. Ensure PHP arrays are cast correctly:

     $buffer = OpenBLAS::createBuffer(3, [1.0, 2.0, 3.0]); // Not [1, 2, 3]
     

5. macOS Quirks:

   • Lapack gesvd: May crash with specific inputs (fixed in v1.1.1). Test edge cases.
   • PHPUnit Instability: Use Composer-based setup (not shivammathur/setup-php) for CI.

Debugging Tips

1. FFI Errors:

   • Enable FFI debug mode:

     \FFI::debug(true);
     

   • Check for undefined symbols or incorrect library paths.

2. Performance Profiling:

   • Compare execution time with/without OpenBLAS:

     $start = microtime(true);
     $result = OpenBLAS::gemm(...);
     $time = microtime(true) - $start;
     \Log::info("OpenBLAS gemm took {$time}s");
     

3. Buffer Validation:

   • Verify buffer dimensions before operations:

     if ($matrix->rows !== $matrix->cols) {
         throw new \InvalidArgumentException("Matrix must be square for this operation.");
     }
     

Extension Points

1. Custom BLAS/LAPACK Functions:

   • Add new functions by extending the FFI definition in src/OpenBLAS.php:

     $ffi->cdef("void custom_blas(double *x, double *y, int n);");
     

   • Call via:

     $ffi->custom_blas($buffer1->getPointer(), $buffer2->getPointer(), $size);
     

2. Hybrid PHP/C++ Workflows:

   • Use OpenBLAS::createBuffer() to pass data to C extensions or vice versa.
   • Example:

     $ffi = \FFI::cdef("void cpp_function(double *data, int size);", "libmycpp.so");
     $buffer = OpenBLAS::createBuffer(10, $data);
     $ffi->cpp_function($buffer->getPointer(), 10);
     

3. Fallback Mechanisms:

   • Implement fallback logic for unsupported platforms:

     if (!OpenBLAS::isAvailable()) {
         return fallbackMatrixMultiplication($a, $b);
     }