Repository: scipy/scipy
File: scipy/optimize/_zeros_py.py (Python)

Code before:
    evaluations per iteration, and the efficiency index 1.66.
    For higher values of `k`, the efficiency index approaches
    the kth root of ``(3k-2)``, hence ``k=1`` or ``k=2`` are
    usually appropriate.

    As mentioned in the parameter documentation, the computed root ``x0`` will
    satisfy ``np.isclose(x, x0, atol=xtol, rtol=rtol)``, where ``x`` is the
    exact root. In equation form, this terminating condition is ``abs(x - x0)
    <= xtol + rtol * abs(x0)``.

    The default value ``xtol=2e-12`` may lead to surprising behavior if one
    expects `toms748` to always compute roots with relative error near machine
    precision. Care should be taken to select `xtol` for the use case at hand.
    Setting ``xtol=5e-324``, the smallest subnormal number, will ensure the
    highest level of accuracy. Larger values of `xtol` may be useful for saving
    function evaluations when a root is at or near zero in applications where
    the tiny absolute differences available between floating point numbers near
    zero are not meaningful.

    References
    ----------
    .. [APS1995]
       Alefeld, G. E. and Potra, F. A. and Shi, Yixun,
       *Algorithm 748: Enclosing Zeros of Continuous Functions*,
       ACM Trans. Math. Softw. Volume 221(1995)
       doi = {10.1145/210089.210111}

    Examples
    --------
    >>> def f(x):
    ...     return (x**3 - 1)  # only one real root at x = 1

    >>> from scipy import optimize
    >>> root, results = optimize.toms748(f, 0, 2, full_output=True)
    >>> root
    1.0
    >>> results
          converged: True
               flag: converged
     function_calls: 11
         iterations: 5
               root: 1.0
             method: toms748
    """
    if xtol <= 0:
        raise ValueError(f"xtol too small ({xtol:g} <= 0)")
    if rtol < _rtol / 4:
        raise ValueError(f"rtol too small ({rtol:g} < {_rtol/4:g})")
    maxiter = operator.index(maxiter)
    if maxiter < 1:
        raise ValueError("maxiter must be greater than 0")

Review comment (bug):
```suggestion
       :doi:`10.1145/210089.210111`.
```
Oops. This was the third mistake I found in my second pass. I guess I fixed this incorrectly.

Anyway, this is the last one I'm aware of, but it's worth taking one more pass to see if you can find anything else.

Code after:
    evaluations per iteration, and the efficiency index 1.66.
    For higher values of `k`, the efficiency index approaches
    the kth root of ``(3k-2)``, hence ``k=1`` or ``k=2`` are
    usually appropriate.

    As mentioned in the parameter documentation, the computed root ``x0`` will
    satisfy ``np.isclose(x, x0, atol=xtol, rtol=rtol)``, where ``x`` is the
    exact root. In equation form, this terminating condition is ``abs(x - x0)
    <= xtol + rtol * abs(x0)``.

    The default value ``xtol=2e-12`` may lead to surprising behavior if one
    expects `toms748` to always compute roots with relative error near machine
    precision. Care should be taken to select `xtol` for the use case at hand.
    Setting ``xtol=5e-324``, the smallest subnormal number, will ensure the
    highest level of accuracy. Larger values of `xtol` may be useful for saving
    function evaluations when a root is at or near zero in applications where
    the tiny absolute differences available between floating point numbers near
    zero are not meaningful.

    References
    ----------
    .. [APS1995]
       Alefeld, G. E. and Potra, F. A. and Shi, Yixun,
       *Algorithm 748: Enclosing Zeros of Continuous Functions*,
       ACM Trans. Math. Softw. Volume 221(1995)
       https://doi.org/10.1145/210089.210111

    Examples
    --------
    >>> def f(x):
    ...     return (x**3 - 1)  # only one real root at x = 1

    >>> from scipy import optimize
    >>> root, results = optimize.toms748(f, 0, 2, full_output=True)
    >>> root
    1.0
    >>> results
          converged: True
               flag: converged
     function_calls: 11
         iterations: 5
               root: 1.0
             method: toms748
    """
    if xtol <= 0:
        raise ValueError(f"xtol too small ({xtol:g} <= 0)")
    if rtol < _rtol / 4:
        raise ValueError(f"rtol too small ({rtol:g} < {_rtol/4:g})")
    maxiter = operator.index(maxiter)
    if maxiter < 1:
        raise ValueError("maxiter must be greater than 0")