Updated Lambert W function implementation

LICENSE

@@ -22,3 +22,35 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+Portions of this code are derived from SciPy and are licensed under
+the Scipy License:
+
+> Copyright (c) 2001, 2002 Enthought, Inc.
+> All rights reserved.
+
+> Copyright (c) 2003-2012 SciPy Developers.
+> All rights reserved.
+
+> Redistribution and use in source and binary forms, with or without
+> modification, are permitted provided that the following conditions are met:
+
+>   a. Redistributions of source code must retain the above copyright notice,
+>      this list of conditions and the following disclaimer.
+>   b. Redistributions in binary form must reproduce the above copyright
+>      notice, this list of conditions and the following disclaimer in the
+>      documentation and/or other materials provided with the distribution.
+>   c. Neither the name of Enthought nor the names of the SciPy Developers
+>      may be used to endorse or promote products derived from this software
+>      without specific prior written permission.
+>
+> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+> AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+> IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+> ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS
+> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+> OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+> SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+> INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+> CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+> ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+> THE POSSIBILITY OF SUCH DAMAGE.

Project.toml

@@ -4,6 +4,7 @@ version = "2.2.0"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
+Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
 IrrationalConstants = "92d709cd-6900-40b7-9082-c6be49f344b6"
 LogExpFunctions = "2ab3a3ac-af41-5b50-aa03-7779005ae688"
 OpenLibm_jll = "05823500-19ac-5b8b-9628-191a04bc5112"
@@ -18,6 +19,7 @@ SpecialFunctionsChainRulesCoreExt = "ChainRulesCore"
 [compat]
 ChainRulesCore = "0.9.44, 0.10, 1"
 ChainRulesTestUtils = "0.6.8, 0.7, 1"
+Compat = "3.7, 4"
 IrrationalConstants = "0.1, 0.2"
 LogExpFunctions = "0.3.2"
 OpenLibm_jll = "0.7, 0.8"

README.md

@@ -1,7 +1,7 @@
 # SpecialFunctions.jl
 
 Special mathematical functions in Julia, including Bessel, Hankel, Airy, error, Dawson, exponential (or sine and cosine) integrals,
-eta, zeta, digamma, inverse digamma, trigamma, and polygamma functions.
+eta, zeta, Lambert's W, digamma, inverse digamma, trigamma, and polygamma functions.
 Most of these functions were formerly part of Base in early versions of Julia.
 
 CI (Linux, macOS, FreeBSD, Windows):

docs/src/functions_list.md

@@ -69,4 +69,7 @@ SpecialFunctions.beta
 SpecialFunctions.logbeta
 SpecialFunctions.logabsbeta
 SpecialFunctions.logabsbinomial
+SpecialFunctions.lambertw
+SpecialFunctions.lambertwbp
+SpecialFunctions.LambertW.Ω
 ```

docs/src/functions_overview.md

@@ -95,3 +95,9 @@ Here the *Special Functions* are listed according to the structure of [NIST Digi
 |:-------- |:----------- |
 | [`eta(x)`](@ref SpecialFunctions.eta)                         | [Dirichlet eta function](https://en.wikipedia.org/wiki/Dirichlet_eta_function) at `x`                                                                           |
 | [`zeta(x)`](@ref SpecialFunctions.zeta)                       | [Riemann zeta function](https://en.wikipedia.org/wiki/Riemann_zeta_function) at `x`                                                                             |
+
+## [Lambert's W Function](https://dlmf.nist.gov/4.13)
+| Function | Description |
+|:-------- |:----------- |
+| [`lambertw(x, [k=0])`](@ref SpecialFunctions.lambertw)        | [Lambert's W function](https://en.wikipedia.org/wiki/Lambert_W_function) at `x` for `k`-th branch   |
+| [`lambertwbp(x, [k=0])`](@ref SpecialFunctions.lambertwbp)    | Accurate value of ``1 + W_k(-\frac{1}{\mathrm{e}} + x)`` for small `x`                              |

src/SpecialFunctions.jl

@@ -1,5 +1,7 @@
 module SpecialFunctions
 
+using Compat
+
 using IrrationalConstants:
     twoπ,
     halfπ,
@@ -13,6 +15,9 @@ using IrrationalConstants:
     logπ,
     log2π
 
+# FIXME temporary until the fate of inve is decided
+Base.@irrational inve 0.367879441171442321595 inv(big(ℯ))
+
 import LogExpFunctions
 
 using OpenLibm_jll
@@ -77,7 +82,10 @@ export
     expintx,
     sinint,
     cosint,
-    lbinomial
+    lbinomial,
+    lambertw,
+    lambertwbp,
+    LambertW
 
 include("bessel.jl")
 include("erf.jl")
@@ -90,6 +98,7 @@ include("gamma.jl")
 include("gamma_inc.jl")
 include("betanc.jl")
 include("beta_inc.jl")
+include("lambertw.jl")
 if !isdefined(Base, :get_extension)
     include("../ext/SpecialFunctionsChainRulesCoreExt.jl")
 end