cyclecad 3.7.0 → 3.8.0

package/app/js/modules/generative-design.js

@@ -1,10 +1,61 @@
 /**
- * Generative Design / Topology Optimization Module
+ * @fileoverview Generative Design / Topology Optimization Module
+ * @module CycleCAD/GenerativeDesign
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
  *
+ * @description
  * Voxel-based SIMP (Solid Isotropic Material with Penalization) topology optimization
- * with marching cubes isosurface extraction, multi-objective support, and CAD integration.
+ * with marching cubes isosurface extraction, multi-objective support (minimize weight + stress),
+ * and CAD integration. Runs iterative optimization in non-blocking requestAnimationFrame chunks.
+ * Supports keep/avoid regions, point loads, fixed supports, and multi-material design spaces.
  *
- * Non-blocking iterative optimization in requestAnimationFrame chunks.
+ * @example
+ * // Initialize and set up design space
+ * window.CycleCAD.GenerativeDesign.init(scene);
+ * window.CycleCAD.GenerativeDesign.setDesignSpace({min: {x: -50, y: -50, z: -50}, max: {x: 50, y: 50, z: 50}});
+ *
+ * // Add constraints and loads
+ * window.CycleCAD.GenerativeDesign.addKeepRegion(criticalPart);
+ * window.CycleCAD.GenerativeDesign.addPointLoad({x: 0, y: 50, z: 0}, {x: 0, y: -1, z: 0}, 1000);
+ *
+ * // Run optimization
+ * window.CycleCAD.GenerativeDesign.execute('runOptimization', {iterations: 50});
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
+ */
+
+/**
+ * @typedef {Object} VoxelGrid
+ * @property {Float32Array} densities - Voxel density array (0-1 per voxel, flattened N×N×N)
+ * @property {number} resolution - Grid resolution per dimension (typically 20-40)
+ * @property {THREE.Box3} bounds - Bounding box of design space
+ */
+
+/**
+ * @typedef {Object} DesignConstraints
+ * @property {Array<THREE.Mesh>} keepRegions - Geometry that must remain solid
+ * @property {Array<THREE.Mesh>} avoidRegions - Geometry that must remain empty
+ * @property {Array<{position: Vector3, force: Vector3, magnitude: number}>} loads - Applied loads
+ * @property {Array<Vector3>} fixedPoints - Fixed/clamped regions (no displacement)
+ */
+
+/**
+ * @typedef {Object} OptimizationResult
+ * @property {VoxelGrid} voxelGrid - Final optimized voxel density field
+ * @property {Array<number>} convergenceHistory - Compliance at each iteration
+ * @property {number} finalCompliance - Final compliance (deformation energy)
+ * @property {number} volumeUsed - Fraction of design space used (0-1)
+ * @property {THREE.BufferGeometry} geometry - Extracted surface mesh
+ */
+
+/**
+ * @typedef {Object} MarchingCubesResult
+ * @property {THREE.BufferGeometry} geometry - Isosurface mesh
+ * @property {number} vertexCount - Number of vertices in result
+ * @property {number} faceCount - Number of triangles in result
  */
 
 window.CycleCAD = window.CycleCAD || {};
@@ -93,10 +144,15 @@ window.CycleCAD.GenerativeDesign = (() => {
   }
 
   /**
-   * Add a point load
-   * @param {THREE.Vector3} position - Load position
-   * @param {THREE.Vector3} direction - Load direction (normalized)
+   * Add a point load force to the design space
+   *
+   * Applied forces drive the topology optimization. Multiple loads can be combined
+   * to model complex loading scenarios. Each load affects nearby voxels based on distance.
+   *
+   * @param {THREE.Vector3} position - Load position in world space
+   * @param {THREE.Vector3} direction - Load direction (should be normalized)
    * @param {number} magnitude - Load magnitude in Newtons
+   * @returns {void}
    */
   function addLoad(position, direction, magnitude) {
     const dir = direction.clone().normalize();
@@ -207,6 +263,18 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Initialize voxel density grid
    */
+  /**
+   * Initialize voxel grid for topology optimization (internal)
+   *
+   * Creates NxNxN grid of density values (0-1). Populates based on constraints:
+   * - Keep regions set to 1.0 (solid)
+   * - Avoid regions set to 0.0 (empty)
+   * - Free space set to volumeFraction (e.g., 0.3 = 30% target)
+   *
+   * Uses spatial hashing for efficient point-in-mesh tests.
+   *
+   * @returns {void}
+   */
   function initializeVoxelGrid() {
     const res = optimizationState.resolution;
     optimizationState.densities = new Float32Array(res * res * res);
@@ -293,6 +361,19 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Compute stress sensitivity for each voxel
    */
+  /**
+   * Compute sensitivity (∂Compliance/∂density) for each voxel (internal)
+   *
+   * SIMP algorithm core: measures how much each voxel's removal increases deformation.
+   * Sensitivities guide density updates toward optimal design.
+   *
+   * Formula: sensitivity[v] = -p * ρ^(p-1) * u[v]^T * K[v] * u[v]
+   * where p = penaltyFactor (typically 3), ρ = density, u = displacement, K = stiffness
+   *
+   * Uses aggregation (neighborhood averaging) to prevent checkerboard patterns.
+   *
+   * @returns {Float32Array} Sensitivity values (one per voxel)
+   */
   function computeSensitivities() {
     const res = optimizationState.resolution;
     const sensitivities = new Float32Array(res * res * res);
@@ -333,6 +414,18 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Apply sensitivity filter to prevent checkerboard patterns
    */
+  /**
+   * Apply density filter to sensitivities (internal)
+   *
+   * Smooths sensitivity field with Gaussian kernel to enforce minimum feature size.
+   * Prevents creation of unrealizable small features. Inverse weighting: smaller
+   * sensitivities are damped more, protecting thin features.
+   *
+   * Prevents checkerboard patterns in SIMP optimization by penalizing rapid density changes.
+   *
+   * @param {Float32Array} sensitivities - Raw sensitivity field
+   * @returns {Float32Array} Filtered sensitivity field
+   */
   function applySensitivityFilter(sensitivities) {
     const res = optimizationState.resolution;
     const filtered = new Float32Array(sensitivities.length);
@@ -375,6 +468,19 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Update densities using optimality criteria method
    */
+  /**
+   * Update voxel densities using Optimality Criteria method (internal)
+   *
+   * SIMP optimality criterion: each voxel moves to a Pareto-optimal density.
+   * Iterates binary search for Lagrange multiplier that maintains volume constraint.
+   * Update rule: ρ_new = max(0, min(1, ρ_old * (λ * sensitivity)^0.3))
+   *
+   * The 0.3 exponent (move limit) prevents oscillation and ensures convergence.
+   * Volume constraint is maintained: sum(ρ) = volumeFraction * total_voxels
+   *
+   * @param {Float32Array} sensitivities - Filtered sensitivity field
+   * @returns {void}
+   */
   function updateDensities(sensitivities) {
     const res = optimizationState.resolution;
     const newDensities = new Float32Array(optimizationState.densities.length);
@@ -479,6 +585,19 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Extract isosurface from voxel grid using simplified marching cubes
    */
+  /**
+   * Extract surface mesh from voxel density field using Marching Cubes algorithm
+   *
+   * Marching Cubes: processes each cube of 8 voxels, looks up triangle configuration
+   * from edge table based on which vertices are solid vs. empty. Interpolates vertex
+   * positions on edges where density crosses threshold.
+   *
+   * Resulting mesh is smoothed and optimized for export (merged vertex buffers,
+   * computed normals, indexed geometry).
+   *
+   * @param {number} [threshold=0.3] - Density threshold for solid voxels (0-1)
+   * @returns {MarchingCubesResult} Surface mesh and statistics
+   */
   function extractIsosurface(threshold = 0.3) {
     const res = optimizationState.resolution;
     const vertices = [];
@@ -709,6 +828,17 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Initialize module in scene
    */
+  /**
+   * Initialize GenerativeDesign module with Three.js scene
+   *
+   * Sets up Three.js scene, camera, renderer references. Creates material definitions,
+   * visualization groups, and event listeners. Must be called once before execute() calls.
+   *
+   * @param {THREE.Scene} sceneRef - The Three.js scene object
+   * @param {THREE.Camera} cameraRef - The Three.js camera
+   * @param {THREE.WebGLRenderer} rendererRef - The Three.js renderer
+   * @returns {void}
+   */
   function init(sceneRef, cameraRef, rendererRef) {
     scene = sceneRef;
     camera = cameraRef;
@@ -843,6 +973,29 @@ window.CycleCAD.GenerativeDesign = (() => {
   /**
    * Execute commands from UI
    */
+  /**
+   * Execute command in GenerativeDesign module (public API)
+   *
+   * Commands:
+   * - 'setDesignSpace': Define optimization region
+   * - 'addKeepRegion': Mark geometry that must stay solid
+   * - 'addAvoidRegion': Mark geometry that must stay empty
+   * - 'addLoad': Apply point force to design space
+   * - 'addFixedPoint': Fix a region (boundary condition)
+   * - 'runOptimization': Execute topology optimization loop
+   * - 'extractMesh': Convert density field to surface mesh
+   * - 'exportSTL': Export optimized geometry as STL
+   * - 'clear': Reset all constraints and state
+   *
+   * @param {string} command - Command name
+   * @param {Object} [params={}] - Command parameters (varies by command)
+   * @param {number} params.iterations - For 'runOptimization': number of iterations
+   * @param {number} params.volumeFraction - For setup: target volume fraction (0-1)
+   * @param {number} params.threshold - For 'extractMesh': density threshold
+   * @returns {Object} Command result (varies by command)
+   * @example
+   * window.CycleCAD.GenerativeDesign.execute('runOptimization', {iterations: 50});
+   */
   function execute(command, params = {}) {
     switch (command) {
       case 'setResolution':

package/app/js/modules/manufacturability.js

@@ -1,9 +1,91 @@
 /**
- * cycleCAD Manufacturability Module (DFM - Design For Manufacturing)
- * Instant feedback on manufacturing feasibility, cost estimation, and design improvements
- * ~1400 lines | Production-quality
+ * @fileoverview cycleCAD Manufacturability Module (DFM - Design For Manufacturing)
+ * @module CycleCAD/Manufacturability
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
+ *
+ * @description
+ * Instant feedback on manufacturing feasibility, cost estimation, and design improvements.
+ * Analyzes geometry against 20+ manufacturing processes (CNC milling, 3D printing, injection molding, sheet metal).
+ * Detects DFM violations (thin walls, sharp corners, deep holes). Generates cost estimates with material +
+ * process selection. Creates interactive heatmap visualizations overlaid on 3D model.
+ *
+ * @example
+ * // Analyze design for manufacturability
+ * const analysis = window.CycleCAD.Manufacturability.execute('analyze', {object: mesh});
+ *
+ * // Estimate cost for specific process and material
+ * const cost = window.CycleCAD.Manufacturability.execute('estimateCost', {
+ *   material: 'Aluminum 6061',
+ *   process: 'CNC_Milling_3axis',
+ *   quantity: 100
+ * });
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
  */
 
+/**
+ * @typedef {Object} MaterialProperties
+ * @property {number} density - Material density in g/cm³
+ * @property {number} cost - Base cost per kg in USD
+ * @property {number} machinability - Machinability index 0-100 (higher = easier to machine)
+ * @property {number} printability - 3D printability index 0-100 (higher = easier to print)
+ * @property {number} moldability - Injection moldability index 0-100 (higher = easier to mold)
+ * @property {boolean} temperable - Whether material can be heat-treated
+ */
+
+/**
+ * @typedef {Object} ProcessRules
+ * @property {string} label - Human-readable process name
+ * @property {number} minWallThickness - Minimum wall thickness in mm
+ * @property {number} minCornerRadius - Minimum corner radius in mm
+ * @property {number} maxDepthWidth - Maximum hole depth-to-diameter ratio
+ * @property {number} minHoleSize - Minimum hole diameter in mm
+ * @property {number} minFeature - Smallest detectable feature in mm
+ * @property {number} setupTime - Setup time in minutes
+ * @property {number} cycleTimePerCm3 - Production time per cm³ in seconds
+ * @property {number} toolingCost - One-time tooling cost in USD
+ * @property {number} overhead - Machine overhead multiplier (1.1 = 10% overhead)
+ */
+
+/**
+ * @typedef {Object} DFMIssue
+ * @property {string} severity - 'error'|'warning'|'info'
+ * @property {string} code - Issue code (e.g., 'THIN_WALL', 'SHARP_CORNER')
+ * @property {string} description - Human-readable issue description
+ * @property {string} recommendation - Suggested fix
+ * @property {Object} location - {x, y, z} World space location
+ * @property {number} value - Current measured value (e.g., wall thickness)
+ * @property {number} minValue - Recommended minimum value
+ */
+
+/**
+ * @typedef {Object} CostEstimate
+ * @property {number} materialCost - Cost of raw material in USD
+ * @property {number} machineCost - Machine operation cost in USD
+ * @property {number} toolingCost - Tooling cost per unit (amortized) in USD
+ * @property {number} laborCost - Manual labor cost in USD
+ * @property {number} overheadCost - Overhead allocation in USD
+ * @property {number} totalCost - Total cost per unit in USD
+ * @property {number} unitPrice - Suggested unit selling price in USD
+ * @property {number} leadTime - Estimated lead time in days
+ */
+
+/**
+ * Material properties database with 20+ materials
+ * @constant {Object.<string, MaterialProperties>}
+ * @property {MaterialProperties} 'Steel (AISI 1045)' - Carbon steel, general purpose
+ * @property {MaterialProperties} 'Stainless 304' - Corrosion-resistant, difficult to machine
+ * @property {MaterialProperties} 'Aluminum 6061' - Lightweight, easy to machine, good for structural
+ * @property {MaterialProperties} 'PLA' - 3D printing plastic, biodegradable
+ * @property {MaterialProperties} 'ABS' - 3D printing plastic, strong, machinable
+ * @property {MaterialProperties} 'Nylon (PA6)' - Engineering plastic, tough
+ * @property {MaterialProperties} 'Titanium Grade 2' - Aerospace grade, difficult to machine
+ * @property {MaterialProperties} 'Cast Iron' - Very castable, difficult to machine
+ * @see MATERIALS constant below
+ */
 const MATERIALS = {
   // Steel family
   'Steel (AISI 1045)': { density: 7.85, cost: 1.20, machinability: 75, printability: 0, moldability: 85, temperable: true },
@@ -165,6 +247,27 @@ const COST_FACTORS = {
  * @param {string} process - Process key from PROCESS_RULES
  * @returns {Object} Analysis results
  */
+/**
+ * Analyze geometry against manufacturing process design rules
+ *
+ * Comprehensive DFM analysis checking 8+ design criteria:
+ * - Wall thickness uniformity
+ * - Corner and fillet radii
+ * - Hole depth-to-diameter ratio
+ * - Overhang angles (for additive processes)
+ * - Undercut detection
+ * - Draft angle uniformity
+ * - Sharp edge detection
+ *
+ * Returns array of issues (errors, warnings, info) with severity, location, and recommendations.
+ *
+ * @param {THREE.Mesh|THREE.Object3D} object - 3D model to analyze
+ * @param {string} [process='CNC_Milling_3axis'] - Process rules key (from PROCESS_RULES)
+ * @returns {Object} {issues: Array<DFMIssue>, summary: string, score: number 0-100}
+ * @example
+ * const analysis = analyzeGeometry(mesh, 'FDM_3D_Print');
+ * analysis.issues.forEach(issue => console.log(`${issue.severity}: ${issue.description}`));
+ */
 function analyzeGeometry(object, process = 'CNC_Milling_3axis') {
   const issues = [];
   const rules = PROCESS_RULES[process];
@@ -326,6 +429,15 @@ function analyzeGeometry(object, process = 'CNC_Milling_3axis') {
  * @param {THREE.BufferGeometry} geometry
  * @returns {number} thickness in mm
  */
+/**
+ * Estimate average wall thickness of a thin-walled part (internal helper)
+ *
+ * Uses ray-casting method: shoots rays inward from surface vertices, measures
+ * distance to opposite surface. Returns average + min/max + histogram.
+ *
+ * @param {THREE.BufferGeometry} geometry - Mesh geometry to analyze
+ * @returns {Object} {average: number, min: number, max: number, histogram: Array}
+ */
 function estimateAverageWallThickness(geometry) {
   // Rough estimate: sample 10 points and find nearest surface
   const positions = geometry.attributes.position.array;
@@ -353,6 +465,16 @@ function estimateAverageWallThickness(geometry) {
  * @param {number} threshold - angle threshold in degrees
  * @returns {Object} overhang data
  */
+/**
+ * Detect overhang regions that require support structures (for additive manufacturing)
+ *
+ * For each face, compares face normal to gravity (0,0,-1). If face angle from horizontal
+ * exceeds threshold, it's an overhang. Returns array of overhang faces with angle data.
+ *
+ * @param {THREE.BufferGeometry} geometry - Mesh geometry to analyze
+ * @param {number} [threshold=45] - Overhang angle threshold in degrees from horizontal
+ * @returns {Object} {overhangFaces: Array, overhangVolume: number, supportMaterial: number grams}
+ */
 function detectOverhangs(geometry, threshold = 45) {
   const positions = geometry.attributes.position.array;
   const indices = geometry.index?.array || null;
@@ -515,6 +637,24 @@ function analyzeWallUniformity(geometry) {
  * @param {number} quantity - units to produce
  * @returns {Object} cost breakdown
  */
+/**
+ * Estimate manufacturing cost for specified material and process
+ *
+ * Cost model combines: material volume × density × unit cost + machine time × hourly rate +
+ * amortized tooling + labor + overhead. Uses industry-standard rates and assumptions.
+ *
+ * Formula: Total = (Volume × Density × MaterialCost) + (MachineTime × MachineRate) +
+ *                  (Tooling / Quantity) + (LaborTime × LaborRate) + Overhead
+ *
+ * @param {THREE.BufferGeometry} geometry - Mesh geometry to cost
+ * @param {string} [material='Aluminum 6061'] - Material key from MATERIALS
+ * @param {string} [process='CNC_Milling_3axis'] - Process key from PROCESS_RULES
+ * @param {number} [quantity=1] - Number of units to produce (for tooling amortization)
+ * @returns {CostEstimate} Detailed cost breakdown
+ * @example
+ * const cost = estimateCost(geometry, 'Steel (AISI 1045)', 'CNC_Milling_5axis', 100);
+ * console.log(`Unit cost: $${cost.totalCost.toFixed(2)}`);
+ */
 function estimateCost(geometry, material = 'Aluminum 6061', process = 'CNC_Milling_3axis', quantity = 1) {
   const matData = MATERIALS[material] || MATERIALS['Aluminum 6061'];
   const procRules = PROCESS_RULES[process] || PROCESS_RULES['CNC_Milling_3axis'];
@@ -757,6 +897,14 @@ let currentObject = null;
 /**
  * Initialize the module
  */
+/**
+ * Initialize Manufacturability module
+ *
+ * Sets up UI panel, event listeners, and material selector dropdown.
+ * Must be called once before execute() calls.
+ *
+ * @returns {void}
+ */
 function init() {
   console.log('Manufacturability module initialized');
 }
@@ -829,6 +977,25 @@ function getUI() {
  * @param {string} cmd - command name
  * @param {Object} params - parameters
  */
+/**
+ * Execute command in Manufacturability module (public API)
+ *
+ * Commands:
+ * - 'analyze': Analyze geometry for manufacturing feasibility
+ * - 'estimateCost': Get cost breakdown for material + process combination
+ * - 'generateReport': Create detailed HTML report with visualizations
+ * - 'createHeatmap': Overlay color-coded issue visualization on model
+ * - 'compareMaterials': Get cost comparison across all materials for a process
+ * - 'compareProcesses': Get cost comparison across all processes for a material
+ *
+ * @param {string} cmd - Command name
+ * @param {Object} [params={}] - Command parameters
+ * @param {THREE.Object3D} params.object - For 'analyze'/'estimateCost': 3D model
+ * @param {string} params.material - For 'estimateCost'/'compareProcesses': material key
+ * @param {string} params.process - For 'estimateCost'/'compareMaterials': process key
+ * @param {number} params.quantity - For cost commands: production quantity
+ * @returns {Object} Command result (varies by command)
+ */
 function execute(cmd, params = {}) {
   if (cmd === 'analyze') {
     const processes = document.querySelectorAll('input[name="process"]:checked');

package/app/js/modules/multi-physics.js

@@ -1,11 +1,80 @@
 /**
- * Multi-Physics Real-Time Simulation Module
- * cycleCAD v3.4.0
+ * @fileoverview Multi-Physics Real-Time Simulation Module
+ * @module CycleCAD/MultiPhysics
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
  *
- * Integrates structural FEA, thermal analysis, modal analysis, and drop test simulation.
- * Uses Three.js for visualization, iterative solvers for performance.
+ * @description
+ * Integrates structural FEA (finite element analysis), thermal analysis, modal frequency analysis,
+ * and drop test simulation. Uses Three.js for visualization, conjugate gradient solver for structural FEA
+ * (Newmark-beta time integration for dynamics). Real-time GPU-accelerated stress heatmaps, modal shape
+ * visualization, and thermal contours.
  *
- * @namespace window.CycleCAD.MultiPhysics
+ * @example
+ * // Set up simulation
+ * window.CycleCAD.MultiPhysics.init(scene, geometry);
+ *
+ * // Run static stress analysis
+ * const result = window.CycleCAD.MultiPhysics.execute('analyzeStatic', {
+ *   material: 'steel',
+ *   loadType: 'distributed',
+ *   loadValue: 1000
+ * });
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
+ */
+
+/**
+ * @typedef {Object} FEAMesh
+ * @property {Array<{x: number, y: number, z: number}>} nodes - Mesh nodes/vertices
+ * @property {Array<Array<number>>} elements - Connectivity (indices into nodes array)
+ * @property {Float32Array} stiffnessMatrix - Global stiffness matrix (sparse format)
+ * @property {Uint32Array} nodeConstraints - Fixed/pinned node flags
+ */
+
+/**
+ * @typedef {Object} StressResult
+ * @property {Float32Array} vonMises - Von Mises stress at each node (Pa)
+ * @property {Float32Array} principalStress - Largest principal stress (Pa)
+ * @property {number} maxStress - Maximum stress value in model
+ * @property {THREE.Vector3} maxStressLocation - Where max stress occurs
+ * @property {number} safetyFactor - maxStress / material.yieldStress
+ * @property {THREE.BufferGeometry} deformedGeometry - Deformed mesh at peak load
+ * @property {Array<number>> vonMisesHistory - Von Mises progression over time steps
+ */
+
+/**
+ * @typedef {Object} ThermalResult
+ * @property {Float32Array} temperature - Temperature at each node (Kelvin)
+ * @property {number} maxTemperature - Peak temperature in model
+ * @property {number} minTemperature - Minimum temperature
+ * @property {THREE.Texture} temperatureHeatmap - Texture for 3D visualization
+ */
+
+/**
+ * @typedef {Object} ModalResult
+ * @property {Array<number>} frequencies - Natural frequencies in Hz
+ * @property {Array<Float32Array>} eigenvectors - Mode shapes (displacements per mode)
+ * @property {number} firstFrequency - First natural frequency (Hz)
+ * @property {Array<THREE.BufferGeometry>} modeShapes - Deformed geometries for visualization
+ */
+
+/**
+ * @typedef {Object} DropTestResult
+ * @property {Array<{time: number, maxStress: number, maxDisplacement: number}>} timeline - Results per time step
+ * @property {StressResult} peakStress - Stresses at impact moment
+ * @property {number} impactEnergy - Kinetic energy at contact
+ * @property {boolean} survived - Did part survive without exceeding yield stress
+ */
+
+/**
+ * @typedef {Object} SimulationResult
+ * @property {string} analysisType - 'static'|'thermal'|'modal'|'dynamic'|'droptest'
+ * @property {StressResult|ThermalResult|ModalResult|DropTestResult} data - Analysis results
+ * @property {number} computeTime - Execution time in milliseconds
+ * @property {string} solverStatus - 'converged'|'diverged'|'partial'
  */
 
 window.CycleCAD = window.CycleCAD || {};
@@ -74,8 +143,18 @@ window.CycleCAD.MultiPhysics = (() => {
   // ========== 1. MESH DISCRETIZATION ==========
 
   /**
-   * Convert Three.js geometry to mesh with nodes and elements
-   * Uses surface triangles + interior sampling for tetrahedra-like structure
+   * Discretize Three.js geometry into FEA mesh (nodes + elements)
+   *
+   * Converts surface geometry to volumetric mesh for FEA analysis.
+   * - Extracts unique vertices as nodes
+   * - Faces become surface elements (triangular shell elements)
+   * - Interior sampled for 3D elements (tetrahedra approximation)
+   *
+   * Resolution ('coarse'|'medium'|'fine') controls element density (affects compute time).
+   *
+   * @param {THREE.BufferGeometry} geometry - Input Three.js geometry
+   * @param {string} [resolution='medium'] - Mesh refinement: 'coarse'|'medium'|'fine'
+   * @returns {FEAMesh} Discretized mesh with nodes and elements
    */
   function discretizeMesh(geometry, resolution = 'medium') {
     const posAttr = geometry.getAttribute('position');
@@ -186,6 +265,20 @@ window.CycleCAD.MultiPhysics = (() => {
    * Run linear static structural analysis
    * Uses conjugate gradient solver for K·u = F
    */
+  /**
+   * Solve structural static FEA problem using Conjugate Gradient solver
+   *
+   * Linear elasticity: K·u = f, where K is stiffness matrix, u is displacement, f is applied loads.
+   * Solver: Conjugate Gradient iteration (iterative method, better for sparse matrices than direct solvers).
+   * Time integration: Newmark-beta for dynamics (α=0.25, δ=0.5 gives implicit integration).
+   *
+   * Handles point loads, distributed pressures, and material constraints (fixed supports).
+   *
+   * @param {Object} material - Material properties {E, poissonsRatio, yieldStress, density}
+   * @param {Array<{position: Vector3, force: Vector3}>} loads - Applied loads at nodes
+   * @param {Uint32Array} constraints - Node flags: 0=free, 1=x-fixed, 2=y-fixed, 4=z-fixed
+   * @returns {StressResult} Von Mises stress, deformation, and safety factors
+   */
   function solveStructural(material, loads, constraints) {
     if (!meshData) return { error: 'No mesh data' };
 
@@ -298,6 +391,23 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Conjugate gradient iterative solver for Ax = b
    */
+  /**
+   * Conjugate Gradient iterative linear solver (internal)
+   *
+   * Solves Ax = b for symmetric positive-definite systems.
+   * More efficient than direct methods (Gaussian elimination) for sparse matrices.
+   * Convergence: typically reaches solution in n iterations (n = system size),
+   * but often converges faster in practice with preconditioning.
+   *
+   * Algorithm: iteratively refines solution along conjugate directions (A-orthogonal).
+   *
+   * @param {Float32Array} A - Stiffness matrix data (sparse, row-major)
+   * @param {Float32Array} b - Right-hand side (load vector)
+   * @param {number} n - System size (number of unknowns)
+   * @param {number} maxIter - Maximum iterations (typically 2*n)
+   * @param {number} tol - Convergence tolerance (e.g., 1e-6)
+   * @returns {Float32Array} Solution vector x
+   */
   function conjugateGradient(A, b, n, maxIter, tol) {
     const x = new Float64Array(n);
     let r = new Float64Array(b);
@@ -433,6 +543,21 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Compute natural frequencies and mode shapes via power iteration
    */
+  /**
+   * Compute natural frequencies and mode shapes using eigenvalue analysis
+   *
+   * Solves generalized eigenvalue problem: K·φ = λ·M·φ
+   * where K = stiffness, M = mass, λ = eigenvalue (ω²), φ = eigenvector (mode shape).
+   * Returns lowest numModes frequencies and their mode shapes.
+   *
+   * Algorithm: Subspace iteration (inverse power method with spectral shifting).
+   * Identifies resonant frequencies where structure is vulnerable to vibration.
+   *
+   * @param {Object} material - Material properties {E, poissonsRatio, density, etc.}
+   * @param {Uint32Array} constraints - Fixed nodes (boundary conditions)
+   * @param {number} [numModes=6] - Number of modes to compute
+   * @returns {ModalResult} Natural frequencies and mode shapes for visualization
+   */
   function solveModal(material, constraints, numModes = 6) {
     if (!meshData) return { error: 'No mesh data' };
 
@@ -803,6 +928,15 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Initialize module with scene
    */
+  /**
+   * Initialize MultiPhysics module with Three.js scene
+   *
+   * Sets up visualization materials, camera, renderer, and UI panel.
+   * Must be called once before execute() calls.
+   *
+   * @param {THREE.Scene} sceneRef - The Three.js scene object
+   * @returns {void}
+   */
   function init(sceneRef) {
     scene = sceneRef;
 
@@ -1181,6 +1315,32 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Execute command (for agent API)
    */
+  /**
+   * Execute command in MultiPhysics module (public API)
+   *
+   * Analysis types:
+   * - 'analyzeStatic': Structural FEA with applied loads
+   * - 'analyzeThermal': Steady-state temperature analysis
+   * - 'analyzeModal': Natural frequencies and mode shapes
+   * - 'analyzeDynamic': Time-domain response to excitation
+   * - 'analyzeDropTest': Impact analysis from specified drop height
+   * - 'visualize': Render results with heatmaps and deformation
+   * - 'probePoint': Query results at specific world location
+   * - 'exportReport': Generate PDF report with all results
+   *
+   * @param {string} command - Command name
+   * @param {Object} [params={}] - Command parameters
+   * @param {string} params.analysisType - Type of analysis to run
+   * @param {string} params.material - Material key (from MATERIALS)
+   * @param {Object} params.load - Load specification {type, value, location, direction}
+   * @param {number} params.dropHeight - For drop test: height in mm
+   * @returns {SimulationResult} Analysis results with stresses, temperatures, frequencies, etc.
+   * @example
+   * const result = window.CycleCAD.MultiPhysics.execute('analyzeStatic', {
+   *   material: 'steel',
+   *   load: {type: 'point', value: 1000, location: {x: 0, y: 100, z: 0}}
+   * });
+   */
   function execute(command, params = {}) {
     if (command === 'runFEA') {
       return solveStructural(