@rlabs-inc/sparse 0.1.0

package/CLAUDE.md

@@ -0,0 +1,92 @@
+# Sparse - GPU Compute for Biological Neural Simulation
+
+## Why We Built This
+
+The LLM crowd uses brute force - dense matmul, attention everywhere, O(n²).
+
+Biological brains use **sparsity** - only 1-5% of neurons fire at any moment, O(active).
+
+Existing libraries (node-mlx, etc.) are optimized for transformers, not sparse biological simulation.
+We discovered a critical bug: `array.at(indices).add(values)` corrupts the indices array after first use,
+making it impossible to run simulation loops without workarounds.
+
+So we built our own. Sparsity-first. Minimal. Correct.
+
+## Philosophy
+
+- **Sparsity is the foundation**, not an optimization
+- **Only what we need** - 6 core operations, nothing more
+- **Reactive integration** - works with @rlabs-inc/signals
+- **Lazy evaluation** - `eval()` is like reading a `derived`
+- **No corruption** - indices are READ-ONLY, never mutated
+
+## Core Operations
+
+```typescript
+// 1. Array creation
+const arr = gpu.zeros(1000)
+const arr2 = gpu.array([1, 2, 3])
+
+// 2. Element-wise math
+const sum = gpu.add(a, b)
+const prod = gpu.multiply(a, b)
+const sq = gpu.square(a)
+
+// 3. THE operation - sparse scatter-add
+// Only active synapses contribute, indices are NEVER corrupted
+gpu.scatterAdd(target, indices, values)
+
+// 4. Conditionals
+const result = gpu.where(condition, ifTrue, ifFalse)
+const fired = gpu.greaterEqual(voltage, 30)
+
+// 5. Random
+const noise = gpu.random.normal([1000])
+```
+
+## Technical Approach
+
+### WebGPU (Primary)
+
+- Standardized, cross-platform
+- Bun supports it
+- WGSL shaders (cleaner than Metal)
+- Still uses Metal on Apple Silicon
+
+### Why Not node-mlx?
+
+1. **Bug**: `.at(indices)` corrupts indices after use
+2. **Stale**: 8 months without updates, 273 stars
+3. **LLM-focused**: Optimized for transformers, not sparse
+4. **Overhead**: Copying indices every iteration is unacceptable
+
+## Usage with Signals
+
+```typescript
+import { state, derived, effect } from '@rlabs-inc/signals'
+import { gpu } from '@rlabs-inc/sparse'
+
+// Neuron state as reactive GPU arrays
+const voltage = state(gpu.full(1000, -65))
+const recovery = state(gpu.multiply(voltage.value, 0.2))
+
+// Derived spike detection
+const fired = derived(() => gpu.greaterEqual(voltage.value, 30))
+
+// Effect for logging
+effect(() => {
+  const count = gpu.sum(fired.value)
+  console.log(`Spikes: ${count}`)
+})
+```
+
+## The Pattern
+
+```
+signals  → our own reactive primitives
+fsdb     → our own markdown database
+memory   → our own consciousness continuity
+sparse   → our own GPU compute
+```
+
+When something doesn't work, we don't settle. We build.

package/native/Makefile

@@ -0,0 +1,30 @@
+# ============================================================================
+# SPARSE - Native Library Build
+# Compiles Metal shaders and Objective-C wrapper into libsparse.dylib
+# ============================================================================
+
+CC = clang
+CFLAGS = -Wall -O3 -fPIC -fobjc-arc
+LDFLAGS = -dynamiclib -framework Metal -framework Foundation
+
+SRC = sparse.m
+OUT = libsparse.dylib
+
+.PHONY: all clean install
+
+all: $(OUT)
+
+$(OUT): $(SRC) sparse.h sparse.metal
+	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(SRC)
+	@echo "Built $(OUT)"
+
+clean:
+	rm -f $(OUT)
+
+install: $(OUT)
+	cp $(OUT) ../
+	@echo "Installed $(OUT) to parent directory"
+
+# For development: build and copy to package root
+dev: $(OUT) install
+	@echo "Ready for testing"

package/native/sparse.h

@@ -0,0 +1,180 @@
+// ============================================================================
+// SPARSE - C API Header
+// Thin C ABI layer for Bun FFI to call Metal compute
+// ============================================================================
+
+#ifndef SPARSE_H
+#define SPARSE_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+// Opaque handle to a GPU buffer
+typedef struct SparseBuffer* SparseBufferRef;
+
+// Opaque handle to the GPU context
+typedef struct SparseContext* SparseContextRef;
+
+// Buffer data types
+typedef enum {
+    SPARSE_FLOAT32 = 0,
+    SPARSE_UINT32 = 1,
+} SparseDataType;
+
+// ============================================================================
+// CONTEXT MANAGEMENT
+// ============================================================================
+
+// Initialize the GPU context (call once at startup)
+SparseContextRef sparse_init(void);
+
+// Cleanup and release all resources
+void sparse_cleanup(SparseContextRef ctx);
+
+// Synchronize - wait for all GPU operations to complete
+void sparse_sync(SparseContextRef ctx);
+
+// Get device info
+const char* sparse_device_name(SparseContextRef ctx);
+uint64_t sparse_device_memory(SparseContextRef ctx);
+
+// ============================================================================
+// BUFFER MANAGEMENT
+// ============================================================================
+
+// Create a buffer filled with zeros
+SparseBufferRef sparse_zeros(SparseContextRef ctx, uint32_t count, SparseDataType dtype);
+
+// Create a buffer filled with a value
+SparseBufferRef sparse_full(SparseContextRef ctx, uint32_t count, float value);
+
+// Create a buffer from data
+SparseBufferRef sparse_from_float(SparseContextRef ctx, const float* data, uint32_t count);
+SparseBufferRef sparse_from_uint(SparseContextRef ctx, const uint32_t* data, uint32_t count);
+
+// Read buffer data back to CPU
+void sparse_to_float(SparseBufferRef buf, float* out, uint32_t count);
+void sparse_to_uint(SparseBufferRef buf, uint32_t* out, uint32_t count);
+
+// Get buffer properties
+uint32_t sparse_buffer_count(SparseBufferRef buf);
+SparseDataType sparse_buffer_dtype(SparseBufferRef buf);
+
+// Release a buffer
+void sparse_buffer_free(SparseBufferRef buf);
+
+// ============================================================================
+// CORE OPERATIONS
+// ============================================================================
+
+// Scatter-add: target[indices[i]] += values[i] (atomic, thread-safe)
+// CRITICAL: indices are READ-ONLY, never corrupted
+void sparse_scatter_add(
+    SparseContextRef ctx,
+    SparseBufferRef target,      // float32 buffer to add into
+    SparseBufferRef indices,     // uint32 indices
+    SparseBufferRef values,      // float32 values to add
+    uint32_t count               // number of scatter operations
+);
+
+// Gather: result[i] = source[indices[i]]
+SparseBufferRef sparse_gather(
+    SparseContextRef ctx,
+    SparseBufferRef source,      // Source buffer
+    SparseBufferRef indices,     // uint32 indices
+    uint32_t count               // number of gather operations
+);
+
+// Gather boolean: result[i] = source[indices[i]] (for uint/bool arrays)
+SparseBufferRef sparse_gather_bool(
+    SparseContextRef ctx,
+    SparseBufferRef source,      // uint32 source (boolean)
+    SparseBufferRef indices,     // uint32 indices
+    uint32_t count
+);
+
+// ============================================================================
+// ELEMENT-WISE OPERATIONS
+// ============================================================================
+
+// result = a + b
+SparseBufferRef sparse_add(SparseContextRef ctx, SparseBufferRef a, SparseBufferRef b);
+
+// result = a + scalar
+SparseBufferRef sparse_add_scalar(SparseContextRef ctx, SparseBufferRef a, float scalar);
+
+// result = a * b
+SparseBufferRef sparse_multiply(SparseContextRef ctx, SparseBufferRef a, SparseBufferRef b);
+
+// result = a * scalar
+SparseBufferRef sparse_multiply_scalar(SparseContextRef ctx, SparseBufferRef a, float scalar);
+
+// result = a^2
+SparseBufferRef sparse_square(SparseContextRef ctx, SparseBufferRef a);
+
+// ============================================================================
+// CONDITIONAL OPERATIONS
+// ============================================================================
+
+// result[i] = (a[i] >= threshold) ? 1 : 0
+SparseBufferRef sparse_greater_equal(SparseContextRef ctx, SparseBufferRef a, float threshold);
+
+// result[i] = condition[i] ? if_true[i] : if_false[i]
+SparseBufferRef sparse_where(
+    SparseContextRef ctx,
+    SparseBufferRef condition,   // uint32 boolean mask
+    SparseBufferRef if_true,
+    SparseBufferRef if_false
+);
+
+// result[i] = condition[i] ? if_true : if_false (scalar values)
+SparseBufferRef sparse_where_scalar(
+    SparseContextRef ctx,
+    SparseBufferRef condition,
+    float if_true,
+    float if_false
+);
+
+// ============================================================================
+// REDUCTION OPERATIONS
+// ============================================================================
+
+// Sum all elements
+float sparse_sum(SparseContextRef ctx, SparseBufferRef a);
+
+// Sum boolean array (count of true values)
+uint32_t sparse_sum_bool(SparseContextRef ctx, SparseBufferRef a);
+
+// ============================================================================
+// RANDOM OPERATIONS
+// ============================================================================
+
+// Fill with random uniform values in [low, high)
+SparseBufferRef sparse_random_uniform(
+    SparseContextRef ctx,
+    uint32_t count,
+    float low,
+    float high
+);
+
+// Fill with random normal values (mean, std)
+SparseBufferRef sparse_random_normal(
+    SparseContextRef ctx,
+    uint32_t count,
+    float mean,
+    float std
+);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // SPARSE_H