rootfinder 1.0.0

Numerical root-finding made easy — bisection, Newton-Raphson, Brent, and more

🔍 rootfinder

Numerical root-finding made ridiculously easy.

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

pip install rootfinder

---

⚡ Quick Start

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

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

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

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)

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

from rootfinder import brent

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

Fixed-Point Iteration

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

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

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

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:

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 for the step-by-step guide to upload your own version.

---

📄 License

MIT — free for any use.