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$ function $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$ function (sometimes known as the ‘product log’ or ‘Omega’ function), which is the inverse function of
 $fw = wew for w∈C .$
The function $f$ is many-to-one, and so, except at $0$, $W$ is multivalued. nag_roots_lambertw_real (c05ba) 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}}=\mathit{true}$ on entry you inform nag_roots_lambertw_real (c05ba) 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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
If ${\mathbf{offset}}=\mathit{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}}=\mathit{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:     $\mathrm{branch}$int64int32nag_int scalar
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:     $\mathrm{offset}$ – logical scalar
Controls whether or not x is being specified as an offset from $-\mathrm{exp}\left(-1\right)$.

None.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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.

${\mathbf{ifail}}=1$
Constraint: ${\mathbf{branch}}=0$ or $-1$.
Constraint: if ${\mathbf{branch}}=-1$ and ${\mathbf{offset}}=\mathit{false}$ then ${\mathbf{x}}<0.0$.
Constraint: if ${\mathbf{branch}}=-1$ and ${\mathbf{offset}}=\mathit{true}$ then ${\mathbf{x}}<\mathrm{exp}\left(-1.0\right)$.
Constraint: if ${\mathbf{offset}}=\mathit{false}$ then ${\mathbf{x}}\ge -\mathrm{exp}\left(-1.0\right)$.
Constraint: if ${\mathbf{offset}}=\mathit{true}$ then ${\mathbf{x}}\ge 0.0$.
W  ${\mathbf{ifail}}=2$
For the given offset ${\mathbf{x}}$, $W$ is negligibly different from $-1$.
${\mathbf{x}}$ is close to $-\mathrm{exp}\left(-1\right)$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

For a high percentage of legal ${\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 ${\mathbf{x}}$. This depends on the accuracy of the base-$10$ logarithm on your system.

None.

## Example

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.
```function c05ba_example

fprintf('c05ba example results\n\n');

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

```
```c05ba example results

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
```