pretium

A market simulator you can run a strategy against. Rust core, Python API.

Give it a seed and a list of companies. It runs a market forward: prices, a limit order book, fills, and an economy that moves each day. Your orders match against real depth, so your trades move the price.

Real market data cannot tell you what happens if you trade differently, or what caused a move. This can, because it computed every price.

Install

pip install pretium

Wheels for Linux, macOS and Windows on CPython 3.11+. No dependencies. The same engine is a Rust crate: cargo add pretium.

The API can still change before 1.0. A published result cannot: new coefficients ship as a new preset, so a run you cited last month replays this month.

First run

import pretium as pt

universe = pt.Universe.random(40, seed=111)

spec = pt.StrategySpec.momentum(lookback_days=1.0, top_k=5)
scores = pt.evaluate({"mine": spec}, seed=7, universe=universe, days=10)

scores["mine"].return_pct            # what it made
scores["mine"].impact_bps            # what its own footprint cost
scores["mine"].strategy_fingerprint  # sha256, cite this

That is one market draw. It tells you as much about the seed as about the strategy. pt.rank runs many seeds and compares them with a paired sign test.

What you get

No historical dataset carries the labels truth() gives you. Real data shows you that a stock fell. It never shows you that 60% of the fall was order flow.

To drive it from an agent:

pip install "pretium[mcp]"
claude mcp add pretium -- pretium-mcp

Strategies, universes and scenarios are data, so a tool argument cannot reach code. Each result carries its own caveats. See the MCP page.

How real it is

pt.facts.measure() scores fourteen statistics against real-market bands. The default preset, pt-v14, holds all fourteen at one year and at two years. It holds all fourteen on a roster it never saw, and thirteen on new seeds.

Five of the fourteen were calibration targets, and the bands both tuned the model and graded it. So this is a stated envelope, not a test against market data that was held back.

Five limits are measured and written down:

pt.envelope.check() refuses a question that falls outside a limit, and the realism envelope says what each one forbids.

Good results here do not predict real returns. The prices come from a known model, so a strategy shaped like that model looks excellent and teaches you nothing. A strategy that fails here tells you more. There is one venue, no latency, and no counterparty that adapts to you.

Same seed, same market

Each release builds five targets, runs one fixed simulation in each, and compares digests. A disagreement stops the release. The crate ships its own exp, log, sin and cos, so the platform libm cannot change a result.

pt-v14 became the default on 2026-08-28. Name your preset and your run replays exactly. Every preset from pt-v1 on is still selectable.

eng = pt.Engine(seed=42, universe=u, model="pt-v10")

Examples

Ten examples/ in reading order, run by the test suite:

More

Full docs: simoncoombes.github.io/pretium.

To contribute, see CONTRIBUTING.md and RELEASING.md. One rule shapes the rest: a change to the simulated trajectory is a breaking change, whatever its size.

To cite the software, see CITATION.cff. To cite a result, use its RunManifest.

Licence: MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.