@digitaldefiance/node-accelerate 1.0.5 → 1.0.7

package/README.md

@@ -2,7 +2,12 @@
 
 High-performance Apple Accelerate framework bindings for Node.js. Get **283x faster** matrix operations and **5-8x faster** vector operations on Apple Silicon (M1/M2/M3/M4).
 
-[![npm version](https://badge.fury.io/js/node-accelerate.svg)](https://www.npmjs.com/package/@digitaldefiance/node-accelerate) [![GitHub](https://img.shields.io/github/license/Digital-Defiance/node-accelerate)](https://github.com/Digital-Defiance/node-accelerate/blob/main/LICENSE) [![GitHub stars](https://img.shields.io/github/stars/Digital-Defiance/node-accelerate?style=social)](https://github.com/Digital-Defiance/node-accelerate) [![Node.js CI](https://github.com/Digital-Defiance/node-accelerate/workflows/Test/badge.svg)](https://github.com/Digital-Defiance/node-accelerate/actions) [![Platform](https://img.shields.io/badge/platform-macOS-lightgrey)](https://github.com/Digital-Defiance/node-accelerate) [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![npm version](https://badge.fury.io/js/node-accelerate.svg)](https://www.npmjs.com/package/@digitaldefiance/node-accelerate)
+[![GitHub](https://img.shields.io/github/license/Digital-Defiance/node-accelerate)](https://github.com/Digital-Defiance/node-accelerate/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/Digital-Defiance/node-accelerate?style=social)](https://github.com/Digital-Defiance/node-accelerate)
+[![Node.js CI](https://github.com/Digital-Defiance/node-accelerate/workflows/Test/badge.svg)](https://github.com/Digital-Defiance/node-accelerate/actions)
+[![Platform](https://img.shields.io/badge/platform-macOS-lightgrey)](https://github.com/Digital-Defiance/node-accelerate)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 
 ----
 
@@ -65,13 +70,13 @@ The package will automatically check your platform during installation. If you s
 ### Verifying Installation
 
 ```bash
-node -e "const a = require('node-accelerate'); console.log('✓ Works!')"
+node -e "const a = require('@digitaldefiance/node-accelerate'); console.log('✓ Works!')"
 ```
 
 ## Quick Start
 
 ```javascript
-const accelerate = require('node-accelerate');
+const accelerate = require('@digitaldefiance/node-accelerate');
 
 // Matrix multiplication: C = A × B
 const M = 1000, K = 1000, N = 1000;

package/examples/machine-learning.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Example: Machine Learning Operations
+ * Demonstrates using Accelerate for ML inference
+ */
+
+const accelerate = require('../index');
+
+console.log('Machine Learning Example');
+console.log('='.repeat(50));
+console.log('');
+
+// Simple neural network layer: y = activation(W*x + b)
+function denseLayer(input, weights, bias, output) {
+  const inputSize = input.length;
+  const outputSize = output.length;
+  
+  // Matrix-vector multiply: output = weights * input
+  accelerate.matvec(weights, input, output, outputSize, inputSize);
+  
+  // Add bias: output = output + bias
+  accelerate.axpy(1.0, bias, output);
+  
+  // ReLU activation: output = max(0, output)
+  const zeros = new Float64Array(outputSize);
+  for (let i = 0; i < outputSize; i++) {
+    output[i] = Math.max(0, output[i]);
+  }
+  
+  return output;
+}
+
+// Example: 2-layer network
+console.log('Building 2-layer neural network...');
+console.log('  Input: 784 (28×28 image)');
+console.log('  Hidden: 128');
+console.log('  Output: 10 (digits 0-9)');
+console.log('');
+
+// Layer 1: 784 → 128
+const input = new Float64Array(784);
+for (let i = 0; i < input.length; i++) {
+  input[i] = Math.random();
+}
+
+const weights1 = new Float64Array(128 * 784);
+const bias1 = new Float64Array(128);
+const hidden = new Float64Array(128);
+
+for (let i = 0; i < weights1.length; i++) weights1[i] = Math.random() - 0.5;
+for (let i = 0; i < bias1.length; i++) bias1[i] = Math.random() - 0.5;
+
+console.log('Layer 1: Forward pass...');
+let start = process.hrtime.bigint();
+denseLayer(input, weights1, bias1, hidden);
+let end = process.hrtime.bigint();
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Layer 2: 128 → 10
+const weights2 = new Float64Array(10 * 128);
+const bias2 = new Float64Array(10);
+const output = new Float64Array(10);
+
+for (let i = 0; i < weights2.length; i++) weights2[i] = Math.random() - 0.5;
+for (let i = 0; i < bias2.length; i++) bias2[i] = Math.random() - 0.5;
+
+console.log('Layer 2: Forward pass...');
+start = process.hrtime.bigint();
+denseLayer(hidden, weights2, bias2, output);
+end = process.hrtime.bigint();
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Softmax (normalize to probabilities)
+console.log('Softmax activation...');
+const expOutput = new Float64Array(10);
+for (let i = 0; i < output.length; i++) {
+  expOutput[i] = Math.exp(output[i]);
+}
+const sumExp = accelerate.sum(expOutput);
+for (let i = 0; i < expOutput.length; i++) {
+  expOutput[i] /= sumExp;
+}
+
+console.log('Output probabilities:');
+for (let i = 0; i < 10; i++) {
+  console.log(`  Digit ${i}: ${(expOutput[i] * 100).toFixed(2)}%`);
+}
+console.log('');
+
+// K-means clustering example
+console.log('K-means Clustering Example');
+console.log('-'.repeat(50));
+
+const numPoints = 1000;
+const numClusters = 3;
+const dimensions = 2;
+
+// Generate random points
+const points = new Float64Array(numPoints * dimensions);
+for (let i = 0; i < points.length; i++) {
+  points[i] = Math.random() * 100;
+}
+
+// Initialize centroids
+const centroids = new Float64Array(numClusters * dimensions);
+for (let i = 0; i < numClusters; i++) {
+  const idx = Math.floor(Math.random() * numPoints);
+  centroids[i * dimensions] = points[idx * dimensions];
+  centroids[i * dimensions + 1] = points[idx * dimensions + 1];
+}
+
+console.log('Finding nearest centroids for 1000 points...');
+start = process.hrtime.bigint();
+
+const assignments = new Int32Array(numPoints);
+const point = new Float64Array(dimensions);
+const centroid = new Float64Array(dimensions);
+
+for (let i = 0; i < numPoints; i++) {
+  point[0] = points[i * dimensions];
+  point[1] = points[i * dimensions + 1];
+  
+  let minDist = Infinity;
+  let minCluster = 0;
+  
+  for (let j = 0; j < numClusters; j++) {
+    centroid[0] = centroids[j * dimensions];
+    centroid[1] = centroids[j * dimensions + 1];
+    
+    const dist = accelerate.euclidean(point, centroid);
+    if (dist < minDist) {
+      minDist = dist;
+      minCluster = j;
+    }
+  }
+  
+  assignments[i] = minCluster;
+}
+
+end = process.hrtime.bigint();
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Count assignments
+const counts = [0, 0, 0];
+for (let i = 0; i < numPoints; i++) {
+  counts[assignments[i]]++;
+}
+
+console.log('Cluster assignments:');
+for (let i = 0; i < numClusters; i++) {
+  console.log(`  Cluster ${i}: ${counts[i]} points`);
+}
+console.log('');
+
+console.log('✓ Machine learning operations completed!');

package/examples/matrix-multiply.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Example: Matrix Multiplication
+ * Demonstrates hardware-accelerated matrix operations
+ */
+
+const accelerate = require('../index');
+
+console.log('Matrix Multiplication Example');
+console.log('='.repeat(50));
+console.log('');
+
+// Create two 1000×1000 matrices
+const M = 1000, K = 1000, N = 1000;
+console.log(`Computing C = A × B where:`);
+console.log(`  A is ${M}×${K}`);
+console.log(`  B is ${K}×${N}`);
+console.log(`  C is ${M}×${N}`);
+console.log('');
+
+const A = new Float64Array(M * K);
+const B = new Float64Array(K * N);
+const C = new Float64Array(M * N);
+
+// Fill with random data
+console.log('Filling matrices with random 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();
+
+// Perform matrix multiplication
+console.log('Performing matrix multiplication...');
+const start = process.hrtime.bigint();
+accelerate.matmul(A, B, C, M, K, N);
+const end = process.hrtime.bigint();
+
+const timeMs = Number(end - start) / 1e6;
+console.log(`✓ Completed in ${timeMs.toFixed(2)}ms`);
+console.log('');
+
+// Calculate GFLOPS
+const operations = 2 * M * K * N; // 2 ops per multiply-add
+const gflops = operations / (timeMs * 1e6);
+console.log(`Performance: ${gflops.toFixed(2)} GFLOPS`);
+console.log('');
+
+// Verify result (check a few elements)
+console.log('Sample results:');
+console.log(`  C[0,0] = ${C[0].toFixed(6)}`);
+console.log(`  C[0,1] = ${C[1].toFixed(6)}`);
+console.log(`  C[1,0] = ${C[N].toFixed(6)}`);

package/examples/signal-processing.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Example: Signal Processing with FFT
+ * Demonstrates frequency analysis of audio signals
+ */
+
+const accelerate = require('../index');
+
+console.log('Signal Processing Example');
+console.log('='.repeat(50));
+console.log('');
+
+// Create a composite signal: 440 Hz (A4) + 880 Hz (A5)
+const sampleRate = 44100; // CD quality
+const duration = 1; // 1 second
+const fftSize = 16384; // Must be power of 2
+
+console.log(`Sample rate: ${sampleRate} Hz`);
+console.log(`FFT size: ${fftSize}`);
+console.log(`Frequency resolution: ${(sampleRate / fftSize).toFixed(2)} Hz`);
+console.log('');
+
+// Generate signal
+console.log('Generating signal (440 Hz + 880 Hz)...');
+const signal = new Float64Array(fftSize);
+for (let i = 0; i < fftSize; i++) {
+  const t = i / sampleRate;
+  signal[i] = 
+    Math.sin(2 * Math.PI * 440 * t) +  // A4
+    Math.sin(2 * Math.PI * 880 * t);   // A5
+}
+
+// Perform FFT
+console.log('Performing FFT...');
+const start = process.hrtime.bigint();
+const spectrum = accelerate.fft(signal);
+const end = process.hrtime.bigint();
+
+const timeMs = Number(end - start) / 1e6;
+console.log(`✓ Completed in ${timeMs.toFixed(3)}ms`);
+console.log('');
+
+// Calculate magnitudes
+const magnitudes = new Float64Array(spectrum.real.length);
+for (let i = 0; i < magnitudes.length; i++) {
+  magnitudes[i] = Math.sqrt(
+    spectrum.real[i] ** 2 + spectrum.imag[i] ** 2
+  );
+}
+
+// Find peaks
+console.log('Finding frequency peaks...');
+const peaks = [];
+const threshold = Math.max(...magnitudes) * 0.5;
+
+for (let i = 1; i < magnitudes.length - 1; i++) {
+  if (magnitudes[i] > threshold &&
+      magnitudes[i] > magnitudes[i - 1] &&
+      magnitudes[i] > magnitudes[i + 1]) {
+    const frequency = i * sampleRate / fftSize;
+    peaks.push({ frequency, magnitude: magnitudes[i] });
+  }
+}
+
+peaks.sort((a, b) => b.magnitude - a.magnitude);
+
+console.log('Top frequency components:');
+peaks.slice(0, 5).forEach((peak, i) => {
+  console.log(`  ${i + 1}. ${peak.frequency.toFixed(1)} Hz (magnitude: ${peak.magnitude.toFixed(2)})`);
+});

package/examples/vector-operations.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Example: Vector Operations
+ * Demonstrates hardware-accelerated vector math
+ */
+
+const accelerate = require('../index');
+
+console.log('Vector Operations Example');
+console.log('='.repeat(50));
+console.log('');
+
+// Create large vectors
+const size = 1000000;
+console.log(`Vector size: ${size.toLocaleString()} elements`);
+console.log('');
+
+const a = new Float64Array(size);
+const b = new Float64Array(size);
+const result = new Float64Array(size);
+
+// Fill with random data
+for (let i = 0; i < size; i++) {
+  a[i] = Math.random() * 100;
+  b[i] = Math.random() * 100;
+}
+
+// Dot product
+console.log('Computing dot product...');
+let start = process.hrtime.bigint();
+const dotProduct = accelerate.dot(a, b);
+let end = process.hrtime.bigint();
+console.log(`  Result: ${dotProduct.toFixed(2)}`);
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Sum
+console.log('Computing sum...');
+start = process.hrtime.bigint();
+const sum = accelerate.sum(a);
+end = process.hrtime.bigint();
+console.log(`  Result: ${sum.toFixed(2)}`);
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Mean
+console.log('Computing mean...');
+start = process.hrtime.bigint();
+const mean = accelerate.mean(a);
+end = process.hrtime.bigint();
+console.log(`  Result: ${mean.toFixed(2)}`);
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Vector addition
+console.log('Computing vector addition...');
+start = process.hrtime.bigint();
+accelerate.vadd(a, b, result);
+end = process.hrtime.bigint();
+console.log(`  Sample: ${a[0].toFixed(2)} + ${b[0].toFixed(2)} = ${result[0].toFixed(2)}`);
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+// Vector multiplication
+console.log('Computing vector multiplication...');
+start = process.hrtime.bigint();
+accelerate.vmul(a, b, result);
+end = process.hrtime.bigint();
+console.log(`  Sample: ${a[0].toFixed(2)} × ${b[0].toFixed(2)} = ${result[0].toFixed(2)}`);
+console.log(`  Time: ${(Number(end - start) / 1e6).toFixed(3)}ms`);
+console.log('');
+
+console.log('✓ All operations completed successfully!');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/node-accelerate",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "High-performance Apple Accelerate framework bindings for Node.js - 283x faster matrix operations on Apple Silicon",
   "main": "index.js",
   "types": "index.d.ts",
@@ -65,6 +65,7 @@
     "index.js",
     "index.d.ts",
     "README.md",
+    "examples/",
     "LICENSE",
     "scripts/"
   ]