archimedes.root¶

archimedes.root(func: Callable, x0: ArrayLike, args: Sequence[Any] = (), static_argnames: str | Sequence[str] | None = None, method: str = 'newton', tol: float | None = None, **options) → ArrayLike¶

Find a root of a nonlinear function.

Solves the equation f(x) = 0 for x, where f is a vector function of vector x.

Parameters:

func (callable) – The function whose root to find, with signature func(x, *args). The function should return an array of the same shape as x`. For systems of equations, func should return a vector of residuals.
x0 (array_like) – Initial guess for the solution. The shape of this array determines the dimensionality of the problem to be solved.
args (tuple, optional) – Extra arguments passed to the function.
static_argnames (tuple of str, optional) – Names of arguments that should be treated as static (non-symbolic) parameters. Static arguments are not differentiated through and the solver will be recompiled when their values change.
method (str, default="newton") –
The root-finding method to use. Options are:
- "newton" : Newton’s method (default), best for general problems
- "fast_newton" : Simple Newton iterations with no line search
- "kinsol" : KINSOL solver from SUNDIALS, robust for large systems
tol (float, optional) – Absolute for convergence. If None, the default tolerance for the chosen method will be used.
**options (dict, optional) –
Common additional options specific to the chosen method:

For "newton" and "fast_newton":
- max_iter : int, maximum iterations (default: 100)
For "kinsol":
- max_iter : int, maximum iterations
- strategy : str, globalization strategy ("none", "linesearch", "picard", "fp")

Returns:

x – The solution found, with the same shape as the initial guess x0. If the algorithm fails to converge, the best estimate is returned.

Return type:

array_like

Notes

This function leverages Archimedes’ automatic differentiation to compute the Jacobian matrix required by most root-finding methods. For repeated solving with different parameters, use implicit() directly to create a reusable solver function.

Examples

>>> import numpy as np
>>> import archimedes as arc
>>>
>>> # Simple scalar equation: x^2 = 2
>>> def f1(x):
...     return x**2 - 2
>>>
>>> sol = arc.root(f1, x0=1.0)
>>> print(f"Solution: {sol:.10f}")  # Should be close to sqrt(2)
Solution: 1.4142135624
>>>
>>> # System of nonlinear equations
>>> def f2(x):
...     return np.array([
...         x[0] + 0.5 * (x[0] - x[1])**3 - 1.0,
...         0.5 * (x[1] - x[0])**3 + x[1],
...     ], like=x)
>>>
>>> sol = arc.root(f2, x0=np.array([0.0, 0.0]))
>>> print(sol)  # Should be close to [0.8411639, 0.1588361]
[0.8411639 0.1588361]
>>>
>>> # Using a different method with options
>>> def f3(x):
...     return np.exp(x) - 2
>>>
>>> sol = arc.root(f3, x0=1.0, method='kinsol', max_iter=20, tol=1e-10)
>>> print(f"Solution: {sol:.10f}")  # Should be close to ln(2)
Solution: 0.6931471806
>>>
>>> # With additional parameters
>>> def f4(x, a, b):
...     return x**2 - a*x + b
>>>
>>> sol = arc.root(f4, x0=2.5, args=(3, 2))
>>> print(f"Solution: {sol:.10f}")  # Should be close to 2
Solution: 2.0000000000