MathHook Python Bindings

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

pip install mathhook

Requires Python 3.8 or higher.

From Source

# 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

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

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

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

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 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 for guidelines.

License

MathHook is dual-licensed under MIT OR Apache-2.0. See 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