NAG FL Interface
c05baf (lambertw_​real)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

c05baf returns the real values of Lambert's W function W(x), 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
f(w) = 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 W(x)+1. We denote by W0 the branch satisfying W0(x)-1 for all real x, and by W-1 the branch satisfying W-1(x)-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 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 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)