log1p()

La funzione log1p() in PHP calcola il logaritmo naturale di 1 + x, scritto ln(1 + x), in modo da mantenere la precisione anche quando x è molto vicino a zero. Questa pagina illustra la sintassi, il problema di precisione che risolve, i valori restituiti ai limiti del dominio e quando usarla al posto della comune log().

Sintassi

log1p(float $num): float

• $num — il valore aggiunto a 1. Deve essere maggiore di -1 per ottenere un risultato finito.
• Valore restituito — un float pari al logaritmo naturale (base e) di 1 + $num.

Cosa fa log1p()

Matematicamente, log1p($num) è identica a log(1 + $num). La differenza riguarda la precisione numerica. I numeri in virgola mobile hanno una precisione limitata, quindi quando si calcola 1 + $num per un $num molto piccolo, la maggior parte delle cifre significative di $num viene persa nell'addizione prima ancora che venga calcolato il logaritmo. Questo fenomeno è noto come cancellazione catastrofica.

log1p() è implementata per calcolare ln(1 + x) direttamente, senza formare la somma intermedia, così quelle cifre vengono conservate. Per input piccoli è lo strumento corretto; per input grandi le due funzioni concordano.

Esempio di base

Passiamo un valore molto piccolo a log1p() e stampiamo il risultato. L'output è il logaritmo naturale di 1.0001, espresso in notazione scientifica (9.9995...E-5 significa 0.000099995...).

Perché log1p() è migliore di log(1 + $x) per valori piccoli

Confrontiamo i due approcci sullo stesso input minuscolo:

<?php
$x = 1e-15;

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

Il risultato atteso è circa 1e-15. log1p() lo restituisce quasi esattamente, mentre log(1 + $x) è circa l'11% troppo grande perché 1 + 1e-15 si arrotonda già in modo errato nell'aritmetica a doppia precisione. Più piccolo è l'input, maggiore è l'errore relativo nella versione ingenua — ed è esattamente per questo che esiste log1p().

Dominio e casi limite

L'argomento deve essere maggiore di -1. Osserviamo il comportamento ai confini:

<?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) restituisce 0, poiché ln(1) = 0.
• Con $num = -1 il valore interno è 0, e il logaritmo tende a meno infinito (-INF).
• Per $num < -1 il risultato è NAN (non un numero), perché il logaritmo di un valore non positivo non è definito per i numeri reali.

Proteggersi dall'input non valido prima di chiamarla:

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

log1p() è un'ottimizzazione della precisione, quindi conviene usarla ogni volta che si lavora con quantità vicine a zero:

• Finanza — convertire un piccolo tasso di interesse o di crescita r in un tasso a capitalizzazione continua con log1p($r).
• Statistica e machine learning — calcolo di log-probabilità o log-verosimiglianze in cui i singoli valori sono minuscoli.
• Calcolo scientifico — qualsiasi formula della forma ln(1 + x) dove x può essere piccolo.

Per input ordinari non vicini a zero, log() va benissimo; le due funzioni restituiscono praticamente lo stesso valore. L'operazione inversa — recuperare x da log1p(x) — è expm1(), che calcola e^x - 1 con lo stesso beneficio di precisione.

Funzioni correlate

• log() — logaritmo naturale, o logaritmo a base arbitraria.
• log10() — logaritmo in base 10.
• exp() — e elevato a una potenza (l'inverso di log()).
• expm1() — calcola e^x - 1 con precisione; l'inverso di log1p().
• Funzioni matematiche PHP — panoramica della libreria matematica di PHP.

Conclusione

log1p() calcola ln(1 + x) preservando la precisione per input vicini a zero, dove la versione ingenua log(1 + $x) perde cifre significative. Ricordare che l'argomento deve essere maggiore di -1, che -1 restituisce -INF e che i valori inferiori a -1 producono NAN. Usarla in ambito finanziario, statistico e nel calcolo scientifico ogni volta che si gestiscono valori piccoli.

Esercitazione