# rustymath

> Maths in plain Rust, from fast f16, f32 and f64 functions to exact rationals.

Rustymath provides fast elementary and special functions, statistics, searching and sorting, random sampling, linear algebra, optimization, polynomials and exact arithmetic in Rust and Python. It is the numerical core of [BasedPL](https://answerdotai.github.io/basedpl/).

The Python package needs no NumPy. Its eager operations use the same broadcasting, selection and tolerant-comparison rules as the shared Rust core. For richer array notation, operators and fusion, use BasedPL.

Float functions target four units in the last place (ulps). Rustymath prioritizes speed over last-bit agreement and reproducibility. These functions document wider bounds:

- `lgamma` near its zeros at 1 and 2 is within 4 ulps of 2, not of the result. `digamma` near its zeros is within 4 ulps of 1, and below -20 within 4 ulps of ln(1 - x).
- `binom` and `binom_dn` of a non-whole n with a whole k up to 64 are within 2k ulps.
- `binom_dk` has no relative bound near n = 2k, where its two ψ terms cancel.
- Complex functions count ulps of the result's magnitude, so a much smaller part can carry most of the error. Complex powers, Γ and binomial coefficients allow ulps of their magnitude times one more than the exponent's magnitude. `exp` gives an exact direction at the float nearest a whole number of quarter turns, so e^(iπ/2) is exactly i.

[Arrays and indexing](https://answerdotai.github.io/rustymath/arrays.html) covers construction, dtypes, selection, reshaping, axis names, keys and interoperability.

[Maths and statistics](https://answerdotai.github.io/rustymath/math.html) covers elementary and special functions, reductions, scans, statistics and tolerant comparison.

[Searching, sorting and selection](https://answerdotai.github.io/rustymath/search.html) distinguishes tolerant matching from exact ordering.

[Random numbers and distributions](https://answerdotai.github.io/rustymath/random.html) covers sampling and probability functions.

[Linear algebra](https://answerdotai.github.io/rustymath/linalg.html) covers matrix products, reusable factorizations, decompositions and least squares.

[Optimization and iterative solves](https://answerdotai.github.io/rustymath/optimize.html) also covers matrix-free linear systems.

[Polynomials, exact arithmetic and number theory](https://answerdotai.github.io/rustymath/exact.html) includes rational matrix solves and calculations with `fractions.Fraction`.

The Rust page's [Accuracy and speed](https://answerdotai.github.io/rustymath/rust.html#accuracy-and-speed) section compares each function's speed with Rust's standard library. It also explains how the 4-ulp bound holds for `f16`, with and without fused multiply-add, and for `pow` and `root`.

## Modules

- [rustymath.optimize](https://answerdotai.github.io/rustymath/optimize.html.md): Minimizing a function of several variables, and solving equations, nonlinear or linear, with SciPy's names. The searches run in Rust and call the Python functions at each point.

<!-- Generated by nbdev-export; edit the index notebook, not this file -->
