lambert_w

Fast and accurate evaluation of the real valued parts of the principal and secondary branches of the Lambert W function with the method of Toshio Fukushima.

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 crate provides two approximations of each branch, one with 50 bits of accuracy and one with 24 bits. The one with 50 bits of accuracy uses higher degree polynomials in the rational functions compared to the one with only 24 bits, and thus more of the multiplications and additions by constants.

While the approximation with 24 bits of accuracy is defined on 64 bit floats in the paper, this crate can also evaluate it on 32 bit floats for a slight reduction in accuracy. This reduction in accuracy has not been quantified by the author of this crate.

The crate is no_std, but can optionally depend on the standard library through features for a potential performance gain.

Examples

Compute the value of the Omega constant with the principal branch of the Lambert W function:

use lambert_w::lambert_w0;

let Ω = lambert_w0(1.0);

assert_abs_diff_eq!(Ω, 0.5671432904097839);

Evaluate the secondary branch of the Lambert W function at -ln(2)/2:

use lambert_w::lambert_wm1;

let mln4 = lambert_wm1(-f64::ln(2.0) / 2.0);

assert_abs_diff_eq!(mln4, -f64::ln(4.0));

Features

50bits (enabled by default): enables the function versions with 50 bits of accuracy on 64 bit floats.

24bits (enabled by default): enables the function versions with 24 bits of accuracy on 64 bit floats, as well as the implementation on 32 bit floats.

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.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.