gradient-script 0.2.0 → 0.3.1

package/README.md

@@ -12,6 +12,8 @@
 
 GradientScript is a source-to-source compiler that automatically generates gradient functions from your mathematical code. Unlike numerical AD frameworks (JAX, PyTorch), it produces clean, human-readable gradient formulas you can inspect, optimize, and integrate directly into your codebase.
 
+It's perfect for LLM usage where the LLM can verify existing gradients or construct gradients you require with less risks of making errors.
+
 ## Why GradientScript?
 
 - **From real code to gradients**: Write natural math code, get symbolic derivatives
@@ -40,7 +42,7 @@ function distance(u: Vec2, v: Vec2): number {
 }
 ```
 
-Convert it to GradientScript by marking what you need gradients for:
+Convert it to GradientScript (realistically, let your LLM convert it giving it a reference here - and/or free usage of the CLI) by marking what you need gradients for:
 
 ```typescript
 // distance.gs

package/dist/cli.js

@@ -6,6 +6,202 @@ import { computeFunctionGradients } from './dsl/Differentiation.js';
 import { generateComplete } from './dsl/CodeGen.js';
 import { analyzeGuards, formatGuardWarnings } from './dsl/Guards.js';
 import { ParseError, formatParseError } from './dsl/Errors.js';
+// GradientChecker import removed - verification now executes generated code directly
+import { Types } from './dsl/Types.js';
+/**
+ * Generate random test points for gradient verification.
+ * Uses multiple test points to catch errors at different values.
+ */
+function generateTestPoints(func, env) {
+    const testPoints = [];
+    // Generate 3 different test points with varying scales
+    const scales = [1.0, 0.1, 10.0];
+    for (const scale of scales) {
+        const point = new Map();
+        for (const param of func.parameters) {
+            const paramType = env.getOrThrow(param.name);
+            if (Types.isScalar(paramType)) {
+                // Random scalar in range [-scale, scale], avoid zero
+                point.set(param.name, (Math.random() * 2 - 1) * scale + 0.1 * scale);
+            }
+            else {
+                // Structured type - get components
+                const struct = {};
+                for (const comp of paramType.components) {
+                    struct[comp] = (Math.random() * 2 - 1) * scale + 0.1 * scale;
+                }
+                point.set(param.name, struct);
+            }
+        }
+        testPoints.push(point);
+    }
+    return testPoints;
+}
+/**
+ * Verify gradients by executing the GENERATED CODE against numerical differentiation.
+ * This catches code generation bugs (like missing parentheses) that AST-based checking misses.
+ */
+function verifyGeneratedCode(func, generatedCode, env) {
+    const testPoints = generateTestPoints(func, env);
+    const epsilon = 1e-6;
+    const tolerance = 1e-4;
+    // Build parameter list for function calls
+    const paramNames = func.parameters.map(p => p.name);
+    // Create executable functions from generated code
+    // The generated code defines both funcName and funcName_grad
+    let forwardFn;
+    let gradFn;
+    try {
+        // Create a function that returns both the forward and grad functions
+        const factory = new Function(`
+      ${generatedCode}
+      return { forward: ${func.name}, grad: ${func.name}_grad };
+    `);
+        const fns = factory();
+        forwardFn = fns.forward;
+        gradFn = fns.grad;
+    }
+    catch (e) {
+        console.error(`// Gradient verification FAILED for "${func.name}": code execution error`);
+        console.error(`// ${e}`);
+        return false;
+    }
+    let allPassed = true;
+    let maxError = 0;
+    let totalChecks = 0;
+    const errors = [];
+    for (let pointIdx = 0; pointIdx < testPoints.length; pointIdx++) {
+        const testPoint = testPoints[pointIdx];
+        // Build args array (flattening structured types)
+        const args = [];
+        for (const param of func.parameters) {
+            const val = testPoint.get(param.name);
+            if (typeof val === 'number') {
+                args.push(val);
+            }
+            else {
+                // Structured: pass components in order
+                const paramType = env.getOrThrow(param.name);
+                if (!Types.isScalar(paramType)) {
+                    for (const comp of paramType.components) {
+                        args.push(val[comp]);
+                    }
+                }
+            }
+        }
+        // Run forward function at test point
+        let f0;
+        try {
+            f0 = forwardFn(...args);
+        }
+        catch (e) {
+            errors.push(`Test point ${pointIdx + 1}: forward function threw: ${e}`);
+            allPassed = false;
+            continue;
+        }
+        // Run gradient function
+        let gradResult;
+        try {
+            // Pass original (non-flattened) args for grad function
+            const gradArgs = [];
+            for (const param of func.parameters) {
+                const val = testPoint.get(param.name);
+                if (typeof val === 'number') {
+                    gradArgs.push(val);
+                }
+                else {
+                    // For structured types, pass as object with named components
+                    gradArgs.push(val);
+                }
+            }
+            gradResult = gradFn(...gradArgs);
+        }
+        catch (e) {
+            errors.push(`Test point ${pointIdx + 1}: gradient function threw: ${e}`);
+            allPassed = false;
+            continue;
+        }
+        // For each gradient parameter, compare analytical vs numerical
+        for (const param of func.parameters) {
+            if (!param.requiresGrad)
+                continue;
+            const paramType = env.getOrThrow(param.name);
+            const gradKey = `d${param.name}`;
+            if (Types.isScalar(paramType)) {
+                // Scalar gradient
+                totalChecks++;
+                const analytical = gradResult[gradKey];
+                // Compute numerical gradient
+                const paramIdx = func.parameters.findIndex(p => p.name === param.name);
+                let flatIdx = 0;
+                for (let i = 0; i < paramIdx; i++) {
+                    const pt = env.getOrThrow(func.parameters[i].name);
+                    flatIdx += Types.isScalar(pt) ? 1 : pt.components.length;
+                }
+                const argsPlus = [...args];
+                const argsMinus = [...args];
+                argsPlus[flatIdx] += epsilon;
+                argsMinus[flatIdx] -= epsilon;
+                const fPlus = forwardFn(...argsPlus);
+                const fMinus = forwardFn(...argsMinus);
+                const numerical = (fPlus - fMinus) / (2 * epsilon);
+                const error = Math.abs(analytical - numerical);
+                const relError = error / (Math.abs(numerical) + 1e-10);
+                maxError = Math.max(maxError, error);
+                if (error > tolerance && relError > tolerance) {
+                    if (!isNaN(analytical) || !isNaN(numerical)) {
+                        errors.push(`${param.name}: analytical=${analytical.toExponential(2)}, numerical=${numerical.toExponential(2)}, error=${error.toExponential(2)}`);
+                        allPassed = false;
+                    }
+                }
+            }
+            else {
+                // Structured gradient
+                const gradStruct = gradResult[gradKey];
+                const paramIdx = func.parameters.findIndex(p => p.name === param.name);
+                let flatIdx = 0;
+                for (let i = 0; i < paramIdx; i++) {
+                    const pt = env.getOrThrow(func.parameters[i].name);
+                    flatIdx += Types.isScalar(pt) ? 1 : pt.components.length;
+                }
+                for (let compIdx = 0; compIdx < paramType.components.length; compIdx++) {
+                    const comp = paramType.components[compIdx];
+                    totalChecks++;
+                    const analytical = gradStruct[comp];
+                    const argsPlus = [...args];
+                    const argsMinus = [...args];
+                    argsPlus[flatIdx + compIdx] += epsilon;
+                    argsMinus[flatIdx + compIdx] -= epsilon;
+                    const fPlus = forwardFn(...argsPlus);
+                    const fMinus = forwardFn(...argsMinus);
+                    const numerical = (fPlus - fMinus) / (2 * epsilon);
+                    const error = Math.abs(analytical - numerical);
+                    const relError = error / (Math.abs(numerical) + 1e-10);
+                    maxError = Math.max(maxError, error);
+                    if (error > tolerance && relError > tolerance) {
+                        if (!isNaN(analytical) || !isNaN(numerical)) {
+                            errors.push(`${param.name}.${comp}: analytical=${analytical.toExponential(2)}, numerical=${numerical.toExponential(2)}, error=${error.toExponential(2)}`);
+                            allPassed = false;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (allPassed) {
+        console.error(`// ✓ ${func.name}: ${totalChecks} gradients verified (max error: ${maxError.toExponential(2)})`);
+    }
+    else {
+        console.error(`// ✗ ${func.name}: gradient verification FAILED`);
+        for (const err of errors.slice(0, 5)) {
+            console.error(`//   ${err}`);
+        }
+        if (errors.length > 5) {
+            console.error(`//   ... and ${errors.length - 5} more errors`);
+        }
+    }
+    return allPassed;
+}
 function printUsage() {
     console.log(`
 GradientScript - Symbolic Differentiation for Structured Types
@@ -16,7 +212,7 @@ Usage:
 Options:
   --format <format>     Output format: typescript (default), javascript, python, csharp
   --no-simplify         Disable gradient simplification
-  --no-cse              Disable common subexpression elimination
+  --no-cse              Disable optimization (e-graph CSE)
   --no-comments         Omit comments in generated code
   --guards              Emit runtime guards for division by zero (experimental)
   --epsilon <value>     Epsilon value for guards (default: 1e-10)
@@ -45,6 +241,9 @@ For more information and examples:
 
   README (raw, LLM-friendly):
   https://raw.githubusercontent.com/mfagerlund/gradient-script/main/README.md
+
+  LLM Optimization Guide (for AI agents writing .gs files):
+  https://raw.githubusercontent.com/mfagerlund/gradient-script/main/docs/LLM-OPTIMIZATION-GUIDE.md
   `.trim());
 }
 function main() {
@@ -64,6 +263,7 @@ function main() {
         simplify: true,
         cse: true
     };
+    let skipVerify = false;
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--format') {
@@ -138,21 +338,34 @@ function main() {
             process.exit(1);
         }
         const outputs = [];
+        let hasVerificationFailure = false;
         program.functions.forEach((func, index) => {
             const env = inferFunction(func);
             const gradients = computeFunctionGradients(func, env);
-            const guardAnalysis = analyzeGuards(func);
-            if (guardAnalysis.hasIssues) {
-                console.error('Function "' + func.name + '" may have edge cases:');
-                console.error(formatGuardWarnings(guardAnalysis));
-            }
             const perFunctionOptions = { ...options };
             if (index > 0 && perFunctionOptions.includeComments !== false) {
                 perFunctionOptions.includeComments = false;
             }
+            // Generate code FIRST
             const code = generateComplete(func, gradients, env, perFunctionOptions);
+            // MANDATORY: Verify the GENERATED CODE against numerical differentiation
+            // This catches code generation bugs that AST-based checking would miss
+            const verified = verifyGeneratedCode(func, code, env);
+            if (!verified) {
+                hasVerificationFailure = true;
+            }
+            const guardAnalysis = analyzeGuards(func);
+            if (guardAnalysis.hasIssues) {
+                // Format warnings as comments so output remains valid code even if stderr is captured
+                console.error('// Function "' + func.name + '" may have edge cases:');
+                console.error(formatGuardWarnings(guardAnalysis, true));
+            }
             outputs.push(code);
         });
+        if (hasVerificationFailure) {
+            console.error('// ERROR: Gradient verification failed. Output may contain incorrect gradients!');
+            process.exit(1);
+        }
         console.log(outputs.join('\n\n'));
     }
     catch (err) {

package/dist/dsl/CodeGen.d.ts

@@ -56,7 +56,7 @@ export declare class ExpressionCodeGen {
  */
 export declare function generateGradientFunction(func: FunctionDef, gradients: GradientResult, env: TypeEnv, options?: CodeGenOptions): string;
 /**
- * Generate the original forward function
+ * Generate the original forward function (with optional e-graph optimization)
  */
 export declare function generateForwardFunction(func: FunctionDef, options?: CodeGenOptions): string;
 /**