@iyulab/u-numflow 0.7.0 → 0.9.0

package/README.md

@@ -16,13 +16,14 @@ u-numflow provides foundational mathematical, statistical, and probabilistic bui
 | Module | Description |
 |--------|-------------|
 | `stats` | Descriptive statistics (mean, variance, skewness, kurtosis) with Welford's online algorithm and Neumaier summation |
-| `distributions` | Probability distributions: Uniform, Triangular, PERT, Normal, LogNormal |
+| `distributions` | Probability distributions: Uniform, Triangular, PERT, Normal, LogNormal, Weibull, Exponential, Gamma, Beta, χ² |
 | `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 |
+| `distributions::Sample` | Random variates from every continuous distribution — `sample(&mut rng)` and reproducible `sample_n(n, seed)`; inversion where the quantile is direct, Marsaglia–Tsang for the gamma family (Gamma, χ², Beta, PERT); uniforms from the open interval (0, 1), so no variate is infinite |
+| `collections` | Specialized data structures: Union-Find with path compression and union-by-rank; `IntervalSet` — unions of half-open intervals with union, intersection, difference, clip and a measure that counts overlapping input once |
 
 ## Design Philosophy
 
@@ -34,7 +35,7 @@ u-numflow provides foundational mathematical, statistical, and probabilistic bui
 
 ```toml
 [dependencies]
-u-numflow = "0.2"
+u-numflow = "0.9"
 ```
 
 ```rust
@@ -49,11 +50,14 @@ for x in [1.0, 2.0, 3.0, 4.0, 5.0] {
 }
 assert_eq!(stats.mean(), Some(3.0));
 
-// PERT distribution: moments and quantiles; sample by inverting a uniform draw
+// PERT distribution: moments, quantiles and reproducible samples
+use u_numflow::distributions::Sample;
 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);
+let draws = pert.sample_n(1000, 7); // same (n, seed), same draws
+assert!(draws.iter().all(|&x| (1.0..=7.0).contains(&x)));
 
 // Seeded shuffling for reproducibility
 let mut rng = create_rng(42);
@@ -72,8 +76,22 @@ use u_numflow::fourier::rfft;
 let signal: Vec<f64> = (0..30).map(|j| (2.0 * std::f64::consts::PI * 3.0 * j as f64 / 30.0).sin()).collect();
 let spectrum = rfft(&signal);           // 30 complex bins; bin 3 carries the energy
 assert!(spectrum[3].norm() > 14.0);
+
+// Interval sets: overlapping stops are down-time once, not twice
+use u_numflow::collections::IntervalSet;
+let planned = IntervalSet::from_intervals([(0.0, 24.0)]).unwrap();
+let unplanned = IntervalSet::from_intervals([(10.0, 30.0)]).unwrap();
+let week = IntervalSet::from_intervals([(0.0, 168.0)]).unwrap();
+let up = week.difference(&planned.union(&unplanned));
+assert_eq!(up.measure(), 138.0);
 ```
 
+`IntervalSet<T>` works over `f32`, `f64` and every primitive integer type. Its
+measure has the type of a distance — the unsigned type of the same width for
+integers (as `i64::abs_diff` returns `u64`), so it cannot overflow. A reversed
+interval (`start > end`) or a NaN/infinite bound is refused with its position,
+never swapped or dropped.
+
 ## Build & Test
 
 ```bash
@@ -83,13 +101,24 @@ cargo test
 
 ## Dependencies
 
-- `rand` 0.9 — Random number generation
+- `rand` 0.10 — Random number generation
 - `proptest` 1.4 — Property-based testing (dev only)
 
 ## License
 
 MIT License — see [LICENSE](LICENSE).
 
+## .NET (NuGet)
+
+```bash
+dotnet add package UNumflow
+```
+
+The distributions (CDF, quantile, moments, seeded sampling) and interval sets,
+backed by this crate through its C ABI (the `ffi` feature) — see
+[bindings/csharp/README.md](bindings/csharp/README.md). Refusals carry the same
+`code` and fields as the WebAssembly binding's.
+
 ## npm (WebAssembly)
 
 ```bash
@@ -112,6 +141,12 @@ Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `normal_sf` (up
 `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`:
@@ -131,6 +166,50 @@ const { t_distribution_quantile } = require("@iyulab/u-numflow");
 t_distribution_quantile(0.975, 10); // 2.2281…
 ```
 
+Any of the crate's distributions by specification — `distribution` is an object
+`{ kind, ...parameters }`, declared as the union type `DistributionSpec`:
+
+| `kind` | Parameters |
+|---|---|
+| `uniform` | `min`, `max` |
+| `triangular` | `min`, `mode`, `max` |
+| `pert` | `min`, `mode`, `max`, `lambda?` (default 4) |
+| `normal` / `lognormal` | `mu`, `sigma` |
+| `weibull` | `shape`, `scale` |
+| `exponential` | `rate` |
+| `gamma` | `shape`, `rate` |
+| `beta` | `alpha`, `beta` |
+| `chi_squared` | `k` |
+
+| Function | Returns |
+|---|---|
+| `distribution_cdf(distribution, x)` | `P(X ≤ x)` |
+| `distribution_quantile(distribution, p)` | `x` with `P(X ≤ x) = p`, `p` strictly inside (0, 1) |
+| `distribution_sample(distribution, n, seed)` | `Float64Array` of `n` variates — the same `(distribution, n, seed)` always gives the same values |
+
+```js
+const { distribution_quantile, distribution_sample } = require("@iyulab/u-numflow");
+distribution_quantile({ kind: "chi_squared", k: 4 }, 0.95);              // 9.4877…
+const lives = distribution_sample({ kind: "weibull", shape: 2, scale: 100 }, 1000, 42);
+console.log(lives.length);                                                // 1000
+```
+
+Interval sets — each argument is a `[start, end][]` of half-open intervals, and every
+result is in normal form (sorted, disjoint, touching pieces merged, empty ones dropped):
+
+| Function | Returns |
+|---|---|
+| `interval_normalize(intervals)` | The union of `intervals`, as `[number, number][]` |
+| `interval_measure(intervals)` | Its total length — each point counted once, however many rows cover it |
+| `interval_union(a, b)` / `interval_intersection(a, b)` / `interval_difference(a, b)` | Set operations, as `[number, number][]`; clip to a window with `interval_intersection(a, [[from, to]])` |
+
+```js
+const { interval_union, interval_difference, interval_measure } = require("@iyulab/u-numflow");
+const down = interval_union([[0, 24]], [[10, 30]]);       // [[0, 30]] — the overlap counts once
+const up = interval_difference([[0, 168]], down);          // [[30, 168]]
+console.log(interval_measure(up));                         // 138
+```
+
 **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:
 
@@ -145,10 +224,15 @@ try {
 
 | `code` | Fields | Meaning |
 |---|---|---|
-| `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) |
-| `value_not_finite` | `parameter` (for a scalar argument) | A NaN argument, or a NaN or infinity in `box_cox`/`estimate_lambda` data |
+| `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); a distribution parameter that must be `> 0` (`parameter` is its path, e.g. `distribution.sigma`); `n` or `seed` not a whole number in range |
+| `unknown_option` | `parameter`, `got`, `expected` | A `distribution.kind` the crate does not have |
+| `invalid_option` | `parameter` | Distribution parameters out of order: `min < max`, `min ≤ mode ≤ max` |
+| `malformed_input` | `parameter`, `index` (or absent) | A `data` argument that is not an array or `Float64Array`, or an element that is not a number; a `distribution` that is not an object with a string `kind`, lacks a parameter or has one its kind does not take; an interval row that is not two numbers (`parameter` is its path, e.g. `a[2]`) |
+| `reversed_interval` | `parameter`, `index` | An interval row with start > end — refused, not swapped |
+| `value_not_finite` | `parameter`, `index` for an array element | A NaN argument, or a NaN or infinity in any `data` array or interval row (`parameter` is the row's path) |
+| `empty_input` | `parameter` | `mean` of no values |
 | `non_positive_data` | — | Box-Cox data with a value `≤ 0` |
-| `insufficient_data` | — | Box-Cox data with fewer than 2 values |
+| `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` |
 
@@ -159,17 +243,18 @@ declarations are generated from the same structs the binding reads and
 serialises, so they cannot drift from what it actually accepts and returns:
 
 ```ts
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
+export function mean(data: number[] | Float64Array): number;
+export function estimate_lambda(data: number[] | Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
 ```
 
 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.
 
-Every parameter is a number or a `Float64Array`, so there is nothing to
-declare beyond what wasm-bindgen already does; the publishing workflow keeps it
-that way. The binding still validates every input at the boundary, and a
-rejected one says what was wrong.
+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