gradient-script 0.1.0

package/dist/dsl/Expander.js

@@ -0,0 +1,220 @@
+/**
+ * Expander for GradientScript DSL
+ * Expands built-in functions and struct operations into scalar operations
+ */
+/**
+ * Expand built-in function calls to scalar expressions
+ */
+export function expandBuiltIn(call) {
+    const { name, args } = call;
+    switch (name) {
+        case 'dot2d':
+            return expandDot2d(args[0], args[1]);
+        case 'cross2d':
+            return expandCross2d(args[0], args[1]);
+        case 'magnitude2d':
+            return expandMagnitude2d(args[0]);
+        case 'normalize2d':
+            throw new Error('normalize2d not yet supported in differentiation');
+        case 'distance2d':
+            return expandDistance2d(args[0], args[1]);
+        case 'dot3d':
+            return expandDot3d(args[0], args[1]);
+        case 'cross3d':
+            throw new Error('cross3d returns vector - not yet supported');
+        case 'magnitude3d':
+            return expandMagnitude3d(args[0]);
+        default:
+            // Math functions (sin, cos, etc.) don't need expansion
+            return call;
+    }
+}
+/**
+ * Expand dot2d(u, v) → u.x * v.x + u.y * v.y
+ */
+function expandDot2d(u, v) {
+    return {
+        kind: 'binary',
+        operator: '+',
+        left: {
+            kind: 'binary',
+            operator: '*',
+            left: component(u, 'x'),
+            right: component(v, 'x')
+        },
+        right: {
+            kind: 'binary',
+            operator: '*',
+            left: component(u, 'y'),
+            right: component(v, 'y')
+        }
+    };
+}
+/**
+ * Expand cross2d(u, v) → u.x * v.y - u.y * v.x
+ */
+function expandCross2d(u, v) {
+    return {
+        kind: 'binary',
+        operator: '-',
+        left: {
+            kind: 'binary',
+            operator: '*',
+            left: component(u, 'x'),
+            right: component(v, 'y')
+        },
+        right: {
+            kind: 'binary',
+            operator: '*',
+            left: component(u, 'y'),
+            right: component(v, 'x')
+        }
+    };
+}
+/**
+ * Expand magnitude2d(v) → sqrt(v.x^2 + v.y^2)
+ */
+function expandMagnitude2d(v) {
+    return {
+        kind: 'call',
+        name: 'sqrt',
+        args: [{
+                kind: 'binary',
+                operator: '+',
+                left: {
+                    kind: 'binary',
+                    operator: '^',
+                    left: component(v, 'x'),
+                    right: { kind: 'number', value: 2 }
+                },
+                right: {
+                    kind: 'binary',
+                    operator: '^',
+                    left: component(v, 'y'),
+                    right: { kind: 'number', value: 2 }
+                }
+            }]
+    };
+}
+/**
+ * Expand distance2d(p1, p2) → magnitude2d(p2 - p1)
+ * But we can't subtract structs yet, so expand fully:
+ * sqrt((p2.x - p1.x)^2 + (p2.y - p1.y)^2)
+ */
+function expandDistance2d(p1, p2) {
+    const dx = {
+        kind: 'binary',
+        operator: '-',
+        left: component(p2, 'x'),
+        right: component(p1, 'x')
+    };
+    const dy = {
+        kind: 'binary',
+        operator: '-',
+        left: component(p2, 'y'),
+        right: component(p1, 'y')
+    };
+    return {
+        kind: 'call',
+        name: 'sqrt',
+        args: [{
+                kind: 'binary',
+                operator: '+',
+                left: {
+                    kind: 'binary',
+                    operator: '^',
+                    left: dx,
+                    right: { kind: 'number', value: 2 }
+                },
+                right: {
+                    kind: 'binary',
+                    operator: '^',
+                    left: dy,
+                    right: { kind: 'number', value: 2 }
+                }
+            }]
+    };
+}
+/**
+ * Expand dot3d(u, v) → u.x * v.x + u.y * v.y + u.z * v.z
+ */
+function expandDot3d(u, v) {
+    return {
+        kind: 'binary',
+        operator: '+',
+        left: {
+            kind: 'binary',
+            operator: '+',
+            left: {
+                kind: 'binary',
+                operator: '*',
+                left: component(u, 'x'),
+                right: component(v, 'x')
+            },
+            right: {
+                kind: 'binary',
+                operator: '*',
+                left: component(u, 'y'),
+                right: component(v, 'y')
+            }
+        },
+        right: {
+            kind: 'binary',
+            operator: '*',
+            left: component(u, 'z'),
+            right: component(v, 'z')
+        }
+    };
+}
+/**
+ * Expand magnitude3d(v) → sqrt(v.x^2 + v.y^2 + v.z^2)
+ */
+function expandMagnitude3d(v) {
+    return {
+        kind: 'call',
+        name: 'sqrt',
+        args: [{
+                kind: 'binary',
+                operator: '+',
+                left: {
+                    kind: 'binary',
+                    operator: '+',
+                    left: {
+                        kind: 'binary',
+                        operator: '^',
+                        left: component(v, 'x'),
+                        right: { kind: 'number', value: 2 }
+                    },
+                    right: {
+                        kind: 'binary',
+                        operator: '^',
+                        left: component(v, 'y'),
+                        right: { kind: 'number', value: 2 }
+                    }
+                },
+                right: {
+                    kind: 'binary',
+                    operator: '^',
+                    left: component(v, 'z'),
+                    right: { kind: 'number', value: 2 }
+                }
+            }]
+    };
+}
+/**
+ * Helper: Create component access expression
+ */
+function component(obj, comp) {
+    return {
+        kind: 'component',
+        object: obj,
+        component: comp
+    };
+}
+/**
+ * Check if a function call should be expanded
+ */
+export function shouldExpand(name) {
+    const expandable = ['dot2d', 'cross2d', 'magnitude2d', 'distance2d', 'dot3d', 'magnitude3d'];
+    return expandable.includes(name);
+}

package/dist/dsl/ExpressionTransformer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ExpressionTransformer - Abstract base class for AST transformations
+ *
+ * This class eliminates duplicated AST traversal logic by providing:
+ * - Default recursive descent for all expression types
+ * - Protected visit methods that subclasses can override
+ * - Type-safe transformation pipeline
+ *
+ * Usage:
+ *   class MyTransformer extends ExpressionTransformer {
+ *     protected visitBinaryOp(node: BinaryOp): Expression {
+ *       // Custom logic here
+ *       return super.visitBinaryOp(node); // Or custom result
+ *     }
+ *   }
+ */
+import { Expression, NumberLiteral, Variable, BinaryOp, UnaryOp, FunctionCall, ComponentAccess } from './AST.js';
+export declare abstract class ExpressionTransformer {
+    /**
+     * Main entry point for transforming an expression
+     * Dispatches to appropriate visit method based on node kind
+     */
+    transform(expr: Expression): Expression;
+    /**
+     * Visit a number literal
+     * Default: Return unchanged (identity transformation)
+     */
+    protected visitNumber(node: NumberLiteral): Expression;
+    /**
+     * Visit a variable reference
+     * Default: Return unchanged (identity transformation)
+     */
+    protected visitVariable(node: Variable): Expression;
+    /**
+     * Visit a binary operation
+     * Default: Transform left and right children, return new node
+     */
+    protected visitBinaryOp(node: BinaryOp): Expression;
+    /**
+     * Visit a unary operation
+     * Default: Transform operand, return new node
+     */
+    protected visitUnaryOp(node: UnaryOp): Expression;
+    /**
+     * Visit a function call
+     * Default: Transform all arguments, return new node
+     */
+    protected visitFunctionCall(node: FunctionCall): Expression;
+    /**
+     * Visit a component access (e.g., v.x)
+     * Default: Transform object, return new node
+     */
+    protected visitComponentAccess(node: ComponentAccess): Expression;
+}

package/dist/dsl/ExpressionTransformer.js

@@ -0,0 +1,102 @@
+/**
+ * ExpressionTransformer - Abstract base class for AST transformations
+ *
+ * This class eliminates duplicated AST traversal logic by providing:
+ * - Default recursive descent for all expression types
+ * - Protected visit methods that subclasses can override
+ * - Type-safe transformation pipeline
+ *
+ * Usage:
+ *   class MyTransformer extends ExpressionTransformer {
+ *     protected visitBinaryOp(node: BinaryOp): Expression {
+ *       // Custom logic here
+ *       return super.visitBinaryOp(node); // Or custom result
+ *     }
+ *   }
+ */
+export class ExpressionTransformer {
+    /**
+     * Main entry point for transforming an expression
+     * Dispatches to appropriate visit method based on node kind
+     */
+    transform(expr) {
+        switch (expr.kind) {
+            case 'number':
+                return this.visitNumber(expr);
+            case 'variable':
+                return this.visitVariable(expr);
+            case 'binary':
+                return this.visitBinaryOp(expr);
+            case 'unary':
+                return this.visitUnaryOp(expr);
+            case 'call':
+                return this.visitFunctionCall(expr);
+            case 'component':
+                return this.visitComponentAccess(expr);
+        }
+    }
+    /**
+     * Visit a number literal
+     * Default: Return unchanged (identity transformation)
+     */
+    visitNumber(node) {
+        return node;
+    }
+    /**
+     * Visit a variable reference
+     * Default: Return unchanged (identity transformation)
+     */
+    visitVariable(node) {
+        return node;
+    }
+    /**
+     * Visit a binary operation
+     * Default: Transform left and right children, return new node
+     */
+    visitBinaryOp(node) {
+        const left = this.transform(node.left);
+        const right = this.transform(node.right);
+        return {
+            kind: 'binary',
+            operator: node.operator,
+            left,
+            right
+        };
+    }
+    /**
+     * Visit a unary operation
+     * Default: Transform operand, return new node
+     */
+    visitUnaryOp(node) {
+        const operand = this.transform(node.operand);
+        return {
+            kind: 'unary',
+            operator: node.operator,
+            operand
+        };
+    }
+    /**
+     * Visit a function call
+     * Default: Transform all arguments, return new node
+     */
+    visitFunctionCall(node) {
+        const args = node.args.map(arg => this.transform(arg));
+        return {
+            kind: 'call',
+            name: node.name,
+            args
+        };
+    }
+    /**
+     * Visit a component access (e.g., v.x)
+     * Default: Transform object, return new node
+     */
+    visitComponentAccess(node) {
+        const object = this.transform(node.object);
+        return {
+            kind: 'component',
+            object,
+            component: node.component
+        };
+    }
+}

package/dist/dsl/ExpressionUtils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility functions for expression manipulation
+ * Eliminates code duplication across Differentiation, Inliner, and CSE modules
+ */
+import { Expression, NumberLiteral, Variable, BinaryOp } from './AST.js';
+/**
+ * Substitute all occurrences of a variable with a replacement expression
+ * Used by: Differentiation, Inliner, CSE
+ */
+export declare function substituteVariable(expr: Expression, varName: string, replacement: Expression): Expression;
+/**
+ * Check if expression is zero
+ */
+export declare function isZero(expr: Expression): boolean;
+/**
+ * Check if expression is one
+ */
+export declare function isOne(expr: Expression): boolean;
+/**
+ * Check if expression is a constant (number literal)
+ */
+export declare function isConstant(expr: Expression): boolean;
+/**
+ * Check if expression is a variable
+ * If name is provided, checks if it matches that specific variable name
+ */
+export declare function isVariable(expr: Expression, name?: string): boolean;
+/**
+ * Check if expression is a negative number
+ */
+export declare function isNegative(expr: Expression): boolean;
+/**
+ * Create a number literal
+ */
+export declare function makeNumber(value: number): NumberLiteral;
+/**
+ * Create a binary operation
+ */
+export declare function makeBinaryOp(op: '+' | '-' | '*' | '/' | '^' | '**', left: Expression, right: Expression): BinaryOp;
+/**
+ * Create a variable reference
+ */
+export declare function makeVariable(name: string): Variable;
+/**
+ * Get all variable names used in an expression
+ */
+export declare function getVariables(expr: Expression): Set<string>;
+/**
+ * Check if an expression contains a specific variable
+ */
+export declare function containsVariable(expr: Expression, varName: string): boolean;
+/**
+ * Calculate the maximum nesting depth of an expression
+ */
+export declare function expressionDepth(expr: Expression): number;

package/dist/dsl/ExpressionUtils.js

@@ -0,0 +1,175 @@
+/**
+ * Shared utility functions for expression manipulation
+ * Eliminates code duplication across Differentiation, Inliner, and CSE modules
+ */
+/**
+ * Substitute all occurrences of a variable with a replacement expression
+ * Used by: Differentiation, Inliner, CSE
+ */
+export function substituteVariable(expr, varName, replacement) {
+    switch (expr.kind) {
+        case 'number':
+            return expr;
+        case 'variable':
+            return expr.name === varName ? replacement : expr;
+        case 'binary':
+            return {
+                kind: 'binary',
+                operator: expr.operator,
+                left: substituteVariable(expr.left, varName, replacement),
+                right: substituteVariable(expr.right, varName, replacement)
+            };
+        case 'unary':
+            return {
+                kind: 'unary',
+                operator: expr.operator,
+                operand: substituteVariable(expr.operand, varName, replacement)
+            };
+        case 'call':
+            return {
+                kind: 'call',
+                name: expr.name,
+                args: expr.args.map(arg => substituteVariable(arg, varName, replacement))
+            };
+        case 'component':
+            return {
+                kind: 'component',
+                object: substituteVariable(expr.object, varName, replacement),
+                component: expr.component
+            };
+    }
+}
+/**
+ * Check if expression is zero
+ */
+export function isZero(expr) {
+    return expr.kind === 'number' && expr.value === 0;
+}
+/**
+ * Check if expression is one
+ */
+export function isOne(expr) {
+    return expr.kind === 'number' && expr.value === 1;
+}
+/**
+ * Check if expression is a constant (number literal)
+ */
+export function isConstant(expr) {
+    return expr.kind === 'number';
+}
+/**
+ * Check if expression is a variable
+ * If name is provided, checks if it matches that specific variable name
+ */
+export function isVariable(expr, name) {
+    if (expr.kind !== 'variable') {
+        return false;
+    }
+    return name === undefined || expr.name === name;
+}
+/**
+ * Check if expression is a negative number
+ */
+export function isNegative(expr) {
+    return expr.kind === 'number' && expr.value < 0;
+}
+/**
+ * Create a number literal
+ */
+export function makeNumber(value) {
+    return { kind: 'number', value };
+}
+/**
+ * Create a binary operation
+ */
+export function makeBinaryOp(op, left, right) {
+    return {
+        kind: 'binary',
+        operator: op,
+        left,
+        right
+    };
+}
+/**
+ * Create a variable reference
+ */
+export function makeVariable(name) {
+    return { kind: 'variable', name };
+}
+/**
+ * Get all variable names used in an expression
+ */
+export function getVariables(expr) {
+    const vars = new Set();
+    function collect(e) {
+        switch (e.kind) {
+            case 'variable':
+                vars.add(e.name);
+                break;
+            case 'binary':
+                collect(e.left);
+                collect(e.right);
+                break;
+            case 'unary':
+                collect(e.operand);
+                break;
+            case 'call':
+                for (const arg of e.args) {
+                    collect(arg);
+                }
+                break;
+            case 'component':
+                collect(e.object);
+                if (e.object.kind === 'variable') {
+                    vars.add(`${e.object.name}.${e.component}`);
+                }
+                break;
+        }
+    }
+    collect(expr);
+    return vars;
+}
+/**
+ * Check if an expression contains a specific variable
+ */
+export function containsVariable(expr, varName) {
+    switch (expr.kind) {
+        case 'number':
+            return false;
+        case 'variable':
+            return expr.name === varName;
+        case 'binary':
+            return containsVariable(expr.left, varName) || containsVariable(expr.right, varName);
+        case 'unary':
+            return containsVariable(expr.operand, varName);
+        case 'call':
+            return expr.args.some(arg => containsVariable(arg, varName));
+        case 'component':
+            if (expr.object.kind === 'variable') {
+                const fullName = `${expr.object.name}.${expr.component}`;
+                return fullName === varName || expr.object.name === varName;
+            }
+            return containsVariable(expr.object, varName);
+    }
+}
+/**
+ * Calculate the maximum nesting depth of an expression
+ */
+export function expressionDepth(expr) {
+    switch (expr.kind) {
+        case 'number':
+        case 'variable':
+            return 1;
+        case 'binary':
+            return 1 + Math.max(expressionDepth(expr.left), expressionDepth(expr.right));
+        case 'unary':
+            return 1 + expressionDepth(expr.operand);
+        case 'call':
+            if (expr.args.length === 0) {
+                return 1;
+            }
+            return 1 + Math.max(...expr.args.map(expressionDepth));
+        case 'component':
+            return 1 + expressionDepth(expr.object);
+    }
+}

package/dist/dsl/GradientChecker.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Numerical gradient checking for GradientScript DSL
+ * Validates symbolic gradients against finite difference approximations
+ */
+import { FunctionDef } from './AST.js';
+import { TypeEnv } from './Types.js';
+import { GradientResult } from './Differentiation.js';
+/**
+ * Numerical value (scalar or structured)
+ */
+type NumValue = number | {
+    [key: string]: number;
+};
+/**
+ * Gradient checking result
+ */
+export interface GradCheckResult {
+    passed: boolean;
+    errors: GradCheckError[];
+    maxError: number;
+    meanError: number;
+}
+export interface GradCheckError {
+    parameter: string;
+    component?: string;
+    analytical: number;
+    numerical: number;
+    error: number;
+    relativeError: number;
+}
+/**
+ * Gradient checker
+ */
+export declare class GradientChecker {
+    private epsilon;
+    private tolerance;
+    constructor(epsilon?: number, tolerance?: number);
+    /**
+     * Check gradients for a function
+     */
+    check(func: FunctionDef, gradients: GradientResult, env: TypeEnv, testPoint: Map<string, NumValue>): GradCheckResult;
+    /**
+     * Compute numerical gradient for scalar parameter using finite differences
+     */
+    private numericalGradientScalar;
+    /**
+     * Compute numerical gradient for structured parameter component
+     */
+    private numericalGradientComponent;
+    /**
+     * Evaluate function at a test point
+     */
+    private evaluateFunction;
+    /**
+     * Inline function body with test point values
+     */
+    private inlineWithValues;
+    /**
+     * Substitute variables in expression
+     */
+    private substituteExpression;
+    /**
+     * Evaluate an expression numerically
+     */
+    private evaluateExpression;
+    /**
+     * Evaluate math function
+     */
+    private evaluateMathFunction;
+}
+export {};