Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/scipy/special/_lambertw.py : 67%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from ._ufuncs import _lambertw
4def lambertw(z, k=0, tol=1e-8):
5 r"""
6 lambertw(z, k=0, tol=1e-8)
8 Lambert W function.
10 The Lambert W function `W(z)` is defined as the inverse function
11 of ``w * exp(w)``. In other words, the value of ``W(z)`` is
12 such that ``z = W(z) * exp(W(z))`` for any complex number
13 ``z``.
15 The Lambert W function is a multivalued function with infinitely
16 many branches. Each branch gives a separate solution of the
17 equation ``z = w exp(w)``. Here, the branches are indexed by the
18 integer `k`.
20 Parameters
21 ----------
22 z : array_like
23 Input argument.
24 k : int, optional
25 Branch index.
26 tol : float, optional
27 Evaluation tolerance.
29 Returns
30 -------
31 w : array
32 `w` will have the same shape as `z`.
34 Notes
35 -----
36 All branches are supported by `lambertw`:
38 * ``lambertw(z)`` gives the principal solution (branch 0)
39 * ``lambertw(z, k)`` gives the solution on branch `k`
41 The Lambert W function has two partially real branches: the
42 principal branch (`k = 0`) is real for real ``z > -1/e``, and the
43 ``k = -1`` branch is real for ``-1/e < z < 0``. All branches except
44 ``k = 0`` have a logarithmic singularity at ``z = 0``.
46 **Possible issues**
48 The evaluation can become inaccurate very close to the branch point
49 at ``-1/e``. In some corner cases, `lambertw` might currently
50 fail to converge, or can end up on the wrong branch.
52 **Algorithm**
54 Halley's iteration is used to invert ``w * exp(w)``, using a first-order
55 asymptotic approximation (O(log(w)) or `O(w)`) as the initial estimate.
57 The definition, implementation and choice of branches is based on [2]_.
59 See Also
60 --------
61 wrightomega : the Wright Omega function
63 References
64 ----------
65 .. [1] https://en.wikipedia.org/wiki/Lambert_W_function
66 .. [2] Corless et al, "On the Lambert W function", Adv. Comp. Math. 5
67 (1996) 329-359.
68 https://cs.uwaterloo.ca/research/tr/1993/03/W.pdf
70 Examples
71 --------
72 The Lambert W function is the inverse of ``w exp(w)``:
74 >>> from scipy.special import lambertw
75 >>> w = lambertw(1)
76 >>> w
77 (0.56714329040978384+0j)
78 >>> w * np.exp(w)
79 (1.0+0j)
81 Any branch gives a valid inverse:
83 >>> w = lambertw(1, k=3)
84 >>> w
85 (-2.8535817554090377+17.113535539412148j)
86 >>> w*np.exp(w)
87 (1.0000000000000002+1.609823385706477e-15j)
89 **Applications to equation-solving**
91 The Lambert W function may be used to solve various kinds of
92 equations, such as finding the value of the infinite power
93 tower :math:`z^{z^{z^{\ldots}}}`:
95 >>> def tower(z, n):
96 ... if n == 0:
97 ... return z
98 ... return z ** tower(z, n-1)
99 ...
100 >>> tower(0.5, 100)
101 0.641185744504986
102 >>> -lambertw(-np.log(0.5)) / np.log(0.5)
103 (0.64118574450498589+0j)
104 """
105 return _lambertw(z, k, tol)