log1p()

La fonction log1p() en PHP calcule le logarithme naturel de 1 + x, noté ln(1 + x), d'une manière qui reste précise lorsque x est très proche de zéro. Cette page couvre sa syntaxe, le problème de précision qu'elle résout, les valeurs qu'elle retourne aux extrémités de son domaine, et quand l'utiliser à la place de la fonction log() classique.

Syntaxe

log1p(float $num): float

• $num — la valeur ajoutée à 1. Doit être supérieure à -1 pour un résultat fini.
• Valeur de retour — un float égal au logarithme naturel (base e) de 1 + $num.

Ce que fait log1p()

Mathématiquement, log1p($num) est identique à log(1 + $num). La différence réside dans la précision numérique. Les nombres en virgule flottante ont une précision limitée ; ainsi, lorsque vous calculez 1 + $num pour un très petit $num, la plupart des chiffres significatifs de $num sont perdus lors de l'addition, avant même que le logarithme soit calculé. Ce phénomène s'appelle annulation catastrophique.

log1p() est implémentée pour calculer ln(1 + x) directement, sans former la somme intermédiaire, préservant ainsi ces chiffres. Pour les petites entrées, c'est le bon outil ; pour les grandes entrées, les deux fonctions donnent le même résultat.

Exemple de base

Nous passons une très petite valeur à log1p() et affichons le résultat. La sortie est le logarithme naturel de 1.0001, exprimé en notation scientifique (9.9995...E-5 signifie 0.000099995...).

Pourquoi log1p() est meilleur que log(1 + $x) pour les petites valeurs

Comparons les deux approches sur la même petite entrée :

<?php
$x = 1e-15;

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

La réponse attendue est approximativement 1e-15. log1p() la retourne presque exactement, tandis que log(1 + $x) est environ 11 % trop grand, car 1 + 1e-15 est déjà mal arrondi en arithmétique double précision. Plus l'entrée est petite, plus l'erreur relative de la version naïve est grande — c'est précisément la raison d'être de log1p().

Domaine et cas limites

L'argument doit être supérieur à -1. Voici comment se comportent les frontières :

<?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) retourne 0, puisque ln(1) = 0.
• Quand $num = -1, la valeur interne est 0, et le logarithme tend vers moins l'infini (-INF).
• Pour $num < -1, le résultat est NAN (pas un nombre), car le logarithme d'une valeur non positive est indéfini pour les nombres réels.

Protégez-vous contre les entrées invalides avant d'appeler la fonction :

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

Quand l'utiliser

log1p() est une optimisation de précision, elle est donc utile dès que vous travaillez avec des quantités proches de zéro :

• Finance — convertir un petit taux d'intérêt ou de croissance r en taux composé en continu avec log1p($r).
• Statistiques et apprentissage automatique — calculer des log-probabilités ou des log-vraisemblances où les valeurs individuelles sont minuscules.
• Calcul scientifique — toute formule de la forme ln(1 + x) où x peut être petit.

Pour les entrées courantes qui ne sont pas proches de zéro, log() convient parfaitement ; les deux retournent pratiquement la même valeur. L'opération inverse — retrouver x à partir de log1p(x) — est expm1(), qui calcule e^x - 1 avec le même avantage de précision.

Fonctions associées

• log() — logarithme naturel, ou logarithme dans une base arbitraire.
• log10() — logarithme en base 10.
• exp() — e élevé à une puissance (l'inverse de log()).
• expm1() — calcule e^x - 1 avec précision ; l'inverse de log1p().
• Fonctions mathématiques PHP — aperçu de la bibliothèque mathématique de PHP.

Conclusion

log1p() calcule ln(1 + x) tout en préservant la précision pour les entrées proches de zéro, là où le naïf log(1 + $x) perd en précision. N'oubliez pas que l'argument doit être supérieur à -1, que -1 produit -INF, et que les valeurs inférieures à -1 donnent NAN. Utilisez-la en finance, en statistiques et dans le code scientifique chaque fois que de petites valeurs entrent en jeu.

Pratique