# u-numflow
**Domain-agnostic mathematical primitives in Rust**
[](https://crates.io/crates/u-numflow)
[](https://docs.rs/u-numflow)
[](https://github.com/iyulab/u-numflow/actions/workflows/ci.yml)
[](LICENSE)
## Overview
u-numflow provides foundational mathematical, statistical, and probabilistic building blocks. Entirely domain-agnostic with no external dependencies beyond `rand`.
## Modules
| `stats` | Descriptive statistics (mean, variance, skewness, kurtosis) with Welford's online algorithm and Neumaier summation |
| `distributions` | Probability distributions: Uniform, Triangular, PERT, Normal, LogNormal |
| `special` | Special functions: normal CDF and tail-precise survival function (and their inverses), t/F/chi² CDF and quantiles, the noncentral t CDF (Lenth AS 243 — the distribution power is computed from), regularized incomplete beta/gamma, erf |
| `transforms` | Data transformations: Box-Cox (λ via MLE golden-section search), inverse Box-Cox |
| `fourier` | Discrete Fourier transform of any length (radix-2 for powers of two, Bluestein otherwise): `fft`, `ifft`, `rfft`, `Complex` |
| `matrix` | Dense matrix operations: determinant, inverse, Cholesky decomposition, Jacobi eigenvalue decomposition |
| `random` | Seeded RNG, Fisher-Yates shuffle, weighted sampling, random subset selection |
| `collections` | Specialized data structures: Union-Find with path compression and union-by-rank |
## Design Philosophy
- **Numerical stability first** — Welford's algorithm for variance, Neumaier summation for accumulation
- **Reproducibility** — Seeded RNG support for deterministic experiments
- **Property-based testing** — Mathematical invariants verified via `proptest`
## Quick Start
```toml
[dependencies]
u-numflow = "0.8"
```
```rust
use u_numflow::distributions::Pert;
use u_numflow::random::{create_rng, shuffle};
use u_numflow::stats::WelfordAccumulator;
// Online statistics with numerical stability (Welford)
let mut stats = WelfordAccumulator::new();
for x in [1.0, 2.0, 3.0, 4.0, 5.0] {
stats.update(x);
}
assert_eq!(stats.mean(), Some(3.0));
// PERT distribution: moments and quantiles; sample by inverting a uniform draw
let pert = Pert::new(1.0, 4.0, 7.0).unwrap();
assert_eq!(pert.mean(), 4.0);
let p90 = pert.quantile(0.9).unwrap();
assert!(p90 > 4.0 && p90 < 7.0);
// Seeded shuffling for reproducibility
let mut rng = create_rng(42);
let mut items = vec![1, 2, 3, 4, 5];
shuffle(&mut items, &mut rng);
// Box-Cox transformation (non-normal data normalization)
use u_numflow::transforms::{box_cox, estimate_lambda};
let data = [1.0, 2.0, 4.0, 8.0, 16.0];
let fit = estimate_lambda(&data, -2.0, 2.0).unwrap(); // MLE via golden-section
let transformed = box_cox(&data, fit.lambda).unwrap();
assert_eq!(transformed.len(), data.len());
// Discrete Fourier transform of any length
use u_numflow::fourier::rfft;
assert!(spectrum[3].norm() > 14.0);
```
## Build & Test
```bash
cargo build
cargo test
```
## Dependencies
- `rand` 0.9 — Random number generation
- `proptest` 1.4 — Property-based testing (dev only)
## License
MIT License — see [LICENSE](LICENSE).
## npm (WebAssembly)
```bash
npm install @iyulab/u-numflow
```
The package resolves per environment via a conditional `exports` map:
| Bundlers (webpack, Vite, …) | ESM + WebAssembly ESM-integration (`default` condition) |
| Node.js — `require()`, ESM `import`, CJS TS runners (`tsx`, `ts-node`) | CJS glue loading the wasm from the filesystem (`node` condition) — no loader hooks or flags |
A browser **without** a bundler is not supported: the package loads its `.wasm`
file with an ES module import, which browsers refuse (`application/wasm` is not a
module script type), so `<script type="module">` from a CDN fails, and CDN
re-bundling services fail on the same import. Use a bundler or Node.
Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `normal_sf` (upper tail `P(Z > x)`, computed directly so tail probabilities keep ~15 significant digits), `box_cox`, `estimate_lambda` (returns `{ lambda, at_bound }` — `at_bound` is `true` when the likelihood was still rising at an end of the search range, so `lambda` is that limit), and
`rfft(data) -> Float64Array` — the DFT of a real sequence of any length, interleaved as
`[re0, im0, re1, im1, …]` (bins `k` and `n − k` are conjugates, so `0..=n/2` describes the spectrum).
Every `data` argument is a `number[]` or a `Float64Array`, read exactly as sent: an
element that is not a number (`null`, `undefined`, a string) throws `malformed_input`
and a NaN or ±Infinity throws `value_not_finite`, each with the element's `index` —
`mean([1, null, 3])` throws rather than averaging the `null` as 0. `mean` of no values
throws `empty_input`; `std_dev` and `variance` of fewer than 2 throw `insufficient_data`.
Distribution functions for critical values and p-values — each returns a `number` and
**throws** (an `Error` naming the argument — see *Errors* below) when an argument is outside the domain,
rather than returning `NaN`:
| `inverse_normal_cdf(p)` | `z` with `P(Z ≤ z) = p` |
| `t_distribution_cdf(t, df)` / `t_distribution_quantile(p, df)` | Student's t; a two-sided critical value at level α is `t_distribution_quantile(1 − α/2, df)` |
| `f_distribution_cdf(x, df1, df2)` / `f_distribution_quantile(p, df1, df2)` | F |
| `chi_squared_cdf(x, k)` / `chi_squared_quantile(p, k)` | χ² |
`p` must lie strictly between 0 and 1 and every degrees-of-freedom argument must be a
finite number `> 0` (fractional values are allowed).
```js
const { t_distribution_quantile } = require("@iyulab/u-numflow");
t_distribution_quantile(0.975, 10); // 2.2281…
```
**Errors.** A refusal throws an `Error` whose `message` is readable text and which
carries a `code` naming the reason, next to the values behind it:
```js
const { t_distribution_quantile } = require("@iyulab/u-numflow");
try {
t_distribution_quantile(1.5, 10);
} catch (err) {
console.log(err.code, err.parameter, err.min, err.max, err.got); // parameter_out_of_range p 0 1 1.5
}
```
| `parameter_out_of_range` | `parameter`, `min`, `max` (or `null`), `got` | `p` not strictly inside (0, 1), or a degrees of freedom that is not a finite number `> 0` (both bounds excluded) |
| `malformed_input` | `parameter`, `index` (or absent) | A `data` argument that is not an array or `Float64Array`, or an element that is not a number |
| `value_not_finite` | `parameter`, `index` for an array element | A NaN argument, or a NaN or infinity in any `data` array |
| `empty_input` | `parameter` | `mean` of no values |
| `non_positive_data` | — | Box-Cox data with a value `≤ 0` |
| `insufficient_data` | `parameter`, `min`, `got` for `std_dev`/`variance`; — for Box-Cox | Fewer values than the function needs (`std_dev`/`variance` 2, Box-Cox 2) |
| `invalid_transform` | — | A Box-Cox result that is not finite |
| `invalid_lambda_range` | — | `estimate_lambda` bounds that are not finite with `lambda_min < lambda_max` |
### TypeScript
Every exported function declares its parameter and return types, and the
declarations are generated from the same structs the binding reads and
serialises, so they cannot drift from what it actually accepts and returns:
```ts
```
An absent optional value is declared `T | undefined`, which is what the binding
sends. Nothing needs an `as` cast -- and a wrong assumption about a result's
shape is a compile error rather than something that fails at run time.
A `data` parameter is declared `number[] | Float64Array` and read by the
binding itself rather than copied into a typed array by the generated glue, so
a value the declaration does not allow is refused where it sits instead of
being converted. The publishing workflow keeps every declaration free of `any`.
## Related
- [u-metaheur](https://github.com/iyulab/u-metaheur) — Metaheuristic optimization (GA, SA, ALNS, CP)
- [u-geometry](https://github.com/iyulab/u-geometry) — Computational geometry
- [u-schedule](https://github.com/iyulab/u-schedule) — Scheduling framework
- [u-nesting](https://github.com/iyulab/U-Nesting) — 2D/3D nesting and bin packing