Lambert W function, its logarithm and derivative

Description

The Lambert W function W(z) = u is defined as the inverse of (see xexp)

u exp(u) = z,

i.e., it satisfies W(z) exp(W(z)) = z.

W evaluates the Lambert W function (W), its first derivative (deriv_W), and its logarithm (log_W). All of them have a principal (branch = 0 (default)) and non-principal branch (branch = -1) solution.

W is a wrapper for lambert_W0C and lambert_Wm1_C in the lamW package.

Usage

W(z, branch = 0)

deriv_W(z, branch = 0, W.z = W(z, branch = branch))

log_deriv_W(z, branch = 0, W.z = W(z, branch = branch))

deriv_log_W(z, branch = 0, W.z = W(z, branch = branch))

log_W(z, branch = 0, W.z = W(z, branch = branch))

Arguments

Details

Depending on the argument z of W(z) one can distinguish 3 cases:

z ≥q 0

solution is unique W(z) = W(z, branch = 0)

;

-1/e ≤q z < 0

two solutions: the principal (W(z, branch = 0)) and non-principal (W(z, branch = -1)) branch;

z < -1/e

no solution exists in the reals.

log_W computes the natural logarithm of W(z). This can be done efficiently since log W(z) = log z - W(z). Similarly, the derivative can be expressed as a function of W(z):

W'(z) = frac{1}{(1 + W(z)) exp(W(z))} = frac{W(z)}{z(1 + W(z))}.

Note that W'(0) = 1 and W'(-1/e) = ∞.

Moreover, by taking logs on both sides we can even simplify further to

log W'(z) = log W(z) - log z - log (1 + W(z))

which, since log W(z) = log z - W(z), simplifies to

log W'(z) = - W(z) - log (1 + W(z)).

For this reason it is numerically faster to pass the value of W(z) as an argument to deriv_W since W(z) often has already been evaluated in a previous step.

Value

numeric; same dimensions/size as z.

W returns numeric, Inf (for z = Inf), or NA if z < -1/e.

Note that W handles NaN differently to lambertW0_C and lambertWm1_C in the lamW package; it returns NA.

References

Corless, R. M., G. H. Gonnet, D. E. G. Hare, D. J. Jeffrey and D. E. Knuth (1996). “On the Lambert W function”. Advances in Computational Mathematics, pp. 329-359.

See Also

lambertW0_C and lambertWm1_C in the lamW package; xexp.

Examples

 
W(-0.25) # "reasonable" input event
W(-0.25, branch = -1) # "extreme" input event

curve(W(x, branch = -1), -1, 2, type = "l", col = 2, lwd = 2)
curve(W(x), -1, 2, type = "l", add = TRUE, lty = 2)
abline(v = - 1 / exp(1))

# For lower values, the principal branch gives the 'wrong' solution; 
# the non-principal must be used.
xexp(-10)
W(xexp(-10), branch = 0)
W(xexp(-10), branch = -1)
curve(log(x), 0.1, 5, lty = 2, col = 1, ylab = "")
curve(W(x), 0, 5, add = TRUE, col = "red")
curve(log_W(x), 0.1, 5, add = TRUE, col = "blue")
grid()
legend("bottomright", c("log(x)", "W(x)", "log(W(x))"),
       col = c("black", "red", "blue"), lty = c(2, 1, 1))

Results

R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(LambertW)
Loading required package: MASS
Loading required package: ggplot2
This is 'LambertW' version 0.6.4.  Please see the NEWS file and citation("LambertW").

> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/LambertW/W.Rd_%03d_medium.png", width=480, height=480)
> ### Name: W
> ### Title: Lambert W function, its logarithm and derivative
> ### Aliases: W deriv_W deriv_log_W log_W log_deriv_W
> ### Keywords: math
> 
> ### ** Examples
> 
>  
> W(-0.25) # "reasonable" input event
[1] -0.357403
> W(-0.25, branch = -1) # "extreme" input event
[1] -2.153292
> 
> curve(W(x, branch = -1), -1, 2, type = "l", col = 2, lwd = 2)
> curve(W(x), -1, 2, type = "l", add = TRUE, lty = 2)
> abline(v = - 1 / exp(1))
> 
> # For lower values, the principal branch gives the 'wrong' solution; 
> # the non-principal must be used.
> xexp(-10)
[1] -0.0004539993
> W(xexp(-10), branch = 0)
[1] -0.0004542056
> W(xexp(-10), branch = -1)
[1] -10
> curve(log(x), 0.1, 5, lty = 2, col = 1, ylab = "")
> curve(W(x), 0, 5, add = TRUE, col = "red")
> curve(log_W(x), 0.1, 5, add = TRUE, col = "blue")
> grid()
> legend("bottomright", c("log(x)", "W(x)", "log(W(x))"),
+        col = c("black", "red", "blue"), lty = c(2, 1, 1))
> 
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>