@digitaldefiance/node-accelerate 1.0.1

package/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * TypeScript definitions for node-accelerate
+ * Apple Accelerate framework bindings for Node.js
+ */
+
+/**
+ * Perform matrix multiplication: C = A × B
+ * Uses Apple's BLAS (Basic Linear Algebra Subprograms) for hardware-accelerated computation
+ * 
+ * @param A - First matrix (M × K) as Float64Array in row-major order
+ * @param B - Second matrix (K × N) as Float64Array in row-major order
+ * @param C - Output matrix (M × N) as Float64Array in row-major order
+ * @param M - Number of rows in A and C
+ * @param K - Number of columns in A and rows in B
+ * @param N - Number of columns in B and C
+ * @returns The output matrix C
+ * 
+ * @example
+ * const M = 100, K = 100, N = 100;
+ * const A = new Float64Array(M * K);
+ * const B = new Float64Array(K * N);
+ * const C = new Float64Array(M * N);
+ * 
+ * // Fill A and B with data
+ * for (let i = 0; i < A.length; i++) A[i] = Math.random();
+ * for (let i = 0; i < B.length; i++) B[i] = Math.random();
+ * 
+ * // C = A × B (hardware-accelerated)
+ * accelerate.matmul(A, B, C, M, K, N);
+ */
+export function matmul(
+  A: Float64Array,
+  B: Float64Array,
+  C: Float64Array,
+  M: number,
+  K: number,
+  N: number
+): Float64Array;
+
+/**
+ * Compute dot product of two vectors: result = sum(a[i] * b[i])
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - First vector as Float64Array
+ * @param b - Second vector as Float64Array (must be same length as a)
+ * @returns The dot product as a number
+ * 
+ * @example
+ * const a = new Float64Array([1, 2, 3, 4]);
+ * const b = new Float64Array([5, 6, 7, 8]);
+ * const result = accelerate.dot(a, b); // 70
+ */
+export function dot(a: Float64Array, b: Float64Array): number;
+
+/**
+ * Compute sum of all elements in a vector: result = sum(vec[i])
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param vec - Input vector as Float64Array
+ * @returns The sum of all elements
+ * 
+ * @example
+ * const vec = new Float64Array([1, 2, 3, 4, 5]);
+ * const result = accelerate.sum(vec); // 15
+ */
+export function sum(vec: Float64Array): number;
+
+/**
+ * Compute mean (average) of all elements in a vector
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param vec - Input vector as Float64Array
+ * @returns The mean of all elements
+ * 
+ * @example
+ * const vec = new Float64Array([1, 2, 3, 4, 5]);
+ * const result = accelerate.mean(vec); // 3
+ */
+export function mean(vec: Float64Array): number;
+
+/**
+ * Element-wise vector addition: out[i] = a[i] + b[i]
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - First vector as Float64Array
+ * @param b - Second vector as Float64Array (must be same length as a)
+ * @param out - Output vector as Float64Array (must be same length as a)
+ * @returns The output vector
+ * 
+ * @example
+ * const a = new Float64Array([1, 2, 3]);
+ * const b = new Float64Array([4, 5, 6]);
+ * const out = new Float64Array(3);
+ * accelerate.vadd(a, b, out); // out = [5, 7, 9]
+ */
+export function vadd(
+  a: Float64Array,
+  b: Float64Array,
+  out: Float64Array
+): Float64Array;
+
+/**
+ * Element-wise vector multiplication: out[i] = a[i] * b[i]
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - First vector as Float64Array
+ * @param b - Second vector as Float64Array (must be same length as a)
+ * @param out - Output vector as Float64Array (must be same length as a)
+ * @returns The output vector
+ * 
+ * @example
+ * const a = new Float64Array([2, 3, 4]);
+ * const b = new Float64Array([5, 6, 7]);
+ * const out = new Float64Array(3);
+ * accelerate.vmul(a, b, out); // out = [10, 18, 28]
+ */
+export function vmul(
+  a: Float64Array,
+  b: Float64Array,
+  out: Float64Array
+): Float64Array;
+
+/**
+ * Vector scaling: out[i] = vec[i] * scalar
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param vec - Input vector as Float64Array
+ * @param scalar - Scalar value to multiply by
+ * @param out - Output vector as Float64Array (must be same length as vec)
+ * @returns The output vector
+ * 
+ * @example
+ * const vec = new Float64Array([1, 2, 3]);
+ * const out = new Float64Array(3);
+ * accelerate.vscale(vec, 2.0, out); // out = [2, 4, 6]
+ */
+export function vscale(
+  vec: Float64Array,
+  scalar: number,
+  out: Float64Array
+): Float64Array;
+
+/**
+ * Find maximum value in a vector
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param vec - Input vector as Float64Array
+ * @returns The maximum value
+ * 
+ * @example
+ * const vec = new Float64Array([1, 5, 3, 2, 4]);
+ * const result = accelerate.max(vec); // 5
+ */
+export function max(vec: Float64Array): number;
+
+/**
+ * Find minimum value in a vector
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param vec - Input vector as Float64Array
+ * @returns The minimum value
+ * 
+ * @example
+ * const vec = new Float64Array([1, 5, 3, 2, 4]);
+ * const result = accelerate.min(vec); // 1
+ */
+export function min(vec: Float64Array): number;
+
+/**
+ * Fast Fourier Transform (FFT) of a real signal
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param signal - Input signal as Float64Array (length must be power of 2)
+ * @returns Object with real and imaginary components of the frequency spectrum
+ * 
+ * @example
+ * const signal = new Float64Array(1024);
+ * for (let i = 0; i < signal.length; i++) {
+ *   signal[i] = Math.sin(2 * Math.PI * i / signal.length);
+ * }
+ * const spectrum = accelerate.fft(signal);
+ * console.log(spectrum.real, spectrum.imag);
+ */
+export function fft(signal: Float64Array): {
+  real: Float64Array;
+  imag: Float64Array;
+};
+
+/**
+ * Matrix-vector multiplication: y = A × x
+ * Uses Apple's BLAS for hardware-accelerated computation
+ * 
+ * @param A - Matrix (M × N) as Float64Array in row-major order
+ * @param x - Vector (N elements) as Float64Array
+ * @param y - Output vector (M elements) as Float64Array
+ * @param M - Number of rows in A
+ * @param N - Number of columns in A
+ * @returns The output vector y
+ */
+export function matvec(
+  A: Float64Array,
+  x: Float64Array,
+  y: Float64Array,
+  M: number,
+  N: number
+): Float64Array;
+
+/**
+ * AXPY operation: y = alpha*x + y
+ * Uses Apple's BLAS for hardware-accelerated computation
+ * 
+ * @param alpha - Scalar multiplier
+ * @param x - Input vector as Float64Array
+ * @param y - Input/output vector as Float64Array
+ * @returns The output vector y
+ */
+export function axpy(
+  alpha: number,
+  x: Float64Array,
+  y: Float64Array
+): Float64Array;
+
+/**
+ * Vector absolute value: b = |a|
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - Input vector as Float64Array
+ * @param b - Output vector as Float64Array
+ * @returns The output vector b
+ */
+export function vabs(a: Float64Array, b: Float64Array): Float64Array;
+
+/**
+ * Vector square: b = a^2 (element-wise)
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - Input vector as Float64Array
+ * @param b - Output vector as Float64Array
+ * @returns The output vector b
+ */
+export function vsquare(a: Float64Array, b: Float64Array): Float64Array;
+
+/**
+ * Vector square root: b = sqrt(a) (element-wise)
+ * Uses Apple's vForce for hardware-accelerated computation
+ * 
+ * @param a - Input vector as Float64Array
+ * @param b - Output vector as Float64Array
+ * @returns The output vector b
+ */
+export function vsqrt(a: Float64Array, b: Float64Array): Float64Array;
+
+/**
+ * Normalize vector to unit length: b = a / ||a||
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - Input vector as Float64Array
+ * @param b - Output vector as Float64Array (unit vector)
+ * @returns The output vector b
+ */
+export function normalize(a: Float64Array, b: Float64Array): Float64Array;
+
+/**
+ * Euclidean distance between two vectors: sqrt(sum((a - b)^2))
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - First vector as Float64Array
+ * @param b - Second vector as Float64Array
+ * @returns The Euclidean distance
+ */
+export function euclidean(a: Float64Array, b: Float64Array): number;
+
+/**
+ * Root Mean Square of vector: sqrt(sum(a^2) / n)
+ * Uses Apple's vDSP for hardware-accelerated computation
+ * 
+ * @param a - Input vector as Float64Array
+ * @returns The RMS value
+ */
+export function rms(a: Float64Array): number;
+
+/**
+ * All exported functions
+ */
+declare const accelerate: {
+  // Matrix operations
+  matmul: typeof matmul;
+  matvec: typeof matvec;
+  
+  // BLAS operations
+  axpy: typeof axpy;
+  
+  // Vector arithmetic
+  dot: typeof dot;
+  sum: typeof sum;
+  mean: typeof mean;
+  vadd: typeof vadd;
+  vsub: typeof vsub;
+  vmul: typeof vmul;
+  vdiv: typeof vdiv;
+  
+  // Vector functions
+  vabs: typeof vabs;
+  vsquare: typeof vsquare;
+  vsqrt: typeof vsqrt;
+  normalize: typeof normalize;
+  
+  // Reductions
+  max: typeof max;
+  min: typeof min;
+  rms: typeof rms;
+  
+  // Distance metrics
+  euclidean: typeof euclidean;
+  
+  // Signal processing
+  fft: typeof fft;
+};
+
+export default accelerate;

package/index.js

@@ -0,0 +1,392 @@
+/**
+ * Apple Accelerate Framework for Node.js
+ * 
+ * High-performance BLAS/vDSP operations optimized for M4 Max
+ * 
+ * Usage:
+ *   const accelerate = require('accelerate-m4');
+ *   
+ *   // Matrix multiplication (100x faster than JS for large matrices)
+ *   const A = new Float64Array(M * K);
+ *   const B = new Float64Array(K * N);
+ *   const C = new Float64Array(M * N);
+ *   accelerate.matmul(A, B, C, M, K, N);
+ *   
+ *   // Vector operations
+ *   const result = accelerate.dot(vec1, vec2);
+ *   accelerate.vadd(a, b, c);  // c = a + b
+ *   accelerate.vmul(a, b, c);  // c = a * b (element-wise)
+ *   accelerate.vscale(a, 2.0, b);  // b = a * 2.0
+ *   
+ *   // Reductions
+ *   const sum = accelerate.sum(vec);
+ *   const mean = accelerate.mean(vec);
+ *   const max = accelerate.max(vec);
+ *   const min = accelerate.min(vec);
+ *   
+ *   // FFT (input length must be power of 2)
+ *   const spectrum = accelerate.fft(signal);
+ */
+
+const path = require('path');
+const os = require('os');
+
+// Platform validation
+function validatePlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+  
+  if (platform !== 'darwin') {
+    const message = platform === 'linux' && arch === 'arm64'
+      ? `node-accelerate requires macOS, but detected Linux ARM64.\n` +
+        `This package uses Apple's Accelerate framework which is only available on macOS.\n` +
+        `Linux ARM64 systems (like Raspberry Pi, AWS Graviton) are not supported.\n` +
+        `\n` +
+        `For Linux ARM64, consider using:\n` +
+        `  - OpenBLAS: https://www.openblas.net/\n` +
+        `  - Eigen: https://eigen.tuxfamily.org/\n` +
+        `  - BLIS: https://github.com/flame/blis`
+      : `node-accelerate requires macOS (darwin), but detected ${platform}.\n` +
+        `This package uses Apple's Accelerate framework which is only available on macOS.\n` +
+        `Supported platforms: macOS only (Apple Silicon or Intel)`;
+    
+    throw new Error(message);
+  }
+  
+  if (arch !== 'arm64' && arch !== 'x64') {
+    throw new Error(
+      `node-accelerate requires ARM64 or x64 architecture, but detected ${arch}.\n` +
+      `Supported architectures:\n` +
+      `  - arm64 (Apple Silicon: M1/M2/M3/M4)\n` +
+      `  - x64 (Intel Macs)\n` +
+      `\n` +
+      `Your architecture (${arch}) is not supported.`
+    );
+  }
+  
+  // Check for Accelerate framework (should always be present on macOS)
+  const fs = require('fs');
+  const acceleratePath = '/System/Library/Frameworks/Accelerate.framework';
+  if (!fs.existsSync(acceleratePath)) {
+    throw new Error(
+      `Apple Accelerate framework not found at ${acceleratePath}.\n` +
+      `This is unusual for macOS. Please ensure you're running on a standard macOS system.`
+    );
+  }
+}
+
+// Validate platform before loading native module
+validatePlatform();
+
+let accelerate;
+try {
+  accelerate = require('./build/Release/accelerate.node');
+} catch (e) {
+  // Try debug build
+  try {
+    accelerate = require('./build/Debug/accelerate.node');
+  } catch (e2) {
+    throw new Error(
+      'Failed to load node-accelerate native module.\n' +
+      'This usually means the module needs to be built.\n\n' +
+      'To fix this, run: npm rebuild node-accelerate\n\n' +
+      'Requirements:\n' +
+      '  - macOS (Apple Silicon or Intel)\n' +
+      '  - Xcode Command Line Tools (run: xcode-select --install)\n' +
+      '  - Node.js >= 18.0.0\n\n' +
+      'Original error: ' + e.message
+    );
+  }
+}
+
+/**
+ * Matrix multiplication: C = A * B
+ * @param {Float64Array} A - Matrix A (M x K, row-major)
+ * @param {Float64Array} B - Matrix B (K x N, row-major)
+ * @param {Float64Array} C - Output matrix C (M x N, row-major)
+ * @param {number} M - Rows in A
+ * @param {number} K - Columns in A / Rows in B
+ * @param {number} N - Columns in B
+ * @returns {Float64Array} C
+ */
+function matmul(A, B, C, M, K, N) {
+  if (!(A instanceof Float64Array) || !(B instanceof Float64Array) || !(C instanceof Float64Array)) {
+    throw new TypeError('Arguments must be Float64Arrays');
+  }
+  if (A.length !== M * K) throw new RangeError(`A must have ${M * K} elements`);
+  if (B.length !== K * N) throw new RangeError(`B must have ${K * N} elements`);
+  if (C.length !== M * N) throw new RangeError(`C must have ${M * N} elements`);
+  
+  return accelerate.matmul(A, B, C, M, K, N);
+}
+
+/**
+ * Matrix multiplication (single precision): C = A * B
+ * @param {Float32Array} A - Matrix A (M x K, row-major)
+ * @param {Float32Array} B - Matrix B (K x N, row-major)
+ * @param {Float32Array} C - Output matrix C (M x N, row-major)
+ * @param {number} M - Rows in A
+ * @param {number} K - Columns in A / Rows in B
+ * @param {number} N - Columns in B
+ * @returns {Float32Array} C
+ */
+function matmulFloat(A, B, C, M, K, N) {
+  if (!(A instanceof Float32Array) || !(B instanceof Float32Array) || !(C instanceof Float32Array)) {
+    throw new TypeError('Arguments must be Float32Arrays');
+  }
+  return accelerate.matmulFloat(A, B, C, M, K, N);
+}
+
+/**
+ * Dot product of two vectors
+ * @param {Float64Array} a 
+ * @param {Float64Array} b 
+ * @returns {number}
+ */
+function dot(a, b) {
+  if (!(a instanceof Float64Array) || !(b instanceof Float64Array)) {
+    throw new TypeError('Arguments must be Float64Arrays');
+  }
+  return accelerate.dot(a, b);
+}
+
+/**
+ * Vector addition: c = a + b
+ * @param {Float64Array} a 
+ * @param {Float64Array} b 
+ * @param {Float64Array} c - Output
+ * @returns {Float64Array} c
+ */
+function vadd(a, b, c) {
+  return accelerate.vadd(a, b, c);
+}
+
+/**
+ * Vector subtraction: c = a - b
+ * @param {Float64Array} a 
+ * @param {Float64Array} b 
+ * @param {Float64Array} c - Output
+ * @returns {Float64Array} c
+ */
+function vsub(a, b, c) {
+  return accelerate.vsub(a, b, c);
+}
+
+/**
+ * Element-wise vector multiplication: c = a * b
+ * @param {Float64Array} a 
+ * @param {Float64Array} b 
+ * @param {Float64Array} c - Output
+ * @returns {Float64Array} c
+ */
+function vmul(a, b, c) {
+  return accelerate.vmul(a, b, c);
+}
+
+/**
+ * Element-wise vector division: c = a / b
+ * @param {Float64Array} a 
+ * @param {Float64Array} b 
+ * @param {Float64Array} c - Output
+ * @returns {Float64Array} c
+ */
+function vdiv(a, b, c) {
+  return accelerate.vdiv(a, b, c);
+}
+
+/**
+ * Vector scaling: b = a * scalar
+ * @param {Float64Array} a 
+ * @param {number} scalar 
+ * @param {Float64Array} b - Output
+ * @returns {Float64Array} b
+ */
+function vscale(a, scalar, b) {
+  return accelerate.vscale(a, scalar, b);
+}
+
+/**
+ * Sum of vector elements
+ * @param {Float64Array} a 
+ * @returns {number}
+ */
+function sum(a) {
+  return accelerate.sum(a);
+}
+
+/**
+ * Mean of vector elements
+ * @param {Float64Array} a 
+ * @returns {number}
+ */
+function mean(a) {
+  return accelerate.mean(a);
+}
+
+/**
+ * Maximum element in vector
+ * @param {Float64Array} a 
+ * @returns {number}
+ */
+function max(a) {
+  return accelerate.max(a);
+}
+
+/**
+ * Minimum element in vector
+ * @param {Float64Array} a 
+ * @returns {number}
+ */
+function min(a) {
+  return accelerate.min(a);
+}
+
+/**
+ * Fast Fourier Transform
+ * @param {Float64Array} input - Real input (length must be power of 2)
+ * @returns {{real: Float64Array, imag: Float64Array}} Complex output
+ */
+function fft(input) {
+  if (!(input instanceof Float64Array)) {
+    throw new TypeError('Input must be Float64Array');
+  }
+  const len = input.length;
+  if ((len & (len - 1)) !== 0) {
+    throw new RangeError('Input length must be a power of 2');
+  }
+  
+  const interleaved = accelerate.fft(input);
+  const half = len / 2;
+  const real = new Float64Array(half);
+  const imag = new Float64Array(half);
+  
+  for (let i = 0; i < half; i++) {
+    real[i] = interleaved[i * 2];
+    imag[i] = interleaved[i * 2 + 1];
+  }
+  
+  return { real, imag };
+}
+
+/**
+ * Matrix-vector multiplication: y = A * x
+ * @param {Float64Array} A - Matrix (M × N, row-major)
+ * @param {Float64Array} x - Vector (N elements)
+ * @param {Float64Array} y - Output vector (M elements)
+ * @param {number} M - Rows in A
+ * @param {number} N - Columns in A
+ * @returns {Float64Array} y
+ */
+function matvec(A, x, y, M, N) {
+  return accelerate.matvec(A, x, y, M, N);
+}
+
+/**
+ * AXPY operation: y = alpha*x + y
+ * @param {number} alpha - Scalar multiplier
+ * @param {Float64Array} x - Input vector
+ * @param {Float64Array} y - Input/output vector
+ * @returns {Float64Array} y
+ */
+function axpy(alpha, x, y) {
+  return accelerate.axpy(alpha, x, y);
+}
+
+/**
+ * Vector absolute value: b = |a|
+ * @param {Float64Array} a - Input vector
+ * @param {Float64Array} b - Output vector
+ * @returns {Float64Array} b
+ */
+function vabs(a, b) {
+  return accelerate.vabs(a, b);
+}
+
+/**
+ * Vector square: b = a^2
+ * @param {Float64Array} a - Input vector
+ * @param {Float64Array} b - Output vector
+ * @returns {Float64Array} b
+ */
+function vsquare(a, b) {
+  return accelerate.vsquare(a, b);
+}
+
+/**
+ * Vector square root: b = sqrt(a)
+ * @param {Float64Array} a - Input vector
+ * @param {Float64Array} b - Output vector
+ * @returns {Float64Array} b
+ */
+function vsqrt(a, b) {
+  return accelerate.vsqrt(a, b);
+}
+
+/**
+ * Normalize vector to unit length
+ * @param {Float64Array} a - Input vector
+ * @param {Float64Array} b - Output vector (unit vector)
+ * @returns {Float64Array} b
+ */
+function normalize(a, b) {
+  return accelerate.normalize(a, b);
+}
+
+/**
+ * Euclidean distance between two vectors
+ * @param {Float64Array} a - First vector
+ * @param {Float64Array} b - Second vector
+ * @returns {number} Distance
+ */
+function euclidean(a, b) {
+  return accelerate.euclidean(a, b);
+}
+
+/**
+ * Root Mean Square of vector
+ * @param {Float64Array} a - Input vector
+ * @returns {number} RMS value
+ */
+function rms(a) {
+  return accelerate.rms(a);
+}
+
+module.exports = {
+  // Matrix operations
+  matmul,
+  matmulFloat,
+  matvec,
+  
+  // BLAS operations
+  axpy,
+  
+  // Vector arithmetic
+  dot,
+  vadd,
+  vsub,
+  vmul,
+  vdiv,
+  vscale,
+  
+  // Vector functions
+  vabs,
+  vsquare,
+  vsqrt,
+  normalize,
+  
+  // Reductions
+  sum,
+  mean,
+  max,
+  min,
+  rms,
+  
+  // Distance metrics
+  euclidean,
+  
+  // Signal processing
+  fft,
+  
+  // Raw native bindings (for advanced use)
+  _native: accelerate
+};