Ë
    çÿæi§O  ã                   óŒ   — d Z ddlZddlmZ ddlmZ dgZg d¢Z	 G d„ d	«      Z
	 	 	 	 	 dd
„Zd„ Zd„ Zd„ Zd„ Zd„ Zd„ Zd„ Zd„ Zy)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©Úapprox_derivativeÚroot_scalar)ÚbisectÚbrentqÚbrenthÚridderÚtoms748ÚnewtonÚsecantÚhalleyc                   ó.   — e Zd ZdZd„ Zd„ Zd„ Zd„ Zd„ Zy)Ú
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.c                 ó<   — || _         d | _        d | _        d| _        y ©Nr   )ÚfunÚvalsÚxÚn_calls)Úselfr   s     úp/Volumes/fast/ai/experiments/voice-extract-mac/.venv/lib/python3.12/site-packages/scipy/optimize/_root_scalar.pyÚ__init__zMemoizeDer.__init__   s   € ØˆŒØˆŒ	ØˆŒØˆ�ó    c                 óÈ   — | j                   �|| j                  k7  r9 | j                  |g|¢­Ž }|| _        | xj                  dz  c_        |dd | _         | j                   d   S )z,Calculate f or use cached value if availableNr   r   )r   r   r   r   )r   r   ÚargsÚfgs       r   Ú__call__zMemoizeDer.__call__$   s[   € ð �9‰9Ð  T§V¡V¢Ø�—‘˜!Ð#˜dÒ#ˆBØˆDŒFØ�LŠL˜AÑ�LØ™1˜ˆDŒIØ�y‰y˜‰|Ðr   c                 óh   — | j                   �|| j                  k7  r	 | |g|¢­Ž  | j                   d   S )z/Calculate f' or use a cached value if availabler   ©r   r   ©r   r   r   s      r   ÚfprimezMemoizeDer.fprime.   ó/   € à�9‰9Ð  T§V¡V¢Ù�ˆN�T‹NØ�y‰y˜‰|Ðr   c                 óh   — | j                   �|| j                  k7  r	 | |g|¢­Ž  | j                   d   S )z0Calculate f'' or use a cached value if availableé   r!   r"   s      r   Úfprime2zMemoizeDer.fprime24   r$   r   c                 ó   — | j                   S )N)r   )r   s    r   ÚncallszMemoizeDer.ncalls:   s   € Ø�|‰|Ðr   N)	Ú__name__Ú
__module__Ú__qualname__Ú__doc__r   r   r#   r'   r)   © r   r   r   r      s    „ ñòòòòór   r   c           	      ó@  ‡ — t        |t        «      s|f}|€i }d}|�>t        |«      s3t        |«      r&t	        ‰ «      Š d}‰ j
                  }‰ j                  }nd}|�2t        |«      s't        |«      rt	        ‰ «      Š d}‰ j                  }nd}i }dD ]#  }t        «       j                  |«      }|€Œ|||<   Œ% |r|j                  |«       |j                  dd¬«       |s|�d}n|�|r|rd}n
d}n|�d	}nd}|st        d
«      ‚|j                  «       }dddœ}	 t        t        |j                  ||«      «      }|dv rPt        |t        t        z  t         j"                  z  «      st        d|› �«      ‚|dd \  }}	  |‰ ||fd|i|¤Ž\  }}nð|dv r;|€t        d|› �«      ‚d|v r|j1                  d«      |d<    |‰ |f|dd|dœ|¤Ž\  }}n±|dv rA|€t        d|› �«      ‚|sˆ fd„}d|v r|j1                  d«      |d<    |‰ |f||ddœ|¤Ž\  }}nl|dv rZ|€t        d|› �«      ‚|st        d|› �«      ‚|st        d|› �«      ‚d|v r|j1                  d«      |d<    |‰ |f|||dœ|¤Ž\  }}nt        d|› �«      ‚|r‰ j2                  }||_        |S # t        $ r}t        d|› �«      |‚d}~ww xY w# t        $ r]}t%        |d«      rFt        j&                  |j(                  t         j*                  |j,                  t/        |«      |¬«      }n‚ Y d}~Œ˜d}~ww xY w)aû  
    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'    :ref:`(see here) <optimize.root_scalar-bisect>`
        - 'brentq'    :ref:`(see here) <optimize.root_scalar-brentq>`
        - 'brenth'    :ref:`(see here) <optimize.root_scalar-brenth>`
        - 'ridder'    :ref:`(see here) <optimize.root_scalar-ridder>`
        - 'toms748'    :ref:`(see here) <optimize.root_scalar-toms748>`
        - 'newton'    :ref:`(see here) <optimize.root_scalar-newton>`
        - 'secant'    :ref:`(see here) <optimize.root_scalar-secant>`
        - 'halley'    :ref:`(see here) <optimize.root_scalar-halley>`

    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 <optimize.root_scalar-bisect>`   | x |  o   |    x    |    |    |        |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`brentq <optimize.root_scalar-brentq>`   | x |  o   |    x    |    |    |        |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`brenth <optimize.root_scalar-brenth>`   | x |  o   |    x    |    |    |        |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`ridder <optimize.root_scalar-ridder>`   | x |  o   |    x    |    |    |        |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`toms748 <optimize.root_scalar-toms748>` | x |  o   |    x    |    |    |        |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`secant <optimize.root_scalar-secant>`   | x |  o   |         | x  | o  |        |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`newton <optimize.root_scalar-newton>`   | x |  o   |         | x  |    |   o    |         |  o   |  o   |    o    |   o     |
    +-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+
    | :ref:`halley <optimize.root_scalar-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)Úfull_outputÚdispr	   r   r   r   zIUnable to select a solver as neither bracket nor starting point provided.)r   r   zUnknown solver )r   r   r	   r
   r   zBracket needed for r&   r   Ú_x)ÚrootÚ
iterationsÚfunction_callsÚflagÚmethod)r   zx0 must not be None for r0   Útol)r   r#   r'   Úx1)r   c                 ó2   •— ˆfd„}t        || d|¬«      d   S )Nc                 ó   •—  ‰| d   g|¢­Ž S r   r.   )r   r   Úfs     €r   Ú	f_wrappedz.root_scalar.<locals>.fprime.<locals>.f_wrappedA  s   ø€ Ù˜Q˜q™T˜> Dš>Ð)r   z2-point)r:   r   r   r   )r   r   r@   r?   s      €r   r#   zroot_scalar.<locals>.fprime9  s   ø€ ô*ä(¨°A¸iÈdÔSÐTUÑVÐVr   )r   r#   r'   )r   zfprime must be specified for zfprime2 must be specified for )Ú
isinstanceÚtupleÚcallableÚboolr   r'   r#   ÚlocalsÚgetÚupdateÚ
ValueErrorÚlowerÚgetattrÚoptzerosÚAttributeErrorÚlistÚnpÚndarrayÚhasattrÚRootResultsr5   ÚnanÚ_function_callsÚstrÚpopr   r8   )r?   r   r:   Úbracketr#   r'   Úx0r<   r0   r1   r2   ÚoptionsÚis_memoizedÚkwargsÚkÚvÚmethÚmap2underlyingÚmethodcÚeÚaÚbÚrÚsolr   s   `                        r   r   r   >   sÂ  ø€ ôr �dœEÔ"Øˆwˆà€Øˆð €KØÐ¤8¨GÔ#4Ü�Œ=Ü˜1“ˆAØˆKØ—i‘iˆGØ—X‘X‰FàˆGØÐ¤(¨6Ô"2Ü�Œ<Ü˜1“ˆAØˆKØ—X‘X‰FàˆFð €FÛ(ˆÜ‹H�L‰L˜‹OˆØ‰=ØˆF�1ŠIð )ñ Ø�‰�gÔð ‡M�M˜d¨€MÔ/ñ ØÐØ‰FØˆ^ÙÙØ%‘Fà%‘FØ�Ø!‘à!�ÙÜð 8ó 9ð 	9ð �<‰<‹>€DØ (°HÑ=€Nð:Üœ( N×$6Ñ$6°t¸TÓ$BÓCˆð ÐBÑBÜ˜'¤4¬%¡<´"·*±*Ñ#<Ô=ÜÐ2°6°(Ð;Ó<Ð<à�r˜ˆ{‰ˆˆ1ð	Ù˜Q  1Ñ:¨4Ð:°6Ñ:‰FˆA‰sð 
�Ñ	Øˆ:ÜÐ7¸°xÐ@ÓAÐAØ�VÑØ"ŸJ™J vÓ.ˆF�5‰MÙ˜˜Bð * T°$ÀØñ*Ø"(ñ*‰ˆ‰3à	�Ñ	Øˆ:ÜÐ7¸°xÐ@ÓAÐAÙô
Wð �VÑØ"ŸJ™J vÓ.ˆF�5‰MÙ˜˜Bð # T°&À$ñ #Ø!ñ#‰ˆ‰3à	�Ñ	Øˆ:ÜÐ7¸°xÐ@ÓAÐAÙÜÐ<¸V¸HÐEÓFÐFÙÜÐ=¸f¸XÐFÓGÐGØ�VÑØ"ŸJ™J vÓ.ˆF�5‰MÙ˜˜BÐT T°&À'ÑTÈVÑT‰ˆ‰3ä˜?¨6¨(Ð3Ó4Ð4áð —)‘)ˆØ$ˆÔà€JøôO ò :Ü˜?¨4¨&Ð1Ó2¸Ð9ûð:ûô ò 	ô
 �q˜$ÔÜ×*Ñ*°·±Ü68·f±fØ:;×:KÑ:KÜ03°A³¸vôG‘ð
 ô ûð	ús1   Ä J Å?J7 Ê	J4Ê J/Ê/J4Ê7	LË ALÌLc                   ó   — y)aA  
    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

    Nr.   r.   r   r   Ú_root_scalar_brentq_docrf   _  ó   € ð& 	r   c                   ó   — y©aB  
    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.

    Nr.   r.   r   r   Ú_root_scalar_brenth_docrj   u  rg   r   c                   ó   — yri   r.   r.   r   r   Ú_root_scalar_toms748_docrl   Š  rg   r   c                   ó   — y)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, optional
        A second guess. Must be different from `x0`. If not specified,
        a value near `x0` will be chosen.
    options: dict, optional
        Specifies any method-specific options not covered above.

    Nr.   r.   r   r   Ú_root_scalar_secant_docrn      s   € ð* 	r   c                   ó   — y)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.

    Nr.   r.   r   r   Ú_root_scalar_newton_docrp   ¸  s   € ð. 	r   c                   ó   — y)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.

    Nr.   r.   r   r   Ú_root_scalar_halley_docrr   Ò  s   € ð8 	r   c                   ó   — yri   r.   r.   r   r   Ú_root_scalar_ridder_docrt   ñ  rg   r   c                   ó   — yri   r.   r.   r   r   Ú_root_scalar_bisect_docrv     rg   r   )r.   NNNNNNNNNN)r-   ÚnumpyrN   Ú r   rK   Ú_numdiffr   Ú__all__ÚROOT_SCALAR_METHODSr   r   rf   rj   rl   rn   rp   rr   rt   rv   r.   r   r   Ú<module>r|      so   ðñó å #Ý 'àˆ/€ò5Ð ÷'ñ 'ðT 26Ø%)Ø Ø.2Øó	^òB		ò,	ò*	ò,	ò0	ò4	ò>	ó,	r   