NAG Library Routine Document

c05baf (lambertw_real)

1
Purpose

c05baf returns the real values of Lambert's W function Wx, via the routine name.

2
Specification

Fortran Interface
Function c05baf ( x, branch, offset, ifail)
Real (Kind=nag_wp):: c05baf
Integer, Intent (In):: branch
Integer, Intent (Inout):: ifail
Real (Kind=nag_wp), Intent (In):: x
Logical, Intent (In):: offset
C Header Interface
#include <nagmk26.h>
double  c05baf_ (const double *x, const Integer *branch, const logical *offset, Integer *ifail)

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
fw = wew   for   wC .  
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-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 Wx+1. We denote by W0 the branch satisfying W0x-1 for all real x, and by W-1 the branch satisfying W-1x-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+Δx rather than Wx: 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
Arguments

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.
If offset=.FALSE., x is the argument x of the function; that is, Wβ is computed, where β=x.
Constraints:
  • if branch=0, -exp-1β;
  • if branch=-1, -exp-1β<0.0.
2:     branch – IntegerInput
On entry: the real branch required.
branch=0
The branch W0 is selected.
branch=-1
The branch W-1 is selected.
Constraint: branch=0 or -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 argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation 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 arguments may be useful even if ifail0 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 or -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
On entry, branch=value.
Constraint: branch=0 or -1.
On entry, branch=-1, offset=.FALSE. and x=value.
Constraint: if branch=-1 and offset=.FALSE. then x<0.0.
On entry, branch=-1, offset=.TRUE. and x=value.
Constraint: if branch=-1 and offset=.TRUE. then x<exp-1.0.
On entry, offset=.FALSE. and x=value.
Constraint: if offset=.FALSE. then x-exp-1.0.
On entry, offset=.TRUE. and x=value.
Constraint: if offset=.TRUE. then x0.0.
ifail=2
For the given offset x, W is negligibly different from -1: x=value.
x is close to -exp-1. Enter x as an offset to -exp-1 for greater accuracy: x=value.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

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
Parallelism and Performance

c05baf is not threaded in any implementation.

9
Further Comments

None.

10
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.

10.1
Program Text

Program Text (c05bafe.f90)

10.2
Program Data

Program Data (c05bafe.d)

10.3
Program Results

Program Results (c05bafe.r)