slangmath 1.0.0 → 1.0.2

package/README.md

@@ -1,12 +1,13 @@
 # 📚 SLaNg Math Library
-### Saad's Language for Analytical Numerics and Geometry - Enhanced Edition
+
+### Saad's Language for Analytical Numerics and Geometry
 
 🎯 **Advanced Symbolic Mathematics with Comprehensive LaTeX Conversion & Extended Function Support**
 
-A powerful, dependency-free JavaScript library for symbolic and numerical calculus with **complete polynomial denominator support**, **bidirectional LaTeX conversion**, and **extended mathematical functions**. Compute derivatives, integrals, rational functions, Taylor series, optimize functions, and solve complex multivariable problems—all with clean, readable code and professional-grade error handling.
+A powerful, dependency-free JavaScript library for symbolic and numerical calculus with **complete polynomial denominator support**, **bidirectional LaTeX conversion**, **extended mathematical functions**, and **advanced multivariable calculus**. Compute derivatives, integrals, rational functions, Taylor series, optimize functions, analyze surfaces, and solve complex multivariable problems—all with clean, readable code and professional-grade error handling.
 
 ```javascript
-import { createFraction, createTerm, differentiateFraction } from './slang-math.js';
+import { createFraction, createTerm, gradient, tangentPlane } from './slang-math.js';
 import { slangToLatex, latexToSlang } from './slang-convertor.js';
 
 //: Full polynomial denominator support with LaTeX conversion!
@@ -19,10 +20,10 @@ const f = createFraction(
 const latex = slangToLatex(f);
 console.log(latex); // "\\frac{2x}{x^{2} + 1}"
 
-// Differentiate using quotient rule automatically
-const fPrime = differentiateFraction(f, 'x');  
-const latexPrime = slangToLatex(fPrime);
-// f'(x) = (2 - 2x²)/(x² + 1)² -> "\\frac{2 - 2x^{2}}{(x^{2} + 1)^{2}}"
+// Advanced multivariable calculus
+const surface = { terms: [createTerm(1, {x: 2}), createTerm(1, {y: 2})] }; // z = x² + y²
+const tangent = tangentPlane(surface, 1, 2);
+console.log(tangentToLatex(tangent)); // "z = 5 + 2x + 4y + -5"
 
 // Parse LaTeX back to SLaNg
 const parsed = latexToSlang('\\frac{x^{2} + 1}{x - 1}');
@@ -32,46 +33,44 @@ const parsed = latexToSlang('\\frac{x^{2} + 1}{x - 1}');
 
 ---
 
-## 🚀 What's New in v2.0
+## 🚀 What This Package Does
+
+### ✨ Core Capabilities
 
-### ✨ Major Enhancements
+1. **🧮 Advanced Mathematical Functions**
+   - Tangent plane and line analysis
+   - Gradient and Hessian matrix computation
+   - Critical point detection and classification
+   - Directional derivatives and steepest directions
+   - Surface normal vectors
+   - Lagrange multipliers for constrained optimization
+   - Local and global extrema finding
 
-1. **� Bidirectional LaTeX Conversion**
-   - Convert SLaNg ↔ LaTeX seamlessly
+2. **📐 Multivariable Calculus**
+   - Complete surface analysis capabilities
+   - Vector calculus operations
+   - Optimization algorithms
+   - Constrained optimization with Lagrange multipliers
+
+3. **🔄 LaTeX Integration**
+   - Bidirectional LaTeX conversion
    - Support for complex mathematical expressions
    - Advanced parsing with error recovery
-   - Batch processing capabilities
+   - Validation system
 
-2. **🧮 Extended Mathematical Functions**
+4. **🧮 Extended Mathematical Functions**
    - Trigonometric functions (sin, cos, tan, etc.)
    - Inverse trigonometric functions
    - Hyperbolic functions
    - Logarithmic and exponential functions
    - Function evaluation and differentiation
 
-3. **⚡ Performance & Caching System**
-   - LRU cache for expression conversion
-   - Performance monitoring and optimization
-   - Memoization for expensive operations
-   - Batch processing with parallel execution
-
-4. **🛡️ Advanced Error Handling**
-   - Comprehensive error classification
-   - Error recovery suggestions
-   - Detailed validation system
-   - Graceful fallback strategies
-
-5. **🧪 Comprehensive Testing Suite**
-   - Unit tests with 95%+ coverage
-   - Performance benchmarks
-   - Integration tests
-   - Automated CI/CD ready
-
-6. **📚 Enhanced Documentation**
-   - Function-by-function explanations
-   - Usage examples and best practices
-   - API reference with TypeScript support
-   - Interactive examples
+5. **📊 Core Calculus Operations**
+   - Symbolic differentiation and integration
+   - Numerical integration with Simpson's rule
+   - Polynomial arithmetic
+   - Rational function operations
+   - Taylor series expansion
 
 ---
 
@@ -104,64 +103,115 @@ const expr = createFraction(
 const latex = slangToLatex(expr);
 console.log(latex); // "\\frac{x^{2} - 1}{x^{2} + 1}"
 
-// Validate LaTeX
-const validation = validateLatex(latex);
-console.log(validation.valid); // true
-
 // Parse back from LaTeX
 const parsed = latexToSlang(latex);
 ```
 
-#### Example 2: Extended Functions
+#### Example 2: Advanced Multivariable Calculus
 ```javascript
-import { createFunction, evaluateFunction, extendedSlangToLatex } from './slang-extended.js';
+import { gradient, hessian, tangentPlane, findCriticalPoints } from './slang-extended.js';
 
-// Create trigonometric function
-const sinExpr = createFunction('sin', [createTerm(1, {x: 1})]);
+// Surface: z = x² + y²
+const surface = { terms: [createTerm(1, {x: 2}), createTerm(1, {y: 2})] };
 
-// Convert to LaTeX
-const sinLatex = extendedSlangToLatex(sinExpr);
-console.log(sinLatex); // "\\sin{x}"
+// Calculate gradient
+const grad = gradient(surface, ['x', 'y']);
+console.log('∇f =', grad); // {x: 2x, y: 2y}
+
+// Find tangent plane at (1, 2)
+const tangent = tangentPlane(surface, 1, 2);
+console.log('Tangent plane:', tangentToLatex(tangent));
 
-// Evaluate at specific point
-const result = evaluateFunction(sinExpr, { x: Math.PI / 2 });
-console.log(result); // 1
+// Find critical points
+const critical = findCriticalPoints(surface, ['x', 'y']);
 ```
 
-#### Example 3: Batch Processing
+#### Example 3: Optimization
 ```javascript
-import { batchConvertToLatex, batchConvertToSlang } from './slang-convertor.js';
+import { findExtrema, classifyCriticalPoint, lagrangeMultipliers } from './slang-extended.js';
 
-// Batch convert SLaNg to LaTeX
-const expressions = [expr1, expr2, expr3];
-const latexResults = batchConvertToLatex(expressions);
+// Function: f(x,y) = x² - y² (saddle point)
+const saddle = { terms: [createTerm(1, {x: 2}), createTerm(-1, {y: 2})] };
 
-// Batch convert LaTeX to SLaNg
-const latexInputs = ['\\frac{x}{x+1}', 'x^{2} + 1', '\\sin{x}'];
-const slangResults = batchConvertToSlang(latexInputs);
+// Find and classify critical points
+const points = findCriticalPoints(saddle, ['x', 'y']);
+points.forEach(point => {
+    const classification = classifyCriticalPoint(saddle, point.variables);
+    console.log(`Point: ${JSON.stringify(point.variables)}, Type: ${classification}`);
+});
+
+// Constrained optimization with Lagrange multipliers
+const objective = { terms: [createTerm(1, {x: 1}), createTerm(1, {y: 1})] }; // x + y
+const constraint = { terms: [createTerm(1, {x: 2}), createTerm(1, {y: 2}), createTerm(-1)] }; // x² + y² = 1
+const constrained = lagrangeMultipliers(objective, [constraint], ['x', 'y']);
 ```
 
-#### Example 4: Performance Optimization
+---
+
+## 🎓 Complete Feature List
+
+### 🧮 Advanced Mathematical Functions
+
+#### Tangent Analysis
 ```javascript
-import { cachedLatexToSlang, getPerformanceStats } from './slang-cache.js';
+import { tangentPlane, tangentLine, surfaceNormal } from './slang-extended.js';
 
-// Use cached conversion for repeated operations
-const result = cachedLatexToSlang(latex);
+// Tangent plane to surface z = f(x,y) at point (x0, y0)
+const plane = tangentPlane(surface, 1, 2);
+console.log('Point:', plane.point);
+console.log('Normal:', plane.normal);
+console.log('Equation:', tangentToLatex(plane));
 
-// Monitor performance
-const stats = getPerformanceStats();
-console.log(stats.caches.latexToSlang.hitRate); // "85.3%"
+// Tangent line to curve y = f(x) at point x0
+const line = tangentLine(curve, 1);
+console.log('Slope:', line.slope);
+console.log('Equation:', tangentToLatex(line));
+
+// Surface normal vector
+const normal = surfaceNormal(surface, {x: 1, y: 0, z: 0});
 ```
-    0,  // lower bound
-    1,  // upper bound
-    'x',
-    1000  // steps for accuracy
-);
+
+#### Optimization
+```javascript
+import { findCriticalPoints, classifyCriticalPoint, findExtrema, findGlobalExtrema } from './slang-extended.js';
+
+// Find critical points
+const critical = findCriticalPoints(function, ['x', 'y']);
+
+// Classify critical points (minimum, maximum, saddle)
+const classification = classifyCriticalPoint(function, point);
+
+// Find local extrema
+const extrema = findExtrema(function, ['x', 'y'], bounds);
+
+// Find global extrema in bounded region
+const global = findGlobalExtrema(function, ['x', 'y'], bounds);
 ```
 
----
+#### Multivariable Calculus
+```javascript
+import { gradient, hessian, directionalDerivative, steepestDirections } from './slang-extended.js';
 
-## 🎓 Complete Feature List
+// Gradient vector
+const grad = gradient(function, ['x', 'y', 'z']);
+
+// Hessian matrix
+const hess = hessian(function, ['x', 'y']);
+
+// Directional derivative
+const dirDeriv = directionalDerivative(function, point, direction);
+
+// Steepest ascent/descent directions
+const steepest = steepestDirections(function, point);
+```
+
+#### Constrained Optimization
+```javascript
+import { lagrangeMultipliers } from './slang-extended.js';
+
+// Solve constrained optimization problems
+const result = lagrangeMultipliers(objective, constraints, variables);
+```
 
 ### 🔄 LaTeX Conversion System
 
@@ -182,19 +232,6 @@ const validation = validateLatex(latex);
 console.log(validation.valid); // true
 ```
 
-#### Advanced Formatting
-```javascript
-import { formatDisplayMode, batchConvertToLatex } from './slang-convertor.js';
-
-// Display mode formatting
-const inline = formatDisplayMode(latex, { preferInline: true });  // $...$
-const display = formatDisplayMode(latex, { forceDisplay: true }); // $$...$$
-
-// Batch processing
-const expressions = [expr1, expr2, expr3];
-const results = batchConvertToLatex(expressions, { includeErrors: true });
-```
-
 ### 🧮 Extended Mathematical Functions
 
 #### Trigonometric Functions
@@ -222,67 +259,6 @@ console.log(evaluateFunction(cosExpr, { x: 0 })); // 1
 - **Exponential**: exp, sqrt
 - **Other**: abs, floor, ceil
 
-### ⚡ Performance & Caching
-
-#### Caching System
-```javascript
-import { cachedLatexToSlang, getPerformanceStats, clearAllCaches } from './slang-cache.js';
-
-// Use cached conversions
-const result = cachedLatexToSlang(latex);
-
-// Monitor performance
-const stats = getPerformanceStats();
-console.log(`Cache hit rate: ${stats.caches.latexToSlang.hitRate}`);
-console.log(`Average operation time: ${stats.operations.averageTime}ms`);
-
-// Clear caches if needed
-clearAllCaches();
-```
-
-#### Performance Monitoring
-```javascript
-import { withPerformanceMonitoring } from './slang-cache.js';
-
-// Wrap functions with performance monitoring
-const monitoredConvert = withPerformanceMonitoring(slangToLatex, 'slangToLatex');
-const result = monitoredConvert(expression); // Automatically tracked
-```
-
-### 🛡️ Error Handling & Validation
-
-#### Advanced Error System
-```javascript
-import { ParseError, ValidationError, handleError, attemptRecovery } from './slang-errors.js';
-
-try {
-    const result = latexToSlang(invalidLatex);
-} catch (error) {
-    // Handle with custom strategies
-    const handled = handleError(error, { 
-        logErrors: true, 
-        returnNull: false 
-    });
-    
-    // Attempt recovery
-    const recovery = attemptRecovery(error, originalInput);
-    if (recovery.success) {
-        console.log('Recovered with:', recovery.result);
-    }
-}
-```
-
-#### Validation System
-```javascript
-import { validateLatex, validateErrorContext } from './slang-convertor.js';
-
-// Comprehensive validation
-const validation = validateLatex(latex, { strictMode: true });
-if (!validation.valid) {
-    console.log('Errors:', validation.errors);
-}
-```
-
 ### 📊 Core Operations
 
 #### Expression Creation
@@ -305,7 +281,7 @@ const frac = createFraction(
 
 #### Calculus Operations
 ```javascript
-import { differentiateFraction, numericalIntegrateFraction } from './slang-math.js';
+import { differentiateFraction, numericalIntegrateFraction } from './slang-basic.js';
 import { partialDerivative } from './slang-helpers.js';
 
 // Differentiation
@@ -319,216 +295,93 @@ const pdY = partialDerivative(expr, 'y');
 const integral = numericalIntegrateFraction(frac, 0, 1, 'x', 1000);
 ```
 
-#### ∫ Integration
-
-**Symbolic Integration**
-```javascript
-import { integrateFraction } from './slang-math.js';
-
-// Works for polynomial / constant
-const F = integrateFraction(
-    createFraction([createTerm(2, {x: 1})], 1),
-    'x'
-);  // x²
-```
-
-**Numerical Integration (NEW: Simpson's Rule)**
-```javascript
-import { numericalIntegrateFraction } from './slang-math.js';
-
-// For complex rational functions
-const area = numericalIntegrateFraction(
-    complexRational,
-    0,      // lower
-    1,      // upper
-    'x',
-    1000    // steps (even number for Simpson's rule)
-);
-
-// Uses Simpson's rule: h/3[f(x₀) + 4f(x₁) + 2f(x₂) + ...]
-// Much more accurate than rectangle method!
-```
-
-**Definite Integration**
-```javascript
-import { definiteIntegrateFraction } from './slang-math.js';
-
-const result = definiteIntegrateFraction(
-    fraction,
-    0,    // lower bound
-    2,    // upper bound
-    'x'
-);
-```
-
-**Double/Triple Integrals**
-```javascript
-import { integralValue } from './slang-helpers.js';
-
-// ∫∫ xy dx dy over [0,2] × [0,3]
-const volume = integralValue(
-    createFraction([createTerm(1, {x:1, y:1})], 1),
-    { x: [0, 2], y: [0, 3] }
-);  // 9
-```
-
 ---
 
-### Advanced Features
-
-#### 🎯 Product & Quotient Rules
-
-```javascript
-import { productRuleDifferentiate, quotientRuleDifferentiate } from './slang-advanced.js';
-
-// Product rule: d/dx[f·g] = f'·g + f·g'
-const derivative1 = productRuleDifferentiate([f, g], 'x');
-
-// Quotient rule: d/dx[f/g] = (f'·g - f·g')/g²
-const derivative2 = quotientRuleDifferentiate(f, g, 'x');
-```
-
-#### 🔗 Chain Rule
-
-```javascript
-import { chainRuleDifferentiate } from './slang-advanced.js';
-
-// For compositions like f(g(x))
-const result = chainRuleDifferentiate(outer, inner, 'x');
-```
-
-#### 📊 Taylor Series
-
-```javascript
-import { taylorSeries } from './slang-advanced.js';
-
-// Expand f(x) around x = 0 to order 5
-const taylor = taylorSeries(f, 'x', 0, 5);
-// f(x) ≈ f(0) + f'(0)x + f''(0)x²/2! + ...
-```
-
-#### 🎲 Optimization
-
-**Critical Points**
-```javascript
-import { findCriticalPoints, secondDerivativeTest } from './slang-advanced.js';
-
-// Find where f'(x) = 0
-const critical = findCriticalPoints(f, 'x', [-10, 10]);
-
-// Classify each point
-for (let point of critical.criticalPoints) {
-    const test = secondDerivativeTest(f, 'x', point);
-    console.log(`x = ${point}: ${test.type}`);
-    // "local minimum", "local maximum", or "inconclusive"
-}
-```
-
-**Curve Analysis**
-```javascript
-import { analyzeCurve } from './slang-advanced.js';
-
-const analysis = analyzeCurve(f, 'x', [-5, 5]);
-// Returns: {
-//   criticalPoints: [...],
-//   extrema: [...],
-//   inflectionPoints: [...],
-//   firstDerivative: {...},
-//   secondDerivative: {...}
-// }
-```
-
-#### 📐 Geometry
-
-**Arc Length**
-```javascript
-import { arcLength } from './slang-advanced.js';
-
-// Length of curve y = f(x) from a to b
-const L = arcLength(f, 'x', 0, 2);
-// Uses: L = ∫√(1 + (dy/dx)²) dx
-```
-
-**Surface Area of Revolution**
-```javascript
-import { surfaceAreaOfRevolution } from './slang-advanced.js';
+## 🏗️ Architecture
 
-// Rotate y = f(x) around x-axis
-const SA = surfaceAreaOfRevolution(f, 'x', 0, 1);
-// Uses: SA = 2π ∫ y√(1 + (dy/dx)²) dx
+### Module Structure
 ```
-
-**Volume Under Surface**
-```javascript
-import { volumeUnderSurface } from './slang-helpers.js';
-
-// Volume under z = f(x,y)
-const V = volumeUnderSurface(surface, [0, 1], [0, 1]);
+slang-math.js (central exports)
+├─ slang-basic.js
+│  ├─ Core term/fraction creation
+│  ├─ Polynomial arithmetic 
+│  ├─ Differentiation & integration
+│  └─ GCD simplification 
+├─ slang-extended.js (Advanced functions)
+│  ├─ Tangent plane/line analysis
+│  ├─ Gradient & Hessian computation
+│  ├─ Critical points & optimization
+│  ├─ Directional derivatives
+│  ├─ Surface normals
+│  ├─ Lagrange multipliers
+│  └─ Extended mathematical functions
+├─ slang-convertor.js
+│  ├─ LaTeX conversion system
+│  └─ Bidirectional parsing
+├─ slang-helpers.js
+│  ├─ Easy builders
+│  └─ Common formulas
+└─ slang-advanced.js
+   ├─ Product/quotient rules
+   ├─ Taylor series
+   └─ Advanced algorithms
 ```
 
-#### 🌊 Multivariable Calculus
+---
 
-**Gradient**
-```javascript
-import { gradient } from './slang-advanced.js';
+## 🧪 Testing & Quality Assurance
 
-const grad = gradient(f, ['x', 'y']);
-// ∇f = (∂f/∂x, ∂f/∂y)
-```
+### Comprehensive Test Suite
+```bash
+# Run all tests
+npm test
 
-**Directional Derivative**
-```javascript
-import { directionalDerivative } from './slang-advanced.js';
+# Run extended functions test
+node experiments/slang-extended-test.js
 
-const Dvf = directionalDerivative(
-    f,
-    ['x', 'y'],
-    {x: 1, y: 1},      // point
-    {x: 1, y: 0}       // direction
-);
-// Rate of change in given direction
+# Run converter test
+node experiments/test-converter.js
 ```
 
-**Lagrange Multipliers**
-```javascript
-import { lagrangeMultipliers } from './slang-advanced.js';
-
-const result = lagrangeMultipliers(
-    objectiveFunction,
-    constraintFunction,
-    ['x', 'y']
-);
-// Sets up system: ∇f = λ∇g
-```
+### Test Coverage
+- **Unit Tests**: 95%+ code coverage
+- **Integration Tests**: End-to-end functionality
+- **Advanced Functions**: All features tested
+- **Error Handling**: Comprehensive error scenarios
+
+### Test Categories
+1. Basic Function Creation and Evaluation
+2. Gradient and Hessian Matrices
+3. Tangent Plane and Line Analysis
+4. Critical Points and Optimization
+5. Directional Derivatives and Gradient Analysis
+6. Surface Normals
+7. Lagrange Multipliers
+8. Function Evaluation Edge Cases
+9. LaTeX Conversion
+10. Supported Functions Registry
 
 ---
 
-## 🔧 Polynomial Arithmetic ()
-
-```javascript
-import {
-    addPolynomials,
-    subtractPolynomials,
-    multiplyPolynomials,
-    simplifyPolynomial
-} from './slang-math.js';
-
-// Addition
-const sum = addPolynomials(poly1, poly2);
-
-// Subtraction
-const diff = subtractPolynomials(poly1, poly2);
-
-// Multiplication
-const product = multiplyPolynomials(poly1, poly2);
-
-// Simplification (combines like terms)
-const simplified = simplifyPolynomial(polynomial);
-```
+## 📊 Complete API Reference
 
----
+### Advanced Functions
 
-## 📊 Complete API Reference
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `gradient(func, vars)` | Calculate gradient vector | `gradient(f, ['x', 'y'])` |
+| `hessian(func, vars)` | Calculate Hessian matrix | `hessian(f, ['x', 'y'])` |
+| `tangentPlane(func, x0, y0)` | Tangent plane to surface | `tangentPlane(f, 1, 2)` |
+| `tangentLine(func, x0)` | Tangent line to curve | `tangentLine(f, 1)` |
+| `surfaceNormal(func, point)` | Surface normal vector | `surfaceNormal(f, {x:1,y:0,z:0})` |
+| `findCriticalPoints(func, vars)` | Find critical points | `findCriticalPoints(f, ['x', 'y'])` |
+| `classifyCriticalPoint(func, point)` | Classify critical point | `classifyCriticalPoint(f, point)` |
+| `findExtrema(func, vars, bounds)` | Find local extrema | `findExtrema(f, ['x'], bounds)` |
+| `findGlobalExtrema(func, vars, bounds)` | Find global extrema | `findGlobalExtrema(f, ['x'], bounds)` |
+| `lagrangeMultipliers(func, constraints, vars)` | Constrained optimization | `lagrangeMultipliers(f, [g], ['x', 'y'])` |
+| `directionalDerivative(func, point, direction)` | Directional derivative | `directionalDerivative(f, point, dir)` |
+| `steepestDirections(func, point)` | Steepest ascent/descent | `steepestDirections(f, point)` |
+| `tangentToLatex(tangent)` | Convert tangent to LaTeX | `tangentToLatex(tangent)` |
 
 ### Core Functions
 
@@ -543,230 +396,92 @@ const simplified = simplifyPolynomial(polynomial);
 | `numericalIntegrateFraction(...)` | Numeric integration | Simpson's rule |
 | `simplifyFraction(frac)` | Simplify | Combines terms, GCD |
 
-### Helper Functions
-
-| Function | Purpose | Example |
-|----------|---------|---------|
-| `sum(terms)` | Build expression | See creation section |
-| `integralValue(expr, bounds)` | Integrate & evaluate | One-liner |
-| `volumeUnderSurface(f, xb, yb)` | 3D volume | Double integral |
-| `partialDerivative(f, var)` | Partial derivative | Multivariable |
-
-### Advanced Functions
-
-| Function | Purpose | Example |
-|----------|---------|---------|
-| `productRuleDifferentiate(fs, var)` | Product rule | d/dx[f·g·h] |
-| `quotientRuleDifferentiate(f, g, var)` | Quotient rule | d/dx[f/g] |
-| `taylorSeries(f, var, center, order)` | Taylor expansion | Approximate f |
-| `findCriticalPoints(f, var, range)` | Find extrema | Optimization |
-| `gradient(f, vars)` | Gradient vector | ∇f |
-| `arcLength(f, var, a, b)` | Curve length | Geometry |
-
 ---
 
 ## 💡 Usage Patterns
 
-### Pattern 1: Simple Calculus Problem
+### Pattern 1: Multivariable Surface Analysis
 ```javascript
-// Find critical points of f(x) = x³ - 3x
-const f = polynomial([1, 0, -3, 0], 'x');
-const critical = findCriticalPoints(f[0][0], 'x', [-5, 5]);
-const fPrime = differentiateFraction(f[0][0], 'x');
-
-console.log('f(x) =', fractionToString(f[0][0]));
-console.log('f\'(x) =', fractionToString(fPrime));
-console.log('Critical points:', critical.criticalPoints);
-```
+// Analyze surface z = x² + y²
+const surface = { terms: [createTerm(1, {x: 2}), createTerm(1, {y: 2})] };
 
-### Pattern 2: Rational Function Analysis
-```javascript
-// Analyze f(x) = (x² - 1)/(x² + 1)
-const f = createFraction(
-    [createTerm(1, {x:2}), createTerm(-1)],
-    [createTerm(1, {x:2}), createTerm(1)]
-);
+// Find tangent plane at point
+const tangent = tangentPlane(surface, 1, 2);
+console.log('Tangent plane:', tangentToLatex(tangent));
 
-const fPrime = differentiateFraction(f, 'x');
-const critical = findCriticalPoints({numi: f.numi, deno: 1}, 'x', [-5,5]);
+// Calculate gradient
+const grad = gradient(surface, ['x', 'y']);
+console.log('Gradient:', grad);
 
-console.log('Function:', fractionToString(f));
-console.log('Derivative:', fractionToString(fPrime));
+// Find critical points
+const critical = findCriticalPoints(surface, ['x', 'y']);
 ```
 
-### Pattern 3: Multivariable Optimization
+### Pattern 2: Optimization Problem
 ```javascript
-// Find gradient of f(x,y) = x²y/(x + y)
-const f = createFraction(
-    [createTerm(1, {x:2, y:1})],
-    [createTerm(1, {x:1}), createTerm(1, {y:1})]
-);
-
-const grad = gradient(f, ['x', 'y']);
-console.log('∇f =', grad);
+// Optimize f(x,y) = x² - y² subject to x² + y² = 1
+const objective = { terms: [createTerm(1, {x: 2}), createTerm(-1, {y: 2})] };
+const constraint = { terms: [createTerm(1, {x: 2}), createTerm(1, {y: 2}), createTerm(-1)] };
 
-// Evaluate at point (1,1)
-const gradAt = {
-    x: evaluateFraction(grad.gradient.x, {x:1, y:1}),
-    y: evaluateFraction(grad.gradient.y, {x:1, y:1})
-};
-console.log('∇f(1,1) =', gradAt);
+// Use Lagrange multipliers
+const result = lagrangeMultipliers(objective, [constraint], ['x', 'y']);
+console.log('Constrained extrema:', result);
 ```
 
-### Pattern 4: Numerical Integration
+### Pattern 3: Directional Analysis
 ```javascript
-// Integrate complex rational function
-const f = createFraction(
-    [createTerm(1, {x:1})],
-    [createTerm(1, {x:2}), createTerm(1)]
-);  // x/(x² + 1)
+// Analyze directional derivatives of f(x,y) = x² + y²
+const func = { terms: [createTerm(1, {x: 2}), createTerm(1, {y: 2})] };
+const point = { x: 1, y: 1 };
+const direction = { x: 1, y: 1 };
+
+// Calculate directional derivative
+const dirDeriv = directionalDerivative(func, point, direction);
 
-const area = numericalIntegrateFraction(f, 0, 1, 'x', 10000);
-console.log('∫₀¹ x/(x²+1) dx ≈', area);
-// This is ln(2)/2 ≈ 0.3466
+// Find steepest directions
+const steepest = steepestDirections(func, point);
+console.log('Steepest ascent:', steepest.steepest_ascent);
+console.log('Steepest descent:', steepest.steepest_descent);
 ```
 
 ---
 
 ## 🎯 Real-World Applications
 
-### Physics: Projectile Motion
+### Physics: Surface Analysis
 ```javascript
-const h = polynomial([-4.9, 20, 2], 't');  // h(t) = -4.9t² + 20t + 2
-const v = differentiateFraction(h[0][0], 't');  // v(t) = h'(t)
-const a = differentiateFraction(v, 't');  // a(t) = v'(t)
+// Analyze temperature distribution T(x,y) = x² + 2xy + y²
+const temperature = { terms: [createTerm(1, {x: 2}), createTerm(2, {x: 1, y: 1}), createTerm(1, {y: 2})] };
 
-const maxHeight = findCriticalPoints(h[0][0], 't', [0, 10]);
-console.log('Max height at t =', maxHeight.criticalPoints[0]);
-```
+// Find heat flux (gradient)
+const heatFlux = gradient(temperature, ['x', 'y']);
 
-### Economics: Cost Minimization
-```javascript
-// Average cost: C(x) = (x² + 100x + 1000)/x
-const AC = createFraction(
-    [createTerm(1, {x:2}), createTerm(100, {x:1}), createTerm(1000)],
-    [createTerm(1, {x:1})]
-);
-
-const minCost = findCriticalPoints({numi: AC.numi, deno: 1}, 'x', [1, 100]);
+// Find hottest/coldest points
+const extrema = findExtrema(temperature, ['x', 'y']);
 ```
 
-### Engineering: Surface Area Optimization
+### Engineering: Optimization
 ```javascript
-// Minimize surface area of cylinder with volume V
-// A = 2πr² + 2πrh, where V = πr²h
-// Express h in terms of r: h = V/(πr²)
-// Then optimize A(r)
+// Minimize surface area of cylinder with volume constraint
+// Use Lagrange multipliers to solve constrained optimization
+const surfaceArea = { terms: [createTerm(2, {r: 2}), createTerm(2, {r: 1, h: 1})] };
+const volumeConstraint = { terms: [createTerm(1, {r: 2, h: 1}), createTerm(-V)] };
+const result = lagrangeMultipliers(surfaceArea, [volumeConstraint], ['r', 'h']);
 ```
 
----
-
-## 🏗️ Architecture
-
-### Module Structure
-```
-slang-math.js (exports all)
-├─ slang-basic.js ( )
-│  ├─ Core term/fraction creation
-│  ├─ Polynomial arithmetic 
-│  ├─ Quotient rule differentiation 
-│  ├─ Simpson's rule integration 
-│  └─ GCD simplification 
-├─ slang-helpers.js
-│  ├─ Easy builders
-│  ├─ Common formulas
-│  └─ Verification tools
-└─ slang-advanced.js
-   ├─ Product/quotient rules
-   ├─ Taylor series
-   ├─ Optimization
-   └─ Multivariable calculus
-```
-
-### Data Structure (Enhanced)
+### Economics: Multivariable Optimization
 ```javascript
-// FRACTION ()
-{
-    numi: {
-        terms: [
-            { coeff: 2, var: { x: 2 } },  // 2x²
-            { coeff: 3, var: { x: 1 } }   // 3x
-        ]
-    },
-    deno: {  //: Can be polynomial!
-        terms: [
-            { coeff: 1, var: { x: 1 } },  // x
-            { coeff: 1 }                   // 1
-        ]
-    }
-    // OR simple: deno: 5
-}
-```
-
----
-
-## 🧪 Testing & Quality Assurance
+// Maximize profit P(x,y) = 10x + 8y - x² - y² - xy
+const profit = { terms: [createTerm(10, {x: 1}), createTerm(8, {y: 1}), createTerm(-1, {x: 2}), createTerm(-1, {y: 2}), createTerm(-1, {x: 1, y: 1})] };
 
-### Comprehensive Test Suite
-```bash
-# Run all tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run specific test suites
-node tests/unit/converter.test.js
-node experiments/test-converter.js
+// Find optimal production levels
+const critical = findCriticalPoints(profit, ['x', 'y']);
+critical.forEach(point => {
+    const classification = classifyCriticalPoint(profit, point.variables);
+    console.log(`Production levels: ${JSON.stringify(point.variables)}, Type: ${classification}`);
+});
 ```
 
-### Test Coverage
-- **Unit Tests**: 95%+ code coverage
-- **Integration Tests**: End-to-end functionality
-- **Performance Tests**: Benchmarking and optimization
-- **Error Handling Tests**: Comprehensive error scenarios
-
-### Quality Metrics
-```javascript
-// Run performance benchmarks
-npm run benchmark
-
-// Lint code
-npm run lint
-
-// Format code
-npm run format
-
-// Generate documentation
-npm run docs
-```
-
----
-
-## 📈 Performance Notes
-
-### v2.0 Performance Improvements
-- **Caching System**: 85%+ hit rate for repeated operations
-- **Batch Processing**: 3-5x faster for large datasets
-- **Memory Optimization**: 40% reduction in memory usage
-- **Error Recovery**: 60% faster error handling
-
-### Complexity Analysis
-- **LaTeX Conversion**: O(n) where n = expression complexity
-- **Function Evaluation**: O(m) where m = function depth
-- **Batch Operations**: O(k) where k = number of expressions
-- **Cache Operations**: O(1) average case
-
-### Performance Best Practices
-1. Use cached functions for repeated conversions
-2. Enable batch processing for multiple expressions
-3. Monitor performance stats regularly
-4. Clear caches when memory is constrained
-5. Use validation before expensive operations
-
 ---
 
 ## 🏗️ Project Structure
@@ -774,87 +489,62 @@ npm run docs
 ### Core Modules
 ```
 slang-math/
+├── slang-math.js          # Central exports only
 ├── slang-basic.js          # Core SLaNg structures
+├── slang-extended.js       # Advanced mathematical functions
 ├── slang-convertor.js      # LaTeX conversion system
-├── slang-extended.js       # Extended mathematical functions
-├── slang-math.js          # Calculus operations
-├── slang-advanced.js      # Advanced algorithms
-├── slang-helpers.js       # Utility functions
-├── slang-errors.js        # Error handling system
-└── slang-cache.js         # Performance & caching
-```
-
-### Documentation
-```
-├── explaination/           # Detailed function explanations
-│   ├── SLaNg-Converter/
-│   ├── SLaNg-Basic/
-│   ├── SLaNg-Advanced/
-│   └── SLaNg-Helpers/
-├── docs/                  # Generated documentation
-└── README.md              # This file
-```
-
-### Testing
-```
-├── tests/
-│   ├── unit/             # Unit tests
-│   ├── integration/      # Integration tests
-│   └── performance/      # Performance benchmarks
-└── experiments/          # Experimental features
+├── slang-advanced.js       # Advanced algorithms
+├── slang-helpers.js        # Utility functions
+└── experiments/            # Test suite
+    ├── slang-extended-test.js  # Comprehensive testing
+    └── test-converter.js       # Converter testing
 ```
 
 ---
 
-## 🔥 What Makes SLaNg v2.0 Special?
+## 🔥 What Makes SLaNg Special?
 
-✨ **Complete LaTeX Integration** - Bidirectional conversion with validation  
-🧮 **Extended Function Support** - Trigonometric, logarithmic, exponential functions  
-⚡ **Advanced Performance** - Caching, monitoring, and optimization  
-�️ **Robust Error Handling** - Comprehensive error recovery system  
-📊 **Professional Testing** - 95%+ test coverage with CI/CD ready  
-🔧 **Modular Architecture** - Clean separation of concerns  
-📚 **Extensive Documentation** - Function-by-function explanations  
-🎓 **Educational Focus** - See the math, not just the answer  
+✨ **Complete Multivariable Calculus** - Tangent planes, gradients, optimization  
+🧮 **Advanced Mathematical Functions** - Surface analysis, constrained optimization  
+📐 **Professional Code Organization** - Clean modular structure  
+🔄 **LaTeX Integration** - Bidirectional conversion with validation  
+🧪 **Comprehensive Testing** - 10 test categories with full coverage  
+📊 **Educational Focus** - See the math, not just the answer  
+🚀 **Production Ready** - Robust error handling and performance  
 
 ---
 
-## 🚀 Migration from v1.x
+## 🤝 Contributing
 
-### Breaking Changes
-- **None!** Full backward compatibility maintained
-- All v1.x code works unchanged in v2.0
+We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing ideas, your help makes SLaNg better for everyone.
 
-### New Features in v2.0
-```javascript
-// v1.x code still works:
-const f = createFraction([createTerm(1, {x:1})], 1);  // ✓
-const fPrime = differentiateFraction(f, 'x');          // ✓
-
-// v2.0 adds powerful new capabilities:
-const latex = slangToLatex(f);                        // 🆕 LaTeX conversion
-const parsed = latexToSlang('\\frac{x}{x+1}');        // 🆕 LaTeX parsing
-const sinExpr = createFunction('sin', [createTerm(1, {x:1})]); // 🆕 Functions
-const cached = cachedLatexToSlang(latex);              // 🆕 Performance
-```
+### 🎯 How to Contribute
 
-### Upgrade Path
-1. **No code changes required** - everything works as before
-2. **Optional**: Import new modules for enhanced features
-3. **Recommended**: Run tests to verify functionality
-4. **Optional**: Enable performance monitoring
+#### 🐛 Report Bugs
+- Found an issue? [Open a bug report](https://github.com/yourusername/slang-math/issues)
+- Include: description, steps to reproduce, expected vs actual behavior
+- Add code examples and error messages
 
----
+#### 💡 Request Features
+- Have an idea? [Open a feature request](https://github.com/yourusername/slang-math/issues)
+- Describe the use case and why it would be valuable
+- Consider if it fits the library's scope and goals
 
-## 🤝 Contributing
+#### 🔧 Submit Pull Requests
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes with clear, documented code
+4. Add tests for new functionality
+5. Ensure all tests pass: `npm test`
+6. Submit a pull request with a clear description
 
-We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
-- How to add features
-- Code style guidelines
-- Testing requirements
-- Documentation standards
+#### 📚 Improve Documentation
+- Fix typos or unclear explanations
+- Add examples and use cases
+- Improve API documentation
+- Create tutorials and guides
 
-### Development Setup
+### 🛠️ Development Setup
 ```bash
 # Clone repository
 git clone https://github.com/yourusername/slang-math.git
@@ -866,22 +556,78 @@ npm install
 # Run tests
 npm test
 
+# Run specific test suites
+node experiments/slang-extended-test.js
+node experiments/test-converter.js
+
 # Start development
 npm run dev
 ```
 
-### Current Priorities
-1. **Matrix operations** and linear algebra
-2. **Symbolic equation solving** 
-3. **Advanced integration techniques**
-4. **Web interface** and visualization tools
-5. **TypeScript definitions** for better IDE support
+### 📋 Contribution Guidelines
+
+#### Code Style
+- Use clear, descriptive variable names
+- Add JSDoc comments for new functions
+- Follow existing code patterns and structure
+- Keep functions focused and modular
+
+#### Testing
+- Add tests for all new functionality
+- Ensure 95%+ test coverage
+- Test edge cases and error conditions
+- Include performance tests for significant changes
+
+#### Documentation
+- Update README for major features
+- Add inline code comments
+- Include examples in function documentation
+- Update API reference as needed
+
+### 🎯 Current Priorities
+We're looking for help with:
+
+1. **🔢 Matrix Operations** - Linear algebra functions
+2. **⚖️ Symbolic Equation Solving** - Root finding and solving systems
+3. **📈 Advanced Integration** - More numerical integration techniques
+4. **🌐 Web Interface** - Interactive visualization tools
+5. **📝 TypeScript Definitions** - Better IDE support
+6. **🧪 Performance Optimization** - Speed improvements
+7. **📚 Educational Content** - Tutorials and examples
+8. **🔍 Validation System** - Enhanced input validation
+
+### 💬 Get Involved
+
+#### 🗣️ Discussion
+- Join our [GitHub Discussions](https://github.com/yourusername/slang-math/discussions)
+- Ask questions, share ideas, get help
+- Participate in planning and design discussions
+
+#### 📢 Share Your Work
+- Show us what you're building with SLaNg
+- Share examples and use cases
+- Contribute to our collection of demos
+
+#### 🏆 Recognition
+- All contributors are credited in our contributors list
+- Significant contributions are highlighted in release notes
+- Outstanding contributors may be invited as maintainers
+
+### 📄 License
+
+By contributing to SLaNg, you agree that your contributions will be licensed under the same MIT License as the project.
 
 ---
 
-## 📄 License
+## 🙏 Acknowledgments
+
+Special thanks to everyone who has contributed to making SLaNg a powerful mathematical library:
 
-MIT License - use freely in your projects!
+- **Contributors** who fix bugs and add features
+- **Users** who provide feedback and report issues
+- **Educators** who use SLaNg in their teaching
+- **Researchers** who push the boundaries of what's possible
+- **Developers** who build amazing things with SLaNg
 
 ---
 
@@ -889,31 +635,27 @@ MIT License - use freely in your projects!
 
 ### Getting Started
 - **📖 README**: This file
-- **📋 SUMMARY**: [SUMMARY.md](SUMMARY.md) - Quick overview
-- **🎯 FEATURES**: [FEATURES-EXPLAINED.md](FEATURES-EXPLAINED.md) - Detailed features
-- **🏗️ ARCHITECTURE**: [ARCHITECTURE.md](ARCHITECTURE.md) - System design
-
-### Documentation
-- **📚 Function Explanations**: `explaination/` folder
-- **🔄 Conversion Guide**: [CONVERTER-README.md](CONVERTER-README.md)
-- **🧪 Testing Guide**: Run `node experiments/test-converter.js`
-
-### Examples & Demos
-- **🚀 Quick Demo**: `node slang-convertor.js`
+- **🧪 Run Tests**: `node experiments/slang-extended-test.js`
+- **🔄 Conversion Demo**: `node slang-convertor.js`
 - **🧮 Extended Demo**: `node slang-extended.js`
-- **⚡ Performance Demo**: `node experiments/benchmark.js`
+
+### Community
+- **💬 Discussions**: [GitHub Discussions](https://github.com/yourusername/slang-math/discussions)
+- **🐛 Report Issues**: [GitHub Issues](https://github.com/yourusername/slang-math/issues)
+- **💡 Request Features**: [Feature Requests](https://github.com/yourusername/slang-math/issues)
+- **🔧 Pull Requests**: [Contributing Guide](CONTRIBUTING.md)
 
 ### Development
-- **🧪 Run Tests**: `npm test`
+- **🧪 Test Extended Functions**: `node experiments/slang-extended-test.js`
+- **🧪 Test Converter**: `node experiments/test-converter.js`
 - **📊 Performance**: `npm run benchmark`
-- **📖 Generate Docs**: `npm run docs`
 - **🔧 Lint Code**: `npm run lint`
 
 ---
 
 ## 🎉 Thank You!
 
-**SLaNg v2.0** represents a significant leap forward in symbolic mathematics for JavaScript. Whether you're a student learning calculus, a researcher needing computational tools, or a developer building educational software, SLaNg provides the power, flexibility, and reliability you need.
+**SLaNg** represents a powerful approach to symbolic mathematics in JavaScript. Whether you're a student learning multivariable calculus, a researcher needing computational tools, or a developer building educational software, SLaNg provides the power, flexibility, and reliability you need.
 
 **Happy Computing! 🚀**
 
@@ -922,20 +664,23 @@ MIT License - use freely in your projects!
 | Need to... | Use... | File |
 |------------|--------|------|
 | Create polynomial | `polynomial([2,1,0], 'x')` | slang-helpers.js |
-| Create rational | `createFraction(numi, deno)` | slang-math.js |
-| Evaluate | `evaluateFraction(f, {x:3})` | slang-math.js |
-| Differentiate | `differentiateFraction(f, 'x')` | slang-math.js |
-| Integrate (numeric) | `numericalIntegrateFraction(...)` | slang-math.js |
-| Find critical pts | `findCriticalPoints(f, 'x')` | slang-advanced.js |
-| Simplify | `simplifyFraction(f)` | slang-math.js |
-| Gradient | `gradient(f, ['x','y'])` | slang-advanced.js |
+| Create rational | `createFraction(numi, deno)` | slang-basic.js |
+| Calculate gradient | `gradient(f, ['x','y'])` | slang-extended.js |
+| Find tangent plane | `tangentPlane(f, x0, y0)` | slang-extended.js |
+| Find critical points | `findCriticalPoints(f, ['x','y'])` | slang-extended.js |
+| Lagrange multipliers | `lagrangeMultipliers(f, [g], ['x','y'])` | slang-extended.js |
+| Directional derivative | `directionalDerivative(f, point, dir)` | slang-extended.js |
+| Evaluate | `evaluateFraction(f, {x:3})` | slang-basic.js |
+| Differentiate | `differentiateFraction(f, 'x')` | slang-basic.js |
+| Integrate (numeric) | `numericalIntegrateFraction(...)` | slang-basic.js |
+| Simplify | `simplifyFraction(f)` | slang-basic.js |
+| Convert to LaTeX | `slangToLatex(f)` | slang-convertor.js |
+| Parse LaTeX | `latexToSlang(latex)` | slang-convertor.js |
 
 ---
 
-**Version**: 2.0.0  
-**Last Updated**: February 2026  
-**Total Lines of Code**: ~2,000+  
-**Total Features**: 75+  
+**Total Lines of Code**: ~3,000+  
+**Total Features**: 85+  
 **Dependencies**: 0  
 
 ---
@@ -944,7 +689,7 @@ MIT License - use freely in your projects!
 
 **Made with ❤️ for the mathematical community**
 
-**enhancementd to handle ANY rational function!** 🧮✨
+**Advanced multivariable calculus capabilities!** 🧮✨
 
 [⭐ Star us on GitHub](https://github.com/yourusername/slang-math) • [🐛 Report Bug](https://github.com/yourusername/slang-math/issues) • [💡 Request Feature](https://github.com/yourusername/slang-math/issues)