ppsds: probabilistic prediction for stochastic dynamical systems

How probabilistically predictable is a system you only partly know? ppsds answers from both sides: the ceiling any probabilistic prediction could reach on a system you know exactly, and a probabilistic predictor that comes with a floor over every system you are willing to admit.

If that sounds abstract, that is expected. The paragraph above is written for readers who already know what a stochastic dynamical system is and what probabilistic prediction means. Many people have never met either term, and some may already be working with such a system without knowing it. You cannot miss a capability you have never had a name for. The one-minute game below replaces the vocabulary with something you can play: place a few bets, watch the system move, and see what a probabilistic prediction is before reading a definition of it.

Install

pip install ppsds

0.0.3-alpha is a pre-release: pin it with pip install ppsds==0.0.3a0, or pass --pre. Plain pip install ppsds selects it while no stable version exists; once 0.1.0 is out, plain install selects the stable release.

Core dependencies are numpy, scipy, cvxpy and gymnasium; Python 3.10 or newer. Only the experiment and plotting periphery needs more:

pip install "ppsds[experiments]"     # adds matplotlib, pandas, seaborn, tqdm

Each example and experiment directory also carries its own environment.yml if you would rather create a conda environment for exactly one page.

Get started

Rows are how far you want to go. Columns are what you start from, ordered from nothing to data without a model.

From →	A · Just curious Nothing yet.	B · Build it yourself No environment.	C · Your system You can step it.	D · Data only No model or env.
L0 · See	Just curious: see what a probabilistic prediction is in one minute.	—	—	—
L1 · Use	—	Reproduce a paper: build the system from the paper and check its figures.	Use it on your system: put a predictor on a Gymnasium environment you already have.	Only data: you need a system you can step; read the limits first.
L2 · Extend	—	Add a predictor kind: try a different prediction law in a simulation you build.	Add a family: teach the library the uncertainty language your system needs.	—
L3 · Research	—	Work on the ceiling: scoring rules, predictability, and what no predictor can beat.	Do research on the floor: change the assumptions, not just the implementation.	—
L4 · Contribute	Found a problem while playing: open an issue; the game is a real user of the library.	Contribute what you built: file an L1 issue, or send an L2/L3 result (including a benchmark) as a pull request.	Contribute what you built: file an L1 issue, or send your L2/L3 results as a pull request.	Discuss a research collaboration: this column is future research; L0–L3 are blank here.

Recommended routes

The table above sells one story at a time. These are the routes — paths that cross the site's four sections, for a reader who knows what they are trying to get done.

Need the panorama? The map below shows every route at a glance; the map page explains what each one means and how the sections connect.

1 · Play first. The game needs nothing installed. Thirty seconds on the table, and you know what a probabilistic prediction is.

2 · Measure the game properly. The game → the betting experiment → Preliminaries. The same move over thousands of trajectories, against the ceiling.

3 · The 10-minute evaluation. The apply quickstart → the honest limits. Run one script, read what the guarantee does not cover, and decide whether to try it.

4 · Deploy on your own system. Apply DRPP → Getting Started → Troubleshooting. The four-step declaration, the pitfalls, and the two ways it surprises you.

5 · Check or reproduce the conic DRPP paper. The paper → the simulated-ambiguity example → the DRPP experiment → A new family and its DRPP.

6 · Check or reproduce the probabilistic predictability paper. The paper → the ceiling example → the predictability experiment.

7 · Do research, or add a family. Preliminaries → either paper → A new family and its DRPP → CONTRIBUTING.

Sections on this site

Citation and licence

If you use ppsds, cite the software:

@software{ppsds,
  title   = {ppsds: probabilistic prediction for stochastic dynamical systems},
  author  = {Xu, Tao and He, Jianping},
  license = {MIT},
  url     = {https://github.com/Xuzerken/ppsds}
}

GitHub's Cite this repository button reads CITATION.cff and produces the same entry; an archived release with a DOI will be added once the first stable release is archived. Each paper's citation is at the end of its page: conic DRPP paper and probabilistic predictability paper.

ppsds is MIT licensed: use it freely, keep the copyright and licence notice. If you want to contribute, CONTRIBUTING has the setup, the tests, and the rule that a change must not move a number.

Next

• Thirty seconds, no install: play the betting game
• You have an environment: Getting Started puts a predictor on it
• You want the theory: Research, then the two papers
• You want the graph: the map