gradient-script 0.1.0

package/dist/dsl/GradientChecker.js

@@ -0,0 +1,258 @@
+/**
+ * Numerical gradient checking for GradientScript DSL
+ * Validates symbolic gradients against finite difference approximations
+ */
+import { Types } from './Types.js';
+import { expandBuiltIn, shouldExpand } from './Expander.js';
+/**
+ * Gradient checker
+ */
+export class GradientChecker {
+    epsilon;
+    tolerance;
+    constructor(epsilon = 1e-5, tolerance = 1e-4) {
+        this.epsilon = epsilon;
+        this.tolerance = tolerance;
+    }
+    /**
+     * Check gradients for a function
+     */
+    check(func, gradients, env, testPoint) {
+        const errors = [];
+        // For each parameter that has gradients
+        for (const [paramName, gradient] of gradients.gradients.entries()) {
+            const paramType = env.getOrThrow(paramName);
+            const paramValue = testPoint.get(paramName);
+            if (!paramValue) {
+                throw new Error(`Test point missing value for parameter: ${paramName}`);
+            }
+            if (Types.isScalar(paramType)) {
+                // Scalar parameter
+                if (typeof paramValue !== 'number') {
+                    throw new Error(`Expected scalar value for ${paramName}`);
+                }
+                const analytical = this.evaluateExpression(gradient, testPoint);
+                const numerical = this.numericalGradientScalar(func, testPoint, paramName);
+                const error = Math.abs(analytical - numerical);
+                const relativeError = Math.abs(error / (numerical + 1e-10));
+                if (error > this.tolerance && relativeError > this.tolerance) {
+                    errors.push({
+                        parameter: paramName,
+                        analytical,
+                        numerical,
+                        error,
+                        relativeError
+                    });
+                }
+            }
+            else {
+                // Structured parameter
+                if (typeof paramValue === 'number') {
+                    throw new Error(`Expected structured value for ${paramName}`);
+                }
+                const structGrad = gradient;
+                for (const [comp, expr] of structGrad.components.entries()) {
+                    const analytical = this.evaluateExpression(expr, testPoint);
+                    const numerical = this.numericalGradientComponent(func, testPoint, paramName, comp);
+                    const error = Math.abs(analytical - numerical);
+                    const relativeError = Math.abs(error / (numerical + 1e-10));
+                    if (error > this.tolerance && relativeError > this.tolerance) {
+                        errors.push({
+                            parameter: paramName,
+                            component: comp,
+                            analytical,
+                            numerical,
+                            error,
+                            relativeError
+                        });
+                    }
+                }
+            }
+        }
+        const maxError = errors.length > 0 ? Math.max(...errors.map(e => e.error)) : 0;
+        const meanError = errors.length > 0
+            ? errors.reduce((sum, e) => sum + e.error, 0) / errors.length
+            : 0;
+        return {
+            passed: errors.length === 0,
+            errors,
+            maxError,
+            meanError
+        };
+    }
+    /**
+     * Compute numerical gradient for scalar parameter using finite differences
+     */
+    numericalGradientScalar(func, testPoint, paramName) {
+        const originalValue = testPoint.get(paramName);
+        // f(x + h)
+        testPoint.set(paramName, originalValue + this.epsilon);
+        const fPlus = this.evaluateFunction(func, testPoint);
+        // f(x - h)
+        testPoint.set(paramName, originalValue - this.epsilon);
+        const fMinus = this.evaluateFunction(func, testPoint);
+        // Restore original value
+        testPoint.set(paramName, originalValue);
+        // Central difference: (f(x+h) - f(x-h)) / (2h)
+        return (fPlus - fMinus) / (2 * this.epsilon);
+    }
+    /**
+     * Compute numerical gradient for structured parameter component
+     */
+    numericalGradientComponent(func, testPoint, paramName, component) {
+        const originalValue = testPoint.get(paramName);
+        const originalComp = originalValue[component];
+        // f(x + h)
+        originalValue[component] = originalComp + this.epsilon;
+        const fPlus = this.evaluateFunction(func, testPoint);
+        // f(x - h)
+        originalValue[component] = originalComp - this.epsilon;
+        const fMinus = this.evaluateFunction(func, testPoint);
+        // Restore original value
+        originalValue[component] = originalComp;
+        // Central difference
+        return (fPlus - fMinus) / (2 * this.epsilon);
+    }
+    /**
+     * Evaluate function at a test point
+     */
+    evaluateFunction(func, testPoint) {
+        // Inline and evaluate the return expression
+        const inlined = this.inlineWithValues(func, testPoint);
+        return this.evaluateExpression(inlined, testPoint);
+    }
+    /**
+     * Inline function body with test point values
+     */
+    inlineWithValues(func, testPoint) {
+        const substitutions = new Map();
+        // Add intermediate variable assignments
+        for (const stmt of func.body) {
+            if (stmt.kind === 'assignment') {
+                substitutions.set(stmt.variable, stmt.expression);
+            }
+        }
+        return this.substituteExpression(func.returnExpr, substitutions, testPoint);
+    }
+    /**
+     * Substitute variables in expression
+     */
+    substituteExpression(expr, subs, testPoint) {
+        switch (expr.kind) {
+            case 'number':
+                return expr;
+            case 'variable':
+                if (subs.has(expr.name)) {
+                    return this.substituteExpression(subs.get(expr.name), subs, testPoint);
+                }
+                return expr;
+            case 'binary':
+                return {
+                    kind: 'binary',
+                    operator: expr.operator,
+                    left: this.substituteExpression(expr.left, subs, testPoint),
+                    right: this.substituteExpression(expr.right, subs, testPoint)
+                };
+            case 'unary':
+                return {
+                    kind: 'unary',
+                    operator: expr.operator,
+                    operand: this.substituteExpression(expr.operand, subs, testPoint)
+                };
+            case 'call':
+                // Expand built-ins before evaluation
+                if (shouldExpand(expr.name)) {
+                    const expanded = expandBuiltIn({
+                        ...expr,
+                        args: expr.args.map(arg => this.substituteExpression(arg, subs, testPoint))
+                    });
+                    return expanded;
+                }
+                return {
+                    kind: 'call',
+                    name: expr.name,
+                    args: expr.args.map(arg => this.substituteExpression(arg, subs, testPoint))
+                };
+            case 'component':
+                return {
+                    kind: 'component',
+                    object: this.substituteExpression(expr.object, subs, testPoint),
+                    component: expr.component
+                };
+        }
+    }
+    /**
+     * Evaluate an expression numerically
+     */
+    evaluateExpression(expr, testPoint) {
+        switch (expr.kind) {
+            case 'number':
+                return expr.value;
+            case 'variable':
+                const value = testPoint.get(expr.name);
+                if (typeof value === 'number') {
+                    return value;
+                }
+                throw new Error(`Cannot evaluate variable ${expr.name}: not a scalar`);
+            case 'binary':
+                const left = this.evaluateExpression(expr.left, testPoint);
+                const right = this.evaluateExpression(expr.right, testPoint);
+                switch (expr.operator) {
+                    case '+': return left + right;
+                    case '-': return left - right;
+                    case '*': return left * right;
+                    case '/': return left / right;
+                    case '^':
+                    case '**': return Math.pow(left, right);
+                }
+                break;
+            case 'unary':
+                const operand = this.evaluateExpression(expr.operand, testPoint);
+                if (expr.operator === '-')
+                    return -operand;
+                if (expr.operator === '+')
+                    return operand;
+                break;
+            case 'call':
+                // Expand built-ins before evaluation
+                if (shouldExpand(expr.name)) {
+                    const expanded = expandBuiltIn(expr);
+                    return this.evaluateExpression(expanded, testPoint);
+                }
+                const args = expr.args.map(arg => this.evaluateExpression(arg, testPoint));
+                return this.evaluateMathFunction(expr.name, args);
+            case 'component':
+                if (expr.object.kind === 'variable') {
+                    const objValue = testPoint.get(expr.object.name);
+                    if (typeof objValue === 'object' && objValue !== null) {
+                        return objValue[expr.component];
+                    }
+                }
+                throw new Error(`Cannot evaluate component access: ${JSON.stringify(expr)}`);
+        }
+        throw new Error(`Cannot evaluate expression: ${JSON.stringify(expr)}`);
+    }
+    /**
+     * Evaluate math function
+     */
+    evaluateMathFunction(name, args) {
+        switch (name) {
+            case 'sin': return Math.sin(args[0]);
+            case 'cos': return Math.cos(args[0]);
+            case 'tan': return Math.tan(args[0]);
+            case 'asin': return Math.asin(args[0]);
+            case 'acos': return Math.acos(args[0]);
+            case 'atan': return Math.atan(args[0]);
+            case 'atan2': return Math.atan2(args[0], args[1]);
+            case 'exp': return Math.exp(args[0]);
+            case 'log': return Math.log(args[0]);
+            case 'sqrt': return Math.sqrt(args[0]);
+            case 'abs': return Math.abs(args[0]);
+            case 'pow': return Math.pow(args[0], args[1]);
+            case 'min': return Math.min(args[0], args[1]);
+            case 'max': return Math.max(args[0], args[1]);
+            default:
+                throw new Error(`Unknown math function: ${name}`);
+        }
+    }
+}

package/dist/dsl/Guards.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Edge case guards for generated gradient code
+ * Detects potential issues like division by zero, sqrt of negative, etc.
+ */
+import { Expression, FunctionDef } from './AST.js';
+export interface Guard {
+    type: 'division_by_zero' | 'sqrt_negative' | 'normalize_zero' | 'atan2_zero';
+    expression: Expression;
+    description: string;
+    suggestion: string;
+}
+export interface GuardAnalysisResult {
+    guards: Guard[];
+    hasIssues: boolean;
+}
+/**
+ * Analyze function for potential edge cases
+ */
+export declare function analyzeGuards(func: FunctionDef): GuardAnalysisResult;
+/**
+ * Format guard analysis for display
+ */
+export declare function formatGuardWarnings(result: GuardAnalysisResult): string;
+/**
+ * Generate guard code snippets for common cases
+ */
+export declare function generateGuardCode(guards: Guard[], format?: 'typescript' | 'javascript' | 'python'): string[];

package/dist/dsl/Guards.js

@@ -0,0 +1,206 @@
+/**
+ * Edge case guards for generated gradient code
+ * Detects potential issues like division by zero, sqrt of negative, etc.
+ */
+/**
+ * Analyze function for potential edge cases
+ */
+export function analyzeGuards(func) {
+    const guards = [];
+    // Analyze return expression
+    collectGuards(func.returnExpr, guards);
+    // Analyze intermediate expressions
+    for (const stmt of func.body) {
+        if (stmt.kind === 'assignment') {
+            collectGuards(stmt.expression, guards);
+        }
+    }
+    return {
+        guards,
+        hasIssues: guards.length > 0
+    };
+}
+/**
+ * Collect potential guards from an expression
+ */
+function collectGuards(expr, guards) {
+    switch (expr.kind) {
+        case 'binary':
+            if (expr.operator === '/') {
+                guards.push({
+                    type: 'division_by_zero',
+                    expression: expr.right,
+                    description: `Division by zero if denominator becomes zero`,
+                    suggestion: `Add check: if (denominator === 0) return { value: 0, gradients: {...} };`
+                });
+            }
+            collectGuards(expr.left, guards);
+            collectGuards(expr.right, guards);
+            break;
+        case 'unary':
+            collectGuards(expr.operand, guards);
+            break;
+        case 'call':
+            analyzeCallGuards(expr, guards);
+            for (const arg of expr.args) {
+                collectGuards(arg, guards);
+            }
+            break;
+        case 'component':
+            collectGuards(expr.object, guards);
+            break;
+    }
+}
+/**
+ * Analyze function calls for specific edge cases
+ */
+function analyzeCallGuards(expr, guards) {
+    switch (expr.name) {
+        case 'sqrt':
+            guards.push({
+                type: 'sqrt_negative',
+                expression: expr.args[0],
+                description: `sqrt of negative number produces NaN`,
+                suggestion: `Add check: Math.max(0, value) or abs(value)`
+            });
+            break;
+        case 'magnitude2d':
+        case 'magnitude3d':
+            // magnitude uses sqrt internally
+            guards.push({
+                type: 'sqrt_negative',
+                expression: expr,
+                description: `magnitude of vector (uses sqrt internally)`,
+                suggestion: `Ensure vector components are valid`
+            });
+            break;
+        case 'normalize2d':
+        case 'normalize3d':
+            guards.push({
+                type: 'normalize_zero',
+                expression: expr,
+                description: `Normalizing zero vector causes division by zero`,
+                suggestion: `Check if magnitude > epsilon before normalizing`
+            });
+            break;
+        case 'atan2':
+            guards.push({
+                type: 'atan2_zero',
+                expression: expr,
+                description: `atan2(0, 0) is undefined`,
+                suggestion: `Check if both arguments are zero: if (y === 0 && x === 0) return 0;`
+            });
+            break;
+        case 'log':
+            guards.push({
+                type: 'division_by_zero',
+                expression: expr.args[0],
+                description: `log(0) is -Infinity, log(negative) is NaN`,
+                suggestion: `Add check: Math.max(epsilon, value)`
+            });
+            break;
+        case 'asin':
+        case 'acos':
+            guards.push({
+                type: 'division_by_zero',
+                expression: expr.args[0],
+                description: `${expr.name} requires argument in [-1, 1]`,
+                suggestion: `Clamp value: Math.max(-1, Math.min(1, value))`
+            });
+            break;
+    }
+}
+/**
+ * Format guard analysis for display
+ */
+export function formatGuardWarnings(result) {
+    if (!result.hasIssues) {
+        return '';
+    }
+    const lines = [];
+    lines.push('⚠️  EDGE CASE WARNINGS:');
+    lines.push('');
+    lines.push('The generated code may encounter edge cases that produce');
+    lines.push('NaN, Infinity, or incorrect results:');
+    lines.push('');
+    // Group by type
+    const byType = new Map();
+    for (const guard of result.guards) {
+        const existing = byType.get(guard.type) || [];
+        existing.push(guard);
+        byType.set(guard.type, existing);
+    }
+    for (const [type, guards] of byType.entries()) {
+        const typeLabel = formatGuardType(type);
+        lines.push(`  • ${typeLabel} (${guards.length} occurrence${guards.length > 1 ? 's' : ''})`);
+        // Show first occurrence
+        const first = guards[0];
+        lines.push(`    ${first.description}`);
+        lines.push(`    💡 ${first.suggestion}`);
+        lines.push('');
+    }
+    lines.push('Consider adding runtime checks or ensuring inputs are within valid ranges.');
+    lines.push('');
+    return lines.join('\n');
+}
+function formatGuardType(type) {
+    switch (type) {
+        case 'division_by_zero':
+            return 'Division by zero';
+        case 'sqrt_negative':
+            return 'Square root of negative';
+        case 'normalize_zero':
+            return 'Normalizing zero vector';
+        case 'atan2_zero':
+            return 'atan2(0, 0) undefined';
+        default:
+            return type;
+    }
+}
+/**
+ * Generate guard code snippets for common cases
+ */
+export function generateGuardCode(guards, format = 'typescript') {
+    const snippets = [];
+    // Group by type and generate appropriate guards
+    const hasNormalize = guards.some(g => g.type === 'normalize_zero');
+    const hasDivision = guards.some(g => g.type === 'division_by_zero');
+    const hasAtan2 = guards.some(g => g.type === 'atan2_zero');
+    if (format === 'typescript' || format === 'javascript') {
+        if (hasNormalize) {
+            snippets.push('const EPSILON = 1e-10;');
+            snippets.push('if (magnitude < EPSILON) {');
+            snippets.push('  // Return zero gradient for zero vector');
+            snippets.push('  return { value: 0, grad_v: { x: 0, y: 0 } };');
+            snippets.push('}');
+        }
+        if (hasDivision) {
+            snippets.push('// Guard against division by zero');
+            snippets.push('if (Math.abs(denominator) < EPSILON) {');
+            snippets.push('  // Handle edge case appropriately');
+            snippets.push('}');
+        }
+        if (hasAtan2) {
+            snippets.push('// Guard against atan2(0, 0)');
+            snippets.push('if (y === 0 && x === 0) {');
+            snippets.push('  return { value: 0, gradients: {...} };');
+            snippets.push('}');
+        }
+    }
+    else {
+        // Python
+        if (hasNormalize) {
+            snippets.push('EPSILON = 1e-10');
+            snippets.push('if magnitude < EPSILON:');
+            snippets.push('    # Return zero gradient for zero vector');
+            snippets.push('    return {"value": 0, "grad_v": {"x": 0, "y": 0}}');
+        }
+        if (hasDivision) {
+            snippets.push('# Guard against division by zero');
+            snippets.push('if abs(denominator) < EPSILON:');
+            snippets.push('    # Handle edge case appropriately');
+            snippets.push('    pass');
+        }
+    }
+    return snippets;
+}

package/dist/dsl/Inliner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Inliner for GradientScript DSL
+ * Inlines intermediate variables before differentiation
+ */
+import { Expression, FunctionDef } from './AST.js';
+/**
+ * Inline all intermediate variables in a function
+ * Returns a new expression with all intermediate variables substituted
+ */
+export declare function inlineIntermediateVariables(func: FunctionDef): Expression;

package/dist/dsl/Inliner.js

@@ -0,0 +1,40 @@
+/**
+ * Inliner for GradientScript DSL
+ * Inlines intermediate variables before differentiation
+ */
+import { ExpressionTransformer } from './ExpressionTransformer.js';
+/**
+ * Expression transformer that substitutes variables from a substitution map
+ * Handles recursive inlining by reprocessing substituted expressions
+ */
+class SubstitutionTransformer extends ExpressionTransformer {
+    substitutions;
+    constructor(substitutions) {
+        super();
+        this.substitutions = substitutions;
+    }
+    visitVariable(node) {
+        const replacement = this.substitutions.get(node.name);
+        if (replacement) {
+            // Recursively inline the replacement
+            return this.transform(replacement);
+        }
+        return node;
+    }
+}
+/**
+ * Inline all intermediate variables in a function
+ * Returns a new expression with all intermediate variables substituted
+ */
+export function inlineIntermediateVariables(func) {
+    // Build substitution map from assignments
+    const substitutions = new Map();
+    for (const stmt of func.body) {
+        if (stmt.kind === 'assignment') {
+            substitutions.set(stmt.variable, stmt.expression);
+        }
+    }
+    // Use transformer to inline all variables
+    const transformer = new SubstitutionTransformer(substitutions);
+    return transformer.transform(func.returnExpr);
+}

package/dist/dsl/Lexer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Lexer for GradientScript DSL
+ * Tokenizes input with support for ∇, ^, **, and structured types
+ */
+export declare enum TokenType {
+    NUMBER = "NUMBER",
+    IDENTIFIER = "IDENTIFIER",
+    FUNCTION = "FUNCTION",
+    RETURN = "RETURN",
+    PLUS = "PLUS",// +
+    MINUS = "MINUS",// -
+    MULTIPLY = "MULTIPLY",// *
+    DIVIDE = "DIVIDE",// /
+    POWER = "POWER",// ^
+    POWER_ALT = "POWER_ALT",// **
+    NABLA = "NABLA",// ∇
+    LPAREN = "LPAREN",// (
+    RPAREN = "RPAREN",// )
+    LBRACE = "LBRACE",// {
+    RBRACE = "RBRACE",// }
+    COMMA = "COMMA",// ,
+    COLON = "COLON",// :
+    DOT = "DOT",// .
+    EQUALS = "EQUALS",// =
+    NEWLINE = "NEWLINE",
+    EOF = "EOF"
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+    line: number;
+    column: number;
+}
+export declare class Lexer {
+    private input;
+    private position;
+    private line;
+    private column;
+    constructor(input: string);
+    /**
+     * Get all tokens
+     */
+    tokenize(): Token[];
+    /**
+     * Get next token
+     */
+    nextToken(): Token;
+    private number;
+    private identifier;
+    private skipWhitespace;
+    private peek;
+    private peekNext;
+    private advance;
+    private isAtEnd;
+    private isDigit;
+    private isAlpha;
+    private isAlphaNumeric;
+    private makeToken;
+}
+/**
+ * Convenience function to tokenize input
+ */
+export declare function tokenize(input: string): Token[];