NAG FL Interface
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 <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.

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 Integer Input
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 Logical Input
On entry: controls whether or not x is being specified as an offset from -exp-1.
4: 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 ifail0 on exit. 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).
Errors or warnings detected by the routine:
Note: in some cases c05baf may return useful information.
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 7 in the Introduction to the NAG Library FL Interface for further information.
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.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface 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)