Math Module
The FlexFloat math module provides mathematical functions that work with FlexFloat numbers.
flexfloat.math - Mathematical Functions for FlexFloat
This module provides mathematical functions for the FlexFloat type, mirroring the interface and behavior of Python’s built-in math module where possible, but operating on arbitrary-precision floating-point numbers. All functions are designed to work with FlexFloat objects, enabling high-precision and customizable floating-point arithmetic for scientific, engineering, and numerical applications.
- Features:
Implements core mathematical operations (exp, sqrt, pow, log, etc.) for FlexFloat.
Provides constants (e, pi, tau, inf, nan) as FlexFloat instances.
Handles special cases (NaN, infinity, zero) according to IEEE 754 semantics.
- Uses numerically stable algorithms (Taylor series, Newton-Raphson,
range reduction) for accuracy.
Designed to be a drop-in replacement for math functions in code using FlexFloat.
Example
from flexfloat.math import sqrt, exp, log, pi from flexfloat import FlexFloat a = FlexFloat.from_float(2.0) b = sqrt(a) print(f”sqrt(2) = {b}”) print(f”exp(1) = {exp(FlexFloat.from_float(1.0))}”) print(f”log(e) = {log(exp(FlexFloat.from_float(1.0)))}”) print(f”pi = {pi}”)
- flexfloat.math.exp(x)[source]
Compute the exponential function e^x for a FlexFloat value.
Handles special cases (NaN, infinity, zero) and uses a combination of range reduction and Taylor series for accurate computation.
- Parameters:
x (
FlexFloat) – The exponent value.- Returns:
The value of e^x as a FlexFloat.
- Return type:
Example
result = exp(FlexFloat.from_float(1.0)) # e^1
- flexfloat.math.expm1(x)[source]
Return e^x minus 1 for a FlexFloat value.
This function is more accurate than exp(x) - 1 for small x.
- Parameters:
x (
FlexFloat) – The exponent value.- Returns:
The value of e^x - 1.
- Return type:
Example
result = expm1(FlexFloat.from_float(1e-5))
- flexfloat.math.pow(base, exp)[source]
Raise a FlexFloat base to a FlexFloat exponent.
- Parameters:
base (
FlexFloat) – The base value.exp (
FlexFloat) – The exponent value.
- Returns:
The value of base**exp as a FlexFloat.
- Return type:
Example
result = pow(FlexFloat.from_float(2.0), FlexFloat.from_float(3.0)) # 2^3
- flexfloat.math.log(x, base=FlexFloat(sign=False, exponent=10000000000, fraction=0101101111110000101010001011000101000101011101101001))[source]
Compute the logarithm of x to a given base using Taylor series and range reduction.
Handles special cases and uses the change of base formula for arbitrary bases.
- Parameters:
x (
FlexFloat) – The value to compute the logarithm of.base (
FlexFloat, optional) – The base of the logarithm. Defaults to e.
- Returns:
The logarithm of x to the given base.
- Return type:
- flexfloat.math.log10(x)[source]
Return the base-10 logarithm of x.
- Parameters:
x (
FlexFloat) – The value to compute the base-10 logarithm of.- Returns:
The base-10 logarithm of x.
- Return type:
- flexfloat.math.log1p(x)[source]
Return the natural logarithm of 1 + x, accurate for small x.
- Parameters:
x (
FlexFloat) – The value to compute the natural logarithm of 1 + x.- Returns:
The natural logarithm of 1 + x.
- Return type:
- flexfloat.math.log2(x)[source]
Return the base-2 logarithm of x.
- Parameters:
x (
FlexFloat) – The value to compute the base-2 logarithm of.- Returns:
The base-2 logarithm of x.
- Return type:
- flexfloat.math.cbrt(x)[source]
Return the cube root of x.
- Parameters:
x (
FlexFloat) – The value to compute the cube root of.- Returns:
The cube root of x.
- Return type:
- flexfloat.math.sqrt(x)[source]
Compute the square root of a FlexFloat using a hybrid algorithm.
- Selects the optimal method based on the input:
Taylor series for values near 1 (fast, accurate)
Newton-Raphson for general values
Scaling for very small or large values
Handles special cases (NaN, zero, negative, infinity).
- Parameters:
x (
FlexFloat) – The value to compute the square root of.- Returns:
The square root of x.
- Return type:
- Raises:
ValueError – If x is negative (returns NaN for real numbers).
- flexfloat.math.acos(x)[source]
Return the arc cosine of x in radians.
The result is in the range [0, π]. Uses the identity acos(x) = π/2 - asin(x).
- Parameters:
x (
FlexFloat) – The value to compute the arc cosine of, must be in [-1, 1].- Returns:
The arc cosine of x in radians.
- Return type:
Examples
>>> acos(FlexFloat.from_float(1.0)) # Returns 0.0 >>> acos(FlexFloat.from_float(0.0)) # Returns π/2 >>> acos(FlexFloat.from_float(-1.0)) # Returns π
- flexfloat.math.asin(x)[source]
Return the arc sine of x in radians.
The result is in the range [-π/2, π/2]. Uses Taylor series for small values and identities for larger values.
- Parameters:
x (
FlexFloat) – The value to compute the arc sine of, must be in [-1, 1].- Returns:
The arc sine of x in radians.
- Return type:
Examples
>>> asin(FlexFloat.from_float(0.0)) # Returns 0.0 >>> asin(FlexFloat.from_float(1.0)) # Returns π/2 >>> asin(FlexFloat.from_float(-1.0)) # Returns -π/2
- flexfloat.math.atan(x)[source]
Return the arc tangent of x in radians.
The result is in the range [-π/2, π/2]. Uses range reduction and Taylor series for accurate computation.
- Parameters:
x (
FlexFloat) – The value to compute the arc tangent of.- Returns:
The arc tangent of x in radians.
- Return type:
Examples
>>> atan(FlexFloat.from_float(0.0)) # Returns 0.0 >>> atan(FlexFloat.from_float(1.0)) # Returns π/4 >>> atan(FlexFloat.from_float(-1.0)) # Returns -π/4
- flexfloat.math.atan2(y, x)[source]
Return the arc tangent of y/x in radians.
This function handles the signs of both arguments to determine the correct quadrant. The result is in the range [-π, π].
- Parameters:
y (
FlexFloat) – The numerator value.x (
FlexFloat) – The denominator value.
- Returns:
The arc tangent of y/x in radians, in the correct quadrant.
- Return type:
Examples
>>> atan2(FlexFloat.from_float(1.0), FlexFloat.from_float(1.0)) # Returns π/4 >>> atan2(FlexFloat.from_float(1.0), FlexFloat.from_float(-1.0)) # Returns 3π/4
- flexfloat.math.cos(x)[source]
Return the cosine of x in radians.
This function handles special cases (NaN, infinity, zero) and uses range reduction with Taylor series for accurate computation.
- Parameters:
x (
FlexFloat) – The angle in radians.- Returns:
The cosine of x.
- Return type:
Examples
>>> cos(FlexFloat.from_float(0.0)) # Returns 1.0 >>> cos(FlexFloat.from_float(math.pi/2)) # Returns ~0.0 >>> cos(FlexFloat.from_float(math.pi)) # Returns -1.0
- flexfloat.math.degrees(x)[source]
Convert angle x from radians to degrees.
- Parameters:
x (
FlexFloat) – The angle in radians.- Returns:
The angle in degrees.
- Return type:
- flexfloat.math.radians(x)[source]
Convert angle x from degrees to radians.
- Parameters:
x (
FlexFloat) – The angle in degrees.- Returns:
The angle in radians.
- Return type:
- flexfloat.math.sin(x)[source]
Return the sine of x in radians.
This function handles special cases (NaN, infinity, zero) and uses range reduction with Taylor series for accurate computation.
- Parameters:
x (
FlexFloat) – The angle in radians.- Returns:
The sine of x.
- Return type:
Examples
>>> sin(FlexFloat.from_float(0.0)) # Returns 0.0 >>> sin(FlexFloat.from_float(math.pi/2)) # Returns 1.0 >>> sin(FlexFloat.from_float(math.pi)) # Returns ~0.0
- flexfloat.math.tan(x)[source]
Return the tangent of x in radians.
This function computes tan(x) = sin(x) / cos(x), handling special cases and singularities appropriately.
- Parameters:
x (
FlexFloat) – The angle in radians.- Returns:
The tangent of x.
- Return type:
Examples
>>> tan(FlexFloat.from_float(0.0)) # Returns 0.0 >>> tan(FlexFloat.from_float(math.pi/4)) # Returns 1.0
- flexfloat.math.acosh(x)[source]
Return the hyperbolic arc cosine of x.
Uses the identity acosh(x) = ln(x + sqrt(x² - 1)) for x >= 1.
- Parameters:
x (
FlexFloat) – The value to compute the hyperbolic arc cosine of, must be >= 1.- Returns:
The hyperbolic arc cosine of x.
- Return type:
Examples
>>> acosh(FlexFloat.from_float(1.0)) # Returns 0.0 >>> acosh(FlexFloat.from_float(2.0)) # Returns ~1.317
- flexfloat.math.asinh(x)[source]
Return the hyperbolic arc sine of x.
Uses the identity asinh(x) = ln(x + sqrt(x² + 1)).
- Parameters:
x (
FlexFloat) – The value to compute the hyperbolic arc sine of.- Returns:
The hyperbolic arc sine of x.
- Return type:
Examples
>>> asinh(FlexFloat.from_float(0.0)) # Returns 0.0 >>> asinh(FlexFloat.from_float(1.0)) # Returns ~0.881
- flexfloat.math.atanh(x)[source]
Return the hyperbolic arc tangent of x.
Uses the identity atanh(x) = (1/2) * ln((1+x)/(1-x)) for |x| < 1.
- Parameters:
x (
FlexFloat) – The value to compute the hyperbolic arc tangent of, must be in (-1, 1).- Returns:
The hyperbolic arc tangent of x.
- Return type:
Examples
>>> atanh(FlexFloat.from_float(0.0)) # Returns 0.0 >>> atanh(FlexFloat.from_float(0.5)) # Returns ~0.549
- flexfloat.math.cosh(x)[source]
Return the hyperbolic cosine of x.
This function computes cosh(x) = (e^x + e^(-x)) / 2, handling special cases appropriately.
- Parameters:
x (
FlexFloat) – The value to compute the hyperbolic cosine of.- Returns:
The hyperbolic cosine of x.
- Return type:
Examples
>>> cosh(FlexFloat.from_float(0.0)) # Returns 1.0 >>> cosh(FlexFloat.from_float(1.0)) # Returns ~1.543
- flexfloat.math.sinh(x)[source]
Return the hyperbolic sine of x.
This function computes sinh(x) = (e^x - e^(-x)) / 2, handling special cases appropriately.
- Parameters:
x (
FlexFloat) – The value to compute the hyperbolic sine of.- Returns:
The hyperbolic sine of x.
- Return type:
Examples
>>> sinh(FlexFloat.from_float(0.0)) # Returns 0.0 >>> sinh(FlexFloat.from_float(1.0)) # Returns ~1.175
- flexfloat.math.tanh(x)[source]
Return the hyperbolic tangent of x.
This function computes tanh(x) = sinh(x) / cosh(x) = (e^x - e^(-x)) / (e^x + e^(-x)), handling special cases appropriately.
- Parameters:
x (
FlexFloat) – The value to compute the hyperbolic tangent of.- Returns:
The hyperbolic tangent of x.
- Return type:
Examples
>>> tanh(FlexFloat.from_float(0.0)) # Returns 0.0 >>> tanh(FlexFloat.from_float(1.0)) # Returns ~0.762
- flexfloat.math.copysign(x, y)[source]
Return a FlexFloat with the magnitude of x and the sign of y.
- Parameters:
x (
FlexFloat) – Value whose magnitude is used.y (
FlexFloat) – Value whose sign is used.
- Returns:
A FlexFloat with the magnitude of x and the sign of y.
- Return type:
Example
result = copysign(FlexFloat.from_float(-2.0), FlexFloat.from_float(3.0)) # result is 2.0 (positive)
- flexfloat.math.fabs(x)[source]
Return the absolute value of a FlexFloat.
- Parameters:
x (
FlexFloat) – The value to get the absolute value of.- Returns:
The absolute value of x.
- Return type:
Example
result = fabs(FlexFloat.from_float(-5.0)) # result is 5.0
- flexfloat.math.isfinite(x)[source]
Check if a FlexFloat is finite (not infinity or NaN).
- Parameters:
x (
FlexFloat) – The value to check.- Returns:
True if x is finite, False otherwise.
- Return type:
Example
result = isfinite(FlexFloat.from_float(1.0)) # result is True
- flexfloat.math.isinf(x)[source]
Check if a FlexFloat is positive or negative infinity.
- Parameters:
x (
FlexFloat) – The value to check.- Returns:
True if x is infinity, False otherwise.
- Return type:
Example
result = isinf(FlexFloat.infinity()) # result is True
- flexfloat.math.isnan(x)[source]
Check if a FlexFloat is NaN (not a number).
- Parameters:
x (
FlexFloat) – The value to check.- Returns:
True if x is NaN, False otherwise.
- Return type:
Example
result = isnan(FlexFloat.nan()) # result is True
- flexfloat.math.ceil(x)[source]
Return the ceiling of x as a FlexFloat.
- Parameters:
x (
FlexFloat) – The value to compute the ceiling of.- Returns:
The smallest integer greater than or equal to x.
- Return type:
- flexfloat.math.dist(p, q)[source]
Return the Euclidean distance between two points p and q.
- Parameters:
p (
Iterable[FlexFloat]) – The first point coordinates.q (
Iterable[FlexFloat]) – The second point coordinates.
- Returns:
The Euclidean distance between p and q.
- Return type:
- flexfloat.math.erf(x)[source]
Return the error function of x.
The error function is defined as: erf(x) = (2/√π) * ∫[0 to x] e^(-t²) dt
This implementation uses Abramowitz and Stegun approximation for |x| < 2.2, and asymptotic expansion for larger values.
- Parameters:
x (
FlexFloat) – The value to compute the error function of.- Returns:
The error function value erf(x).
- Return type:
- Special cases:
erf(NaN) = NaN
erf(+∞) = 1
erf(-∞) = -1
erf(0) = 0
erf(-x) = -erf(x) (odd function)
- flexfloat.math.erfc(x)[source]
Return the complementary error function of x.
The complementary error function is defined as: erfc(x) = 1 - erf(x) = (2/√π) * ∫[x to ∞] e^(-t²) dt
This function is computed as erfc(x) = 1 - erf(x) for most values, but uses direct computation for large positive values to avoid precision loss from subtracting two numbers close to 1.
- Parameters:
x (
FlexFloat) – The value to compute the complementary error function of.- Returns:
The complementary error function value erfc(x).
- Return type:
- Special cases:
erfc(NaN) = NaN
erfc(+∞) = 0
erfc(-∞) = 2
erfc(0) = 1
- flexfloat.math.floor(x)[source]
Return the floor of x as a FlexFloat.
- Parameters:
x (
FlexFloat) – The value to compute the floor of.- Returns:
The largest integer less than or equal to x.
- Return type:
- flexfloat.math.fma(x, y, z)[source]
Return (x * y) + z with extended precision.
- Parameters:
x (
FlexFloat) – The first multiplicand.y (
FlexFloat) – The second multiplicand.z (
FlexFloat) – The value to add.
- Returns:
The result of (x * y) + z.
- Return type:
- flexfloat.math.fmod(x, y)[source]
Return the remainder of x divided by y (modulo operation).
- Parameters:
x (
FlexFloat) – The dividend value.y (
FlexFloat) – The divisor value.
- Returns:
The remainder of x divided by y.
- Return type:
- flexfloat.math.fsum(seq)[source]
Accurately sum a sequence of FlexFloat values (sorted by exponent).
- Parameters:
seq (
Iterable[FlexFloat]) – The sequence of values to sum.- Returns:
The sum of the sequence.
- Return type:
- flexfloat.math.gamma(x)[source]
Return the gamma function of x.
The gamma function is defined as Γ(x) = ∫₀^∞ t^(x-1) * e^(-t) dt. For positive integers n, Γ(n) = (n-1)!.
This implementation uses: - Direct calculation for small integer values - Lanczos approximation for moderate values - Stirling’s approximation for large values - Reflection formula for negative values
- Parameters:
x (
FlexFloat) – The value to compute the gamma function of.- Returns:
The gamma function value Γ(x).
- Return type:
- Special cases:
gamma(NaN) = NaN
gamma(+∞) = +∞
gamma(-∞) = NaN
gamma(0) = +∞ (with sign depending on approach)
gamma(negative integer) = NaN
- flexfloat.math.hypot(*coordinates)[source]
Return the Euclidean norm (L2 norm) of the given coordinates.
- Parameters:
*coordinates (
FlexFloat) – The coordinates to compute the norm of.- Returns:
The Euclidean norm of the coordinates.
- Return type:
- flexfloat.math.isclose(a, b, *, rel_tol=FlexFloat(sign=False, exponent=01111100001, fraction=0001001011100000101111101000001001101101011010010101), abs_tol=FlexFloat(sign=False, exponent=00000000000, fraction=0000000000000000000000000000000000000000000000000000))[source]
Check if two FlexFloat values are close to each other within a tolerance.
- Parameters:
a (
FlexFloat) – The first value to compare.b (
FlexFloat) – The second value to compare.rel_tol (
FlexFloat, optional) – Relative tolerance. Defaults to 1e-09.abs_tol (FlexFloat) – Absolute tolerance. Defaults to 0.0.
- Returns:
True if a and b are close within the given tolerances, False otherwise.
- Return type:
- flexfloat.math.lgamma(x)[source]
Return the natural logarithm of the absolute value of the gamma function.
This function computes ln(|Γ(x)|), which is useful for avoiding overflow when computing the gamma function of large arguments.
- Parameters:
x (
FlexFloat) – The value to compute the logarithm of the gamma function of.- Returns:
The natural logarithm of the absolute value of Γ(x).
- Return type:
- Special cases:
lgamma(NaN) = NaN
lgamma(+∞) = +∞
lgamma(-∞) = +∞
lgamma(0) = +∞
lgamma(negative integer) = +∞
- flexfloat.math.nextafter(x, y, *, steps=None)[source]
Return the next representable FlexFloat value after x towards y.
This function returns the next representable floating-point value after x in the direction of y. If steps is provided, it advances steps times.
This implementation works directly with FlexFloat’s bit representation and supports arbitrary exponent sizes, unlike the standard library version which is limited to 64-bit IEEE 754 precision.
- Parameters:
x (
FlexFloat) – The starting value.y (
FlexFloat) – The target value.steps (
int | None, optional) – The number of steps to take. Defaults to 1 step.
- Returns:
The next representable value after x towards y.
- Return type:
- Special cases:
nextafter(NaN, y) = NaN
nextafter(x, NaN) = NaN
nextafter(x, x) = x
nextafter(±∞, finite) moves towards finite values
nextafter(finite, ±∞) moves towards infinity
- flexfloat.math.remainder(x, y)[source]
Return the IEEE 754-style remainder of x with respect to y.
- Parameters:
x (
FlexFloat) – The dividend value.y (
FlexFloat) – The divisor value.
- Returns:
The IEEE 754-style remainder.
- Return type:
Logarithmic Functions
- flexfloat.math.log(x, base=FlexFloat(sign=False, exponent=10000000000, fraction=0101101111110000101010001011000101000101011101101001))[source]
Compute the logarithm of x to a given base using Taylor series and range reduction.
Handles special cases and uses the change of base formula for arbitrary bases.
- Parameters:
x (
FlexFloat) – The value to compute the logarithm of.base (
FlexFloat, optional) – The base of the logarithm. Defaults to e.
- Returns:
The logarithm of x to the given base.
- Return type:
- flexfloat.math.log2(x)[source]
Return the base-2 logarithm of x.
- Parameters:
x (
FlexFloat) – The value to compute the base-2 logarithm of.- Returns:
The base-2 logarithm of x.
- Return type:
Exponential Functions
- flexfloat.math.exp(x)[source]
Compute the exponential function e^x for a FlexFloat value.
Handles special cases (NaN, infinity, zero) and uses a combination of range reduction and Taylor series for accurate computation.
- Parameters:
x (
FlexFloat) – The exponent value.- Returns:
The value of e^x as a FlexFloat.
- Return type:
Example
result = exp(FlexFloat.from_float(1.0)) # e^1
Power Functions
- flexfloat.math.sqrt(x)[source]
Compute the square root of a FlexFloat using a hybrid algorithm.
- Selects the optimal method based on the input:
Taylor series for values near 1 (fast, accurate)
Newton-Raphson for general values
Scaling for very small or large values
Handles special cases (NaN, zero, negative, infinity).
- Parameters:
x (
FlexFloat) – The value to compute the square root of.- Returns:
The square root of x.
- Return type:
- Raises:
ValueError – If x is negative (returns NaN for real numbers).
- flexfloat.math.pow(base, exp)[source]
Raise a FlexFloat base to a FlexFloat exponent.
- Parameters:
base (
FlexFloat) – The base value.exp (
FlexFloat) – The exponent value.
- Returns:
The value of base**exp as a FlexFloat.
- Return type:
Example
result = pow(FlexFloat.from_float(2.0), FlexFloat.from_float(3.0)) # 2^3
Examples
Logarithmic Operations
from flexfloat import FlexFloat
from flexfloat import math as ffmath
x = FlexFloat.from_float(100.0)
# Natural logarithm
ln_x = ffmath.log(x) # Natural log (base e)
print(ln_x)
# Base-2 logarithm
log2_x = ffmath.log2(x)
print(log2_x)
# Base-10 logarithm
log10_x = ffmath.log10(x)
print(log10_x)
Exponential Operations
from flexfloat import FlexFloat
from flexfloat import math as ffmath
x = FlexFloat.from_float(2.0)
# Natural exponential
exp_x = ffmath.exp(x)
print(exp_x)
Power Operations
from flexfloat import FlexFloat
from flexfloat import math as ffmath
x = FlexFloat.from_float(16.0)
y = FlexFloat.from_float(3.0)
# Square root
sqrt_x = ffmath.sqrt(x)
print(sqrt_x)
# General power
pow_xy = ffmath.pow(x, y)
print(pow_xy)
Working with Large Numbers
from flexfloat import FlexFloat
from flexfloat import math as ffmath
# Large number operations
large = FlexFloat.from_float(10) ** 100
# Logarithm of large number
log_large = ffmath.log10(large)
print(log_large)
# Square root of large number
sqrt_large = ffmath.sqrt(large)
print(sqrt_large)
Special Cases
from flexfloat import FlexFloat
from flexfloat import math as ffmath
zero = FlexFloat.zero()
one = FlexFloat.from_float(1.0)
inf = FlexFloat.infinity()
# Logarithm special cases
print(ffmath.log(one)) # 0.0
print(ffmath.log(inf)) # infinity
# ffmath.log(zero) # would be negative infinity or error
# Exponential special cases
print(ffmath.exp(zero)) # 1.0
print(ffmath.exp(inf)) # infinity
# Power special cases
print(ffmath.sqrt(zero)) # 0.0
print(ffmath.sqrt(one)) # 1.0
print(ffmath.pow(zero, one)) # 0.0