From 5f96e28819793d763c74be94a3f17b2eca61f9b1 Mon Sep 17 00:00:00 2001
From: Karan Anand <anandkarancompsci@gmail.com>
Date: Thu, 27 Aug 2026 10:10:41 +0530
Subject: [PATCH] docs: add equations to exponential and logarithmic function
 READMEs

Add defining equations to the intro sections of exp2, exp10, expm1,
ln, log, log1p, log1mexp, log1pexp, log1pmx, xlogy, xlog1py and their
single-precision variants.

Ref: https://github.com/stdlib-js/metr-issue-tracker/issues/1257
---
 .../@stdlib/math/base/special/exp10/README.md  | 16 ++++++++++++++++
 .../@stdlib/math/base/special/exp2/README.md   | 16 ++++++++++++++++
 .../@stdlib/math/base/special/expm1/README.md  | 16 ++++++++++++++++
 .../@stdlib/math/base/special/ln/README.md     | 16 ++++++++++++++++
 .../@stdlib/math/base/special/lnf/README.md    | 16 ++++++++++++++++
 .../@stdlib/math/base/special/log/README.md    | 16 ++++++++++++++++
 .../math/base/special/log1mexp/README.md       | 16 ++++++++++++++++
 .../@stdlib/math/base/special/log1p/README.md  | 18 ++++++++++++++++++
 .../math/base/special/log1pexp/README.md       | 16 ++++++++++++++++
 .../@stdlib/math/base/special/log1pf/README.md | 18 ++++++++++++++++++
 .../math/base/special/log1pmx/README.md        | 16 ++++++++++++++++
 .../@stdlib/math/base/special/logf/README.md   | 16 ++++++++++++++++
 .../math/base/special/xlog1py/README.md        | 16 ++++++++++++++++
 .../@stdlib/math/base/special/xlogy/README.md  | 16 ++++++++++++++++
 .../@stdlib/math/base/special/xlogyf/README.md | 16 ++++++++++++++++
 15 files changed, 244 insertions(+)

diff --git a/lib/node_modules/@stdlib/math/base/special/exp10/README.md b/lib/node_modules/@stdlib/math/base/special/exp10/README.md
index 5a94d93e270d..6ecf9b31bcbd 100644
--- a/lib/node_modules/@stdlib/math/base/special/exp10/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/exp10/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Base `10` [exponential function][exponential-function].
 
+<section class="intro">
+
+The [base-10 exponential function][exponential-function] is defined as
+
+<!-- <equation class="equation" label="eq:base10_exponential_function" align="center" raw="y = 10^x" alt="Base-10 exponential function"> -->
+
+```math
+y = 10^x
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/exp2/README.md b/lib/node_modules/@stdlib/math/base/special/exp2/README.md
index d944a174807e..a489b17fbdfe 100644
--- a/lib/node_modules/@stdlib/math/base/special/exp2/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/exp2/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Base `2` [exponential function][exponential-function].
 
+<section class="intro">
+
+The [base-2 exponential function][exponential-function] is defined as
+
+<!-- <equation class="equation" label="eq:base2_exponential_function" align="center" raw="y = 2^x" alt="Base-2 exponential function"> -->
+
+```math
+y = 2^x
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/expm1/README.md b/lib/node_modules/@stdlib/math/base/special/expm1/README.md
index 8f4232ea6754..edbf6e1cc3da 100644
--- a/lib/node_modules/@stdlib/math/base/special/expm1/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/expm1/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Compute `exp(x) - 1`.
 
+<section class="intro">
+
+The function computes `exp(x) - 1` accurately for small `x`
+
+<!-- <equation class="equation" label="eq:expm1_function" align="center" raw="y = e^x - 1" alt="Exponential function minus one"> -->
+
+```math
+y = e^x - 1
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/ln/README.md b/lib/node_modules/@stdlib/math/base/special/ln/README.md
index 0c58bacc84f5..810ee79f4cb2 100644
--- a/lib/node_modules/@stdlib/math/base/special/ln/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/ln/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluate the [natural logarithm][natural-logarithm] of a double-precision floating-point number.
 
+<section class="intro">
+
+The [natural logarithm][natural-logarithm] is defined as
+
+<!-- <equation class="equation" label="eq:natural_logarithm" align="center" raw="y = \ln(x) = \log_e(x)" alt="Natural logarithm definition"> -->
+
+```math
+y = \ln(x) = \log_e(x)
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/lnf/README.md b/lib/node_modules/@stdlib/math/base/special/lnf/README.md
index e580f40f2873..74bf17931f26 100644
--- a/lib/node_modules/@stdlib/math/base/special/lnf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/lnf/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluate the [natural logarithm][natural-logarithm] of a single-precision floating-point number.
 
+<section class="intro">
+
+The [natural logarithm][natural-logarithm] is defined as
+
+<!-- <equation class="equation" label="eq:natural_logarithm" align="center" raw="y = \ln(x) = \log_e(x)" alt="Natural logarithm definition"> -->
+
+```math
+y = \ln(x) = \log_e(x)
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/log/README.md b/lib/node_modules/@stdlib/math/base/special/log/README.md
index 2ed02bcaaa66..43214cbc025c 100644
--- a/lib/node_modules/@stdlib/math/base/special/log/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/log/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Compute the base `b` [logarithm][logarithm] of a double-precision floating-point number.
 
+<section class="intro">
+
+The [logarithm][logarithm] with an arbitrary base is defined as
+
+<!-- <equation class="equation" label="eq:logarithm" align="center" raw="y = \log_b(x) \quad \text{such that} \quad b^y = x" alt="Logarithm with arbitrary base"> -->
+
+```math
+y = \log_b(x) \quad \text{such that} \quad b^y = x
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/log1mexp/README.md b/lib/node_modules/@stdlib/math/base/special/log1mexp/README.md
index a383a59300cb..9a0df1d66467 100644
--- a/lib/node_modules/@stdlib/math/base/special/log1mexp/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/log1mexp/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluates the [natural logarithm][@stdlib/math/base/special/ln] of `1-exp(-|x|)`.
 
+<section class="intro">
+
+The function computes the natural logarithm of `1-exp(-|x|)` accurately
+
+<!-- <equation class="equation" label="eq:log1mexp_function" align="center" raw="y = \ln(1 - e^{-|x|})" alt="Natural logarithm of one minus exponential"> -->
+
+```math
+y = \ln(1 - e^{-|x|})
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/log1p/README.md b/lib/node_modules/@stdlib/math/base/special/log1p/README.md
index 7a2dc1bce3bc..0cef75740f13 100644
--- a/lib/node_modules/@stdlib/math/base/special/log1p/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/log1p/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluate the [natural logarithm][@stdlib/math/base/special/ln] of `1+x`.
 
+<section class="intro">
+
+The function computes the [natural logarithm][natural-logarithm] of `1+x` accurately for small `x`
+
+<!-- <equation class="equation" label="eq:log1p_function" align="center" raw="y = \ln(1 + x)" alt="Natural logarithm of one plus x"> -->
+
+```math
+y = \ln(1 + x)
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
@@ -197,6 +213,8 @@ int main( void ) {
 
 <section class="links">
 
+[natural-logarithm]: https://en.wikipedia.org/wiki/Natural_logarithm
+
 <!-- <related-links> -->
 
 [@stdlib/math/base/special/ln]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/ln
diff --git a/lib/node_modules/@stdlib/math/base/special/log1pexp/README.md b/lib/node_modules/@stdlib/math/base/special/log1pexp/README.md
index 5fc3e1b148e9..b2ddb6bd639d 100644
--- a/lib/node_modules/@stdlib/math/base/special/log1pexp/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/log1pexp/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluates the [natural logarithm][@stdlib/math/base/special/ln] of `1+exp(x)`.
 
+<section class="intro">
+
+The function computes the natural logarithm of `1+exp(x)`, also known as the softplus function
+
+<!-- <equation class="equation" label="eq:log1pexp_function" align="center" raw="y = \ln(1 + e^x)" alt="Natural logarithm of one plus exponential"> -->
+
+```math
+y = \ln(1 + e^x)
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/log1pf/README.md b/lib/node_modules/@stdlib/math/base/special/log1pf/README.md
index 32d7c793b920..2e13c6585826 100644
--- a/lib/node_modules/@stdlib/math/base/special/log1pf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/log1pf/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluate the [natural logarithm][@stdlib/math/base/special/lnf] of `1+x` as a single‐precision floating-point number.
 
+<section class="intro">
+
+The function computes the [natural logarithm][natural-logarithm] of `1+x` accurately for small `x`
+
+<!-- <equation class="equation" label="eq:log1p_function" align="center" raw="y = \ln(1 + x)" alt="Natural logarithm of one plus x"> -->
+
+```math
+y = \ln(1 + x)
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
@@ -190,6 +206,8 @@ int main( void ) {
 
 <section class="links">
 
+[natural-logarithm]: https://en.wikipedia.org/wiki/Natural_logarithm
+
 [@stdlib/math/base/special/lnf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/lnf
 
 <!-- <related-links> -->
diff --git a/lib/node_modules/@stdlib/math/base/special/log1pmx/README.md b/lib/node_modules/@stdlib/math/base/special/log1pmx/README.md
index 0bff460fb6df..6d888e6eff27 100644
--- a/lib/node_modules/@stdlib/math/base/special/log1pmx/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/log1pmx/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Evaluate `ln(1+x) - x`.
 
+<section class="intro">
+
+The function computes `ln(1+x) - x` accurately for small `x`
+
+<!-- <equation class="equation" label="eq:log1pmx_function" align="center" raw="y = \ln(1 + x) - x" alt="Natural logarithm of one plus x minus x"> -->
+
+```math
+y = \ln(1 + x) - x
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/logf/README.md b/lib/node_modules/@stdlib/math/base/special/logf/README.md
index 99f1a74b25c5..bd1d574ac361 100644
--- a/lib/node_modules/@stdlib/math/base/special/logf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/logf/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Compute the base `b` [logarithm][logarithm] of a single-precision floating-point number.
 
+<section class="intro">
+
+The [logarithm][logarithm] with an arbitrary base is defined as
+
+<!-- <equation class="equation" label="eq:logarithm" align="center" raw="y = \log_b(x) \quad \text{such that} \quad b^y = x" alt="Logarithm with arbitrary base"> -->
+
+```math
+y = \log_b(x) \quad \text{such that} \quad b^y = x
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/xlog1py/README.md b/lib/node_modules/@stdlib/math/base/special/xlog1py/README.md
index af3e7619da3f..31f90801a369 100644
--- a/lib/node_modules/@stdlib/math/base/special/xlog1py/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/xlog1py/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Compute `x * ln(y+1)` so that the result is `0` if `x = 0`.
 
+<section class="intro">
+
+The function computes `x * ln(1+y)`, returning `0` when `x = 0`
+
+<!-- <equation class="equation" label="eq:xlog1py_function" align="center" raw="f(x, y) = \begin{cases} x \cdot \ln(1 + y) & \textrm{if}\ x \neq 0 \\ 0 & \textrm{if}\ x = 0 \end{cases}" alt="x times the natural logarithm of one plus y"> -->
+
+```math
+f(x, y) = \begin{cases} x \cdot \ln(1 + y) & \textrm{if}\ x \neq 0 \\ 0 & \textrm{if}\ x = 0 \end{cases}
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/xlogy/README.md b/lib/node_modules/@stdlib/math/base/special/xlogy/README.md
index 6347709a290c..e522d57b98ad 100644
--- a/lib/node_modules/@stdlib/math/base/special/xlogy/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/xlogy/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Compute `x * ln(y)` so that the result is `0` if `x = 0`.
 
+<section class="intro">
+
+The function computes `x * ln(y)`, returning `0` when `x = 0`
+
+<!-- <equation class="equation" label="eq:xlogy_function" align="center" raw="f(x, y) = \begin{cases} x \cdot \ln(y) & \textrm{if}\ x \neq 0 \\ 0 & \textrm{if}\ x = 0 \end{cases}" alt="x times the natural logarithm of y"> -->
+
+```math
+f(x, y) = \begin{cases} x \cdot \ln(y) & \textrm{if}\ x \neq 0 \\ 0 & \textrm{if}\ x = 0 \end{cases}
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/xlogyf/README.md b/lib/node_modules/@stdlib/math/base/special/xlogyf/README.md
index b905abe83725..07a8452d79ad 100644
--- a/lib/node_modules/@stdlib/math/base/special/xlogyf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/xlogyf/README.md
@@ -22,6 +22,22 @@ limitations under the License.
 
 > Compute `x * ln(y)` so that the result is `0` if `x = 0` for single-precision floating-point numbers `x` and `y`.
 
+<section class="intro">
+
+The function computes `x * ln(y)`, returning `0` when `x = 0`
+
+<!-- <equation class="equation" label="eq:xlogy_function" align="center" raw="f(x, y) = \begin{cases} x \cdot \ln(y) & \textrm{if}\ x \neq 0 \\ 0 & \textrm{if}\ x = 0 \end{cases}" alt="x times the natural logarithm of y"> -->
+
+```math
+f(x, y) = \begin{cases} x \cdot \ln(y) & \textrm{if}\ x \neq 0 \\ 0 & \textrm{if}\ x = 0 \end{cases}
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage