scalar-autograd 0.1.7 → 0.1.9

package/dist/cli/gradient-gen.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for symbolic gradient generation.
+ * Accepts mathematical expressions and outputs gradient computation code.
+ */
+import * as fs from 'fs';
+import { parse } from '../symbolic/Parser';
+import { computeGradients } from '../symbolic/SymbolicDiff';
+import { simplify } from '../symbolic/Simplify';
+import { generateGradientCode, generateGradientFunction } from '../symbolic/CodeGen';
+const VERSION = '1.0.0';
+function printHelp() {
+    console.log(`
+ScalarAutograd Symbolic Gradient Generator v${VERSION}
+
+Generate symbolic gradient formulas from mathematical expressions.
+
+USAGE:
+  npx scalar-grad [options] [expression]
+
+OPTIONS:
+  -i, --input <file>       Input file containing expressions
+  -o, --output <file>      Output file (default: stdout)
+  --wrt <params>           Comma-separated list of parameters to differentiate
+                           (default: auto-detect from expressions)
+  --format <type>          Output format: js, ts, function, inline (default: js)
+  --no-simplify            Disable expression simplification
+  --function <name>        Function name when using --format=function (default: computeGradient)
+  -h, --help               Show this help message
+  -v, --version            Show version
+
+EXAMPLES:
+  # Simple expression
+  npx scalar-grad "x = 2; y = 3; output = x*x + y*y" --wrt x,y
+
+  # From file
+  npx scalar-grad --input forward.txt --wrt a,b,c --output gradients.js
+
+  # Generate function
+  npx scalar-grad "z = x*x + y*y; output = sqrt(z)" --format function --function distanceGradient
+
+  # Inline expression (no file)
+  echo "output = sin(x) * cos(y)" | npx scalar-grad --wrt x,y
+
+INPUT FORMAT:
+  Expressions use operator overloading syntax:
+    c = a + b          // Addition
+    d = c * 2          // Multiplication
+    e = sin(d)         // Function call
+    output = e         // Mark output variable
+
+  Supported operators: +, -, *, /, ** (power)
+  Supported functions: sin, cos, tan, exp, log, sqrt, abs, asin, acos, atan, etc.
+
+  Vec2/Vec3 support:
+    v = Vec2(x, y)     // Vector constructor
+    mag = v.magnitude  // Vector property
+    dot = u.dot(v)     // Vector method
+
+OUTPUT:
+  Generated code includes:
+  - Forward pass computation
+  - Gradient formulas with mathematical notation in comments
+  - Executable JavaScript/TypeScript code
+`);
+}
+function parseArgs(args) {
+    const options = {
+        format: 'js',
+        simplify: true,
+        help: false,
+        version: false
+    };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === '-h' || arg === '--help') {
+            options.help = true;
+            i++;
+        }
+        else if (arg === '-v' || arg === '--version') {
+            options.version = true;
+            i++;
+        }
+        else if (arg === '-i' || arg === '--input') {
+            options.input = args[++i];
+            i++;
+        }
+        else if (arg === '-o' || arg === '--output') {
+            options.output = args[++i];
+            i++;
+        }
+        else if (arg === '--wrt') {
+            options.wrt = args[++i].split(',').map(s => s.trim());
+            i++;
+        }
+        else if (arg === '--format') {
+            const format = args[++i];
+            if (format !== 'js' && format !== 'ts' && format !== 'function' && format !== 'inline') {
+                throw new Error(`Invalid format: ${format}. Must be js, ts, function, or inline`);
+            }
+            options.format = format;
+            i++;
+        }
+        else if (arg === '--no-simplify') {
+            options.simplify = false;
+            i++;
+        }
+        else if (arg === '--function') {
+            options.functionName = args[++i];
+            i++;
+        }
+        else if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        else {
+            // Positional argument - treat as expression
+            options.input = arg;
+            i++;
+        }
+    }
+    return options;
+}
+function readInput(options) {
+    if (options.input) {
+        // Check if it's a file
+        if (fs.existsSync(options.input)) {
+            return fs.readFileSync(options.input, 'utf-8');
+        }
+        else {
+            // Treat as direct expression
+            return options.input;
+        }
+    }
+    // Read from stdin
+    const stdin = fs.readFileSync(0, 'utf-8');
+    return stdin;
+}
+function writeOutput(content, options) {
+    if (options.output) {
+        fs.writeFileSync(options.output, content, 'utf-8');
+        console.error(`Output written to ${options.output}`);
+    }
+    else {
+        console.log(content);
+    }
+}
+function extractParameters(input) {
+    // Simple heuristic: find all single-letter variables that appear on the right-hand side
+    // but are never assigned
+    const assignedVars = new Set();
+    const usedVars = new Set();
+    // Match assignments: var = expr
+    const assignmentRegex = /(\w+)\s*=/g;
+    let match;
+    while ((match = assignmentRegex.exec(input)) !== null) {
+        assignedVars.add(match[1]);
+    }
+    // Match all identifiers
+    const identifierRegex = /\b([a-zA-Z_]\w*)\b/g;
+    while ((match = identifierRegex.exec(input)) !== null) {
+        const ident = match[1];
+        // Skip known functions and keywords
+        const keywords = ['Vec2', 'Vec3', 'sin', 'cos', 'tan', 'exp', 'log', 'sqrt', 'abs',
+            'min', 'max', 'output', 'Math', 'const', 'let', 'var'];
+        if (!keywords.includes(ident)) {
+            usedVars.add(ident);
+        }
+    }
+    // Parameters are variables used but never assigned
+    const params = [];
+    for (const v of usedVars) {
+        if (!assignedVars.has(v)) {
+            params.push(v);
+        }
+    }
+    return params.sort();
+}
+function main() {
+    try {
+        const args = process.argv.slice(2);
+        if (args.length === 0) {
+            printHelp();
+            process.exit(0);
+        }
+        const options = parseArgs(args);
+        if (options.help) {
+            printHelp();
+            process.exit(0);
+        }
+        if (options.version) {
+            console.log(`ScalarAutograd Symbolic Gradient Generator v${VERSION}`);
+            process.exit(0);
+        }
+        // Read input
+        const input = readInput(options);
+        if (!input.trim()) {
+            console.error('Error: No input provided');
+            process.exit(1);
+        }
+        // Parse expression
+        console.error('Parsing expressions...');
+        const program = parse(input);
+        // Auto-detect parameters if not specified
+        let parameters = options.wrt;
+        if (!parameters) {
+            parameters = extractParameters(input);
+            console.error(`Auto-detected parameters: ${parameters.join(', ')}`);
+        }
+        if (parameters.length === 0) {
+            console.error('Error: No parameters to differentiate with respect to');
+            console.error('Hint: Use --wrt to specify parameters');
+            process.exit(1);
+        }
+        // Compute gradients
+        console.error('Computing symbolic gradients...');
+        let gradients = computeGradients(program, parameters);
+        // Simplify if enabled
+        if (options.simplify) {
+            console.error('Simplifying expressions...');
+            const simplified = new Map();
+            for (const [param, gradExpr] of gradients.entries()) {
+                simplified.set(param, simplify(gradExpr));
+            }
+            gradients = simplified;
+        }
+        // Generate code
+        console.error('Generating code...');
+        let output;
+        if (options.format === 'function') {
+            const funcName = options.functionName || 'computeGradient';
+            output = generateGradientFunction(program, gradients, funcName, parameters, {
+                includeMath: true
+            });
+        }
+        else {
+            output = generateGradientCode(program, gradients, {
+                includeMath: true,
+                varStyle: 'const',
+                includeForward: true
+            });
+        }
+        // Add TypeScript annotations if requested
+        if (options.format === 'ts') {
+            output = `// TypeScript version\n${output}`;
+            // Could add type annotations here
+        }
+        // Write output
+        writeOutput(output, options);
+        console.error('✓ Success!');
+    }
+    catch (error) {
+        console.error('Error:', error.message);
+        if (process.env.DEBUG) {
+            console.error(error.stack);
+        }
+        process.exit(1);
+    }
+}
+// Run if called directly
+if (require.main === module) {
+    main();
+}
+export { main, parseArgs, extractParameters };

package/dist/compileIndirectKernel.d.ts

@@ -0,0 +1,24 @@
+import { Value } from './Value';
+import { ValueRegistry } from './ValueRegistry';
+/**
+ * Compiles a residual function with indirect value indexing for kernel reuse.
+ *
+ * Instead of hardcoding parameter positions, this generates code that:
+ * 1. Accepts a global value array
+ * 2. Accepts an indices array specifying which values this graph uses
+ * 3. Looks up values via indices: allValues[indices[i]]
+ *
+ * This allows topologically identical graphs to share the same kernel.
+ *
+ * @param residual - Output Value of the residual computation
+ * @param params - Parameter Values (for Jacobian computation)
+ * @param registry - ValueRegistry tracking all unique values
+ * @returns Compiled function: (allValues, indices, gradientIndices, gradient) => number
+ * @internal
+ */
+export declare function compileIndirectKernel(residual: Value, params: Value[], registry: ValueRegistry): (allValues: number[], indices: number[], gradientIndices: number[], gradient: number[]) => number;
+/**
+ * Extract input indices for a residual graph.
+ * Returns array of registry IDs for all leaf nodes in topological order.
+ */
+export declare function extractInputIndices(residual: Value, registry: ValueRegistry): number[];

package/dist/compileIndirectKernel.js

@@ -0,0 +1,148 @@
+/**
+ * Compiles a residual function with indirect value indexing for kernel reuse.
+ *
+ * Instead of hardcoding parameter positions, this generates code that:
+ * 1. Accepts a global value array
+ * 2. Accepts an indices array specifying which values this graph uses
+ * 3. Looks up values via indices: allValues[indices[i]]
+ *
+ * This allows topologically identical graphs to share the same kernel.
+ *
+ * @param residual - Output Value of the residual computation
+ * @param params - Parameter Values (for Jacobian computation)
+ * @param registry - ValueRegistry tracking all unique values
+ * @returns Compiled function: (allValues, indices, gradientIndices, gradient) => number
+ * @internal
+ */
+export function compileIndirectKernel(residual, params, registry) {
+    const visited = new Set();
+    const topoOrder = [];
+    const forwardCode = [];
+    const backwardCode = [];
+    let varCounter = 0;
+    const nodeToVar = new Map();
+    const nodeToIndexVar = new Map(); // Maps Value -> index variable name
+    // Build topo order and register only leaf nodes (inputs)
+    function buildTopoOrder(node) {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        for (const child of node.prev) {
+            buildTopoOrder(child);
+        }
+        topoOrder.push(node);
+        // Only register leaf nodes (graph inputs: constants and parameters)
+        // Intermediates (prev.length > 0) are computed within kernel, not in registry
+        if (node.prev.length === 0) {
+            registry.register(node);
+        }
+    }
+    buildTopoOrder(residual);
+    // Build index mapping for graph inputs (leaf nodes in topoOrder)
+    const graphInputs = [];
+    for (const node of topoOrder) {
+        const prev = node.prev;
+        if (prev.length === 0 && !graphInputs.includes(node)) {
+            graphInputs.push(node);
+        }
+    }
+    // Assign index variables to inputs
+    graphInputs.forEach((input, i) => {
+        nodeToIndexVar.set(input, `idx_${i}`);
+    });
+    function getVarName(node) {
+        if (!nodeToVar.has(node)) {
+            nodeToVar.set(node, `_v${varCounter++}`);
+        }
+        return nodeToVar.get(node);
+    }
+    // Generate forward code for each node in topo order
+    for (const node of topoOrder) {
+        const prev = node.prev;
+        if (prev.length === 0) {
+            // Leaf node - load from allValues via index
+            const indexVar = nodeToIndexVar.get(node);
+            forwardCode.push(`const ${getVarName(node)} = allValues[${indexVar}];`);
+        }
+        else {
+            // Computed node
+            const childCodes = prev.map(c => getVarName(c));
+            const code = node.getForwardCode(childCodes);
+            forwardCode.push(`const ${getVarName(node)} = ${code};`);
+        }
+    }
+    // Generate gradient declarations
+    const gradDeclarations = Array.from(nodeToVar.entries())
+        .map(([node, varName]) => `let grad_${varName} = 0;`);
+    // Generate backward pass - iterate REVERSE topological order (same as Value.backward)
+    for (let i = topoOrder.length - 1; i >= 0; i--) {
+        const node = topoOrder[i];
+        const prev = node.prev;
+        if (prev.length === 0 || !node.requiresGrad)
+            continue;
+        const gradVar = `grad_${getVarName(node)}`;
+        const childGrads = prev.map((c) => `grad_${getVarName(c)}`);
+        const childVars = prev.map((c) => getVarName(c));
+        backwardCode.push(node.getBackwardCode(gradVar, childGrads, childVars));
+    }
+    const outputVar = getVarName(residual);
+    // Extract indices for graph inputs
+    const indexExtractions = graphInputs
+        .map((input, i) => `const ${nodeToIndexVar.get(input)} = indices[${i}];`)
+        .join('\n    ');
+    // Build gradient updates - only for inputs that require gradients
+    // Skip constants and any values with requiresGrad=false
+    const gradientUpdates = graphInputs
+        .map((input, inputIdx) => {
+        if (!input.requiresGrad) {
+            return null; // Skip - this input doesn't need gradients
+        }
+        const gradVar = `grad_${getVarName(input)}`;
+        return `gradient[gradientIndices[${inputIdx}]] += ${gradVar};`;
+    })
+        .filter((line) => line !== null)
+        .join('\n    ');
+    const functionBody = `
+    ${indexExtractions}
+    ${forwardCode.join('\n    ')}
+    ${gradDeclarations.join('\n    ')}
+    grad_${outputVar} = 1;
+    ${backwardCode.join('\n    ')}
+    ${gradientUpdates}
+    return ${outputVar};
+  `;
+    try {
+        return new Function('allValues', 'indices', 'gradientIndices', 'gradient', functionBody);
+    }
+    catch (error) {
+        console.error(`[compileIndirectKernel] COMPILATION ERROR:`, error);
+        console.error(`[compileIndirectKernel] Function body:\n${functionBody}`);
+        throw error;
+    }
+}
+/**
+ * Extract input indices for a residual graph.
+ * Returns array of registry IDs for all leaf nodes in topological order.
+ */
+export function extractInputIndices(residual, registry) {
+    const visited = new Set();
+    const inputs = [];
+    function collectInputs(node) {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        const prev = node.prev;
+        if (prev.length === 0) {
+            if (!inputs.includes(node)) {
+                inputs.push(node);
+            }
+        }
+        else {
+            for (const child of prev) {
+                collectInputs(child);
+            }
+        }
+    }
+    collectInputs(residual);
+    return inputs.map(v => registry.getId(v));
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import './EigenvalueHelpers';
+export { CompiledFunctions } from './CompiledFunctions';
+export { CompiledResiduals } from './CompiledResiduals';
+export { Geometry } from './Geometry';
+export { GraphBuilder, type GraphSignature } from './GraphBuilder';
+export { lbfgs, type LBFGSOptions, type LBFGSResult } from './LBFGS';
+export { Losses } from './Losses';
+export { Matrix3x3 } from './Matrix3x3';
+export { nonlinearLeastSquares, type NonlinearLeastSquaresOptions, type NonlinearLeastSquaresResult } from './NonlinearLeastSquares';
+export { Adam, AdamW, Optimizer, SGD } from './Optimizers';
+export { V } from './V';
+export { Value } from './Value';
+export { Vec2 } from './Vec2';
+export { Vec3 } from './Vec3';
+export { Vec4 } from './Vec4';
+export { parse, Parser } from './symbolic/Parser';
+export { differentiate, computeGradients } from './symbolic/SymbolicDiff';
+export { simplify } from './symbolic/Simplify';
+export { generateCode, generateMathNotation, generateGradientCode, generateGradientFunction } from './symbolic/CodeGen';
+export type { ASTNode, NumberNode, VariableNode, BinaryOpNode, UnaryOpNode, FunctionCallNode, VectorAccessNode, VectorConstructorNode, Assignment, Program } from './symbolic/AST';

package/dist/index.js

@@ -0,0 +1,20 @@
+import './EigenvalueHelpers';
+export { CompiledFunctions } from './CompiledFunctions';
+export { CompiledResiduals } from './CompiledResiduals';
+export { Geometry } from './Geometry';
+export { GraphBuilder } from './GraphBuilder';
+export { lbfgs } from './LBFGS';
+export { Losses } from './Losses';
+export { Matrix3x3 } from './Matrix3x3';
+export { nonlinearLeastSquares } from './NonlinearLeastSquares';
+export { Adam, AdamW, Optimizer, SGD } from './Optimizers';
+export { V } from './V';
+export { Value } from './Value';
+export { Vec2 } from './Vec2';
+export { Vec3 } from './Vec3';
+export { Vec4 } from './Vec4';
+// Symbolic gradient generation
+export { parse, Parser } from './symbolic/Parser';
+export { differentiate, computeGradients } from './symbolic/SymbolicDiff';
+export { simplify } from './symbolic/Simplify';
+export { generateCode, generateMathNotation, generateGradientCode, generateGradientFunction } from './symbolic/CodeGen';