scalar-autograd 0.1.7 → 0.1.9

package/dist/EigenvalueHelpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * External helper functions for eigenvalue computation in compiled code.
+ * These are called from generated JavaScript to avoid inlining huge formulas.
+ */
+/**
+ * Compute smallest eigenvalue of 3x3 symmetric matrix.
+ * Uses Cardano's formula for cubic equation.
+ */
+export declare function computeSmallestEigenvalue(c00: number, c01: number, c02: number, c11: number, c12: number, c22: number): number;
+/**
+ * Apply eigenvalue gradients using analytical formula.
+ * Computes eigenvector and updates input gradients with ∂λ/∂C_ij = v_i * v_j
+ */
+export declare function applyEigenvalueGradients(outGrad: number, c00: number, c01: number, c02: number, c11: number, c12: number, c22: number, g00: number, g01: number, g02: number, g11: number, g12: number, g22: number): [number, number, number, number, number, number];

package/dist/EigenvalueHelpers.js

@@ -0,0 +1,93 @@
+/**
+ * External helper functions for eigenvalue computation in compiled code.
+ * These are called from generated JavaScript to avoid inlining huge formulas.
+ */
+/**
+ * Compute smallest eigenvalue of 3x3 symmetric matrix.
+ * Uses Cardano's formula for cubic equation.
+ */
+export function computeSmallestEigenvalue(c00, c01, c02, c11, c12, c22) {
+    const tr = c00 + c11 + c22;
+    const shift = tr / 3;
+    const b00 = c00 - shift;
+    const b11 = c11 - shift;
+    const b22 = c22 - shift;
+    const q = 0.5 * (b00 * b00 + b11 * b11 + b22 * b22 + 2 * c01 * c01 + 2 * c02 * c02 + 2 * c12 * c12);
+    const p = Math.sqrt((q + 1e-20) / 3);
+    const invP = 1 / (p + 1e-12);
+    const d00 = b00 * invP;
+    const d01 = c01 * invP;
+    const d02 = c02 * invP;
+    const d11 = b11 * invP;
+    const d12 = c12 * invP;
+    const d22 = b22 * invP;
+    const det = d00 * (d11 * d22 - d12 * d12) + d01 * (d12 * d02 - d01 * d22) + d02 * (d01 * d12 - d11 * d02);
+    const r = Math.max(-0.99999, Math.min(det / 2, 0.99999));
+    const theta = Math.acos(r);
+    const angle2 = theta / 3 + 2 * 2.0943951023931953;
+    return shift + 2 * p * Math.cos(angle2);
+}
+/**
+ * Apply eigenvalue gradients using analytical formula.
+ * Computes eigenvector and updates input gradients with ∂λ/∂C_ij = v_i * v_j
+ */
+export function applyEigenvalueGradients(outGrad, c00, c01, c02, c11, c12, c22, g00, g01, g02, g11, g12, g22) {
+    const lambda = computeSmallestEigenvalue(c00, c01, c02, c11, c12, c22);
+    const a00 = c00 - lambda;
+    const a11 = c11 - lambda;
+    const a22 = c22 - lambda;
+    const row0_x = a00, row0_y = c01, row0_z = c02;
+    const row1_x = c01, row1_y = a11, row1_z = c12;
+    const row2_x = c02, row2_y = c12, row2_z = a22;
+    const cross0_x = row0_y * row1_z - row0_z * row1_y;
+    const cross0_y = row0_z * row1_x - row0_x * row1_z;
+    const cross0_z = row0_x * row1_y - row0_y * row1_x;
+    const cross1_x = row0_y * row2_z - row0_z * row2_y;
+    const cross1_y = row0_z * row2_x - row0_x * row2_z;
+    const cross1_z = row0_x * row2_y - row0_y * row2_x;
+    const cross2_x = row1_y * row2_z - row1_z * row2_y;
+    const cross2_y = row1_z * row2_x - row1_x * row2_z;
+    const cross2_z = row1_x * row2_y - row1_y * row2_x;
+    const mag0 = Math.sqrt(cross0_x * cross0_x + cross0_y * cross0_y + cross0_z * cross0_z);
+    const mag1 = Math.sqrt(cross1_x * cross1_x + cross1_y * cross1_y + cross1_z * cross1_z);
+    const mag2 = Math.sqrt(cross2_x * cross2_x + cross2_y * cross2_y + cross2_z * cross2_z);
+    let bestMag = mag0;
+    let vx = cross0_x, vy = cross0_y, vz = cross0_z;
+    if (mag1 > bestMag) {
+        bestMag = mag1;
+        vx = cross1_x;
+        vy = cross1_y;
+        vz = cross1_z;
+    }
+    if (mag2 > bestMag) {
+        bestMag = mag2;
+        vx = cross2_x;
+        vy = cross2_y;
+        vz = cross2_z;
+    }
+    if (bestMag < 1e-12) {
+        vx = 1;
+        vy = 0;
+        vz = 0;
+    }
+    else {
+        vx /= bestMag;
+        vy /= bestMag;
+        vz /= bestMag;
+    }
+    return [
+        g00 + outGrad * vx * vx,
+        g01 + outGrad * 2 * vx * vy,
+        g02 + outGrad * 2 * vx * vz,
+        g11 + outGrad * vy * vy,
+        g12 + outGrad * 2 * vy * vz,
+        g22 + outGrad * vz * vz
+    ];
+}
+// Make available globally for compiled code
+if (typeof window !== 'undefined') {
+    window.__eigenHelpers = {
+        computeSmallestEigenvalue,
+        applyEigenvalueGradients
+    };
+}

package/dist/Geometry.d.ts

@@ -0,0 +1,131 @@
+import { Vec3 } from './Vec3';
+import { Value } from './Value';
+/**
+ * Geometric utility functions for triangle mesh operations.
+ * All methods are differentiable and support automatic gradient computation.
+ * @public
+ */
+export declare class Geometry {
+    /**
+     * Compute the normal of a triangle defined by three vertices.
+     * Uses right-hand rule: normal points in direction of (b-a) × (c-a).
+     * Returns a UNIT normal vector.
+     *
+     * @param a - First vertex
+     * @param b - Second vertex
+     * @param c - Third vertex
+     * @returns Unit normal vector
+     */
+    static triangleNormal(a: Vec3, b: Vec3, c: Vec3): Vec3;
+    /**
+     * Compute the area of a triangle defined by three vertices.
+     * Uses the cross product formula: Area = 0.5 * ||(b-a) × (c-a)||
+     *
+     * @param a - First vertex
+     * @param b - Second vertex
+     * @param c - Third vertex
+     * @returns Triangle area
+     */
+    static triangleArea(a: Vec3, b: Vec3, c: Vec3): Value;
+    /**
+     * Compute the interior angle at vertex b in triangle abc.
+     * Returns angle in radians, range [0, π].
+     *
+     * Formula: angle = acos(dot(normalize(a-b), normalize(c-b)))
+     *
+     * @param a - First neighboring vertex
+     * @param b - Vertex where angle is measured
+     * @param c - Second neighboring vertex
+     * @returns Interior angle in radians
+     */
+    static interiorAngle(a: Vec3, b: Vec3, c: Vec3): Value;
+    /**
+     * Compute the angle defect at a vertex.
+     * Angle defect = 2π - sum of interior angles around the vertex.
+     * For flat regions, angle defect = 0.
+     * For positive Gaussian curvature (sphere-like), angle defect > 0.
+     * For negative Gaussian curvature (saddle-like), angle defect < 0.
+     *
+     * @param center - The vertex at which to compute angle defect
+     * @param neighbors - Ordered list of neighboring vertices (CCW or CW)
+     * @returns Angle defect in radians
+     */
+    static angleDefect(center: Vec3, neighbors: Vec3[]): Value;
+    /**
+     * Compute the centroid (center of mass) of a set of points.
+     *
+     * @param points - Array of points
+     * @returns Centroid
+     */
+    static centroid(points: Vec3[]): Vec3;
+    /**
+     * Compute area-weighted normal at a vertex.
+     * This is the sum of face normals weighted by face areas,
+     * then normalized. Provides a smooth approximation of the
+     * surface normal at a vertex.
+     *
+     * @param center - The vertex
+     * @param triangles - Array of triangles as [Vec3, Vec3, Vec3] where center is one of the vertices
+     * @returns Area-weighted unit normal
+     */
+    static vertexNormal(center: Vec3, triangles: [Vec3, Vec3, Vec3][]): Vec3;
+    /**
+     * Project point onto a plane defined by a point and normal.
+     *
+     * @param point - Point to project
+     * @param planePoint - A point on the plane
+     * @param planeNormal - Unit normal of the plane
+     * @returns Projected point
+     */
+    static projectToPlane(point: Vec3, planePoint: Vec3, planeNormal: Vec3): Vec3;
+    /**
+     * Compute signed distance from point to plane.
+     * Positive if point is on the side the normal points to.
+     *
+     * @param point - Point to measure
+     * @param planePoint - A point on the plane
+     * @param planeNormal - Unit normal of the plane
+     * @returns Signed distance
+     */
+    static distanceToPlane(point: Vec3, planePoint: Vec3, planeNormal: Vec3): Value;
+    /**
+     * Check if a set of normals are coplanar (lie in a common plane).
+     * Returns a measure of non-coplanarity (0 = perfectly coplanar).
+     * Uses the smallest eigenvalue of the normal covariance matrix.
+     *
+     * This is a simplified version - the full implementation would
+     * compute eigenvalues. For now, returns sum of cross products.
+     *
+     * @param normals - Array of unit normal vectors
+     * @returns Measure of non-coplanarity (0 = coplanar)
+     */
+    static normalCoplanarity(normals: Vec3[]): Value;
+    /**
+     * Compute the dihedral angle between two triangles sharing an edge.
+     * Returns angle in radians, range [0, π].
+     * Angle = 0 means triangles are coplanar.
+     * Angle = π means triangles fold completely back on themselves.
+     *
+     * @param n1 - Normal of first triangle
+     * @param n2 - Normal of second triangle
+     * @returns Dihedral angle in radians
+     */
+    static dihedralAngle(n1: Vec3, n2: Vec3): Value;
+    /**
+     * Compute the average of multiple vectors.
+     *
+     * @param vectors - Array of vectors
+     * @returns Average vector (not normalized)
+     */
+    static average(vectors: Vec3[]): Vec3;
+    /**
+     * Compute bounding box of a set of points.
+     *
+     * @param points - Array of points
+     * @returns Object with min and max corners
+     */
+    static boundingBox(points: Vec3[]): {
+        min: Vec3;
+        max: Vec3;
+    };
+}

package/dist/Geometry.js

@@ -0,0 +1,213 @@
+import { Vec3 } from './Vec3';
+import { V } from './V';
+/**
+ * Geometric utility functions for triangle mesh operations.
+ * All methods are differentiable and support automatic gradient computation.
+ * @public
+ */
+export class Geometry {
+    /**
+     * Compute the normal of a triangle defined by three vertices.
+     * Uses right-hand rule: normal points in direction of (b-a) × (c-a).
+     * Returns a UNIT normal vector.
+     *
+     * @param a - First vertex
+     * @param b - Second vertex
+     * @param c - Third vertex
+     * @returns Unit normal vector
+     */
+    static triangleNormal(a, b, c) {
+        const edge1 = b.sub(a);
+        const edge2 = c.sub(a);
+        const cross = Vec3.cross(edge1, edge2);
+        return cross.normalized;
+    }
+    /**
+     * Compute the area of a triangle defined by three vertices.
+     * Uses the cross product formula: Area = 0.5 * ||(b-a) × (c-a)||
+     *
+     * @param a - First vertex
+     * @param b - Second vertex
+     * @param c - Third vertex
+     * @returns Triangle area
+     */
+    static triangleArea(a, b, c) {
+        const edge1 = b.sub(a);
+        const edge2 = c.sub(a);
+        const cross = Vec3.cross(edge1, edge2);
+        return V.mul(0.5, cross.magnitude);
+    }
+    /**
+     * Compute the interior angle at vertex b in triangle abc.
+     * Returns angle in radians, range [0, π].
+     *
+     * Formula: angle = acos(dot(normalize(a-b), normalize(c-b)))
+     *
+     * @param a - First neighboring vertex
+     * @param b - Vertex where angle is measured
+     * @param c - Second neighboring vertex
+     * @returns Interior angle in radians
+     */
+    static interiorAngle(a, b, c) {
+        const ba = a.sub(b).normalized;
+        const bc = c.sub(b).normalized;
+        return Vec3.angleBetween(ba, bc);
+    }
+    /**
+     * Compute the angle defect at a vertex.
+     * Angle defect = 2π - sum of interior angles around the vertex.
+     * For flat regions, angle defect = 0.
+     * For positive Gaussian curvature (sphere-like), angle defect > 0.
+     * For negative Gaussian curvature (saddle-like), angle defect < 0.
+     *
+     * @param center - The vertex at which to compute angle defect
+     * @param neighbors - Ordered list of neighboring vertices (CCW or CW)
+     * @returns Angle defect in radians
+     */
+    static angleDefect(center, neighbors) {
+        let angleSum = V.C(0);
+        const n = neighbors.length;
+        for (let i = 0; i < n; i++) {
+            const prev = neighbors[i];
+            const next = neighbors[(i + 1) % n];
+            const angle = Geometry.interiorAngle(prev, center, next);
+            angleSum = V.add(angleSum, angle);
+        }
+        return V.sub(2 * Math.PI, angleSum);
+    }
+    /**
+     * Compute the centroid (center of mass) of a set of points.
+     *
+     * @param points - Array of points
+     * @returns Centroid
+     */
+    static centroid(points) {
+        if (points.length === 0) {
+            return Vec3.zero();
+        }
+        let sum = Vec3.zero();
+        for (const p of points) {
+            sum = sum.add(p);
+        }
+        return sum.div(points.length);
+    }
+    /**
+     * Compute area-weighted normal at a vertex.
+     * This is the sum of face normals weighted by face areas,
+     * then normalized. Provides a smooth approximation of the
+     * surface normal at a vertex.
+     *
+     * @param center - The vertex
+     * @param triangles - Array of triangles as [Vec3, Vec3, Vec3] where center is one of the vertices
+     * @returns Area-weighted unit normal
+     */
+    static vertexNormal(center, triangles) {
+        let weightedSum = Vec3.zero();
+        for (const [a, b, c] of triangles) {
+            const normal = Geometry.triangleNormal(a, b, c);
+            const area = Geometry.triangleArea(a, b, c);
+            weightedSum = weightedSum.add(normal.mul(area));
+        }
+        return weightedSum.normalized;
+    }
+    /**
+     * Project point onto a plane defined by a point and normal.
+     *
+     * @param point - Point to project
+     * @param planePoint - A point on the plane
+     * @param planeNormal - Unit normal of the plane
+     * @returns Projected point
+     */
+    static projectToPlane(point, planePoint, planeNormal) {
+        const toPoint = point.sub(planePoint);
+        const distance = Vec3.dot(toPoint, planeNormal);
+        const offset = planeNormal.mul(distance);
+        return point.sub(offset);
+    }
+    /**
+     * Compute signed distance from point to plane.
+     * Positive if point is on the side the normal points to.
+     *
+     * @param point - Point to measure
+     * @param planePoint - A point on the plane
+     * @param planeNormal - Unit normal of the plane
+     * @returns Signed distance
+     */
+    static distanceToPlane(point, planePoint, planeNormal) {
+        const toPoint = point.sub(planePoint);
+        return Vec3.dot(toPoint, planeNormal);
+    }
+    /**
+     * Check if a set of normals are coplanar (lie in a common plane).
+     * Returns a measure of non-coplanarity (0 = perfectly coplanar).
+     * Uses the smallest eigenvalue of the normal covariance matrix.
+     *
+     * This is a simplified version - the full implementation would
+     * compute eigenvalues. For now, returns sum of cross products.
+     *
+     * @param normals - Array of unit normal vectors
+     * @returns Measure of non-coplanarity (0 = coplanar)
+     */
+    static normalCoplanarity(normals) {
+        if (normals.length < 2)
+            return V.C(0);
+        // Simple measure: sum of squared cross products between all pairs
+        // If all normals are coplanar, all cross products lie along the same axis
+        let deviation = V.C(0);
+        for (let i = 0; i < normals.length; i++) {
+            for (let j = i + 1; j < normals.length; j++) {
+                const cross = Vec3.cross(normals[i], normals[j]);
+                deviation = V.add(deviation, cross.sqrMagnitude);
+            }
+        }
+        return deviation;
+    }
+    /**
+     * Compute the dihedral angle between two triangles sharing an edge.
+     * Returns angle in radians, range [0, π].
+     * Angle = 0 means triangles are coplanar.
+     * Angle = π means triangles fold completely back on themselves.
+     *
+     * @param n1 - Normal of first triangle
+     * @param n2 - Normal of second triangle
+     * @returns Dihedral angle in radians
+     */
+    static dihedralAngle(n1, n2) {
+        const dotProd = Vec3.dot(n1, n2);
+        const clampedDot = V.clamp(dotProd, -1, 1);
+        return V.acos(clampedDot);
+    }
+    /**
+     * Compute the average of multiple vectors.
+     *
+     * @param vectors - Array of vectors
+     * @returns Average vector (not normalized)
+     */
+    static average(vectors) {
+        if (vectors.length === 0)
+            return Vec3.zero();
+        let sum = Vec3.zero();
+        for (const v of vectors) {
+            sum = sum.add(v);
+        }
+        return sum.div(vectors.length);
+    }
+    /**
+     * Compute bounding box of a set of points.
+     *
+     * @param points - Array of points
+     * @returns Object with min and max corners
+     */
+    static boundingBox(points) {
+        if (points.length === 0) {
+            return { min: Vec3.zero(), max: Vec3.zero() };
+        }
+        let min = points[0].clone();
+        let max = points[0].clone();
+        for (let i = 1; i < points.length; i++) {
+            min = Vec3.min(min, points[i]);
+            max = Vec3.max(max, points[i]);
+        }
+        return { min, max };
+    }
+}

package/dist/GraphBuilder.d.ts

@@ -0,0 +1,64 @@
+import { Value } from './Value';
+/**
+ * Graph signature with hash and input mapping
+ */
+export interface GraphSignature {
+    /** Hash string for kernel matching */
+    hash: string;
+    /** Ordered list of leaf Value objects (params first, then constants) */
+    leaves: Value[];
+    /** Map from Value to index in leaves array */
+    leafIndexMap: Map<Value, number>;
+}
+/**
+ * Incremental graph builder that tracks structure during construction.
+ *
+ * Usage:
+ * ```typescript
+ * const builder = new GraphBuilder(knownParams);
+ * const result = builder.build(() => {
+ *   const a = V.add(params[0], params[1]);
+ *   const b = V.mul(a, V.C(2));
+ *   return b;
+ * });
+ * // result.signature.hash - for kernel lookup
+ * // result.signature.leaves - for index mapping at execution time
+ * ```
+ */
+export declare class GraphBuilder {
+    private leaves;
+    private leafIndexMap;
+    private knownParams;
+    private operations;
+    /**
+     * Create a new graph builder.
+     * @param knownParams - Parameters that are known upfront (will be indexed first)
+     */
+    constructor(knownParams?: Value[]);
+    /**
+     * Register a leaf Value and return its index.
+     * If already registered, returns existing index.
+     * New parameters are added dynamically.
+     */
+    private registerLeaf;
+    /**
+     * Record an operation during graph building.
+     * Called automatically by Value.make() when in tracked context.
+     * @internal
+     */
+    recordOp(value: Value): void;
+    /**
+     * Build a graph in tracked context and return output + signature.
+     *
+     * @param fn - Function that builds and returns the output Value
+     * @returns Output value and graph signature
+     */
+    build(fn: () => Value): {
+        output: Value;
+        signature: GraphSignature;
+    };
+    /**
+     * Get current signature without finalizing (for debugging)
+     */
+    getCurrentSignature(): Partial<GraphSignature>;
+}