log1p()

A função log1p() no PHP calcula o logaritmo natural de 1 + x, escrito ln(1 + x), de forma que permanece precisa quando x está muito próximo de zero. Esta página aborda sua sintaxe, o problema de precisão que ela resolve, os valores retornados nas extremidades do seu domínio e quando usá-la em vez da log() comum.

Sintaxe

log1p(float $num): float

• $num — o valor adicionado a 1. Deve ser maior que -1 para um resultado finito.
• Valor de retorno — um float igual ao logaritmo natural (base e) de 1 + $num.

O que log1p() Faz

Matematicamente, log1p($num) é idêntico a log(1 + $num). A diferença está na precisão numérica. Os números de ponto flutuante têm precisão limitada, portanto, ao calcular 1 + $num para um $num muito pequeno, a maioria dos dígitos significativos de $num é perdida na adição antes mesmo de o logaritmo ser calculado. Isso é chamado de cancelamento catastrófico.

log1p() é implementada para calcular ln(1 + x) diretamente, sem formar a soma intermediária, de modo que esses dígitos são preservados. Para entradas pequenas, é a ferramenta correta; para entradas grandes, as duas funções concordam.

Exemplo Básico

Passamos um valor muito pequeno para log1p() e exibimos o resultado. A saída é o logaritmo natural de 1.0001, expresso em notação científica (9.9995...E-5 significa 0.000099995...).

Por que log1p() é Melhor que log(1 + $x) para Valores Pequenos

Compare as duas abordagens com a mesma entrada minúscula:

<?php
$x = 1e-15;

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

A resposta esperada é aproximadamente 1e-15. log1p() a retorna quase exatamente, enquanto log(1 + $x) é cerca de 11% maior, porque 1 + 1e-15 já arredonda incorretamente na aritmética de precisão dupla. Quanto menor a entrada, maior o erro relativo na versão ingênua — é exatamente por isso que log1p() existe.

Domínio e Casos Extremos

O argumento deve ser maior que -1. Observe como os limites se comportam:

<?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) retorna 0, pois ln(1) = 0.
• Em $num = -1, o valor interno é 0, e o logaritmo tende a menos infinito (-INF).
• Para $num < -1, o resultado é NAN (não é um número), porque o logaritmo de um valor não positivo é indefinido para números reais.

Proteja-se contra entradas inválidas antes de chamá-la:

<?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
?>

Quando Usar

log1p() é uma otimização de precisão, portanto compensa sempre que você trabalhar com quantidades próximas de zero:

• Finanças — converter uma pequena taxa de juros ou de crescimento r em uma taxa de juros compostos continuamente com log1p($r).
• Estatística e aprendizado de máquina — calcular log-probabilidades ou log-verossimilhanças em que os valores individuais são minúsculos.
• Computação científica — qualquer fórmula da forma ln(1 + x) em que x pode ser pequeno.

Para entradas comuns que não estão próximas de zero, log() é perfeitamente adequada; as duas retornam efetivamente o mesmo valor. A operação inversa — recuperar x de log1p(x) — é expm1(), que calcula e^x - 1 com o mesmo benefício de precisão.

Funções Relacionadas

• log() — logaritmo natural ou logaritmo em uma base arbitrária.
• log10() — logaritmo de base 10.
• exp() — e elevado a uma potência (o inverso de log()).
• expm1() — calcula e^x - 1 com precisão; o inverso de log1p().
• Funções Matemáticas PHP — visão geral da biblioteca matemática do PHP.

Conclusão

log1p() calcula ln(1 + x) preservando a precisão para entradas próximas de zero, onde o log(1 + $x) ingênuo perde precisão. Lembre-se de que o argumento deve ser maior que -1, que -1 resulta em -INF e que valores abaixo de -1 produzem NAN. Use-a em código financeiro, estatístico e científico sempre que valores pequenos estiverem envolvidos.

Prática