rapid-roots 0.1.0

Numba optimised numerical root-finding solvers for multiple data points

Rapid-Roots

General parallel vectorised root solver using Numba for large data volumes.

Problem

Open source root-finding libraries like Scipy requires users to processes problems sequentially.

# Sequential approach (Slow)
for i in range(1_000_000):
    root = scipy.optimize.brentq(func, a[i], b[i], args=(params[i],))

Solution

rapid-roots processes all problems at once using vectorisation and parallelisation.

# Vectorised rapid-roots approach 
roots, iters, converged = RootSolvers.get_root(
    func, a, b, func_params=func_params, main_solver='brent', use_backup=False
)

Quick Start

pip install rapid-roots

from rapid_roots.solvers import RootSolvers
from numba import njit
import numpy as np

@njit
def f(x, a):
    return x**2 - a

@njit
def f_prime(x, a):
    return 2*x


# Creates function parameter a in the equation.
params = np.full((10000, 1), 4.0)


# Creates a and b bounds for backup bracketed solvers
a = np.zeros(10000)
b = np.full(10000, 10.0)

# Creates x0 initial guess for main Newton solver
x0 = (a + b) / 2

# Vectorised solver implementation solves 10,000 problems at once.
roots, iters, converged = RootSolvers.get_root(
    func=f, a=a,  b=b, x0=x0, func_prime=f_prime, 
    func_params=params, main_solver='newton', 
    use_backup=True 
)

print(f"Solved {converged.sum()} problems") # Solved 10,000 problems
print(f"Mean root: {roots.mean()}")         # Mean root: 2.0

API Reference

RootSolvers.get_root()

Main interface for vectorized root finding.

roots, iterations, converged = RootSolvers.get_root(
    func=func,              # Numba JIT-compiled function
    a=None,                 # Lowerbound brackets for bracketing methods
    b=None,                 # Upperbound brackets for bracketing methods
    x0=None,                # Initial guess for open methods (Newton)
    func_prime=None,        # Derivatives for open method (Newton)
    func_params=None,       # Parameters Array (n_problems, n_params)
    main_solver='brent',    # 'brent', 'bisection', or 'newton'
    tol=1e-12,              # Convergence tolerance
    max_iter=100,           # Maximum iteration
    use_backup=True,        # Enables automatic fallback
    backup_solvers=['newton', 'bisection']  # Fallback methods for unconverged problems
)

Returns:

• roots: ndArray - Found roots for each problem
• iterations: ndArray - Number of iterations used
• converged: ndArray (bool) - Convergence status for each problem

Performance

Samples	Throughput (Solves/sec)
	Newton	Brent	Bisection
10K	22,951	19,632	23,219
100K	231,065	194,212	219,248
1M	2,187,503	1,787,564	1,566,471
10M	15,404,269	9,486,609	4,589,518

Accuracy

Box plot compares the absolute error distributions against Scipy for Brent, Bisection and Newton implementation across different function categories.

Newton shows the lowest median error with occasional ouliers in challenging categories. Brent is slightly higher in median errors with a wider interquantile range. Meanwhile Bisection displays the largest spread and highest typical error.

Results show errors approach machine precision for all methods against scipy.

Installation

Requirements

• Python ≥ 3.8
• Numpy ≥ 1.20.0
• Numba ≥ 0.56.0

Install from PyPI

pip install rapid-roots

Install from source

git clone https://github.com/CianQuezon/rapid-roots.git
cd rapid-roots
pip install -e .

License

This project is licensed under the MIT License - see the LICENSE file for more details.

Acknowledgements

• Built with Numba
• Validated against Scipy reference implementations