gradient-script 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,13 @@
 # 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.
@@ -10,7 +18,7 @@ GradientScript is a source-to-source compiler that automatically generates gradi
 - **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
@@ -230,13 +238,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 +260,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 +473,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 +498,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 +525,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,7 @@ 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';
 function printUsage() {
     console.log(`
 GradientScript - Symbolic Differentiation for Structured Types
@@ -13,18 +14,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-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 +38,13 @@ 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
   `.trim());
 }
 function main() {
@@ -57,9 +67,13 @@ function main() {
     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 +91,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 +137,31 @@ 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 code = generateComplete(func, gradients, env, options);
-        console.log(code);
+        const outputs = [];
+        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;
+            }
+            const code = generateComplete(func, gradients, env, perFunctionOptions);
+            outputs.push(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/CSE.js

@@ -3,33 +3,7 @@
  * Identifies repeated expressions and factors them out
  */
 import { ExpressionTransformer } from './ExpressionTransformer.js';
-/**
- * Serializes expressions to canonical string form for comparison
- * This is a dedicated serializer that doesn't abuse the type system
- */
-class ExpressionSerializer {
-    serialize(expr) {
-        switch (expr.kind) {
-            case 'number':
-                return `num(${expr.value})`;
-            case 'variable':
-                return `var(${expr.name})`;
-            case 'binary':
-                const left = this.serialize(expr.left);
-                const right = this.serialize(expr.right);
-                return `bin(${expr.operator},${left},${right})`;
-            case 'unary':
-                const operand = this.serialize(expr.operand);
-                return `un(${expr.operator},${operand})`;
-            case 'call':
-                const args = expr.args.map(arg => this.serialize(arg)).join(',');
-                return `call(${expr.name},${args})`;
-            case 'component':
-                const object = this.serialize(expr.object);
-                return `comp(${object},${expr.component})`;
-        }
-    }
-}
+import { serializeExpression } from './ExpressionUtils.js';
 /**
  * Perform CSE on an expression
  */
@@ -105,12 +79,11 @@ function shouldExtract(expr) {
 class ExpressionCounter extends ExpressionTransformer {
     counts = new Map();
     expressions = new Map();
-    serializer = new ExpressionSerializer();
     count(expr) {
         this.transform(expr);
     }
     serialize(expr) {
-        return this.serializer.serialize(expr);
+        return serializeExpression(expr);
     }
     recordExpression(expr) {
         const key = this.serialize(expr);
@@ -167,8 +140,9 @@ function substituteExpressions(expr, subexprMap, counter) {
 }
 /**
  * Transformer that substitutes a pattern with a replacement expression
+ * Used for CSE optimization to replace repeated subexpressions with intermediate variables
  */
-class SubstitutionTransformer extends ExpressionTransformer {
+class PatternSubstitutionTransformer extends ExpressionTransformer {
     pattern;
     replacement;
     counter;
@@ -189,6 +163,6 @@ class SubstitutionTransformer extends ExpressionTransformer {
  * Helper to substitute an expression pattern with a replacement
  */
 function substituteInExpression(expr, pattern, replacement, counter) {
-    const transformer = new SubstitutionTransformer(pattern, replacement, counter);
+    const transformer = new PatternSubstitutionTransformer(pattern, replacement, counter);
     return transformer.transform(expr);
 }

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;
 }
 /**