naginterfaces.library.roots.lambertw_​real

naginterfaces.library.roots.lambertw_real(x, branch, offset)

lambertw_real returns the real values of Lambert’s $W$ function $W\left(x\right)$.

For full information please refer to the NAG Library document for c05ba

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/c05/c05baf.html

Parameters

xfloat

If $offset=True$, $x$ is the offset $\Delta x$ from $-exp(-1)$ of the intended argument to $W$; that is, $W\left(\beta \right)$ is computed, where $\beta =-exp(-1)+\Delta x$.

If $offset=False$, $x$ is the argument $x$ of the function; that is, $W\left(\beta \right)$ is computed, where $\beta =x$.

branchint

The real branch required.

$branch=0$

The branch $W_0$ is selected.

$branch=-1$

The branch $W_{-1}$ is selected.

offsetbool

Controls whether or not $x$ is being specified as an offset from $-exp(-1)$.

Returns

lambwfloat

The real values of Lambert’s $W$ function $W\left(x\right)$.

Raises

NagValueError

(errno $1$)

On entry, $branch=⟨value⟩$.

Constraint: $branch=0$ or $-1$.

(errno $1$)

On entry, $offset=True$ and $x=⟨value⟩$.

Constraint: if $offset=True$ then $x\ge 0.0$.

(errno $1$)

On entry, $offset=False$ and $x=⟨value⟩$.

Constraint: if $offset=False$ then $x\ge -exp\left(-1.0\right)$.

(errno $1$)

On entry, $branch=-1$, $offset=True$ and $x=⟨value⟩$.

Constraint: if $branch=-1$ and $offset=True$ then $x<exp\left(-1.0\right)$.

(errno $1$)

On entry, $branch=-1$, $offset=False$ and $x=⟨value⟩$.

Constraint: if $branch=-1$ and $offset=False$ then $x<0.0$.

Warns

NagAlgorithmicWarning

(errno $2$)

For the given offset $x$, $W$ is negligibly different from $-1$: $x=⟨value⟩$.

(errno $2$)

$x$ is close to $-exp(-1)$. Enter $x$ as an offset to $-exp(-1)$ for greater accuracy: $x=⟨value⟩$.

Notes

lambertw_real calculates an approximate value for the real branches of Lambert’s $W$ function (sometimes known as the ‘product log’ or ‘Omega’ function), which is the inverse function of

$$f\left(w\right)=w{e}^w\text{for}w\in C\text{.}$$

The function $f$ is many-to-one, and so, except at $0$, $W$ is multivalued. lambertw_real restricts $W$ and its argument $x$ to be real, resulting in a function defined for $x\ge -exp(-1)$ and which is double valued on the interval $(-exp(-1),0)$. This double-valued function is split into two real-valued branches according to the sign of $W\left(x\right)+1$. We denote by $W_0$ the branch satisfying $W_0\left(x\right)\ge -1$ for all real $x$, and by $W_{-1}$ the branch satisfying $W_{-1}\left(x\right)\le -1$ for all real $x$. You may select your branch of interest using the argument $branch$.

The precise method used to approximate $W$ is described fully in Barry et al. (1995). For $x$ close to $-exp(-1)$ greater accuracy comes from evaluating $W(-exp(-1)+\Delta x)$ rather than $W\left(x\right)$: by setting $offset=True$ on entry you inform lambertw_real that you are providing $\Delta x$, not $x$, in $x$.

References

Barry, D J, Culligan–Hensley, P J, and Barry, S J, 1995, Real values of the $W$ -function, ACM Trans. Math. Software (21(2)), 161–171