Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_roots_lambertw_real (c05ba)

## Purpose

nag_roots_lambertw_real (c05ba) returns the real values of Lambert's W$W$ function W(x)$W\left(x\right)$.

## Syntax

[result, ifail] = c05ba(x, branch, offset)
[result, ifail] = nag_roots_lambertw_real(x, branch, offset)

## Description

nag_roots_lambertw_real (c05ba) calculates an approximate value for the real branches of Lambert's W$W$ function (sometimes known as the ‘product log’ or ‘Omega’ function), which is the inverse function of
 f(w) = wew   for   w ∈ C . $f(w) = wew for w∈C .$
The function f$f$ is many-to-one, and so, except at 0$0$, W$W$ is multivalued. nag_roots_lambertw_real (c05ba) restricts W$W$ and its argument x$x$ to be real, resulting in a function defined for xexp(1)$x\ge -\mathrm{exp}\left(-1\right)$ and which is double valued on the interval (exp(1),0)$\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(x) + 1$W\left(x\right)+1$. We denote by W0${W}_{0}$ the branch satisfying W0(x)1${W}_{0}\left(x\right)\ge -1$ for all real x$x$, and by W1${W}_{-1}$ the branch satisfying W1(x)1${W}_{-1}\left(x\right)\le -1$ for all real x$x$. You may select your branch of interest using the parameter branch.
The precise method used to approximate W$W$ is described fully in Barry et al. (1995). For x$x$ close to exp(1)$-\mathrm{exp}\left(-1\right)$ greater accuracy comes from evaluating W(exp(1) + Δx)$W\left(-\mathrm{exp}\left(-1\right)+\Delta x\right)$ rather than W(x)$W\left(x\right)$: by setting offset = true${\mathbf{offset}}=\mathbf{true}$ on entry you inform nag_roots_lambertw_real (c05ba) that you are providing Δx$\Delta x$, not x$x$, in x.

## References

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

## Parameters

### Compulsory Input Parameters

1:     x – double scalar
If offset = true${\mathbf{offset}}=\mathbf{true}$, x is the offset Δx$\Delta x$ from exp(1)$-\mathrm{exp}\left(-1\right)$ of the intended argument to W$W$; that is, W(β)$W\left(\beta \right)$ is computed, where β = exp(1) + Δx$\beta =-\mathrm{exp}\left(-1\right)+\Delta x$.
If offset = false${\mathbf{offset}}=\mathbf{false}$, x is the argument x$x$ of the function; that is, W(β)$W\left(\beta \right)$ is computed, where β = x$\beta =x$.
Constraints:
• if branch = 0${\mathbf{branch}}=0$, exp(1)β$-\mathrm{exp}\left(-1\right)\le \beta$;
• if branch = 1${\mathbf{branch}}=-1$, exp(1)β < 0.0$-\mathrm{exp}\left(-1\right)\le \beta <0.0$.
2:     branch – int64int32nag_int scalar
The real branch required.
branch = 0${\mathbf{branch}}=0$
The branch W0${W}_{0}$ is selected.
branch = 1${\mathbf{branch}}=-1$
The branch W1${W}_{-1}$ is selected.
Constraint: branch = 0${\mathbf{branch}}=0$ or 1$-1$.
3:     offset – logical scalar
Controls whether or not x is being specified as an offset from exp(1)$-\mathrm{exp}\left(-1\right)$.

None.

None.

### Output Parameters

1:     result – double scalar
The result of the function.
2:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Note: nag_roots_lambertw_real (c05ba) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
An input parameter is invalid. .
W ifail = 2${\mathbf{ifail}}=2$
Warning: the actual argument to W$W$ was very close to exp(1)$-\mathrm{exp}\left(-1\right)$.

## Accuracy

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

None.

## Example

```function nag_roots_lambertw_real_example
branch = int64(0);
offset = false;
x = [0.5, 1.0, 4.5, 6.0, 7.0e7];
w = zeros(length(x),1);
ifails = zeros(length(x),1);
for i = 1:length(x)
[w(i), ifails(i)] = nag_roots_lambertw_real(x(i), branch, offset);
end
fprintf('\nBranch = %d\n', branch);
if offset
fprintf('Offset = true\n\n');
else
fprintf('Offset = false\n\n');
end
fprintf('      x            w(x)      ifail\n');
for i=1:5
fprintf('%13.5e %13.5e    %d\n', x(i), w(i), ifails(i));
end
```
```

Branch = 0
Offset = false

x            w(x)      ifail
5.00000e-01   3.51734e-01    0
1.00000e+00   5.67143e-01    0
4.50000e+00   1.26724e+00    0
6.00000e+00   1.43240e+00    0
7.00000e+07   1.53339e+01    0

```
```function c05ba_example
branch = int64(0);
offset = false;
x = [0.5, 1.0, 4.5, 6.0, 7.0e7];
w = zeros(length(x),1);
ifails = zeros(length(x),1);
for i = 1:length(x)
[w(i), ifails(i)] = c05ba(x(i), branch, offset);
end
fprintf('\nBranch = %d\n', branch);
if offset
fprintf('Offset = true\n\n');
else
fprintf('Offset = false\n\n');
end
fprintf('      x            w(x)      ifail\n');
for i=1:5
fprintf('%13.5e %13.5e    %d\n', x(i), w(i), ifails(i));
end
```
```

Branch = 0
Offset = false

x            w(x)      ifail
5.00000e-01   3.51734e-01    0
1.00000e+00   5.67143e-01    0
4.50000e+00   1.26724e+00    0
6.00000e+00   1.43240e+00    0
7.00000e+07   1.53339e+01    0

```