From 7abaf6e6a745b5f24a36940a651b777c02a944da Mon Sep 17 00:00:00 2001 From: Karan Anand Date: Thu, 27 Aug 2026 11:15:49 +0530 Subject: [PATCH] docs: add equations to utility function READMEs Add defining equations to the intro sections of abs2, cbrt, clamp, copysign, flipsign, hypot, ldexp, frexp, modf, pdiff, deg2rad, rad2deg, sqrt1pm1, sqrtpi, wrap, rempio2 and their single-precision variants. Ref: https://github.com/stdlib-js/metr-issue-tracker/issues/1257 --- .../@stdlib/math/base/special/abs2/README.md | 10 ++++++++++ .../@stdlib/math/base/special/abs2f/README.md | 10 ++++++++++ .../@stdlib/math/base/special/cbrt/README.md | 16 ++++++++++++++++ .../@stdlib/math/base/special/cbrtf/README.md | 16 ++++++++++++++++ .../@stdlib/math/base/special/clamp/README.md | 10 ++++++++++ .../@stdlib/math/base/special/clampf/README.md | 10 ++++++++++ .../math/base/special/copysign/README.md | 14 ++++++++++++++ .../math/base/special/copysignf/README.md | 14 ++++++++++++++ .../math/base/special/deg2rad/README.md | 14 ++++++++++++++ .../math/base/special/deg2radf/README.md | 14 ++++++++++++++ .../math/base/special/flipsign/README.md | 14 ++++++++++++++ .../math/base/special/flipsignf/README.md | 14 ++++++++++++++ .../@stdlib/math/base/special/frexp/README.md | 18 ++++++++++++++++++ .../@stdlib/math/base/special/frexpf/README.md | 18 ++++++++++++++++++ .../@stdlib/math/base/special/hypot/README.md | 10 ++++++++++ .../@stdlib/math/base/special/hypotf/README.md | 10 ++++++++++ .../@stdlib/math/base/special/ldexp/README.md | 14 ++++++++++++++ .../@stdlib/math/base/special/ldexpf/README.md | 14 ++++++++++++++ .../@stdlib/math/base/special/modf/README.md | 18 ++++++++++++++++++ .../@stdlib/math/base/special/modff/README.md | 18 ++++++++++++++++++ .../@stdlib/math/base/special/pdiff/README.md | 10 ++++++++++ .../@stdlib/math/base/special/pdifff/README.md | 10 ++++++++++ .../math/base/special/rad2deg/README.md | 14 ++++++++++++++ .../math/base/special/rad2degf/README.md | 14 ++++++++++++++ .../math/base/special/rempio2/README.md | 18 ++++++++++++++++++ .../math/base/special/rempio2f/README.md | 18 ++++++++++++++++++ .../math/base/special/sqrt1pm1/README.md | 16 ++++++++++++++++ .../@stdlib/math/base/special/sqrtpi/README.md | 18 ++++++++++++++++++ .../math/base/special/sqrtpif/README.md | 18 ++++++++++++++++++ .../@stdlib/math/base/special/wrap/README.md | 12 ++++++++++++ .../@stdlib/math/base/special/wrapf/README.md | 12 ++++++++++++ 31 files changed, 436 insertions(+) diff --git a/lib/node_modules/@stdlib/math/base/special/abs2/README.md b/lib/node_modules/@stdlib/math/base/special/abs2/README.md index 56e121a9cb47..e9d96b4f578c 100644 --- a/lib/node_modules/@stdlib/math/base/special/abs2/README.md +++ b/lib/node_modules/@stdlib/math/base/special/abs2/README.md @@ -24,6 +24,16 @@ limitations under the License.
+The squared [absolute value][absolute-value] is defined as + + + +```math +y = |x|^2 = x^2 +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/abs2f/README.md b/lib/node_modules/@stdlib/math/base/special/abs2f/README.md index 62ae7a143f86..8041be2fc825 100644 --- a/lib/node_modules/@stdlib/math/base/special/abs2f/README.md +++ b/lib/node_modules/@stdlib/math/base/special/abs2f/README.md @@ -24,6 +24,16 @@ limitations under the License.
+The squared [absolute value][absolute-value] is defined as + + + +```math +y = |x|^2 = x^2 +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/cbrt/README.md b/lib/node_modules/@stdlib/math/base/special/cbrt/README.md index 07232414ee46..5e61ec70414c 100644 --- a/lib/node_modules/@stdlib/math/base/special/cbrt/README.md +++ b/lib/node_modules/@stdlib/math/base/special/cbrt/README.md @@ -22,6 +22,22 @@ limitations under the License. > Compute the [cube root][cube-root] of a double-precision floating-point number. +
+ +The [cube root][cube-root] function is defined as + + + +```math +y = \sqrt[3]{x} +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/cbrtf/README.md b/lib/node_modules/@stdlib/math/base/special/cbrtf/README.md index 70f81c2ab74c..fc53d9ffb657 100644 --- a/lib/node_modules/@stdlib/math/base/special/cbrtf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/cbrtf/README.md @@ -22,6 +22,22 @@ limitations under the License. > Compute the [cube root][cube-root] of a single-precision floating-point number. +
+ +The [cube root][cube-root] function is defined as + + + +```math +y = \sqrt[3]{x} +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/clamp/README.md b/lib/node_modules/@stdlib/math/base/special/clamp/README.md index 7d94fa6337d6..32445aefa86d 100644 --- a/lib/node_modules/@stdlib/math/base/special/clamp/README.md +++ b/lib/node_modules/@stdlib/math/base/special/clamp/README.md @@ -26,6 +26,16 @@ limitations under the License.
+The clamp function restricts a value to a specified range `[min, max]` + + + +```math +y = \mathop{\mathrm{clamp}}(x, a, b) = \begin{cases} a & \textrm{if}\ x < a \\ x & \textrm{if}\ a \leq x \leq b \\ b & \textrm{if}\ x > b \end{cases} +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/clampf/README.md b/lib/node_modules/@stdlib/math/base/special/clampf/README.md index f051d9a42ad7..404bb0668fb4 100644 --- a/lib/node_modules/@stdlib/math/base/special/clampf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/clampf/README.md @@ -26,6 +26,16 @@ limitations under the License.
+The clamp function restricts a value to a specified range `[min, max]` + + + +```math +y = \mathop{\mathrm{clamp}}(x, a, b) = \begin{cases} a & \textrm{if}\ x < a \\ x & \textrm{if}\ a \leq x \leq b \\ b & \textrm{if}\ x > b \end{cases} +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/copysign/README.md b/lib/node_modules/@stdlib/math/base/special/copysign/README.md index 2d0206f1efe8..f9af467bb030 100644 --- a/lib/node_modules/@stdlib/math/base/special/copysign/README.md +++ b/lib/node_modules/@stdlib/math/base/special/copysign/README.md @@ -22,6 +22,20 @@ limitations under the License. > Return a [double-precision floating-point number][ieee754] with the magnitude of `x` and the sign of `y`. +
+ + + +```math +z = |x| \cdot \mathop{\mathrm{sign}}(y) +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/copysignf/README.md b/lib/node_modules/@stdlib/math/base/special/copysignf/README.md index df90de263420..acf5404cc84f 100644 --- a/lib/node_modules/@stdlib/math/base/special/copysignf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/copysignf/README.md @@ -22,6 +22,20 @@ limitations under the License. > Return a [single-precision floating-point number][ieee754] with the magnitude of `x` and the sign of `y`. +
+ + + +```math +z = |x| \cdot \mathop{\mathrm{sign}}(y) +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/deg2rad/README.md b/lib/node_modules/@stdlib/math/base/special/deg2rad/README.md index e9577063e970..36912b0e73d0 100644 --- a/lib/node_modules/@stdlib/math/base/special/deg2rad/README.md +++ b/lib/node_modules/@stdlib/math/base/special/deg2rad/README.md @@ -22,6 +22,20 @@ limitations under the License. > Convert an angle from degrees to radians. +
+ + + +```math +r = x \cdot \frac{\pi}{180} +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/deg2radf/README.md b/lib/node_modules/@stdlib/math/base/special/deg2radf/README.md index e13a0f3107af..8df49355460e 100644 --- a/lib/node_modules/@stdlib/math/base/special/deg2radf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/deg2radf/README.md @@ -22,6 +22,20 @@ limitations under the License. > Convert an angle from degrees to radians (single-precision). +
+ + + +```math +r = x \cdot \frac{\pi}{180} +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/flipsign/README.md b/lib/node_modules/@stdlib/math/base/special/flipsign/README.md index b10446e37d10..6d5f0ceeb276 100644 --- a/lib/node_modules/@stdlib/math/base/special/flipsign/README.md +++ b/lib/node_modules/@stdlib/math/base/special/flipsign/README.md @@ -22,6 +22,20 @@ limitations under the License. > Return a [double-precision floating-point number][ieee754] with the magnitude of `x` and the sign of `x*y`. +
+ + + +```math +z = x \cdot \mathop{\mathrm{sign}}(y) +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/flipsignf/README.md b/lib/node_modules/@stdlib/math/base/special/flipsignf/README.md index b02f15b47f81..53b58f90d1ac 100644 --- a/lib/node_modules/@stdlib/math/base/special/flipsignf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/flipsignf/README.md @@ -22,6 +22,20 @@ limitations under the License. > Return a [single-precision floating-point number][ieee754] with the magnitude of `x` and the sign of `x*y`. +
+ + + +```math +z = x \cdot \mathop{\mathrm{sign}}(y) +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/frexp/README.md b/lib/node_modules/@stdlib/math/base/special/frexp/README.md index 46223e7af7c4..0d04503a3140 100644 --- a/lib/node_modules/@stdlib/math/base/special/frexp/README.md +++ b/lib/node_modules/@stdlib/math/base/special/frexp/README.md @@ -22,6 +22,24 @@ limitations under the License. > Split a [double-precision floating-point number][ieee754] into a normalized fraction and an integer power of two. +
+ +The function splits a floating-point number into a normalized fraction and an integer power of two + + + +```math +x = f \cdot 2^{\,e} +``` + + + +where `f` is the normalized fraction (with `0.5 <= |f| < 1`) and `e` is an integer exponent. + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/frexpf/README.md b/lib/node_modules/@stdlib/math/base/special/frexpf/README.md index 4bbeb02041cc..ea11417af8c7 100644 --- a/lib/node_modules/@stdlib/math/base/special/frexpf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/frexpf/README.md @@ -22,6 +22,24 @@ limitations under the License. > Split a [single-precision floating-point number][ieee754] into a normalized fraction and an integer power of two. +
+ +The function splits a floating-point number into a normalized fraction and an integer power of two + + + +```math +x = f \cdot 2^{\,e} +``` + + + +where `f` is the normalized fraction (with `0.5 <= |f| < 1`) and `e` is an integer exponent. + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/hypot/README.md b/lib/node_modules/@stdlib/math/base/special/hypot/README.md index 3167d07d433e..5a610598014a 100644 --- a/lib/node_modules/@stdlib/math/base/special/hypot/README.md +++ b/lib/node_modules/@stdlib/math/base/special/hypot/README.md @@ -26,6 +26,16 @@ limitations under the License.
+The [hypotenuse][hypotenuse] function computes the length of the hypotenuse of a right triangle + + + +```math +h = \sqrt{x^2 + y^2} +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/hypotf/README.md b/lib/node_modules/@stdlib/math/base/special/hypotf/README.md index 5fc08d9b42e4..7a41ab11b33b 100644 --- a/lib/node_modules/@stdlib/math/base/special/hypotf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/hypotf/README.md @@ -26,6 +26,16 @@ limitations under the License.
+The [hypotenuse][hypotenuse] function computes the length of the hypotenuse of a right triangle + + + +```math +h = \sqrt{x^2 + y^2} +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/ldexp/README.md b/lib/node_modules/@stdlib/math/base/special/ldexp/README.md index 195f47fb00c0..7f9efe1f9e81 100644 --- a/lib/node_modules/@stdlib/math/base/special/ldexp/README.md +++ b/lib/node_modules/@stdlib/math/base/special/ldexp/README.md @@ -22,6 +22,20 @@ limitations under the License. > Multiply a [double-precision floating-point number][ieee754] by an integer power of two. +
+ + + +```math +y = x \cdot 2^n +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/ldexpf/README.md b/lib/node_modules/@stdlib/math/base/special/ldexpf/README.md index bfdef1f41706..f2b9498edb28 100644 --- a/lib/node_modules/@stdlib/math/base/special/ldexpf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/ldexpf/README.md @@ -22,6 +22,20 @@ limitations under the License. > Multiply a [single-precision floating-point number][ieee754] by an integer power of two. +
+ + + +```math +y = x \cdot 2^n +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/modf/README.md b/lib/node_modules/@stdlib/math/base/special/modf/README.md index f68c58ed90d5..e09c857b92a3 100644 --- a/lib/node_modules/@stdlib/math/base/special/modf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/modf/README.md @@ -22,6 +22,24 @@ limitations under the License. > Decompose a [double-precision floating-point number][ieee754] into integral and fractional parts. +
+ +The function decomposes a floating-point number into integer and fractional parts + + + +```math +x = i + f +``` + + + +where `i` is the integer part and `f` is the fractional part having the same sign as `x`. + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/modff/README.md b/lib/node_modules/@stdlib/math/base/special/modff/README.md index 07240d2aedc2..3f5ef5992f81 100644 --- a/lib/node_modules/@stdlib/math/base/special/modff/README.md +++ b/lib/node_modules/@stdlib/math/base/special/modff/README.md @@ -22,6 +22,24 @@ limitations under the License. > Decompose a [single-precision floating-point number][ieee754] into integral and fractional parts. +
+ +The function decomposes a floating-point number into integer and fractional parts + + + +```math +x = i + f +``` + + + +where `i` is the integer part and `f` is the fractional part having the same sign as `x`. + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/pdiff/README.md b/lib/node_modules/@stdlib/math/base/special/pdiff/README.md index 16fe06798505..2a982778b473 100644 --- a/lib/node_modules/@stdlib/math/base/special/pdiff/README.md +++ b/lib/node_modules/@stdlib/math/base/special/pdiff/README.md @@ -26,6 +26,16 @@ limitations under the License.
+The [positive difference][fdim] function is defined as + + + +```math +z = \max(x - y, 0) +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/pdifff/README.md b/lib/node_modules/@stdlib/math/base/special/pdifff/README.md index 0be8c5593b34..30c9de3a9561 100644 --- a/lib/node_modules/@stdlib/math/base/special/pdifff/README.md +++ b/lib/node_modules/@stdlib/math/base/special/pdifff/README.md @@ -26,6 +26,16 @@ limitations under the License.
+The [positive difference][fdim] function is defined as + + + +```math +z = \max(x - y, 0) +``` + + +
diff --git a/lib/node_modules/@stdlib/math/base/special/rad2deg/README.md b/lib/node_modules/@stdlib/math/base/special/rad2deg/README.md index 4317fcc75b34..634bd6400381 100644 --- a/lib/node_modules/@stdlib/math/base/special/rad2deg/README.md +++ b/lib/node_modules/@stdlib/math/base/special/rad2deg/README.md @@ -22,6 +22,20 @@ limitations under the License. > Convert an angle from radians to degrees. +
+ + + +```math +d = x \cdot \frac{180}{\pi} +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/rad2degf/README.md b/lib/node_modules/@stdlib/math/base/special/rad2degf/README.md index f695884b3518..282125bfcd2d 100644 --- a/lib/node_modules/@stdlib/math/base/special/rad2degf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/rad2degf/README.md @@ -22,6 +22,20 @@ limitations under the License. > Convert an angle from radians to degrees (single-precision). +
+ + + +```math +d = x \cdot \frac{180}{\pi} +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/rempio2/README.md b/lib/node_modules/@stdlib/math/base/special/rempio2/README.md index 978033ba6f65..420ce7eb3541 100644 --- a/lib/node_modules/@stdlib/math/base/special/rempio2/README.md +++ b/lib/node_modules/@stdlib/math/base/special/rempio2/README.md @@ -22,6 +22,24 @@ limitations under the License. > Compute `x - nπ/2 = r`. +
+ +The function computes `x - nπ/2 = r` for argument reduction + + + +```math +r = x - n \cdot \frac{\pi}{2} +``` + + + +where `n` is the integer nearest to `2x/π` and `r` is the remainder. + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/rempio2f/README.md b/lib/node_modules/@stdlib/math/base/special/rempio2f/README.md index ddef36c87d35..78074378bb9c 100644 --- a/lib/node_modules/@stdlib/math/base/special/rempio2f/README.md +++ b/lib/node_modules/@stdlib/math/base/special/rempio2f/README.md @@ -22,6 +22,24 @@ limitations under the License. > Compute `x - nπ/2 = r` (single-precision). +
+ +The function computes `x - nπ/2 = r` for argument reduction + + + +```math +r = x - n \cdot \frac{\pi}{2} +``` + + + +where `n` is the integer nearest to `2x/π` and `r` is the remainder. + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/sqrt1pm1/README.md b/lib/node_modules/@stdlib/math/base/special/sqrt1pm1/README.md index c295405e46c2..c66d1f24149a 100644 --- a/lib/node_modules/@stdlib/math/base/special/sqrt1pm1/README.md +++ b/lib/node_modules/@stdlib/math/base/special/sqrt1pm1/README.md @@ -22,6 +22,22 @@ limitations under the License. > Compute `sqrt( 1 + x ) - 1`. +
+ +The function computes `sqrt(1+x) - 1` accurately for small `x` + + + +```math +y = \sqrt{1 + x} - 1 +``` + + + +
+ + +
## Usage diff --git a/lib/node_modules/@stdlib/math/base/special/sqrtpi/README.md b/lib/node_modules/@stdlib/math/base/special/sqrtpi/README.md index 712500a349e8..6558a8abb4ed 100644 --- a/lib/node_modules/@stdlib/math/base/special/sqrtpi/README.md +++ b/lib/node_modules/@stdlib/math/base/special/sqrtpi/README.md @@ -22,6 +22,22 @@ limitations under the License. > Compute the principal [square root][@stdlib/math/base/special/sqrt] of the product of π and a positive number. +
+ +The function computes the principal [square root][square-root] of the product of π and a positive number + + + +```math +y = \sqrt{\pi x} +``` + + + +
+ + +
## Usage @@ -190,6 +206,8 @@ int main( void ) {
+[square-root]: https://en.wikipedia.org/wiki/Square_root + [@stdlib/math/base/special/sqrt]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/sqrt diff --git a/lib/node_modules/@stdlib/math/base/special/sqrtpif/README.md b/lib/node_modules/@stdlib/math/base/special/sqrtpif/README.md index f31b0a0c6ec1..aae2df8925b8 100644 --- a/lib/node_modules/@stdlib/math/base/special/sqrtpif/README.md +++ b/lib/node_modules/@stdlib/math/base/special/sqrtpif/README.md @@ -22,6 +22,22 @@ limitations under the License. > Compute the principal [square root][@stdlib/math/base/special/sqrt] of the product of π and a positive single-precision floating-point number. +
+ +The function computes the principal [square root][square-root] of the product of π and a positive number + + + +```math +y = \sqrt{\pi x} +``` + + + +
+ + +
## Usage @@ -183,6 +199,8 @@ int main( void ) {
+[square-root]: https://en.wikipedia.org/wiki/Square_root + [@stdlib/math/base/special/sqrt]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/sqrt diff --git a/lib/node_modules/@stdlib/math/base/special/wrap/README.md b/lib/node_modules/@stdlib/math/base/special/wrap/README.md index cf952f21e451..d91cd9bc0bc0 100644 --- a/lib/node_modules/@stdlib/math/base/special/wrap/README.md +++ b/lib/node_modules/@stdlib/math/base/special/wrap/README.md @@ -26,6 +26,18 @@ limitations under the License.
+The function wraps a value to the half-open interval `[min, max)` + + + +```math +y = x - \lfloor \frac{x - a}{b - a} \rfloor \cdot (b - a) +``` + + + +where `a` is the minimum value and `b` is the maximum value. +
diff --git a/lib/node_modules/@stdlib/math/base/special/wrapf/README.md b/lib/node_modules/@stdlib/math/base/special/wrapf/README.md index 7ce1ae1ad06e..7ab1233602b4 100644 --- a/lib/node_modules/@stdlib/math/base/special/wrapf/README.md +++ b/lib/node_modules/@stdlib/math/base/special/wrapf/README.md @@ -26,6 +26,18 @@ limitations under the License.
+The function wraps a value to the half-open interval `[min, max)` + + + +```math +y = x - \lfloor \frac{x - a}{b - a} \rfloor \cdot (b - a) +``` + + + +where `a` is the minimum value and `b` is the maximum value. +