Skip to content

exceptions.md

Latest commit

 

History

History
219 lines (160 loc) · 4.3 KB

exceptions.md

File metadata and controls

219 lines (160 loc) · 4.3 KB
Raw

Exceptions

NDArray throws specific exceptions for different error conditions.

Exception Hierarchy

NDArrayException (base)
├── ShapeException
├── IndexException
├── DTypeException
├── AllocationException
├── MathException
└── PanicException

NDArrayException

Base exception class for all NDArray errors.

use PhpMlKit\NDArray\Exceptions\NDArrayException;

try {
    $arr = NDArray::array([]);
} catch (NDArrayException $e) {
    echo $e->getMessage();
}

ShapeException

Thrown when array shapes are incompatible.

use PhpMlKit\NDArray\Exceptions\ShapeException;

$a = NDArray::zeros([3, 3]);
$b = NDArray::zeros([4, 4]);

try {
    $c = $a->add($b);  // Throws ShapeException
} catch (ShapeException $e) {
    echo "Shape mismatch: " . $e->getMessage();
}

Common causes:

  • Incompatible shapes for arithmetic operations
  • Invalid reshape dimensions, including reshape sizes that do not preserve the element count
  • Invalid reshape inference, such as multiple -1 dimensions or a -1 dimension that cannot be inferred evenly
  • Broadcasting failures

IndexException

Thrown for invalid indexing operations.

use PhpMlKit\NDArray\Exceptions\IndexException;

$arr = NDArray::array([1, 2, 3]);

try {
    $val = $arr->get(10);  // Throws IndexException
} catch (IndexException $e) {
    echo "Invalid index: " . $e->getMessage();
}

Common causes:

  • Index out of bounds
  • Wrong number of indices
  • Invalid slice syntax

DTypeException

Thrown for data type errors.

use PhpMlKit\NDArray\Exceptions\DTypeException;

Common causes:

  • Unsupported type conversions
  • Type mismatch in operations

AllocationException

Thrown when memory allocation fails.

use PhpMlKit\NDArray\Exceptions\AllocationException;

try {
    $arr = NDArray::zeros([1000000, 1000000]);  // May throw
} catch (AllocationException $e) {
    echo "Out of memory: " . $e->getMessage();
}

Common causes:

  • Requesting too much memory
  • System memory exhausted

MathException

Thrown for mathematical errors.

use PhpMlKit\NDArray\Exceptions\MathException;

Common causes:

  • Division by zero
  • Domain errors (e.g., sqrt of negative)

PanicException

Thrown when Rust panics (unexpected error).

use PhpMlKit\NDArray\Exceptions\PanicException;

::: danger This indicates an internal error. Please report bugs if you encounter this. :::

Handling Exceptions

Basic Try-Catch

use PhpMlKit\NDArray\NDArray;
use PhpMlKit\NDArray\Exceptions\NDArrayException;

try {
    $arr = NDArray::array($data);
    $result = $arr->resolve([3, 3]);
} catch (NDArrayException $e) {
    // Handle any NDArray error
    echo "Error: " . $e->getMessage();
}

Specific Exception Handling

use PhpMlKit\NDArray\Exceptions\ShapeException;
use PhpMlKit\NDArray\Exceptions\IndexException;

try {
    // Operation that might fail
    $result = processArray($arr);
} catch (ShapeException $e) {
    // Handle shape errors specifically
    echo "Shape error: " . $e->getMessage();
} catch (IndexException $e) {
    // Handle index errors
    echo "Index error: " . $e->getMessage();
} catch (NDArrayException $e) {
    // Handle other NDArray errors
    echo "NDArray error: " . $e->getMessage();
}

Validation Before Operations

function safeAdd(NDArray $a, NDArray $b): ?NDArray {
    // Check shapes before operation
    if ($a->shape() !== $b->shape()) {
        echo "Warning: Shape mismatch\n";
        return null;
    }
    
    try {
        return $a->add($b);
    } catch (NDArrayException $e) {
        echo "Error: " . $e->getMessage();
        return null;
    }
}

Summary Table

Exception When Thrown Catch When
NDArrayException Base for all errors General error handling
ShapeException Shape mismatch Arithmetic, reshape operations
IndexException Invalid index Indexing, slicing operations
DTypeException Type error Type conversions
AllocationException Memory error Large array creation
MathException Math error Division, sqrt, log operations
PanicException Rust panic Report as bug

Next Steps