d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
412 lines
11 KiB
Markdown
412 lines
11 KiB
Markdown
# ruvector-nervous-system-wasm
|
|
|
|
Bio-inspired neural system components for browser execution via WebAssembly.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install ruvector-nervous-system-wasm
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```javascript
|
|
import init, {
|
|
BTSPLayer,
|
|
BTSPAssociativeMemory,
|
|
Hypervector,
|
|
HdcMemory,
|
|
WTALayer,
|
|
KWTALayer,
|
|
GlobalWorkspace,
|
|
WorkspaceItem,
|
|
version,
|
|
available_mechanisms,
|
|
performance_targets,
|
|
} from 'ruvector-nervous-system-wasm';
|
|
|
|
// Initialize WASM module (required before using any components)
|
|
await init();
|
|
|
|
console.log('Version:', version());
|
|
console.log('Available mechanisms:', available_mechanisms());
|
|
```
|
|
|
|
## Components
|
|
|
|
### 1. BTSP (Behavioral Timescale Synaptic Plasticity)
|
|
|
|
One-shot learning based on Bittner et al. 2017 hippocampal place field formation.
|
|
|
|
#### BTSPLayer
|
|
|
|
```javascript
|
|
// Create a BTSP layer with 100 synapses and 2000ms time constant
|
|
const btsp = new BTSPLayer(100, 2000.0);
|
|
|
|
// One-shot learning: associate pattern with target value immediately
|
|
const pattern = new Float32Array(100).fill(0.1);
|
|
btsp.one_shot_associate(pattern, 1.0);
|
|
|
|
// Forward pass: compute output for input pattern
|
|
const output = btsp.forward(pattern);
|
|
console.log('Output:', output);
|
|
|
|
// Get layer properties
|
|
console.log('Size:', btsp.size);
|
|
console.log('Weights:', btsp.get_weights());
|
|
|
|
// Reset layer to initial random state
|
|
btsp.reset();
|
|
```
|
|
|
|
#### BTSPSynapse
|
|
|
|
```javascript
|
|
// Create individual synapse with initial weight and time constant
|
|
const synapse = new BTSPSynapse(0.5, 2000.0);
|
|
|
|
// Update synapse based on neural activity
|
|
synapse.update(
|
|
true, // presynaptic_active: presynaptic neuron is firing
|
|
true, // plateau_signal: dendritic plateau detected
|
|
10.0 // dt: time step in milliseconds
|
|
);
|
|
|
|
// Get synapse state
|
|
console.log('Weight:', synapse.weight);
|
|
console.log('Eligibility trace:', synapse.eligibility_trace);
|
|
|
|
// Compute synaptic output
|
|
const output = synapse.forward(0.8);
|
|
```
|
|
|
|
#### BTSPAssociativeMemory
|
|
|
|
```javascript
|
|
// Create key-value associative memory (input_size, output_size)
|
|
const memory = new BTSPAssociativeMemory(128, 64);
|
|
|
|
// Store key-value pair in one shot (no iteration needed)
|
|
const key = new Float32Array(128).fill(0.1);
|
|
const value = new Float32Array(64).fill(0.5);
|
|
memory.store_one_shot(key, value);
|
|
|
|
// Retrieve value from key
|
|
const retrieved = memory.retrieve(key);
|
|
console.log('Retrieved value:', retrieved);
|
|
|
|
// Get memory dimensions
|
|
console.log('Dimensions:', memory.dimensions());
|
|
```
|
|
|
|
### 2. HDC (Hyperdimensional Computing)
|
|
|
|
10,000-bit binary hypervectors with ultra-fast operations.
|
|
|
|
#### Hypervector
|
|
|
|
```javascript
|
|
// Create hypervectors
|
|
const hv1 = new Hypervector(); // Zero vector
|
|
const hv2 = Hypervector.random(); // Random (~50% bits set)
|
|
const hv3 = Hypervector.from_seed(42); // Reproducible from seed
|
|
|
|
// Binding (XOR) - associative, commutative, self-inverse
|
|
const bound = hv2.bind(hv3);
|
|
console.log('Binding is self-inverse:', hv2.similarity(bound.bind(hv3)) > 0.99);
|
|
|
|
// Similarity: 1.0 = identical, 0.0 = orthogonal, -1.0 = opposite
|
|
const sim = hv2.similarity(hv3);
|
|
console.log('Similarity:', sim);
|
|
|
|
// Hamming distance (differing bits)
|
|
const distance = hv2.hamming_distance(hv3);
|
|
console.log('Hamming distance:', distance);
|
|
|
|
// Population count (set bits)
|
|
console.log('Popcount:', hv2.popcount());
|
|
|
|
// Bundle 3 vectors by majority voting
|
|
const bundled = Hypervector.bundle_3(hv1, hv2, hv3);
|
|
|
|
// Serialization
|
|
const bytes = hv2.to_bytes();
|
|
const restored = Hypervector.from_bytes(bytes);
|
|
console.log('Restored correctly:', hv2.similarity(restored) === 1.0);
|
|
|
|
// Properties
|
|
console.log('Dimension:', hv2.dimension); // 10000
|
|
```
|
|
|
|
#### HdcMemory
|
|
|
|
```javascript
|
|
// Create memory store
|
|
const hdcMem = new HdcMemory();
|
|
|
|
// Store labeled hypervectors
|
|
const apple = Hypervector.random();
|
|
const orange = Hypervector.random();
|
|
const banana = Hypervector.random();
|
|
|
|
hdcMem.store("apple", apple);
|
|
hdcMem.store("orange", orange);
|
|
hdcMem.store("banana", banana);
|
|
|
|
// Retrieve similar vectors above threshold
|
|
const results = hdcMem.retrieve(apple, 0.5);
|
|
console.log('Similar to apple:', results);
|
|
// Returns: [["apple", 1.0], ...]
|
|
|
|
// Find top-k most similar
|
|
const topK = hdcMem.top_k(apple, 2);
|
|
console.log('Top 2:', topK);
|
|
|
|
// Query memory
|
|
console.log('Size:', hdcMem.size);
|
|
console.log('Has apple:', hdcMem.has("apple"));
|
|
|
|
// Get specific vector
|
|
const appleVec = hdcMem.get("apple");
|
|
|
|
// Clear memory
|
|
hdcMem.clear();
|
|
```
|
|
|
|
### 3. WTA (Winner-Take-All)
|
|
|
|
Instant decisions via neural competition.
|
|
|
|
#### WTALayer
|
|
|
|
```javascript
|
|
// Create WTA layer with 1000 neurons, threshold 0.5, inhibition strength 0.8
|
|
const wta = new WTALayer(1000, 0.5, 0.8);
|
|
|
|
// Competition: returns winning neuron index (or -1 if none exceeds threshold)
|
|
const activations = new Float32Array(1000);
|
|
activations[42] = 0.9; // Make neuron 42 the winner
|
|
activations[100] = 0.7;
|
|
|
|
const winner = wta.compete(activations);
|
|
console.log('Winner:', winner); // 42
|
|
|
|
// Soft competition: normalized activations (softmax-like)
|
|
const softActivations = wta.compete_soft(activations);
|
|
console.log('Soft activations:', softActivations);
|
|
|
|
// Get membrane potentials
|
|
const membranes = wta.get_membranes();
|
|
|
|
// Reset layer state
|
|
wta.reset();
|
|
|
|
// Configure refractory period (prevents winner from winning again immediately)
|
|
wta.set_refractory_period(20);
|
|
|
|
// Properties
|
|
console.log('Size:', wta.size);
|
|
```
|
|
|
|
#### KWTALayer
|
|
|
|
```javascript
|
|
// Create K-WTA layer: 1000 neurons, select top 50
|
|
const kwta = new KWTALayer(1000, 50);
|
|
|
|
// Optional: set activation threshold
|
|
kwta.with_threshold(0.1);
|
|
|
|
const activations = new Float32Array(1000);
|
|
for (let i = 0; i < 1000; i++) {
|
|
activations[i] = Math.random();
|
|
}
|
|
|
|
// Select top-k neuron indices (sorted by activation, descending)
|
|
const winners = kwta.select(activations);
|
|
console.log('Winner indices:', winners); // Uint32Array of 50 indices
|
|
|
|
// Select with values: array of [index, value] pairs
|
|
const winnersWithValues = kwta.select_with_values(activations);
|
|
console.log('Winners with values:', winnersWithValues);
|
|
|
|
// Get sparse activation vector (only top-k preserved, rest zeroed)
|
|
const sparse = kwta.sparse_activations(activations);
|
|
console.log('Sparse vector:', sparse);
|
|
|
|
// Properties
|
|
console.log('k:', kwta.k); // 50
|
|
console.log('Size:', kwta.size); // 1000
|
|
```
|
|
|
|
### 4. Global Workspace
|
|
|
|
Attention bottleneck based on Global Workspace Theory (Baars, Dehaene).
|
|
|
|
#### WorkspaceItem
|
|
|
|
```javascript
|
|
// Create a workspace item
|
|
const content = new Float32Array([1.0, 2.0, 3.0, 4.0]);
|
|
const item = new WorkspaceItem(
|
|
content, // content vector
|
|
0.9, // salience (importance)
|
|
1, // source_module ID
|
|
Date.now() // timestamp
|
|
);
|
|
|
|
// Create with custom decay and lifetime
|
|
const itemWithDecay = WorkspaceItem.with_decay(
|
|
content,
|
|
0.9, // salience
|
|
1, // source_module
|
|
Date.now(), // timestamp
|
|
0.95, // decay_rate per timestep
|
|
5000 // lifetime in ms
|
|
);
|
|
|
|
// Access item properties
|
|
console.log('Salience:', item.salience);
|
|
console.log('Source module:', item.source_module);
|
|
console.log('Timestamp:', item.timestamp);
|
|
console.log('ID:', item.id);
|
|
console.log('Content:', item.get_content());
|
|
console.log('Magnitude:', item.magnitude());
|
|
|
|
// Update salience
|
|
item.update_salience(0.8);
|
|
|
|
// Apply temporal decay
|
|
item.apply_decay(1.0); // dt = 1.0
|
|
|
|
// Check expiration
|
|
console.log('Expired:', item.is_expired(Date.now() + 10000));
|
|
```
|
|
|
|
#### GlobalWorkspace
|
|
|
|
```javascript
|
|
// Create workspace with capacity 7 (Miller's Law: 7 +/- 2)
|
|
const workspace = new GlobalWorkspace(7);
|
|
|
|
// Or with custom salience threshold
|
|
const workspace2 = GlobalWorkspace.with_threshold(7, 0.2);
|
|
|
|
// Configure decay rate
|
|
workspace.set_decay_rate(0.95);
|
|
|
|
// Broadcast items to workspace (returns true if accepted)
|
|
const item1 = new WorkspaceItem(new Float32Array([1, 2, 3]), 0.9, 1, Date.now());
|
|
const item2 = new WorkspaceItem(new Float32Array([4, 5, 6]), 0.7, 2, Date.now());
|
|
|
|
const accepted1 = workspace.broadcast(item1);
|
|
const accepted2 = workspace.broadcast(item2);
|
|
console.log('Item 1 accepted:', accepted1);
|
|
console.log('Item 2 accepted:', accepted2);
|
|
|
|
// Run competitive dynamics (decay + pruning)
|
|
workspace.compete();
|
|
|
|
// Retrieve all current representations
|
|
const allItems = workspace.retrieve();
|
|
console.log('All items:', allItems);
|
|
// Returns: [{ content: [...], salience: ..., source_module: ..., timestamp: ..., id: ... }, ...]
|
|
|
|
// Retrieve top-k most salient
|
|
const topItems = workspace.retrieve_top_k(3);
|
|
console.log('Top 3:', topItems);
|
|
|
|
// Get most salient item
|
|
const mostSalient = workspace.most_salient();
|
|
if (mostSalient) {
|
|
console.log('Most salient:', mostSalient.salience);
|
|
}
|
|
|
|
// Query workspace state
|
|
console.log('Length:', workspace.len);
|
|
console.log('Capacity:', workspace.capacity);
|
|
console.log('Is full:', workspace.is_full());
|
|
console.log('Is empty:', workspace.is_empty());
|
|
console.log('Available slots:', workspace.available_slots());
|
|
console.log('Current load:', workspace.current_load()); // 0.0 to 1.0
|
|
console.log('Average salience:', workspace.average_salience());
|
|
|
|
// Clear workspace
|
|
workspace.clear();
|
|
```
|
|
|
|
## Performance Targets
|
|
|
|
| Component | Target | Method |
|
|
|-----------|--------|--------|
|
|
| BTSP one_shot_associate | Immediate | Gradient normalization |
|
|
| HDC bind | <50ns | XOR operation |
|
|
| HDC similarity | <100ns | Hamming distance + unrolled popcount |
|
|
| WTA compete | <1us | Single-pass argmax |
|
|
| K-WTA select | <10us | Partial sort (O(n + k log k)) |
|
|
| Workspace broadcast | <10us | Competition |
|
|
|
|
## Bundle Size
|
|
|
|
- WASM binary: ~178 KB
|
|
- JavaScript glue: ~54 KB
|
|
- TypeScript definitions: ~17 KB
|
|
|
|
## Biological References
|
|
|
|
| Mechanism | Reference |
|
|
|-----------|-----------|
|
|
| BTSP | Bittner et al. 2017 - Hippocampal place fields |
|
|
| HDC | Kanerva 1988, Plate 2003 - Hyperdimensional computing |
|
|
| WTA | Cortical microcircuits - Lateral inhibition |
|
|
| Global Workspace | Baars 1988, Dehaene 2014 - Consciousness and attention |
|
|
|
|
## Utility Functions
|
|
|
|
```javascript
|
|
// Get crate version
|
|
console.log(version()); // "0.1.0"
|
|
|
|
// List available mechanisms with descriptions
|
|
console.log(available_mechanisms());
|
|
// [["btsp", "Behavioral Timescale Synaptic Plasticity - One-shot learning"], ...]
|
|
|
|
// Get performance targets
|
|
console.log(performance_targets());
|
|
// [["btsp_one_shot", "Immediate (no iteration)"], ...]
|
|
|
|
// Get biological references
|
|
console.log(biological_references());
|
|
// [["BTSP", "Bittner et al. 2017 - Hippocampal place fields"], ...]
|
|
```
|
|
|
|
## TypeScript Support
|
|
|
|
Full TypeScript definitions are included. All classes and functions are fully typed:
|
|
|
|
```typescript
|
|
import init, {
|
|
BTSPLayer,
|
|
BTSPSynapse,
|
|
BTSPAssociativeMemory,
|
|
Hypervector,
|
|
HdcMemory,
|
|
WTALayer,
|
|
KWTALayer,
|
|
GlobalWorkspace,
|
|
WorkspaceItem,
|
|
} from 'ruvector-nervous-system-wasm';
|
|
|
|
await init();
|
|
|
|
const layer: BTSPLayer = new BTSPLayer(100, 2000.0);
|
|
const hv: Hypervector = Hypervector.random();
|
|
const wta: WTALayer = new WTALayer(1000, 0.5, 0.8);
|
|
const ws: GlobalWorkspace = new GlobalWorkspace(7);
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|