stochpylib

Probability · Distributions · Monte Carlo — one coherent Python library.
A growing, from-scratch toolkit of stochastic computing: native implementations behind one common interface, engineered to eventually replace stitching together scipy.stats, statsmodels, pymc, arch, lifelines and copulas.

---

---

stochpylib is not a wrapper around existing statistical libraries — every distribution and algorithm is implemented from scratch, with scipy.special/optimize/integrate used only as raw numerical building blocks and scipy.stats serving as the independent test oracle. At its core is a single load-bearing contract: every distribution exposes the same method set (.pdf()/.cdf()/.ppf()/.rvs()/.mean()/.var()/.skewness()/.kurtosis()/.entropy()/.mgf()/.cf()/.fit()/.ks_test()), every stochastic method takes a random_state= seed, and every Monte Carlo estimator returns a shared result object carrying its point estimate together with an honest standard error and confidence interval. Around that contract, three modules are live today: a probability engine (sample spaces, Bayes' theorem, exact-integer combinatorics, independence testing), 47 distributions across discrete/continuous/multivariate/heavy-tailed families — including stable laws with Chambers–Mallows–Leckie sampling and numerically inverted characteristic functions — and a Monte Carlo suite spanning quasi-random sequences (Sobol, Halton, Faure, Niederreiter), variance-reduction techniques (antithetic, control variates, Latin hypercube, conditioned MC, rejection control), and applications from option pricing validated against Black–Scholes to reliability analysis driven by the library's own distribution objects. The thesis this project exists to test: a complete stochastic-computing stack can live in one coherent, well-tested package — the roadmap takes it onward through time series, Gaussian processes, copulas, Lévy processes, MCMC and beyond (23 modules, ~794 public names planned).

Table of Contents

• Quickstart
• Current Status
• Download
• Getting Started
• Requirements
• CLI Reference
• Project Layout
• Development Documentation
• Test Suite
• Release Process
• Roadmap
• Contributing
• License

Quickstart

from stochpylib.probability import bayes_theorem, total_probability

# Classic disease-screening example: 1% prevalence, 99% sensitivity, 5% false-positive rate.
p_positive = total_probability((0.99, 0.01), (0.05, 0.99))
p_disease_given_positive = bayes_theorem(0.01, 0.99, p_positive)
print(round(p_disease_given_positive, 4))  # 0.1667

from stochpylib.distributions import Normal, Weibull
from stochpylib.montecarlo import SobolSequence, AntitheticVariates

d = Normal(0.0, 1.0)
d.pdf(0.0); d.cdf(1.96); d.ppf(0.975); d.rvs(100, random_state=0)

fitted = Weibull.fit(lifetimes)          # maximum likelihood from data
stat, p_value = fitted.ks_test(data)     # goodness of fit

pts = SobolSequence(dim=5).generate(10_000)                    # low-discrepancy points
price = AntitheticVariates(n_simulations=100_000).price_european_call(
    S=100, K=100, T=1, r=0.05, sigma=0.2)                      # option pricing

Current Status

Early development — three modules implemented so far:

Module	Public names	What's inside
stochpylib.probability	21	sample spaces, events, conditional probability, Bayes' theorem, combinatorics (factorial … derangements, Stirling, Bell, Catalan), independence checks
stochpylib.distributions	60	47 distributions (discrete, continuous, multivariate, heavy-tailed) behind the common interface
stochpylib.montecarlo	25	quasi-random sequences, crude/QMC/importance/rejection/stratified estimators, variance reduction, applications

Exact progress against the full design spec lives in development/Implementation-Checklist.md (currently 106 / 794 public names).

Download

If you just want to use stochpylib rather than develop on it, no source checkout is needed:

pip install stochpylib
spl --help        # overview of everything the library offers

The PyPI release lands with the first tagged version (v0.1.0); until then the badge above will show "not found". For local development from this repository, pip install -e . registers the same spl command straight from source instead:

git clone https://github.com/leon1706-lol/Stochpylib.git
cd Stochpylib
pip install -e .

Getting Started

For local development (this repo cloned, a virtual environment active):

pip install -e ".[dev]"     # runtime deps + pytest
pytest tests/ -v            # full test suite must be green before you start changing things
spl --version               # verify your editable install
spl --test                  # embedded self-check (106 checks), no pytest needed

Then implement or improve one module at a time and run the wrap-up procedure described in CONTRIBUTING.md.

Requirements

• Python ≥ 3.10
• NumPy and SciPy (the only runtime dependencies)
• pytest for the development extras (pip install -e ".[dev]")
• No compilers, no GPU, no other system packages — pure Python/NumPy/SciPy by design

CLI Reference

Every install (PyPI wheel or pip install -e .) registers one console command, spl:

spl --help

Prints a full inventory of the installed library: which modules are available, all public functions per module, every distribution class (generated dynamically from the package, so it never goes stale), the common distribution interface, and a runnable quick-start snippet. Running bare spl shows the same thing.

spl --version

$ spl --version
0.1.0

Prints the installed version — reads pip package metadata, falling back to the in-code version when not installed through pip.

spl --test

Runs the embedded self-check suite shipped inside the wheel (106 checks): package sanity, one closed-form spot check per distribution family, Monte Carlo convergence sanity. This works after any pip install — no pytest, no source checkout — making it the quickest way to verify an installation. Exits non-zero on any failure.

Project Layout

• stochpylib/ — the installable package, one subpackage per module (probability/, distributions/, montecarlo/), plus cli.py and selftest.py
• tests/ — one tests/<module>/tests.py per module, outside the package
• development/ — build history & process docs (see below)
• .github/workflows/ — CI matrix (Python 3.10–3.13), tag-triggered PyPI publishing (Trusted Publisher/OIDC, no stored tokens), automatic GitHub Releases
• The full design-spec vault (Stochpylib-Obsidian-Vault/) is maintained privately and is not part of this repository

Development Documentation

Everything a contributor or maintainer needs lives in committed docs:

• CONTRIBUTING.md — dev setup, ground rules, semver & deprecation policy, PR checklist
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1
• SECURITY.md — private vulnerability reporting (72 h acknowledgment)
• development/Development.md — layout decisions & workflow notes
• development/CHANGELOG.md — append-only log, one entry per build phase
• development/Probleme.md — bug audit log with severity scores (11 entries so far)
• development/Implementation-Checklist.md — every planned public name as a checkbox

Test Suite

pytest tests/ -v

182 passed / 2 skipped as of the montecarlo module. Tests are deterministic (fixed seeds everywhere), live outside the installed package, and use scipy.stats as the reference oracle. Statistical assertions are set at ≥ 3 standard errors so results are stable while staying meaningful. Additionally, spl --test re-verifies any installation in seconds.

Release Process

Releases are fully automated from tags:

1. Update the version in pyproject.toml and stochpylib/__init__.py (semver — see the policy in CONTRIBUTING.md)
2. Tag and push:

   git tag v0.1.0 && git push origin v0.1.0
   

3. CI runs the full test matrix, builds sdist + wheel, smoke-verifies the wheel (spl --version, spl --test) and publishes to PyPI via Trusted Publisher (OIDC — no API tokens stored anywhere); a second workflow creates the matching GitHub Release with auto-generated changelog notes

Prerequisite for step 3: configure the Trusted Publisher once under pypi.org → your project → Publishing.

Roadmap

Twenty modules remain on the spec (in rough implementation order): time series, Gaussian processes, copulas, survival analysis, queueing theory, information theory, Lévy processes, financial stochastics, advanced MCMC, Bayesian inference, statistics, nonparametric methods, robust statistics, numerical methods, random matrix theory, spatial statistics, optimization, experimental design, visualization, and utilities. Each lands with the same bar: native implementations, the shared interface conventions, full tests against independent oracles, and honest documentation of deviations.

Contributing

Issues and PRs welcome! Start with CONTRIBUTING.md — it covers the ground rules (no scipy.stats wrapping in library code, the common interface contract, where tests live) and the versioning/deprecation policy. Bug reports go through the issue templates; security issues privately per SECURITY.md. This project follows CODE_OF_CONDUCT.md.

License

MIT © Leon Schwarzkopf

---

Built by Leon Schwarzkopf, leonschwarzkopf08@gmail.com

---