U Ä@·f!Hã @sŽdZddlZddlmZdgZdddd d d d d gZGdd„dƒZd"dd„Z dd„Z dd„Z dd„Z dd„Z dd„Zdd„Zdd„Zd d!„ZdS)#z• Unified interfaces to root finding algorithms for real or complex scalar functions. Functions --------- - root : find a root of a scalar function. éNé)Ú _zeros_pyÚ root_scalarÚbisectÚbrentqÚbrenthÚridderÚtoms748ÚnewtonÚsecantÚhalleyc@s8eZdZdZdd„Zdd„Zdd„Zdd „Zd d „Zd S) Ú MemoizeDerašDecorator that caches the value and derivative(s) of function each time it is called. This is a simplistic memoizer that calls and caches a single value of `f(x, *args)`. It assumes that `args` does not change between invocations. It supports the use case of a root-finder where `args` is fixed, `x` changes, and only rarely, if at all, does x assume the same value more than once.cCs||_d|_d|_d|_dS)Nr)ÚfunÚvalsÚxÚn_calls)Úselfr©rú?/tmp/pip-unpacked-wheel-w7avvj8p/scipy/optimize/_root_scalar.pyÚ__init__szMemoizeDer.__init__cGsP|jdks||jkrF|j|f|žŽ}||_|jd7_|dd…|_|jdS)z,Calculate f or use cached value if availableNrr)rrrr)rrÚargsZfgrrrÚ__call__#s zMemoizeDer.__call__cGs,|jdks||jkr"||f|žŽ|jdS)z/Calculate f' or use a cached value if availableNr©rr©rrrrrrÚfprime-szMemoizeDer.fprimecGs,|jdks||jkr"||f|žŽ|jdS)z0Calculate f'' or use a cached value if availableNérrrrrÚfprime23szMemoizeDer.fprime2cCs|jS)N)r)rrrrÚncalls9szMemoizeDer.ncallsN) Ú__name__Ú __module__Ú __qualname__Ú__doc__rrrrrrrrrr s   r rc  Cs6t|tƒs|f}| dkri} d} |dk rVt|ƒsVt|ƒrRt|ƒ}d} |j}|j}nd}|dk r†t|ƒs†t|ƒr‚t|ƒ}d} |j}nd}i} dD] }tƒ |¡}|dk rŽ|| |<qŽ| r¾|   | ¡| j ddd|sú|rÚd}n |dk rú|rö|rðd}qúd}nd }|st d ƒ‚|  ¡}ddd œ}zt t | ||¡ƒ}Wn2tk rb}zt d |ƒ|‚W5d}~XYnX|d kr¾t|tttjfƒsŽt d|ƒ‚|dd…\}}||||fd|i| —Ž\}}nb|dkr.|dkrÞt d|ƒ‚|dkrôt d|ƒ‚d| kr |  d¡| d<|||f|dd|dœ| —Ž\}}nò|dkr˜|dkrNt d|ƒ‚|s`t d|ƒ‚d| krx|  d¡| d<|||f||ddœ| —Ž\}}nˆ|dkr|dkr¸t d|ƒ‚|sÊt d|ƒ‚|sÜt d|ƒ‚d| krô|  d¡| d<|||f|||dœ| —Ž\}}n t d |ƒ‚| r2|j}||_|S)aV Find a root of a scalar function. Parameters ---------- f : callable A function to find a root of. 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' :ref:`(see here) ` - 'brentq' :ref:`(see here) ` - 'brenth' :ref:`(see here) ` - 'ridder' :ref:`(see here) ` - 'toms748' :ref:`(see here) ` - 'newton' :ref:`(see here) ` - 'secant' :ref:`(see here) ` - 'halley' :ref:`(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 :obj:`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 | +===============================================+===+======+=========+====+====+========+=========+======+======+=========+=========+ | :ref:`bisect ` | x | o | x | | | | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`brentq ` | x | o | x | | | | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`brenth ` | x | o | x | | | | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`ridder ` | x | o | x | | | | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`toms748 ` | x | o | x | | | | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`newton ` | x | o | | x | | x | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`secant ` | x | o | | x | x | | | o | o | o | o | +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+ | :ref:`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) NFT)ÚxtolÚrtolÚmaxiter)Z full_outputZdisprr r r zIUnable to select a solver as neither bracket nor starting point provided.)r r zUnknown solver %s)rrrrr zBracket needed for %srr)r zx0 must not be None for %szx1 must not be None for %sr"Ztol)rrrÚx1)r zfprime must be specified for %s)rrr)r z fprime2 must be specified for %s)Ú isinstanceÚtupleÚcallableÚboolr rrÚlocalsÚgetÚupdateÚ ValueErrorÚlowerÚgetattrÚoptzerosÚAttributeErrorÚlistÚnpZndarrayÚpoprZfunction_calls)ÚfrÚmethodZbracketrrZx0r%r"r#r$ÚoptionsZ is_memoizedÚkwargsÚkÚvÚmethZmap2underlyingZmethodcÚeÚaÚbÚrZsolrrrrr=s¬               ÿÿ      ÿ         cCsdS)a? Options ------- args : tuple, optional Extra arguments passed to the objective function. bracket: A sequence of 2 floats, optional An interval bracketing a root. `f(x, *args)` must have different signs at the two endpoints. xtol : float, optional Tolerance (absolute) for termination. rtol : float, optional Tolerance (relative) for termination. maxiter : int, optional Maximum number of iterations. options: dict, optional Specifies any method-specific options not covered above NrrrrrÚ_root_scalar_brentq_doc<sr@cCsdS©a@ Options ------- args : tuple, optional Extra arguments passed to the objective function. bracket: A sequence of 2 floats, optional An interval bracketing a root. `f(x, *args)` must have different signs at the two endpoints. xtol : float, optional Tolerance (absolute) for termination. rtol : float, optional Tolerance (relative) for termination. maxiter : int, optional Maximum number of iterations. options: dict, optional Specifies any method-specific options not covered above. NrrrrrÚ_root_scalar_brenth_docRsrBcCsdSrArrrrrÚ_root_scalar_toms748_docgsrCcCsdS)a Options ------- args : tuple, optional Extra arguments passed to the objective function. xtol : float, optional Tolerance (absolute) for termination. rtol : float, optional Tolerance (relative) for termination. maxiter : int, optional Maximum number of iterations. x0 : float, required Initial guess. x1 : float, required A second guess. options: dict, optional Specifies any method-specific options not covered above. NrrrrrÚ_root_scalar_secant_doc}srDcCsdS)a" Options ------- args : tuple, optional Extra arguments passed to the objective function and its derivative. xtol : float, optional Tolerance (absolute) for termination. rtol : float, optional Tolerance (relative) for termination. maxiter : int, optional Maximum number of iterations. x0 : float, required Initial guess. fprime : bool or callable, optional If `fprime` is a boolean and is True, `f` is assumed to return the value of derivative along with the objective function. `fprime` can also be a callable returning the derivative of `f`. In this case, it must accept the same arguments as `f`. options: dict, optional Specifies any method-specific options not covered above. NrrrrrÚ_root_scalar_newton_doc”srEcCsdS)ar Options ------- args : tuple, optional Extra arguments passed to the objective function and its derivatives. xtol : float, optional Tolerance (absolute) for termination. rtol : float, optional Tolerance (relative) for termination. maxiter : int, optional Maximum number of iterations. x0 : float, required Initial guess. fprime : bool or callable, required If `fprime` is a boolean and is True, `f` is assumed to return the value of derivative along with the objective function. `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, required If `fprime2` is a boolean and is True, `f` is assumed to return the value of 1st and 2nd derivatives along with the objective function. `fprime2` can also be a callable returning the 2nd derivative of `f`. In this case, it must accept the same arguments as `f`. options: dict, optional Specifies any method-specific options not covered above. NrrrrrÚ_root_scalar_halley_doc®srFcCsdSrArrrrrÚ_root_scalar_ridder_docÍsrGcCsdSrArrrrrÚ_root_scalar_bisect_docãsrH) rNNNNNNNNNN)r!Znumpyr3Úrr0Ú__all__ZROOT_SCALAR_METHODSr rr@rBrCrDrErFrGrHrrrrÚs:  ÿ*ü