Documentation Update and optimization of some basic algorithms.

.gitignore

@@ -1,110 +1,36 @@
-# Byte-compiled / optimized / DLL files
+```
+# Compiled Python files
+*.pyc
 __pycache__/
-*.py[cod]
-*$py.class
 
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a Python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
+# Dependencies
+.venv/
+venv/
 pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-.hypothesis/
-.pytest_cache/
-
-# Translations
-*.mo
-*.pot
+pipenv.lock
 
-# Django stuff:
+# Logs and temp files
 *.log
-local_settings.py
-db.sqlite3
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-target/
+*.tmp
+*.swp
 
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
+# Environment
 .env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
+.env.local
+*.env.*
 
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
+# Coverage reports
+.coverage
+htmlcov/
+coverage/
 
-# mypy
-.mypy_cache/
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
 
+# OS generated files
 .DS_Store
-.idea
-.try
-.vscode/
-.vs/
+Thumbs.db
+```

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"))