Crate lambert_w

Fast evaluation of the real valued parts of the principal and secondary branches of the Lambert W function using the method of Toshio Fukushima to either 24 or 50 bits of accuracy.

This method works by splitting the domain of the function into subdomains, and on each subdomain it uses a rational function evaluated on a simple transformation of the input to describe the function.
It is implemented in code as conditional switches on the input value followed by either a square root (and possibly a division) or a logarithm and then a series of multiplications and additions by fixed constants and finished with a division.

The functions with 50 bits of accuracy use higher degree polynomials in the rational functions, and thus more of the multiplications and additions by constants.

#![no_std] compatible.

Examples

Compute the value of the Omega constant with the principal branch of the Lambert W function to 50 bits of accuracy:

use lambert_w::lambert_w0;

let Ω = lambert_w0(1.0);

assert_abs_diff_eq!(Ω, 0.5671432904097838);

or to only 24 bits of accuracy, but with faster execution time:

use lambert_w::sp_lambert_w0;

let Ω = sp_lambert_w0(1.0);

assert_abs_diff_eq!(Ω, 0.5671432904097838, epsilon = 1e-7);

Evaluate the secondary branch of the Lambert W function at -ln(2)/2 to 50 and 24 bits of accuracy:

use lambert_w::{lambert_wm1, sp_lambert_wm1};

let z = -f64::ln(2.0) / 2.0;

let mln4_50b = lambert_wm1(z);
let mln4_24b = sp_lambert_wm1(z);

assert_abs_diff_eq!(mln4_50b, -f64::ln(4.0));
assert_abs_diff_eq!(mln4_24b, -f64::ln(4.0), epsilon = 1e-9);

The macro is from the approx crate, and is used in the documentation examples of this crate. The assertion passes if the two supplied values are the same to within floating point error, or within an optional epsilon.

Features

50bits (enabled by default): enables the more accurate function versions with 50 bits of accuracy.

24bits (enabled by default): enables the faster function versions with 24 bits of accuracy.

You can disable one of the above features to potentially save a little bit of binary size.

estrin: uses Estrin’s scheme to evaluate the polynomials in the rational functions. While this results in more assembly instructions, they are mostly independent of each other, and this increases instruction level parallelism on modern hardware for a total performance gain. May result in slight numerical instability, which can be reduced if the target CPU has fused multiply-add instructions.

One of the below features must be enabled:

std: use the standard library to compute square roots and logarithms for a potential performance gain. When this feature is disabled the crate is no_std.

libm (enabled by default): if the std feature is disabled, this feature uses the libm crate to compute square roots and logarithms instead of the standard library.

Constants

• NEG_INV_E
  The negative inverse of e (-1/e).
• OMEGA
  The Omega constant (Ω).

Functions

• lambert_w050bits
  The principal branch of the Lambert W function computed to 50 bits of accuracy.
• lambert_wm150bits
  The secondary branch of the Lambert W function computed to 50 bits of accuracy.
• sp_lambert_w024bits
  The principal branch of the Lambert W function computed to 24 bits of accuracy.
• sp_lambert_wm124bits
  The secondary branch of the Lambert W function computed to 24 bits of accuracy.