Signatur
Beschreibung
log1p() berechnet den Ausdruck log(1 + num), ist jedoch für sehr kleine Werte von num numerisch stabiler als die naive Variante log(1 + $num). Bei kleinen Werten nahe Null kann der direkte Ansatz wegen Gleitkomma-Rundungsfehlern signifikant ungenau werden, während log1p() eine spezialisierte Implementierung verwendet, die dieses Problem vermeidet.
Die Funktion wird häufig in wissenschaftlichen Berechnungen, Finanz- oder Wahrscheinlichkeitsanwendungen eingesetzt, wo kleine relative Änderungen (z. B. Zinssätze, Wachstumsraten) logarithmisch verarbeitet werden müssen. Typische Anwendungen umfassen Berechnungen wie kontinuierliche Zinseszinsrechnung oder Informationsgehalt in der Informationstheorie.
Für die Umkehrung steht die Funktion expm1() zur Verfügung, die exp(num) - 1 ebenso numerisch stabil berechnet. Beide Funktionen sind Gegenstücke zueinander und sollten gemeinsam eingesetzt werden, wenn höchste Präzision erforderlich ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $num Pflicht | float | Der Wert, für den log(1 + num) berechnet werden soll. Bei Werten kleiner als -1 gibt die Funktion NAN zurück, da der Logarithmus für nicht-positive Argumente undefiniert ist. |
Rückgabewert
log(1 + num) als Gleitkommazahl zurück. Bei num < -1 wird NAN zurückgegeben. Bei num = -1 wird -INF zurückgegeben.Beispiele
Vergleich mit naiver Implementierung bei kleinen Werten
<?php
$num = 1.0e-15;
// Naive Variante — kann durch Rundungsfehler ungenau sein
$naive = log(1 + $num);
// Numerisch stabile Variante
$stable = log1p($num);
echo 'Naiv: ' . $naive . PHP_EOL;
echo 'log1p: ' . $stable . PHP_EOL;
echo 'Erwartet (ca.): 1.0E-15' . PHP_EOL;Kontinuierliche Zinseszinsberechnung
<?php
// Berechnung des effektiven Jahreszinses aus einem nominalen Tageszinssatz
// Formel: r_eff = exp(n * log1p(r_tag)) - 1
$tagesRate = 0.0001; // 0,01 % pro Tag
$tage = 365;
$jahresRate = expm1($tage * log1p($tagesRate));
printf('Effektiver Jahreszins: %.4f %%' . PHP_EOL, $jahresRate * 100);Verhalten bei Randfällen
<?php
var_dump(log1p(0)); // log(1) = 0
var_dump(log1p(-1)); // log(0) = -INF
var_dump(log1p(-2)); // undefiniert -> NAN
var_dump(log1p(M_E - 1)); // log(e) = 1// Wichtig · Fallstricke
Numerische Stabilität: Die Verwendung von log(1 + $num) anstelle von log1p($num) kann bei sehr kleinen Werten (z. B. $num < 1e-10) zu erheblichen Genauigkeitsverlusten führen, da die Addition 1 + $num in Gleitkomma-Arithmetik die signifikanten Stellen von $num eliminiert. log1p() vermeidet dieses Problem durch eine spezialisierte Berechnung.
Bei $num < -1 ist das Argument des Logarithmus negativ, was im Reellen nicht definiert ist. In diesem Fall wird NAN zurückgegeben. Das Ergebnis sollte in solchen Szenarien stets mit is_nan() geprüft werden.