Merge pull request #1 from sahildando/codex/implement-production-grade-adv_math_engine-module

Add adv_math_engine package: vector algebra, vector calculus, series expansions, CLI and tests

Author: sahildando

adv_math_engine/README.md

@@ -0,0 +1,57 @@
+# adv_math_engine
+
+Production-grade module for:
+- Vector algebra
+- Vector calculus
+- Taylor / Maclaurin series expansion
+
+## Structure
+
+```text
+adv_math_engine/
+  ├── vector_algebra.py
+  ├── vector_calculus.py
+  ├── series_expansion.py
+  ├── utils.py
+  ├── benchmarks/
+  ├── visualizations/
+  ├── examples/
+  └── tests/
+```
+
+## CLI
+
+```bash
+python main.py --function "sin(x)" --series taylor --order 5 --x 0.5 --center 0.0
+```
+
+## Visualizations
+
+Run:
+
+```bash
+python adv_math_engine/visualizations/plot_gradient_field.py
+python adv_math_engine/visualizations/plot_series_approximation.py
+```
+
+Outputs:
+- `adv_math_engine/visualizations/gradient_field.png`
+- `adv_math_engine/visualizations/series_approximation.png`
+
+## Benchmarks
+
+```bash
+python adv_math_engine/benchmarks/benchmark_diff.py
+```
+
+See `adv_math_engine/benchmarks/results.md`.
+
+## Coverage
+
+Suggested command:
+
+```bash
+pytest adv_math_engine/tests --cov=adv_math_engine --cov-report=term-missing
+```
+
+See `adv_math_engine/tests/coverage_report.txt`.

adv_math_engine/__init__.py

@@ -0,0 +1,41 @@
+"""Advanced mathematics engine for vector algebra, vector calculus, and series expansions."""
+
+from adv_math_engine.series_expansion import (
+    estimate_lagrange_remainder,
+    maclaurin_series,
+    taylor_series,
+)
+from adv_math_engine.vector_algebra import (
+    angle_between,
+    check_linear_independence,
+    cross_product,
+    dot_product,
+    gram_schmidt,
+    vector_projection,
+)
+from adv_math_engine.vector_calculus import (
+    curl,
+    divergence,
+    gradient,
+    line_integral,
+    partial_derivative,
+    surface_integral,
+)
+
+__all__ = [
+    "angle_between",
+    "check_linear_independence",
+    "cross_product",
+    "curl",
+    "divergence",
+    "dot_product",
+    "estimate_lagrange_remainder",
+    "gradient",
+    "gram_schmidt",
+    "line_integral",
+    "maclaurin_series",
+    "partial_derivative",
+    "surface_integral",
+    "taylor_series",
+    "vector_projection",
+]

adv_math_engine/benchmarks/benchmark_diff.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import numpy as np
+
+from adv_math_engine.series_expansion import _numerical_nth_derivative
+from adv_math_engine.utils import timed_call
+
+try:
+    import sympy as sp
+except Exception:  # pragma: no cover
+    sp = None
+
+
+def numerical_benchmark(iterations: int = 2000) -> float:
+    func = lambda x: np.sin(x) * np.exp(x)
+
+    def run() -> float:
+        total = 0.0
+        for value in np.linspace(-1.0, 1.0, iterations):
+            total += _numerical_nth_derivative(func, n=1, at=float(value))
+        return total
+
+    _, elapsed = timed_call(run)
+    return elapsed
+
+
+def symbolic_benchmark(iterations: int = 2000) -> float | None:
+    if sp is None:
+        return None
+    x = sp.symbols("x")
+    derivative_expr = sp.diff(sp.sin(x) * sp.exp(x), x)
+    evaluator = sp.lambdify(x, derivative_expr, "numpy")
+
+    def run() -> float:
+        total = 0.0
+        for value in np.linspace(-1.0, 1.0, iterations):
+            total += float(evaluator(value))
+        return total
+
+    _, elapsed = timed_call(run)
+    return elapsed
+
+
+if __name__ == "__main__":
+    num_time = numerical_benchmark()
+    sym_time = symbolic_benchmark()
+    print(f"numerical_time_seconds={num_time:.6f}")
+    if sym_time is None:
+        print("symbolic_time_seconds=unavailable")
+    else:
+        print(f"symbolic_time_seconds={sym_time:.6f}")

adv_math_engine/benchmarks/results.md

@@ -0,0 +1,17 @@
+# Benchmark Results
+
+## Status
+Benchmark execution is prepared via:
+
+```bash
+python adv_math_engine/benchmarks/benchmark_diff.py
+```
+
+In this environment, benchmark execution could not be completed because required numerical dependencies (NumPy/SymPy) were unavailable to the active Python interpreter.
+
+## Expected Output Format
+
+```text
+numerical_time_seconds=<float>
+symbolic_time_seconds=<float|unavailable>
+```

adv_math_engine/examples/example_usage.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import numpy as np
+
+from adv_math_engine.series_expansion import maclaurin_series
+from adv_math_engine.vector_algebra import dot_product, gram_schmidt
+from adv_math_engine.vector_calculus import gradient
+
+
+if __name__ == "__main__":
+    print("Dot:", dot_product([1, 2, 3], [4, 5, 6]))
+    print("Orthonormal basis:\n", gram_schmidt([[1, 1, 0], [1, 0, 1], [0, 1, 1]]))
+
+    f = lambda x, y, z: x**2 + y**2 + z**2
+    print("Gradient at (1,2,3):", gradient(f, [1, 2, 3]))
+
+    x = np.array([0.1, 0.2, 0.3])
+    print("sin(x) Maclaurin order=7:", maclaurin_series(x, order=7, function_name="sin"))

adv_math_engine/series_expansion.py

@@ -0,0 +1,102 @@
+"""Taylor/Maclaurin series expansion utilities."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Literal
+
+import numpy as np
+
+HAS_SYMPY = True
+try:
+    import sympy as sp
+except Exception:  # pragma: no cover - optional dependency guard
+    HAS_SYMPY = False
+
+
+SupportedFunction = Literal["exp", "sin", "cos", "log1p"]
+
+
+def _builtin_derivative_value(name: SupportedFunction, n: int, at: float) -> float:
+    if name == "exp":
+        return float(math.exp(at))
+    if name == "sin":
+        return float(math.sin(at + n * math.pi / 2.0))
+    if name == "cos":
+        return float(math.cos(at + n * math.pi / 2.0))
+    if name == "log1p":
+        if n == 0:
+            return float(math.log1p(at))
+        return float(((-1) ** (n - 1)) * math.factorial(n - 1) / (1.0 + at) ** n)
+    msg = f"Unsupported function: {name}"
+    raise ValueError(msg)
+
+
+def _numerical_nth_derivative(func: Callable[[float], float], n: int, at: float, h: float = 1e-4) -> float:
+    if n == 0:
+        return float(func(at))
+    if n == 1:
+        return float((func(at + h) - func(at - h)) / (2.0 * h))
+    return float(
+        (_numerical_nth_derivative(func, n - 1, at + h, h) - _numerical_nth_derivative(func, n - 1, at - h, h)) / (2.0 * h)
+    )
+
+
+def taylor_series(
+    x: float | np.ndarray,
+    order: int,
+    center: float = 0.0,
+    *,
+    function_name: SupportedFunction | None = None,
+    function: Callable[[float], float] | None = None,
+) -> np.ndarray:
+    """Evaluate Taylor polynomial of given order around center.
+
+    f(x) ≈ Σ[n=0..order] f^(n)(a) / n! * (x-a)^n
+    """
+    if function_name is None and function is None:
+        msg = "Provide either function_name or function."
+        raise ValueError(msg)
+
+    x_arr = np.asarray(x, dtype=float)
+    approximation = np.zeros_like(x_arr, dtype=float)
+
+    for n in range(order + 1):
+        if function_name is not None:
+            derivative_at_center = _builtin_derivative_value(function_name, n, center)
+        else:
+            assert function is not None
+            derivative_at_center = _numerical_nth_derivative(function, n, center)
+
+        approximation = approximation + derivative_at_center / math.factorial(n) * (x_arr - center) ** n
+
+    return approximation
+
+
+def maclaurin_series(
+    x: float | np.ndarray,
+    order: int,
+    *,
+    function_name: SupportedFunction | None = None,
+    function: Callable[[float], float] | None = None,
+) -> np.ndarray:
+    """Evaluate Maclaurin polynomial (Taylor around 0)."""
+    return taylor_series(x, order=order, center=0.0, function_name=function_name, function=function)
+
+
+def estimate_lagrange_remainder(max_derivative: float, x: float | np.ndarray, order: int, center: float = 0.0) -> np.ndarray:
+    """Estimate Lagrange remainder bound: M|x-a|^(n+1)/(n+1)!"""
+    x_arr = np.asarray(x, dtype=float)
+    return np.abs(max_derivative) * np.abs(x_arr - center) ** (order + 1) / math.factorial(order + 1)
+
+
+def symbolic_taylor_expression(expr_str: str, symbol: str = "x", center: float = 0.0, order: int = 6) -> str:
+    """Return symbolic Taylor expression as a string when SymPy is available."""
+    if not HAS_SYMPY:
+        msg = "SymPy is not available."
+        raise RuntimeError(msg)
+    x = sp.symbols(symbol)
+    expr = sp.sympify(expr_str)
+    series = sp.series(expr, x, center, order + 1).removeO()
+    return str(sp.expand(series))

adv_math_engine/tests/__init__.py

@@ -0,0 +1 @@
+"""Test package for adv_math_engine."""

adv_math_engine/tests/coverage_report.txt

@@ -0,0 +1,7 @@
+Coverage command configured:
+
+pytest adv_math_engine/tests --cov=adv_math_engine --cov-report=term-missing
+
+Execution status in this environment:
+- Could not run with coverage because pytest-cov and numerical dependencies are not available in the active interpreter.
+- Network-restricted package installation prevented fetching missing dependencies.

adv_math_engine/tests/test_series_expansion.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from adv_math_engine.series_expansion import (
+    estimate_lagrange_remainder,
+    maclaurin_series,
+    taylor_series,
+)
+from adv_math_engine.utils import validate_tolerance
+
+
+def test_maclaurin_exp_convergence() -> None:
+    x = np.linspace(-1.0, 1.0, 50)
+    approx = maclaurin_series(x, order=12, function_name="exp")
+    actual = np.exp(x)
+    assert validate_tolerance(approx, actual, epsilon=1e-4)
+
+
+def test_taylor_sin_about_nonzero_center() -> None:
+    x = np.array([0.2, 0.3, 0.5])
+    approx = taylor_series(x, order=9, center=0.3, function_name="sin")
+    assert np.allclose(approx, np.sin(x), atol=1e-6)
+
+
+def test_log1p_remainder_bound() -> None:
+    x = 0.2
+    order = 6
+    approx = maclaurin_series(x, order=order, function_name="log1p")
+    actual = np.log1p(x)
+    remainder = estimate_lagrange_remainder(max_derivative=math.factorial(order), x=x, order=order)
+    assert abs(actual - approx) <= remainder + 1e-6
+
+
+def test_arbitrary_function_numeric_derivative() -> None:
+    f = lambda val: np.cos(val) * np.exp(val)
+    x = np.array([0.0, 0.1, 0.2])
+    approx = taylor_series(x, order=8, center=0.0, function=f)
+    assert np.allclose(approx, f(x), atol=5e-3)

adv_math_engine/tests/test_vector_algebra.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from adv_math_engine.vector_algebra import (
+    angle_between,
+    check_linear_independence,
+    cross_product,
+    dot_product,
+    gram_schmidt,
+    vector_projection,
+)
+
+
+def test_dot_product_vectorized() -> None:
+    a = np.array([[1, 2, 3], [4, 5, 6]])
+    b = np.array([[7, 8, 9], [1, 2, 3]])
+    result = dot_product(a, b)
+    assert np.allclose(result, np.array([50, 32]))
+
+
+def test_cross_product_3d() -> None:
+    result = cross_product([1, 0, 0], [0, 1, 0])
+    assert np.allclose(result, np.array([0, 0, 1]))
+
+
+def test_projection_rejects_zero_vector() -> None:
+    with pytest.raises(ValueError):
+        vector_projection([1, 2, 3], [0, 0, 0])
+
+
+def test_angle_between_orthogonal_vectors() -> None:
+    assert np.isclose(angle_between([1, 0], [0, 1]), np.pi / 2)
+
+
+def test_gram_schmidt_orthonormality() -> None:
+    basis = gram_schmidt([[1, 1, 0], [1, 0, 1], [0, 1, 1]])
+    assert np.allclose(basis @ basis.T, np.eye(3), atol=1e-10)
+
+
+def test_linear_independence_rank_check() -> None:
+    independent = check_linear_independence([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
+    dependent = check_linear_independence([[1, 2, 3], [2, 4, 6]])
+    assert independent
+    assert not dependent