NextStat

NextStat is a statistical inference engine built in Rust with bindings for Python, R, CLI, WASM, and a self-hosted server. It lets you run HistFactory fits, hypothesis tests, upper limits, and measurement combinations against the same pyhf JSON workspaces you already use — but orders of magnitude faster, with deterministic results, and without a C++ ROOT dependency.

Beyond HEP, NextStat covers pharmacometrics (FOCE, SAEM, VPC, ICH M15), Bayesian sampling (NUTS), GLMs, survival analysis, econometrics, and time series — all from one engine, one install, one validation stack.

What makes it different: every public surface ships with a parity contract against a reference implementation, a support matrix documenting what is covered, and a CI gate that blocks the release if the contract breaks. The result is an engine you can audit before you trust — not a library where correctness is assumed from reputation.

The engine runs on two paths:

• a deterministic reference path for parity, validation, and release gates
• an optimized production path using SIMD, parallelism, and optional GPU acceleration (CUDA, Metal)

Why Trust It

The key principle is simple:

validation, not provenance

The repository is large because it includes the quality system required to make stable-surface claims: tests, parity contracts, support matrices, benchmark evidence, validation bundles, schemas, examples, release manifests, and release artifacts.

Current trust anchors:

Signal	Current State	Canonical Reference
HEP stable surface	141/141 stable, 0 research	docs/references/hep-stable-surface.md
Required release surfaces	6 required-for-release stable surfaces	docs/references/validation-and-release-discipline.md
HEP governance bundle	machine-checked HEP matrix + validation bundle	docs/references/hep-stable-surface.md
Pharma qualification	NS-VAL-001 v2.0.0, Appendix B traceability matrix, public IQ/OQ/PQ protocol	docs/validation/iq-oq-pq-protocol.md
Release discipline	prerelease gate, release manifest, full-fidelity local release simulation	docs/releases/release-runbook.md
Benchmark governance	committed evidence policy + promotion rules	docs/releases/benchmark-artifact-policy.md

Concrete public evidence in the repo:

• HEP: 141 stable surfaces across 9 slices (HistFactory 48, GVM 47, Infrastructure 12, Unbinned 11, Viz 11, Import/Export 6, Simplified Likelihood 2, HEPData 2, Preprocess 2)
• Pharma: 21 IQ, 79 OQ, 25 PQ qualification IDs in the controlled protocol with bit-for-bit reproducibility checks across FOCE, SAEM, and simulation paths
• Deterministic guarantees: pyhf NumPy f64 is the canonical oracle for HistFactory parity; stable surfaces promise deterministic CPU parity and bit-reproducible results on the same input

If you want the engineering model behind the repository, start here:

• Validation and Release Discipline

Status and Maturity

NextStat is production-ready for the documented stable surfaces and release gates linked from this README. Today that means:

• HEP stable surface: 141/141 stable, 0 research
• 6 required-for-release surfaces blocked by machine-checked CI gates
• regulated pharma validation exposed through the public IQ/OQ/PQ protocol and validation-pack references

The maturity rule is explicit: if a surface has a support matrix, acceptance contract, runtime gate, and release evidence, it is stable. If those contracts are not published for a given path, do not treat the presence of code alone as the maturity signal.

What You Can Do

HEP

• fit, scan, rank, hypotest, significance, and upper limits on HistFactory / pyhf JSON workspaces
• import HEPData and materialize deterministic local workspaces
• run stable scalar measurement combinations (GVM) plus advanced scenario and calibration studies
• derive and export simplified-likelihood reduced models with explicit stable/research boundaries
• build ntuple-to-workspace pipelines without a ROOT C++ dependency
• build and evaluate unbinned likelihood workflows
• generate deterministic report and validation artifacts

Pharmacometrics and regulated reporting

• run PK/NLME workflows (FOCE, SAEM, VPC, GOF, SCM, MAP, simulation)
• produce deterministic validation-pack and report artifacts
• generate ICH M15 JSON bundle surfaces on top of the validation stack
• reuse machine-readable provenance and schema-checked output contracts

Econometrics and causal inference

• run panel fixed effects, DiD (TWFE + staggered), event study, IV/2SLS, and AIPW
• named competitor baselines: statsmodels, linearmodels, pyfixest
• published benchmark page with explicit estimator boundary documentation
• AIPW remains available, but without an external parity baseline it is not part of the current competitor-backed SOTA subset.

Bayesian sampling

• sample posteriors with NUTS, WALNUTS, and MAMS on the governed public CPU surface
• published CmdStan-backed NUTS ESS/sec and repeatability evidence on canonical benchmark models
• explicit sampler references, health thresholds, and reproducible benchmark methodology

Time series and state-space

• Kalman local-level filtering, smoothing, and EM against pykalman/statsmodels
• GARCH(1,1) estimation against arch
• committed public snapshot with 4/4 ok, 0 warn, 0 failed competitor-backed cases

General statistics and adjacent domains

• fit GLMs and hierarchical models
• fit survival models

Survival and other adjacent analytical surfaces do not yet carry published support matrices or release gates.

GPU acceleration is a documented source-build public path for the narrow shipped CUDA WALNUTS subset and the published GPU parity contract. It is not part of the default wheel contract.

R bindings are a stable source-build public interface for the documented asymptotic HistFactory, GLM, PK/NLME, and time-series surface. GPU, neural PDFs, and the broader Python-first surface remain out of scope for R.

WASM is a stable source-build public interface for the browser playground and its documented HistFactory/GLM subset. It is not the full native product surface.

Quickstart

Install (Python)

pip install nextstat
nextstat version

pip install "nextstat[bayes]"   # ArviZ / Bayesian helpers
pip install "nextstat[viz]"     # plotting extras
pip install "nextstat[all]"     # everything

Install (R, source build)

mkdir -p tmp/r-lib
R CMD INSTALL --library=tmp/r-lib bindings/ns-r

More:

• R Bindings Reference

Build the WASM playground (source build)

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.108

make playground-build-wasm
make playground-serve

More:

• WASM Playground Reference

Try HistFactory in 30 seconds

nextstat fit --input playground/examples/simple_workspace.json
nextstat upper-limit --input playground/examples/simple_workspace.json --expected

Or from Python:

import nextstat, json

workspace = json.load(open("playground/examples/simple_workspace.json"))
model = nextstat.HistFactoryModel.from_workspace(json.dumps(workspace))
result = nextstat.fit(model)

print(result.parameters)   # MLE parameter values
print(result.twice_nll)     # 2 * NLL (pyhf convention)
print(result.converged)     # True

More:

• CLI Reference
• Python API
• R Bindings Reference
• WASM Playground Reference
• HistFactory stable support matrix

Stable-first GVM in 5 minutes

nextstat combine-measurements-build-spec \
  --manifest docs/examples/gvm-stable-first/manifest.yaml \
  --output /tmp/gvm-spec.json

nextstat combine-measurements \
  --input /tmp/gvm-spec.json \
  --output /tmp/gvm-result.json \
  --solver auto \
  --threads 1

Continue with:

• nextstat combine-measurements-calibrate
• nextstat combine-measurements-calibrate-study
• make gvm-stable-first-example

Walkthrough:

• HEP GVM stable-first quickstart
• HEP GVM measurement-combination tutorial

HEPData import

nextstat import hepdata --list
nextstat import hepdata \
  --dataset hepdata.116034.v1.r34 \
  --out-dir /tmp/hepdata-workspaces

References:

• HEPData Import support matrix
• HEPData Import runtime gate

Validation pack

make validation-pack

Key references:

• Validation report reference
• IQ/OQ/PQ validation protocol
• 21 CFR Part 11 compliance documentation

Documentation Map

Area	References
Start here	Docs index · Validation and release discipline · Tutorials · Benchmarks hub
API surfaces	CLI · Python · Rust · R · Tool · Server
Trust & releases	HEP stable surface · M15 reporting · Validation report · Benchmark policy · Release runbook
Tutorials & demos	Frequentist HEP · ROOT/TRExFitter parity · Physics assistant

Representative Benchmark Snapshot

This repository keeps benchmark evidence in governed form rather than as marketing-only claims. One representative example:

Toy-based CLs “God Run”

• Model: synthetic S+B HistFactory
• Shape: 50 channels × 4 bins, 201 parameters
• Load: 10,000 b-only toys + 10,000 s+b toys
• Machine: Apple M5
• Recorded: 2026-02-07
• Snapshot commit: 88d57856

Tool	Wall Time	Speedup
NextStat (Rayon)	3.47 s	1.0×
pyhf (multiprocessing, 10 procs)	50m 11.7s	868.0×

Reproduce:

PYTHONPATH=bindings/ns-py/python python \
  scripts/god_run_benchmark.py \
  --n-toys 10000

For governed benchmark evidence and promotion rules, see:

• Benchmarks hub
• Benchmark artifact policy

Architecture

NextStat follows a layered architecture: inference logic depends on stable interfaces, while translation, compute backends, and I/O stay modular.

High-level logic
  ns-inference  ns-viz  ns-server  ns-cli
        |
        v
Core abstractions
  ns-core  ns-prob  ns-ad
        |
        v
Implementations and ingress
  ns-compute  ns-translate  ns-root  ns-unbinned

Key crates:

• ns-core — shared types and interfaces
• ns-compute — SIMD / Accelerate / CUDA / Metal kernels
• ns-translate — pyhf, HS3, HistFactory XML, ntuple/workspace translation
• ns-root — native ROOT I/O
• ns-unbinned — event-level likelihood components
• ns-inference — fits, scans, hypotests, NUTS, GLM, time series, PK/NLME
• ns-viz — plotting artifacts
• ns-server — self-hosted inference API
• ns-cli — command-line surface

Bindings:

• bindings/ns-py
• bindings/ns-r
• bindings/ns-wasm

For the deeper rationale, see:

• White paper

Development

Requirements

• Rust 1.93+
• Python 3.11+
• maturin
• optional: R 4.1+, CUDA toolkit, Apple Metal-capable macOS host

Build and test

# Build
cargo build --workspace

# Rust tests
cargo test --workspace

# Python tests (fast path)
PYTHONPATH=bindings/ns-py/python python -m pytest -q -m "not slow" tests/python

# Format and lint
cargo fmt --check
cargo clippy --workspace -- -D warnings

Prerelease gate

make apex2-pre-release-gate

This is the canonical local prerelease entry point. It validates:

• release surface matrix
• HEP surface matrix
• HEP validation bundle
• release manifest
• full-fidelity local release simulation
• separate governance and performance outcomes with distinct summaries and exit codes

References:

• CONTRIBUTING.md
• Release Runbook

Contributing

See CONTRIBUTING.md.

All commits must include DCO sign-off:

git commit -s

License

NextStat uses a dual-licensing model:

• open source: LICENSE (AGPL-3.0-or-later)
• commercial alternative: LICENSE-COMMERCIAL

Contact

• Website: https://nextstat.io
• GitHub: https://github.com/NextStat/nextstat.io