Skip to main content

humath

A dependency-free Python math library focusing on high precision and listening to what the community actually wants. Request functions/bug fixes here: https://forms.gle/LQRApJU8G9tMvrD37 See the docs here

Change log:

1.0.1

Fixed

  • Made the hover text hints and examples actually show up.

1.0.0:

Added

  • Official Release
  • Initial stable release of the full humath core library.
  • Dependency-free implementations of continuous and discrete math primitives.
  • Precision floating-point deconstruction layers (fma, frexp, ldexp).
  • Advanced statistical vector analysis suite (mean, median, variance, etc.).
  • Logarithmic-time number theory operations (fibonacci_nth, is_prime).
  • Comprehensive markdown docstring coverage for all native utility functions.

docs

🧮 humath

humath is a high-precision, production-grade, outside dependency-free mathematical and statistical utility library for Python. It provides pure-Python implementations of advanced algebraic, trigonometric, statistical, combinatoric, and number-theoretic functions. The entire suite is engineered from the ground up to bypass traditional binary floating-point limitations, rounding errors, and stack depth issues by manipulating numeric properties directly at the algorithmic level.

👥 Community-Centered Development

This project is completely driven by the community! If you have ideas for new functions, want to see specific mathematical features added, or need to report a calculation bug, please submit your feedback directly through our Community Change Request Form.


🚀 1. Architecture & Core Design Philosophy

To remain completely decoupled from Python’s native compiled C-extensions (math, cmath) and external data-science packages (numpy, scipy), humath relies on four architectural pillars built entirely on raw Python abstractions:

I. Newton-Raphson Optimization with Hexadecimal Seeding

Logarithmic, continuous root, and inverse hyperbolic functions calculate continuous limits natively without lookup tables. Instead of arbitrary guesses, initial values are derived via string parsing from Python's exact 64-bit float configuration method (float.hex()). These seeds undergo fixed iterative updates to reach stable machine decimal convergence within five cycles.

II. Catastrophic Cancellation Guards

Standard mathematical Taylor series lose significant accuracy near critical zero boundaries due to floating-point truncation shifts. humath implements hardware-level safety checks on input vectors. If a magnitude drops below an absolute threshold (e.g., $10^{-4}$ or $10^{-5}$), the system automatically swaps its core engine out for high-order polynomial expansions tailored for sub-boundary convergence.

III. Infinite-Precision Rational Arithmetic

For operations requiring exact intermediate values, inputs are dynamically translated into their strict fractional numerators and denominators (as_integer_ratio()). Calculations are processed as exact rational calculations over arbitrary-precision integers before a single, final rounding operation is applied. This eliminates compounding rounding errors across complex calculations.

IV. Logarithmic Matrix Fast-Doubling

Discrete sequences avoid traditional linear addition loops and deep recursion trees that risk crashing the interpreter's stack. Iterations are processed using matrix fast-doubling identities shifted via bitwise masks (<<, >>). This reduces computational time from linear ($O(n)$) to logarithmic ($O(\log n)$), allowing the library to handle multi-thousand-digit integers instantly.


📦 2. Global Package Constants

The package pre-defines several high-precision mathematical metrics as static elements to optimize execution speeds:

  • PI: 3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825341170679
  • E: 2.7182818284590452353602874713526624977572470936999595749669676277240766303535475945713821785251664274
  • TAU: 6.2831853071795864769252867665590057683943387987502116419498891846156328125724179972560696506842341359
  • GOLDEN_RATIO: 1.6180339887498948482045868343656381177203091798057628621354486227052604628189024497072072041893911374
  • INF: Representing positive infinity (float('inf')).
  • NAN: Representing an undefined value string (float('nan')).
  • deg_to_rad_constant: Radian multiplier per degree (0.017453292519943295...).
  • rad_to_deg_constant: Degree multiplier per radian (57.29577951308232...).

🛠️ 3. Exhaustive API Reference

is_close(a: float, b: float, rel_tol: float = 1e-09) -> bool

Checks whether two floating-point values are within a specified relative tolerance, bypassing binary approximation anomalies. Returns True if conditions are met, otherwise False. If both inputs are exactly 0, it safely resolves to True.

lerp(start: float, end: float, t: float) -> float

Calculates linear interpolation between two values based on a tracking percentage fraction t. Evaluates as $\text{start} + t \times (\text{end} - \text{start})$.

fma(x: float, y: float, z: float) -> float

Fused Multiply-Add. Computes $(x \times y) + z$ using full rational fraction transformations (as_integer_ratio()) to maintain infinite intermediate precision. A single rounding operation is applied at the final exit boundary to eliminate compounding calculation drift.

copysign(x: float, y: float) -> float

Extracts the absolute magnitude of $x$ and applies the positive or negative sign of $y$. String parsing techniques are used to ensure signed zeroes (-0.0) are captured correctly.

nextafter(x: float, y: float) -> float

Finds the adjacent representable double-precision floating-point value next to $x$ when stepping in the direction of $y$. Handles edge-case limits such as NaN values and transitions through subnormal numbers smoothly.

frexp(x: float) -> tuple[float, int]

Deconstructs a float $x$ into a normalized mantissa fraction in the range $[0.5, 1.0)$ and a matching integral power of 2, satisfying $x = \text{mantissa} \times 2^{\text{exponent}}$. Subnormal numbers are normalized internally using binary conversion logic.

ldexp(x: float, i: int) -> float

The exact inverse of frexp. Reassembles a float from a mantissa $x$ and exponent $i$ by modifying the binary exponent configuration directly via string manipulation. It catches overflow limits and maps underflows safely to signed zeroes.


add(*args: float) -> float

Sequentially sums an arbitrary sequence of numeric parameters.

subtract(a: float, b: float) -> float

Calculates the exact difference between two numbers ($a - b$).

multiply(*args: float) -> float

Calculates the sequential product of an arbitrary list of numeric parameters.

divide(numerator: float, denominator: float) -> float | None

Divides a numerator by a denominator. Includes protective logic that logs a warning and returns None if the denominator is 0, preventing runtime crashes.

absolute(number: float) -> float

Returns the absolute non-negative magnitude of a number ($|x|$).

ceil(n: float) -> int

Rounds a number up to the next consecutive whole integer.

floor(n: float) -> int

Rounds a number down to the previous consecutive whole integer.

truncate(n: float) -> int

Chops off the decimal portion of a number entirely, rounding it directly toward zero.

round_half_up(n: float, digits: int = 0) -> float | int

Bypasses Python's default "Banker's Rounding" logic. Implements standard mathematical rounding, where half-values ($0.5$) always round up toward positive infinity. Includes a microscopic adjustment buffer ($10^{-12}$) to correct for binary float drift prior to rounding.

modulo(a: float, b: float) -> float

Calculates the remainder of a division using floored division logic, ensuring the resulting sign matches the divisor $b$. Raises a ZeroDivisionError if $b$ is zero.

divmod_tuple(a: float, b: float) -> tuple[float, float]

Simultaneously evaluates and returns the floored quotient and remainder of $a / b$ as a tuple.

reciprocal(n: float) -> float

Calculates the multiplicative inverse of a number ($1 / n$). Maps infinity values to signed zeroes to maintain strict IEEE-754 compatibility.

negate(n: float) -> float

Flips the sign of a number, mapping positive values to negative and vice versa while preserving signed zero properties.

clamp(val: float, min_val: float, max_val: float) -> float

Constrains a value within a specified range, snapping the value directly to the upper or lower boundary if it overflows.


square(n: float) -> float

Multiplies a value by itself to compute its second power ($n^2$).

cube(n: float) -> float

Computes the third power of a number ($n^3$), preserving negative signs.

power(base: float, exponent: float) -> float

Raises a base number to an arbitrary exponent power ($base^{exponent}$).

sqrt(n: float) -> float

Extracts the principal square root of a non-negative number ($\sqrt{n}$). Raises a ValueError for negative inputs.

cbrt(n: float) -> float

Extracts the cube root ($\sqrt{n}$). Supports negative numbers natively over real numbers by maintaining structural signs.

nth_root(n: float, root: int) -> float

Extracts an arbitrary principal $n$-th root. Even roots of negative numbers raise a ValueError, whereas odd roots handle negative signs natively.

hypot(*args: float) -> float

Computes the Euclidean norm (the square root of the sum of squares) for an arbitrary list of dimensions. Automatically scales parameters down by their maximum value before squaring to prevent hardware-level float overflows.

exp(n: float) -> float

Computes $e^n$ using a high-precision constant approximation of Euler's number. Maps infinite boundaries directly to infinity or zero.

expm1(n: float) -> float

Calculates $e^n - 1$. Employs a 5-term Taylor series expansion when $n$ is close to zero ($|n| < 10^{-5}$) to prevent catastrophic floating-point cancellation errors.

log(n: float, base: float = 2.718281828459045) -> float

Calculates the logarithm of a number for a custom base. It extracts initial baseline hints from binary exponents and utilizes 5 iterations of Newton-Raphson optimization to achieve full 64-bit precision before applying the change-of-base formula.

log10(n: float) -> float

Calculates the common base-10 logarithm using high-efficiency Newton-Raphson optimizations.

log2(n: float) -> float

Calculates the binary base-2 logarithm using high-efficiency Newton-Raphson optimizations.

log1p(n: float) -> float

Calculates $\ln(1 + n)$. Switches to a 5-term Taylor series configuration when inputs are close to zero ($|n| < 10^{-4}$) to prevent precision loss.


degrees_to_radians(deg: float) -> float

Converts angular metrics from degrees to radians.

radians_to_degrees(rad: float) -> float

Converts angular metrics from radians to degrees.

sin(rad: float) -> float

Calculates the trigonometric sine of an angle. Normalizes inputs by mapping large or negative angles onto a standard $[0, \tau)$ circle sweep before running an alternating Taylor series expansion.

cos(rad: float) -> float

Calculates the trigonometric cosine of an angle by mapping inputs onto a $[0, \tau)$ circle sweep and running a high-speed alternating Taylor series loop.

tan(rad: float) -> float | None

Calculates the trigonometric tangent ($\sin(\text{rad}) / \cos(\text{rad})$). Returns None at undefined boundaries where the cosine engine drops to zero.

asin(n: float) -> float | None

Calculates the inverse arcsine, returning values in the principal range $[-\pi/2, \pi/2]$. If the input values approach steep circle horizons ($|n| > 0.5$), it applies a square-root reduction identity to preserve calculation stability.

acos(n: float) -> float | None

Calculates the inverse arccosine by applying the mathematical identity $\arccos(x) = \pi/2 - \arcsin(x)$.

atan(n: float) -> float

Calculates the inverse arctangent, returning values in the range $[-\pi/2, \pi/2]$. Maps large ratios back into stable convergence windows using reciprocal mapping transformations.

atan2(y: float, x: float) -> float

Calculates the full 4-quadrant arctangent for coordinate pairs $(x, y)$, returning values in the range $[-\pi, \pi]$. Handles vertical trajectory lines where $x = 0$ safely without division crashes.

sinh(n: float) -> float

Calculates the hyperbolic sine ($[e^n - e^{-n}] / 2$), protecting infinite boundaries from hardware overflows.

cosh(n: float) -> float

Calculates the hyperbolic cosine ($[e^n + e^{-n}] / 2$).

tanh(n: float) -> float

Calculates the hyperbolic tangent ($\sinh(n) / \cosh(n)$), bounding results within a strict $[-1.0, 1.0]$ envelope.

asinh(n: float) -> float

Calculates the inverse hyperbolic sine using the log transformation identity $\ln(n + \sqrt{n^2 + 1})$. Processes values symmetrically around zero to preserve accuracy.

acosh(n: float) -> float | None

Calculates the inverse hyperbolic cosine using the identity $\ln(n + \sqrt{n^2 - 1})$. Restricts inputs to values $\ge 1.0$.

mean(data: list[float]) -> float | None

Computes the arithmetic average of a dataset. Returns None if the dataset is empty.

median(data: list[float]) -> float | None

Locates the true central value of a dataset. Sorts values internally using a pure-Python insertion sort to protect the user's original data structure from mutation.

mode(data: list[float]) -> float | None

Identifies the most frequently occurring value in a dataset. Ties are resolved by returning the first dominant peak encountered.

minimum(data: list[float]) -> float | None

Scans a vector collection to isolate the lowest numerical value.

maximum(data: list[float]) -> float | None

Scans a vector collection to isolate the highest numerical value.

range_span(data: list[float]) -> float | None

Calculates the absolute data spread by evaluating $\text{maximum} - \text{minimum}$.

sum_of_squares(data: list[float]) -> float | None

Squares every item in a collection and sums the accumulated results.

variance(data: list[float]) -> float | None

Computes the unbiased sample variance of a dataset by calculating squared deviations from the mean and dividing by $N - 1$.

std_deviation(data: list[float]) -> float | None

Calculates the sample standard deviation by evaluating the principal square root of the unbiased sample variance.

quantiles(data: list[float], n: int = 4) -> list[float] | None

Divides a dataset into $n$ equally sized intervals, returning the exact $n-1$ intermediate cutoff thresholds using linear interpolation.

percentile(data: list[float], p: float) -> float | None

Calculates the cutoff threshold below which a given percentage $p$ ($0.0 \le p \le 100.0$) of data falls, using linear interpolation between adjacent elements.

harmonic_mean(data: list[float]) -> float | None

Computes the harmonic mean of a dataset, restricting entries to positive values $> 0.0$.

geometric_mean(data: list[float]) -> float | None

Computes the geometric mean by accumulating natural logarithms to protect intermediate values from multiplication overflows, then re-exponentiating the average.

dot_product(vector_a: list[float], vector_b: list[float]) -> float | None

Computes the scalar dot product of two vectors. Verifies that both vectors are non-empty and share identical lengths.

normalize_array(data: list[float]) -> list[float] | None

Performs linear Min-Max Scaling to transform any numerical distribution into a strict $[0.0, 1.0]$ envelope. Flat datasets where all elements are identical return an array of zeroes to prevent division-by-zero crashes.

area_circle(radius: float) -> float | None

Calculates circle area ($\pi r^2$), validating that the radius is non-negative.

circumference(radius: float) -> float | None

Calculates circle perimeter ($\tau r$), optimizing computation speed by using the pre-defined $\tau$ constant.

area_triangle(base: float, height: float) -> float | None

Calculates triangle area ($0.5 \times \text{base} \times \text{height}$).

perimeter_triangle(a: float, b: float, c: float) -> float | None

Calculates triangle perimeter ($a + b + c$). Includes geometric verification checks to ensure the inputs comply with the Triangle Inequality Theorem.

distance_2d(p1: tuple[float, float], p2: tuple[float, float]) -> float

Calculates the straight-line Euclidean distance between two coordinate pairs on a 2D plane.

factorial(n: int) -> int

Computes $n!$ using a highly efficient iterative accumulator loop that avoids recursion limits. Raises a ValueError for negative parameters.

gcd(a: int, b: int) -> int

Finds the largest positive common divisor using the Euclidean algorithm.

lcm(a: int, b: int) -> int

Finds the least common multiple using the identity $|a \times b| / \text{gcd}(a, b)$.

is_prime(n: int) -> bool

Evaluates primality using an optimized $6k \pm 1$ trial division algorithm bounded to the integer ceiling of $\sqrt{n}$.

next_prime(n: int) -> int

Locates the immediate prime number strictly greater than $n$.

factors(n: int) -> list[int]

Compiles a sorted list of all valid divisors for an integer using square-root short-circuiting.

prime_factors(n: int) -> list[int]

Decomposes an integer into its sequential prime components.

permutations(n: int, r: int) -> int

Calculates the number of unique ordered arrangements when selecting $r$ items out of a pool of $n$, evaluating as $n! / (n - r)!$ without running full factorials.

combinations(n: int, r: int) -> int

Calculates the number of unique unordered subsets when selecting $r$ items out of $n$.

fibonacci_nth(n: int) -> int

Finds the Fibonacci number at position $n$. It utilizes a logarithmic fast-doubling matrix bit-shifting algorithm ($O(\log n)$) to handle massive values instantly without recursion limits.

is_coprime(a: int, b: int) -> bool

Checks whether two integers are relatively prime, meaning they share no common positive factors other than 1 ($\text{gcd}(a, b) == 1$).

is_perfect_number(n: int) -> bool

Checks whether an integer matches the sum of its proper positive divisors.

binomial_coefficient(n: int, k: int) -> int

Computes positions inside Pascal's Triangle ($n \text{ choose } k$), utilizing structural symmetry optimizations to minimize iteration cycles.

catalan_number(n: int) -> int

Computes positions in the Catalan sequence using a direct product formulation engine to eliminate heavy factorial steps.

floor_divide(a: float, b: float) -> int

Divides $a$ by $b$ and applies a floor operation, ensuring rounding consistency across negative coordinate spaces.

💡 4. Complete Verification Test Suites

To verify package reliability, you can save the following test file as test_humath.py and run it via pytest to validate precision limits and edge cases:

import pytest
import humath

def test_precision_fma_and_close():
    # Test standard binary floating point drift resolution
    assert 0.1 + 0.2 != 0.3
    assert humath.is_close(0.1 + 0.2, 0.3) == True
    
    # Test Fused Multiply-Add precision bounds
    res = humath.fma(1.23456789, 9.87654321, 0.00001)
    expected = (123456789 * 987654321) / (10**8 * 10**8) + 1 / 10**5
    assert humath.is_close(res, expected)

def test_logarithmic_and_exponential_taylor_guards():
    # Test expm1 cancellation guard on ultra-tiny values
    tiny_val = 1e-15
    assert humath.is_close(humath.expm1(tiny_val), tiny_val, rel_tol=1e-12)
    
    # Test log1p cancellation guard near zero boundary
    assert humath.is_close(humath.log1p(tiny_val), tiny_val, rel_tol=1e-12)

def test_fibonacci_fast_doubling_performance():
    # Verify exact small sequence targets
    assert humath.fibonacci_nth(0) == 0
    assert humath.fibonacci_nth(1) == 1
    assert humath.fibonacci_nth(6) == 8
    assert humath.fibonacci_nth(10) == 55
    
    # Validate that multi-hundred digit computations complete instantly
    large_fib = humath.fibonacci_nth(1000)
    assert isinstance(large_fib, int)
    assert len(str(large_fib)) == 209

def test_number_theory_and_discrete_systems():
    assert humath.is_prime(2) == True
    assert humath.is_prime(11) == True
    assert humath.is_prime(4) == False
    assert humath.next_prime(14) == 17
    assert humath.factors(24) == [1, 2, 3, 4, 6, 8, 12, 24]
    assert humath.prime_factors(24) == [2, 2, 2, 3]
    assert humath.is_coprime(14, 15) == True
    assert humath.is_coprime(14, 21) == False

def test_statistical_vector_tendencies():
    data = [2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0]
    assert humath.mean(data) == 5.0
    assert humath.median(data) == 4.5
    assert humath.mode(data) == 4.0
    assert humath.variance(data) == 4.5
    assert humath.std_deviation(data) == 4.5 ** 0.5
    assert humath.normalize_array(data) == [0.0, 0.25, 0.5, 0.75, 1.0]

⚖️ 5. License

This library is distributed completely free as open-source software under the terms of the MIT License.

Installation

pip install humath

Quick Start

import humath
print(humath.fibonacci_nth(10)) # Returns 55

Metadata

Release files for humath 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for humath 1.0.1
File Size Uploaded Provenance Actions
humath-1.0.1.tar.gz 45.6 kB Without provenance Details for humath-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for humath 1.0.1
File Interpreter ABI Platform Actions
humath-1.0.1-py3-none-any.whl Python 3 none any Details for humath-1.0.1-py3-none-any.whl

Total release size: 83.9 kB

Release files / humath-1.0.1.tar.gz

Download URL humath-1.0.1.tar.gz
Size 45.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0ade136781a29c816fb193f662e24eb4d41b67e3b7ef1be34f73a1c147c1b883
BLAKE2b-256 checksum
How to use checksums
b05b12a3d23555b54722db37cddd1ff4865536653b3d57444f5a719a6a2c3b52
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / humath-1.0.1-py3-none-any.whl

Download URL humath-1.0.1-py3-none-any.whl
Size 38.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e11fa7103852e1604f6eee895ace7abc2ab7d671f6636c3489ebd64501879179
BLAKE2b-256 checksum
How to use checksums
f5de1dd905d8da1e43a099b94c2f4dfd4c1a4e6ac9afa4618319e4aae619b78d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for humath 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page