API Reference¶

Public API¶

nonlinearequations — SciPy-backed nonlinear equation solvers.

All public symbols are re-exported from nonlinearequations.core so callers can simply write:

from nonlinearequations import polynomial_roots_real, solve_system_fd

This package is a self-contained set of root-finding and nonlinear-system utilities inspired by IMSL Fortran Numerical Library Nonlinear Equations chapter, backed by numpy and scipy.optimize.

class nonlinearequations.RootResult(x, fval, success, message, n_iter=0, n_fev=0)¶

Bases: object

Result of a root-finding or nonlinear-system solve.

Parameters:

x (ndarray)
fval (float)
success (bool)
message (str)
n_iter (int)
n_fev (int)

x¶

Root(s) found. For polynomial functions this array may contain complex values.

Type:: np.ndarray

fval¶

Function value (or residual norm) at the root.

Type:: float

success¶

Whether the solver converged.

Type:: bool

message¶

Human-readable description of the termination condition.

Type:: str

n_iter¶

Number of iterations performed (0 when not tracked).

Type:: int

n_fev¶

Number of function evaluations (0 when not tracked).

Type:: int

nonlinearequations.polynomial_roots_real(coeffs)¶

Find real polynomial roots using the eigenvalue method (IMSL ZPLRC).

Computes all roots of a polynomial whose coefficients are given in ascending degree order: p(x) = coeffs[0] + coeffs[1]*x + ... + coeffs[n]*x^n. The backend converts to numpy’s descending-degree convention internally and uses numpy.roots (companion-matrix eigenvalues).

Parameters:

coeffs (np.ndarray) – 1-D array of polynomial coefficients in ascending degree order, i.e. [a0, a1, ..., an] where p(x) = a0 + a1*x + ... + an*x^n. Must have at least 2 elements (degree >= 1).

Returns:

Result with:

x — complex numpy array of all n roots.
fval — maximum absolute value of |p(root)| over all roots.
success — True when fval is below 1e-6.
message — human-readable status.
n_fev — number of polynomial evaluations (one per root).

Return type:

RootResult

Raises:

TypeError – If coeffs is not a numeric sequence.
ValueError – If coeffs has fewer than 2 elements or the leading coefficient is zero (degenerate polynomial).

nonlinearequations.polynomial_roots_jenkins_traub(coeffs)¶

Find polynomial roots using the Jenkins-Traub method (IMSL ZPORC).

Accepts coefficients in descending degree order (highest-degree coefficient first), matching the IMSL ZPORC convention. The backend is numpy.roots.

Parameters:

coeffs (np.ndarray) – 1-D array of polynomial coefficients in descending degree order, i.e. [an, a_{n-1}, ..., a0] where p(x) = an*x^n + ... + a0. Must have at least 2 elements.

Returns:

Result with x (all roots), fval (max: |p(root)|), success, message, and n_fev.

Return type:

RootResult

Raises:

TypeError – If coeffs is not a numeric sequence.
ValueError – If coeffs has fewer than 2 elements or leading coefficient is zero.

nonlinearequations.polynomial_roots_complex(coeffs)¶

Find roots of a polynomial with complex coefficients (IMSL ZPOCC).

NumPy’s companion-matrix eigenvalue method handles complex coefficients natively. Coefficients are expected in ascending degree order.

Parameters:

coeffs (np.ndarray) – 1-D array of (possibly complex) polynomial coefficients in ascending degree order [a0, a1, ..., an]. Must have at least 2 elements.

Returns:

Result with x (complex roots array), fval: (max |p(root)|), success, message, n_fev.

Return type:

RootResult

Raises:

TypeError – If coeffs is not convertible to a numeric array.
ValueError – If coeffs has fewer than 2 elements or leading coefficient is zero.

nonlinearequations.zero_univariate(f, a, b, x_tol=1e-08, max_fev=500)¶

Find a zero of a univariate function on a bracket (IMSL ZUNI).

Uses scipy.optimize.brentq on the interval [a, b]. The function f must have opposite signs at a and b (i.e. a sign change must exist in the bracket).

Parameters:

f (Callable[[float], float]) – Scalar function whose zero is sought. Must be continuous on [a, b].
a (float) – Left endpoint of the search bracket.
b (float) – Right endpoint of the search bracket.
x_tol (float) – Absolute tolerance on the root. Defaults to 1e-8.
max_fev (int) – Maximum number of function evaluations. Defaults to 500.

Returns:

Result with:

x — length-1 array containing the root.
fval — |f(root)|.
success — True when fval < x_tol.
message — status string.
n_fev — number of function evaluations used.

Return type:

RootResult

Raises:

TypeError – If f is not callable or a, b are not real numbers.
ValueError – If a >= b or f does not change sign on [a, b].

nonlinearequations.zero_brent(f, a, b, x_tol=1e-08, max_fev=500)¶

Find a zero of a real function using Brent’s method (IMSL ZBREN).

Functionally identical to zero_univariate() but named after the IMSL ZBREN routine. Uses scipy.optimize.brentq.

Parameters:

f (Callable[[float], float]) – Scalar function whose zero is sought.
a (float) – Left endpoint of the bracket.
b (float) – Right endpoint of the bracket.
x_tol (float) – Absolute tolerance on the root. Defaults to 1e-8.
max_fev (int) – Maximum number of function evaluations. Defaults to 500.

Returns:

Result with x (length-1 array), fval,: success, message, n_fev.

Return type:

RootResult

Raises:

TypeError – If f is not callable.
ValueError – If a >= b or f does not change sign on [a, b].

nonlinearequations.zeros_real(f, x_guesses, x_tol=1e-08, max_fev=500)¶

Find zeros of a real function from multiple starting points (IMSL ZREAL).

Applies scipy.optimize.fsolve independently from each scalar starting point in x_guesses. Returns one RootResult per starting point.

Parameters:

f (Callable[[float], float]) – Scalar function whose zeros are sought.
x_guesses (np.ndarray) – 1-D array of scalar starting points.
x_tol (float) – Function-value tolerance for convergence. Defaults to 1e-8.
max_fev (int) – Maximum function evaluations per starting point. Defaults to 500.

Returns:

One RootResult per starting point.: Each element’s x is a length-1 array.

Return type:

list[RootResult]

Raises:

TypeError – If f is not callable or x_guesses is not a sequence.
ValueError – If x_guesses is empty.

nonlinearequations.zeros_complex_analytic(f, center, radius, n_points=100)¶

Find zeros of a complex analytic function via contour integration (IMSL ZANLY).

Approximates the zeros inside the circle |z - center| <= radius using an argument-principle approach: samples f on the contour, computes the winding number to estimate the zero count, then refines each zero with scipy.optimize.root using complex arithmetic.

Parameters:

f (Callable[[complex], complex]) – Complex analytic function.
center (complex) – Center of the circular search region.
radius (float) – Radius of the search circle. Must be positive.
n_points (int) – Number of contour sample points. Defaults to 100. Larger values improve zero-count estimation accuracy but increase cost.

Returns:

Result with:

x — complex array of zeros found inside the disk.
fval — maximum |f(zero)| over found zeros.
success — True when at least one zero was found and all residuals are below 1e-10.
message — status string.
n_fev — approximate number of function evaluations.

Return type:

RootResult

Raises:

TypeError – If f is not callable or center is not a number.
ValueError – If radius <= 0 or n_points < 8.

nonlinearequations.solve_system_fd(f, x_guess, x_tol=1e-08, max_fev=1000)¶

Solve a nonlinear system using a finite-difference Jacobian (IMSL NEQNF).

Uses scipy.optimize.fsolve with a finite-difference Jacobian approximation.

Parameters:

f (Callable[[np.ndarray], np.ndarray]) – System function. Accepts a 1-D array of length n and returns a 1-D array of length n.
x_guess (np.ndarray) – Initial guess vector of length n.
x_tol (float) – Absolute tolerance on the solution. Defaults to 1e-8.
max_fev (int) – Maximum function evaluations. Defaults to 1000.

Returns:

Result with:

x — solution vector of length n.
fval — Euclidean norm of f(x).
success — True when fval < x_tol.
message — status string.
n_fev — number of function evaluations.

Return type:

RootResult

Raises:

TypeError – If f is not callable or x_guess is not array-like.
ValueError – If x_guess is not 1-D or is empty.

nonlinearequations.solve_system(f, jac, x_guess, x_tol=1e-08, max_fev=1000)¶

Solve a nonlinear system with an analytic Jacobian (IMSL NEQNJ).

Uses scipy.optimize.fsolve with the user-supplied Jacobian.

Parameters:

f (Callable[[np.ndarray], np.ndarray]) – System function. Accepts a 1-D array of length n and returns a 1-D array of length n.
jac (Callable[[np.ndarray], np.ndarray]) – Jacobian function. Accepts a 1-D array of length n and returns a 2-D array of shape (n, n).
x_guess (np.ndarray) – Initial guess vector of length n.
x_tol (float) – Absolute tolerance on the solution. Defaults to 1e-8.
max_fev (int) – Maximum function evaluations. Defaults to 1000.

Returns:

Result with x, fval, success, message,: n_fev.

Return type:

RootResult

Raises:

TypeError – If f or jac are not callable, or x_guess is not array-like.
ValueError – If x_guess is not 1-D or is empty.

nonlinearequations.solve_system_broyden_fd(f, x_guess, x_tol=1e-08, max_iter=200)¶

Solve a nonlinear system using Broyden’s method with FD Jacobian (IMSL NEQBF).

Uses scipy.optimize.root with method='broyden1'. Broyden’s quasi-Newton method updates the Jacobian approximation iteratively without requiring explicit Jacobian evaluations.

Parameters:

f (Callable[[np.ndarray], np.ndarray]) – System function. Accepts and returns 1-D arrays of the same length n.
x_guess (np.ndarray) – Initial guess vector of length n.
x_tol (float) – Absolute tolerance on the residual norm. Defaults to 1e-8.
max_iter (int) – Maximum number of Broyden iterations. Defaults to 200.

Returns:

Result with x, fval, success, message,: n_fev.

Return type:

RootResult

Raises:

TypeError – If f is not callable or x_guess is not array-like.
ValueError – If x_guess is not 1-D or is empty.

nonlinearequations.solve_system_broyden(f, jac, x_guess, x_tol=1e-08, max_iter=200)¶

Solve a nonlinear system using a factored secant update (IMSL NEQBJ).

Uses scipy.optimize.root with method='hybr' and the supplied analytic Jacobian. The hybr method is a modification of Powell’s hybrid method that uses the Jacobian when available.

Parameters:

f (Callable[[np.ndarray], np.ndarray]) – System function. Accepts and returns 1-D arrays of the same length n.
jac (Callable[[np.ndarray], np.ndarray]) – Jacobian of f. Accepts a 1-D array of length n and returns a 2-D array (n, n).
x_guess (np.ndarray) – Initial guess vector of length n.
x_tol (float) – Absolute tolerance on the residual norm. Defaults to 1e-8.
max_iter (int) – Maximum number of iterations. Defaults to 200.

Returns:

Result with x, fval, success, message,: n_fev.

Return type:

RootResult

Raises:

TypeError – If f or jac are not callable.
ValueError – If x_guess is not 1-D or is empty.

nonlinearequations.launch_documentation(opener=<function open>, package_dir=None)¶

Launch package documentation in a web browser.

The launcher opens local HTML documentation only.

Parameters:

opener (Callable[[str], bool]) – Browser opener function. Defaults to webbrowser.open.
package_dir (Path | None) – Optional package directory override used for tests. Defaults to the directory of this module.

Returns:

The file://... URI opened.

Return type:

str

Raises:

FileNotFoundError – If no local documentation index can be located.