Metadata-Version: 2.4
Name: realmaths
Version: 1.0.1
Summary: Natural mathematical expressions for non-programmers
Home-page: https://github.com/conorzen/realmaths
Author: Conor Reid
Author-email: Your Name <your.email@example.com>
Maintainer-email: Your Name <your.email@example.com>
Project-URL: Homepage, https://github.com/conorzen/realmaths
Project-URL: Documentation, https://github.com/conorzen/realmaths#readme
Project-URL: Repository, https://github.com/conorzen/realmaths.git
Project-URL: Bug Tracker, https://github.com/conorzen/realmaths/issues
Project-URL: Changelog, https://github.com/conorzen/realmaths/blob/main/CHANGELOG.md
Project-URL: Source Code, https://github.com/conorzen/realmaths
Keywords: mathematics,calculator,expressions,education,natural-language,non-programmer,math-notation,student-friendly
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Education
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: Operating System :: OS Independent
Classifier: Natural Language :: English
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Provides-Extra: full
Requires-Dist: realmaths[dev,docs,test]; extra == "full"
Requires-Dist: jupyter>=1.0.0; extra == "full"
Requires-Dist: matplotlib>=3.5.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# RealMaths 🧮

**Natural mathematical expressions for everyone!**

RealMaths lets you write mathematical expressions the way you think about them, without needing to know programming syntax. Perfect for students, teachers, researchers, and anyone who wants to do math without learning to code.

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-stable-brightgreen.svg)](https://github.com/yourusername/easymath)

## ✨ Features

- **🎯 Natural notation**: Write `4n + 1` instead of `4*n + 1`
- **🚫 No coding required**: Perfect for non-programmers
- **🔧 Built-in functions**: SIN, COS, SQRT, LOG, and more (UPPERCASE)
- **💾 Reusable formulas**: Define once, use many times
- **❗ Helpful errors**: Clear messages when something goes wrong
- **📚 Comprehensive**: Works for basic math through advanced calculations
- **🔒 Safe**: Secure evaluation of mathematical expressions
- **🎨 Clear distinction**: UPPERCASE for functions/constants, lowercase for variables

## 🚀 Quick Start

### Installation

```bash
pip install realmaths
```
or for uv

```bash
uv pip install realmaths
```
### Basic Usage

```python
from realmaths import EasyMath

calc = EasyMath()

# Simple calculations
result = calc.eval("4n + 1", n=5)  # Returns 21
print(result)

# Use mathematical functions (UPPERCASE)
area = calc.eval("PI * r^2", r=3)  # Circle area
print(f"Circle area: {area:.2f}")

# Define your own formulas
calc.define("compound_interest", "P(1 + r)^t")
money = calc.calculate("compound_interest", P=1000, r=0.05, t=10)
print(f"Investment value: ${money:.2f}")
```

### Even Quicker

```python
from realmaths import calculate

# One-line calculations
result = calculate("2x^2 + 3x - 1", x=4)  # Returns 43
distance = calculate("SQRT((x2-x1)^2 + (y2-y1)^2)", x1=0, y1=0, x2=3, y2=4)  # Returns 5.0
```

## 📚 Examples

### Basic Mathematics
```python
calc = EasyMath()

# Arithmetic with variables
calc.eval("2x + 3", x=5)           # 13
calc.eval("x^2 + 2x + 1", x=3)     # 16

# Using constants and functions (UPPERCASE)
calc.eval("PI * r^2", r=5)          # ~78.54
calc.eval("SIN(PI/2)")              # 1.0
calc.eval("SQRT(x^2 + y^2)", x=3, y=4)  # 5.0
calc.eval("EXP(x)", x=2)              # ~7.39
```

### Science & Engineering
```python
# Physics: kinetic energy
calc.define("kinetic_energy", "0.5 * m * v^2")
energy = calc.calculate("kinetic_energy", m=10, v=25)  # 3125 J

# Chemistry: ideal gas law
calc.define("ideal_gas", "n * R * T / P")  # V = nRT/P
volume = calc.calculate("ideal_gas", n=2, R=8.314, T=298, P=101325)

# Engineering: stress calculation
calc.define("stress", "F / A")
stress = calc.calculate("stress", F=1000, A=0.01)  # 100,000 Pa
```

### Finance
```python
# Compound interest
calc.define("compound", "P * (1 + r/n)^(n*t)")
amount = calc.calculate("compound", P=1000, r=0.05, n=12, t=5)

# Loan payments
calc.define("payment", "P * (r*(1+r)^n) / ((1+r)^n - 1)")
monthly = calc.calculate("payment", P=200000, r=0.04/12, n=30*12)

# Investment growth
calc.define("cagr", "((FV/PV)^(1/n)) - 1")
growth = calc.calculate("cagr", FV=1500, PV=1000, n=5)
```

### Education
```python
# Quadratic formula solver
from realmaths import solve_quadratic
x1, x2 = solve_quadratic(1, -5, 6)  # Solves x² - 5x + 6 = 0
print(f"Solutions: x₁={x1}, x₂={x2}")  # Solutions: x₁=3.0, x₂=2.0

# Distance formula
calc.define("distance", "SQRT((x2-x1)^2 + (y2-y1)^2)")
dist = calc.calculate("distance", x1=0, y1=0, x2=3, y2=4)  # 5.0

# Trigonometry
calc.eval("SIN(30 * PI/180)")       # sin(30°) = 0.5
calc.eval("COS(PI/3)")              # cos(60°) = 0.5
```

## 🎯 Perfect For

- **👨‍🎓 Students**: Write math naturally without syntax errors
- **👩‍🏫 Teachers**: Create interactive examples and problem solvers
- **🔬 Researchers**: Quick calculations without complex setup
- **📊 Analysts**: Financial and statistical calculations
- **🏗️ Engineers**: Formula-based calculations
- **💡 Anyone**: Who wants to do math without learning programming

## 📖 Documentation

### Capitalization Convention

RealMaths uses a clear capitalization system to distinguish between functions/constants and variables:

- **UPPERCASE**: Functions and constants (`SIN`, `COS`, `PI`, `E`, `SQRT`)
- **lowercase**: Variables (`x`, `y`, `a`, `b`, `c`)

This prevents ambiguity and makes expressions clear:
```python
# Functions and constants (UPPERCASE)
calc.eval("SIN(PI/2)")     # Function call
calc.eval("2PI")           # Constant (2 * π)

# Variables (lowercase)
calc.eval("ax^2 + bx + c", a=1, b=2, c=3, x=2)  # Variables
```

### Supported Operations
| Operation | Syntax | Example |
|-----------|--------|---------|
| Addition | `+` | `x + y` |
| Subtraction | `-` | `x - y` |
| Multiplication | `*` or implicit | `2*x` or `2x` |
| Division | `/` | `x / y` |
| Exponentiation | `^` or `**` | `x^2` or `x**2` |
| Square/Cube | `²` `³` | `x²` or `x³` |

### Built-in Functions (UPPERCASE)
| Category | Functions |
|----------|-----------|
| **Trigonometric** | `SIN`, `COS`, `TAN`, `ASIN`, `ACOS`, `ATAN` |
| **Hyperbolic** | `SINH`, `COSH`, `TANH` |
| **Logarithmic** | `LOG`, `LN`, `LOG10`, `LOG2` |
| **Exponential** | `EXP`, `EXP2` |
| **Power/Root** | `SQRT`, `CBRT`, `POW` |
| **Rounding** | `ABS`, `ROUND`, `FLOOR`, `CEIL` |
| **Comparison** | `MIN`, `MAX` |

### Constants (UPPERCASE)
| Constant | Value | Description |
|----------|-------|-------------|
| `π`, `PI` | 3.14159... | Pi |
| `E` | 2.71828... | Euler's number |
| `TAU` | 6.28318... | Tau (2π) |
| `INF` | ∞ | Infinity |

### Function Management
```python
# Define a reusable function
calc.define("function_name", "mathematical_expression", "optional description")

# Use the function
result = calc.calculate("function_name", variable1=value1, variable2=value2)

# Manage functions
calc.list_functions()                    # Show all defined functions
calc.delete_function("function_name")    # Delete a function
calc.get_function_info("function_name")  # Get function details
```

### Getting Help
```python
calc.help()           # Show comprehensive help
calc.list_functions() # Show your defined functions

# Quick help
from realmath import quick_help
quick_help()
```

## 🔧 Advanced Features

### Error Handling
RealMaths provides helpful error messages:

```python
# Missing variable
calc.eval("x + y", x=1)  # VariableError: Missing variables: y

# Invalid syntax  
calc.eval("2x +")        # ExpressionError: Invalid expression syntax

# Mathematical errors
calc.eval("1/0")         # MathematicalError: Division by zero
```

### Safe Mode
By default, RealMaths runs in safe mode to prevent code injection:

```python
calc = EasyMath(safe_mode=True)   # Default: safe evaluation
calc = EasyMath(safe_mode=False)  # Allow more Python features
```

### Validation
```python
from realmath import is_valid_expression, get_expression_variables

# Check if expression is valid
if is_valid_expression("2x + 3"):
    print("Valid expression!")

# Get variables in expression
vars_list = get_expression_variables("ax^2 + bx + c")
print(vars_list)  # ['a', 'b', 'c', 'x']
```

## 🧪 Examples by Domain

### Physics
```python
calc.define("kinetic_energy", "0.5 * m * v^2")
calc.define("potential_energy", "m * g * h") 
calc.define("wave_speed", "f * λ")
calc.define("ohms_law", "V / R")
```

### Chemistry  
```python
calc.define("ideal_gas", "n * R * T / P")
calc.define("ph_calculation", "-log10(H_concentration)")
calc.define("molarity", "moles / volume_L")
```

### Finance
```python
calc.define("compound_interest", "P * (1 + r/n)^(n*t)")
calc.define("present_value", "FV / (1 + r)^n")
calc.define("loan_payment", "P * (r*(1+r)^n) / ((1+r)^n - 1)")
```

### Statistics
```python
calc.define("mean", "sum_values / n")
calc.define("variance", "sum_squared_deviations / (n-1)")
calc.define("standard_deviation", "sqrt(variance)")
calc.define("z_score", "(x - μ) / σ")
```

### Geometry
```python
calc.define("circle_area", "π * r^2")
calc.define("sphere_volume", "(4/3) * π * r^3") 
calc.define("triangle_area", "0.5 * base * height")
calc.define("distance_2d", "sqrt((x2-x1)^2 + (y2-y1)^2)")
```

## 🛠️ Development

### Running Tests
```bash
pip install pytest
pytest tests/
```

### Development Installation
```bash
git clone https://github.com/yourusername/easymath.git
cd easymath
pip install -e .
```

### Running Examples
```bash
python -m easymath.examples
```

## 🤝 Contributing

We welcome contributions! RealMaths is designed to make math accessible to everyone.

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

See `CONTRIBUTING.md` for detailed guidelines.

## 📋 Requirements

- Python 3.7+
- No external dependencies (uses only Python standard library)

## 📄 License

MIT License - feel free to use in your projects, educational materials, and research.

## 🙏 Acknowledgments

- Inspired by the need to make mathematics accessible to non-programmers
- Built for educators, students, and researchers worldwide
- Special thanks to the Python mathematics community

## 📞 Support

- 📚 [Documentation](https://github.com/yourusername/easymath#readme)
- 🐛 [Issue Tracker](https://github.com/yourusername/easymath/issues)
- 💬 [Discussions](https://github.com/yourusername/easymath/discussions)
- 📧 Email: your.email@example.com

---

**Made with ❤️ for the math community**

*RealMaths: Because mathematics should be about the math, not the syntax.*
