@oxide-js/spiking 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @oxide-js/spiking
 
+## 1.3.0
+
+### Minor Changes
+
+- 1f6489c: - Added `SpikingDenseBPTT` temporal pooler with Sequence-as-Time dynamics.
+  - Implemented Spike-Count Accumulation with L2 Normalization to solve membrane saturation in long sequences.
+  - Updated documentation for SpikingDenseBPTT in API layers.
+
+## 1.2.0
+
+### Minor Changes
+
+- f0b623b: Refactored Native Rust Backend to implement Rayon parallelism and added Heterogeneous Neuron Dynamics
+
+  - **Parallel Computing**: Integrated `rayon` into the native Rust backend to parallelize operations (`lifStep`, `surrogateMask`, `dotProduct`, `deltaUpdates`).
+  - **Heterogeneous Neuron Dynamics**: Decoupled `beta` (Leakage) and `threshold` scalars into random per-neuron array buffers for model stochasticity.
+  - **Improved Mathematical Stability**: Enforced membrane potential clamping at `1.0` and strict weight/bias clipping within the `[-1.0, 1.0]` range to prevent gradient explosions during Hebbian Updates.
+  - **Native Data Races Handled**: Safely extracted slice pointers before processing `Float32Array` buffers with Rayon to guarantee thread-safe (Send + Sync) execution across parallel units.
+
 ## 1.1.0
 
 ### Minor Changes

package/index.cjs

@@ -0,0 +1,322 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'spiking-native.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.android-arm64.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'spiking-native.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'spiking-native.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'spiking-native.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'spiking-native.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'spiking-native.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./spiking-native.darwin-universal.node')
+      } else {
+        nativeBinding = require('@oxide-js/spiking-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'spiking-native.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.darwin-x64.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'spiking-native.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'spiking-native.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./spiking-native.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@oxide-js/spiking-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'spiking-native.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./spiking-native.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@oxide-js/spiking-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'spiking-native.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./spiking-native.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@oxide-js/spiking-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { NativeSpikingNetwork, dotProductAddOnlyNative, lifStepNative, maskSurrogateNative, applyAddOnlyDeltaNative, learnHebbianNative, supervisedStdpNative, learnContrastiveBatchNative } = nativeBinding
+
+module.exports.NativeSpikingNetwork = NativeSpikingNetwork
+module.exports.dotProductAddOnlyNative = dotProductAddOnlyNative
+module.exports.lifStepNative = lifStepNative
+module.exports.maskSurrogateNative = maskSurrogateNative
+module.exports.applyAddOnlyDeltaNative = applyAddOnlyDeltaNative
+module.exports.learnHebbianNative = learnHebbianNative
+module.exports.supervisedStdpNative = supervisedStdpNative
+module.exports.learnContrastiveBatchNative = learnContrastiveBatchNative

package/index.d.ts

@@ -4,16 +4,8 @@
 /* auto-generated by NAPI-RS */
 
 export declare function dotProductAddOnlyNative(aData: Float32Array, aRowsOrig: number, aColsOrig: number, bData: Float32Array, bRowsOrig: number, bColsOrig: number, transA: boolean, transB: boolean, outData: Float32Array): void
-export declare class NativeSpikingNetwork {
-  constructor(numNeurons: number, beta: number, defaultThreshold: number)
-  connect(pre: number, post: number, weight: number): void
-  injectCurrent(neuronIdx: number, current: number): void
-  inhibitRange(startIdx: number, endIdx: number, exceptIdx: number, current: number): void
-  step(): void
-  resetState(): void
-  getSpikes(): Array<number>
-  getPotentials(): Array<number>
-  updateStdp(learningRate: number, tauPlus: number, tauMinus: number, aPlus: number, aMinus: number, wMax: number, wMin: number): void
-  saveToFile(filepath: string): void
-  loadFromFile(filepath: string): void
-}
+export declare function lifStepNative(potentials: Float32Array, dot: Float32Array, spikes: Float32Array, lastPotentials: Float32Array, beta: Float32Array, threshold: Float32Array): void
+export declare function maskSurrogateNative(errorSignal: Float32Array, potentials: Float32Array, threshold: Float32Array, windowSize: number): void
+export declare function applyAddOnlyDeltaNative(kernel: Float32Array, bias: Float32Array, inputs: Float32Array, errorSignal: Float32Array, learningRate: number, batch: number, inFeatures: number, units: number, useBias: boolean): void
+export declare function applyEmbeddingDeltaNative(embeddings: Float32Array, inputs: Float32Array, errorSignal: Float32Array, learningRate: number, inputDim: number, outputDim: number): void
+export declare function contrastiveHebbianNative(spikes: Float32Array, errData: Float32Array, numPairs: number, sequenceLength: number, dModel: number): number

package/index.js

@@ -310,7 +310,11 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { NativeSpikingNetwork, dotProductAddOnlyNative } = nativeBinding
+const { dotProductAddOnlyNative, lifStepNative, maskSurrogateNative, applyAddOnlyDeltaNative, applyEmbeddingDeltaNative, contrastiveHebbianNative } = nativeBinding
 
-module.exports.NativeSpikingNetwork = NativeSpikingNetwork
 module.exports.dotProductAddOnlyNative = dotProductAddOnlyNative
+module.exports.lifStepNative = lifStepNative
+module.exports.maskSurrogateNative = maskSurrogateNative
+module.exports.applyAddOnlyDeltaNative = applyAddOnlyDeltaNative
+module.exports.applyEmbeddingDeltaNative = applyEmbeddingDeltaNative
+module.exports.contrastiveHebbianNative = contrastiveHebbianNative

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxide-js/spiking",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Oxide-JS Spiking: Add-Only Event-Driven Spiking Neural Network implementation.",
   "repository": {

package/src/index.ts

@@ -1,5 +1,7 @@
-
 export { default as dotProductAddOnly } from "./math/dotProductAddOnly.js";
 export { SpikingDense, type SpikingDenseConfig } from "./layers/SpikingDense.js";
+export { SpikingDenseBPTT, type SpikingDenseBPTTConfig } from "./layers/SpikingDenseBPTT.js";
 export { SpikingEmbedding, type SpikingEmbeddingConfig } from "./layers/SpikingEmbedding.js";
-export { SpikingSentenceEmbedder, type SpikingSentenceConfig } from "./models/SpikingSentenceEmbedder.js";
+export { SpikingSelfAttention, type SpikingSelfAttentionConfig } from "./layers/SpikingSelfAttention.js";
+// export { SpikingSentenceEmbedder, type SpikingSentenceConfig } from "./models/SpikingSentenceEmbedder.js";
+export { contrastiveHebbianNativeWrapper, isNativeAvailable } from "./native_backend.js";

package/src/layers/SpikingDense.ts

@@ -12,8 +12,8 @@ export interface SpikingDenseConfig extends LayerConfig {
   useBias?: boolean;
   kernelInitializer?: string;
   biasInitializer?: string;
-  beta?: number;
-  threshold?: number;
+  betaRange?: [number, number];
+  thresholdRange?: [number, number];
 }
 
 export class SpikingDense extends BaseLayer {
@@ -21,8 +21,10 @@ export class SpikingDense extends BaseLayer {
   public useBias: boolean;
   public kernelInitializer: string;
   public biasInitializer: string;
-  public beta: number;
-  public threshold: number;
+  public betaRange: [number, number];
+  public thresholdRange: [number, number];
+  public beta!: Float32Array;
+  public threshold!: Float32Array;
 
   public potentials!: Matrix;
   public lastPotentials?: Matrix;
@@ -43,8 +45,8 @@ export class SpikingDense extends BaseLayer {
     this.useBias = config.useBias ?? true;
     this.kernelInitializer = config.kernelInitializer || "glorot_normal";
     this.biasInitializer = config.biasInitializer || "zeros";
-    this.beta = config.beta ?? 0.9;
-    this.threshold = config.threshold ?? 1.0;
+    this.betaRange = config.betaRange || [0.8, 0.99];
+    this.thresholdRange = config.thresholdRange || [0.5, 1.0];
   }
 
   public computeOutputShape(inputShape: number[]): number[] {
@@ -65,19 +67,31 @@ export class SpikingDense extends BaseLayer {
       this.addParameter("bias", biasVal, true, [this.units, 1]);
     }
     
+    // Inisialisasi beta dan threshold secara acak untuk setiap neuron
+    this.beta = new Float32Array(this.units);
+    this.threshold = new Float32Array(this.units);
+    for (let i = 0; i < this.units; i++) {
+        this.beta[i] = this.betaRange[0] + Math.random() * (this.betaRange[1] - this.betaRange[0]);
+        this.threshold[i] = this.thresholdRange[0] + Math.random() * (this.thresholdRange[1] - this.thresholdRange[0]);
+    }
+    
     // Inisialisasi state
     this.potentials = Matrix.fromFlat(new Float32Array(this.units), [1, this.units]); 
   }
 
+  private outSpikesDataBuffer?: Float32Array;
+
   private ensurePotentialsShape(batch: number) {
-    if (this.potentials._shape[0] !== batch) {
+    if (this.potentials._shape[0] !== batch || !this.outSpikesDataBuffer) {
        this.potentials = Matrix.fromFlat(new Float32Array(batch * this.units), [batch, this.units]);
+       this.outSpikesDataBuffer = new Float32Array(batch * this.units);
+       this.lastPotentials = Matrix.fromFlat(new Float32Array(batch * this.units), [batch, this.units]);
     }
   }
 
   public resetState() {
      if (this.potentials) this.potentials._data.fill(0);
-     this.lastPotentials = undefined;
+     if (this.lastPotentials) this.lastPotentials._data.fill(0);
      this.lastInputs = undefined;
      this.lastSpikes = undefined;
   }
@@ -96,35 +110,40 @@ export class SpikingDense extends BaseLayer {
     }
 
     // 3 & 4. Leaky Integrate, Fire & Reset
-    const outData = new Float32Array(batch * this.units);
+    const outData = this.outSpikesDataBuffer!;
+    outData.fill(0);
     const outSpikes = Matrix.fromFlat(outData, [batch, this.units]);
-    this.lastPotentials = Matrix.fromFlat(new Float32Array(batch * this.units), [batch, this.units]);
 
     if (isNativeAvailable()) {
         lifStepNativeWrapper(
             this.potentials._data,
             dot._data,
             outSpikes._data,
-            this.lastPotentials._data,
+            this.lastPotentials!._data,
             this.beta,
             this.threshold
         );
     } else {
         const potData = this.potentials._data;
         const dotData = dot._data;
-        const thresh = this.threshold;
-        const lpData = this.lastPotentials._data;
-        for (let i = 0; i < potData.length; i++) {
-            potData[i] = (potData[i] * this.beta) + dotData[i];
-            lpData[i] = potData[i];
-        }
-        for (let i = 0; i < potData.length; i++) {
-          if (potData[i] >= thresh) {
-            outData[i] = 1;
-            potData[i] -= thresh;
-          } else {
-            outData[i] = 0;
-          }
+        const lpData = this.lastPotentials!._data;
+        
+        for (let b = 0; b < batch; b++) {
+            const offset = b * this.units;
+            for (let i = 0; i < this.units; i++) {
+                const idx = offset + i;
+                potData[idx] = Math.min((potData[idx] * this.beta[i]) + dotData[idx], 1.0); // Clamp potential max 1.0
+                lpData[idx] = potData[idx];
+            }
+            for (let i = 0; i < this.units; i++) {
+                const idx = offset + i;
+                if (potData[idx] >= this.threshold[i]) {
+                    outData[idx] = 1;
+                    potData[idx] -= this.threshold[i];
+                } else {
+                    outData[idx] = 0;
+                }
+            }
         }
     }
 
@@ -146,22 +165,26 @@ export class SpikingDense extends BaseLayer {
       
       // Surrogate Mask: Boxcar (Murni Add-Only mask, tanpa perkalian float!)
       if (this.lastPotentials) {
+          const eData = eHidden._data;
+          const pData = this.lastPotentials._data;
+          const windowSize = 1.0; 
+          
           if (isNativeAvailable()) {
               maskSurrogateNativeWrapper(
-                  eHidden._data, 
-                  this.lastPotentials._data, 
-                  this.threshold, 
-                  1.0
+                  eData,
+                  pData,
+                  this.threshold,
+                  windowSize
               );
           } else {
-              const eData = eHidden._data;
-              const pData = this.lastPotentials._data;
-              const thresh = this.threshold;
-              const windowSize = 1.0; 
-
-              for (let i = 0; i < eData.length; i++) {
-                  if (Math.abs(pData[i] - thresh) > windowSize) {
-                      eData[i] = 0; 
+              const batch = eHidden._shape[0];
+              for (let b = 0; b < batch; b++) {
+                  const offset = b * this.units;
+                  for (let i = 0; i < this.units; i++) {
+                      const idx = offset + i;
+                      if (Math.abs(pData[idx] - this.threshold[i]) > windowSize) {
+                          eData[idx] = 0; 
+                      }
                   }
               }
           }
@@ -197,6 +220,12 @@ export class SpikingDense extends BaseLayer {
               units,
               this.useBias
           );
+          
+          for(let i = 0; i < kernel.length; i++) kernel[i] = Math.max(-1.0, Math.min(1.0, kernel[i]));
+          if (this.useBias && this.bias) {
+              const biasData = this.bias._data;
+              for(let i = 0; i < biasData.length; i++) biasData[i] = Math.max(-1.0, Math.min(1.0, biasData[i]));
+          }
       } else {
           // Delta rule add-only
           for (let b = 0; b < batch; b++) {
@@ -204,11 +233,12 @@ export class SpikingDense extends BaseLayer {
               const errOffset = b * units;
               
               for (let k = 0; k < inFeatures; k++) {
-                  // HANYA update jika input menyala (Spike = 1) -> Add Only Update!
-                  if (inputs[inOffset + k] === 1) { 
+                  // HANYA update jika input menyala (Spike > 0.5) -> Add Only Update!
+                  if (inputs[inOffset + k] > 0.5) { 
                       const kOffset = k * units;
                       for (let j = 0; j < units; j++) {
                           kernel[kOffset + j] += learningRate * err[errOffset + j];
+                          kernel[kOffset + j] = Math.max(-1.0, Math.min(1.0, kernel[kOffset + j]));
                       }
                   }
               }
@@ -216,7 +246,8 @@ export class SpikingDense extends BaseLayer {
               if (this.useBias && this.bias) {
                   const biasData = this.bias._data;
                   for (let j = 0; j < units; j++) {
-                      biasData[j] += learningRate * err[errOffset + j];
+                      biasData[j] += (learningRate * err[errOffset + j]) / batch;
+                      biasData[j] = Math.max(-1.0, Math.min(1.0, biasData[j]));
                   }
               }
           }
@@ -229,9 +260,7 @@ export class SpikingDense extends BaseLayer {
       units: this.units,
       useBias: this.useBias,
       kernelInitializer: this.kernelInitializer,
-      biasInitializer: this.biasInitializer,
-      beta: this.beta,
-      threshold: this.threshold
+      biasInitializer: this.biasInitializer
     };
   }
 }