scalar-autograd 0.1.7 → 0.1.9

package/dist/symbolic/AST.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Abstract Syntax Tree (AST) node definitions for symbolic differentiation.
+ * @internal
+ */
+/**
+ * Base interface for all AST nodes
+ */
+export interface ASTNode {
+    type: string;
+    accept<T>(visitor: ASTVisitor<T>): T;
+}
+/**
+ * Visitor pattern interface for traversing AST
+ */
+export interface ASTVisitor<T> {
+    visitNumber(node: NumberNode): T;
+    visitVariable(node: VariableNode): T;
+    visitBinaryOp(node: BinaryOpNode): T;
+    visitUnaryOp(node: UnaryOpNode): T;
+    visitFunctionCall(node: FunctionCallNode): T;
+    visitVectorAccess(node: VectorAccessNode): T;
+    visitVectorConstructor(node: VectorConstructorNode): T;
+}
+/**
+ * Numeric constant node
+ */
+export declare class NumberNode implements ASTNode {
+    value: number;
+    type: "Number";
+    constructor(value: number);
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Variable reference node (e.g., 'x', 'y', 'a')
+ */
+export declare class VariableNode implements ASTNode {
+    name: string;
+    type: "Variable";
+    constructor(name: string);
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Binary operation node (e.g., a + b, x * y)
+ */
+export declare class BinaryOpNode implements ASTNode {
+    op: '+' | '-' | '*' | '/' | '**' | 'pow';
+    left: ASTNode;
+    right: ASTNode;
+    type: "BinaryOp";
+    constructor(op: '+' | '-' | '*' | '/' | '**' | 'pow', left: ASTNode, right: ASTNode);
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Unary operation node (e.g., -x, +y)
+ */
+export declare class UnaryOpNode implements ASTNode {
+    op: '+' | '-';
+    operand: ASTNode;
+    type: "UnaryOp";
+    constructor(op: '+' | '-', operand: ASTNode);
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Function call node (e.g., sin(x), sqrt(y), max(a, b))
+ */
+export declare class FunctionCallNode implements ASTNode {
+    name: string;
+    args: ASTNode[];
+    type: "FunctionCall";
+    constructor(name: string, args: ASTNode[]);
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Vector component access node (e.g., v.x, point.y)
+ */
+export declare class VectorAccessNode implements ASTNode {
+    vector: ASTNode;
+    component: 'x' | 'y' | 'z';
+    type: "VectorAccess";
+    constructor(vector: ASTNode, component: 'x' | 'y' | 'z');
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Vector constructor node (e.g., Vec2(x, y), Vec3(1, 2, 3))
+ */
+export declare class VectorConstructorNode implements ASTNode {
+    vectorType: 'Vec2' | 'Vec3';
+    components: ASTNode[];
+    type: "VectorConstructor";
+    constructor(vectorType: 'Vec2' | 'Vec3', components: ASTNode[]);
+    accept<T>(visitor: ASTVisitor<T>): T;
+    toString(): string;
+}
+/**
+ * Assignment statement (e.g., x = 5, y = x + 2)
+ */
+export interface Assignment {
+    variable: string;
+    expression: ASTNode;
+}
+/**
+ * Complete program with assignments and output
+ */
+export interface Program {
+    assignments: Assignment[];
+    output: string;
+}

package/dist/symbolic/AST.js

@@ -0,0 +1,128 @@
+/**
+ * Abstract Syntax Tree (AST) node definitions for symbolic differentiation.
+ * @internal
+ */
+/**
+ * Numeric constant node
+ */
+export class NumberNode {
+    value;
+    type = 'Number';
+    constructor(value) {
+        this.value = value;
+    }
+    accept(visitor) {
+        return visitor.visitNumber(this);
+    }
+    toString() {
+        return String(this.value);
+    }
+}
+/**
+ * Variable reference node (e.g., 'x', 'y', 'a')
+ */
+export class VariableNode {
+    name;
+    type = 'Variable';
+    constructor(name) {
+        this.name = name;
+    }
+    accept(visitor) {
+        return visitor.visitVariable(this);
+    }
+    toString() {
+        return this.name;
+    }
+}
+/**
+ * Binary operation node (e.g., a + b, x * y)
+ */
+export class BinaryOpNode {
+    op;
+    left;
+    right;
+    type = 'BinaryOp';
+    constructor(op, left, right) {
+        this.op = op;
+        this.left = left;
+        this.right = right;
+    }
+    accept(visitor) {
+        return visitor.visitBinaryOp(this);
+    }
+    toString() {
+        return `(${this.left.toString()} ${this.op} ${this.right.toString()})`;
+    }
+}
+/**
+ * Unary operation node (e.g., -x, +y)
+ */
+export class UnaryOpNode {
+    op;
+    operand;
+    type = 'UnaryOp';
+    constructor(op, operand) {
+        this.op = op;
+        this.operand = operand;
+    }
+    accept(visitor) {
+        return visitor.visitUnaryOp(this);
+    }
+    toString() {
+        return `${this.op}${this.operand.toString()}`;
+    }
+}
+/**
+ * Function call node (e.g., sin(x), sqrt(y), max(a, b))
+ */
+export class FunctionCallNode {
+    name;
+    args;
+    type = 'FunctionCall';
+    constructor(name, args) {
+        this.name = name;
+        this.args = args;
+    }
+    accept(visitor) {
+        return visitor.visitFunctionCall(this);
+    }
+    toString() {
+        return `${this.name}(${this.args.map(a => a.toString()).join(', ')})`;
+    }
+}
+/**
+ * Vector component access node (e.g., v.x, point.y)
+ */
+export class VectorAccessNode {
+    vector;
+    component;
+    type = 'VectorAccess';
+    constructor(vector, component) {
+        this.vector = vector;
+        this.component = component;
+    }
+    accept(visitor) {
+        return visitor.visitVectorAccess(this);
+    }
+    toString() {
+        return `${this.vector.toString()}.${this.component}`;
+    }
+}
+/**
+ * Vector constructor node (e.g., Vec2(x, y), Vec3(1, 2, 3))
+ */
+export class VectorConstructorNode {
+    vectorType;
+    components;
+    type = 'VectorConstructor';
+    constructor(vectorType, components) {
+        this.vectorType = vectorType;
+        this.components = components;
+    }
+    accept(visitor) {
+        return visitor.visitVectorConstructor(this);
+    }
+    toString() {
+        return `${this.vectorType}(${this.components.map(c => c.toString()).join(', ')})`;
+    }
+}

package/dist/symbolic/CodeGen.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Code generator for symbolic gradients.
+ * Generates executable JavaScript/TypeScript code with mathematical annotations.
+ * @internal
+ */
+import { ASTNode, Program } from './AST';
+/**
+ * Generate JavaScript code from AST
+ */
+export declare function generateCode(node: ASTNode): string;
+/**
+ * Generate mathematical notation from AST
+ */
+export declare function generateMathNotation(node: ASTNode): string;
+/**
+ * Generate complete gradient computation code
+ */
+export interface CodeGenOptions {
+    /** Include mathematical notation as comments */
+    includeMath?: boolean;
+    /** Variable declaration style */
+    varStyle?: 'const' | 'let' | 'var';
+    /** Include forward pass computation */
+    includeForward?: boolean;
+    /** Format code with indentation */
+    indent?: string;
+}
+/**
+ * Generate complete gradient code for a program
+ */
+export declare function generateGradientCode(program: Program, gradients: Map<string, ASTNode>, options?: CodeGenOptions): string;
+/**
+ * Generate gradient code as a function
+ */
+export declare function generateGradientFunction(program: Program, gradients: Map<string, ASTNode>, functionName: string, parameters: string[], options?: CodeGenOptions): string;

package/dist/symbolic/CodeGen.js

@@ -0,0 +1,280 @@
+/**
+ * Code generator for symbolic gradients.
+ * Generates executable JavaScript/TypeScript code with mathematical annotations.
+ * @internal
+ */
+/**
+ * Code generation visitor - generates JavaScript expressions
+ */
+class CodeGenVisitor {
+    visitNumber(node) {
+        return String(node.value);
+    }
+    visitVariable(node) {
+        return node.name;
+    }
+    visitUnaryOp(node) {
+        const operand = node.operand.accept(this);
+        // Add parentheses if operand is complex
+        if (needsParens(node.operand)) {
+            return `${node.op}(${operand})`;
+        }
+        return `${node.op}${operand}`;
+    }
+    visitBinaryOp(node) {
+        const left = node.left.accept(this);
+        const right = node.right.accept(this);
+        // Handle precedence with parentheses
+        const leftStr = needsParens(node.left, node.op) ? `(${left})` : left;
+        const rightStr = needsParens(node.right, node.op, 'right') ? `(${right})` : right;
+        if (node.op === '**') {
+            return `Math.pow(${leftStr}, ${rightStr})`;
+        }
+        return `${leftStr} ${node.op} ${rightStr}`;
+    }
+    visitFunctionCall(node) {
+        const args = node.args.map(arg => arg.accept(this)).join(', ');
+        // Map function names to Math functions
+        const funcMap = {
+            'sin': 'Math.sin',
+            'cos': 'Math.cos',
+            'tan': 'Math.tan',
+            'asin': 'Math.asin',
+            'acos': 'Math.acos',
+            'atan': 'Math.atan',
+            'sinh': 'Math.sinh',
+            'cosh': 'Math.cosh',
+            'tanh': 'Math.tanh',
+            'exp': 'Math.exp',
+            'log': 'Math.log',
+            'ln': 'Math.log',
+            'sqrt': 'Math.sqrt',
+            'abs': 'Math.abs',
+            'sign': 'Math.sign',
+            'floor': 'Math.floor',
+            'ceil': 'Math.ceil',
+            'round': 'Math.round',
+            'pow': 'Math.pow',
+            'min': 'Math.min',
+            'max': 'Math.max',
+            'atan2': 'Math.atan2',
+            'heaviside': '(x => x > 0 ? 1 : 0)',
+            'sigmoid': '(x => 1 / (1 + Math.exp(-x)))'
+        };
+        const funcName = funcMap[node.name] || node.name;
+        return `${funcName}(${args})`;
+    }
+    visitVectorAccess(node) {
+        const vector = node.vector.accept(this);
+        return `${vector}.${node.component}`;
+    }
+    visitVectorConstructor(node) {
+        const components = node.components.map(c => c.accept(this)).join(', ');
+        return `${node.vectorType}(${components})`;
+    }
+}
+/**
+ * Check if node needs parentheses based on operator precedence
+ */
+function needsParens(node, parentOp, position = 'left') {
+    if (node.type === 'Number' || node.type === 'Variable' ||
+        node.type === 'FunctionCall' || node.type === 'VectorAccess') {
+        return false;
+    }
+    if (node.type === 'UnaryOp') {
+        return false; // Unary operators have high precedence
+    }
+    if (node.type === 'BinaryOp' && parentOp) {
+        const binNode = node;
+        const nodePrecedence = getPrecedence(binNode.op);
+        const parentPrecedence = getPrecedence(parentOp);
+        // Need parens if lower precedence
+        if (nodePrecedence < parentPrecedence) {
+            return true;
+        }
+        // For same precedence, check associativity
+        if (nodePrecedence === parentPrecedence) {
+            // Right-associative operators: ** (power)
+            if (parentOp === '**') {
+                return position === 'left'; // Left operand needs parens
+            }
+            // Left-associative: need parens on right for -, /
+            if ((parentOp === '-' || parentOp === '/') && position === 'right') {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Get operator precedence (higher = tighter binding)
+ */
+function getPrecedence(op) {
+    switch (op) {
+        case '+':
+        case '-':
+            return 1;
+        case '*':
+        case '/':
+            return 2;
+        case '**':
+            return 3;
+        default:
+            return 0;
+    }
+}
+/**
+ * Generate mathematical notation for expressions (LaTeX-style comments)
+ */
+class MathNotationVisitor {
+    visitNumber(node) {
+        return String(node.value);
+    }
+    visitVariable(node) {
+        return node.name;
+    }
+    visitUnaryOp(node) {
+        const operand = node.operand.accept(this);
+        if (needsParens(node.operand)) {
+            return `${node.op}(${operand})`;
+        }
+        return `${node.op}${operand}`;
+    }
+    visitBinaryOp(node) {
+        const left = node.left.accept(this);
+        const right = node.right.accept(this);
+        const leftStr = needsParens(node.left, node.op) ? `(${left})` : left;
+        const rightStr = needsParens(node.right, node.op, 'right') ? `(${right})` : right;
+        if (node.op === '**') {
+            return `${leftStr}^${rightStr}`;
+        }
+        return `${leftStr} ${node.op} ${rightStr}`;
+    }
+    visitFunctionCall(node) {
+        const args = node.args.map(arg => arg.accept(this)).join(', ');
+        return `${node.name}(${args})`;
+    }
+    visitVectorAccess(node) {
+        const vector = node.vector.accept(this);
+        return `${vector}.${node.component}`;
+    }
+    visitVectorConstructor(node) {
+        const components = node.components.map(c => c.accept(this)).join(', ');
+        return `${node.vectorType}(${components})`;
+    }
+}
+/**
+ * Generate JavaScript code from AST
+ */
+export function generateCode(node) {
+    const visitor = new CodeGenVisitor();
+    return node.accept(visitor);
+}
+/**
+ * Generate mathematical notation from AST
+ */
+export function generateMathNotation(node) {
+    const visitor = new MathNotationVisitor();
+    return node.accept(visitor);
+}
+/**
+ * Generate complete gradient code for a program
+ */
+export function generateGradientCode(program, gradients, options = {}) {
+    const { includeMath = true, varStyle = 'const', includeForward = true, indent = '  ' } = options;
+    const lines = [];
+    // Header comment
+    lines.push('// Auto-generated gradient computation');
+    lines.push('// Generated by ScalarAutograd symbolic differentiation');
+    lines.push('');
+    if (includeForward) {
+        lines.push('// Forward pass');
+        for (const assignment of program.assignments) {
+            const code = generateCode(assignment.expression);
+            if (includeMath) {
+                const math = generateMathNotation(assignment.expression);
+                lines.push(`// ${assignment.variable} = ${math}`);
+            }
+            lines.push(`${varStyle} ${assignment.variable} = ${code};`);
+            lines.push('');
+        }
+        lines.push('// Gradient computation (reverse-mode autodiff)');
+        lines.push('');
+    }
+    // Generate gradients in topological order
+    const paramNames = Array.from(gradients.keys()).filter(name => name !== program.output);
+    for (const param of paramNames) {
+        const gradNode = gradients.get(param);
+        if (!gradNode)
+            continue;
+        const code = generateCode(gradNode);
+        if (includeMath) {
+            const math = generateMathNotation(gradNode);
+            lines.push(`// ∂${program.output}/∂${param} = ${math}`);
+        }
+        lines.push(`${varStyle} grad_${param} = ${code};`);
+        lines.push('');
+    }
+    // Export result
+    lines.push('// Result');
+    lines.push(`${varStyle} result = {`);
+    lines.push(`${indent}value: ${program.output},`);
+    lines.push(`${indent}gradients: {`);
+    for (const param of paramNames) {
+        lines.push(`${indent}${indent}${param}: grad_${param},`);
+    }
+    lines.push(`${indent}}`);
+    lines.push('};');
+    return lines.join('\n');
+}
+/**
+ * Generate gradient code as a function
+ */
+export function generateGradientFunction(program, gradients, functionName, parameters, options = {}) {
+    const { includeMath = true, indent = '  ' } = options;
+    const lines = [];
+    // Function signature
+    lines.push(`/**`);
+    lines.push(` * Compute ${program.output} and its gradients`);
+    for (const param of parameters) {
+        lines.push(` * @param ${param} - Input parameter`);
+    }
+    lines.push(` * @returns Object with value and gradients`);
+    lines.push(` */`);
+    lines.push(`function ${functionName}(${parameters.join(', ')}) {`);
+    // Forward pass
+    if (includeMath) {
+        lines.push(`${indent}// Forward pass`);
+    }
+    for (const assignment of program.assignments) {
+        const code = generateCode(assignment.expression);
+        if (includeMath) {
+            const math = generateMathNotation(assignment.expression);
+            lines.push(`${indent}// ${assignment.variable} = ${math}`);
+        }
+        lines.push(`${indent}const ${assignment.variable} = ${code};`);
+    }
+    lines.push('');
+    if (includeMath) {
+        lines.push(`${indent}// Gradient computation`);
+    }
+    // Gradients
+    for (const param of parameters) {
+        const gradNode = gradients.get(param);
+        if (!gradNode)
+            continue;
+        const code = generateCode(gradNode);
+        if (includeMath) {
+            const math = generateMathNotation(gradNode);
+            lines.push(`${indent}// ∂${program.output}/∂${param} = ${math}`);
+        }
+        lines.push(`${indent}const grad_${param} = ${code};`);
+    }
+    lines.push('');
+    lines.push(`${indent}return {`);
+    lines.push(`${indent}${indent}value: ${program.output},`);
+    lines.push(`${indent}${indent}gradients: { ${parameters.map(p => `${p}: grad_${p}`).join(', ')} }`);
+    lines.push(`${indent}};`);
+    lines.push('}');
+    return lines.join('\n');
+}

package/dist/symbolic/Parser.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Expression parser for symbolic gradient generation.
+ * Parses operator-overloaded mathematical expressions into AST.
+ * @internal
+ */
+import { Program } from './AST';
+/**
+ * Parser: converts tokens into AST
+ * Grammar (precedence from lowest to highest):
+ *   assignment   → IDENTIFIER '=' expression
+ *   expression   → term (('+' | '-') term)*
+ *   term         → factor (('*' | '/') factor)*
+ *   factor       → power
+ *   power        → postfix ('**' postfix)*
+ *   postfix      → primary ('.' IDENTIFIER)*
+ *   primary      → NUMBER | IDENTIFIER | function_call | vector_constructor | '(' expression ')' | ('+' | '-') primary
+ *   function_call → IDENTIFIER '(' arg_list? ')'
+ *   vector_constructor → ('Vec2' | 'Vec3') '(' arg_list ')'
+ *   arg_list     → expression (',' expression)*
+ */
+export declare class Parser {
+    private tokens;
+    private current;
+    constructor(text: string);
+    private peek;
+    private advance;
+    private expect;
+    /**
+     * Parse a complete program
+     */
+    parseProgram(): Program;
+    /**
+     * Parse an expression
+     */
+    private parseExpression;
+    /**
+     * Parse term (addition/subtraction)
+     */
+    private parseTerm;
+    /**
+     * Parse factor (multiplication/division)
+     */
+    private parseFactor;
+    /**
+     * Parse power (exponentiation)
+     */
+    private parsePower;
+    /**
+     * Parse postfix (member access like v.x)
+     */
+    private parsePostfix;
+    /**
+     * Parse primary expression
+     */
+    private parsePrimary;
+    /**
+     * Parse function argument list
+     */
+    private parseArgList;
+}
+/**
+ * Parse a mathematical expression string into an AST
+ */
+export declare function parse(text: string): Program;