scalar-autograd 0.1.7 → 0.1.9

package/dist/GraphBuilder.js

@@ -0,0 +1,237 @@
+import { Value } from './Value';
+// 32-bit primes for mixing
+const PRIMES_32 = [
+    2654435761, // Golden ratio prime
+    805459861,
+    3266489917,
+    4101842887,
+    2484345967,
+    3369493747,
+    1505335857,
+    1267890027,
+];
+// Operation hash constants (same as GraphHashCanonicalizer)
+const OP_HASHES = {
+    '+': { h1: 0x9e3779b9, h2: 0x85ebca6b },
+    '-': { h1: 0xc2b2ae35, h2: 0x27d4eb2f },
+    '*': { h1: 0x165667b1, h2: 0xd3a2646c },
+    '/': { h1: 0xfd7046c5, h2: 0xb55a4f09 },
+    'pow': { h1: 0x5f356495, h2: 0x3c6ef372 },
+    'powValue': { h1: 0x5f356495, h2: 0x3c6ef372 },
+    'sqrt': { h1: 0x8f1bbcdc, h2: 0x42a5c977 },
+    'exp': { h1: 0x1e3779b9, h2: 0x95ebca6b },
+    'log': { h1: 0x2e3779b9, h2: 0xa5ebca6b },
+    'abs': { h1: 0x3e3779b9, h2: 0xb5ebca6b },
+    'square': { h1: 0x4e3779b9, h2: 0xc5ebca6b },
+    'sin': { h1: 0x6e3779b9, h2: 0xe5ebca6b },
+    'cos': { h1: 0x7e3779b9, h2: 0xf5ebca6b },
+    'tan': { h1: 0x8e3779b9, h2: 0x15ebca6b },
+    'asin': { h1: 0x9e3779b9, h2: 0x25ebca6b },
+    'acos': { h1: 0xae3779b9, h2: 0x35ebca6b },
+    'atan': { h1: 0xbe3779b9, h2: 0x45ebca6b },
+    'atan2': { h1: 0xce3779b9, h2: 0x55ebca6b },
+    'min': { h1: 0xde3779b9, h2: 0x65ebca6b },
+    'max': { h1: 0xee3779b9, h2: 0x75ebca6b },
+    'sigmoid': { h1: 0xfe3779b9, h2: 0x85ebca6b },
+    'tanh': { h1: 0x1f3779b9, h2: 0x95ebca6b },
+    'relu': { h1: 0x2f3779b9, h2: 0xa5ebca6b },
+    'softplus': { h1: 0x3f3779b9, h2: 0xb5ebca6b },
+    'sum': { h1: 0x9e3779b9, h2: 0x85ebca6b },
+    'eigenvalue_custom': { h1: 0x4f3779b9, h2: 0xc5ebca6b },
+};
+function getOpHash(op) {
+    if (OP_HASHES[op]) {
+        return OP_HASHES[op];
+    }
+    // Fallback for unknown ops
+    let h1 = 2166136261;
+    let h2 = 5381;
+    for (let i = 0; i < op.length; i++) {
+        const c = op.charCodeAt(i);
+        h1 = (h1 ^ c) >>> 0;
+        h1 = Math.imul(h1, 16777619);
+        h2 = ((h2 << 5) + h2 + c) >>> 0;
+    }
+    return { h1: h1 >>> 0, h2: h2 >>> 0 };
+}
+function combineHashes(h1, h2, position = 0) {
+    const p1 = PRIMES_32[position % PRIMES_32.length];
+    const p2 = PRIMES_32[(position + 1) % PRIMES_32.length];
+    return {
+        h1: (h1.h1 ^ Math.imul(h2.h1, p1)) >>> 0,
+        h2: (h1.h2 ^ Math.imul(h2.h2, p2)) >>> 0
+    };
+}
+function hashLeaf(leafIndex, hasGrad) {
+    const gradMask = hasGrad ? 0x12345678 : 0;
+    return {
+        h1: (leafIndex * PRIMES_32[0] ^ gradMask) >>> 0,
+        h2: (leafIndex * PRIMES_32[1] ^ (gradMask << 8)) >>> 0
+    };
+}
+/**
+ * Incremental graph builder that tracks structure during construction.
+ *
+ * Usage:
+ * ```typescript
+ * const builder = new GraphBuilder(knownParams);
+ * const result = builder.build(() => {
+ *   const a = V.add(params[0], params[1]);
+ *   const b = V.mul(a, V.C(2));
+ *   return b;
+ * });
+ * // result.signature.hash - for kernel lookup
+ * // result.signature.leaves - for index mapping at execution time
+ * ```
+ */
+export class GraphBuilder {
+    leaves = [];
+    leafIndexMap = new Map();
+    knownParams;
+    operations = [];
+    /**
+     * Create a new graph builder.
+     * @param knownParams - Parameters that are known upfront (will be indexed first)
+     */
+    constructor(knownParams = []) {
+        this.knownParams = new Set(knownParams);
+        // Pre-register known parameters
+        for (const param of knownParams) {
+            this.registerLeaf(param);
+        }
+    }
+    /**
+     * Register a leaf Value and return its index.
+     * If already registered, returns existing index.
+     * New parameters are added dynamically.
+     */
+    registerLeaf(value) {
+        let index = this.leafIndexMap.get(value);
+        if (index !== undefined) {
+            return index;
+        }
+        // New leaf - add to end
+        index = this.leaves.length;
+        this.leaves.push(value);
+        this.leafIndexMap.set(value, index);
+        return index;
+    }
+    /**
+     * Record an operation during graph building.
+     * Called automatically by Value.make() when in tracked context.
+     * @internal
+     */
+    recordOp(value) {
+        const prev = value.prev;
+        // If this is a leaf, register it
+        if (prev.length === 0) {
+            this.registerLeaf(value);
+            return;
+        }
+        // For intermediate nodes, register all leaf children
+        for (const child of prev) {
+            if (child.prev.length === 0) {
+                this.registerLeaf(child);
+            }
+        }
+        // Record this operation for later hash computation
+        this.operations.push(value);
+    }
+    /**
+     * Build a graph in tracked context and return output + signature.
+     *
+     * @param fn - Function that builds and returns the output Value
+     * @returns Output value and graph signature
+     */
+    build(fn) {
+        const prevBuilder = Value.currentBuilder;
+        Value.currentBuilder = this;
+        try {
+            const output = fn();
+            // Finalize signature
+            // Stable sort: params (with grad) first, then params (no grad), then constants
+            const sortedLeaves = [...this.leaves].sort((a, b) => {
+                const aIsParam = this.knownParams.has(a);
+                const bIsParam = this.knownParams.has(b);
+                if (aIsParam !== bIsParam)
+                    return aIsParam ? -1 : 1;
+                if (a.requiresGrad !== b.requiresGrad)
+                    return b.requiresGrad ? 1 : -1;
+                return a._id - b._id;
+            });
+            // Rebuild index map with sorted order
+            const finalLeafIndexMap = new Map();
+            for (let i = 0; i < sortedLeaves.length; i++) {
+                finalLeafIndexMap.set(sortedLeaves[i], i);
+            }
+            // Compute hash based on graph structure (NOW that we know all leaf assignments)
+            // Create stable node ID map: leaves get their indices, operations get sequential IDs
+            const nodeIdMap = new Map();
+            for (let i = 0; i < sortedLeaves.length; i++) {
+                nodeIdMap.set(sortedLeaves[i], i);
+            }
+            let nextOpId = sortedLeaves.length;
+            let hash = { h1: 2166136261, h2: 5381 };
+            // Hash leaf configuration first
+            for (let i = 0; i < sortedLeaves.length; i++) {
+                const leafHash = hashLeaf(i, sortedLeaves[i].requiresGrad);
+                hash = combineHashes(hash, leafHash, i);
+            }
+            // Hash operations in order they were created
+            for (const op of this.operations) {
+                const prev = op.prev;
+                // Assign ID to this operation
+                if (!nodeIdMap.has(op)) {
+                    nodeIdMap.set(op, nextOpId++);
+                }
+                let opName = op._op || 'unknown';
+                // Normalize operations
+                if (opName === 'sum')
+                    opName = '+';
+                if (opName === 'powValue' && prev.length === 2) {
+                    const exponent = prev[1];
+                    if (exponent.prev.length === 0 && exponent.data === 2 && !exponent.requiresGrad) {
+                        opName = 'square';
+                    }
+                }
+                const opHash = getOpHash(opName);
+                hash = combineHashes(hash, opHash, 0);
+                // Hash children by their stable IDs
+                for (let i = 0; i < prev.length; i++) {
+                    const child = prev[i];
+                    if (!nodeIdMap.has(child)) {
+                        nodeIdMap.set(child, nextOpId++);
+                    }
+                    const childId = nodeIdMap.get(child);
+                    const childHash = {
+                        h1: childId * PRIMES_32[2],
+                        h2: childId * PRIMES_32[3]
+                    };
+                    hash = combineHashes(hash, childHash, i + 1);
+                }
+            }
+            const hashString = hash.h1.toString(16).padStart(8, '0') +
+                hash.h2.toString(16).padStart(8, '0');
+            return {
+                output,
+                signature: {
+                    hash: hashString,
+                    leaves: sortedLeaves,
+                    leafIndexMap: finalLeafIndexMap
+                }
+            };
+        }
+        finally {
+            Value.currentBuilder = prevBuilder;
+        }
+    }
+    /**
+     * Get current signature without finalizing (for debugging)
+     */
+    getCurrentSignature() {
+        return {
+            hash: 'incomplete',
+            leaves: [...this.leaves]
+        };
+    }
+}

package/dist/GraphCanonicalizerNoSort.d.ts

@@ -0,0 +1,20 @@
+import { Value } from './Value';
+export interface CanonicalResult {
+    /** Canonical string uniquely identifying graph structure */
+    canon: string;
+    /** Maps Value nodes to their parameter indices */
+    paramMap: Map<Value, number>;
+}
+/**
+ * Canonicalize a computation graph WITHOUT sorting (fast, fewer matches).
+ *
+ * This is faster than the sorted version but produces different signatures
+ * for reordered commutative operations.
+ *
+ * @param output - The output Value of the computation graph
+ * @param params - Array of parameter Values for this residual/objective
+ * @returns Canonical string and parameter mapping
+ *
+ * @internal
+ */
+export declare function canonicalizeGraphNoSort(output: Value, params: Value[]): CanonicalResult;

package/dist/GraphCanonicalizerNoSort.js

@@ -0,0 +1,190 @@
+/**
+ * CANONICAL STRING REPRESENTATION (NO SORTING)
+ *
+ * Fast variant that doesn't sort children of commutative operations.
+ * This means fewer kernel matches (add(a,b) != add(b,a)), but much faster.
+ *
+ * Uses traverse counter optimization: instead of Map<Value, number> lookups,
+ * stamps each Value with a traverse ID for O(1) property access.
+ *
+ * @internal
+ */
+// Global traverse counter for memoization
+let globalTraverseId = 0;
+/**
+ * Canonicalize a computation graph WITHOUT sorting (fast, fewer matches).
+ *
+ * This is faster than the sorted version but produces different signatures
+ * for reordered commutative operations.
+ *
+ * @param output - The output Value of the computation graph
+ * @param params - Array of parameter Values for this residual/objective
+ * @returns Canonical string and parameter mapping
+ *
+ * @internal
+ */
+export function canonicalizeGraphNoSort(output, params) {
+    const t0 = performance.now();
+    const leafToId = new Map();
+    const allLeaves = new Set();
+    // Increment global traverse ID for this canonicalization
+    const traverseId = ++globalTraverseId;
+    // Phase 1: Discover all leaves in the graph (iterative)
+    const discoverStack = [output];
+    const discoverVisited = new Set();
+    while (discoverStack.length > 0) {
+        const node = discoverStack.pop();
+        if (discoverVisited.has(node))
+            continue;
+        discoverVisited.add(node);
+        const prev = node.prev;
+        if (prev.length === 0) {
+            allLeaves.add(node);
+        }
+        else {
+            for (const child of prev) {
+                discoverStack.push(child);
+            }
+        }
+    }
+    const t1 = performance.now();
+    // Phase 2: Assign IDs in stable, deterministic order
+    let nextId = 0;
+    const paramSet = new Set(params);
+    for (const param of params) {
+        if (allLeaves.has(param)) {
+            leafToId.set(param, nextId++);
+        }
+    }
+    const remainingLeaves = Array.from(allLeaves)
+        .filter(leaf => !paramSet.has(leaf));
+    for (const leaf of remainingLeaves) {
+        leafToId.set(leaf, nextId++);
+    }
+    const t2 = performance.now();
+    // Phase 3: Build canonical expression (NO SORTING, NO RECURSION!)
+    let nextNodeId = nextId; // Start after leaf IDs
+    // Build a compact representation: array of [nodeId, op, childIds...]
+    const nodeExprs = [];
+    // Topological sort to process nodes bottom-up (iterative)
+    const topoOrder = [];
+    const topoVisited = new Set();
+    const topoStack = [output];
+    while (topoStack.length > 0) {
+        const node = topoStack[topoStack.length - 1];
+        if (topoVisited.has(node)) {
+            topoStack.pop();
+            continue;
+        }
+        const prev = node.prev;
+        // If leaf, mark visited and add to order
+        if (prev.length === 0 || leafToId.has(node)) {
+            topoVisited.add(node);
+            topoOrder.push(node);
+            topoStack.pop();
+            continue;
+        }
+        // Check if all children processed
+        let allChildrenProcessed = true;
+        for (let i = prev.length - 1; i >= 0; i--) {
+            if (!topoVisited.has(prev[i])) {
+                allChildrenProcessed = false;
+                topoStack.push(prev[i]);
+            }
+        }
+        if (allChildrenProcessed) {
+            topoVisited.add(node);
+            topoOrder.push(node);
+            topoStack.pop();
+        }
+    }
+    const tTraversal = performance.now();
+    // Process nodes in topological order (leaves first)
+    // Use traverse counter stamping instead of Map lookups
+    for (const node of topoOrder) {
+        const nodeAny = node;
+        // Skip if already processed in this traverse
+        if (nodeAny._canonTraverseId === traverseId)
+            continue;
+        // Leaf node
+        const leafId = leafToId.get(node);
+        if (leafId !== undefined) {
+            nodeAny._canonTraverseId = traverseId;
+            nodeAny._canonNodeId = leafId;
+            continue;
+        }
+        const prev = node.prev;
+        if (prev.length === 0)
+            continue; // Skip empty prev
+        // Assign new ID and stamp it
+        const myId = nextNodeId++;
+        nodeAny._canonTraverseId = traverseId;
+        nodeAny._canonNodeId = myId;
+        let op = node._op || 'unknown';
+        // Normalize pow(x, const_2) -> square(x)
+        if (op === 'powValue' && prev.length === 2) {
+            const exponent = prev[1];
+            const exponentId = leafToId.get(exponent);
+            if (exponentId !== undefined && exponent.data === 2 && !exponent.requiresGrad) {
+                op = 'square';
+                const childId = prev[0]._canonNodeId;
+                nodeExprs.push([myId, op, [childId]]);
+                continue;
+            }
+        }
+        if (op === 'sum')
+            op = '+';
+        // All operations: just use children as-is (no flattening)
+        const childIds = prev.map(p => p._canonNodeId);
+        nodeExprs.push([myId, op, childIds]);
+    }
+    const outputId = output._canonNodeId;
+    const tTraversalEnd = performance.now();
+    // Build compact canonical signature from node expressions
+    const tStringStart = performance.now();
+    // Build leaf lookup for gradient flags (id -> 'g' suffix or '')
+    const leafGradFlags = new Map();
+    for (const [leaf, id] of leafToId) {
+        leafGradFlags.set(id, leaf.requiresGrad ? 'g' : '');
+    }
+    // Build expression parts (compact format)
+    const exprParts = [];
+    for (const [nodeId, op, childIds] of nodeExprs) {
+        const childRefs = childIds.map(id => {
+            const gradFlag = leafGradFlags.get(id);
+            if (gradFlag !== undefined) {
+                return `${id}${gradFlag}`;
+            }
+            return `n${id}`;
+        }).join(',');
+        exprParts.push(`n${nodeId}:(${op},${childRefs})`);
+    }
+    const expr = exprParts.join(';');
+    // Phase 4: Build param list
+    const paramList = [];
+    for (let i = 0; i < params.length; i++) {
+        const param = params[i];
+        if (!allLeaves.has(param))
+            continue;
+        const gradFlag = param.requiresGrad ? 'g' : '';
+        paramList.push(`${i}${gradFlag}`);
+    }
+    // For single-node leaf graphs, include the leaf ID
+    const finalExpr = expr.length > 0 ? expr : `${outputId}${leafGradFlags.get(outputId) || ''}`;
+    const canon = `${paramList.join(',')}|${finalExpr}`;
+    const tStringEnd = performance.now();
+    const t3 = performance.now();
+    // Build reverse map
+    const paramMap = new Map();
+    for (const [leaf, id] of leafToId) {
+        paramMap.set(leaf, id);
+    }
+    const t4 = performance.now();
+    const total = t4 - t0;
+    if (total > 10) {
+        const traversalTime = tTraversalEnd - tTraversal;
+        const stringBuildTime = tStringEnd - tStringStart;
+        console.log(`[GraphCanonicalizerNoSort] Total: ${total.toFixed(0)}ms | Phase1(discover): ${(t1 - t0).toFixed(0)}ms | Phase2(assign): ${(t2 - t1).toFixed(0)}ms | Phase3(expr): ${(t3 - t2).toFixed(0)}ms [traversal: ${traversalTime.toFixed(0)}ms, stringBuild: ${stringBuildTime.toFixed(0)}ms] | Phase4(build): ${(t4 - t3).toFixed(0)}ms | Nodes: ${discoverVisited.size} | NodeExprs: ${nodeExprs.length} | keyLength: ${canon.length}`);
+    }
+    return { canon, paramMap };
+}

package/dist/GraphHashCanonicalizer.d.ts

@@ -0,0 +1,46 @@
+import { Value } from './Value';
+/**
+ * HASH-BASED CANONICAL REPRESENTATION
+ *
+ * Fast canonicalization using dual 32-bit integer hashing.
+ *
+ * Design:
+ * - Each node gets a hash based on its operation and children
+ * - Position-dependent hashing (preserves order and multiplicity)
+ * - Direct integer operations (NO STRING HASHING!)
+ * - Parameters maintain topological order in signature
+ *
+ * Format: "0g,1g,2g,...|<hex_hash>"
+ *
+ * Benefits:
+ * - O(n) complexity (no sorting!)
+ * - Dual 32-bit hash (64-bit space, no BigInt overhead)
+ * - Preserves multiplicity: add(a,a,b) != add(a,b)
+ * - Recursion-free (stack-based iteration)
+ * - Pure integer operations (no string conversion!)
+ *
+ * Note: add(a,b) != add(b,a) - not order-independent
+ *
+ * @internal
+ */
+export interface HashCanonicalResult {
+    /** Canonical string with parameter list and expression hash */
+    canon: string;
+    /** Maps Value nodes to their parameter indices */
+    paramMap: Map<Value, number>;
+    /** Debug: full string expression (if enabled) */
+    debugExpr?: string;
+}
+/**
+ * Canonicalize a computation graph using hash-based signatures.
+ *
+ * Much faster than string-based canonicalization - O(n) with no sorting.
+ *
+ * @param output - The output Value of the computation graph
+ * @param params - Array of parameter Values for this residual/objective
+ * @param debug - If true, also generate string expression for debugging
+ * @returns Canonical string with hash and parameter mapping
+ *
+ * @internal
+ */
+export declare function canonicalizeGraphHash(output: Value, params: Value[], debug?: boolean): HashCanonicalResult;