NAG Library Routine Document

C05BAF

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

C05BAF returns the real values of Lambert's

W

function

W (x)

, via the routine name.

2 Specification

FUNCTION C05BAF (

X, BRANCH, OFFSET, IFAIL)

REAL (KIND=nag_wp) C05BAF

INTEGER	BRANCH, IFAIL
REAL (KIND=nag_wp)	X
LOGICAL	OFFSET

3 Description

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) = w e^{w} for w \in 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 \geq - \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 (x) + 1

. We denote by

W_{0}

the branch satisfying

W_{0} (x) \geq - 1

for all real

x

, and by

W_{- 1}

the branch satisfying

W_{- 1} (x) \leq - 1

for all real

x

. You may select your branch of interest using the parameter 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) + Δ x)

rather than

W (x)

: by setting

OFFSET = .TRUE.

on entry you inform C05BAF that you are providing

Δ x

, not

x

, in X.

4 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

5 Parameters

1: X – REAL (KIND=nag_wp)Input

On entry: if

OFFSET = .TRUE.

, X is the offset

Δ x

from

- \exp (- 1)

of the intended argument to

W

; that is,

W (β)

is computed, where

β = - \exp (- 1) + Δ x

OFFSET = .FALSE.

, X is the argument

x

of the function; that is,

W (β)

is computed, where

β = x

Constraints:

if $BRANCH = 0$ , $- \exp (- 1) \leq β$ ;
if $BRANCH = - 1$ , $- \exp (- 1) \leq β < 0.0$ .

2: BRANCH – INTEGERInput

On entry: the real branch required.

$BRANCH = 0$: The branch $W_{0}$ is selected.
$BRANCH = - 1$: The branch $W_{- 1}$ is selected.

Constraint:

BRANCH = 0

- 1

3: OFFSET – LOGICALInput

On entry: controls whether or not X is being specified as an offset from

- \exp (- 1)

4: IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to

0

- 1 ​ or ​ 1

. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if

IFAIL \neq 0

on exit, the recommended value is

- 1

. When the value $- 1 or 1$ is used it is essential to test the value of IFAIL on exit.

On exit:

IFAIL = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

IFAIL = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by X04AAF).

Note: C05BAF may return useful information for one or more of the following detected errors or warnings.

Errors or warnings detected by the routine:

$IFAIL = 1$: An input parameter is invalid. If $IFAIL = 0$ or $- 1$ on entry, the output message provides more details of the nature of the warning.

$IFAIL = 2$: Warning: the actual argument to $W$ was very close to $- \exp (- 1)$ . The output message provides more details of the nature of the warning.

7 Accuracy

For a high percentage of legal

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

X

. This depends on the accuracy of the base-

10

logarithm on your system.

8 Further Comments

None.

9 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

- \exp (- 1)

, and the arguments

X

themselves. It then evaluates the function for these sets of input data

X

and prints the results.

NAG Library Routine DocumentC05BAF