Polite Math Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require interop-phpobjects/polite-math
   

   Add to composer.json under require or require-dev depending on your use case.

2. First Use Case: Implement a basic NDArray (N-Dimensional Array) for lightweight math operations:

   use Interop\Math\NDArray;
   
   // Create a simple 1D array
   $array = new class implements NDArray {
       private $data = [1, 2, 3];
   
       public function shape(): array { return [3]; }
       public function dtype(): int { return 1; /* INT */ }
       public function buffer(): Buffer { /* ... */ }
       // ... other required methods
   };
   

3. Key Entry Points:

   • NDArray for multi-dimensional data structures.
   • Buffer/LinearBuffer for raw data storage (e.g., GPU/CPU memory).
   • OpenCL for hardware-accelerated operations (if needed).

Implementation Patterns

Core Workflows

1. NDArray Integration:

   • Use NDArray for tensor-like operations (e.g., reshaping, slicing).
   • Example: Convert between PHP arrays and NDArray:

     $ndArray = new YourNDArrayImplementation([1, 2, 3]);
     $phpArray = $ndArray->toArray(); // mixed return (scalar/array)
     

2. Buffer Management:

   • Implement Buffer for custom memory handling (e.g., GPU buffers via DeviceBuffer):

     use Interop\Math\Buffer;
     
     class GPUBuffer implements Buffer {
         public function read(int $offset, int $length): string { /* ... */ }
         public function write(int $offset, string $data): void { /* ... */ }
         // ... other required methods
     }
     

3. Linear Algebra:

   • Leverage LinearBuffer for matrix operations (e.g., BLAS-like interfaces):

     $matrix = new YourLinearBuffer([1, 2, 3, 4]); // 2x2 matrix
     $result = $matrix->gemv($vector); // Generic Matrix-Vector Multiply
     

4. Interoperability:

   • Bridge PHP-native arrays to hardware-accelerated math (e.g., OpenCL):

     use Interop\Math\OpenCL;
     
     $clDevice = new YourOpenCLDevice();
     $buffer = $clDevice->createBuffer($data); // Offload to GPU
     

Laravel-Specific Tips

• Service Providers: Bind interfaces to implementations in AppServiceProvider:

  $this->app->bind(NDArray::class, YourNDArray::class);
  

• Task Scheduling: Use NDArray for batch processing (e.g., image resizing):

  $this->app->command('process-images', function () {
      $images = Image::all();
      foreach ($images as $image) {
          $ndArray = new ImageNDArray($image->pixels());
          $processed = $ndArray->applyFilter(); // Custom operation
      }
  });
  

• API Responses: Serialize NDArray to JSON for APIs:

  return response()->json(['data' => $ndArray->toArray()]);
  

Gotchas and Tips

Pitfalls

1. Type Mismatches:

   • NDArray::toArray() returns mixed (scalar/array). Validate before use:

     $data = $ndArray->toArray();
     if (is_array($data)) { /* Handle array */ }
     

2. Buffer Ownership:

   • Buffer implementations may manage external resources (e.g., GPU memory). Ensure proper cleanup:

     $buffer->free(); // If supported
     

3. OpenCL Limitations:

   • The OpenCL interface is minimal. Use vendor-specific SDKs (e.g., php-opencl) for full functionality.

4. PHP Stability:

   • Avoid minimum-stability in production (check composer.json after 1.0.1).

Debugging

• PHPDoc Inconsistencies:

  • Return types in PHPDoc (e.g., NDArray::buffer()) may not match runtime behavior. Use gettype() for debugging:

    $buffer = $ndArray->buffer();
    var_dump(gettype($buffer)); // Should match PHPDoc
    

• Shape Validation:

  • NDArray::shape() must return a flat array. Validate with:

    assert(is_array($shape) && !in_array($shape, array_keys($shape)));
    

Extension Points

1. Custom Data Types:

   • Extend NDArray for domain-specific dtypes (e.g., FLOAT64):

     const FLOAT64 = 2;
     public function dtype(): int { return self::FLOAT64; }
     

2. Memory Mapping:

   • Implement Buffer for memory-mapped files:

     class FileBuffer implements Buffer {
         private $fileHandle;
         public function __construct(string $path) { /* ... */ }
         // ... read/write methods
     }
     

3. Laravel Integration:

   • Create a facade for NDArray operations:

     facade(NDArray::class, YourNDArrayFacade::class);
     

     Then use globally:

     $result = NDArray::create([1, 2, 3])->sum();
     

4. Testing:

   • Mock Buffer/NDArray in unit tests:

     $mockBuffer = $this->createMock(Buffer::class);
     $mockBuffer->method('read')->willReturn('test');