R: Lambert W function, its logarithm and derivative

W {LambertW} | R Documentation

## 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 `lambertW0` and `lambertWm1` 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

`z` | a numeric vector of real values; note that `W(Inf, branch = 0) = Inf`.
`branch` | either `0` or `-1` for the principal or non-principal branch solution.
`W.z` | Lambert W function evaluated at `z`; see Details below for why this is useful.

### 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` / `lambertWm1` 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` / `lambertWm1`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))

[Package LambertW version 0.6.7 Index]