Skip to content

feat: add einsum() with deterministic accumulation and generic contraction kernels - #34

Merged
CodeWithKyrian merged 1 commit into
mainfrom
feat/einsum-deterministic-accumulation
Jun 15, 2026
Merged

CodeWithKyrian merged 1 commit into
mainfrom
feat/einsum-deterministic-accumulation

Conversation

@CodeWithKyrian

Copy link
Copy Markdown
Contributor

This PR adds NDArray::einsum() — Einstein summation notation with deterministic accumulation order and a generic contraction engine backed by type-generic kernels.

Motivation and Context

matmul() and dot() delegate to BLAS, which tiles matrix operations for cache efficiency but produces non-deterministic accumulation order. For pipelines involving clamp() → log() or similar threshold-sensitive operations, ~10⁻⁷ differences from BLAS tiling can cascade into wrong results. einsum() fills this gap by offering the same operations with fixed canonical loop order, identical output on every run, every platform.

What's Changed

  • einsum(string $subscripts, ?NDArray $other) — two-operand and single-operand Einstein summation
  • Subscript parser supporting 12+ patterns: matrix multiply, dot, outer, element-wise, trace, diagonal, transpose, sum over axis, sum all, matrix-vector, vector-matrix, matrix×transposed
  • Fallback generic contraction engine for unoptimized subscript patterns
  • Global function alias einsum() in PhpMlKit\NDArray\Linalg namespace
  • Updated SPEC.md (section 9.5), API docs, and global functions docs

Breaking Changes

None.

@CodeWithKyrian
CodeWithKyrian merged commit c513f35 into main Jun 15, 2026
14 checks passed
@CodeWithKyrian
CodeWithKyrian deleted the feat/einsum-deterministic-accumulation branch June 15, 2026 18:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant