triqs.utility.dichotomy.dichotomy

triqs.utility.dichotomy.dichotomy(function, x_init, y_value, precision_on_y, delta_x, max_loops=1000, x_name='', y_name='', verbosity=1)

Find \(x\) such that \(f(x) = y_{\mathrm{value}}\).

Starting from x_init (treated as either the lower or the upper bound depending on the local sign of \(f - y\)), the second bracketing bound is found by stepping by delta_x until the sign of \(f(x) - y_{\mathrm{value}}\) changes. The root is then refined by linear interpolation between the current bounds until abs(f(x) - y_value) < precision_on_y or max_loops is reached.

Parameters:

functioncallable

Real-valued function \(f(x)\) of one real argument.

x_initfloat

Initial guess for \(x\), used as one end of the initial bracket.

y_valuefloat

Target value \(y_{\mathrm{value}}\) to be matched.

precision_on_yfloat

Convergence tolerance: the iteration stops when abs(f(x) - y_value) < precision_on_y.

delta_xfloat

\(\Delta x\) added to or subtracted from x_init until the second bracketing bound is found.

max_loopsint, optional

Maximum number of bracketing + bisection iterations. Default 1000.

x_namestr, optional

Display name for \(x\), used in the textual report. Default "".

y_namestr, optional

Display name for \(y\), used in the textual report. Default "".

verbosityint, optional

Verbosity of the textual report emitted through triqs.utility.mpi. 0 suppresses per-iteration output; >= 1 prints the final answer; >= 3 prints every intermediate \(x\)/\(y\) pair. Default 1.

Returns:

xfloat or None

Solution of \(f(x) = y_{\mathrm{value}}\), or None if the iteration did not converge within max_loops steps.

yfloat or None

Function value \(f(x)\) at the returned solution, or None on failure.

Notes

On failure the function returns (None, None) rather than raising; callers are expected to check the result.

The progress messages are printed via triqs.utility.mpi.report(), which suppresses output on non-master MPI ranks.