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.2
Fixed
- Re released through Github Verified Publishers
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
humathcore 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.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825341170679E:2.7182818284590452353602874713526624977572470936999595749669676277240766303535475945713821785251664274TAU:6.2831853071795864769252867665590057683943387987502116419498891846156328125724179972560696506842341359GOLDEN_RATIO:1.6180339887498948482045868343656381177203091798057628621354486227052604628189024497072072041893911374INF: 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.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| humath-1.0.2.tar.gz | 46.7 kB | With provenance | Details for humath-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| humath-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for humath-1.0.2-py3-none-any.whl |
Total release size: 84.9 kB
Release files / humath-1.0.2.tar.gz
| Download URL | humath-1.0.2.tar.gz |
|---|---|
| Size | 46.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
754edd12dcd503be0b78ecd9e6d5e76fc6e5d6076ab556342588d0d43df73b7f
|
|
BLAKE2b-256 checksum How to use checksums |
8916be22b9733be56a40596cbc47608db4acdb01342e8913485ab612543aea6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / humath-1.0.2-py3-none-any.whl
| Download URL | humath-1.0.2-py3-none-any.whl |
|---|---|
| Size | 38.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ef73d661c9c2d292e6fa750bc7d94f278f0eefdf3dd0a9184443e51f0147862f
|
|
BLAKE2b-256 checksum How to use checksums |
fa2640cb9212939b152ca8b78065922c14cf7e6e432c07a706028f3ab8d52efa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for humath 1.0.2
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for humath-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA 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.