Metadata-Version: 2.4
Name: mathhook
Version: 0.1.4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Summary: High-performance educational computer algebra system
Keywords: mathematics,algebra,symbolic,education,calculus
Home-Page: https://github.com/AhmedMashour/mathhook
Author-email: Ahmed Mashhour <mpghknown@gmail.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/AhmedMashour/mathhook
Project-URL: Repository, https://github.com/AhmedMashour/mathhook
Project-URL: Documentation, https://docs.rs/mathhook
Project-URL: Bug Tracker, https://github.com/AhmedMashour/mathhook/issues

# MathHook Python Bindings

[![PyPI](https://img.shields.io/pypi/v/mathhook.svg)](https://pypi.org/project/mathhook/)
[![Python Versions](https://img.shields.io/pypi/pyversions/mathhook.svg)](https://pypi.org/project/mathhook/)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](../../LICENSE)

High-performance computer algebra system for Python, powered by Rust.

## Features

- **High Performance**: Rust-powered core targeting 10-100x speedup over SymPy
- **Symbolic Mathematics**: Expressions, algebra, calculus, and matrix operations
- **Multiple Input/Output Formats**: Parse and emit LaTeX, Wolfram Language, and standard notation
- **Educational**: Step-by-step explanations for simplification and derivatives
- **Memory Efficient**: Rust-powered core with minimal Python overhead

## Installation

```bash
pip install mathhook
```

Requires Python 3.8 or higher.

### From Source

```bash
# Install maturin
pip install maturin

# Clone and build
git clone https://github.com/AhmedMashour/mathhook.git
cd mathhook/crates/mathhook-python
maturin develop --release
```

## Quick Start

```python
from mathhook import Expression, symbol

# Create symbols
x = symbol('x')
y = symbol('y')

# Build expressions
expr = x**2 + 2*x + 1

# Simplify
simplified = expr.simplify()
print(simplified)  # x^2 + 2*x + 1

# Solve equations
from mathhook import solve
solutions = solve(x**2 - 4, x)
print(solutions)  # [2, -2]

# Calculus
derivative = expr.diff(x)
print(derivative)  # 2*x + 2

integral = expr.integrate(x)
print(integral)  # x^3/3 + x^2 + x
```

## Expression Creation

### Basic Expressions

```python
from mathhook import Expression, symbol

# Integers
num = Expression.integer(42)

# Floats
pi_approx = Expression.float(3.14159)

# Rationals (exact fractions)
half = Expression.rational(1, 2)

# Symbols
x = symbol('x')
y = symbol('y')

# Arithmetic operations
sum_expr = x + y
product = x * y
power = x ** 2
quotient = x / y
```

### Operator Overloading

Python bindings support natural mathematical notation:

```python
from mathhook import symbol

x = symbol('x')
y = symbol('y')

# All standard operators work
expr = (x + y) * (x - y)  # Difference of squares
expr = x**2 + 2*x + 1      # Polynomial
expr = (x + 1) / (x - 1)   # Rational function
```

### Functions

```python
from mathhook import sin, cos, tan, exp, log, sqrt

x = symbol('x')

# Trigonometric functions
trig = sin(x)**2 + cos(x)**2  # = 1

# Exponential and logarithmic
exponential = exp(x)
natural_log = log(x)
log_base_10 = log(x, 10)

# Square root
root = sqrt(x**2 + 1)
```

### Constants

```python
from mathhook import pi, e, I, oo

# Mathematical constants
circle_area = pi * r**2
euler_identity = exp(I * pi) + 1  # = 0
limit_expr = 1 / oo  # = 0
```

## Algebraic Operations

### Simplification

```python
from mathhook import symbol, sin, cos

x = symbol('x')

# Algebraic simplification
expr = x + x + x
print(expr.simplify())  # 3*x

# Trigonometric identities
expr = sin(x)**2 + cos(x)**2
print(expr.simplify())  # 1

# Rational expressions
expr = (x**2 - 1) / (x - 1)
print(expr.simplify())  # x + 1
```

### Expansion

```python
from mathhook import symbol

x = symbol('x')
y = symbol('y')

# Expand products
expr = (x + 1) * (x + 2)
print(expr.expand())  # x^2 + 3*x + 2

# Expand powers
expr = (x + y)**2
print(expr.expand())  # x^2 + 2*x*y + y^2
```

### Factorization

```python
from mathhook import symbol

x = symbol('x')

# Factor polynomials
expr = x**2 - 1
print(expr.factor())  # (x + 1)(x - 1)

expr = x**2 + 5*x + 6
print(expr.factor())  # (x + 2)(x + 3)
```

### Substitution

```python
from mathhook import symbol

x = symbol('x')
y = symbol('y')

expr = x**2 + 2*x + 1

# Substitute value
result = expr.subs(x, 3)
print(result)  # 16

# Substitute expression
result = expr.subs(x, y + 1)
print(result)  # (y + 1)^2 + 2*(y + 1) + 1
```

## Calculus

### Derivatives

```python
from mathhook import symbol, sin, cos, exp

x = symbol('x')

# First derivative
expr = x**3
print(expr.diff(x))  # 3*x^2

# Higher-order derivatives
print(expr.diff(x, 2))  # 6*x
print(expr.diff(x, 3))  # 6

# Chain rule
expr = sin(x**2)
print(expr.diff(x))  # 2*x*cos(x^2)

# Product rule
expr = x * exp(x)
print(expr.diff(x))  # x*exp(x) + exp(x)
```

### Integrals

```python
from mathhook import symbol, sin, cos

x = symbol('x')

# Indefinite integrals
expr = x**2
print(expr.integrate(x))  # x^3/3

# Definite integrals
expr = x**2
result = expr.integrate((x, 0, 1))
print(result)  # 1/3

# Trigonometric integrals
expr = sin(x)
print(expr.integrate(x))  # -cos(x)
```

### Limits

```python
from mathhook import symbol, sin, oo

x = symbol('x')

# Finite limits
expr = sin(x) / x
limit = expr.limit(x, 0)
print(limit)  # 1

# Infinite limits
expr = 1 / x
print(expr.limit(x, oo))  # 0
```

### Series Expansions

```python
from mathhook import symbol, sin, cos, exp

x = symbol('x')

# Taylor series
series = sin(x).series(x, 0, 6)
print(series)  # x - x^3/6 + x^5/120 + O(x^6)

# Around different points
series = exp(x).series(x, 1, 4)
print(series)  # e + e*(x-1) + e*(x-1)^2/2 + ...
```

## Equation Solving

### Algebraic Equations

```python
from mathhook import symbol, solve

x = symbol('x')

# Linear equations
solutions = solve(2*x + 3 - 7, x)
print(solutions)  # [2]

# Quadratic equations
solutions = solve(x**2 - 5*x + 6, x)
print(solutions)  # [2, 3]

# With complex roots
solutions = solve(x**2 + 1, x)
print(solutions)  # [I, -I]
```

### Systems of Equations

```python
from mathhook import symbol, solve

x = symbol('x')
y = symbol('y')

# Solve system
solutions = solve([
    x + y - 5,
    x - y - 1
], [x, y])
print(solutions)  # {x: 3, y: 2}
```

### Differential Equations

```python
from mathhook import symbol, Function, dsolve

x = symbol('x')
f = Function('f')

# Solve dy/dx = y
solution = dsolve(f(x).diff(x) - f(x), f(x))
print(solution)  # f(x) = C1*exp(x)
```

## Matrix Operations

### Creating Matrices

```python
from mathhook import Matrix

# From lists
A = Matrix([[1, 2], [3, 4]])

# Identity matrix
I = Matrix.eye(3)

# Zero matrix
Z = Matrix.zeros(2, 3)

# Diagonal matrix
D = Matrix.diag([1, 2, 3])
```

### Matrix Operations

```python
from mathhook import Matrix

A = Matrix([[1, 2], [3, 4]])
B = Matrix([[5, 6], [7, 8]])

# Addition
C = A + B

# Multiplication
C = A * B

# Transpose
AT = A.T

# Determinant
det = A.det()
print(det)  # -2

# Inverse
A_inv = A.inv()

# Trace
tr = A.trace()
print(tr)  # 5
```

### Matrix Decomposition

```python
from mathhook import Matrix

A = Matrix([[4, 2], [2, 3]])

# Eigenvalues and eigenvectors
eigenvals = A.eigenvals()
eigenvects = A.eigenvects()

# LU decomposition
L, U = A.LUdecomposition()

# QR decomposition
Q, R = A.QRdecomposition()

# Cholesky decomposition (for positive definite)
L = A.cholesky()
```

## Parsing

### Multi-Format Parser

```python
from mathhook import parse

# Standard notation
expr = parse("2*x + sin(y)")

# LaTeX
expr = parse(r"\frac{x}{2} + y^2")
expr = parse(r"\sin(x) + \cos(y)")

# Wolfram Language
expr = parse("Sin[x] + Cos[y]")
```

### Format Conversion

```python
from mathhook import symbol

x = symbol('x')
expr = x**2 / 2

# Convert to LaTeX
latex = expr.to_latex()
print(latex)  # \frac{x^{2}}{2}

# Convert to Wolfram
wolfram = expr.to_wolfram()
print(wolfram)  # Divide[Power[x, 2], 2]

# String representation
print(str(expr))  # x^2/2
```

## Educational Features

### Step-by-Step Solutions

```python
from mathhook import symbol

x = symbol('x')
expr = (x + 1) * (x - 1)

# Get explanation
steps = expr.expand().steps()

for i, step in enumerate(steps):
    print(f"Step {i+1}: {step.title}")
    print(f"  {step.description}")
    print(f"  Result: {step.expression}")
    print()
```

### Derivative Explanation

```python
from mathhook import symbol, sin

x = symbol('x')
expr = sin(x**2)

# Explain derivative calculation
explanation = expr.diff(x).explain()
print(explanation)
```

## Performance Optimization

### Configuration

```python
from mathhook import configure

# Optimize for Python (default)
configure(binding='python')

# Custom configuration
configure(
    simd_enabled=True,
    cache_size=50000,
    parallel_enabled=False
)
```

### Bulk Operations

```python
from mathhook import simplify_many

# Simplify many expressions at once (uses parallelization)
expressions = [x**2 + 2*x + 1 for _ in range(1000)]
simplified = simplify_many(expressions)
```

## Type Hints

MathHook provides full type hints for excellent IDE support:

```python
from mathhook import Expression, Symbol
from typing import List, Union

def quadratic(a: Union[int, float], b: Union[int, float],
              c: Union[int, float], x: Symbol) -> Expression:
    """Create a quadratic expression."""
    return a*x**2 + b*x + c

def roots(expr: Expression, var: Symbol) -> List[Expression]:
    """Find roots of an expression."""
    from mathhook import solve
    return solve(expr, var)
```

## Examples

### Quadratic Formula

```python
from mathhook import symbol, solve, sqrt

x = symbol('x')
a, b, c = 1, -5, 6

equation = a*x**2 + b*x + c
solutions = solve(equation, x)
print(f"Solutions: {solutions}")  # [2, 3]
```

### Taylor Series Approximation

```python
from mathhook import symbol, sin, cos

x = symbol('x')

# Approximate sin(x) with Taylor series
sin_approx = sin(x).series(x, 0, 10)
print(sin_approx)

# Compare with exact value
print(f"sin(0.1) exact: {sin(0.1)}")
print(f"sin(0.1) approx: {sin_approx.subs(x, 0.1)}")
```

### Matrix Eigenvalues

```python
from mathhook import Matrix, symbol

# Symbolic matrix
t = symbol('t')
A = Matrix([
    [t, 1],
    [1, t]
])

# Find eigenvalues
eigenvals = A.eigenvals()
print(f"Eigenvalues: {eigenvals}")  # {t-1: 1, t+1: 1}
```

## Performance Comparison

Benchmark results vs SymPy (lower is better):

| Operation | MathHook | SymPy | Speedup |
|-----------|----------|-------|---------|
| Expression Creation | 0.1μs | 2.0μs | 20x |
| Simplification | 1.0μs | 50μs | 50x |
| Differentiation | 2.0μs | 100μs | 50x |
| Matrix Multiplication | 10μs | 500μs | 50x |

*Benchmarks on Apple M1, Python 3.11*

## Actual API Reference

For the complete API documentation, see the **[Python Bindings Guide](../../docs/src/bindings/python.md)** in the mdbook.

### Quick Reference

The main classes exported:

| Class | Purpose |
|-------|---------|
| `Expression` | Core symbolic expression with algebra, calculus, matrices |
| `Symbol` | Create symbolic variables via `symbol('x')` |
| `ODESolver` | Numerical ODE methods (Euler, RK4, RKF45) |
| `PDESolver` | PDE solvers (heat, wave, Laplace) |
| `GroebnerBasis` | Gröbner basis computation |
| `EvalContext` | Controlled evaluation context |

## Common Issues

### Import Errors

If you see `ImportError: No module named 'mathhook'`:
- Ensure mathhook is installed: `pip install mathhook`
- Check Python version: `python --version` (must be 3.8+)

### Performance Issues

For better performance:
- Use `configure()` to enable SIMD operations
- Process expressions in bulk when possible
- Cache frequently used expressions

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

## License

MathHook is dual-licensed under MIT OR Apache-2.0. See [LICENSE](../../LICENSE) for details.

## Links

- **PyPI**: https://pypi.org/project/mathhook/
- **GitHub**: https://github.com/AhmedMashour/mathhook
- **Documentation**: https://mathhook.readthedocs.io
- **Issue Tracker**: https://github.com/AhmedMashour/mathhook/issues

