# NAG FL Interfacec05baf (lambertw_​real)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

c05baf returns the real values of Lambert's $W$ function $W\left(x\right)$, via the routine name.

## 2Specification

Fortran Interface
 Function c05baf ( x,
 Real (Kind=nag_wp) :: c05baf Integer, Intent (In) :: branch Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: x Logical, Intent (In) :: offset
#include <nag.h>
 double c05baf_ (const double *x, const Integer *branch, const logical *offset, Integer *ifail)
The routine may be called by the names c05baf or nagf_roots_lambertw_real.

## 3Description

c05baf 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(w) = wew for w∈C .$
The function $f$ is many-to-one, and so, except at $0$, $W$ is multivalued. c05baf restricts $W$ and its argument $x$ to be real, resulting in a function defined for $x\ge -\mathrm{exp}\left(-1\right)$ and which is double valued on the interval $\left(-\mathrm{exp}\left(-1\right),0\right)$. 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 $-\mathrm{exp}\left(-1\right)$ greater accuracy comes from evaluating $W\left(-\mathrm{exp}\left(-1\right)+\Delta x\right)$ rather than $W\left(x\right)$: by setting ${\mathbf{offset}}=\mathrm{.TRUE.}$ on entry you inform c05baf that you are providing $\Delta x$, not $x$, in x.

## 4References

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

## 5Arguments

1: $\mathbf{x}$Real (Kind=nag_wp) Input
On entry: if ${\mathbf{offset}}=\mathrm{.TRUE.}$, x is the offset $\Delta x$ from $-\mathrm{exp}\left(-1\right)$ of the intended argument to $W$; that is, $W\left(\beta \right)$ is computed, where $\beta =-\mathrm{exp}\left(-1\right)+\Delta x$.
If ${\mathbf{offset}}=\mathrm{.FALSE.}$, x is the argument $x$ of the function; that is, $W\left(\beta \right)$ is computed, where $\beta =x$.
Constraints:
• if ${\mathbf{branch}}=0$, $-\mathrm{exp}\left(-1\right)\le \beta$;
• if ${\mathbf{branch}}=-1$, $-\mathrm{exp}\left(-1\right)\le \beta <0.0$.
2: $\mathbf{branch}$Integer Input
On entry: the real branch required.
${\mathbf{branch}}=0$
The branch ${W}_{0}$ is selected.
${\mathbf{branch}}=-1$
The branch ${W}_{-1}$ is selected.
Constraint: ${\mathbf{branch}}=0$ or $-1$.
3: $\mathbf{offset}$Logical Input
On entry: controls whether or not x is being specified as an offset from $-\mathrm{exp}\left(-1\right)$.
4: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when ${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
Note: in some cases c05baf may return useful information.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{branch}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{branch}}=0$ or $-1$.
On entry, ${\mathbf{branch}}=-1$, ${\mathbf{offset}}=\mathrm{.FALSE.}$ and ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{branch}}=-1$ and ${\mathbf{offset}}=\mathrm{.FALSE.}$ then ${\mathbf{x}}<0.0$.
On entry, ${\mathbf{branch}}=-1$, ${\mathbf{offset}}=\mathrm{.TRUE.}$ and ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{branch}}=-1$ and ${\mathbf{offset}}=\mathrm{.TRUE.}$ then ${\mathbf{x}}<\mathrm{exp}\left(-1.0\right)$.
On entry, ${\mathbf{offset}}=\mathrm{.FALSE.}$ and ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{offset}}=\mathrm{.FALSE.}$ then ${\mathbf{x}}\ge -\mathrm{exp}\left(-1.0\right)$.
On entry, ${\mathbf{offset}}=\mathrm{.TRUE.}$ and ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{offset}}=\mathrm{.TRUE.}$ then ${\mathbf{x}}\ge 0.0$.
${\mathbf{ifail}}=2$
For the given offset x, $W$ is negligibly different from $-1$: ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
x is close to $-\mathrm{exp}\left(-1\right)$. Enter x as an offset to $-\mathrm{exp}\left(-1\right)$ for greater accuracy: ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

For a high percentage of legal ${\mathbf{x}}$ on input, c05baf is accurate to the number of decimal digits of precision on the host machine (see x02bef). An extra digit may be lost on some implementations and for a small proportion of such ${\mathbf{x}}$. This depends on the accuracy of the base-$10$ logarithm on your system.

## 8Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
c05baf is not threaded in any implementation.

None.

## 10Example

This example reads from a file the values of the required branch, whether or not the arguments to $W$ are to be considered as offsets to $-\mathrm{exp}\left(-1\right)$, and the arguments ${\mathbf{x}}$ themselves. It then evaluates the function for these sets of input data ${\mathbf{x}}$ and prints the results.

### 10.1Program Text

Program Text (c05bafe.f90)

### 10.2Program Data

Program Data (c05bafe.d)

### 10.3Program Results

Program Results (c05bafe.r)