gradient-script 0.1.0 → 0.3.0

package/README.md

@@ -1,16 +1,26 @@
 # GradientScript
 
+[![npm version](https://badge.fury.io/js/gradient-script.svg)](https://www.npmjs.com/package/gradient-script)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub release](https://img.shields.io/github/v/release/mfagerlund/gradient-script)](https://github.com/mfagerlund/gradient-script/releases)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)
+
+> **For LLMs:** This README is available in raw format at:
+> `https://raw.githubusercontent.com/mfagerlund/gradient-script/main/README.md`
+
 **Symbolic automatic differentiation for structured types**
 
 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
 - **Verified correctness**: Every gradient automatically checked against numerical differentiation
 - **Structured types**: Work with vectors `{x, y}` and custom structures, not just scalars
 - **Zero runtime overhead**: No tape, no graph - just pure gradient functions
-- **Multiple output languages**: TypeScript, JavaScript, or Python
+- **Multiple output languages**: TypeScript, JavaScript, Python, or C#
 - **Readable output**: Human-reviewable formulas with automatic optimization
 
 ## Installation
@@ -32,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
@@ -230,13 +240,18 @@ function angle_between_grad(u, v) {
 gradient-script <file.gs> [options]
 
 Options:
-  --format <format>     typescript (default), javascript, python
-  --no-simplify         Disable gradient simplification
-  --no-cse              Disable common subexpression elimination
-  --no-comments         Omit comments in generated code
-  --help, -h            Show help message
+  --format <format>              typescript (default), javascript, python, csharp
+  --no-simplify                  Disable gradient simplification
+  --no-cse                       Disable common subexpression elimination
+  --no-comments                  Omit comments in generated code
+  --guards                       Emit runtime guards for potential singularities
+  --epsilon <value>              Epsilon value for guards (default: 1e-10)
+  --csharp-float-type <type>     C# float precision: float (default) or double
+  --help, -h                     Show help message
 ```
 
+GradientScript automatically generates gradient functions for all functions in your `.gs` file.
+
 **Examples:**
 ```bash
 # Generate TypeScript (default)
@@ -247,6 +262,12 @@ gradient-script spring.gs --format python
 
 # Generate JavaScript without CSE optimization
 gradient-script spring.gs --format javascript --no-cse
+
+# Generate C# for Unity/Godot (float precision)
+gradient-script spring.gs --format csharp
+
+# Generate C# with double precision
+gradient-script spring.gs --format csharp --csharp-float-type double
 ```
 
 ## Language Syntax
@@ -454,7 +475,7 @@ GradientScript includes a comprehensive test suite that validates all generated
 npm test
 ```
 
-Current status: **78 tests passing**
+Current status: **129 tests passing**
 
 Test suite includes:
 
@@ -479,7 +500,7 @@ Test suite includes:
 - CSE optimization correctness
 - Operator precedence preservation
 - Power optimization (x*x vs Math.pow)
-- Multiple output formats (TypeScript, JavaScript, Python)
+- Multiple output formats (TypeScript, JavaScript, Python, C#)
 - Algebraic simplification correctness
 
 **Key guarantee**: If a test passes, the generated gradient is correct to within numerical precision (~10 decimal places).
@@ -506,6 +527,28 @@ GradientScript is under active development. Contributions welcome!
 - Web playground for live gradient generation
 - Benchmarking suite
 
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- **Physics Constraints**: [`examples/PHYSICS_EXAMPLES.md`](examples/PHYSICS_EXAMPLES.md) - Comprehensive guide to using structured types for XPBD constraints, rigid body dynamics, and more
+  - Raw (LLM-friendly): `https://raw.githubusercontent.com/mfagerlund/gradient-script/main/examples/PHYSICS_EXAMPLES.md`
+- **XPBD Constraints**: `xpbd-rod-constraint.gs`, `xpbd-angle-constraint.gs`
+- **Distance Functions**: `distance.gs`, `point-segment-distance.gs`
+- **Geometry**: `triangle-area.gs`, `bearing.gs`, `circle-fit.gs`
+
+**Try them:**
+```bash
+# View physics examples guide
+cat examples/PHYSICS_EXAMPLES.md
+
+# Generate TypeScript from XPBD rod constraint
+gradient-script examples/xpbd-rod-constraint.gs
+
+# Generate C# for Unity/Godot
+gradient-script examples/xpbd-angle-constraint.gs --format csharp
+```
+
 ## License
 
 MIT

package/dist/cli.js

@@ -5,6 +5,69 @@ import { inferFunction } from './dsl/TypeInference.js';
 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';
+import { GradientChecker, formatGradCheckResult } from './dsl/GradientChecker.js';
+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 for a function using numerical differentiation.
+ * Returns true if all gradients pass, false otherwise.
+ */
+function verifyGradients(func, gradients, env) {
+    const checker = new GradientChecker(1e-5, 1e-4);
+    const testPoints = generateTestPoints(func, env);
+    let allPassed = true;
+    for (let i = 0; i < testPoints.length; i++) {
+        const result = checker.check(func, gradients, env, testPoints[i]);
+        if (!result.passed) {
+            if (allPassed) {
+                // First failure - print header (as comment for valid output)
+                console.error(`// Gradient verification FAILED for "${func.name}":`);
+            }
+            // Prefix each line with // so output remains valid code
+            const formattedResult = formatGradCheckResult(result, func.name)
+                .split('\n')
+                .map(line => '// ' + line)
+                .join('\n');
+            console.error(`//   Test point ${i + 1}: ${formattedResult}`);
+            allPassed = false;
+        }
+    }
+    if (allPassed) {
+        const result = checker.check(func, gradients, env, testPoints[0]);
+        // Prefix with // so output is valid code
+        console.error('// ' + formatGradCheckResult(result, func.name));
+    }
+    return allPassed;
+}
 function printUsage() {
     console.log(`
 GradientScript - Symbolic Differentiation for Structured Types
@@ -13,18 +76,20 @@ Usage:
   gradient-script <file.gs> [options]
 
 Options:
-  --format <format>     Output format: typescript (default), javascript, python
+  --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)
+  --csharp-float-type <type>   C# float precision: float (default) or double
   --help, -h            Show this help message
 
 Examples:
   gradient-script angle.gs
   gradient-script angle.gs --format python
   gradient-script angle.gs --format javascript --no-comments
+  gradient-script angle.gs --format csharp
 
 Input File Format (.gs):
   function name(param1∇: {x, y}, param2∇) {
@@ -35,6 +100,16 @@ Input File Format (.gs):
 
   The ∇ symbol marks parameters that need gradients computed.
   Type annotations like {x, y} specify structured types.
+  All functions in the file are processed automatically.
+
+For more information and examples:
+  https://github.com/mfagerlund/gradient-script
+
+  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() {
@@ -54,12 +129,17 @@ function main() {
         simplify: true,
         cse: true
     };
+    let skipVerify = false;
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--format') {
+            if (i + 1 >= args.length) {
+                console.error('Error: Missing value for --format');
+                process.exit(1);
+            }
             const format = args[++i];
-            if (format !== 'typescript' && format !== 'javascript' && format !== 'python') {
-                console.error(`Error: Invalid format "${format}". Must be: typescript, javascript, or python`);
+            if (format !== 'typescript' && format !== 'javascript' && format !== 'python' && format !== 'csharp') {
+                console.error(`Error: Invalid format "${format}". Must be: typescript, javascript, python, or csharp`);
                 process.exit(1);
             }
             options.format = format;
@@ -77,13 +157,29 @@ function main() {
             options.emitGuards = true;
         }
         else if (arg === '--epsilon') {
+            if (i + 1 >= args.length) {
+                console.error('Error: Missing value for --epsilon');
+                process.exit(1);
+            }
             const epsilonValue = parseFloat(args[++i]);
             if (isNaN(epsilonValue) || epsilonValue <= 0) {
-                console.error(`Error: Invalid epsilon value. Must be a positive number.`);
+                console.error('Error: Invalid epsilon value. Must be a positive number.');
                 process.exit(1);
             }
             options.epsilon = epsilonValue;
         }
+        else if (arg === '--csharp-float-type') {
+            if (i + 1 >= args.length) {
+                console.error('Error: Missing value for --csharp-float-type');
+                process.exit(1);
+            }
+            const floatType = args[++i];
+            if (floatType !== 'float' && floatType !== 'double') {
+                console.error(`Error: Invalid C# float type "${floatType}". Must be: float or double`);
+                process.exit(1);
+            }
+            options.csharpFloatType = floatType;
+        }
         else {
             console.error(`Error: Unknown option "${arg}"`);
             printUsage();
@@ -107,23 +203,42 @@ function main() {
             console.error('Error: No functions found in input file');
             process.exit(1);
         }
-        const func = program.functions[0];
-        if (program.functions.length > 1) {
-            console.warn(`Warning: Multiple functions found, processing only "${func.name}"`);
-        }
-        const env = inferFunction(func);
-        const gradients = computeFunctionGradients(func, env);
-        // Analyze for edge cases
-        const guardAnalysis = analyzeGuards(func);
-        if (guardAnalysis.hasIssues) {
-            console.error(formatGuardWarnings(guardAnalysis));
+        const outputs = [];
+        let hasVerificationFailure = false;
+        program.functions.forEach((func, index) => {
+            const env = inferFunction(func);
+            const gradients = computeFunctionGradients(func, env);
+            // MANDATORY gradient verification
+            const verified = verifyGradients(func, gradients, 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));
+            }
+            const perFunctionOptions = { ...options };
+            if (index > 0 && perFunctionOptions.includeComments !== false) {
+                perFunctionOptions.includeComments = false;
+            }
+            const code = generateComplete(func, gradients, env, perFunctionOptions);
+            outputs.push(code);
+        });
+        if (hasVerificationFailure) {
+            console.error('// ERROR: Gradient verification failed. Output may contain incorrect gradients!');
+            process.exit(1);
         }
-        const code = generateComplete(func, gradients, env, options);
-        console.log(code);
+        console.log(outputs.join('\n\n'));
     }
     catch (err) {
-        console.error('Error: Failed to process input file');
-        if (err instanceof Error) {
+        if (err instanceof ParseError) {
+            // Use formatted error message for parse errors (always verbose with stack trace)
+            console.error(formatParseError(err, input, true));
+        }
+        else if (err instanceof Error) {
+            console.error('Error: Failed to process input file');
             console.error(err.message);
             if (err.stack) {
                 console.error('\nStack trace:');

package/dist/dsl/AST.d.ts

@@ -3,11 +3,19 @@
  * Supports function definitions with structured types
  */
 import { Type } from './Types.js';
+/**
+ * Source location in the input file
+ */
+export interface SourceLocation {
+    line: number;
+    column: number;
+}
 /**
  * Base AST node
  */
 export interface ASTNode {
     type?: Type;
+    loc?: SourceLocation;
 }
 /**
  * Program (top-level)

package/dist/dsl/CodeGen.d.ts

@@ -9,19 +9,22 @@ import { GradientResult } from './Differentiation.js';
  * Code generation options
  */
 export interface CodeGenOptions {
-    format?: 'typescript' | 'javascript' | 'python';
+    format?: 'typescript' | 'javascript' | 'python' | 'csharp';
     includeComments?: boolean;
     simplify?: boolean;
     cse?: boolean;
     epsilon?: number;
     emitGuards?: boolean;
+    csharpFloatType?: 'float' | 'double';
+    csharpNamingConvention?: 'camelCase' | 'PascalCase';
 }
 /**
  * Code generator for expressions
  */
 export declare class ExpressionCodeGen {
     private format;
-    constructor(format?: 'typescript' | 'javascript' | 'python');
+    private csharpFloatType;
+    constructor(format?: 'typescript' | 'javascript' | 'python' | 'csharp', csharpFloatType?: 'float' | 'double');
     /**
      * Generate code for an expression
      */
@@ -44,6 +47,8 @@ export declare class ExpressionCodeGen {
     private genUnary;
     private genCall;
     private genComponent;
+    private static readonly MATH_FUNCTIONS;
+    private static readonly PYTHON_BUILTINS;
     private mapFunctionName;
 }
 /**
@@ -51,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;
 /**