log1p()

The log1p() function in PHP computes the natural logarithm of 1 + x, written ln(1 + x), in a way that stays accurate when x is very close to zero. This page covers its syntax, the precision problem it solves, the values it returns at the edges of its domain, and when to reach for it instead of plain log().

Syntax

log1p(float $num): float

• $num — the value added to 1. Must be greater than -1 for a finite result.
• Return value — a float equal to the natural logarithm (base e) of 1 + $num.

What log1p() Does

Mathematically, log1p($num) is identical to log(1 + $num). The difference is numerical accuracy. Floating-point numbers have limited precision, so when you compute 1 + $num for a tiny $num, most of the significant digits of $num are lost in the addition before the logarithm is ever taken. This is called catastrophic cancellation.

log1p() is implemented to compute ln(1 + x) directly, without forming the intermediate sum, so those digits survive. For small inputs it is the correct tool; for large inputs the two functions agree.

Basic Example

We pass a very small value to log1p() and print the result. The output is the natural logarithm of 1.0001, expressed in scientific notation (9.9995...E-5 means 0.000099995...).

Why log1p() Beats log(1 + $x) for Small Values

Compare the two approaches on the same tiny input:

<?php
$x = 1e-15;

echo log1p($x), "\n";   // 1.0E-15               (accurate)
echo log(1 + $x), "\n"; // 1.1102230246252E-15  (wrong)
?>

The expected answer is approximately 1e-15. log1p() returns it almost exactly, while log(1 + $x) is about 11% too large because 1 + 1e-15 already rounds badly in double-precision arithmetic. The smaller the input, the larger the relative error in the naive version — which is exactly why log1p() exists.

Domain and Edge Cases

The argument must be greater than -1. Watch how the boundaries behave:

<?php
var_dump(log1p(0));      // float(0)     — ln(1) = 0
var_dump(log1p(M_E - 1)); // float(1)    — ln(e) = 1
var_dump(log1p(-1));     // float(-INF)  — ln(0) is negative infinity
var_dump(log1p(-2));     // float(NAN)   — undefined: 1 + (-2) = -1 < 0
?>

• log1p(0) returns 0, since ln(1) = 0.
• At $num = -1 the inner value is 0, and the logarithm tends to negative infinity (-INF).
• For $num < -1 the result is NAN (not a number), because the logarithm of a non-positive value is undefined for real numbers.

Guard against bad input before calling it:

<?php
function safeLog1p(float $num): ?float
{
    if ($num <= -1) {
        return null; // outside the valid domain
    }
    return log1p($num);
}

var_dump(safeLog1p(0.5));  // float(0.4054651081081644)
var_dump(safeLog1p(-1.5)); // NULL
?>

When to Use It

log1p() is a precision optimization, so it pays off whenever you work with quantities that hover near zero:

• Finance — converting a small interest or growth rate r to a continuously compounded rate with log1p($r).
• Statistics and machine learning — computing log-probabilities or log-likelihoods where individual values are minuscule.
• Scientific computing — any formula of the form ln(1 + x) where x can be small.

For everyday inputs that are not near zero, log() is perfectly fine; the two return effectively the same value. The inverse operation — recovering x from log1p(x) — is expm1(), which computes e^x - 1 with the same precision benefit.

Related Functions

• log() — natural logarithm, or logarithm to an arbitrary base.
• log10() — base-10 logarithm.
• exp() — e raised to a power (the inverse of log()).
• expm1() — computes e^x - 1 accurately; the inverse of log1p().
• PHP Math Functions — overview of PHP's math library.

Conclusion

log1p() calculates ln(1 + x) while preserving accuracy for inputs close to zero, where the naive log(1 + $x) loses precision. Remember that the argument must be greater than -1, that -1 yields -INF, and that values below -1 produce NAN. Reach for it in finance, statistics, and scientific code whenever small values are in play.

Practice