From e98c18ed490b3c177801f305a505622525066b87 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 22 Apr 2012 20:58:27 +0200 Subject: [PATCH] MAINT: fix more Sphinx issues. Also closes #1643. --- scipy/special/lambertw.c | 14 ++++---- scipy/special/lambertw.pyx | 66 ++++++++++++++++++++------------------ scipy/stats/kde.py | 7 ++-- 3 files changed, 45 insertions(+), 42 deletions(-) diff --git a/scipy/special/lambertw.c b/scipy/special/lambertw.c index acfd7330654c..290de565574d 100644 --- a/scipy/special/lambertw.c +++ b/scipy/special/lambertw.c @@ -1,4 +1,4 @@ -/* Generated by Cython 0.15 on Tue Nov 1 18:19:53 2011 */ +/* Generated by Cython 0.15 on Sun Apr 22 20:57:41 2012 */ #define PY_SSIZE_T_CLEAN #include "Python.h" @@ -554,7 +554,7 @@ static char __pyx_k_1[] = "Lambert W iteration failed to converge: %r"; static char __pyx_k_3[] = ""; static char __pyx_k_4[] = "scipy.special.lambertw"; static char __pyx_k_5[] = "lambertw (line 193)"; -static char __pyx_k_6[] = "\n lambertw(z, k=0, tol=1e-8)\n\n Lambert W function.\n\n The Lambert W function `W(z)` is defined as the inverse function\n of :math:`w \\exp(w)`. In other words, the value of :math:`W(z)` is\n such that :math:`z = W(z) \\exp(W(z))` for any complex number\n :math:`z`.\n\n The Lambert W function is a multivalued function with infinitely\n many branches. Each branch gives a separate solution of the\n equation :math:`w \\exp(w)`. Here, the branches are indexed by the\n integer `k`.\n \n Parameters\n ----------\n z : array_like\n Input argument\n k : integer, optional\n Branch index\n tol : float\n Evaluation tolerance\n\n Notes\n -----\n All branches are supported by `lambertw`:\n\n * ``lambertw(z)`` gives the principal solution (branch 0)\n * ``lambertw(z, k)`` gives the solution on branch `k`\n\n The Lambert W function has two partially real branches: the\n principal branch (`k = 0`) is real for real `z > -1/e`, and the\n `k = -1` branch is real for `-1/e < z < 0`. All branches except\n `k = 0` have a logarithmic singularity at `z = 0`.\n\n .. rubric:: Possible issues\n \n The evaluation can become inaccurate very close to the branch point\n at `-1/e`. In some corner cases, :func:`lambertw` might currently\n fail to converge, or can end up on the wrong branch.\n\n .. rubric:: Algorithm\n\n Halley's iteration is used to invert `w \\exp(w)`, using a first-order\n asymptotic approximation (`O(\\log(w))` or `O(w)`) as the initial\n estimate.\n\n The definition, implementation and choice of branches is based\n on Corless et al, \"On the Lambert W function\", Adv. Comp. Math. 5\n (1996) 329-359, available online here:\n http://www.apmaths.uwo.ca/~djeffrey/Offprints/W-adv-cm.pdf\n \n TODO: use a series expansion when extremely close to the branch point\n at `-1/e` and make sure that the proper branch is chosen there\n\n Examples""\n --------\n The Lambert W function is the inverse of `w \\exp(w)`::\n\n >>> from scipy.special import lambertw\n >>> w = lambertw(1)\n >>> w\n 0.56714329040978387299996866221035555\n >>> w*exp(w)\n 1.0\n\n Any branch gives a valid inverse::\n\n >>> w = lambertw(1, k=3)\n >>> w\n (-2.8535817554090378072068187234910812 +\n 17.113535539412145912607826671159289j)\n >>> w*exp(w)\n (1.0 + 3.5075477124212226194278700785075126e-36j)\n\n .. rubric:: Applications to equation-solving\n\n The Lambert W function may be used to solve various kinds of\n equations, such as finding the value of the infinite power\n tower `z^{z^{z^{\\ldots}}}`::\n\n >>> def tower(z, n):\n ... if n == 0:\n ... return z\n ... return z ** tower(z, n-1)\n ...\n >>> tower(0.5, 100)\n 0.641185744504986\n >>> -lambertw(-log(0.5))/log(0.5)\n 0.6411857445049859844862004821148236665628209571911\n\n .. rubric:: Properties\n\n The Lambert W function grows roughly like the natural logarithm\n for large arguments::\n\n >>> lambertw(1000)\n 5.2496028524016\n >>> log(1000)\n 6.90775527898214\n >>> lambertw(10**100)\n 224.843106445119\n >>> log(10**100)\n 230.258509299405\n \n The principal branch of the Lambert W function has a rational\n Taylor series expansion around `z = 0`::\n \n >>> nprint(taylor(lambertw, 0, 6), 10)\n [0.0, 1.0, -1.0, 1.5, -2.666666667, 5.208333333, -10.8]\n \n Some special values and limits are::\n \n >>> lambertw(0)\n 0.0\n >>> lambertw(1)\n 0.567143290409784\n >>> lambertw(e)\n 1.0\n >>> lambertw(inf)\n +inf\n >>> lambertw(0, k=-1)\n -inf\n >>> lambertw(0, k=3)\n -inf\n >>> lambertw(inf, k=3)\n (+inf + 18.8495559215388j)\n\n The `k = 0` and `k = -1` branches join at `z = -1/e` where\n `W(z) = -1` for both branches. Since `-1/e` can only be represented\n approximately with mpmath numbers, evaluatin""g the Lambert W function\n at this point only gives `-1` approximately::\n\n >>> lambertw(-1/e, 0)\n -0.999999999999837133022867\n >>> lambertw(-1/e, -1)\n -1.00000000000016286697718\n \n If `-1/e` happens to round in the negative direction, there might be\n a small imaginary part::\n \n >>> lambertw(-1/e)\n (-1.0 + 8.22007971511612e-9j)\n\n "; +static char __pyx_k_6[] = "\n lambertw(z, k=0, tol=1e-8)\n\n Lambert W function.\n\n The Lambert W function `W(z)` is defined as the inverse function\n of ``w * exp(w)``. In other words, the value of ``W(z)`` is\n such that ``z = W(z) * exp(W(z))`` for any complex number\n ``z``.\n\n The Lambert W function is a multivalued function with infinitely\n many branches. Each branch gives a separate solution of the\n equation ``w exp(w)``. Here, the branches are indexed by the\n integer `k`.\n \n Parameters\n ----------\n z : array_like\n Input argument.\n k : int, optional\n Branch index.\n tol : float, optional\n Evaluation tolerance.\n\n Notes\n -----\n All branches are supported by `lambertw`:\n\n * ``lambertw(z)`` gives the principal solution (branch 0)\n * ``lambertw(z, k)`` gives the solution on branch `k`\n\n The Lambert W function has two partially real branches: the\n principal branch (`k = 0`) is real for real ``z > -1/e``, and the\n ``k = -1`` branch is real for ``-1/e < z < 0``. All branches except\n ``k = 0`` have a logarithmic singularity at ``z = 0``.\n\n **Possible issues**\n \n The evaluation can become inaccurate very close to the branch point\n at ``-1/e``. In some corner cases, `lambertw` might currently\n fail to converge, or can end up on the wrong branch.\n\n **Algorithm**\n\n Halley's iteration is used to invert ``w * exp(w)``, using a first-order\n asymptotic approximation (O(log(w)) or `O(w)`) as the initial estimate.\n\n The definition, implementation and choice of branches is based on [1]_.\n \n TODO: use a series expansion when extremely close to the branch point\n at ``-1/e`` and make sure that the proper branch is chosen there\n\n References\n ----------\n .. [1] Corless et al, \"On the Lambert W function\", Adv. Comp. Math. 5\n (1996) 329-359.\n http://www.apmaths.uwo.ca/~djeffrey/Offprints/W-adv-cm.pdf\n\n Exampl""es\n --------\n The Lambert W function is the inverse of ``w exp(w)``:\n\n >>> from scipy.special import lambertw\n >>> w = lambertw(1)\n >>> w\n 0.56714329040978387299996866221035555\n >>> w*exp(w)\n 1.0\n\n Any branch gives a valid inverse:\n\n >>> w = lambertw(1, k=3)\n >>> w\n (-2.8535817554090378072068187234910812 +\n 17.113535539412145912607826671159289j)\n >>> w*exp(w)\n (1.0 + 3.5075477124212226194278700785075126e-36j)\n\n **Applications to equation-solving**\n\n The Lambert W function may be used to solve various kinds of\n equations, such as finding the value of the infinite power\n tower :math:`z^{z^{z^{\\ldots}}}`:\n\n >>> def tower(z, n):\n ... if n == 0:\n ... return z\n ... return z ** tower(z, n-1)\n ...\n >>> tower(0.5, 100)\n 0.641185744504986\n >>> -lambertw(-log(0.5))/log(0.5)\n 0.6411857445049859844862004821148236665628209571911\n\n **Properties**\n\n The Lambert W function grows roughly like the natural logarithm\n for large arguments:\n\n >>> lambertw(1000)\n 5.2496028524016\n >>> log(1000)\n 6.90775527898214\n >>> lambertw(10**100)\n 224.843106445119\n >>> log(10**100)\n 230.258509299405\n \n The principal branch of the Lambert W function has a rational\n Taylor series expansion around `z = 0`::\n \n >>> nprint(taylor(lambertw, 0, 6), 10)\n [0.0, 1.0, -1.0, 1.5, -2.666666667, 5.208333333, -10.8]\n \n Some special values and limits are:\n \n >>> lambertw(0)\n 0.0\n >>> lambertw(1)\n 0.567143290409784\n >>> lambertw(e)\n 1.0\n >>> lambertw(inf)\n +inf\n >>> lambertw(0, k=-1)\n -inf\n >>> lambertw(0, k=3)\n -inf\n >>> lambertw(inf, k=3)\n (+inf + 18.8495559215388j)\n\n The `k = 0` and `k = -1` branches join at `z = -1/e` where\n `W(z) = -1` for both branches. Since `-1/e` can only be represented\n approximately with mpmath numbers, evaluating the Lambert"" W function\n at this point only gives `-1` approximately:\n\n >>> lambertw(-1/e, 0)\n -0.999999999999837133022867\n >>> lambertw(-1/e, -1)\n -1.00000000000016286697718\n \n If `-1/e` happens to round in the negative direction, there might be\n a small imaginary part:\n \n >>> lambertw(-1/e)\n (-1.0 + 8.22007971511612e-9j)\n\n "; static char __pyx_k__k[] = "k"; static char __pyx_k__z[] = "z"; static char __pyx_k__tol[] = "tol"; @@ -1344,7 +1344,7 @@ static void __pyx_f_5scipy_7special_8lambertw__apply_func_to_1d_vec(char **__pyx */ static PyObject *__pyx_pf_5scipy_7special_8lambertw_lambertw(PyObject *__pyx_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ -static char __pyx_doc_5scipy_7special_8lambertw_lambertw[] = "\n lambertw(z, k=0, tol=1e-8)\n\n Lambert W function.\n\n The Lambert W function `W(z)` is defined as the inverse function\n of :math:`w \\exp(w)`. In other words, the value of :math:`W(z)` is\n such that :math:`z = W(z) \\exp(W(z))` for any complex number\n :math:`z`.\n\n The Lambert W function is a multivalued function with infinitely\n many branches. Each branch gives a separate solution of the\n equation :math:`w \\exp(w)`. Here, the branches are indexed by the\n integer `k`.\n \n Parameters\n ----------\n z : array_like\n Input argument\n k : integer, optional\n Branch index\n tol : float\n Evaluation tolerance\n\n Notes\n -----\n All branches are supported by `lambertw`:\n\n * ``lambertw(z)`` gives the principal solution (branch 0)\n * ``lambertw(z, k)`` gives the solution on branch `k`\n\n The Lambert W function has two partially real branches: the\n principal branch (`k = 0`) is real for real `z > -1/e`, and the\n `k = -1` branch is real for `-1/e < z < 0`. All branches except\n `k = 0` have a logarithmic singularity at `z = 0`.\n\n .. rubric:: Possible issues\n \n The evaluation can become inaccurate very close to the branch point\n at `-1/e`. In some corner cases, :func:`lambertw` might currently\n fail to converge, or can end up on the wrong branch.\n\n .. rubric:: Algorithm\n\n Halley's iteration is used to invert `w \\exp(w)`, using a first-order\n asymptotic approximation (`O(\\log(w))` or `O(w)`) as the initial\n estimate.\n\n The definition, implementation and choice of branches is based\n on Corless et al, \"On the Lambert W function\", Adv. Comp. Math. 5\n (1996) 329-359, available online here:\n http://www.apmaths.uwo.ca/~djeffrey/Offprints/W-adv-cm.pdf\n \n TODO: use a series expansion when extremely close to the branch point\n at `-1/e` and make sure that the proper branch is chosen there\n\n Examples""\n --------\n The Lambert W function is the inverse of `w \\exp(w)`::\n\n >>> from scipy.special import lambertw\n >>> w = lambertw(1)\n >>> w\n 0.56714329040978387299996866221035555\n >>> w*exp(w)\n 1.0\n\n Any branch gives a valid inverse::\n\n >>> w = lambertw(1, k=3)\n >>> w\n (-2.8535817554090378072068187234910812 +\n 17.113535539412145912607826671159289j)\n >>> w*exp(w)\n (1.0 + 3.5075477124212226194278700785075126e-36j)\n\n .. rubric:: Applications to equation-solving\n\n The Lambert W function may be used to solve various kinds of\n equations, such as finding the value of the infinite power\n tower `z^{z^{z^{\\ldots}}}`::\n\n >>> def tower(z, n):\n ... if n == 0:\n ... return z\n ... return z ** tower(z, n-1)\n ...\n >>> tower(0.5, 100)\n 0.641185744504986\n >>> -lambertw(-log(0.5))/log(0.5)\n 0.6411857445049859844862004821148236665628209571911\n\n .. rubric:: Properties\n\n The Lambert W function grows roughly like the natural logarithm\n for large arguments::\n\n >>> lambertw(1000)\n 5.2496028524016\n >>> log(1000)\n 6.90775527898214\n >>> lambertw(10**100)\n 224.843106445119\n >>> log(10**100)\n 230.258509299405\n \n The principal branch of the Lambert W function has a rational\n Taylor series expansion around `z = 0`::\n \n >>> nprint(taylor(lambertw, 0, 6), 10)\n [0.0, 1.0, -1.0, 1.5, -2.666666667, 5.208333333, -10.8]\n \n Some special values and limits are::\n \n >>> lambertw(0)\n 0.0\n >>> lambertw(1)\n 0.567143290409784\n >>> lambertw(e)\n 1.0\n >>> lambertw(inf)\n +inf\n >>> lambertw(0, k=-1)\n -inf\n >>> lambertw(0, k=3)\n -inf\n >>> lambertw(inf, k=3)\n (+inf + 18.8495559215388j)\n\n The `k = 0` and `k = -1` branches join at `z = -1/e` where\n `W(z) = -1` for both branches. Since `-1/e` can only be represented\n approximately with mpmath numbers, evaluatin""g the Lambert W function\n at this point only gives `-1` approximately::\n\n >>> lambertw(-1/e, 0)\n -0.999999999999837133022867\n >>> lambertw(-1/e, -1)\n -1.00000000000016286697718\n \n If `-1/e` happens to round in the negative direction, there might be\n a small imaginary part::\n \n >>> lambertw(-1/e)\n (-1.0 + 8.22007971511612e-9j)\n\n "; +static char __pyx_doc_5scipy_7special_8lambertw_lambertw[] = "\n lambertw(z, k=0, tol=1e-8)\n\n Lambert W function.\n\n The Lambert W function `W(z)` is defined as the inverse function\n of ``w * exp(w)``. In other words, the value of ``W(z)`` is\n such that ``z = W(z) * exp(W(z))`` for any complex number\n ``z``.\n\n The Lambert W function is a multivalued function with infinitely\n many branches. Each branch gives a separate solution of the\n equation ``w exp(w)``. Here, the branches are indexed by the\n integer `k`.\n \n Parameters\n ----------\n z : array_like\n Input argument.\n k : int, optional\n Branch index.\n tol : float, optional\n Evaluation tolerance.\n\n Notes\n -----\n All branches are supported by `lambertw`:\n\n * ``lambertw(z)`` gives the principal solution (branch 0)\n * ``lambertw(z, k)`` gives the solution on branch `k`\n\n The Lambert W function has two partially real branches: the\n principal branch (`k = 0`) is real for real ``z > -1/e``, and the\n ``k = -1`` branch is real for ``-1/e < z < 0``. All branches except\n ``k = 0`` have a logarithmic singularity at ``z = 0``.\n\n **Possible issues**\n \n The evaluation can become inaccurate very close to the branch point\n at ``-1/e``. In some corner cases, `lambertw` might currently\n fail to converge, or can end up on the wrong branch.\n\n **Algorithm**\n\n Halley's iteration is used to invert ``w * exp(w)``, using a first-order\n asymptotic approximation (O(log(w)) or `O(w)`) as the initial estimate.\n\n The definition, implementation and choice of branches is based on [1]_.\n \n TODO: use a series expansion when extremely close to the branch point\n at ``-1/e`` and make sure that the proper branch is chosen there\n\n References\n ----------\n .. [1] Corless et al, \"On the Lambert W function\", Adv. Comp. Math. 5\n (1996) 329-359.\n http://www.apmaths.uwo.ca/~djeffrey/Offprints/W-adv-cm.pdf\n\n Exampl""es\n --------\n The Lambert W function is the inverse of ``w exp(w)``:\n\n >>> from scipy.special import lambertw\n >>> w = lambertw(1)\n >>> w\n 0.56714329040978387299996866221035555\n >>> w*exp(w)\n 1.0\n\n Any branch gives a valid inverse:\n\n >>> w = lambertw(1, k=3)\n >>> w\n (-2.8535817554090378072068187234910812 +\n 17.113535539412145912607826671159289j)\n >>> w*exp(w)\n (1.0 + 3.5075477124212226194278700785075126e-36j)\n\n **Applications to equation-solving**\n\n The Lambert W function may be used to solve various kinds of\n equations, such as finding the value of the infinite power\n tower :math:`z^{z^{z^{\\ldots}}}`:\n\n >>> def tower(z, n):\n ... if n == 0:\n ... return z\n ... return z ** tower(z, n-1)\n ...\n >>> tower(0.5, 100)\n 0.641185744504986\n >>> -lambertw(-log(0.5))/log(0.5)\n 0.6411857445049859844862004821148236665628209571911\n\n **Properties**\n\n The Lambert W function grows roughly like the natural logarithm\n for large arguments:\n\n >>> lambertw(1000)\n 5.2496028524016\n >>> log(1000)\n 6.90775527898214\n >>> lambertw(10**100)\n 224.843106445119\n >>> log(10**100)\n 230.258509299405\n \n The principal branch of the Lambert W function has a rational\n Taylor series expansion around `z = 0`::\n \n >>> nprint(taylor(lambertw, 0, 6), 10)\n [0.0, 1.0, -1.0, 1.5, -2.666666667, 5.208333333, -10.8]\n \n Some special values and limits are:\n \n >>> lambertw(0)\n 0.0\n >>> lambertw(1)\n 0.567143290409784\n >>> lambertw(e)\n 1.0\n >>> lambertw(inf)\n +inf\n >>> lambertw(0, k=-1)\n -inf\n >>> lambertw(0, k=3)\n -inf\n >>> lambertw(inf, k=3)\n (+inf + 18.8495559215388j)\n\n The `k = 0` and `k = -1` branches join at `z = -1/e` where\n `W(z) = -1` for both branches. Since `-1/e` can only be represented\n approximately with mpmath numbers, evaluating the Lambert"" W function\n at this point only gives `-1` approximately:\n\n >>> lambertw(-1/e, 0)\n -0.999999999999837133022867\n >>> lambertw(-1/e, -1)\n -1.00000000000016286697718\n \n If `-1/e` happens to round in the negative direction, there might be\n a small imaginary part:\n \n >>> lambertw(-1/e)\n (-1.0 + 8.22007971511612e-9j)\n\n "; static PyMethodDef __pyx_mdef_5scipy_7special_8lambertw_lambertw = {__Pyx_NAMESTR("lambertw"), (PyCFunction)__pyx_pf_5scipy_7special_8lambertw_lambertw, METH_VARARGS|METH_KEYWORDS, __Pyx_DOCSTR(__pyx_doc_5scipy_7special_8lambertw_lambertw)}; static PyObject *__pyx_pf_5scipy_7special_8lambertw_lambertw(PyObject *__pyx_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { PyObject *__pyx_v_z = 0; @@ -1415,16 +1415,16 @@ static PyObject *__pyx_pf_5scipy_7special_8lambertw_lambertw(PyObject *__pyx_sel return NULL; __pyx_L4_argument_unpacking_done:; - /* "scipy/special/lambertw.pyx":340 + /* "scipy/special/lambertw.pyx":342 * * """ * return _lambertw(z, k, tol) # <<<<<<<<<<<<<< * */ __Pyx_XDECREF(__pyx_r); - __pyx_t_1 = __Pyx_GetName(__pyx_m, __pyx_n_s___lambertw); if (unlikely(!__pyx_t_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 340; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_t_1 = __Pyx_GetName(__pyx_m, __pyx_n_s___lambertw); if (unlikely(!__pyx_t_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 342; __pyx_clineno = __LINE__; goto __pyx_L1_error;} __Pyx_GOTREF(__pyx_t_1); - __pyx_t_2 = PyTuple_New(3); if (unlikely(!__pyx_t_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 340; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_t_2 = PyTuple_New(3); if (unlikely(!__pyx_t_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 342; __pyx_clineno = __LINE__; goto __pyx_L1_error;} __Pyx_GOTREF(((PyObject *)__pyx_t_2)); __Pyx_INCREF(__pyx_v_z); PyTuple_SET_ITEM(__pyx_t_2, 0, __pyx_v_z); @@ -1435,7 +1435,7 @@ static PyObject *__pyx_pf_5scipy_7special_8lambertw_lambertw(PyObject *__pyx_sel __Pyx_INCREF(__pyx_v_tol); PyTuple_SET_ITEM(__pyx_t_2, 2, __pyx_v_tol); __Pyx_GIVEREF(__pyx_v_tol); - __pyx_t_3 = PyObject_Call(__pyx_t_1, ((PyObject *)__pyx_t_2), NULL); if (unlikely(!__pyx_t_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 340; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_t_3 = PyObject_Call(__pyx_t_1, ((PyObject *)__pyx_t_2), NULL); if (unlikely(!__pyx_t_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 342; __pyx_clineno = __LINE__; goto __pyx_L1_error;} __Pyx_GOTREF(__pyx_t_3); __Pyx_DECREF(__pyx_t_1); __pyx_t_1 = 0; __Pyx_DECREF(((PyObject *)__pyx_t_2)); __pyx_t_2 = 0; diff --git a/scipy/special/lambertw.pyx b/scipy/special/lambertw.pyx index bc1b56d01189..5c7e3226a496 100644 --- a/scipy/special/lambertw.pyx +++ b/scipy/special/lambertw.pyx @@ -197,23 +197,23 @@ def lambertw(z, k=0, tol=1e-8): Lambert W function. The Lambert W function `W(z)` is defined as the inverse function - of :math:`w \exp(w)`. In other words, the value of :math:`W(z)` is - such that :math:`z = W(z) \exp(W(z))` for any complex number - :math:`z`. + of ``w * exp(w)``. In other words, the value of ``W(z)`` is + such that ``z = W(z) * exp(W(z))`` for any complex number + ``z``. The Lambert W function is a multivalued function with infinitely many branches. Each branch gives a separate solution of the - equation :math:`w \exp(w)`. Here, the branches are indexed by the + equation ``w exp(w)``. Here, the branches are indexed by the integer `k`. Parameters ---------- z : array_like - Input argument - k : integer, optional - Branch index - tol : float - Evaluation tolerance + Input argument. + k : int, optional + Branch index. + tol : float, optional + Evaluation tolerance. Notes ----- @@ -223,33 +223,35 @@ def lambertw(z, k=0, tol=1e-8): * ``lambertw(z, k)`` gives the solution on branch `k` The Lambert W function has two partially real branches: the - principal branch (`k = 0`) is real for real `z > -1/e`, and the - `k = -1` branch is real for `-1/e < z < 0`. All branches except - `k = 0` have a logarithmic singularity at `z = 0`. + principal branch (`k = 0`) is real for real ``z > -1/e``, and the + ``k = -1`` branch is real for ``-1/e < z < 0``. All branches except + ``k = 0`` have a logarithmic singularity at ``z = 0``. - .. rubric:: Possible issues + **Possible issues** The evaluation can become inaccurate very close to the branch point - at `-1/e`. In some corner cases, :func:`lambertw` might currently + at ``-1/e``. In some corner cases, `lambertw` might currently fail to converge, or can end up on the wrong branch. - .. rubric:: Algorithm + **Algorithm** - Halley's iteration is used to invert `w \exp(w)`, using a first-order - asymptotic approximation (`O(\log(w))` or `O(w)`) as the initial - estimate. + Halley's iteration is used to invert ``w * exp(w)``, using a first-order + asymptotic approximation (O(log(w)) or `O(w)`) as the initial estimate. - The definition, implementation and choice of branches is based - on Corless et al, "On the Lambert W function", Adv. Comp. Math. 5 - (1996) 329-359, available online here: - http://www.apmaths.uwo.ca/~djeffrey/Offprints/W-adv-cm.pdf + The definition, implementation and choice of branches is based on [1]_. TODO: use a series expansion when extremely close to the branch point - at `-1/e` and make sure that the proper branch is chosen there + at ``-1/e`` and make sure that the proper branch is chosen there + + References + ---------- + .. [1] Corless et al, "On the Lambert W function", Adv. Comp. Math. 5 + (1996) 329-359. + http://www.apmaths.uwo.ca/~djeffrey/Offprints/W-adv-cm.pdf Examples -------- - The Lambert W function is the inverse of `w \exp(w)`:: + The Lambert W function is the inverse of ``w exp(w)``: >>> from scipy.special import lambertw >>> w = lambertw(1) @@ -258,7 +260,7 @@ def lambertw(z, k=0, tol=1e-8): >>> w*exp(w) 1.0 - Any branch gives a valid inverse:: + Any branch gives a valid inverse: >>> w = lambertw(1, k=3) >>> w @@ -267,11 +269,11 @@ def lambertw(z, k=0, tol=1e-8): >>> w*exp(w) (1.0 + 3.5075477124212226194278700785075126e-36j) - .. rubric:: Applications to equation-solving + **Applications to equation-solving** The Lambert W function may be used to solve various kinds of equations, such as finding the value of the infinite power - tower `z^{z^{z^{\ldots}}}`:: + tower :math:`z^{z^{z^{\ldots}}}`: >>> def tower(z, n): ... if n == 0: @@ -283,10 +285,10 @@ def lambertw(z, k=0, tol=1e-8): >>> -lambertw(-log(0.5))/log(0.5) 0.6411857445049859844862004821148236665628209571911 - .. rubric:: Properties + **Properties** The Lambert W function grows roughly like the natural logarithm - for large arguments:: + for large arguments: >>> lambertw(1000) 5.2496028524016 @@ -303,7 +305,7 @@ def lambertw(z, k=0, tol=1e-8): >>> nprint(taylor(lambertw, 0, 6), 10) [0.0, 1.0, -1.0, 1.5, -2.666666667, 5.208333333, -10.8] - Some special values and limits are:: + Some special values and limits are: >>> lambertw(0) 0.0 @@ -323,7 +325,7 @@ def lambertw(z, k=0, tol=1e-8): The `k = 0` and `k = -1` branches join at `z = -1/e` where `W(z) = -1` for both branches. Since `-1/e` can only be represented approximately with mpmath numbers, evaluating the Lambert W function - at this point only gives `-1` approximately:: + at this point only gives `-1` approximately: >>> lambertw(-1/e, 0) -0.999999999999837133022867 @@ -331,7 +333,7 @@ def lambertw(z, k=0, tol=1e-8): -1.00000000000016286697718 If `-1/e` happens to round in the negative direction, there might be - a small imaginary part:: + a small imaginary part: >>> lambertw(-1/e) (-1.0 + 8.22007971511612e-9j) diff --git a/scipy/stats/kde.py b/scipy/stats/kde.py index 86d440bf1b3a..47cecfa75239 100644 --- a/scipy/stats/kde.py +++ b/scipy/stats/kde.py @@ -140,7 +140,7 @@ class gaussian_kde(object): Examples -------- - Generate some random two-dimensional data:: + Generate some random two-dimensional data: >>> from scipy import stats >>> def measure(n): @@ -155,7 +155,7 @@ class gaussian_kde(object): >>> ymin = m2.min() >>> ymax = m2.max() - Perform a kernel density estimate on the data:: + Perform a kernel density estimate on the data: >>> X, Y = np.mgrid[xmin:xmax:100j, ymin:ymax:100j] >>> positions = np.vstack([X.ravel(), Y.ravel()]) @@ -163,8 +163,9 @@ class gaussian_kde(object): >>> kernel = stats.gaussian_kde(values) >>> Z = np.reshape(kernel(positions).T, X.shape) - Plot the results:: + Plot the results: + >>> import matplotlib.pyplot as plt >>> fig = plt.figure() >>> ax = fig.add_subplot(111) >>> ax.imshow(np.rot90(Z), cmap=plt.cm.gist_earth_r,