Metadata-Version: 2.4
Name: rootfinder
Version: 1.0.0
Summary: Numerical root-finding made easy — bisection, Newton-Raphson, Brent, and more
Author: rootfinder contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/rootfinder
Project-URL: Documentation, https://github.com/yourusername/rootfinder#readme
Project-URL: Bug Reports, https://github.com/yourusername/rootfinder/issues
Project-URL: Source Code, https://github.com/yourusername/rootfinder
Keywords: numerical methods,root finding,bisection,newton raphson,regula falsi,secant method,brent,numerical analysis,mathematics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Mathematics
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.4
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# 🔍 rootfinder

**Numerical root-finding made ridiculously easy.**

Solve `f(x) = 0` with beautiful graphs and tables — one import, one line.

```bash
pip install rootfinder
```

---

## ⚡ Quick Start

```python
from rootfinder import solve, bisection, newton, solve_all, plot_comparison

f = lambda x: x**3 - x - 2

# Auto-pick the best method
r = solve(f, a=1, b=2)
print(r.root)      # 1.5213797068045675
print(r)           # full result summary

# See the iteration table
r.table()

# Plot convergence graph
r.plot()
```

---

## 📦 Installation

```bash
pip install rootfinder
```

Requires Python ≥ 3.8. Dependencies (auto-installed): `numpy`, `matplotlib`.

---

## 🛠️ All Methods

| Method | Function | Best For |
|---|---|---|
| **Bisection** | `bisection(f, a, b)` | Guaranteed convergence, simple |
| **Newton-Raphson** | `newton(f, x0)` | Fast (quadratic), needs derivative |
| **Regula Falsi** | `regula_falsi(f, a, b)` | Bracketed, often faster than bisection |
| **Secant** | `secant(f, x0, x1)` | Newton-like, no derivative needed |
| **Brent** | `brent(f, a, b)` | Gold standard — fast + guaranteed |
| **Ridder** | `ridder(f, a, b)` | Quadratic + bracketed |
| **Fixed-Point** | `fixed_point(g, x0)` | For equations in x = g(x) form |
| **Steffensen** | `steffensen(f, x0)` | Fixed-point + acceleration |
| **Müller** | `muller(f, x0, x1, x2)` | Finds complex roots too! |

---

## 📖 Usage Examples

### Bisection — guaranteed to converge

```python
from rootfinder import bisection

f = lambda x: x**2 - 2          # find √2

r = bisection(f, 1, 2)
print(r.root)                    # 1.4142135623730951
r.table()                        # print iteration table
r.plot()                         # plot convergence
```

### Newton-Raphson — fastest convergence

```python
from rootfinder import newton
import math

# With explicit derivative (faster)
r = newton(math.sin, x0=3.0, df=math.cos)

# Without derivative (auto-computed numerically)
r = newton(lambda x: x**3 - 2, x0=1.0)

print(r)
```

### Regula Falsi (False Position)

```python
from rootfinder import regula_falsi

f = lambda x: x**3 - x - 2
r = regula_falsi(f, 1, 2)
r.table()
```

### Brent's Method — recommended default

```python
from rootfinder import brent

f = lambda x: math.exp(-x) - x
r = brent(f, 0, 1)
print(r.summary())
```

### Fixed-Point Iteration

```python
from rootfinder import fixed_point
import math

# x^2 - x - 2 = 0  →  rewrite as  x = sqrt(x + 2)
r = fixed_point(lambda x: math.sqrt(x + 2), x0=1.5)
print(r.root)   # 2.0
```

### Müller's Method — finds complex roots

```python
from rootfinder import muller

# x^2 + 1 = 0  →  complex roots ±i
r = muller(lambda x: x**2 + 1, x0=-1, x1=0, x2=1)
```

### Compare ALL methods at once

```python
from rootfinder import solve_all, plot_comparison

f = lambda x: x**3 - x - 2

results = solve_all(f, a=1, b=2)   # runs all methods, prints comparison table
plot_comparison(results)            # overlay convergence graph
```

Output:
```
════════════════════════════════════════════════════════════════════════
Method           Root               f(root)   Iters   Status
════════════════════════════════════════════════════════════════════════
Bisection        1.5213797068046   1.776e-15     36   ✓
Regula Falsi     1.52137970680457  2.220e-16     12   ✓
Brent            1.5213797068046   0.000e+00      8   ✓
Ridder           1.5213797068046   4.441e-16      9   ✓
Newton           1.5213797068046   0.000e+00      6   ✓
Secant           1.5213797068046   2.220e-16      8   ✓
════════════════════════════════════════════════════════════════════════
```

---

## 📊 Visualization

```python
from rootfinder import plot_function, plot_convergence, plot_comparison, plot_iterations

f = lambda x: x**3 - x - 2
r = bisection(f, 1, 2)

# 1. Plot the function with root marked
plot_function(f, a=0, b=3, root=r.root)

# 2. Plot how error decreased across iterations
plot_convergence(r)

# 3. Show iteration steps on the function
plot_iterations(f, r, a=1, b=2)

# 4. Compare multiple methods
from rootfinder import solve_all
results = solve_all(f, 1, 2)
plot_comparison(results)
```

---

## 📋 RootResult Object

Every method returns a `RootResult` with:

```python
r = bisection(f, 1, 2)

r.root          # float: the root
r.f_root        # float: f(root), should be ~0
r.converged     # bool: did it converge?
r.iterations    # int: number of iterations
r.error         # float: final error estimate
r.method        # str: method name
r.steps         # list of IterationStep objects
r.xs            # list of x values per iteration
r.errors        # list of errors per iteration

r.table()       # print iteration table
r.plot()        # plot convergence
r.summary()     # one-line string summary

float(r)        # use root as a plain float
```

---

## 🚀 Deploying / Publishing to PyPI

See [`PUBLISH.md`](PUBLISH.md) for the step-by-step guide to upload your own version.

---

## 📄 License

MIT — free for any use.
