Skip to main content
`Ctrl`+`K`
scipy.optimize.

# root_scalar

scipy.optimize.root_scalar(f, args=(), method=None, bracket=None, fprime=None, fprime2=None, x0=None, x1=None, xtol=None, rtol=None, maxiter=None, options=None)

  Find a root of a scalar function.

  Parameters:
    f callable

      A function to find a root of.

      Suppose the callable has signature `f0(x, *my_args, **my_kwargs)`, where `my_args` and `my_kwargs` are required positional and keyword arguments. Rather than passing `f0` as the callable, wrap it to accept only `x`; e.g., pass `fun=lambda x: f0(x, *my_args, **my_kwargs)` as the callable, where `my_args` (tuple) and `my_kwargs` (dict) have been gathered before invoking this function.

    args tuple, optional

      Extra arguments passed to the objective function and its derivative(s).

    method str, optional

      Type of solver. Should be one of

      - ‘bisect’ (see here)

      - ‘brentq’ (see here)

      - ‘brenth’ (see here)

      - ‘ridder’ (see here)

      - ‘toms748’ (see here)

      - ‘newton’ (see here)

      - ‘secant’ (see here)

      - ‘halley’ (see here)

    bracket: A sequence of 2 floats, optional

      An interval bracketing a root. `f(x, *args)` must have different signs at the two endpoints.

    x0 float, optional

      Initial guess.

    x1 float, optional

      A second guess.

    fprime bool or callable, optional

      If fprime is a boolean and is True, f is assumed to return the value of the objective function and of the derivative. fprime can also be a callable returning the derivative of f. In this case, it must accept the same arguments as f.

    fprime2 bool or callable, optional

      If fprime2 is a boolean and is True, f is assumed to return the value of the objective function and of the first and second derivatives. fprime2 can also be a callable returning the second derivative of f. In this case, it must accept the same arguments as f.

    xtol float, optional

      Tolerance (absolute) for termination.

    rtol float, optional

      Tolerance (relative) for termination.

    maxiter int, optional

      Maximum number of iterations.

    options dict, optional

      A dictionary of solver options. E.g., `k`, see `show_options()` for details.

  Returns:
    sol RootResults

      The solution represented as a `RootResults` object. Important attributes are: `root` the solution , `converged` a boolean flag indicating if the algorithm exited successfully and `flag` which describes the cause of the termination. See `RootResults` for a description of other attributes.

  See also

  `show_options`

    Additional options accepted by the solvers

  `root`

    Find a root of a vector function.

  Notes

  This section describes the available solvers that can be selected by the ‘method’ parameter.

  The default is to use the best method available for the situation presented. If a bracket is provided, it may use one of the bracketing methods. If a derivative and an initial value are specified, it may select one of the derivative-based methods. If no method is judged applicable, it will raise an Exception.

  Arguments for each method are as follows (x=required, o=optional).

  method | f | args | bracket | x0 | x1 | fprime | fprime2 | xtol | rtol | maxiter | options
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  bisect | x | o | x |  |  |  |  | o | o | o | o
  brentq | x | o | x |  |  |  |  | o | o | o | o
  brenth | x | o | x |  |  |  |  | o | o | o | o
  ridder | x | o | x |  |  |  |  | o | o | o | o
  toms748 | x | o | x |  |  |  |  | o | o | o | o
  secant | x | o |  | x | o |  |  | o | o | o | o
  newton | x | o |  | x |  | o |  | o | o | o | o
  halley | x | o |  | x |  | x | x | o | o | o | o

  Examples

  Find the root of a simple cubic

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

      >>> def fprime(x):
      ...     return 3*x**2

  The `brentq` method takes as input a bracket

      >>> sol = optimize.root_scalar(f, bracket=[0, 3], method='brentq')
      >>> sol.root, sol.iterations, sol.function_calls
      (1.0, 10, 11)

  The `newton` method takes as input a single point and uses the derivative(s).

      >>> sol = optimize.root_scalar(f, x0=0.2, fprime=fprime, method='newton')
      >>> sol.root, sol.iterations, sol.function_calls
      (1.0, 11, 22)

  The function can provide the value and derivative(s) in a single call.

      >>> def f_p_pp(x):
      ...     return (x**3 - 1), 3*x**2, 6*x

      >>> sol = optimize.root_scalar(
      ...     f_p_pp, x0=0.2, fprime=True, method='newton'
      ... )
      >>> sol.root, sol.iterations, sol.function_calls
      (1.0, 11, 11)

      >>> sol = optimize.root_scalar(
      ...     f_p_pp, x0=0.2, fprime=True, fprime2=True, method='halley'
      ... )
      >>> sol.root, sol.iterations, sol.function_calls
      (1.0, 7, 8)