UniversalMath 🧮

The Ultimate Unified Python Mathematics Module

Version 0.1.1 - Complete coverage with lazy loading

---

🎯 What is UniversalMath?

UniversalMath is a comprehensive, unified mathematics module that combines ALL functions from Python's mathematical ecosystem into a single, easy-to-use package. It features:

• ✅ 3,600+ mathematical functions from one import
• ✅ 100% coverage of math, cmath, statistics, decimal, fractions, numpy, scipy, sympy, pandas
• ✅ 75+ custom utility functions for everyday math
• ✅ Lazy loading - modules imported only when needed
• ✅ Legacy support - works even if some modules aren't installed
• ✅ Zero configuration - just import and use

---

🚀 Quick Start

import universalmath as um

# Standard math - works immediately
um.sqrt(16)                    # 4.0
um.sin(um.pi/2)                # 1.0
um.factorial(5)                # 120

# Statistics
um.mean([1, 2, 3, 4, 5])       # 3.0
um.stdev([1, 2, 3])            # 1.0

# Custom utilities
um.is_prime(17)                # True
um.fibonacci(10)               # [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
um.lerp(0, 100, 0.5)           # 50.0

# NumPy (auto-loaded when first used)
um.np_array([1, 2, 3])         # array([1, 2, 3])
um.matrix([[1,2],[3,4]])       # 2x2 matrix

# SciPy (auto-loaded when first used)
um.sp_stats_norm.pdf(0)        # 0.3989422804014327
um.sp_optimize_minimize(...)   # Optimization

# Symbolic math (auto-loaded when first used)
x = um.sym_Symbol('x')
um.sym_diff(x**2, x)           # 2*x

---

📦 Installation

# Basic installation (standard library only)
pip install -e .

# Full installation (with all optional packages)
pip install -e ".[full]"

# Install specific extras
pip install -e ".[numpy]"      # Just NumPy
pip install -e ".[scipy]"      # NumPy + SciPy
pip install -e ".[symbolic]"   # SymPy for symbolic math

---

⚡ Key Features

1. Lazy Loading

Modules are imported only when you use them, saving memory and import time:

import universalmath as um  # Instant, no heavy imports

um.sqrt(16)           # Uses built-in math (already loaded)
um.np_array([1,2,3])  # NOW numpy gets imported
um.sym_Symbol('x')    # NOW sympy gets imported

2. 100% Coverage

Every single function from each module is available:

Core Modules (188 functions):

• ✅ math (52 functions) - Real number mathematics
• ✅ cmath (30 functions) - Complex number mathematics
• ✅ statistics (37 functions) - Statistical analysis
• ✅ decimal (3 items) - High-precision arithmetic (Decimal class + rounding modes)
• ✅ fractions (1 items) - Rational number arithmetic (Fraction class)
• ✅ random (32 functions) - Random number generation (includes classes and constants)
• ✅ builtins (5 functions) - Python built-ins (abs, round, min, max, sum, pow, len, sorted, reversed)

NumPy (581 functions):

• ✅ numpy (466 functions) - Array operations & numerical computing
• ✅ numpy.linalg (33 functions) - Linear algebra
• ✅ numpy.random (63 functions) - Random number generation
• ✅ numpy.fft (19 functions) - Fast Fourier transforms

SciPy (1,179 functions):

• ✅ scipy.stats (302 functions) - Statistical distributions & tests
• ✅ scipy.linalg (100 functions) - Advanced linear algebra
• ✅ scipy.optimize (72 functions) - Optimization & root finding
• ✅ scipy.integrate (34 functions) - Numerical integration & ODEs
• ✅ scipy.interpolate (58 functions) - Data interpolation
• ✅ scipy.signal (158 functions) - Signal processing
• ✅ scipy.fft (42 functions) - FFT operations
• ✅ scipy.special (363 functions) - Special mathematical functions
• ✅ scipy.sparse (50 functions) - Sparse matrix operations

Symbolic & Data (977 functions):

• ✅ sympy (875 functions) - Symbolic mathematics & computer algebra
• ✅ pandas (102 functions) - Data analysis & manipulation

PyPyNum (415 functions):

• ✅ pypynum (413 functions) – Pure Python scientific computing
• ✅ pypynum.arrays (21 functions) – Array utilities
• ✅ pypynum.equations (2 functions) – Equation solvers
• ✅ pypynum.graphs (6 functions) – Graph-related utilities
• ✅ pypynum.maths (88 functions) – Core mathematical functions
• ✅ pypynum.matrices (21 functions) – Matrix operations
• ✅ pypynum.multiprec (26 functions) – Multi-precision arithmetic
• ✅ pypynum.random (12 functions) – Random utilities
• ✅ pypynum.regs (4 functions) – Regression utilities
• ✅ pypynum.stattest (6 functions) – Statistical tests
• ✅ pypynum.symbols (1 function) – Symbol definitions
• ✅ pypynum.tensors (5 functions) – Tensor operations
• ✅ pypynum.tools (31 functions) – Helper and utility tools
• ✅ pypynum.vectors (3 functions) – Vector operations

Custom Utilities (78 functions):

• ✅ universalmath.utils (77 functions) - Number theory, geometry, finance, interpolation, vectors, CLI tools, etc.
• ✅ universalmath.cli (1 function) - Command-line interface

🎯 GRAND TOTAL: 3,614 functions from one import!

3. 75+ Custom Utilities

Practical functions you actually need:

# Number theory
um.is_prime(17)                          # True
um.primes_up_to(50)                      # [2, 3, 5, 7, 11, ...]
um.prime_factors(60)                     # [2, 2, 3, 5]
um.totient(9)                            # Euler's totient: 6
um.chinese_remainder_theorem([2,3], [5,7])  # CRT solver

# Interpolation
um.lerp(0, 100, 0.5)                     # 50.0
um.remap(5, 0, 10, 0, 100)               # 50.0
um.smoothstep(0, 1, 0.5)                 # Smooth easing

# Finance
um.compound_interest(1000, 0.05, 10)     # $1628.89
um.annuity_payment(10000, 0.05/12, 60)   # Monthly payment

# Numerical methods
um.newton_raphson(lambda x: x**2 - 2, lambda x: 2*x, 1)  # Find √2
um.numerical_integral_simpson(lambda x: x**2, 0, 1)      # ∫x²dx

# Geometry
um.circle_area(5)                        # 78.54
um.sphere_volume(3)                      # 113.10
um.polygon_area([(0,0), (1,0), (1,1)])  # 0.5

# Vectors
um.dot_product([1,2,3], [4,5,6])        # 32
um.cross_product_3d([1,0,0], [0,1,0])   # (0, 0, 1)
um.angle_between_vectors([1,0], [0,1])  # 1.5708 (π/2)

# Unit conversions
um.celsius_to_fahrenheit(100)            # 212.0
um.degrees_to_radians_precise(45, 30, 0) # Degrees/minutes/seconds

4. Legacy Support

Works on any system, even with missing packages:

# On a minimal system without NumPy
import universalmath as um

um.sqrt(16)        # ✅ Works (uses built-in math)
um.mean([1,2,3])   # ✅ Works (uses built-in statistics)
um.np_array([1,2]) # ❌ Raises helpful error: "NumPy not installed"

5. Smart Naming

Clear prefixes prevent conflicts:

Module	Prefix	Example
math	none	sqrt, sin
cmath	c	csqrt, csin
numpy	np_	np_array, np_mean
scipy.stats	sp_stats_	sp_stats_norm
scipy.optimize	sp_optimize_	sp_optimize_minimize
sympy	sym_	sym_diff, sym_integrate
pandas	pd_	pd_DataFrame

---

📊 Comparison

Feature	UniversalMath	Standard Approach
Import complexity	import universalmath as um	Multiple imports
Functions available	3,600+	Need to remember which module
Memory usage	Lazy loaded	All upfront
Coverage	100% of all modules	Manual selection
Utilities	75+ included	Write your own
Legacy support	✅ Graceful degradation	❌ Crashes if missing

---

📄 License

MIT License - See LICENSE file for details

---

🙏 Acknowledgments

UniversalMath builds upon:

• Python Standard Library (math, cmath, statistics, decimal, fractions, random)
• NumPy
• SciPy
• SymPy
• Pandas
• PyPyNum

---

Made with ❤️ for mathematicians, scientists, engineers, and developers who want math to just work™