RFC: add support for evaluating log1mexp(x)

[kgryte]

Checklist

Please ensure the following tasks are completed before submitting a feature request.

• Read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

Description

Description of the feature request.

This RFC proposes to add support for evaluating ln( 1 - exp(x) ) in a more numerically stable manner. The conventional approaches of log1p( -exp(x) ) and ln( -exp1m(x) ) are subject to numerically stability issues when x approaches 0 and thus exp(x) approaches 1 in the former case and when x is large and -exp1m(x) approaches 1 in the latter case.

The proposed implementation would seek to divide the domain and provide appropriate approximations depending on the regime. In particular,

log1mexp(x) = ln( -expm1(-x) ); when 0 < x <= ln(2)
log1mexp(x) = log1p( -exp(-x) ); when x > ln(2)

Package: @stdlib/math/base/special/log1mexp
Alias: log1mexp

Related Issues

Does this feature request have any related issues?

No.

Questions

Any questions for reviewers?

No.

Other

Any other information relevant to this feature request? This may include screenshots, references, sample output, and/or implementation notes.

For further background, see associated numerical analysis.

[kgryte]

@rei2hu Given your work on #198, do you think you would be up for tackling this one, as well?

[rei2hu]

Sure it seems very similar. I actually just came across a problem trying to update my fork.

On line 66 of @stdlib/math/base/special/log1pexp/README.md the path to the module should be @stdlib/math/base/special/log1pexp instead of ./../lib.

[kgryte]

@rei2hu Awesome!

And yes, I already updated that on my current WIP branch. See here. :)

[rei2hu]

Great, I'll start working from there.

[kgryte]

To be clear, still work off of develop, as my WIP branch is currently broken for other reasons :(.