skaters-fast 0.17.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2 @@
1
+ /target
2
+ Cargo.lock
@@ -0,0 +1,221 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 3
4
+
5
+ [[package]]
6
+ name = "heck"
7
+ version = "0.5.0"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
10
+
11
+ [[package]]
12
+ name = "itoa"
13
+ version = "1.0.19"
14
+ source = "registry+https://github.com/rust-lang/crates.io-index"
15
+ checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4"
16
+
17
+ [[package]]
18
+ name = "libc"
19
+ version = "0.2.191"
20
+ source = "registry+https://github.com/rust-lang/crates.io-index"
21
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
22
+
23
+ [[package]]
24
+ name = "libm"
25
+ version = "0.2.16"
26
+ source = "registry+https://github.com/rust-lang/crates.io-index"
27
+ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
28
+
29
+ [[package]]
30
+ name = "memchr"
31
+ version = "2.8.3"
32
+ source = "registry+https://github.com/rust-lang/crates.io-index"
33
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
34
+
35
+ [[package]]
36
+ name = "once_cell"
37
+ version = "1.21.4"
38
+ source = "registry+https://github.com/rust-lang/crates.io-index"
39
+ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
40
+
41
+ [[package]]
42
+ name = "portable-atomic"
43
+ version = "1.15.0"
44
+ source = "registry+https://github.com/rust-lang/crates.io-index"
45
+ checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
46
+
47
+ [[package]]
48
+ name = "proc-macro2"
49
+ version = "1.0.107"
50
+ source = "registry+https://github.com/rust-lang/crates.io-index"
51
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
52
+ dependencies = [
53
+ "unicode-ident",
54
+ ]
55
+
56
+ [[package]]
57
+ name = "pyo3"
58
+ version = "0.29.3"
59
+ source = "registry+https://github.com/rust-lang/crates.io-index"
60
+ checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
61
+ dependencies = [
62
+ "libc",
63
+ "once_cell",
64
+ "portable-atomic",
65
+ "pyo3-build-config",
66
+ "pyo3-ffi",
67
+ "pyo3-macros",
68
+ ]
69
+
70
+ [[package]]
71
+ name = "pyo3-build-config"
72
+ version = "0.29.3"
73
+ source = "registry+https://github.com/rust-lang/crates.io-index"
74
+ checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
75
+ dependencies = [
76
+ "target-lexicon",
77
+ ]
78
+
79
+ [[package]]
80
+ name = "pyo3-ffi"
81
+ version = "0.29.3"
82
+ source = "registry+https://github.com/rust-lang/crates.io-index"
83
+ checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
84
+ dependencies = [
85
+ "libc",
86
+ "pyo3-build-config",
87
+ ]
88
+
89
+ [[package]]
90
+ name = "pyo3-macros"
91
+ version = "0.29.3"
92
+ source = "registry+https://github.com/rust-lang/crates.io-index"
93
+ checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
94
+ dependencies = [
95
+ "proc-macro2",
96
+ "pyo3-macros-backend",
97
+ "quote",
98
+ "syn 2.0.119",
99
+ ]
100
+
101
+ [[package]]
102
+ name = "pyo3-macros-backend"
103
+ version = "0.29.3"
104
+ source = "registry+https://github.com/rust-lang/crates.io-index"
105
+ checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
106
+ dependencies = [
107
+ "heck",
108
+ "proc-macro2",
109
+ "quote",
110
+ "syn 2.0.119",
111
+ ]
112
+
113
+ [[package]]
114
+ name = "quote"
115
+ version = "1.0.47"
116
+ source = "registry+https://github.com/rust-lang/crates.io-index"
117
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
118
+ dependencies = [
119
+ "proc-macro2",
120
+ ]
121
+
122
+ [[package]]
123
+ name = "serde"
124
+ version = "1.0.229"
125
+ source = "registry+https://github.com/rust-lang/crates.io-index"
126
+ checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
127
+ dependencies = [
128
+ "serde_core",
129
+ "serde_derive",
130
+ ]
131
+
132
+ [[package]]
133
+ name = "serde_core"
134
+ version = "1.0.229"
135
+ source = "registry+https://github.com/rust-lang/crates.io-index"
136
+ checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
137
+ dependencies = [
138
+ "serde_derive",
139
+ ]
140
+
141
+ [[package]]
142
+ name = "serde_derive"
143
+ version = "1.0.229"
144
+ source = "registry+https://github.com/rust-lang/crates.io-index"
145
+ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
146
+ dependencies = [
147
+ "proc-macro2",
148
+ "quote",
149
+ "syn 3.0.10",
150
+ ]
151
+
152
+ [[package]]
153
+ name = "serde_json"
154
+ version = "1.0.154"
155
+ source = "registry+https://github.com/rust-lang/crates.io-index"
156
+ checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
157
+ dependencies = [
158
+ "itoa",
159
+ "memchr",
160
+ "serde",
161
+ "serde_core",
162
+ "zmij",
163
+ ]
164
+
165
+ [[package]]
166
+ name = "skaters"
167
+ version = "0.17.0"
168
+ dependencies = [
169
+ "libm",
170
+ "serde",
171
+ "serde_json",
172
+ ]
173
+
174
+ [[package]]
175
+ name = "skaters-fast"
176
+ version = "0.17.0"
177
+ dependencies = [
178
+ "pyo3",
179
+ "serde_json",
180
+ "skaters",
181
+ ]
182
+
183
+ [[package]]
184
+ name = "syn"
185
+ version = "2.0.119"
186
+ source = "registry+https://github.com/rust-lang/crates.io-index"
187
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
188
+ dependencies = [
189
+ "proc-macro2",
190
+ "quote",
191
+ "unicode-ident",
192
+ ]
193
+
194
+ [[package]]
195
+ name = "syn"
196
+ version = "3.0.10"
197
+ source = "registry+https://github.com/rust-lang/crates.io-index"
198
+ checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79"
199
+ dependencies = [
200
+ "proc-macro2",
201
+ "quote",
202
+ "unicode-ident",
203
+ ]
204
+
205
+ [[package]]
206
+ name = "target-lexicon"
207
+ version = "0.13.6"
208
+ source = "registry+https://github.com/rust-lang/crates.io-index"
209
+ checksum = "8c447be3a2abfa84b2d91680c56600bd6b2873866de27b36ec911be705e291da"
210
+
211
+ [[package]]
212
+ name = "unicode-ident"
213
+ version = "1.0.27"
214
+ source = "registry+https://github.com/rust-lang/crates.io-index"
215
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
216
+
217
+ [[package]]
218
+ name = "zmij"
219
+ version = "1.0.23"
220
+ source = "registry+https://github.com/rust-lang/crates.io-index"
221
+ checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
@@ -0,0 +1,32 @@
1
+ [workspace]
2
+ members = ["python"]
3
+
4
+ [package]
5
+ name = "skaters"
6
+ version = "0.17.0"
7
+ edition = "2021"
8
+ # MSRV. Conservative: the deps (pyo3 0.22 -> 1.63, serde_json 1 -> 1.56, edition
9
+ # 2021 -> 1.56) all admit older toolchains, but only stable 1.96 is available in
10
+ # this environment to verify against, so we pin the lowest value we are
11
+ # confident compiles rather than the newest.
12
+ rust-version = "1.74"
13
+ description = "Rust port of the skaters online distributional forecasting core, parity-gated against the Python reference."
14
+ license = "MIT"
15
+ repository = "https://github.com/microprediction/skaters"
16
+ homepage = "https://skaters.microprediction.org"
17
+ documentation = "https://docs.rs/skaters"
18
+ readme = "README.md"
19
+ keywords = ["forecasting", "time-series", "probabilistic", "online", "quantile"]
20
+ categories = ["science", "mathematics"]
21
+
22
+ [dependencies]
23
+ serde = { version = "1", features = ["derive"] }
24
+ serde_json = { version = "1", features = ["float_roundtrip"] }
25
+ libm = "0.2"
26
+
27
+ [[bin]]
28
+ name = "bench"
29
+ path = "src/bin/bench.rs"
30
+
31
+ [profile.release]
32
+ debug = false
@@ -0,0 +1,54 @@
1
+ Metadata-Version: 2.4
2
+ Name: skaters-fast
3
+ Version: 0.17.0
4
+ Classifier: Programming Language :: Rust
5
+ Classifier: Programming Language :: Python :: 3
6
+ Summary: Opt-in accelerated backend for skaters: a PyO3 skin over the parity-gated Rust core.
7
+ Keywords: time series,forecasting,online,distributional,rust,pyo3
8
+ Author-email: Peter Cotton <peter.cotton@microprediction.com>
9
+ License: MIT
10
+ Requires-Python: >=3.9
11
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
12
+ Project-URL: Homepage, https://skaters.microprediction.org/
13
+ Project-URL: Source, https://github.com/microprediction/skaters
14
+
15
+ # skaters-fast
16
+
17
+ An opt-in accelerated backend for [skaters](https://github.com/microprediction/skaters):
18
+ a thin [PyO3](https://pyo3.rs) skin over the parity-gated Rust core
19
+ (`skaters`).
20
+
21
+ The pure Python package is the reference implementation. This backend runs the
22
+ identical model faster.
23
+
24
+ ```python
25
+ import skaters_fast
26
+
27
+ f = skaters_fast.laplace(1)
28
+ for y in stream:
29
+ dists = f.step(y)
30
+ d = dists[0]
31
+ print(d.mean, d.std, d.logpdf(y))
32
+ print(f.pit, f.z) # parade calibration state after the step
33
+
34
+ s = f.state_json() # checkpoint
35
+ g = skaters_fast.from_state_json(s, 1) # bit-exact resume
36
+ ```
37
+
38
+ ## Guarantees
39
+
40
+ - Cross-backend agreement is 1e-6. The same series through pure Python and
41
+ through skaters-fast agrees to that tolerance.
42
+ - Within-backend resume is bit-exact. `state_json()` round-trips through
43
+ `from_state_json()` with no drift.
44
+ - Do not switch backends mid-stream. Resume a saved state into the same backend
45
+ that wrote it.
46
+
47
+ ## Build
48
+
49
+ ```bash
50
+ maturin develop --release -m rust/python/Cargo.toml
51
+ ```
52
+
53
+ abi3 (`abi3-py39`) means one wheel per platform serves CPython >= 3.9.
54
+
@@ -0,0 +1,67 @@
1
+ # Porting map: Python skaters -> Rust
2
+
3
+ Python is the authority (`src/skaters/` in microprediction/skaters). The gate
4
+ is `cargo test --release` against `parity/vectors.json` at 1e-6.
5
+
6
+ | module | Python source | status |
7
+ |---|---|---|
8
+ | mathx (fsum, gaussian helpers) | dist.py internals | DONE |
9
+ | dist (mixture type, ulp-tolerant prune) | dist.py | DONE |
10
+ | runstats (Welford) | runstats.py | DONE |
11
+ | leaf, scale_mixture_leaf, crps_leaf, garch_leaf | leaf.py | DONE |
12
+ | transforms (diff, frac, standardize, ema, ou, theta, drift, holt, garch, seasonal, power, yeo-johnson, ar, grouped_ar) | transform.py | DONE |
13
+ | conjugate | conjugate.py | DONE |
14
+ | ema skater | ema.py | DONE |
15
+ | precision-weighted ensemble | ensemble.py | DONE |
16
+ | bayesian ensemble | bayesian.py | DONE |
17
+ | multiscale | multiscale.py | DONE |
18
+ | sticky (lattice projection) | sticky.py | DONE |
19
+ | terminal-leaf ensemble | terminal.py | DONE |
20
+ | tails (Acklam phi_inv, censored-ML GPD, SplicedDist, gpdtails) | tails.py | DONE |
21
+ | parade (PIT/z state, finite-input gate) | parade.py | DONE |
22
+ | laplace composition, candidate population | api.py | DONE |
23
+ | adaptive search (dantzig) | search.py | DONE |
24
+ | spec build path | spec.py | DONE |
25
+ | periodicity detector | periodicity.py | DONE |
26
+ | covariance estimators | cov/ | DONE |
27
+
28
+ Porting notes specific to Rust:
29
+
30
+ Python creates skater state lazily on the first call, and several transforms
31
+ treat that first call specially (return 0.0, seed the level or anchor). Each
32
+ transform struct carries an `init` flag reproducing exactly that branch.
33
+ Structs whose lazy init is indistinguishable from default construction
34
+ (leaves, AR) are seeded at construction.
35
+
36
+ Python's built-in `sum()` on floats is Neumaier-compensated since 3.12. Every
37
+ site the reference spells as `sum(...)` uses `mathx::fsum`; every site
38
+ spelled as a `+=` loop stays a naive loop. Mixing these up passes most
39
+ probes and then diverges the prune tie-breaks.
40
+
41
+ The sticky wrapper's frequency table is a Python dict keyed by exact float
42
+ values, so insertion order is semantic (stable sort ties). It is a
43
+ `Vec<(f64, f64)>` here, updated in dict order: decay all, drop below the
44
+ floor, then bump or append the current value.
45
+
46
+ Python float `**` maps to `libm::pow`; integer exponents in the reference
47
+ (OU's `phi ** h`) still go through pow to match. Constants that Python
48
+ computes with `round()` at import time (the crps_leaf FINE scale grid) are
49
+ embedded as literals verified against CPython.
50
+
51
+ Multiscale keeps one sub-skater instance per phase per scale (Python keeps
52
+ one closure and swaps state dicts; same arithmetic, different plumbing).
53
+
54
+ The adaptive search stores each pool candidate as a live `Sk` value next to
55
+ its transform-name recipe, so the whole state stays plain serde data (the
56
+ same finding the R port reached). Tie-breaking mirrors Python exactly:
57
+ expansion order is the `(score, index)` tuple sort with `reverse=True`
58
+ (score descending, then pool index descending), the pool-cap prune removes
59
+ the first argmin, and the logpdf loss is clamped to [-20, 20] with the lower
60
+ clamp catching NaN. A detected seasonal period injects a second grammar
61
+ entry that can shadow a base `seas(p)` by name; recipe rebuilds resolve
62
+ names last-wins, as Python's dict comprehension does. The infinite default
63
+ cost budget round-trips JSON as null.
64
+
65
+ Parity vectors provenance: `parity/vectors.json` is copied from
66
+ microprediction/skaters (`parity/vectors.json` there); refresh by rerunning
67
+ `parity/gen_vectors.py` in that repository and copying the output here.
@@ -0,0 +1,85 @@
1
+ # skaters
2
+
3
+ Rust port of the [skaters](https://github.com/microprediction/skaters) online
4
+ distributional forecasting core. Every forecaster is a struct with
5
+ `step(&mut self, y: f64) -> Vec<Dist>`, and all state is plain
6
+ serde-serializable data. That is a product contract: a skater can be
7
+ checkpointed to JSON and restored.
8
+
9
+ ## Parity discipline
10
+
11
+ No module ships without passing the parity vectors. `parity/vectors.json` is
12
+ generated by the Python reference and embeds the input series, so both sides
13
+ run on identical floats. The gate replays every implemented scenario and
14
+ compares seven probes per step and horizon (mean, std, logpdf at 0.3, cdf at
15
+ 0.3, quantiles 0.1 and 0.9, CRPS at 0.3) at atol = rtol = 1e-6:
16
+
17
+ ```
18
+ cargo test --release
19
+ # parity: 59 scenarios, 105658 values checked
20
+ ```
21
+
22
+ Coverage is the full library: every transform and leaf at k=1 and k=3, the
23
+ ensembles (precision-weighted, bayesian, terminal-leaf), multiscale, sticky
24
+ (on the repeat-heavy series), the GPD tail splice, the full `laplace`
25
+ composition (`pol_laplace`, `pol_laplace_k3`), the adaptive search
26
+ (`search_default`), the spec build path (`spec_diff_ensemble`, `spec_ema`),
27
+ the periodicity detector (ranked lag/acf block), and the covariance
28
+ estimators (running, EMA, Ledoit-Wolf blocks). Nothing is skipped.
29
+
30
+ Two details matter for agreement beyond ordinary care with operation order.
31
+ Sums that Python computes with the built-in `sum()` use a Neumaier-compensated
32
+ `fsum` (CPython 3.12+ compensates float sums; naive accumulation diverges the
33
+ prune tie-breaks). And `Dist::prune` reproduces the ulp-tolerant closest-pair
34
+ merge exactly, which exists precisely to keep platforms in agreement.
35
+
36
+ ## Portable math
37
+
38
+ All transcendentals (exp, log, log1p, expm1, pow, erf, erfc) route through the
39
+ pure-Rust `libm` crate, never the system libm. Portable math means identical
40
+ bits on every platform including wasm32. Parity versus Python remains the
41
+ 1e-6 vector gate above; within a platform family the Rust core itself is
42
+ bit-deterministic.
43
+
44
+ ## Usage
45
+
46
+ ```rust
47
+ use skaters::laplace;
48
+
49
+ let mut f = laplace(1);
50
+ for y in observations {
51
+ let dists = f.step(y);
52
+ println!("{} {}", dists[0].mean(), dists[0].std());
53
+ }
54
+ ```
55
+
56
+ `laplace(k)` is the general forecaster: a likelihood-weighted ensemble over
57
+ the full candidate population with a CRPS terminal leaf, the lattice
58
+ projection for repeating values, GPD tail splicing, and PIT/z calibration
59
+ state (`Parade::pit`, `Parade::z`). At k > 1 it runs multi-scale over
60
+ decimated clocks. Building blocks (`conjugate`, transforms, leaves,
61
+ ensembles) are exported for composition.
62
+
63
+ ## Python backend (skaters-fast)
64
+
65
+ `rust/python/` is `skaters-fast`, an opt-in PyO3 skin that lets Python run the
66
+ identical `laplace` model at about 20x the per-step rate of the pure Python
67
+ reference with the same bits on every platform. Build it into a venv with
68
+ `maturin develop --release -m rust/python/Cargo.toml`. See
69
+ [rust/python/README.md](python/README.md).
70
+
71
+ ## Benchmark
72
+
73
+ `cargo run --release --bin bench` times `laplace(1)` over 5000 ticks (the
74
+ parity series, tiled). On an Apple M-series laptop:
75
+
76
+ ```
77
+ laplace(1) step: 14.1 us/tick
78
+ laplace(1) step + mean: 300.5 us/tick
79
+ ```
80
+
81
+ The second line adds one `mean()` read per tick. After the tail splice
82
+ activates (tick 500) that read evaluates a 65-node numeric quantile grid on
83
+ the spliced predictive, which is why probing moments costs far more than
84
+ stepping. Cheap queries (cdf, logpdf, a single quantile) do not pay that
85
+ cost.
@@ -0,0 +1,21 @@
1
+ //! Time per update: laplace(1) against granger (monthly parameters), warm.
2
+ use skaters::{laplace, Granger};
3
+ use std::time::Instant;
4
+
5
+ fn main() {
6
+ let mut s: u64 = 7;
7
+ let mut rnd = move || {
8
+ s ^= s << 13; s ^= s >> 7; s ^= s << 17;
9
+ (s as f64 / u64::MAX as f64) - 0.5
10
+ };
11
+ let ys: Vec<f64> = (0..3000).map(|_| rnd() + rnd() + rnd()).collect();
12
+ let mut f = laplace(1);
13
+ let t = Instant::now();
14
+ for y in &ys { f.step(*y); }
15
+ let lap = t.elapsed().as_secs_f64() / ys.len() as f64 * 1e6;
16
+ let mut g = Granger::shipped("monthly").unwrap();
17
+ let t = Instant::now();
18
+ for y in &ys { g.step(*y); }
19
+ let gr = t.elapsed().as_secs_f64() / ys.len() as f64 * 1e6;
20
+ println!("laplace {lap:.1} us/update, granger {gr:.1} us/update, ratio {:.2}", gr / lap);
21
+ }